FounderX-AI Orchestration SDK for TypeScript

Production-quality TypeScript SDK for the FounderX-AI Orchestration API with comprehensive error handling, type safety, and full API coverage.

Features

• Full Type Safety: Complete TypeScript definitions for all API types
• Comprehensive Error Handling: Custom error classes for every error type
• Automatic Retries: Exponential backoff for rate limits and server errors
• Token Management: Automatic token refresh and persistence
• Pagination Helpers: Async iterators for automatic pagination
• Streaming Support: Real-time execution streaming via SSE
• Full API Coverage: All endpoints including auth, execution, artifacts, webhooks, marketplace, analytics, settings

Installation

npm install founderx-orchestration-sdk

Or with yarn:

yarn add founderx-orchestration-sdk

Quick Start

import { OrchestrationClient } from 'founderx-orchestration-sdk'

// Initialize client
const client = new OrchestrationClient({
  baseUrl: 'https://api.example.com',
})

// Login
await client.login('username', 'password')

// Start execution
const execution = await client.execute({
  template_id: 'my-template',
  parameters: { env: 'production' },
  workspace: 'default',
})

console.log(`Execution started: ${execution.execution_id}`)

// List artifacts
const artifacts = await client.listArtifacts({
  execution_id: execution.execution_id,
})

for (const artifact of artifacts.items) {
  console.log(`Artifact: ${artifact.name} (${artifact.size} bytes)`)
}

// Download artifact
const content = await client.downloadArtifact('artifact-123')

Authentication

Username/Password

const client = new OrchestrationClient({
  baseUrl: 'https://api.example.com',
})

await client.login('username', 'password')

Access Token

const client = new OrchestrationClient({
  baseUrl: 'https://api.example.com',
  accessToken: 'your-access-token',
})

API Key (Public API)

const client = new OrchestrationClient({
  baseUrl: 'https://api.example.com',
  apiKey: 'your-api-key',
})

// Use api_key for public endpoints
const status = await client.status(true)

Environment Variables

export ORCH_BASE_URL="https://api.example.com/api/v1"
export ORCH_ACCESS_TOKEN="your-access-token"
export PUBLIC_API_KEY="your-api-key"

// Client automatically picks up environment variables
const client = new OrchestrationClient()

Token Persistence

// Save tokens to file (Node.js only)
const client = new OrchestrationClient({
  tokenStorePath: './.tokens.json',
})

await client.login('username', 'password')
// Tokens automatically saved to ./.tokens.json

// Tokens automatically loaded on next initialization
const client2 = new OrchestrationClient({
  tokenStorePath: './.tokens.json',
})
// Already authenticated!

Core Functionality

Execution Management

// Start execution
const execution = await client.execute({
  template_id: 'my-template',
  parameters: { key: 'value' },
  workspace: 'default',
  priority: 5,
  timeout: 3600,
  tags: ['production', 'critical'],
})

// Get execution status
const status = await client.getExecution('execution-123')
console.log(`Status: ${status.status}`)
console.log(`Result: ${JSON.stringify(status.result)}`)

// List executions
const executions = await client.listExecutions({
  workspace: 'default',
  status: 'completed',
  limit: 50,
})

// Cancel execution
await client.cancelExecution('execution-123')

// Stream execution updates
await client.streamExecution('execution-123', false, (event) => {
  console.log(event)
})

Artifact Management

// List artifacts
const artifacts = await client.listArtifacts({
  execution_id: 'execution-123',
  workspace: 'default',
  limit: 50,
})

// Get artifact metadata
const artifact = await client.getArtifact('artifact-123')

// Download artifact
const content = await client.downloadArtifact('artifact-123')
console.log(`Downloaded ${content.length} bytes`)

// Sign artifact with GPG
const signedArtifact = await client.signArtifact('artifact-123')
console.log(`Signature: ${signedArtifact.signature}`)

Webhooks

// List webhooks
const webhooks = await client.listWebhooks()

// Create webhook
const webhook = await client.createWebhook({
  url: 'https://example.com/webhook',
  events: ['execution.completed', 'execution.failed'],
  secret: 'webhook-secret',
  metadata: { team: 'engineering' },
})

// Delete webhook
await client.deleteWebhook('webhook-123')

// Rotate webhook secret
const updated = await client.rotateWebhookSecret('webhook-123')
console.log(`New secret: ${updated.secret}`)

Marketplace

// List marketplace templates
const templates = await client.listMarketplaceTemplates({
  category: 'backend',
  search: 'rest api',
  limit: 20,
})

// Get template details
const template = await client.getMarketplaceTemplate('template-123')
console.log(`Name: ${template.name}`)
console.log(`Rating: ${template.rating}`)
console.log(`Downloads: ${template.downloads}`)

Analytics & Settings

// Get usage statistics
const stats = await client.getUsageStats({
  workspace: 'default',
  start_date: '2025-01-01',
  end_date: '2025-01-31',
})
console.log(`Total executions: ${stats.total_executions}`)
console.log(`Total cost: $${stats.total_cost}`)

// Get settings
const settings = await client.getSettings('default')

// Update settings
const updated = await client.updateSettings('default', {
  default_provider: 'anthropic',
  default_model: 'claude-3-5-sonnet-20241022',
})

Advanced Features

Automatic Pagination

// Iterate over all executions automatically
for await (const execution of client.iterAllExecutions({ workspace: 'default' })) {
  console.log(`Execution: ${execution.execution_id}`)
}

// Iterate over all artifacts
for await (const artifact of client.iterAllArtifacts({ execution_id: 'execution-123' })) {
  console.log(`Artifact: ${artifact.name}`)
}

Custom Configuration

const client = new OrchestrationClient({
  baseUrl: 'https://api.example.com',
  timeout: 60000,        // Request timeout in milliseconds
  maxRetries: 5,         // Maximum retry attempts
})

Error Handling

import {
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  RateLimitError,
  ValidationError,
  ServerError,
  NetworkError,
  TimeoutError,
} from 'founderx-orchestration-sdk'

try {
  await client.login('username', 'wrong-password')
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error(`Auth failed: ${error.message}`)
    console.error(`Status code: ${error.statusCode}`)
  }
}

try {
  const execution = await client.execute({ template_id: 'invalid' })
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Validation failed: ${error.message}`)
    console.error(`Response: ${JSON.stringify(error.response)}`)
  }
}

try {
  const artifact = await client.getArtifact('nonexistent')
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error(`Not found: ${error.message}`)
  }
}

try {
  // Too many requests
  for (let i = 0; i < 1000; i++) {
    await client.status()
  }
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error(`Rate limited: ${error.message}`)
    console.error(`Retry after: ${error.retryAfter} seconds`)
  }
}

Type Definitions

The SDK includes comprehensive TypeScript types:

import type {
  ExecutionRequest,
  ExecutionResponse,
  ExecutionStatus,
  Artifact,
  ArtifactType,
  WebhookConfig,
  WebhookEvent,
  SystemStatus,
  UsageStats,
  MarketplaceTemplate,
  Settings,
  PaginatedResponse,
} from 'founderx-orchestration-sdk'

// Use enums for type safety
const status: ExecutionStatus = ExecutionStatus.COMPLETED
const artifactType: ArtifactType = ArtifactType.JSON
const event: WebhookEvent = WebhookEvent.EXECUTION_COMPLETED

Testing

import { describe, it, expect, vi } from 'vitest'
import { OrchestrationClient } from 'founderx-orchestration-sdk'
import axios from 'axios'

vi.mock('axios')

describe('OrchestrationClient', () => {
  it('should login successfully', async () => {
    const mockPost = vi.fn().mockResolvedValue({
      data: {
        access_token: 'test-token',
        refresh_token: 'test-refresh',
        token_type: 'bearer',
      },
    })

    ;(axios.create as any).mockReturnValue({
      post: mockPost,
      interceptors: {
        request: { use: vi.fn() },
        response: { use: vi.fn() },
      },
    })

    const client = new OrchestrationClient({
      baseUrl: 'http://test.com',
    })

    const response = await client.login('user', 'pass')
    expect(response.access_token).toBe('test-token')
  })
})

Requirements

• Node.js >= 16.0.0
• TypeScript >= 5.0.0 (for TypeScript projects)

License

Proprietary

Support

• Documentation: https://docs.founder-x.ai/orchestration/sdk/typescript
• Email: [email protected]