@gpt-core/client 0.10.13 → 0.10.21

package/README.md

@@ -29,8 +29,11 @@ AI_CONTEXT_END -->
 > **TL;DR for Claude, Cursor, Copilot, and other AI assistants:**
 >
 > ```typescript
-> import { GptClient } from '@gpt-core/client';
-> const client = new GptClient({ baseUrl: 'https://api.example.com', token: 'jwt' });
+> import { GptClient } from "@gpt-core/client";
+> const client = new GptClient({
+>   baseUrl: "https://api.example.com",
+>   token: "jwt",
+> });
 > ```
 >
 > **Common operations:**
@@ -70,26 +73,26 @@ pnpm add @gpt-core/client
 ## Quick Start
 
 ```typescript
-import { GptClient } from '@gpt-core/client';
+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
+  baseUrl: "https://api.gpt-core.com",
+  apiKey: "your-api-key", // For machine-to-machine
+  token: "user-jwt-token", // For user-authenticated requests
 });
 
 // Authenticate a user
 const { user, token } = await client.identity.login(
-  'user@example.com',
-  'password'
+  "user@example.com",
+  "password",
 );
 
 console.log(`Welcome, ${user.attributes.full_name}!`);
 
 // Use the token for subsequent requests
 const authenticatedClient = new GptClient({
-  baseUrl: 'https://api.gpt-core.com',
+  baseUrl: "https://api.gpt-core.com",
   token: token,
 });
 
@@ -117,9 +120,9 @@ 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_...',
-  apiVersion: '2025-12-03',  // Pin to this version
+  baseUrl: "https://api.gpt-core.com",
+  apiKey: "sk_live_...",
+  apiVersion: "2025-12-03", // Pin to this version
 });
 ```
 
@@ -153,18 +156,29 @@ This returns the full list of versions with descriptions and deprecation status.
 ```typescript
 const client = new GptClient({
   // Required: API base URL
-  baseUrl: 'https://api.gpt-core.com',
+  baseUrl: "https://api.gpt-core.com",
 
   // Authentication (provide one or both)
-  apiKey: 'sk_live_...',      // Application API key
-  token: 'eyJhbGc...',        // User JWT token
+  apiKey: "sk_live_...", // Application API key
+  token: "eyJhbGc...", // User JWT token
+
+  // API version (optional, uses SDK default if not specified)
+  apiVersion: "2025-12-03",
+
+  // Security configuration (optional)
+  security: {
+    requireHttps: false, // Throw error on HTTP (default: warn only)
+    warnBrowserApiKey: true, // Warn about API keys in browser (default: true)
+  },
 
   // Retry configuration (optional)
   retry: {
-    maxRetries: 3,             // Default: 3
-    minTimeout: 1000,          // Default: 1000ms
-    maxTimeout: 30000,         // Default: 30000ms
-    randomize: true,           // Default: true (adds jitter)
+    maxRetries: 3, // Default: 3
+    initialDelay: 1000, // Default: 1000ms (renamed from minTimeout)
+    maxDelay: 32000, // Default: 32000ms (renamed from maxTimeout)
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+    totalTimeout: 300000, // Total timeout across all retries (ms)
+    maxRetryAfter: 60, // Max Retry-After header value (seconds)
   },
 
   // Disable retries
@@ -172,6 +186,54 @@ const client = new GptClient({
 });
 ```
 
+## 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 |
+
+### HTTPS Enforcement
+
+```typescript
+// Development: Warns only
+const devClient = new GptClient({
+  baseUrl: "http://localhost:22222",
+  apiKey: process.env.API_KEY,
+  security: { requireHttps: false },
+});
+
+// Production: Blocks HTTP
+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");
+  }
+}
+```
+
+### API Key Validation
+
+The SDK validates API key format and warns about elevated privilege keys:
+
+```typescript
+// Valid keys: 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
 
 ### Identity
@@ -183,7 +245,11 @@ Manage users, authentication, and API keys.
 const { user, token } = await client.identity.login(email, password);
 
 // Register
-const user = await client.identity.register(email, password, passwordConfirmation);
+const user = await client.identity.register(
+  email,
+  password,
+  passwordConfirmation,
+);
 
 // Get current user
 const user = await client.identity.me();
@@ -193,8 +259,8 @@ 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');
+const newKey = await client.identity.apiKeys.create("Production Key");
+await client.identity.apiKeys.allocate("key-id", 1000, "Monthly credits");
 ```
 
 ### Platform
@@ -205,22 +271,25 @@ Manage applications, workspaces, and tenants.
 // Applications
 const apps = await client.platform.applications.list();
 const app = await client.platform.applications.create({
-  name: 'My App',
-  slug: 'my-app',
+  name: "My App",
+  slug: "my-app",
 });
-const app = await client.platform.applications.getBySlug('my-app');
+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');
+const workspace = await client.platform.workspaces.create(
+  "New Workspace",
+  "new-workspace",
+);
 
 // Invitations
 await client.platform.invitations.invite(
-  'colleague@example.com',
-  'editor',
-  'workspace',
-  'workspace-id'
+  "colleague@example.com",
+  "editor",
+  "workspace",
+  "workspace-id",
 );
 ```
 
@@ -232,20 +301,20 @@ Interact with agents, threads, and semantic search.
 // Agents
 const agents = await client.ai.agents.list();
 const agent = await client.ai.agents.create(
-  'Support Agent',
-  'You are a helpful customer support agent'
+  "Support Agent",
+  "You are a helpful customer support agent",
 );
 
 // 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!');
+const thread = await client.ai.threads.create("Bug Report Discussion");
+const message = await client.ai.threads.sendMessage(thread.id, "Hello AI!");
 
 // Search
-const results = await client.ai.search('quarterly earnings', 10);
+const results = await client.ai.search("quarterly earnings", 10);
 
 // Embeddings
-const embedding = await client.ai.embed('text to embed');
+const embedding = await client.ai.embed("text to embed");
 ```
 
 ### Extraction
@@ -258,18 +327,18 @@ const documents = await client.extraction.documents.list();
 
 // Upload (base64)
 const doc = await client.extraction.documents.uploadBase64(
-  'report.pdf',
-  base64Content
+  "report.pdf",
+  base64Content,
 );
 
 // Analyze
 await client.extraction.documents.analyze(doc.id);
 
 // Retrieve
-const doc = await client.extraction.documents.get('doc-id');
+const doc = await client.extraction.documents.get("doc-id");
 
 // Delete
-await client.extraction.documents.delete('doc-id');
+await client.extraction.documents.delete("doc-id");
 
 // Results
 const results = await client.extraction.results.list();
@@ -282,14 +351,14 @@ 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", false);
 
 // Presigned URLs
 const uploadUrl = await client.storage.presigned.upload(
-  'image.png',
-  'image/png'
+  "image.png",
+  "image/png",
 );
-const downloadUrl = await client.storage.presigned.download('file-id');
+const downloadUrl = await client.storage.presigned.download("file-id");
 ```
 
 ### Billing
@@ -318,16 +387,16 @@ import {
   ValidationError,
   RateLimitError,
   ServerError,
-} from '@gpt-core/client';
+} from "@gpt-core/client";
 
 try {
-  await client.identity.login('user@example.com', 'wrong-password');
+  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);
+    console.error("Invalid credentials:", error.message);
+    console.error("Request ID:", error.requestId);
   } else if (error instanceof ValidationError) {
-    console.error('Validation errors:', error.errors);
+    console.error("Validation errors:", error.errors);
   } else if (error instanceof RateLimitError) {
     console.error(`Rate limited. Retry after ${error.retryAfter}s`);
   }
@@ -336,39 +405,50 @@ try {
 
 ### Pagination
 
-Easily iterate over large datasets:
+Easily iterate over large datasets with built-in memory protection:
 
 ```typescript
-import { paginateAll } from '@gpt-core/client';
+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
+// 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
+}
 ```
 
+**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-core/client';
+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' }),
+  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') {
+  if (chunk.type === "content") {
     process.stdout.write(chunk.content); // Real-time output
   }
 }
@@ -376,38 +456,60 @@ for await (const chunk of streamMessage(response)) {
 
 ### Retry Logic
 
-Automatic retries with exponential backoff:
+Automatic retries with exponential backoff and circuit breaker:
 
 ```typescript
-// Retries are enabled by default
+// Retries are enabled by default with circuit breaker protection
 const client = new GptClient({
-  baseUrl: 'https://api.gpt-core.com',
-  token: 'token',
+  baseUrl: "https://api.gpt-core.com",
+  token: "token",
   retry: {
-    maxRetries: 5,      // Retry up to 5 times
-    minTimeout: 2000,   // Start with 2s delay
+    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
   },
 });
 
 // Disable retries for specific operations
 const noRetryClient = new GptClient({
-  baseUrl: 'https://api.gpt-core.com',
-  token: 'token',
+  baseUrl: "https://api.gpt-core.com",
+  token: "token",
   retry: false,
 });
 ```
 
+**Retry Behavior:**
+
+- **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
+
+```typescript
+import { RetryTimeoutError } from "@gpt-core/client";
+
+try {
+  await client.agents.list();
+} catch (error) {
+  if (error instanceof RetryTimeoutError) {
+    console.error("Retry timeout exceeded:", error.message);
+  }
+}
+```
+
 ## TypeScript Support
 
 The SDK is written in TypeScript and provides full type safety:
 
 ```typescript
-import type { user, workspace, document } from '@gpt-core/client';
+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');
+const workspace: workspace = await client.platform.workspaces.create("Test");
 // TypeScript enforces correct parameters
 ```