@gpt-core/client 0.1.0-alpha.1 → 0.2.0

package/README.md

@@ -1,6 +1,20 @@
 # @gpt-core/client
 
-The official TypeScript Client SDK for the GPT Core Platform.
+The official TypeScript SDK for the GPT Core Platform - document extraction, AI agents, and workspace management.
+
+[![npm version](https://img.shields.io/npm/v/@gpt-core/client.svg)](https://www.npmjs.com/package/@gpt-core/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)
+
+## 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
 
 ## Installation
 
@@ -8,6 +22,8 @@ The official TypeScript Client SDK for the GPT Core Platform.
 npm install @gpt-core/client
 # or
 yarn add @gpt-core/client
+# or
+pnpm add @gpt-core/client
 ```
 
 ## Quick Start
@@ -15,50 +31,317 @@ yarn add @gpt-core/client
 ```typescript
 import { GptClient } from '@gpt-core/client';
 
+// Initialize client
 const client = new GptClient({
   baseUrl: 'https://api.gpt-core.com',
-  apiKey: 'your-public-key', // Optional for some endpoints
-  token: 'user-jwt-token',   // Optional for authenticated endpoints
+  apiKey: 'your-api-key',      // For machine-to-machine
+  token: 'user-jwt-token',     // For user-authenticated requests
 });
 
-// Authenticate
-const { user, token } = await client.identity.login('user@example.com', 'password');
-console.log(`Welcome, ${user.attributes.full_name}`);
+// Authenticate a user
+const { user, token } = await client.identity.login(
+  'user@example.com',
+  'password'
+);
+
+console.log(`Welcome, ${user.attributes.full_name}!`);
 
-// Search AI
-const results = await client.ai.search('quarterly earnings');
+// Use the token for subsequent requests
+const authenticatedClient = new GptClient({
+  baseUrl: 'https://api.gpt-core.com',
+  token: token,
+});
+
+// List workspaces
+const workspaces = await authenticatedClient.platform.workspaces.mine();
 ```
 
-## Features
+## Configuration
+
+```typescript
+const client = new GptClient({
+  // Required: API base URL
+  baseUrl: 'https://api.gpt-core.com',
+
+  // Authentication (provide one or both)
+  apiKey: 'sk_live_...',      // Application API key
+  token: 'eyJhbGc...',        // User JWT token
 
-- **Typed Inputs & Outputs**: Fully typed request/response bodies generated from OpenAPI specs.
-- **Auto-Unwrapping**: Automatically handles JSON:API envelopes (`data: { type: ..., attributes: ... }`) so you get clean objects.
-- **Modular**: Grouped by domain (`identity`, `platform`, `ai`, `extraction`, `billing`).
+  // Retry configuration (optional)
+  retry: {
+    maxRetries: 3,             // Default: 3
+    minTimeout: 1000,          // Default: 1000ms
+    maxTimeout: 30000,         // Default: 30000ms
+    randomize: true,           // Default: true (adds jitter)
+  },
 
-## Domains
+  // Disable retries
+  retry: false,
+});
+```
+
+## API Reference
 
 ### Identity
-Manage users, profiles, and API keys.
+
+Manage users, authentication, and API keys.
+
 ```typescript
-await client.identity.me();
-await client.identity.apiKeys.create('My Key');
+// Login
+const { user, token } = await client.identity.login(email, password);
+
+// 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');
 ```
 
 ### Platform
+
 Manage applications, workspaces, and tenants.
+
 ```typescript
-await client.platform.applications.list();
-await client.platform.workspaces.create('New Workspace');
+// 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
+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.invite(
+  'colleague@example.com',
+  'editor',
+  'workspace',
+  'workspace-id'
+);
 ```
 
 ### AI
-Interact with Agents, Threads, and semantic search.
+
+Interact with agents, threads, and semantic search.
+
+```typescript
+// Agents
+const agents = await client.ai.agents.list();
+const agent = await client.ai.agents.create(
+  '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!');
+
+// Search
+const results = await client.ai.search('quarterly earnings', 10);
+
+// Embeddings
+const embedding = await client.ai.embed('text to embed');
+```
+
+### Extraction
+
+Upload and analyze documents.
+
+```typescript
+// Documents
+const documents = await client.extraction.documents.list();
+
+// Upload (base64)
+const doc = await client.extraction.documents.uploadBase64(
+  'report.pdf',
+  base64Content
+);
+
+// Analyze
+await client.extraction.documents.analyze(doc.id);
+
+// Retrieve
+const doc = await client.extraction.documents.get('doc-id');
+
+// Delete
+await client.extraction.documents.delete('doc-id');
+
+// Results
+const results = await client.extraction.results.list();
+```
+
+### Storage
+
+Manage buckets and files.
+
+```typescript
+// Buckets
+const buckets = await client.storage.buckets.list();
+const bucket = await client.storage.buckets.create('uploads', false);
+
+// Presigned URLs
+const uploadUrl = await client.storage.presigned.upload(
+  'image.png',
+  'image/png'
+);
+const downloadUrl = await client.storage.presigned.download('file-id');
+```
+
+### Billing
+
+Access wallet and plan information.
+
+```typescript
+// Wallet
+const wallet = await client.billing.wallet.get();
+
+// Plans
+const plans = await client.billing.plans.list();
+```
+
+## Advanced Features
+
+### Error Handling
+
+The SDK provides detailed error classes:
+
+```typescript
+import {
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ValidationError,
+  RateLimitError,
+  ServerError,
+} from '@gpt-core/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`);
+  }
+}
+```
+
+[Read more about error handling](docs/ERROR_HANDLING.md)
+
+### Pagination
+
+Easily iterate over large datasets:
+
+```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
+for await (const doc of client.extraction.documents.listAll({ limit: 100 })) {
+  console.log(doc.attributes.filename);
+}
+```
+
+[Read more about pagination](docs/PAGINATION.md)
+
+### Streaming
+
+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
+  }
+}
+```
+
+[Read more about streaming](docs/STREAMING.md)
+
+### Retry Logic
+
+Automatic retries with exponential backoff:
+
 ```typescript
-await client.ai.threads.sendMessage('thread-id', 'Hello AI');
+// Retries are enabled by default
+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
+  },
+});
+
+// Disable retries for specific operations
+const noRetryClient = new GptClient({
+  baseUrl: 'https://api.gpt-core.com',
+  token: 'token',
+  retry: false,
+});
 ```
 
-### Extraction & Storage
-Upload documents and manage files.
+## Guides
+
+- [Authentication Guide](docs/AUTHENTICATION.md)
+- [Error Handling Guide](docs/ERROR_HANDLING.md)
+- [Pagination Guide](docs/PAGINATION.md)
+- [Streaming Guide](docs/STREAMING.md)
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type safety:
+
 ```typescript
-await client.extraction.documents.uploadBase64('file.pdf', 'base64string...');
+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
 ```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
+
+## License
+
+MIT © GPT Integrators
+
+## Support
+
+- 📧 Email: support@gpt-core.com
+- 📚 Documentation: https://docs.gpt-core.com
+- 🐛 Issues: https://github.com/GPT-Integrators/gpt-core-sdks/issues