AStack Developer SDK

Server-side SDK for managing AStack sessions, users, billing, workers, and webhooks.

Installation

npm install @aether-stack-dev/developer-sdk

Quick Start

import { AStackSDK } from '@aether-stack-dev/developer-sdk';

const sdk = new AStackSDK({
  apiKey: process.env.ASTACK_API_KEY,
  apiEndpoint: process.env.ASTACK_API_ENDPOINT,
  jwtSecret: process.env.ASTACK_JWT_SECRET,
});

// Create a session
const { session, token } = await sdk.createSession('user_123');

// Return token + workerUrl to your frontend

Constructor

new AStackSDK(config: AStackConfig)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your AStack API key | | apiEndpoint | string | required | AStack API base URL | | jwtSecret | string | required | Stable secret for JWT signing | | databaseUrl | string | '' | Optional database connection URL | | supabasePublishableKey | string | — | Supabase anon key (for WebSocket features) | | sessionTtl | number | 3600 | Session TTL in seconds | | maxConcurrentSessions | number | 100 | Max concurrent sessions | | enableBilling | boolean | true | Enable billing tracking | | enableAuditLogging | boolean | false | Enable audit logs | | debug | boolean | false | Enable debug logging | | rateLimitConfig | RateLimitConfig | — | Rate limit + retry config | | apiKeyScopes | ApiKeyScope[] | — | Restrict SDK to specific scopes |

Sessions

const { session, token } = await sdk.createSession('user_123', {
  connection_type: 'websocket',
  quality: 'high',
  features: ['vision'],
  metadata: { source: 'web' },
});

const session = await sdk.getSession(session.id);
const sessions = await sdk.listUserSessions('user_123', 50, 0);

await sdk.terminateSession(session.id);

Users

const user = await sdk.createUser({
  id: 'user_123',
  email: '[email protected]',
  name: 'Jane Doe',
  plan: 'growth',
  initial_credits: 1000,
});

const user = await sdk.getUserById('user_123');
await sdk.updateUser('user_123', { plan: 'enterprise' });
await sdk.deleteUser('user_123');

// API keys
const { apiKey, key } = await sdk.createApiKey('user_123', {
  key_name: 'Production',
  permissions: { session_create: true, session_manage: true, usage_read: true },
  rate_limit_per_minute: 60,
  rate_limit_per_hour: 1000,
  expires_at: new Date('2026-12-31'),
});
const keys = await sdk.listApiKeys('user_123');
await sdk.revokeApiKey('user_123', apiKey.id);

Billing

const usage = await sdk.getUserUsage('user_123', {
  start: new Date('2026-01-01'),
  end: new Date('2026-02-01'),
});

const estimate = await sdk.estimateSessionCost({
  quality: 'premium',
  features: ['vision'],
  duration: 300,
});

const billing = await sdk.getBillingInfo('user_123');
const invoice = await sdk.generateInvoice('user_123', {
  start: new Date('2026-01-01'),
  end: new Date('2026-02-01'),
});

const alertId = await sdk.setUsageAlert(
  'user_123', 'credit_threshold', 100,
  (alert) => console.log('Low credits:', alert.message)
);

Workers

const worker = await sdk.getWorkerStatus('worker_id');
const { workers, total } = await sdk.listActiveWorkers({
  region: 'us-east-1',
  status: 'active',
  limit: 10,
});
const metrics = await sdk.getWorkerMetrics('worker_id', {
  start: '2026-01-01T00:00:00Z',
  end: '2026-02-01T00:00:00Z',
});
const capacity = await sdk.getCapacityMetrics();

Webhooks

import { WebhookManager, createWebhookHandler, setupWebhooks }
  from '@aether-stack-dev/developer-sdk';

// Option 1: WebhookManager class
const webhooks = new WebhookManager(sdk, process.env.WEBHOOK_SECRET);
webhooks.setHandlers({
  onSessionStarted: (session) => { /* ... */ },
  onSessionEnded: (session, metrics) => { /* ... */ },
  onSessionError: (session, error) => { /* ... */ },
  onUserCreated: (user) => { /* ... */ },
  onUsageRecorded: (usage) => { /* ... */ },
  onInvoiceCreated: (invoice) => { /* ... */ },
});
app.post('/webhooks/astack', webhooks.middleware());

// Option 2: Helper function
app.post('/webhooks/astack', createWebhookHandler(sdk, webhookSecret, {
  onSessionEnded: (session) => { /* ... */ },
}));

// Option 3: Auto-setup
setupWebhooks(app, sdk, {
  webhookSecret: process.env.WEBHOOK_SECRET,
  endpoint: '/webhooks/astack',
  handlers: { onSessionEnded: (session) => { /* ... */ } },
});

Middleware

Express

import {
  authMiddleware, rateLimitMiddleware, corsMiddleware, errorHandler
} from '@aether-stack-dev/developer-sdk';

app.use('/api', authMiddleware(sdk, {
  apiKeyHeader: 'x-api-key',
  requirePermissions: ['session_create'],
}));

app.use(rateLimitMiddleware({ windowMs: 60_000, max: 100 }));
app.use(corsMiddleware(['https://app.example.com']));
app.use(errorHandler());

Fastify

import { astackFastifyPlugin } from '@aether-stack-dev/developer-sdk';

await fastify.register(astackFastifyPlugin, {
  apiKey: process.env.ASTACK_API_KEY,
  enableAuth: true,
  enableRateLimit: true,
});

Admin

const key = await sdk.createApiKeyWithScopes({
  key_name: 'Read-only Dashboard',
  scopes: ['sessions:read', 'billing:read', 'workers:read'],
});

const { logs, total } = await sdk.getAuditLogs({
  action: 'session.create',
  start_date: '2026-01-01',
  limit: 50,
});

const metrics = await sdk.getPerformanceMetrics({
  aggregation: 'day',
  start_date: '2026-01-01',
});

License

MIT