@gpt-core/client

The official TypeScript SDK for the GPT Core Platform - document extraction, AI agents, and workspace management.

Features

✅ Fully Typed - Complete TypeScript support with auto-generated types from OpenAPI specs ✅ Runtime Validation - Zod schemas for request validation ✅ Smart Error Handling - Custom error classes with detailed context ✅ Automatic Retries - Exponential backoff for transient failures ✅ Pagination Support - Async iterators for easy iteration over large datasets ✅ Streaming Support - Server-Sent Events (SSE) for real-time AI responses ✅ JSON:API Compliant - Automatic envelope unwrapping

Installation

npm install @gpt-core/client
# or
yarn add @gpt-core/client
# or
pnpm add @gpt-core/client

Quick Start

import { GptClient } from '@gpt-core/client';

// Initialize client
const client = new GptClient({
  baseUrl: 'https://api.gpt-core.com',
  apiKey: 'your-api-key',      // For machine-to-machine
  token: 'user-jwt-token',     // For user-authenticated requests
});

// Authenticate a user
const { user, token } = await client.identity.login(
  '[email protected]',
  'password'
);

console.log(`Welcome, ${user.attributes.full_name}!`);

// Use the token for subsequent requests
const authenticatedClient = new GptClient({
  baseUrl: 'https://api.gpt-core.com',
  token: token,
});

// List workspaces
const workspaces = await authenticatedClient.platform.workspaces.mine();

Configuration

const client = new GptClient({
  // Required: API base URL
  baseUrl: 'https://api.gpt-core.com',

  // Authentication (provide one or both)
  apiKey: 'sk_live_...',      // Application API key
  token: 'eyJhbGc...',        // User JWT token

  // Retry configuration (optional)
  retry: {
    maxRetries: 3,             // Default: 3
    minTimeout: 1000,          // Default: 1000ms
    maxTimeout: 30000,         // Default: 30000ms
    randomize: true,           // Default: true (adds jitter)
  },

  // Disable retries
  retry: false,
});

API Reference

Identity

Manage users, authentication, and API keys.

// Login
const { user, token } = await client.identity.login(email, password);

// Register
const user = await client.identity.register(email, password, passwordConfirmation);

// Get current user
const user = await client.identity.me();

// Get user profile
const profile = await client.identity.profile();

// API Keys
const keys = await client.identity.apiKeys.list();
const newKey = await client.identity.apiKeys.create('Production Key');
await client.identity.apiKeys.allocate('key-id', 1000, 'Monthly credits');

Platform

Manage applications, workspaces, and tenants.

// Applications
const apps = await client.platform.applications.list();
const app = await client.platform.applications.create({
  name: 'My App',
  slug: 'my-app',
});
const app = await client.platform.applications.getBySlug('my-app');

// Workspaces
const workspaces = await client.platform.workspaces.list();
const myWorkspaces = await client.platform.workspaces.mine();
const workspace = await client.platform.workspaces.create('New Workspace', 'new-workspace');

// Invitations
await client.platform.invitations.invite(
  '[email protected]',
  'editor',
  'workspace',
  'workspace-id'
);

AI

Interact with agents, threads, and semantic search.

// Agents
const agents = await client.ai.agents.list();
const agent = await client.ai.agents.create(
  'Support Agent',
  'You are a helpful customer support agent'
);

// Threads (Conversations)
const threads = await client.ai.threads.list();
const thread = await client.ai.threads.create('Bug Report Discussion');
const message = await client.ai.threads.sendMessage(thread.id, 'Hello AI!');

// Search
const results = await client.ai.search('quarterly earnings', 10);

// Embeddings
const embedding = await client.ai.embed('text to embed');

Extraction

Upload and analyze documents.

// Documents
const documents = await client.extraction.documents.list();

// Upload (base64)
const doc = await client.extraction.documents.uploadBase64(
  'report.pdf',
  base64Content
);

// Analyze
await client.extraction.documents.analyze(doc.id);

// Retrieve
const doc = await client.extraction.documents.get('doc-id');

// Delete
await client.extraction.documents.delete('doc-id');

// Results
const results = await client.extraction.results.list();

Storage

Manage buckets and files.

// Buckets
const buckets = await client.storage.buckets.list();
const bucket = await client.storage.buckets.create('uploads', false);

// Presigned URLs
const uploadUrl = await client.storage.presigned.upload(
  'image.png',
  'image/png'
);
const downloadUrl = await client.storage.presigned.download('file-id');

Billing

Access wallet and plan information.

// Wallet
const wallet = await client.billing.wallet.get();

// Plans
const plans = await client.billing.plans.list();

Advanced Features

Error Handling

The SDK provides detailed error classes:

import {
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
} from '@gpt-core/client';

try {
  await client.identity.login('[email protected]', 'wrong-password');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid credentials:', error.message);
    console.error('Request ID:', error.requestId);
  } else if (error instanceof ValidationError) {
    console.error('Validation errors:', error.errors);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  }
}

Read more about error handling

Pagination

Easily iterate over large datasets:

import { paginateAll } from '@gpt-core/client';

// Using async iteration
for await (const workspace of client.platform.workspaces.listAll()) {
  console.log(workspace.attributes.name);
}

// With limit
for await (const doc of client.extraction.documents.listAll({ limit: 100 })) {
  console.log(doc.attributes.filename);
}

Read more about pagination

Streaming

Stream AI responses in real-time:

import { streamMessage } from '@gpt-core/client';

// Make streaming request
const response = await fetch(streamingEndpoint, {
  method: 'POST',
  headers: { 'Accept': 'text/event-stream' },
  body: JSON.stringify({ content: 'Hello AI' }),
});

// Stream the response
for await (const chunk of streamMessage(response)) {
  if (chunk.type === 'content') {
    process.stdout.write(chunk.content); // Real-time output
  }
}

Read more about streaming

Retry Logic

Automatic retries with exponential backoff:

// Retries are enabled by default
const client = new GptClient({
  baseUrl: 'https://api.gpt-core.com',
  token: 'token',
  retry: {
    maxRetries: 5,      // Retry up to 5 times
    minTimeout: 2000,   // Start with 2s delay
  },
});

// Disable retries for specific operations
const noRetryClient = new GptClient({
  baseUrl: 'https://api.gpt-core.com',
  token: 'token',
  retry: false,
});

Guides

• Authentication Guide
• Error Handling Guide
• Pagination Guide
• Streaming Guide

TypeScript Support

The SDK is written in TypeScript and provides full type safety:

import type { user, workspace, document } from '@gpt-core/client';

const user: user = await client.identity.me();
// TypeScript knows: user.attributes.email, user.id, etc.

const workspace: workspace = await client.platform.workspaces.create('Test');
// TypeScript enforces correct parameters

Contributing

Contributions are welcome! Please read our Contributing Guide.

License

MIT © GPT Integrators

Support

• 📧 Email: [email protected]
• 📚 Documentation: https://docs.gpt-core.com
• 🐛 Issues: https://github.com/GPT-Integrators/gpt-core-sdks/issues