# @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.

[![npm version](https://img.shields.io/npm/v/@gpt-platform/client.svg)](https://www.npmjs.com/package/@gpt-platform/client)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

<!-- AI_CONTEXT_START
This SDK provides TypeScript bindings for the GPT Platform API.
Use this for: document extraction, AI agents, workspace management, user authentication.
NOT for: admin operations (use @gpt-platform/admin instead).

Quick patterns:
- Initialize: new GptClient({ baseUrl, apiKey?, token? })
- Auth: client.identity.login(email, password) -> { user, token }
- Documents: client.extraction.documents.beginUpload({ filename, file_type, workspace_id }) → PUT file → finishUpload(docId)
- AI Search: client.ai.search(query, options?)
- Agents: client.agents.list() / .create(name, { instructions })
- Workspaces: client.platform.workspaces.mine()
- Threads: client.threads.create({ title }) / .messages.send(threadId, content)
- Webhooks (verify only): new Webhooks(secret).verify(body, signature) — webhook management is admin-only

All methods return typed responses. Errors throw typed exceptions (AuthenticationError, ValidationError, etc).
AI_CONTEXT_END -->

## For AI Coding Assistants

> **TL;DR for Claude, Cursor, Copilot, and other AI assistants:**
>
> ```typescript
> 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](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

```bash
npm install @gpt-platform/client
# or
yarn add @gpt-platform/client
# or
pnpm add @gpt-platform/client
```

## Quick Start

```typescript
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("user@example.com", "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:

```http
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:

```typescript
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

```typescript
// 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:

```bash
GET /api-versions
```

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

## Configuration

```typescript
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

```typescript
// 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:

```typescript
// 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:

```typescript
// 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.

```typescript
// 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.

```typescript
// 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(
  "colleague@example.com",
  "editor",
  "workspace",
  "workspace-id",
);
await client.platform.invitations.accept("invitation-id");
```

### Agents

Create and manage AI agents.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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](#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.

```typescript
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.

```typescript
// 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](llms.txt) for an AI-readable catalog of every method, or use per-namespace type imports for a focused surface:

```typescript
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:

```typescript
// 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:

```typescript
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:

```typescript
import {
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
} from "@gpt-platform/client";

try {
  await client.identity.login("user@example.com", "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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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
