@gpt-core/client 0.11.0 → 0.11.1

package/README.md

@@ -16,10 +16,11 @@ NOT for: admin operations (use @gpt-core/admin instead).
 Quick patterns:
 - Initialize: new GptClient({ baseUrl, apiKey?, token? })
 - Auth: client.identity.login(email, password) -> { user, token }
-- Documents: client.extraction.documents.uploadBase64(filename, base64)
-- AI Search: client.ai.search(query, limit?)
-- Agents: client.ai.agents.list() / .create(name, systemPrompt)
+- Documents: client.extraction.documents.upload(file)
+- AI Search: client.ai.search(query, options?)
+- Agents: client.agents.list() / .create(name, systemPrompt)
 - Workspaces: client.platform.workspaces.mine()
+- Threads: client.threads.create(title) / .messages.send(threadId, content)
 
 All methods return typed responses. Errors throw typed exceptions (AuthenticationError, ValidationError, etc).
 AI_CONTEXT_END -->
@@ -41,10 +42,11 @@ AI_CONTEXT_END -->
 > |------|------|
 > | Login | `await client.identity.login(email, password)` |
 > | List workspaces | `await client.platform.workspaces.mine()` |
-> | Upload document | `await client.extraction.documents.uploadBase64(name, b64)` |
+> | Upload document | `await client.extraction.documents.upload(file)` |
 > | AI search | `await client.ai.search(query)` |
-> | Create agent | `await client.ai.agents.create(name, systemPrompt)` |
-> | Send message | `await client.ai.threads.sendMessage(threadId, content)` |
+> | 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](llms.txt) for complete AI-readable SDK reference.**
 
@@ -52,13 +54,20 @@ AI_CONTEXT_END -->
 
 ## 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
+- **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
 
@@ -78,26 +87,18 @@ 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
+  apiKey: "sk_app_...", // For machine-to-machine
+  token: "eyJhbGc...", // For user-authenticated requests
 });
 
 // Authenticate a user
-const { user, token } = await client.identity.login(
-  "user@example.com",
-  "password",
-);
-
-console.log(`Welcome, ${user.attributes.full_name}!`);
+const result = await client.identity.login("user@example.com", "password");
 
-// Use the token for subsequent requests
-const authenticatedClient = new GptClient({
-  baseUrl: "https://api.gpt-core.com",
-  token: token,
-});
+// Update token for subsequent requests
+client.setToken(result.token);
 
 // List workspaces
-const workspaces = await authenticatedClient.platform.workspaces.mine();
+const workspaces = await client.platform.workspaces.mine();
 ```
 
 ## API Versioning
@@ -121,7 +122,7 @@ 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_live_...",
+  apiKey: "sk_app_...",
   apiVersion: "2025-12-03", // Pin to this version
 });
 ```
@@ -155,68 +156,85 @@ This returns the full list of versions with descriptions and deprecation status.
 
 ```typescript
 const client = new GptClient({
-  // Required: API base URL
+  // API base URL (falls back to GPTCORE_BASE_URL env var)
   baseUrl: "https://api.gpt-core.com",
 
-  // Authentication (provide one or both)
-  apiKey: "sk_live_...", // Application API key
-  token: "eyJhbGc...", // User JWT token
+  // 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",
 
-  // Security configuration (optional)
+  // 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 error on HTTP (default: warn only)
-    warnBrowserApiKey: true, // Warn about API keys in browser (default: true)
+    requireHttps: false, // Throw InsecureConnectionError on HTTP (default: warn only)
   },
 
-  // Retry configuration (optional)
+  // Retry configuration (default: 3 retries with exponential backoff)
   retry: {
-    maxRetries: 3, // Default: 3
-    initialDelay: 1000, // Default: 1000ms (renamed from minTimeout)
-    maxDelay: 32000, // Default: 32000ms (renamed from maxTimeout)
+    maxRetries: 3,
+    initialDelay: 1000,
+    maxDelay: 32000,
     retryableStatusCodes: [429, 500, 502, 503, 504],
-    totalTimeout: 300000, // Total timeout across all retries (ms)
-    maxRetryAfter: 60, // Max Retry-After header value (seconds)
   },
 
   // Disable retries
-  retry: false,
+  // retry: false,
 });
 ```
 
-## Security Options
-
-| Option              | Type    | Default | Description                                       |
-| ------------------- | ------- | ------- | ------------------------------------------------- |
-| `requireHttps`      | boolean | `false` | Throw `InsecureConnectionError` on non-HTTPS URLs |
-| `warnBrowserApiKey` | boolean | `true`  | Warn when API key detected in browser environment |
+## Security
 
 ### HTTPS Enforcement
 
 ```typescript
-// Development: Warns only
+// Development: Warns only (localhost is always allowed)
 const devClient = new GptClient({
   baseUrl: "http://localhost:22222",
-  apiKey: process.env.API_KEY,
-  security: { requireHttps: false },
 });
 
-// Production: Blocks HTTP
+// Production: Blocks HTTP connections
 const prodClient = new GptClient({
   baseUrl: "https://api.gpt-core.com",
-  apiKey: process.env.API_KEY,
   security: { requireHttps: true },
 });
+```
 
-try {
-  await prodClient.agents.list();
-} catch (error) {
-  if (error instanceof InsecureConnectionError) {
-    console.error("Cannot use HTTP in production");
-  }
-}
+### 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
@@ -224,14 +242,8 @@ try {
 The SDK validates API key format and warns about elevated privilege keys:
 
 ```typescript
-// Valid keys: sk_tenant_*, sk_app_*, sk_srv_*, sk_sys_*
+// Valid prefixes: sk_tenant_*, sk_app_*, sk_srv_*, sk_sys_*
 // sk_sys_* keys trigger warnings (elevated privileges)
-
-const client = new GptClient({
-  apiKey: "sk_sys_abc123",
-});
-// [GPT Core SDK] Using system-level API key (sk_sys_).
-// Ensure this is intended for platform operations.
 ```
 
 ## API Reference
@@ -242,7 +254,8 @@ Manage users, authentication, and API keys.
 
 ```typescript
 // Login
-const { user, token } = await client.identity.login(email, password);
+const result = await client.identity.login(email, password);
+client.setToken(result.token);
 
 // Register
 const user = await client.identity.register(
@@ -261,19 +274,17 @@ const profile = await client.identity.profile();
 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, and tenants.
+Manage applications, workspaces, tenants, and invitations.
 
 ```typescript
 // 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
@@ -285,63 +296,89 @@ const workspace = await client.platform.workspaces.create(
 );
 
 // Invitations
-await client.platform.invitations.invite(
+await client.platform.invitations.create(
   "colleague@example.com",
   "editor",
   "workspace",
   "workspace-id",
 );
+await client.platform.invitations.accept("invitation-id");
 ```
 
-### AI
+### Agents
 
-Interact with agents, threads, and semantic search.
+Create and manage AI agents.
 
 ```typescript
-// Agents
-const agents = await client.ai.agents.list();
-const agent = await client.ai.agents.create(
+// CRUD
+const agents = await client.agents.list();
+const agent = await client.agents.create(
   "Support Agent",
-  "You are a helpful customer 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
 
-// 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!");
+Semantic search, embeddings, and conversations.
 
+```typescript
 // Search
-const results = await client.ai.search("quarterly earnings", 10);
+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" });
 ```
 
-### Extraction
+### Threads
 
-Upload and analyze documents.
+Real-time messaging threads.
 
 ```typescript
-// Documents
-const documents = await client.extraction.documents.list();
-
-// Upload (base64)
-const doc = await client.extraction.documents.uploadBase64(
-  "report.pdf",
-  base64Content,
-);
+// 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);
+```
 
-// Analyze
-await client.extraction.documents.analyze(doc.id);
+### Extraction
 
-// Retrieve
-const doc = await client.extraction.documents.get("doc-id");
+Upload and process documents.
 
-// Delete
-await client.extraction.documents.delete("doc-id");
+```typescript
+// 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
@@ -351,19 +388,16 @@ Manage buckets and files.
 ```typescript
 // Buckets
 const buckets = await client.storage.buckets.list();
-const bucket = await client.storage.buckets.create("uploads", false);
+const bucket = await client.storage.buckets.create("uploads", "private");
 
 // Presigned URLs
-const uploadUrl = await client.storage.presigned.upload(
-  "image.png",
-  "image/png",
-);
-const downloadUrl = await client.storage.presigned.download("file-id");
+const uploadUrl = await client.storage.signUpload("image.png", "image/png");
+const downloadUrl = await client.storage.signDownload("object-id");
 ```
 
 ### Billing
 
-Access wallet and plan information.
+Access wallet, plans, and payment methods.
 
 ```typescript
 // Wallet
@@ -371,8 +405,86 @@ 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.
+
+```typescript
+// 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.
+
+```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();
+```
+
+## Webhook Signature Verification
+
+Verify incoming webhook payloads using HMAC-SHA256 signatures:
+
+```typescript
+import { Webhooks } from "@gpt-core/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
@@ -410,17 +522,7 @@ Easily iterate over large datasets with built-in memory protection:
 ```typescript
 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 (default: 10,000)
-for await (const doc of client.extraction.documents.listAll({ limit: 100 })) {
-  console.log(doc.attributes.filename);
-}
-
-// Custom page size
 for await (const item of paginateAll(fetcher, { pageSize: 50, limit: 1000 })) {
   // Process items
 }
@@ -439,17 +541,15 @@ Stream AI responses in real-time:
 ```typescript
 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
+    process.stdout.write(chunk.content);
   }
 }
 ```
@@ -459,44 +559,30 @@ for await (const chunk of streamMessage(response)) {
 Automatic retries with exponential backoff and circuit breaker:
 
 ```typescript
-// Retries are enabled by default with circuit breaker protection
 const client = new GptClient({
   baseUrl: "https://api.gpt-core.com",
   token: "token",
   retry: {
-    maxRetries: 5, // Retry up to 5 times
-    initialDelay: 1000, // Start with 1s delay
-    maxDelay: 32000, // Max delay between retries
-    totalTimeout: 300000, // Total timeout (5 min) prevents infinite loops
-    maxRetryAfter: 60, // Cap Retry-After header to 60s
+    maxRetries: 5,
+    initialDelay: 1000,
+    maxDelay: 32000,
   },
 });
 
-// Disable retries for specific operations
+// Disable retries
 const noRetryClient = new GptClient({
-  baseUrl: "https://api.gpt-core.com",
-  token: "token",
   retry: false,
 });
 ```
 
-**Retry Behavior:**
+### Raw Functions
 
-- **Circuit Breaker**: Total timeout prevents unbounded retry loops
-- **Retry-After Validation**: Server Retry-After headers capped at 60 seconds
-- **Jitter**: Random delay added to prevent thundering herd
-- **Protected Status Codes**: 429, 500, 502, 503, 504
+All 403+ generated functions remain available as named exports for power users:
 
 ```typescript
-import { RetryTimeoutError } from "@gpt-core/client";
+import { getAgents, postUsersAuthLogin } from "@gpt-core/client";
 
-try {
-  await client.agents.list();
-} catch (error) {
-  if (error instanceof RetryTimeoutError) {
-    console.error("Retry timeout exceeded:", error.message);
-  }
-}
+const { data, error } = await getAgents({ client: myClientInstance });
 ```
 
 ## TypeScript Support
@@ -504,21 +590,20 @@ try {
 The SDK is written in TypeScript and provides full type safety:
 
 ```typescript
-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
+import type {
+  BaseClientConfig,
+  AppInfo,
+  Logger,
+  LogLevel,
+  RequestOptions,
+} from "@gpt-core/client";
 ```
 
 ## License
 
-MIT © GPT Integrators
+MIT
 
 ## Support
 
-- 📧 Email: support@gpt-core.com
-- 📚 Documentation: https://docs.gpt-core.com
-- 🐛 Issues: https://github.com/GPT-Integrators/gpt-core-sdks/issues
+- Documentation: https://docs.gpt-core.com
+- Issues: https://github.com/GPT-Integrators/gpt-core-sdks/issues