# @gpt-core/client

> TypeScript SDK for GPT Core - document extraction, AI agents, and workspace management.
> Version: 0.11.0

## Installation

```bash
npm install @gpt-core/client
```

## Quick Start

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

const client = new GptClient({
  baseUrl: 'https://api.gpt-core.com',
  apiKey: 'sk_app_...', // or token: 'jwt_token'
});
```

## Configuration

```typescript
new GptClient({
  baseUrl: string,             // API base URL (or env GPTCORE_BASE_URL)
  apiKey?: string,             // API key (or env GPTCORE_API_KEY)
  token?: string,              // JWT token (or env GPTCORE_TOKEN)
  apiVersion?: string,         // Default: '2025-12-03'
  timeout?: number,            // Request timeout in ms
  fetch?: typeof fetch,        // Custom fetch implementation
  defaultHeaders?: Record<string, string>,
  dangerouslyAllowBrowser?: boolean,  // Allow API key in browser
  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none',
  logger?: Logger,             // Custom logger (console API)
  appInfo?: { name: string, version?: string, url?: string },
  retry?: { maxRetries, initialDelay, maxDelay } | false,
  security?: { requireHttps?: boolean },
})
```

## Authentication

```typescript
// API key auth (machine-to-machine)
const client = new GptClient({ baseUrl, apiKey: 'sk_app_...' });

// JWT auth (user sessions)
const client = new GptClient({ baseUrl, token: 'eyJ...' });

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

## Namespaces

### identity

```typescript
client.identity.login(email, password)
client.identity.register(email, password, passwordConfirmation)
client.identity.confirm(token)
client.identity.resendConfirmation(email)
client.identity.requestMagicLink(email)
client.identity.magicLinkLogin(token)
client.identity.changePassword(currentPassword, newPassword, newPasswordConfirmation)
client.identity.resetPassword(token, password, passwordConfirmation)
client.identity.me()
client.identity.profile()
client.identity.updateProfile(attributes)
client.identity.acceptTos()
client.identity.stats()
client.identity.dashboard()
client.identity.activity()
client.identity.tenants()

// API Keys
client.identity.apiKeys.list()
client.identity.apiKeys.active()
client.identity.apiKeys.get(id)
client.identity.apiKeys.create(name)
client.identity.apiKeys.revoke(id)
client.identity.apiKeys.rotate(id)
client.identity.apiKeys.allocate(id, credits, reason?)
client.identity.apiKeys.setBudget(id, budget)
client.identity.apiKeys.stats()
```

### platform

```typescript
// Workspaces
client.platform.workspaces.list()
client.platform.workspaces.create(name, slug)
client.platform.workspaces.get(id)
client.platform.workspaces.update(id, attributes)
client.platform.workspaces.delete(id)
client.platform.workspaces.mine()
client.platform.workspaces.shared()
client.platform.workspaces.members(id)
client.platform.workspaces.allocate(id, credits)

// Applications
client.platform.applications.list()
client.platform.applications.create(attributes)
client.platform.applications.get(id)
client.platform.applications.getBySlug(slug)
client.platform.applications.current()
client.platform.applications.update(id, attributes)
client.platform.applications.delete(id)

// Tenants
client.platform.tenants.list()
client.platform.tenants.get(id)
client.platform.tenants.stats(id)

// Invitations
client.platform.invitations.list()
client.platform.invitations.mine()
client.platform.invitations.create(email, role, scopeType, scopeId)
client.platform.invitations.accept(id)
client.platform.invitations.decline(id)
client.platform.invitations.revoke(id)
client.platform.invitations.resend(id)

// Memberships
client.platform.memberships.list()
client.platform.memberships.create(workspaceId, userId, roleId)

// Roles
client.platform.roles.list()
```

### agents

```typescript
client.agents.list()
client.agents.create(name, systemPrompt, attributes?)
client.agents.get(id)
client.agents.update(id, attributes)
client.agents.delete(id)
client.agents.test(id, input)
client.agents.clone(id)
client.agents.export(id)
client.agents.import(data)
client.agents.validate(id)
client.agents.stats(id)
client.agents.usage(id)

// Versions
client.agents.versions.list(agentId)
client.agents.versions.get(id)
client.agents.versions.publish(agentId, attributes?)
client.agents.versions.restore(agentId, versionId)
client.agents.versions.metrics(id)

// Training
client.agents.training.examples(agentId)
client.agents.training.stats(agentId)
```

### extraction

```typescript
// Documents
client.extraction.documents.list()
client.extraction.documents.get(id)
client.extraction.documents.view(id)
client.extraction.documents.upload(file)
client.extraction.documents.beginUpload(attributes)
client.extraction.documents.findOrBeginUpload(attributes)
client.extraction.documents.finishUpload(id)
client.extraction.documents.delete(id)
client.extraction.documents.bulkDelete(ids)
client.extraction.documents.reprocess(id)
client.extraction.documents.bulkReprocess(ids)
client.extraction.documents.status(id)
client.extraction.documents.cancel(id)
client.extraction.documents.stats()

// Results
client.extraction.results.list()
client.extraction.results.get(id)
client.extraction.results.byDocument(documentId)

// Batches
client.extraction.batches.create(attributes)
client.extraction.batches.get(id)

// Exports
client.extraction.exports.list(workspaceId)
client.extraction.exports.create(workspaceId, attributes)
```

### ai

```typescript
client.ai.search(query, options?)
client.ai.searchAdvanced(query, options?)
client.ai.embed(text)

// Conversations
client.ai.conversations.list()
client.ai.conversations.create(attributes)
client.ai.conversations.get(id)
client.ai.conversations.update(id, attributes)
client.ai.conversations.delete(id)

// Messages
client.ai.messages.list()
client.ai.messages.create(attributes)
client.ai.messages.delete(id)
```

### billing

```typescript
// Wallet
client.billing.wallet.get()
client.billing.wallet.updateCredits(attributes)
client.billing.wallet.updatePlan(planSlug)
client.billing.wallet.planPreview()
client.billing.wallet.autoTopUp(attributes)
client.billing.wallet.addons(attributes)
client.billing.wallet.invoices()

// Plans
client.billing.plans.list()
client.billing.plans.get(id)
client.billing.plans.getBySlug(slug)

// Transactions
client.billing.transactions.list()
client.billing.transactions.get(id)

// Credit Packages
client.billing.creditPackages.list()
client.billing.creditPackages.get(id)

// Payment Methods
client.billing.paymentMethods.list()
client.billing.paymentMethods.create(attributes)
client.billing.paymentMethods.get(id)
client.billing.paymentMethods.delete(id)
client.billing.paymentMethods.setDefault(id)
```

### storage

```typescript
// Buckets
client.storage.buckets.list()
client.storage.buckets.all()
client.storage.buckets.create(name, type)
client.storage.buckets.get(id)
client.storage.buckets.update(id, attributes)
client.storage.buckets.delete(id)
client.storage.buckets.stats(id)
client.storage.buckets.objects(id)

// Objects
client.storage.objects.list()
client.storage.objects.get(id)
client.storage.objects.delete(id)
client.storage.objects.register(attributes)

// Presigned URLs
client.storage.signUpload(filename, contentType)
client.storage.signDownload(objectId)

// Stats
client.storage.stats()
```

### webhooks

```typescript
// Configs
client.webhooks.configs.list()
client.webhooks.configs.create(url, events, attributes?)
client.webhooks.configs.get(id)
client.webhooks.configs.update(id, attributes)
client.webhooks.configs.delete(id)
client.webhooks.configs.test(id)
client.webhooks.configs.rotateSecret(id)
client.webhooks.configs.stats()

// Deliveries
client.webhooks.deliveries.list()
client.webhooks.deliveries.get(id)
client.webhooks.deliveries.retry(id)
client.webhooks.deliveries.stats()
```

### search

```typescript
client.search.query(q, options?)
client.search.semantic(q, options?)
client.search.suggest(q)
client.search.batch(queries)
client.search.reindex()
client.search.indexes()
client.search.stats()
client.search.health()
client.search.status()
client.search.analytics()
client.search.analyticsSummary()

// Saved Searches
client.search.saved.list()
client.search.saved.create(attributes)
client.search.saved.delete(id)
client.search.saved.run(id)
```

### threads

```typescript
client.threads.list()
client.threads.create(title?, attributes?)
client.threads.get(id)
client.threads.update(id, attributes)
client.threads.delete(id)
client.threads.archive(id)
client.threads.unarchive(id)
client.threads.export(id)
client.threads.fork(id)
client.threads.summarize(id)
client.threads.search(query)
client.threads.stats()

// Messages
client.threads.messages.list(threadId)
client.threads.messages.send(threadId, content, attributes?)
```

### communication

```typescript
// Notification Logs
client.communication.notifications.logs()
client.communication.notifications.logById(id)
client.communication.notifications.logStats()

// Notification Methods
client.communication.notifications.methods.list()
client.communication.notifications.methods.get(id)
client.communication.notifications.methods.create(attributes)
client.communication.notifications.methods.update(id, attributes)
client.communication.notifications.methods.delete(id)
client.communication.notifications.methods.verify(id)
client.communication.notifications.methods.setPrimary(id)

// Notification Preferences
client.communication.notifications.preferences.list()
client.communication.notifications.preferences.get(id)
client.communication.notifications.preferences.create(attributes)
client.communication.notifications.preferences.update(id, attributes)
```

## Webhook Signature Verification

```typescript
import { Webhooks } from '@gpt-core/client';

const wh = new Webhooks('whsec_your_secret');

// In your webhook handler:
try {
  await wh.verify(rawBody, req.headers['x-gptcore-signature']);
  // Signature valid, process webhook
} catch (err) {
  // Invalid signature
}
```

## Error Handling

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

try {
  await client.identity.login(email, password);
} catch (error) {
  if (error instanceof AuthenticationError) { /* ... */ }
  if (error instanceof ValidationError) { /* error.errors */ }
  if (error instanceof RateLimitError) { /* error.retryAfter */ }
}
```

## Raw Functions

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

```typescript
import { getAgents, postUsersAuthLogin } from '@gpt-core/client';

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

## Types

```typescript
import type { BaseClientConfig, AppInfo, Logger, LogLevel, RequestOptions } from '@gpt-core/client';
```