@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:
>
> ``typescript
> 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

`bash
npm install @gpt-core/admin


or

yarn add @gpt-core/admin

or

pnpm add @gpt-core/admin
`

Quick Start

`typescript
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

`typescript
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",
});
`

$3

`bash


.env or .env.local


ADMIN_API_URL=https://api.gpt-core.com
ADMIN_JWT_TOKEN=your-admin-jwt-token
APPLICATION_ID=your-application-id
`

`typescript
// 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.

$3

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

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

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

$3

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

`typescript
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
});
`

$3

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

$3

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

`
x-api-version: 2025-12-03
`

$3

List all supported API versions and their changelogs:

`bash
GET /api-versions
`

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

API Reference

$3

#### List Webhook Configs

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

#### Create Webhook

`typescript
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

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

#### Delete Webhook Config

`typescript
await admin.webhooks.configs.delete("webhook-id");
`

#### Test Webhook Config

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

#### Webhook Deliveries

`typescript
// 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");
`

$3

`typescript
// 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");
`

$3

`typescript
// 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");
`

$3

`typescript
// 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"]);
`

$3

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

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

`typescript
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

`typescript
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:

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

Testing

`bash


Run tests

npm test

Watch mode

npm run test:watch

Coverage

npm run test:coverage
``

License

MIT © GPT Integrators