@modelrelay/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,449 @@
+declare const SDK_VERSION: string;
+declare const DEFAULT_BASE_URL = "https://api.modelrelay.ai/api/v1";
+declare const STAGING_BASE_URL = "https://api-stg.modelrelay.ai/api/v1";
+declare const SANDBOX_BASE_URL = "https://api.sandbox.modelrelay.ai/api/v1";
+declare const DEFAULT_CLIENT_HEADER: string;
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+interface ModelRelayOptions {
+    /**
+     * API key (secret or publishable). Publishable keys are required for frontend token exchange.
+     */
+    key?: string;
+    /**
+     * Bearer token to call the API directly (server or frontend token).
+     */
+    token?: string;
+    /**
+     * Optional environment preset; overridden by `baseUrl` when provided.
+     */
+    environment?: Environment;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /**
+     * Default end-user metadata used when exchanging publishable keys for frontend tokens.
+     */
+    endUser?: FrontendIdentity;
+    /**
+     * Optional client header override for telemetry.
+     */
+    clientHeader?: string;
+    /**
+     * Default request timeout in milliseconds (non-streaming). Set to 0 to disable.
+     */
+    timeoutMs?: number;
+    /**
+     * Retry configuration applied to all requests (can be overridden per call). Set to `false` to disable retries.
+     */
+    retry?: RetryConfig | false;
+    /**
+     * Default HTTP headers applied to every request.
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Default metadata merged into every chat completion request.
+     */
+    defaultMetadata?: Record<string, string>;
+}
+type Environment = "production" | "staging" | "sandbox";
+interface FrontendIdentity {
+    id: string;
+    deviceId?: string;
+    ttlSeconds?: number;
+}
+interface FrontendTokenRequest {
+    publishableKey?: string;
+    userId: string;
+    deviceId?: string;
+    ttlSeconds?: number;
+}
+interface FrontendToken {
+    token: string;
+    expiresAt?: Date;
+    expiresIn?: number;
+    tokenType?: string;
+    keyId?: string;
+    sessionId?: string;
+    tokenScope?: string[];
+    tokenSource?: string;
+    /**
+     * The end-user identifier used when issuing the token. Added client-side for caching.
+     */
+    endUserId?: string;
+    /**
+     * Publishable key used for issuance. Added client-side for caching.
+     */
+    publishableKey?: string;
+    /**
+     * Device identifier used when issuing the token. Added client-side for caching.
+     */
+    deviceId?: string;
+}
+interface CheckoutRequest {
+    endUserId: string;
+    deviceId?: string;
+    planId?: string;
+    plan?: string;
+    successUrl: string;
+    cancelUrl: string;
+}
+interface CheckoutSession {
+    id: string;
+    plan: string;
+    status: string;
+    url: string;
+    expiresAt?: Date;
+    completedAt?: Date;
+}
+interface EndUserRef {
+    id: string;
+    externalId: string;
+    ownerId: string;
+}
+interface CheckoutResponse {
+    endUser: EndUserRef;
+    session: CheckoutSession;
+}
+interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+interface ChatMessage {
+    role: string;
+    content: string;
+}
+interface ChatCompletionCreateParams {
+    model: string;
+    messages: ChatMessage[];
+    provider?: string;
+    maxTokens?: number;
+    temperature?: number;
+    metadata?: Record<string, string>;
+    stop?: string[];
+    stopSequences?: string[];
+    /**
+     * When using publishable keys, an end-user id is required to mint a frontend token.
+     */
+    endUserId?: string;
+    /**
+     * Opt out of SSE streaming and request a blocking JSON response.
+     */
+    stream?: boolean;
+    /**
+     * Optional request id to set on the call. If omitted, the server will generate one.
+     */
+    requestId?: string;
+}
+interface ChatCompletionResponse {
+    id: string;
+    provider: string;
+    content: string[];
+    stopReason?: string;
+    model: string;
+    usage: Usage;
+    requestId?: string;
+}
+interface FieldError {
+    field?: string;
+    message: string;
+}
+interface RetryConfig {
+    maxAttempts?: number;
+    baseBackoffMs?: number;
+    maxBackoffMs?: number;
+    retryPost?: boolean;
+}
+type ChatEventType = "message_start" | "message_delta" | "message_stop" | "ping" | "custom";
+interface MessageStartData {
+    responseId?: string;
+    model?: string;
+    message?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface MessageDeltaData {
+    delta?: string | {
+        text?: string;
+        [key: string]: unknown;
+    };
+    responseId?: string;
+    model?: string;
+    [key: string]: unknown;
+}
+interface MessageStopData {
+    stopReason?: string;
+    usage?: Usage;
+    responseId?: string;
+    model?: string;
+    [key: string]: unknown;
+}
+interface ChatCompletionEvent<T = unknown> {
+    type: ChatEventType;
+    event: string;
+    data?: T;
+    textDelta?: string;
+    responseId?: string;
+    model?: string;
+    stopReason?: string;
+    usage?: Usage;
+    requestId?: string;
+    raw: string;
+}
+interface APIFrontendToken {
+    token: string;
+    expires_at?: string;
+    expiresAt?: string;
+    expires_in?: number;
+    expiresIn?: number;
+    token_type?: string;
+    tokenType?: string;
+    key_id?: string;
+    keyId?: string;
+    session_id?: string;
+    sessionId?: string;
+    token_scope?: string[];
+    tokenScope?: string[];
+    token_source?: string;
+    tokenSource?: string;
+}
+interface APIEndUserRef {
+    id: string;
+    external_id: string;
+    owner_id: string;
+}
+interface APICheckoutSession {
+    id: string;
+    plan: string;
+    status: string;
+    url: string;
+    expires_at?: string;
+    completed_at?: string;
+}
+interface APICheckoutResponse {
+    end_user?: APIEndUserRef;
+    session?: APICheckoutSession;
+}
+interface APIChatUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+interface APIChatResponse {
+    id?: string;
+    provider?: string;
+    content?: string | string[];
+    stop_reason?: string;
+    stopReason?: string;
+    model?: string;
+    usage?: APIChatUsage;
+    response_id?: string;
+    responseId?: string;
+    message?: {
+        id?: string;
+        model?: string;
+    };
+    delta?: string | {
+        text?: string;
+        content?: string;
+    };
+    type?: string;
+    event?: string;
+}
+interface APIKey {
+    id: string;
+    label: string;
+    kind: string;
+    createdAt: Date;
+    expiresAt?: Date;
+    lastUsedAt?: Date;
+    redactedKey: string;
+    secretKey?: string;
+}
+interface APIKeyCreateRequest {
+    label: string;
+    expiresAt?: Date;
+    kind?: string;
+}
+
+interface RequestOptions {
+    method?: string;
+    headers?: HeadersInit;
+    body?: unknown;
+    signal?: AbortSignal;
+    apiKey?: string;
+    accessToken?: string;
+    accept?: string;
+    /**
+     * When true, the caller is responsible for handling non-2xx responses.
+     */
+    raw?: boolean;
+    timeoutMs?: number;
+    /**
+     * Override retry behavior for this request. Set to `false` to disable retries.
+     */
+    retry?: RetryConfig | false;
+    /**
+     * When false, skip the default client timeout (useful for streaming).
+     */
+    useDefaultTimeout?: boolean;
+}
+declare class HTTPClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly accessToken?;
+    private readonly fetchImpl?;
+    private readonly clientHeader?;
+    private readonly defaultTimeoutMs;
+    private readonly retry?;
+    private readonly defaultHeaders;
+    constructor(cfg: {
+        baseUrl?: string;
+        apiKey?: string;
+        accessToken?: string;
+        fetchImpl?: typeof fetch;
+        clientHeader?: string;
+        timeoutMs?: number;
+        retry?: RetryConfig | false;
+        defaultHeaders?: Record<string, string>;
+        environment?: Environment;
+    });
+    request(path: string, options?: RequestOptions): Promise<Response>;
+    json<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+
+interface AuthConfig {
+    apiKey?: string;
+    accessToken?: string;
+    endUser?: FrontendIdentity;
+}
+interface AuthHeaders {
+    apiKey?: string;
+    accessToken?: string;
+}
+declare class AuthClient {
+    private readonly http;
+    private readonly apiKey?;
+    private readonly accessToken?;
+    private readonly endUser?;
+    private cachedFrontend;
+    constructor(http: HTTPClient, cfg: AuthConfig);
+    /**
+     * Exchange a publishable key for a short-lived frontend token.
+     * Tokens are cached until they are close to expiry.
+     */
+    frontendToken(request?: Partial<FrontendTokenRequest>): Promise<FrontendToken>;
+    /**
+     * Determine the correct auth headers for chat completions.
+     * Publishable keys are automatically exchanged for frontend tokens.
+     */
+    authForChat(endUserId?: string, overrides?: Partial<FrontendIdentity>): Promise<AuthHeaders>;
+    /**
+     * Billing calls accept either bearer tokens or API keys (including publishable keys).
+     */
+    authForBilling(): AuthHeaders;
+}
+declare function isPublishableKey(value?: string | null): boolean;
+
+declare class ApiKeysClient {
+    private readonly http;
+    constructor(http: HTTPClient);
+    list(): Promise<APIKey[]>;
+    create(req: APIKeyCreateRequest): Promise<APIKey>;
+    delete(id: string): Promise<void>;
+}
+
+declare class BillingClient {
+    private readonly http;
+    private readonly auth;
+    constructor(http: HTTPClient, auth: AuthClient);
+    /**
+     * Initiate a Stripe Checkout session for an end user.
+     */
+    checkout(params: CheckoutRequest): Promise<CheckoutResponse>;
+}
+
+interface ChatRequestOptions {
+    /**
+     * Abort the HTTP request and stream consumption.
+     */
+    signal?: AbortSignal;
+    /**
+     * Override the Accept header to switch between streaming and blocking responses.
+     */
+    stream?: boolean;
+    /**
+     * Optional request id header. `params.requestId` takes precedence if provided.
+     */
+    requestId?: string;
+    /**
+     * Additional HTTP headers for this request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Additional metadata merged into the request body.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Override the per-request timeout in milliseconds (set to 0 to disable).
+     */
+    timeoutMs?: number;
+    /**
+     * Override retry behavior for this call. Set to `false` to disable retries.
+     */
+    retry?: RetryConfig | false;
+}
+declare class ChatClient {
+    readonly completions: ChatCompletionsClient;
+    constructor(http: HTTPClient, auth: AuthClient, cfg?: {
+        defaultMetadata?: Record<string, string>;
+    });
+}
+declare class ChatCompletionsClient {
+    private readonly http;
+    private readonly auth;
+    private readonly defaultMetadata?;
+    constructor(http: HTTPClient, auth: AuthClient, defaultMetadata?: Record<string, string>);
+    create(params: ChatCompletionCreateParams & {
+        stream: false;
+    }, options?: ChatRequestOptions): Promise<ChatCompletionResponse>;
+    create(params: ChatCompletionCreateParams, options: ChatRequestOptions & {
+        stream: false;
+    }): Promise<ChatCompletionResponse>;
+    create(params: ChatCompletionCreateParams, options?: ChatRequestOptions): Promise<ChatCompletionsStream>;
+}
+declare class ChatCompletionsStream implements AsyncIterable<ChatCompletionEvent> {
+    private readonly response;
+    private readonly requestId?;
+    private closed;
+    constructor(response: Response, requestId?: string);
+    cancel(reason?: unknown): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterator<ChatCompletionEvent>;
+}
+
+declare class ModelRelayError extends Error {
+    status: number;
+    code?: string;
+    requestId?: string;
+    fields?: FieldError[];
+    data?: unknown;
+    constructor(message: string, opts: {
+        status: number;
+        code?: string;
+        requestId?: string;
+        fields?: FieldError[];
+        data?: unknown;
+    });
+}
+
+declare class ModelRelay {
+    readonly billing: BillingClient;
+    readonly chat: ChatClient;
+    readonly auth: AuthClient;
+    readonly apiKeys: ApiKeysClient;
+    readonly baseUrl: string;
+    constructor(options: ModelRelayOptions);
+}
+
+export { type APIChatResponse, type APIChatUsage, type APICheckoutResponse, type APICheckoutSession, type APIEndUserRef, type APIFrontendToken, type APIKey, type APIKeyCreateRequest, ApiKeysClient, AuthClient, BillingClient, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutRequest, type CheckoutResponse, type CheckoutSession, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_REQUEST_TIMEOUT_MS, type EndUserRef, type Environment, type FieldError, type FrontendIdentity, type FrontendToken, type FrontendTokenRequest, type MessageDeltaData, type MessageStartData, type MessageStopData, ModelRelay, ModelRelayError, type ModelRelayOptions, type RetryConfig, SANDBOX_BASE_URL, SDK_VERSION, STAGING_BASE_URL, type Usage, isPublishableKey };