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

package/README.md

@@ -2,12 +2,32 @@
 
 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
@@ -15,26 +35,57 @@ 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',
-  token: 'admin-jwt-token', // Must be admin user
-  applicationId: 'your-app-id',
+  token: process.env.ADMIN_JWT_TOKEN,    // Admin JWT token
+  applicationId: process.env.APPLICATION_ID, // Your application ID
 });
 
 // Get storage statistics
 const stats = await admin.storage.stats();
-console.log(`Total storage: ${stats.total_size} 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}`);
 ```
 
-## Features
+## Configuration
 
-✅ **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
+```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
+```
+
+```typescript
+// 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
 
@@ -248,6 +299,58 @@ import type {
 } 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