@gpt-core/admin

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.

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

npm install @gpt-core/admin
# or
yarn add @gpt-core/admin
# or
pnpm add @gpt-core/admin

Quick Start

import { GptAdmin } from '@gpt-core/admin';

// Initialize admin client
const admin = new GptAdmin({
  baseUrl: 'https://api.gpt-core.com',
  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 / 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}`);

Configuration

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)

# .env or .env.local
ADMIN_API_URL=https://api.gpt-core.com
ADMIN_JWT_TOKEN=your-admin-jwt-token
APPLICATION_ID=your-application-id

// 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

List Webhook Configs

const configs = await admin.webhooks.configs.list();

Create Webhook

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

const config = await admin.webhooks.configs.update('webhook-id', {
  enabled: false,
  events: ['document.analyzed'],
});

Delete Webhook Config

await admin.webhooks.configs.delete('webhook-id');

Test Webhook Config

const result = await admin.webhooks.configs.test('webhook-id');
console.log('Test delivery ID:', result.delivery_id);

Webhook Deliveries

// 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

// 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

// 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

// 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

// 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

Bulk Operations

All bulk operations support:

• Minimum: 1 item
• Maximum: 100 items per request
• Validation via Zod schemas

// 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

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

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:

import type {
  WebhookConfig,
  WebhookDelivery,
  Account,
  Document,
  ApiKey,
  Bucket
} from '@gpt-core/admin';

Documentation

For ISV Developers

• ISV Integration Guide - 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 - 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 - Admin token management and security

  • JWT token authentication
  • Token refresh strategies
  • Secret management integration (AWS, Vault, GCP)
  • Multi-environment configuration

• Error Handling - 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 - 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 - Webhook configuration and monitoring

  • Creating and configuring webhooks
  • Signature verification
  • Event handling
  • Monitoring deliveries
  • Troubleshooting

For SDK Contributors

• llms.txt - AI agent context for SDK maintenance
  • SDK architecture and patterns
  • Generated vs handwritten code
  • Development workflows

Testing

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

License

MIT © GPT Integrators