@gpt-platform/client

v0.4.3

Published

7 hours ago

TypeScript SDK for GPT Platform Client API - Document extraction, AI agents, and workspace management

@gpt-platform client

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

[![npm version](https://img.shields.io/npm/v/@gpt-platform client.svg)](https://www.npmjs.com/package/@gpt-platform client)

For AI Coding Assistants

TL;DR for Claude, Cursor, Copilot, and other AI assistants:
import { GptClient } from "@gpt-platform client";
const client = new GptClient({
  baseUrl: "https://api.example.com",
  token: "jwt",
});
Common operations: | Task | Code | |------|------| | Login | await client.identity.login(email, password) | | List workspaces | await client.platform.workspaces.mine() | | Upload document | await client.extraction.documents.upload(file) | | AI search | await client.ai.search(query) | | Create agent | await client.agents.create(name, systemPrompt) | | Send message | await client.threads.messages.send(threadId, content) | | Verify webhook | await new Webhooks(secret).verify(body, signature) |
See llms.txt for complete AI-readable SDK reference.

Features

Fully Typed - Complete TypeScript support with auto-generated types from OpenAPI specs
Class-Based API - Stripe-style GptClient with namespaced methods (12 namespaces, ~135 curated methods)
Runtime Validation - Zod schemas for request validation
Smart Error Handling - Custom error classes with detailed context
Automatic Retries - Exponential backoff with circuit breaker for transient failures
Idempotency Keys - Auto-generated for POST/PATCH/DELETE requests
Webhook Verification - HMAC-SHA256 signature verification with timing-safe comparison
Environment Fallback - Auto-reads GPTCORE_BASE_URL, GPTCORE_API_KEY, GPTCORE_TOKEN
Browser Safety - Throws BrowserApiKeyError when API keys used in browser without opt-in
Structured Logging - Configurable log levels and custom logger support
Custom Fetch - Bring your own fetch implementation for testing or custom network layers
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-platform client
# or
yarn add @gpt-platform client
# or
pnpm add @gpt-platform client

Quick Start

import { GptClient } from "@gpt-platform client";

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

// Authenticate a user
const result = await client.identity.login("[email protected]", "password");

// Update token for subsequent requests
client.setToken(result.token);

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

API Versioning

The SDK uses Stripe-style API versioning. A default API version is sent with every request via the Accept header.

Default Behavior

Every request automatically includes the SDK's built-in API version:

Accept: application/vnd.api+json; version=2025-12-03

No configuration is needed -- the SDK sends DEFAULT_API_VERSION from base-client.ts automatically.

Pinning a Version (Recommended for Production)

Pin a specific API version to protect your integration from breaking changes:

const client = new GptClient({
  baseUrl: "https://api.gpt-core.com",
  apiKey: "sk_app_...",
  apiVersion: "2025-12-03", // Pin to this version
});

Reading the Active Version

// The version the SDK is configured to send
console.log(client.apiVersion);

Response Header

Every API response includes the version that was used to process the request:

x-api-version: 2025-12-03

Discovering Available Versions

List all supported API versions and their changelogs:

GET /api-versions

This returns the full list of versions with descriptions and deprecation status.

Configuration

const client = new GptClient({
  // API base URL (falls back to GPTCORE_BASE_URL env var)
  baseUrl: "https://api.gpt-core.com",

  // Authentication (provide one or both; falls back to env vars)
  apiKey: "sk_app_...", // GPTCORE_API_KEY
  token: "eyJhbGc...", // GPTCORE_TOKEN

  // API version (optional, uses SDK default if not specified)
  apiVersion: "2025-12-03",

  // Request timeout in milliseconds (default: no timeout)
  timeout: 30000,

  // Custom fetch implementation (default: globalThis.fetch)
  fetch: customFetch,

  // Default headers sent with every request (auth headers not overridden)
  defaultHeaders: { "X-Custom-Header": "value" },

  // Allow API key usage in browser (default: false, throws BrowserApiKeyError)
  dangerouslyAllowBrowser: false,

  // Log level (default: 'warn')
  logLevel: "debug", // 'debug' | 'info' | 'warn' | 'error' | 'none'

  // Custom logger (default: console)
  logger: myLogger,

  // Application info for User-Agent header (Stripe-style)
  appInfo: { name: "MyApp", version: "1.0.0", url: "https://myapp.com" },

  // Security configuration
  security: {
    requireHttps: false, // Throw InsecureConnectionError on HTTP (default: warn only)
  },

  // Retry configuration (default: 3 retries with exponential backoff)
  retry: {
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 32000,
    retryableStatusCodes: [429, 500, 502, 503, 504],
  },

  // Disable retries
  // retry: false,
});

Security

HTTPS Enforcement

// Development: Warns only (localhost is always allowed)
const devClient = new GptClient({
  baseUrl: "http://localhost:33333",
});

// Production: Blocks HTTP connections
const prodClient = new GptClient({
  baseUrl: "https://api.gpt-core.com",
  security: { requireHttps: true },
});

Browser Safety

Using API keys in browser environments is blocked by default to prevent credential exposure:

// This throws BrowserApiKeyError in browser:
const client = new GptClient({ apiKey: "sk_app_..." });

// Opt-in if you understand the risks:
const client = new GptClient({
  apiKey: "sk_app_...",
  dangerouslyAllowBrowser: true,
});

API Key Validation

The SDK validates API key format and warns about elevated privilege keys:

// Valid prefixes: sk_tenant_*, sk_app_*, sk_srv_*, sk_sys_*
// sk_sys_* keys trigger warnings (elevated privileges)

API Reference

Identity

Manage users, authentication, and API keys.

// Login
const result = await client.identity.login(email, password);
client.setToken(result.token);

// 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");
await client.identity.apiKeys.revoke("key-id");
await client.identity.apiKeys.rotate("key-id");

Platform

Manage applications, workspaces, tenants, and invitations.

// Applications
const apps = await client.platform.applications.list();
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.create(
  "[email protected]",
  "editor",
  "workspace",
  "workspace-id",
);
await client.platform.invitations.accept("invitation-id");

Agents

Create and manage AI agents.

// CRUD
const agents = await client.agents.list();
const agent = await client.agents.create(
  "Support Agent",
  "You are a helpful assistant",
);
const result = await client.agents.test("agent-id", "Hello!");
await client.agents.clone("agent-id");

// Versioning
const versions = await client.agents.versions.list("agent-id");
await client.agents.versions.publish("agent-id");
await client.agents.versions.restore("agent-id", "version-id");

// Training
const examples = await client.agents.training.examples("agent-id");

AI

Semantic search, embeddings, and conversations.

// Search
const results = await client.ai.search("quarterly earnings");
const advanced = await client.ai.searchAdvanced("revenue data", { limit: 20 });

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

// Conversations
const conversations = await client.ai.conversations.list();
const conv = await client.ai.conversations.create({ title: "New Chat" });

Threads

Real-time messaging threads.

// Threads
const threads = await client.threads.list();
const thread = await client.threads.create("Bug Discussion");

// Messages
const messages = await client.threads.messages.list(thread.id);
await client.threads.messages.send(thread.id, "Hello!");

// Actions
await client.threads.archive(thread.id);
await client.threads.fork(thread.id);
await client.threads.export(thread.id);

Extraction

Upload and process documents.

// Upload
const doc = await client.extraction.documents.upload(file);
const status = await client.extraction.documents.status(doc.id);

// Results
const results = await client.extraction.results.list();
const docResults = await client.extraction.results.byDocument(doc.id);

// Batches
const batch = await client.extraction.batches.create({ name: "Q4 Reports" });

Storage

Manage buckets and files.

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

// Presigned URLs
const uploadUrl = await client.storage.signUpload("image.png", "image/png");
const downloadUrl = await client.storage.signDownload("object-id");

Billing

Access wallet, plans, and payment methods.

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

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

// Payment Methods
const methods = await client.billing.paymentMethods.list();
await client.billing.paymentMethods.setDefault("method-id");

Webhooks

Manage webhook configurations and deliveries.

// Configs
const configs = await client.webhooks.configs.list();
await client.webhooks.configs.create("https://myapp.com/webhooks", [
  "document.processed",
]);
await client.webhooks.configs.test("config-id");
await client.webhooks.configs.rotateSecret("config-id");

// Deliveries
const deliveries = await client.webhooks.deliveries.list();
await client.webhooks.deliveries.retry("delivery-id");

Search

Full-text and semantic search.

const results = await client.search.query("invoice");
const semantic = await client.search.semantic("similar to this document");
const suggestions = await client.search.suggest("inv");

// Saved searches
const saved = await client.search.saved.list();
await client.search.saved.run("saved-search-id");

Communication

Notification management.

// Logs
const logs = await client.communication.notifications.logs();

// Methods
const methods = await client.communication.notifications.methods.list();
await client.communication.notifications.methods.verify("method-id");

// Preferences
const prefs = await client.communication.notifications.preferences.list();

Webhook Signature Verification

Verify incoming webhook payloads using HMAC-SHA256 signatures:

import { Webhooks } from "@gpt-platform client";

const wh = new Webhooks("whsec_your_secret_here");

// In your webhook handler (Express example):
app.post("/webhooks", async (req, res) => {
  const signature = req.headers["x-gptcore-signature"];
  const body = req.body; // raw string body

  try {
    await wh.verify(body, signature);
    // Process the webhook...
    res.status(200).send("OK");
  } catch (err) {
    res.status(400).send("Invalid signature");
  }
});

The whsec_ prefix on secrets is stripped automatically. Signatures are checked with timing-safe comparison and a default 5-minute tolerance for timestamp freshness.

Advanced Features

Error Handling

The SDK provides detailed error classes:

import {
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
} from "@gpt-platform 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`);
  }
}

Pagination

Easily iterate over large datasets with built-in memory protection:

import { paginateAll } from "@gpt-platform client";

// With limit (default: 10,000)
for await (const item of paginateAll(fetcher, { pageSize: 50, limit: 1000 })) {
  // Process items
}

Pagination Safety:

Default Limit: 10,000 items max (prevents memory exhaustion)
Warning: Shows warning when fetching > 1,000 items
Configurable: Set custom limit for your use case

Streaming

Stream AI responses in real-time:

import { streamMessage } from "@gpt-platform client";

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

for await (const chunk of streamMessage(response)) {
  if (chunk.type === "content") {
    process.stdout.write(chunk.content);
  }
}

Retry Logic

Automatic retries with exponential backoff and circuit breaker:

const client = new GptClient({
  baseUrl: "https://api.gpt-core.com",
  token: "token",
  retry: {
    maxRetries: 5,
    initialDelay: 1000,
    maxDelay: 32000,
  },
});

// Disable retries
const noRetryClient = new GptClient({
  retry: false,
});

Raw Functions

All 403+ generated functions remain available as named exports for power users:

import { getAgents, postUsersAuthLogin } from "@gpt-platform client";

const { data, error } = await getAgents({ client: myClientInstance });

TypeScript Support

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

import type {
  BaseClientConfig,
  AppInfo,
  Logger,
  LogLevel,
  RequestOptions,
} from "@gpt-platform client";

License

MIT

Support

Documentation: https://docs.gpt-core.com
Issues: https://github.com/GPT-Integrators/gpt-core-sdks/issues