JSPM

@gpt-core/admin

0.7.67
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 439
  • Score
    100M100P100Q97469F
  • License MIT

TypeScript SDK for GPT Core Admin API - Platform administration and ISV management

Package Exports

  • @gpt-core/admin

Readme

@gpt-core/admin

The official TypeScript Admin SDK for the GPT Core Platform - platform administration, webhook management, and system monitoring.

npm version TypeScript License: 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

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',
});
# .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