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

package/README.md

@@ -1,7 +1,8 @@
 # @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.
+
+⚠️ **This SDK requires admin privileges and should only be used in secure server environments.**
 
 ## Installation
 
@@ -15,33 +16,251 @@ npm install @gpt-core/admin
 import { GptAdmin } from '@gpt-core/admin';
 
 const admin = new GptAdmin({
-  baseUrl: 'https://api.gpt-core.com/admin',
-  apiKey: 'your-secret-admin-key'
+  baseUrl: 'https://api.gpt-core.com',
+  token: 'admin-jwt-token', // Must be admin user
+  applicationId: 'your-app-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} bytes`);
+```
+
+## Features
+
+✅ **Webhook Management** - Configure and monitor webhooks
+✅ **Storage Administration** - Monitor storage usage across workspaces
+✅ **Account Operations** - Credit/debit account balances
+✅ **Document Bulk Operations** - Bulk delete and reprocess documents
+✅ **API Key Management** - Allocate, revoke, rotate API keys
+✅ **Fully Typed** - Complete TypeScript support
+✅ **Runtime Validation** - Zod schemas for request validation
+
+## API Reference
+
+### Webhooks
+
+#### List Webhook Configs
+
+```typescript
+const configs = await admin.webhooks.configs.list();
 ```
 
-## Domains
+#### Create Webhook
 
-### Storage Management
-Monitor storage usage across tenants.
 ```typescript
-await admin.storage.stats();
+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
+);
 ```
 
-### Webhooks
-Manage functionality of webhooks system-wide.
+#### 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
-await admin.webhooks.stats();
-await admin.webhooks.bulkEnable(['config-1', 'config-2']);
+// 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');
 ```
 
-### Agents
-Import/Export Agent configurations.
+### Storage Administration
+
 ```typescript
-const dump = await admin.agents.export('agent-id');
-await admin.agents.import(dump);
+// 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
+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);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+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';
+```
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
+```
+
+## License
+
+MIT © GPT Integrators