@gpt-platform/client

🚧 GPT Integrators — Internal Use Only. This SDK is published for use by GPT Integrators during platform testing and buildout. It is not offered for general public access at this time and is not ready for public release. Do not redistribute, share credentials, or build production integrations against this package outside of authorized GPT Integrator engagements.

The official TypeScript SDK for the GPT Platform — a composable, multi-tenant AI application backend. Covers document extraction, AI agents and agent pipelines (Reactor DAG orchestration), CRM, scheduling (appointments + recurring/cron), clinical workflows, forms, recipes, invoices, campaigns and direct email, case management, contracts, meetings, voice (STT/TTS, real-time streaming), conversational memory and knowledge graph, support tickets and queues, catalog/inventory, multi-channel messaging gateway (WhatsApp/Slack/Email), managed OAuth connectors, polymorphic human-review queues, compliance workflows (HIPAA/GDPR/PCI), and real-time WebSocket events.

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.beginUpload({ filename, file_type, workspace_id }) then PUT to upload_url then finishUpload(docId) | | AI search | await client.ai.search(query) | | Create agent | await client.agents.create(name, { instructions }) | | 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 50+ domain namespaces and hundreds of curated methods
• Per-Namespace Imports — Faster type resolution via subpath exports (import type { CrmAPI } from '@gpt-platform/client/crm')
• 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
• SSE Streaming — Server-Sent Events for real-time AI responses and agent execution
• WebSocket Channels — Scoped channel tokens for real-time domain events (CRM, scheduling, clinical, forms, review workflows, and more)
• 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=2026-05-13

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: "2026-05-13", // 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: 2026-05-13

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: "2026-05-13",

  // 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", {
  instructions: "You are a helpful assistant",
  vertical: "support",
});
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({ title: "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 (two-phase presigned flow)
const doc = await client.extraction.documents.beginUpload({
  filename: "invoice.pdf",
  file_type: "pdf",
  workspace_id: "ws_abc",
});
await fetch(doc.attributes!.upload_url as string, {
  method: "PUT",
  body: file,
});
await client.extraction.documents.finishUpload(doc.id!);
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({
  workspace_id: "ws_abc",
  name: "Q4 Reports",
});

Storage

Manage buckets and files.

// Buckets
const buckets = await client.storage.buckets.list();
const bucket = await client.storage.buckets.create({
  workspace_id: "ws_abc",
  name: "uploads",
});

// Presigned upload — file uploads bypass the API server
const upload = await client.storage.signUpload({
  filename: "image.png",
  content_type: "image/png",
});
// → PUT the file directly to `upload.url`, then reference `upload.storage_path`

// Presigned download for a tracked storage file
const download = await client.storage.files.requestDownloadUrl(
  "file_01HXYZ...",
  { expires_in: 300 }, // 5-minute window
);

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 (signature verification only)

The client SDK ships an HMAC-SHA256 verifier for incoming webhook payloads — see the Webhook Signature Verification section below. Webhook configuration management (create/list/rotate/test, delivery retries) lives on the admin SDK (admin.webhooks.configs.*, admin.webhooks.deliveries.*) since it is a server-to-server administrative operation.

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();

Additional Namespaces

The client exposes 50+ domain namespaces beyond those documented in full above. Each follows the same conventions (typed methods, JSON:API envelope unwrapping, pagination where applicable):

| Namespace | Domain | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | client.accessGrants | Access grant management (permission scopes per actor) | | client.audit | Audit log queries | | client.campaigns | Marketing campaigns, recipients, AI generation, tracking, sequences | | client.cases | Case management with state machines, decisions, and links | | client.catalog | Products, variants, options, taxonomy, inventory | | client.channels | Scoped channel-token exchange for WebSocket connections | | client.clinical | Patients, sessions, notes, care plans — IDs only, no PHI on wire | | client.communication | Notifications: logs, delivery methods, preferences | | client.compliance | PII detection, legal consolidation, consent, GDPR/HIPAA/PCI workflows | | client.connectors | Managed OAuth + adapters (Gmail, Healthie, Stripe, Slack, and more) | | client.content | Generic content operations | | client.contracts | AI contract lifecycle, clause extraction, renewal alerts | | client.crawler | Web crawling, robots.txt-aware content extraction | | client.crm | Contacts, companies, deals, activities, pipelines, relationships | | client.documents | Generic document operations | | client.email | Direct email sending, sender profiles, tracking, unsubscribers | | client.forms | Form definitions, publications, submissions, logic engine (PHI encryption) | | client.imports | Bulk import pipelines with live progress via WebSocket | | client.invoices | AI-enriched invoicing, rules, payments, recurring generation | | client.meetings | AI meeting transcription, summary, and action item extraction (IDs only on the wire — PHI gated by sparse fieldsets) | | client.memory | Knowledge files, hybrid search, session memory, knowledge graph | | client.models | LLM model catalog | | client.ownershipTransfers | Tenant ownership transfer flows | | client.permissions | Permission registry | | client.pipelines | Reactor DAG pipeline definitions | | client.pipelineExecutions | Pipeline run management | | client.pipelineNodes | Pipeline node definitions | | client.pipelineNodeExecutions | Pipeline node execution telemetry | | client.portal | ISV end-user portal check-in and submissions | | client.preferences | User-scoped key/value preferences (workspace-isolated) | | client.projects | Project administration | | client.recipes | Recipes, shopping lists, nutrition, substitutions | | client.reviews | Polymorphic human-review queues + workflow | | client.roles | Role definitions | | client.scheduler | Recurring/cron-style schedules + execution history | | client.scheduling | Appointments, bookings, events, availability, calendar sync | | client.scopes | API key scope catalog | | client.sessionNotes | Clinical session notes with cosign workflow (IDs only on wire) | | client.social | Social accounts, post scheduling, AI campaigns | | client.support | Tickets, queues, SLA, AI modes, agent presence | | client.toolkit | Toolkit primitives for ISV apps (forms, voice, etc.) | | client.training | Agent training examples and feedback | | client.voice | Voice sessions, STT/TTS, real-time streaming | | client.watcher | Type-only namespace for watcher/ingestion events |

See llms.txt for an AI-readable catalog of every method, or use per-namespace type imports for a focused surface:

import type { CrmAPI, CreateContactAttributes } from "@gpt-platform/client/crm";
import type { SchedulingAPI } from "@gpt-platform/client/scheduling";

Real-time WebSocket Channels

Exchange the current bearer token for a short-lived, scoped channel token and connect it to a Phoenix socket for real-time domain events:

// Exchange for a scoped channel token (5-minute TTL)
const { channelToken } = await client.channels.authorize({
  workspaceId: "ws-uuid",
  channels: ["crm", "scheduling", "reviews", "forms"],
});

// Or use a managed token that auto-refreshes before expiry
const manager = await client.channels.createTokenManager({
  workspaceId: "ws-uuid",
  channels: ["crm", "scheduling", "reviews"],
  socketUrl: "wss://platform.example.com/socket",
  onAuthError: async (err) => {
    /* re-auth */
  },
});

// Join topics with a Phoenix socket using manager.getToken() — events arrive
// as {payload, event} messages (e.g. "contact_created", "review_approved",
// "booking_rescheduled"). See the ChannelTokenRequest JSDoc for the full
// list of supported patterns.

Supported patterns include crm, scheduling, clinical, invoices, forms, recipes, social, automation, connectors, tenancy, reviews, cases, import, and more. The full list with per-pattern event descriptions is on ChannelTokenRequest.

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

The full set of generated functions is 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

• See llms.txt (alongside this README) for the AI-readable method catalog
• File issues against the main gpt-core-platform repository