@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.

For AI Coding Assistants

TL;DR for Claude, Cursor, Copilot, and other AI assistants:

import { GptAdmin } from "@gpt-core/admin";
const admin = new GptAdmin({
  baseUrl: "https://api.example.com",
  token: "admin-jwt",
});

Common operations: | Task | Code | |------|------| | Storage stats | await admin.storage.stats() | | List webhooks | await admin.webhooks.configs.list() | | Create webhook | await admin.webhooks.configs.create(name, url, events, appId) | | Credit account | await admin.accounts.credit(id, amount, 'reason') | | Bulk delete docs | await admin.documents.bulkDelete(ids) | | Rotate API key | await admin.apiKeys.rotate(keyId) |

See llms.txt for complete AI-readable SDK reference.

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 Versioning

The SDK uses Stripe-style API versioning. A default API version is sent with every request via the Accept header.

Default Behavior

Every request automatically includes the SDK's built-in API version:

Accept: application/vnd.api+json; version=2025-12-03

No configuration is needed -- the SDK sends DEFAULT_API_VERSION from base-client.ts automatically.

Pinning a Version (Recommended for Production)

Pin a specific API version to protect your integration from breaking changes:

const admin = new GptAdmin({
  baseUrl: "https://api.gpt-core.com",
  token: process.env.ADMIN_JWT_TOKEN,
  applicationId: process.env.APPLICATION_ID,
  apiVersion: "2025-12-03", // Pin to this version
});

Reading the Active Version

// The version the SDK is configured to send
console.log(admin.apiVersion);

Response Header

Every API response includes the version that was used to process the request:

x-api-version: 2025-12-03

Discovering Available Versions

List all supported API versions and their changelogs:

GET /api-versions

This returns the full list of versions with descriptions and deprecation status.

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

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";

Testing

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

License

MIT © GPT Integrators