SwiftlyAI Client SDK for JavaScript/TypeScript

Official JavaScript/TypeScript SDK for the SwiftlyAI Cloud API. Provides chat completions, streaming, image generation, token counting, model discovery, and automatic quota tracking.

Installation

npm install swiftlyai-client

Quick Start

import { SwiftlyClient, userMessage } from 'swiftlyai-client';

const client = new SwiftlyClient({
  apiKey: 'sa_your_api_key_here',
});

// Chat completion
const response = await client.chat('claude-sonnet-4-5-20250929', [
  userMessage('Hello!')
]);
console.log(response.message);

Features

• Chat completions -- synchronous and streaming
• Image generation -- text-to-image with configurable options
• Token counting -- count tokens without making a request
• Model discovery -- list available models and providers
• Health checks -- verify API availability
• Quota tracking -- automatic quota updates from response headers
• TypeScript-first -- full type definitions included
• Zero runtime dependencies -- only uses the native fetch API
• Tree-shakeable -- ESM and CJS builds included

Usage

Configuration

import { SwiftlyClient } from 'swiftlyai-client';

const client = new SwiftlyClient({
  apiKey: 'sa_your_api_key_here',
  bundleId: 'com.yourapp.id', // optional
});

Chat Completion

const response = await client.chat('claude-sonnet-4-5-20250929', [
  userMessage('Explain quantum computing in one sentence.')
], {
  temperature: 0.7,
  maxTokens: 200,
});

console.log(response.message);
console.log(response.usage?.totalTokens);

Streaming

for await (const chunk of client.streamChat('claude-sonnet-4-5-20250929', [
  userMessage('Write a short poem about the ocean.')
])) {
  process.stdout.write(chunk.message);
}

System Prompts

const response = await client.chat('claude-sonnet-4-5-20250929', [
  userMessage('What is 2 + 2?')
], {
  systemPrompt: 'You are a helpful math tutor. Show your work.',
});

Image Generation

const result = await client.generateImage(
  'A sunset over mountains',
  'dall-e-3',
  { size: '1024x1024', quality: 'hd' }
);

console.log(result.images[0].url);

Token Counting

const count = await client.countTokens('claude-sonnet-4-5-20250929', [
  userMessage('How many tokens is this message?')
]);

console.log(count.tokens);

Model Discovery

const models = await client.getModels();

console.log(models.models);       // All model IDs
console.log(models.providers);    // Grouped by provider
console.log(models.defaultModel); // Default model (if set)

Health Check

import { isHealthy } from 'swiftlyai-client';

const health = await client.healthCheck();
console.log(isHealthy(health)); // true

Quota Tracking

Quota info is automatically updated from response headers after each request:

await client.chat('claude-sonnet-4-5-20250929', [userMessage('Hi')]);

const quota = client.currentQuota;
if (quota) {
  console.log(`${quota.remaining} / ${quota.limit} requests remaining`);
}

Static Singleton

For simple apps that use a single client instance:

import { SwiftlyAI } from 'swiftlyai-client';

SwiftlyAI.configure({
  apiKey: 'sa_your_api_key_here',
});

const client = SwiftlyAI.client;

Error Handling

import { SwiftlyClientError } from 'swiftlyai-client';

try {
  await client.chat('claude-sonnet-4-5-20250929', [userMessage('Hello')]);
} catch (err) {
  if (err instanceof SwiftlyClientError) {
    console.log(err.code);            // e.g. 'RATE_LIMITED'
    console.log(err.isRetryable);     // true for transient errors
    console.log(err.isBillingError);  // true for quota/payment issues

    if (err.isRetryable && err.suggestedRetryDelay) {
      // Wait and retry
    }
  }
}

Error codes: UNAUTHORIZED, INVALID_API_KEY, API_KEY_EXPIRED, BUNDLE_ID_NOT_REGISTERED, QUOTA_EXCEEDED, RATE_LIMITED, TOKEN_LIMIT_EXCEEDED, PAYMENT_REQUIRED, MODEL_NOT_ALLOWED, INVALID_REQUEST, PROVIDER_ERROR, SERVER_ERROR, SERVER_UNAVAILABLE, NETWORK_ERROR, STREAM_ERROR, CONTENT_FILTERED, CONTEXT_LENGTH_EXCEEDED, CONFIGURATION_ERROR, UNKNOWN

Requirements

• Node.js 18+ (or any runtime with native fetch)
• TypeScript 5.0+ (optional, for type checking)

License

MIT