JSPM

@gpt-core/admin

0.11.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 439
  • Score
    100M100P100Q97434F
  • 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.

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

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