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

package/README.md

@@ -1,12 +1,33 @@
 # @gpt-core/admin
 
-The official TypeScript Admin SDK for the GPT Core Platform.
-**Intended for backend services and internal tools only.**
+The official TypeScript Admin SDK for the GPT Core Platform - platform administration, webhook management, and system monitoring.
+
+[![npm version](https://img.shields.io/npm/v/@gpt-core/admin.svg)](https://www.npmjs.com/package/@gpt-core/admin)
+[![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)
+
+⚠️ **This SDK requires admin privileges and should only be used in secure server environments.**
+
+## Features
+
+✅ **Fully Typed** - Complete TypeScript support with auto-generated types from OpenAPI specs
+✅ **Runtime Validation** - Zod schemas for request validation
+✅ **Bulk Operations** - Efficient batch processing for documents and webhooks
+✅ **Webhook Management** - Configure, monitor, and test webhook configurations
+✅ **Storage Administration** - Monitor storage usage across workspaces and buckets
+✅ **Account Operations** - Credit/debit account balances with audit trails
+✅ **Document Management** - Bulk delete and reprocess documents
+✅ **API Key Management** - Allocate, revoke, and rotate API keys
+✅ **Error Handling** - Comprehensive error handling with detailed context
 
 ## Installation
 
 ```bash
 npm install @gpt-core/admin
+# or
+yarn add @gpt-core/admin
+# or
+pnpm add @gpt-core/admin
 ```
 
 ## Quick Start
@@ -14,34 +35,335 @@ npm install @gpt-core/admin
 ```typescript
 import { GptAdmin } from '@gpt-core/admin';
 
+// Initialize admin client
 const admin = new GptAdmin({
-  baseUrl: 'https://api.gpt-core.com/admin',
-  apiKey: 'your-secret-admin-key'
+  baseUrl: 'https://api.gpt-core.com',
+  token: process.env.ADMIN_JWT_TOKEN,    // Admin JWT token
+  applicationId: process.env.APPLICATION_ID, // Your application ID
 });
 
-// Check System Health
+// Get storage statistics
 const stats = await admin.storage.stats();
-console.log('Total Storage Used:', stats.total_bytes);
+console.log(`Total storage: ${(stats.total_size / 1024 / 1024).toFixed(2)} MB`);
+console.log(`Total files: ${stats.file_count}`);
+
+// List webhook configurations
+const webhooks = await admin.webhooks.configs.list();
+console.log(`Active webhooks: ${webhooks.filter(w => w.attributes.enabled).length}`);
 ```
 
-## Domains
+## Configuration
+
+```typescript
+const admin = new GptAdmin({
+  // Required: API base URL
+  baseUrl: 'https://api.gpt-core.com',
+
+  // Required: Admin JWT token
+  token: 'admin-jwt-token',
+
+  // Required: Application ID
+  applicationId: 'your-app-id',
+});
+```
+
+### Environment Variables (Recommended)
+
+```bash
+# .env or .env.local
+ADMIN_API_URL=https://api.gpt-core.com
+ADMIN_JWT_TOKEN=your-admin-jwt-token
+APPLICATION_ID=your-application-id
+```
 
-### Storage Management
-Monitor storage usage across tenants.
 ```typescript
-await admin.storage.stats();
+// lib/admin-client.ts
+import { GptAdmin } from '@gpt-core/admin';
+
+export const admin = new GptAdmin({
+  baseUrl: process.env.ADMIN_API_URL!,
+  token: process.env.ADMIN_JWT_TOKEN!,
+  applicationId: process.env.APPLICATION_ID!,
+});
 ```
 
+## API Reference
+
 ### Webhooks
-Manage functionality of webhooks system-wide.
+
+#### List Webhook Configs
+
+```typescript
+const configs = await admin.webhooks.configs.list();
+```
+
+#### Create Webhook
+
+```typescript
+const webhook = await admin.webhooks.configs.create(
+  'My Webhook',                          // name
+  'https://your-server.com/webhook',    // url
+  ['document.analyzed', 'thread.message.created'], // events
+  'app-123',                             // application_id
+  'your-webhook-secret',                 // secret (optional)
+  true                                   // enabled
+);
+```
+
+#### Update Webhook Config
+
+```typescript
+const config = await admin.webhooks.configs.update('webhook-id', {
+  enabled: false,
+  events: ['document.analyzed'],
+});
+```
+
+#### Delete Webhook Config
+
+```typescript
+await admin.webhooks.configs.delete('webhook-id');
+```
+
+#### Test Webhook Config
+
+```typescript
+const result = await admin.webhooks.configs.test('webhook-id');
+console.log('Test delivery ID:', result.delivery_id);
+```
+
+#### Webhook Deliveries
+
+```typescript
+// List deliveries
+const deliveries = await admin.webhooks.deliveries.list();
+
+// Get delivery details
+const delivery = await admin.webhooks.deliveries.get('delivery-id');
+
+// Retry failed delivery
+await admin.webhooks.deliveries.retry('delivery-id');
+```
+
+### Storage Administration
+
+```typescript
+// Get overall storage stats
+const stats = await admin.storage.stats();
+console.log(stats.total_size, stats.file_count);
+
+// Get stats for specific workspace
+const workspaceStats = await admin.storage.stats('workspace-id');
+
+// List all buckets
+const buckets = await admin.storage.buckets.list();
+
+// Get bucket details
+const bucket = await admin.storage.buckets.get('bucket-id');
+
+// Get bucket stats
+const bucketStats = await admin.storage.buckets.stats('bucket-id');
+
+// List bucket objects
+const objects = await admin.storage.buckets.objects('bucket-id');
+```
+
+### Account Management
+
+```typescript
+// List all accounts
+const accounts = await admin.accounts.list();
+
+// Get account details
+const account = await admin.accounts.get('account-id');
+
+// Credit an account
+await admin.accounts.credit('account-id', 1000, 'Bonus credits');
+
+// Debit an account
+await admin.accounts.debit('account-id', 500, 'Usage charge');
+```
+
+### Document Administration
+
+```typescript
+// List documents
+const documents = await admin.documents.list();
+
+// Get document details
+const document = await admin.documents.get('doc-id');
+
+// Bulk delete documents
+await admin.documents.bulkDelete(['doc-id-1', 'doc-id-2']);
+
+// Bulk reprocess documents
+await admin.documents.bulkReprocess(['doc-id-1', 'doc-id-2']);
+```
+
+### API Key Management
+
+```typescript
+// List API keys
+const keys = await admin.apiKeys.list();
+
+// Get API key details
+const key = await admin.apiKeys.get('key-id');
+
+// Allocate credits to API key
+await admin.apiKeys.allocate('key-id', 5000, 'Monthly allocation');
+
+// Revoke API key
+await admin.apiKeys.revoke('key-id');
+
+// Rotate API key
+await admin.apiKeys.rotate('key-id');
+```
+
+## Webhook Events
+
+Available webhook events:
+- `document.uploaded`
+- `document.analyzed`
+- `document.deleted`
+- `thread.created`
+- `thread.message.created`
+- `extraction.completed`
+- `workspace.created`
+- `user.registered`
+
+[See full webhook documentation](docs/WEBHOOKS.md)
+
+## Bulk Operations
+
+All bulk operations support:
+- Minimum: 1 item
+- Maximum: 100 items per request
+- Validation via Zod schemas
+
+```typescript
+// Bulk delete up to 100 documents
+const documentIds = ['doc-1', 'doc-2', 'doc-3'];
+await admin.documents.bulkDelete(documentIds);
+
+// Bulk reprocess documents
+await admin.documents.bulkReprocess(documentIds);
+```
+
+## Security
+
+⚠️ **Admin SDK should NEVER be used in client-side code.**
+
+- Use only in secure server environments
+- Never expose admin tokens in client code
+- Rotate admin tokens regularly
+- Audit admin actions
+- Limit admin access to essential operations
+
+## Error Handling
+
 ```typescript
-await admin.webhooks.stats();
-await admin.webhooks.bulkEnable(['config-1', 'config-2']);
+try {
+  await admin.accounts.credit('account-id', 1000);
+} catch (error) {
+  if (error instanceof ZodError) {
+    console.error('Validation error:', error.errors);
+  } else {
+    console.error('API error:', error);
+  }
+}
 ```
 
-### Agents
-Import/Export Agent configurations.
+## Configuration
+
 ```typescript
-const dump = await admin.agents.export('agent-id');
-await admin.agents.import(dump);
+const admin = new GptAdmin({
+  baseUrl: 'https://api.gpt-core.com',  // API base URL
+  token: 'admin-jwt-token',              // Admin JWT token
+  applicationId: 'app-id',               // Application ID
+  apiKey: 'api-key',                     // Optional: API key
+});
+```
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import type {
+  WebhookConfig,
+  WebhookDelivery,
+  Account,
+  Document,
+  ApiKey,
+  Bucket
+} from '@gpt-core/admin';
+```
+
+## Documentation
+
+### For ISV Developers
+
+- **[ISV Integration Guide](docs/ISV_GUIDE.md)** - Complete production-ready integration guide
+  - Environment setup and authentication
+  - Common workflows (webhooks, storage, billing, bulk ops)
+  - Production best practices and security
+  - Monitoring, observability, error handling
+  - Rate limiting and troubleshooting
+
+- **[AI-Assisted Integration](docs/AI_INTEGRATION_GUIDE.md)** - Quick-start for AI coding assistants
+  - Copy-paste integration patterns
+  - Ready-to-use code snippets for common use cases
+  - AI prompt templates for Cursor/Copilot/Claude
+
+### Topic Guides
+
+- **[Authentication](docs/AUTHENTICATION.md)** - Admin token management and security
+  - JWT token authentication
+  - Token refresh strategies
+  - Secret management integration (AWS, Vault, GCP)
+  - Multi-environment configuration
+
+- **[Error Handling](docs/ERROR_HANDLING.md)** - Comprehensive error handling strategies
+  - Validation errors (Zod)
+  - HTTP errors (401, 403, 404, 429, 500)
+  - Retry strategies (exponential backoff, jitter)
+  - Circuit breaker pattern
+  - Graceful degradation
+
+- **[Bulk Operations](docs/BULK_OPERATIONS.md)** - Efficient batch processing guide
+  - Document bulk delete and reprocess
+  - Webhook bulk enable/disable
+  - Batching strategies and performance optimization
+  - Progress tracking and monitoring
+  - Error handling for partial failures
+
+- **[Webhook Management](docs/WEBHOOKS.md)** - Webhook configuration and monitoring
+  - Creating and configuring webhooks
+  - Signature verification
+  - Event handling
+  - Monitoring deliveries
+  - Troubleshooting
+
+### For SDK Contributors
+
+- **[llms.txt](llms.txt)** - AI agent context for SDK maintenance
+  - SDK architecture and patterns
+  - Generated vs handwritten code
+  - Development workflows
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
 ```
+
+## License
+
+MIT © GPT Integrators