@gpt-core/client 0.10.13 → 0.10.20

package/README.md

@@ -159,12 +159,23 @@ const client = new GptClient({
   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)
+    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 +183,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
@@ -336,7 +395,7 @@ try {
 
 ### Pagination
 
-Easily iterate over large datasets:
+Easily iterate over large datasets with built-in memory protection:
 
 ```typescript
 import { paginateAll } from '@gpt-core/client';
@@ -346,12 +405,23 @@ 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:
@@ -376,16 +446,19 @@ 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',
   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
   },
 });
 
@@ -397,6 +470,25 @@ const noRetryClient = new GptClient({
 });
 ```
 
+**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: