SDK

Piora provides official SDKs that let you easily integrate the Piora API into your applications without dealing with raw HTTP requests.

Official SDKs

Node.js / TypeScript

npm install @piora/sdk

import { PioraClient } from '@piora/sdk';

const piora = new PioraClient({
  token: process.env.PIORA_API_TOKEN,
});

// List all servers
const servers = await piora.servers.list();

// Get application details
const app = await piora.applications.get('app_xxxxxxxxxxxx');

// Trigger a deployment
const deployment = await piora.applications.deploy('app_xxxxxxxxxxxx', {
  branch: 'main',
});

Python

pip install piora-sdk

from piora import PioraClient

piora = PioraClient(token=os.environ['PIORA_API_TOKEN'])

# List all servers
servers = piora.servers.list()

# Get application details
app = piora.applications.get('app_xxxxxxxxxxxx')

# Trigger a deployment
deployment = piora.applications.deploy('app_xxxxxxxxxxxx', branch='main')

SDK Features

All official SDKs provide the following features:

Feature	Description
Full API coverage	Supports all Piora API endpoints
Type safety	Complete TypeScript type definitions
Auto retry	Automatic retry on transient errors
Pagination helpers	Automatic handling of paginated queries
Error handling	Structured error classes

Usage Examples

Managing Servers

// List all servers
const servers = await piora.servers.list();
for (const server of servers) {
  console.log(`${server.name}: ${server.status}`);
}

// Get server stats
const stats = await piora.servers.stats('srv_xxxxxxxxxxxx');
console.log(`CPU: ${stats.cpu}%, Memory: ${stats.memory}%`);

Managing Applications

// Create an application
const app = await piora.applications.create({
  name: 'my-new-app',
  serverId: 'srv_xxxxxxxxxxxx',
  source: {
    type: 'git',
    repository: 'https://github.com/user/repo',
    branch: 'main',
  },
});

// Set environment variables
await piora.applications.setEnv('app_xxxxxxxxxxxx', {
  NODE_ENV: 'production',
  DATABASE_URL: 'postgresql://...',
});

// Deploy
const deployment = await piora.applications.deploy('app_xxxxxxxxxxxx');

// Wait for deployment to complete
await deployment.waitUntilComplete();
console.log('Deployment successful!');

Managing Databases

// Create a PostgreSQL database
const db = await piora.databases.create({
  type: 'postgresql',
  version: '16',
  name: 'my-database',
  serverId: 'srv_xxxxxxxxxxxx',
});

// Get connection info
const connectionInfo = await piora.databases.connectionInfo(db.id);
console.log(connectionInfo.url);

Handling Webhook Events

import { PioraWebhookHandler } from '@piora/sdk';

const handler = new PioraWebhookHandler({
  secret: process.env.PIORA_WEBHOOK_SECRET,
});

// Express.js integration
app.post('/webhook', handler.express((event) => {
  switch (event.type) {
    case 'deployment.succeeded':
      console.log(`Deploy succeeded: ${event.data.application.name}`);
      break;
    case 'deployment.failed':
      console.log(`Deploy failed: ${event.data.application.name}`);
      // Send alert notification
      break;
  }
}));

Error Handling

SDKs provide structured error classes:

import { PioraError, AuthenticationError, NotFoundError } from '@piora/sdk';

try {
  const app = await piora.applications.get('invalid-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Token is invalid or expired');
  } else if (error instanceof NotFoundError) {
    console.error('Application not found');
  } else if (error instanceof PioraError) {
    console.error(`API error: ${error.code} - ${error.message}`);
  }
}

Pagination

// Manual pagination
const page1 = await piora.applications.list({ page: 1, perPage: 20 });
const page2 = await piora.applications.list({ page: 2, perPage: 20 });

// Auto-iterate through all pages
for await (const app of piora.applications.listAll()) {
  console.log(app.name);
}

Community SDKs

In addition to official SDKs, the community maintains SDKs for other languages:

Language	Package	Maintainer
Go	`piora-go`	Community
Ruby	`piora-ruby`	Community
PHP	`piora/sdk-php`	Community