Package Exports
- @gpt-core/admin
- @gpt-core/admin/dist/index.js
- @gpt-core/admin/dist/index.mjs
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@gpt-core/admin) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
@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/adminQuick 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.uploadeddocument.analyzeddocument.deletedthread.createdthread.message.createdextraction.completedworkspace.createduser.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:coverageLicense
MIT © GPT Integrators