Zaguan TypeScript SDK

The official TypeScript SDK for Zaguan CoreX. Build production-ready AI applications with full type safety, async/await support, streaming capabilities, and comprehensive coverage of OpenAI-compatible endpoints. Perfect for Node.js, Deno, and modern JavaScript applications.

View on GitHub npm Package

What's New in v1.2.0

🎉 Full Feature Release - Complete OpenAI API Coverage

New Features

Audio Processing (3 methods)
Image Generation (3 methods)
Batch Processing (4 methods)
Assistants API (10 methods)

Improvements

Fine-Tuning Support (5 methods)
Retry Logic with Exponential Backoff
Logging Hooks for Observability
70+ New TypeScript Types

Installation

Install via npm:

npm install @zaguan_ai/sdk

Or with yarn:

yarn add @zaguan_ai/sdk

Requirements:

•Node.js 18.0.0 or higher
•Zero runtime dependencies (uses native fetch)

Quick Start

Basic Chat Completion

import { ZaguanClient } from '@zaguan_ai/sdk';

// Initialize the client
const client = new ZaguanClient({
  baseUrl: 'https://api.zaguanai.com/',
  apiKey: 'your-api-key',
});

// Simple chat completion
const response = await client.chat({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello, world!' }],
});

console.log(response.choices[0].message.content);

Streaming Responses

// Streaming chat completion
for await (const chunk of client.chatStream({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Tell me a story' }],
})) {
  if (chunk.choices[0]?.delta?.content) {
    process.stdout.write(chunk.choices[0].delta.content);
  }
}

Multi-Provider Access

// Switch providers by changing model name only
const providers = [
  'openai/gpt-4o-mini',
  'anthropic/claude-3-5-sonnet',
  'google/gemini-2.0-flash',
];

for (const model of providers) {
  const response = await client.chat({
    model,
    messages: [{ role: 'user', content: 'Hello!' }],
  });
  console.log(`${model}: ${response.choices[0].message.content}`);
}

Key Features

Core Capabilities

•Full TypeScript type definitions
•Async/await & streaming support
•OpenAI-compatible interface
•Request cancellation with AbortController
•Retry logic with exponential backoff

Complete API Coverage

•Chat completions & function calling
•Audio processing (transcription, TTS)
•Image generation & editing
•Batch processing & Assistants API
•Fine-tuning & content moderation

Advanced Examples

Function Calling

const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get weather information for a location',
    parameters: {
      type: 'object',
      properties: {
        location: { type: 'string' }
      },
      required: ['location']
    }
  }
}];

const response = await client.chat({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: "What's the weather in Paris?" }],
  tools,
  tool_choice: 'auto'
});

Vision & Multimodal

const response = await client.chat({
  model: 'openai/gpt-4o',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: "What's in this image?" },
      {
        type: 'image_url',
        image_url: {
          url: 'https://example.com/image.jpg',
          detail: 'high'
        }
      }
    ]
  }]
});

Provider-Specific Features

// Google Gemini Reasoning
const response = await client.chat({
  model: 'google/gemini-2.0-flash-thinking-exp',
  messages: [{ role: 'user', content: 'Solve this complex problem...' }],
  provider_specific_params: {
    reasoning_effort: 'high',
    thinking_budget: 10000,
    include_thinking: true
  }
});

// Perplexity Search
const searchResponse = await client.chat({
  model: 'perplexity/sonar-reasoning',
  messages: [{ role: 'user', content: 'Latest AI news?' }],
  provider_specific_params: {
    search_domain_filter: ['arxiv.org'],
    return_citations: true,
    search_recency_filter: 'month'
  }
});

Retry Logic & Observability

const client = new ZaguanClient({
  baseUrl: 'https://api.zaguanai.com/',
  apiKey: 'your-api-key',
  retry: {
    maxRetries: 3,
    initialDelayMs: 1000,
    maxDelayMs: 10000,
    backoffMultiplier: 2,
  },
  onLog: (event) => {
    console.log(`[${event.type}] ${event.method} ${event.url}`);
  },
});