@hyperion-ai/sdk 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# Hyperion TypeScript SDK
+
+The official TypeScript/Node.js SDK for the Hyperion AI Gateway. This SDK is a thin, type-safe wrapper around the official `openai` SDK, providing native support for Hyperion's caching, routing, and administrative features.
+
+## Installation
+
+```bash
+npm install @hyperion-ai/sdk
+```
+
+## Quick Start
+
+```typescript
+import { HyperionClient } from '@hyperion-ai/sdk';
+
+const client = new HyperionClient({
+  apiKey: "your-hyperion-key",
+  baseURL: "http://your-gateway:8080/v1"
+});
+
+const res = await client.chat.completions.create({
+  model: "openai/gpt-5.2",
+  messages: [{ role: "user", content: "Explain Hyperion." }],
+  // Hyperion-specific config
+  hyperion: {
+    bypassCache: false,
+    tags: ["production"],
+    routeIntent: "balanced"
+  }
+});
+
+console.log(`Cache Status: ${res.hyperion.cacheStatus}`);
+console.log(`Similarity Score: ${res.hyperion.similarityScore}`);
+```
+
+## Features
+
+- **Standard OpenAI API**: Drop-in replacement for `OpenAI`. All your existing code works exactly the same.
+- **Type Safety**: Fully typed `hyperion` config block and response metadata.
+- **Enriched Metadata**: Every completion response includes a `.hyperion` property with cache status and semantic similarity details.
+- **Admin Client**: Programmatic management of keys, organizations, and budgets.
+- **Isomorphic**: Works in Node.js, Vercel Edge, Cloudflare Workers, and the browser.
+
+## Admin Client
+
+The `HyperionAdmin` client provides full control over the gateway management plane.
+
+```typescript
+import { HyperionAdmin } from '@hyperion-ai/sdk';
+
+const admin = new HyperionAdmin({ adminKey: "admin_secret" });
+
+// Create a new API key with a spend limit
+const key = await admin.keys.create({
+  name: "Internal Bot",
+  budgetLimitUsd: 50,
+  allowedModels: ["gpt-5.2-mini"]
+});
+
+// List all keys
+const keys = await admin.keys.list();
+```
+
+## Using with standard OpenAI SDK
+
+If you don't want to use the `HyperionClient` wrapper, you can manually pass Hyperion headers to the standard OpenAI client:
+
+```typescript
+import OpenAI from 'openai';
+
+const client = new OpenAI({ baseURL: "http://your-gateway:8080/v1" });
+
+const response = await client.chat.completions.create({
+  model: "gpt-5.2",
+  messages: [...],
+}, {
+  headers: { 'X-Cache-Bypass': 'true' }
+});
+```

package/dist/admin.d.ts

@@ -0,0 +1,121 @@
+import type { ApiKey, CreateKeyParams, Tenant, SetBudgetParams, InviteMemberParams, PricingUpsertParams } from './types';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+export interface HyperionAdminOptions {
+    /** Gateway base URL. Defaults to HYPERION_BASE_URL env var or http://localhost:8080 */
+    baseUrl?: string;
+    /** Admin API key. Defaults to HYPERION_ADMIN_KEY env var. */
+    adminKey?: string;
+}
+/**
+ * HyperionAdmin — programmatic management client for the Hyperion Gateway.
+ *
+ * Separate from HyperionClient (inference). Use this to manage keys,
+ * organizations, budgets, members, analytics, and pricing.
+ *
+ * Works isomorphically in Node.js, Edge (Cloudflare Workers, Vercel Edge),
+ * and browser environments since it uses the native `fetch` API.
+ *
+ * @example
+ * ```ts
+ * import { HyperionAdmin } from '@hyperion-ai/sdk';
+ *
+ * const admin = new HyperionAdmin({ adminKey: "admin_secret" });
+ *
+ * const key = await admin.keys.create({
+ *   name: "Production",
+ *   budgetLimitUsd: 100,
+ *   allowedModels: ["gpt-5.2-mini"],
+ * });
+ *
+ * const spend = await admin.analytics.timeseries({ period: "7d" });
+ * ```
+ */
+export declare class HyperionAdmin {
+    private readonly _baseUrl;
+    private readonly _adminKey;
+    readonly keys: KeysResource;
+    readonly tenants: TenantsResource;
+    readonly analytics: AnalyticsResource;
+    readonly members: MembersResource;
+    readonly pricing: PricingResource;
+    constructor(opts?: HyperionAdminOptions);
+    /** Get gateway health status. */
+    health(): Promise<{
+        status: string;
+        [k: string]: unknown;
+    }>;
+}
+type Requester = <T>(m: HttpMethod, path: string, body?: unknown, query?: Record<string, string>) => Promise<T>;
+declare class KeysResource {
+    private req;
+    constructor(req: Requester);
+    /** List all API keys for the current organization. */
+    list(): Promise<ApiKey[]>;
+    /**
+     * Create a new scoped API key.
+     *
+     * @example
+     * ```ts
+     * const key = await admin.keys.create({
+     *   name: "Production Bot",
+     *   budgetLimitUsd: 50,
+     *   allowedModels: ["gpt-5.2-mini", "claude-3-haiku-20240307"],
+     * });
+     * ```
+     */
+    create(params: CreateKeyParams): Promise<ApiKey>;
+    /** Update an existing API key's configuration. */
+    update(keyId: string, fields: Partial<CreateKeyParams>): Promise<ApiKey>;
+    /** Permanently delete an API key. */
+    delete(keyId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Rotate the secret value of an API key, immediately invalidating the old one. */
+    rotate(keyId: string): Promise<ApiKey>;
+}
+declare class TenantsResource {
+    private req;
+    constructor(req: Requester);
+    /** List all tenants visible to this admin key. */
+    list(): Promise<Tenant[]>;
+    /**
+     * Set or update a hard spend budget for a tenant.
+     *
+     * @example
+     * ```ts
+     * await admin.tenants.setBudget({ orgId: "org_123", limitUsd: 200, period: "monthly" });
+     * ```
+     */
+    setBudget(params: SetBudgetParams): Promise<unknown>;
+}
+declare class AnalyticsResource {
+    private req;
+    constructor(req: Requester);
+    /** Fetch request volume and cost timeseries. */
+    timeseries(params?: {
+        period?: string;
+        orgId?: string;
+    }): Promise<unknown>;
+    /** Fetch token usage and cost broken down by model. */
+    usageByModel(params?: {
+        orgId?: string;
+    }): Promise<unknown>;
+}
+declare class MembersResource {
+    private req;
+    constructor(req: Requester);
+    /** List all organization members. */
+    list(): Promise<unknown[]>;
+    /** Invite a new member to the organization by email. */
+    invite(params: InviteMemberParams): Promise<unknown>;
+}
+declare class PricingResource {
+    private req;
+    constructor(req: Requester);
+    /** List all model pricing records. */
+    list(): Promise<unknown[]>;
+    /** Insert or update pricing for a model (cost per 1k tokens, USD). */
+    upsert(params: PricingUpsertParams): Promise<unknown>;
+}
+export {};
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"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"}

package/dist/admin.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HyperionAdmin = void 0;
+async function request(baseUrl, adminKey, method, path, body, query) {
+    let url = `${baseUrl}${path}`;
+    if (query && Object.keys(query).length > 0) {
+        url += '?' + new URLSearchParams(query).toString();
+    }
+    const res = await fetch(url, {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            'X-Admin-Key': adminKey,
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => res.statusText);
+        throw new Error(`Hyperion Admin API error ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+/**
+ * HyperionAdmin — programmatic management client for the Hyperion Gateway.
+ *
+ * Separate from HyperionClient (inference). Use this to manage keys,
+ * organizations, budgets, members, analytics, and pricing.
+ *
+ * Works isomorphically in Node.js, Edge (Cloudflare Workers, Vercel Edge),
+ * and browser environments since it uses the native `fetch` API.
+ *
+ * @example
+ * ```ts
+ * import { HyperionAdmin } from '@hyperion-ai/sdk';
+ *
+ * const admin = new HyperionAdmin({ adminKey: "admin_secret" });
+ *
+ * const key = await admin.keys.create({
+ *   name: "Production",
+ *   budgetLimitUsd: 100,
+ *   allowedModels: ["gpt-5.2-mini"],
+ * });
+ *
+ * const spend = await admin.analytics.timeseries({ period: "7d" });
+ * ```
+ */
+class HyperionAdmin {
+    constructor(opts = {}) {
+        this._baseUrl = (opts.baseUrl ??
+            (typeof process !== 'undefined' ? process.env['HYPERION_BASE_URL'] : undefined) ??
+            'http://localhost:8080').replace(/\/+$/, '') + '/v1';
+        this._adminKey =
+            opts.adminKey ??
+                (typeof process !== 'undefined' ? process.env['HYPERION_ADMIN_KEY'] : undefined) ??
+                '';
+        const req = (method, path, body, query) => request(this._baseUrl, this._adminKey, method, path, body, query);
+        this.keys = new KeysResource(req);
+        this.tenants = new TenantsResource(req);
+        this.analytics = new AnalyticsResource(req);
+        this.members = new MembersResource(req);
+        this.pricing = new PricingResource(req);
+    }
+    /** Get gateway health status. */
+    async health() {
+        return request(this._baseUrl, this._adminKey, 'GET', '/admin/health');
+    }
+}
+exports.HyperionAdmin = HyperionAdmin;
+class KeysResource {
+    constructor(req) {
+        this.req = req;
+    }
+    /** List all API keys for the current organization. */
+    list() {
+        return this.req('GET', '/admin/keys');
+    }
+    /**
+     * Create a new scoped API key.
+     *
+     * @example
+     * ```ts
+     * const key = await admin.keys.create({
+     *   name: "Production Bot",
+     *   budgetLimitUsd: 50,
+     *   allowedModels: ["gpt-5.2-mini", "claude-3-haiku-20240307"],
+     * });
+     * ```
+     */
+    create(params) {
+        const body = { name: params.name };
+        if (params.budgetLimitUsd !== undefined)
+            body['budget_limit_usd'] = params.budgetLimitUsd;
+        if (params.allowedModels)
+            body['allowed_models'] = params.allowedModels;
+        if (params.rateLimitRpm !== undefined)
+            body['rate_limit_rpm'] = params.rateLimitRpm;
+        if (params.tags)
+            body['tags'] = params.tags;
+        if (params.orgId)
+            body['org_id'] = params.orgId;
+        return this.req('POST', '/admin/tenants/key', body);
+    }
+    /** Update an existing API key's configuration. */
+    update(keyId, fields) {
+        return this.req('PUT', `/admin/keys/${keyId}`, fields);
+    }
+    /** Permanently delete an API key. */
+    delete(keyId) {
+        return this.req('DELETE', `/admin/keys/${keyId}`);
+    }
+    /** Rotate the secret value of an API key, immediately invalidating the old one. */
+    rotate(keyId) {
+        return this.req('POST', `/admin/keys/${keyId}/rotate`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Resource: Tenants
+// ---------------------------------------------------------------------------
+class TenantsResource {
+    constructor(req) {
+        this.req = req;
+    }
+    /** List all tenants visible to this admin key. */
+    list() {
+        return this.req('GET', '/admin/tenants');
+    }
+    /**
+     * Set or update a hard spend budget for a tenant.
+     *
+     * @example
+     * ```ts
+     * await admin.tenants.setBudget({ orgId: "org_123", limitUsd: 200, period: "monthly" });
+     * ```
+     */
+    setBudget(params) {
+        return this.req('POST', '/admin/tenants/budget', {
+            org_id: params.orgId,
+            limit_usd: params.limitUsd,
+            period: params.period ?? 'monthly',
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Resource: Analytics
+// ---------------------------------------------------------------------------
+class AnalyticsResource {
+    constructor(req) {
+        this.req = req;
+    }
+    /** Fetch request volume and cost timeseries. */
+    timeseries(params) {
+        const query = {};
+        if (params?.period)
+            query['period'] = params.period;
+        if (params?.orgId)
+            query['org_id'] = params.orgId;
+        return this.req('GET', '/admin/timeseries', undefined, query);
+    }
+    /** Fetch token usage and cost broken down by model. */
+    usageByModel(params) {
+        const query = {};
+        if (params?.orgId)
+            query['org_id'] = params.orgId;
+        return this.req('GET', '/admin/usage-by-model', undefined, query);
+    }
+}
+// ---------------------------------------------------------------------------
+// Resource: Members
+// ---------------------------------------------------------------------------
+class MembersResource {
+    constructor(req) {
+        this.req = req;
+    }
+    /** List all organization members. */
+    list() {
+        return this.req('GET', '/admin/members');
+    }
+    /** Invite a new member to the organization by email. */
+    invite(params) {
+        return this.req('POST', '/admin/invites', {
+            email: params.email,
+            role: params.role ?? 'developer',
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Resource: Pricing
+// ---------------------------------------------------------------------------
+class PricingResource {
+    constructor(req) {
+        this.req = req;
+    }
+    /** List all model pricing records. */
+    list() {
+        return this.req('GET', '/admin/pricing/models');
+    }
+    /** Insert or update pricing for a model (cost per 1k tokens, USD). */
+    upsert(params) {
+        return this.req('POST', '/admin/pricing/models', {
+            model_id: params.modelId,
+            input_cost: params.inputCost,
+            output_cost: params.outputCost,
+        });
+    }
+}
+//# sourceMappingURL=admin.js.map

package/dist/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,60 @@
+import OpenAI from 'openai';
+import type { ClientOptions } from 'openai';
+import type { HyperionConfig, HyperionMeta, HyperionChatCompletion, HyperionCreateParams } from './types';
+export declare function configToHeaders(config: HyperionConfig): Record<string, string>;
+export declare function parseHyperionMeta(headers: Record<string, string>): HyperionMeta;
+export interface HyperionClientOptions extends Omit<ClientOptions, 'apiKey' | 'baseURL'> {
+    /** Hyperion API key. Defaults to `HYPERION_API_KEY` env var. */
+    apiKey?: string;
+    /** Gateway base URL. Defaults to `HYPERION_BASE_URL` env var or `http://localhost:8080/v1`. */
+    baseURL?: string;
+}
+/**
+ * HyperionClient — drop-in replacement for `openai.OpenAI`.
+ *
+ * Extends the official OpenAI SDK and adds:
+ * - `hyperion` config block on `chat.completions.create()` → translated to X-* headers
+ * - `.hyperion` (HyperionMeta) on every response with cache status and similarity score
+ *
+ * All other OpenAI features (streaming, embeddings, images, tool calls, etc.)
+ * are inherited unchanged.
+ *
+ * @example
+ * ```ts
+ * import { HyperionClient } from '@hyperion-ai/sdk';
+ *
+ * const client = new HyperionClient();
+ *
+ * const res = await client.chat.completions.create({
+ *   model: "openai/gpt-5.2",
+ *   messages: [{ role: "user", content: "Hello" }],
+ *   hyperion: { tags: ["prod"], bypassCache: false },
+ * });
+ *
+ * console.log(res.hyperion.cacheStatus); // "HIT" | "MISS"
+ * console.log(res.hyperion.isHit);       // boolean
+ * ```
+ */
+export declare class HyperionClient extends OpenAI {
+    chat: {
+        completions: {
+            create(params: HyperionCreateParams, options?: {
+                headers?: Record<string, string>;
+                [key: string]: unknown;
+            }): Promise<HyperionChatCompletion>;
+        };
+    } & OpenAI['chat'];
+    constructor(opts?: HyperionClientOptions);
+    /**
+     * Patches `this.chat.completions.create` at runtime to:
+     * 1. Extract the `hyperion` config block from params
+     * 2. Map it to X-* request headers
+     * 3. Call the original create method with those headers
+     * 4. Parse response headers and attach `.hyperion` to the result
+     *
+     * We patch at runtime (using `as any`) rather than overriding the full
+     * Completions class, so all other `completions.*` methods remain intact.
+     */
+    private _patchCompletions;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAMjB,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe9E;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,YAAY,CAwB/E;AAMD,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC;IACtF,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,cAAe,SAAQ,MAAM;IAChC,IAAI,EAAE;QACZ,WAAW,EAAE;YACX,MAAM,CACJ,MAAM,EAAE,oBAAoB,EAC5B,OAAO,CAAC,EAAE;gBAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;aAAE,GACrE,OAAO,CAAC,sBAAsB,CAAC,CAAC;SACpC,CAAC;KACH,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;gBAEP,IAAI,GAAE,qBAA0B;IAc5C;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;CA8B1B"}

package/dist/client.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HyperionClient = void 0;
+exports.configToHeaders = configToHeaders;
+exports.parseHyperionMeta = parseHyperionMeta;
+const openai_1 = __importDefault(require("openai"));
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+function configToHeaders(config) {
+    const headers = {};
+    if (config.bypassCache)
+        headers['X-Cache-Bypass'] = 'true';
+    if (config.cacheTtl !== undefined)
+        headers['X-Cache-TTL'] = String(config.cacheTtl);
+    if (config.similarityThreshold !== undefined)
+        headers['X-Similarity-Threshold'] = config.similarityThreshold.toFixed(4);
+    if (config.cacheToolCalls === false)
+        headers['X-Cache-Tool-Calls'] = 'false';
+    if (config.routeIntent)
+        headers['X-Route-Intent'] = config.routeIntent;
+    if (config.forceProvider)
+        headers['X-Force-Provider'] = config.forceProvider;
+    if (config.fallbacks?.length)
+        headers['X-Fallbacks'] = config.fallbacks.join(',');
+    if (config.tags?.length)
+        headers['X-Tags'] = config.tags.join(',');
+    if (config.teamId)
+        headers['X-Team-ID'] = config.teamId;
+    return headers;
+}
+function parseHyperionMeta(headers) {
+    const cacheStatus = headers['x-cache-status'] ?? 'MISS';
+    const rawCacheType = headers['x-cache-type'];
+    // Gateway sends 'L1_EXACT' or 'L2_SEMANTIC'
+    let cacheType;
+    if (rawCacheType === 'L1_EXACT')
+        cacheType = 'L1_EXACT';
+    else if (rawCacheType === 'L2_SEMANTIC')
+        cacheType = 'L2_SEMANTIC';
+    else
+        cacheType = undefined;
+    const scoreRaw = headers['x-similarity-score'];
+    const similarityScore = scoreRaw ? parseFloat(scoreRaw) : undefined;
+    return {
+        cacheStatus,
+        cacheType,
+        similarityScore,
+        get isHit() {
+            return cacheStatus === 'HIT';
+        },
+        get formattedSimilarityScore() {
+            return similarityScore !== undefined ? similarityScore.toFixed(4) : 'N/A';
+        },
+    };
+}
+/**
+ * HyperionClient — drop-in replacement for `openai.OpenAI`.
+ *
+ * Extends the official OpenAI SDK and adds:
+ * - `hyperion` config block on `chat.completions.create()` → translated to X-* headers
+ * - `.hyperion` (HyperionMeta) on every response with cache status and similarity score
+ *
+ * All other OpenAI features (streaming, embeddings, images, tool calls, etc.)
+ * are inherited unchanged.
+ *
+ * @example
+ * ```ts
+ * import { HyperionClient } from '@hyperion-ai/sdk';
+ *
+ * const client = new HyperionClient();
+ *
+ * const res = await client.chat.completions.create({
+ *   model: "openai/gpt-5.2",
+ *   messages: [{ role: "user", content: "Hello" }],
+ *   hyperion: { tags: ["prod"], bypassCache: false },
+ * });
+ *
+ * console.log(res.hyperion.cacheStatus); // "HIT" | "MISS"
+ * console.log(res.hyperion.isHit);       // boolean
+ * ```
+ */
+class HyperionClient extends openai_1.default {
+    constructor(opts = {}) {
+        const { apiKey, baseURL, ...rest } = opts;
+        super({
+            ...rest,
+            apiKey: apiKey ?? process.env['HYPERION_API_KEY'] ?? 'sk-hyperion',
+            baseURL: baseURL ??
+                process.env['HYPERION_BASE_URL'] ??
+                'http://localhost:8080/v1',
+        });
+        this._patchCompletions();
+    }
+    /**
+     * Patches `this.chat.completions.create` at runtime to:
+     * 1. Extract the `hyperion` config block from params
+     * 2. Map it to X-* request headers
+     * 3. Call the original create method with those headers
+     * 4. Parse response headers and attach `.hyperion` to the result
+     *
+     * We patch at runtime (using `as any`) rather than overriding the full
+     * Completions class, so all other `completions.*` methods remain intact.
+     */
+    _patchCompletions() {
+        // Cast to parent type to retain .withResponse() before we overwrite .create
+        const completions = this.chat.completions;
+        const originalCreate = completions.create.bind(completions);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        completions.create = async (params, options) => {
+            const { hyperion, ...rest } = params;
+            const hyperionHeaders = hyperion ? configToHeaders(hyperion) : {};
+            const mergedOptions = {
+                ...options,
+                headers: { ...(options?.headers ?? {}), ...hyperionHeaders },
+            };
+            const { data, response } = await originalCreate(rest, mergedOptions).withResponse();
+            const rawHeaders = {};
+            response.headers.forEach((value, key) => {
+                rawHeaders[key] = value;
+            });
+            const enriched = data;
+            enriched.hyperion = parseHyperionMeta(rawHeaders);
+            return enriched;
+        };
+    }
+}
+exports.HyperionClient = HyperionClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/demo.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/demo.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_1 = require("./client");
+async function main() {
+    // Pass Admin API Key (matches docker-compose)
+    const client = new client_1.HyperionClient('http://127.0.0.1:8080', undefined, 'hyperion-admin-secret-123');
+    try {
+        // 1. Chat Completion
+        console.log("Testing Chat Completion (Explicit Routing)...");
+        const completion = await client.chat.completions.create({
+            model: 'openai/gpt-4.1-nano', // Explicit provider/model
+            messages: [{ role: 'user', content: 'What is the capital of France?' }],
+            max_tokens: 50
+        });
+        console.log("Chat Response:", JSON.stringify(completion, null, 2));
+        // 2. Admin Stats
+        console.log("\nTesting Admin Stats...");
+        const stats = await client.admin.getStats();
+        console.log("Stats:", JSON.stringify(stats, null, 2));
+        // 3. Cache Keys
+        console.log("\nTesting Cache List...");
+        const keys = await client.cache.listKeys();
+        console.log("Cache Keys:", JSON.stringify(keys, null, 2));
+    }
+    catch (error) {
+        console.error("Error:", error);
+    }
+}
+main();

package/dist/demo_tenant_auth.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/demo_tenant_auth.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_1 = require("./client");
+const axios_1 = __importDefault(require("axios"));
+async function main() {
+    const adminClient = new client_1.HyperionClient('http://127.0.0.1:8080', undefined, 'hyperion-admin-secret-123');
+    console.log("1. Generating API Key for 'tenant-A'...");
+    try {
+        // Direct call to admin endpoint since SDK isn't updated for this specific method yet
+        const resp = await axios_1.default.post('http://127.0.0.1:8080/v1/admin/tenants/key', {
+            tenant_id: 'tenant-A'
+        }, {
+            headers: { 'X-Admin-Key': 'hyperion-admin-secret-123' }
+        });
+        const apiKey = resp.data.api_key;
+        console.log("Generated Key:", apiKey);
+        console.log("1.5 Setting Budget for 'tenant-A'...");
+        await axios_1.default.post('http://127.0.0.1:8080/v1/admin/tenants/budget', {
+            tenant_id: 'tenant-A',
+            limit: 10.0
+        }, {
+            headers: { 'X-Admin-Key': 'hyperion-admin-secret-123' }
+        });
+        console.log("\n2. Testing Chat with New Key...");
+        const client = new client_1.HyperionClient('http://127.0.0.1:8080', apiKey);
+        const completion = await client.chat.completions.create({
+            model: 'openai/gpt-4.1-mini',
+            messages: [{ role: 'user', content: 'Hello Tenant A!' }],
+            max_tokens: 10
+        });
+        console.log("Success! Response:", completion.choices[0].message.content);
+        console.log("\n3. Testing Unauthorized Access...");
+        const badClient = new client_1.HyperionClient('http://127.0.0.1:8080', 'invalid-key');
+        try {
+            await badClient.chat.completions.create({
+                model: 'openai/gpt-4.1-mini',
+                messages: [{ role: 'user', content: 'Intruder!' }]
+            });
+        }
+        catch (e) {
+            console.log("Caught Expected Error:", e.response?.status, e.response?.statusText);
+        }
+    }
+    catch (error) {
+        console.error("Test Failed:", error);
+    }
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { HyperionClient } from './client';
+export type { HyperionClientOptions } from './client';
+export { HyperionAdmin } from './admin';
+export type { HyperionAdminOptions } from './admin';
+export type { HyperionConfig, HyperionMeta, HyperionChatCompletion, HyperionCreateParams, CacheStatus, CacheType, ApiKey, CreateKeyParams, Tenant, SetBudgetParams, InviteMemberParams, PricingUpsertParams, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,YAAY,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,YAAY,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACpD,YAAY,EACV,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,WAAW,EACX,SAAS,EACT,MAAM,EACN,eAAe,EACf,MAAM,EACN,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HyperionAdmin = exports.HyperionClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "HyperionClient", { enumerable: true, get: function () { return client_1.HyperionClient; } });
+var admin_1 = require("./admin");
+Object.defineProperty(exports, "HyperionAdmin", { enumerable: true, get: function () { return admin_1.HyperionAdmin; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAA0C;AAAjC,wGAAA,cAAc,OAAA;AAEvB,iCAAwC;AAA/B,sGAAA,aAAa,OAAA"}

package/dist/resources/admin.d.ts

@@ -0,0 +1,8 @@
+import { AxiosInstance } from 'axios';
+import { SystemStats, HealthResponse } from '../types';
+export declare class AdminResource {
+    private client;
+    constructor(client: AxiosInstance);
+    getStats(): Promise<SystemStats>;
+    getHealth(): Promise<HealthResponse>;
+}

package/dist/resources/admin.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminResource = void 0;
+class AdminResource {
+    constructor(client) {
+        this.client = client;
+    }
+    async getStats() {
+        const response = await this.client.get('/admin/stats');
+        return response.data;
+    }
+    async getHealth() {
+        const response = await this.client.get('/admin/health');
+        return response.data;
+    }
+}
+exports.AdminResource = AdminResource;

package/dist/resources/cache.d.ts

@@ -0,0 +1,11 @@
+import { AxiosInstance } from 'axios';
+import { CacheKeyList, CacheEntry, WarmingRequest } from '../types';
+export declare class CacheResource {
+    private client;
+    constructor(client: AxiosInstance);
+    listKeys(pattern?: string, limit?: number): Promise<CacheKeyList>;
+    inspect(key: string): Promise<CacheEntry>;
+    flush(): Promise<void>;
+    warm(req: WarmingRequest): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/resources/cache.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheResource = void 0;
+class CacheResource {
+    constructor(client) {
+        this.client = client;
+    }
+    async listKeys(pattern = '*', limit = 50) {
+        const response = await this.client.get('/cache/keys', {
+            params: { pattern, limit }
+        });
+        return response.data;
+    }
+    async inspect(key) {
+        const response = await this.client.get(`/cache/inspect/${encodeURIComponent(key)}`);
+        return response.data;
+    }
+    async flush() {
+        await this.client.post('/cache/flush');
+    }
+    async warm(req) {
+        await this.client.post('/cache/warm', req);
+    }
+    async delete(key) {
+        await this.client.delete(`/cache/keys/${encodeURIComponent(key)}`);
+    }
+}
+exports.CacheResource = CacheResource;

package/dist/resources/chat.d.ts

@@ -0,0 +1,9 @@
+import { AxiosInstance } from 'axios';
+import { ChatCompletionRequest, ChatCompletionResponse } from '../types';
+export declare class ChatResource {
+    private client;
+    constructor(client: AxiosInstance);
+    completions: {
+        create: (req: ChatCompletionRequest) => Promise<ChatCompletionResponse>;
+    };
+}

package/dist/resources/chat.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatResource = void 0;
+class ChatResource {
+    constructor(client) {
+        this.client = client;
+        this.completions = {
+            create: async (req) => {
+                const response = await this.client.post('/chat/completions', req);
+                return response.data;
+            }
+        };
+    }
+}
+exports.ChatResource = ChatResource;

package/dist/resources/embeddings.d.ts

@@ -0,0 +1,7 @@
+import { AxiosInstance } from 'axios';
+import { EmbeddingRequest, EmbeddingResponse } from '../types';
+export declare class EmbeddingsResource {
+    private client;
+    constructor(client: AxiosInstance);
+    create: (req: EmbeddingRequest) => Promise<EmbeddingResponse>;
+}

package/dist/resources/embeddings.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmbeddingsResource = void 0;
+class EmbeddingsResource {
+    constructor(client) {
+        this.client = client;
+        this.create = async (req) => {
+            const response = await this.client.post('/embeddings', req);
+            return response.data;
+        };
+    }
+}
+exports.EmbeddingsResource = EmbeddingsResource;

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+import type { ChatCompletion, ChatCompletionCreateParams } from 'openai/resources/chat/completions';
+/**
+ * Hyperion-specific configuration for a single inference request.
+ * Pass as the `hyperion` property on any `client.chat.completions.create()` call.
+ *
+ * @example
+ * ```ts
+ * const res = await client.chat.completions.create({
+ *   model: "openai/gpt-5.2",
+ *   messages: [{ role: "user", content: "Hello" }],
+ *   hyperion: {
+ *     bypassCache: true,
+ *     tags: ["prod", "onboarding"],
+ *   }
+ * });
+ * ```
+ */
+export interface HyperionConfig {
+    /** Skip the cache entirely for this request. Forces a live LLM call. */
+    bypassCache?: boolean;
+    /** Override the cache TTL in seconds for the stored response. */
+    cacheTtl?: number;
+    /**
+     * Override the semantic similarity threshold (0.0–1.0).
+     * Higher = stricter match required before serving from cache.
+     */
+    similarityThreshold?: number;
+    /**
+     * Whether to cache the model's tool_call decision response.
+     * Set to `false` to prevent caching tool call decisions.
+     * Defaults to `true` (gateway-configured default).
+     */
+    cacheToolCalls?: boolean;
+    /**
+     * Hint to the routing engine.
+     * Examples: "cheap_fast", "balanced", "high_reasoning", "code_generation".
+     */
+    routeIntent?: string;
+    /** Force a specific provider for this request (e.g., "anthropic", "openai", "google"). */
+    forceProvider?: string;
+    /**
+     * Ordered list of fallback models to try if the primary model fails.
+     * @example ["claude-3-5-sonnet", "gpt-5.2-mini"]
+     */
+    fallbacks?: string[];
+    /** Arbitrary string tags attached to this request for dashboard filtering. */
+    tags?: string[];
+    /** Team or downstream tenant ID for usage attribution in analytics. */
+    teamId?: string;
+}
+export type CacheStatus = 'HIT' | 'MISS' | 'BYPASS' | 'BYPASS-TOOL-RESULT' | 'BYPASS-TOOL-NOCACHE';
+export type CacheType = 'L1_EXACT' | 'L2_SEMANTIC';
+/**
+ * Metadata extracted from Hyperion gateway response headers.
+ * Attached as `.hyperion` on every response returned by `HyperionClient`.
+ */
+export interface HyperionMeta {
+    /** Cache result for this request. */
+    cacheStatus: CacheStatus | string;
+    /** Cache layer that served the hit. Undefined on MISS or BYPASS. */
+    cacheType?: CacheType;
+    /** Cosine similarity score of a semantic cache match. Undefined on exact hit or miss. */
+    similarityScore?: number;
+    /** Convenience flag: true if this response was served from cache. */
+    readonly isHit: boolean;
+    /** Similarity score formatted to 4 decimal places, or 'N/A' if not applicable. */
+    readonly formattedSimilarityScore: string;
+}
+/**
+ * `ChatCompletion` enriched with a `.hyperion` metadata object.
+ */
+export interface HyperionChatCompletion extends ChatCompletion {
+    hyperion: HyperionMeta;
+}
+/**
+ * Extended `create` params that accept a `hyperion` config block.
+ */
+export type HyperionCreateParams = ChatCompletionCreateParams & {
+    hyperion?: HyperionConfig;
+};
+export interface ApiKey {
+    id: string;
+    name: string;
+    key_preview: string;
+    budget_limit_usd?: number;
+    allowed_models?: string[];
+    rate_limit_rpm?: number;
+    created_at: string;
+}
+export interface CreateKeyParams {
+    name: string;
+    budgetLimitUsd?: number;
+    allowedModels?: string[];
+    rateLimitRpm?: number;
+    tags?: string[];
+    orgId?: string;
+}
+export interface Tenant {
+    id: string;
+    name: string;
+    slug: string;
+    created_at: string;
+}
+export interface SetBudgetParams {
+    orgId: string;
+    limitUsd: number;
+    period?: 'daily' | 'monthly';
+}
+export interface InviteMemberParams {
+    email: string;
+    role?: 'owner' | 'admin' | 'developer' | 'viewer';
+}
+export interface PricingUpsertParams {
+    modelId: string;
+    inputCost: number;
+    outputCost: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAuB,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAOzH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAG7B,wEAAwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAIzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAIrB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,oBAAoB,GAAG,qBAAqB,CAAC;AACnG,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,WAAW,EAAE,WAAW,GAAG,MAAM,CAAC;IAElC,oEAAoE;IACpE,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB,kFAAkF;IAClF,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;CAC3C;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,GAAG;IAC9D,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,CAAC;AAMF,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;CACnD;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "@hyperion-ai/sdk",
+    "version": "0.1.0",
+    "description": "The official TypeScript/Node.js SDK for the Hyperion AI Gateway",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "require": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "openai": "^6.22.0"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "typescript": "^5.0.0",
+        "vitest": "^1.0.0"
+    },
+    "keywords": [
+        "hyperion",
+        "ai",
+        "gateway",
+        "openai",
+        "llm",
+        "caching",
+        "low-latency",
+        "high-performance"
+    ],
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/hyperion-hq/hyperion.git",
+        "directory": "sdk/typescript"
+    },
+    "homepage": "https://github.com/hyperion-hq/hyperion/tree/main/sdk/typescript",
+    "bugs": {
+        "url": "https://github.com/hyperion-hq/hyperion/issues"
+    }
+}