@amigo-ai/sdk

Official TypeScript SDK for the Classic Amigo API.

Product Docs · Developer Guide · API Reference · Examples · Changelog

Typed from the committed Classic OpenAPI snapshot, shipped as ESM and CommonJS, and used by existing org-scoped integrations on the original Amigo backend at api.amigo.ai.

Classic Backend Context

@amigo-ai/sdk targets the original org-scoped Amigo backend. Existing deployments still use this surface for conversations, services, organizations, users, agents, context graphs, webhooks, and streaming events.

Product Status

@amigo-ai/sdk remains the supported TypeScript client for the Classic API.

The Platform API is where new workspace-scoped capabilities land first, but the Classic API is not being switched off abruptly. Amigo will publish a migration path, compatibility notes, and upgrade guidance before asking customers to move production workloads.

Choose The Right SDK

Documentation

The docs site remains the primary reference. The repo-local examples stay close to the shipped package surface and are validated in CI.

Installation

npm install @amigo-ai/sdk

Before making requests, obtain Classic organization credentials and a user authorized to read the target resources. Keep API keys in server-side environment variables or a secret manager. The examples below read conversation data; they require access to an existing organization.

For the 2.0.0 generated-model changes, review the current SDK upgrade guidance and recheck the package registry when choosing a version.

Quick Start

import { AmigoClient } from '@amigo-ai/sdk'

const client = new AmigoClient({
  apiKey: 'your-api-key',
  apiKeyId: 'your-api-key-id',
  userId: 'user-id',
  orgId: 'your-organization-id',
})

const conversations = await client.conversations.getConversations({
  limit: 10,
  sort_by: ['-created_at'],
})

console.log(conversations.conversations.map(conversation => conversation.id))

Configuration

Runtime Requirements

The SDK supports Node 18+ and is tested on active Node releases in CI. It relies on web-standard primitives such as fetch, AbortController, URL, and TextEncoder.

Generated Types

The package re-exports the generated OpenAPI types so application code can type directly against the API contract:

import type { components, operations, paths } from '@amigo-ai/sdk'

type Conversation = components['schemas']['ConversationInstance']
type GetConversationsQuery = operations['get-conversations']['parameters']['query']

Public builds are generated from the committed specs/openapi-baseline.json snapshot in this repo so type output stays deterministic across machines and CI runs. When you need to refresh that snapshot, run:

npm run openapi:sync

Retries

The HTTP client retries transient failures with sensible defaults:

• Max attempts: 3
• Backoff base: 250ms with full jitter
• Max delay per attempt: 30s
• Statuses: 408, 429, 500, 502, 503, 504
• Methods: GET, plus POST on 429 when Retry-After is present

Error Handling

import { AmigoClient, AuthenticationError, NetworkError } from '@amigo-ai/sdk'

try {
  const client = new AmigoClient({
    apiKey: 'your-api-key',
    apiKeyId: 'your-api-key-id',
    userId: 'user-id',
    orgId: 'your-organization-id',
  })

  await client.organizations.getOrganization()
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message)
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message)
  } else {
    console.error('Unexpected error:', error)
  }
}

Support

Use the issue tracker for bugs and feature requests. For responsible disclosure, see SECURITY.md.