@onlist/sdk 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,21 +1,390 @@
 import OpenAI, { ClientOptions } from 'openai';
 
+/** Shared options for the REST resources (marketplace and account). */
+interface RequestOptions {
+    apiKey?: string | null;
+    baseURL: string;
+    timeout?: number;
+    /** Maximum retry attempts for failed requests. Defaults to 2. */
+    maxRetries?: number;
+}
+
+/**
+ * Response types for the account API (`/api/v1/*`).
+ *
+ * Field names mirror the wire format one-for-one, which is OpenRouter's, so
+ * code written against OpenRouter's responses reads the same fields here.
+ */
+/**
+ * The deprecated per-key rate limit descriptor on {@link CurrentKey}.
+ *
+ * Onlist has no per-key request-rate limit — only spend budgets — so
+ * `requests` is always `-1`. Do not use it to drive client-side throttling.
+ */
+interface RateLimit {
+    requests: number;
+    interval: string;
+    note: string;
+}
+/**
+ * An inference key (`sk-...`) as returned by the `apiKeys` resource.
+ *
+ * `limit`, `limit_remaining` and `limit_reset` move together: either all
+ * three are set, or all three are `null` (no spend budget). Amounts are USD.
+ * `created_at` / `expires_at` are RFC 3339 UTC strings, or `null` for
+ * "never".
+ */
+interface APIKey {
+    hash: string;
+    name: string;
+    label: string;
+    disabled: boolean;
+    limit: number | null;
+    limit_remaining: number | null;
+    limit_reset: string | null;
+    include_byok_in_limit: boolean;
+    usage: number;
+    usage_daily: number;
+    usage_weekly: number;
+    usage_monthly: number;
+    byok_usage: number;
+    byok_usage_daily: number;
+    byok_usage_weekly: number;
+    byok_usage_monthly: number;
+    created_at: string | null;
+    updated_at: string | null;
+    expires_at: string | null;
+    external_user: string | null;
+    creator_user_id: string | null;
+    workspace_id: string | null;
+}
+/**
+ * The credential used for the request, from `apiKeys.current()`.
+ *
+ * Every field is optional because the endpoint answers for both credential
+ * types and they carry different information: a management key has no usage
+ * and no budget (reporting `0` would read as "an inference key that has
+ * never spent"), so those fields are simply absent from its projection.
+ * Branch on `is_management_key`.
+ */
+interface CurrentKey extends Partial<APIKey> {
+    is_free_tier?: boolean;
+    is_management_key?: boolean;
+    is_provisioning_key?: boolean;
+    rate_limit?: RateLimit;
+}
+/**
+ * The result of `apiKeys.create()`.
+ *
+ * `key` is the full secret in plaintext and is returned **only here, only
+ * once** — the server keeps a hash. Store it before discarding this object.
+ * `data` is the same key object later reads return.
+ */
+interface CreatedKey {
+    key: string;
+    data: APIKey;
+}
+/** Parameters for `apiKeys.create()`. */
+interface CreateKeyParams {
+    /** Spend budget in USD. Omit for no budget. */
+    limit?: number;
+    /** `"daily"`, `"weekly"`, or omitted for a lifetime total. `"monthly"` is rejected. */
+    limit_reset?: string;
+    /** Expiry as a Unix timestamp. Omit to never expire. */
+    expires_at?: number;
+}
+/**
+ * Patch for `apiKeys.update()`.
+ *
+ * Three states: an omitted (or `undefined`) field is left unchanged, and an
+ * explicit `null` clears the value. `name` and `disabled` therefore accept
+ * no `null` — the server reads `{"name": null}` as an empty name (400) and
+ * `{"disabled": null}` as `false`, which would silently re-enable a key you
+ * only meant to leave alone.
+ */
+interface UpdateKeyParams {
+    name?: string;
+    disabled?: boolean;
+    limit?: number | null;
+    limit_reset?: string | null;
+    expires_at?: number | null;
+}
+/** Parameters for `apiKeys.list()`. */
+interface ListKeysParams {
+    /** Number of keys to skip. Pages are a fixed 100 and no total is returned. */
+    offset?: number;
+    /** Include disabled keys in the result. */
+    include_disabled?: boolean;
+}
+/**
+ * Account balance, in USD.
+ *
+ * Remaining balance is `total_credits - total_usage`: the endpoint reports
+ * lifetime totals rather than a single "balance" number, matching
+ * OpenRouter.
+ */
+interface Credits {
+    total_credits: number;
+    total_usage: number;
+}
+/**
+ * Cost and timing for a single completed call, from `generations.get()`.
+ *
+ * Fields Onlist has no data for are `null` rather than `0`: `upstream_id`,
+ * `http_referer`, `user_agent`, `origin`, `api_type`, `cache_discount` and
+ * `native_tokens_reasoning`. For reconciliation, "not measured" and
+ * "measured as zero" are different statements.
+ *
+ * `latency` is time-to-first-token in milliseconds and is `null` for
+ * non-streamed calls, which never measure it. `generation_time` is total
+ * wall time in milliseconds. `total_cost` and `usage` are the same USD
+ * amount under both of OpenRouter's names.
+ */
+interface Generation {
+    id: string;
+    model: string;
+    provider_name: string | null;
+    streamed: boolean;
+    latency: number | null;
+    generation_time: number;
+    created_at: string | null;
+    tokens_prompt: number;
+    tokens_completion: number;
+    native_tokens_prompt: number;
+    native_tokens_completion: number;
+    native_tokens_cached: number | null;
+    native_tokens_reasoning: number | null;
+    total_cost: number;
+    usage: number;
+    cache_discount: number | null;
+    finish_reason: string | null;
+    native_finish_reason: string | null;
+    is_byok: boolean;
+    upstream_id: string | null;
+    http_referer: string | null;
+    user_agent: string | null;
+    origin: string | null;
+    api_type: string | null;
+}
+/**
+ * One day × model × provider bucket from `activity.list()`.
+ *
+ * `date` is a `YYYY-MM-DD` UTC day and `usage` is USD. Only complete days
+ * appear — today is still accumulating, and this endpoint exists for
+ * reconciliation.
+ */
+interface ActivityRow {
+    date: string;
+    model: string;
+    model_permaslug: string;
+    endpoint_id: string;
+    provider_name: string | null;
+    usage: number;
+    byok_usage_inference: number;
+    requests: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    reasoning_tokens: number;
+}
+/** Parameters for `activity.list()`. */
+interface ActivityParams {
+    /** Restrict to one `YYYY-MM-DD` UTC day inside the 30-day window. */
+    date?: string;
+    /** Restrict to one inference key. A hash from another account yields an empty list. */
+    api_key_hash?: string;
+}
+/**
+ * The result of `oauth.exchange()`.
+ *
+ * `key` is a new inference key in plaintext, returned once. `user_id` is
+ * always `null` on Onlist: on OpenRouter it carries the calling
+ * application's own external user identifier, which Onlist has no concept
+ * of.
+ */
+interface ExchangedKey {
+    key: string;
+    user_id: string | null;
+}
+/** An S256 PKCE pair from `generatePkce()`. */
+interface PkcePair {
+    /** Kept in memory and passed back to `oauth.exchange()`. */
+    verifier: string;
+    /** Sent to `/auth` when opening the browser flow. */
+    challenge: string;
+}
+
+/**
+ * Account resources — the OpenRouter-compatible `/api/v1/*` face.
+ *
+ * Namespaces follow the wire path segments (`credits`, `generations`,
+ * `apiKeys`, `activity`) and methods use a fixed verb set
+ * (`list`/`get`/`create`/`update`/`delete`). Two departures, both forced:
+ * `GET /api/v1/key` has no matching verb so it is `apiKeys.current()`, and
+ * `/api/v1/auth/*` would read as client authentication config so the
+ * namespace is `oauth`.
+ *
+ * Most of these endpoints require a **management key** (`mgmt_...`). The SDK
+ * does not inspect key prefixes locally — it sends whatever credential it
+ * was given and surfaces the server's 403 as `PermissionDeniedError`.
+ */
+
+/** Options for creating the account resources. */
+type AccountOptions = RequestOptions;
+/**
+ * Generate an S256 PKCE `{verifier, challenge}` pair.
+ *
+ * Send the challenge to `/auth` when starting the browser flow, keep the
+ * verifier in memory, and pass it back to `oauth.exchange()`:
+ *
+ * ```typescript
+ * const { verifier, challenge } = await generatePkce();
+ * window.location.href =
+ *   `https://onlist.io/auth?callback_url=${cb}` +
+ *   `&code_challenge=${challenge}&code_challenge_method=S256`;
+ * ```
+ */
+declare function generatePkce(): Promise<PkcePair>;
+/**
+ * Exchange a PKCE authorization code for an inference key, with no client.
+ *
+ * `client.oauth.exchange()` does the same thing, but constructing an
+ * {@link Onlist} requires an API key — and an app running the "Sign in with
+ * Onlist" flow does not have one yet. That is the entire point of the flow,
+ * so it gets a credential-free entry point:
+ *
+ * ```typescript
+ * const { verifier, challenge } = await generatePkce();
+ * // ...user approves in the browser, your callback receives ?code=...
+ * const result = await exchangeAuthCode(code, { codeVerifier: verifier });
+ * const client = new Onlist({ apiKey: result.key });
+ * ```
+ *
+ * Single-use: the code is consumed even when the verifier turns out to be
+ * wrong, so a failure means restarting the browser flow.
+ */
+declare function exchangeAuthCode(code: string, opts?: {
+    codeVerifier?: string;
+    baseURL?: string;
+    timeout?: number;
+}): Promise<ExchangedKey>;
+/** Account balance. Requires a management key. */
+declare class AccountCredits {
+    private readonly _opts;
+    constructor(_opts: AccountOptions);
+    /** Get lifetime credits purchased and credits used, in USD. */
+    get(): Promise<Credits>;
+}
+/**
+ * Per-call cost and timing.
+ *
+ * Accepts either credential type: an inference key can look up only the
+ * calls it made, a management key any call on the account.
+ */
+declare class AccountGenerations {
+    private readonly _opts;
+    constructor(_opts: AccountOptions);
+    /**
+     * Look up one call by request ID.
+     *
+     * @param requestId The value of the `X-Oneapi-Request-Id` response header
+     *   from the original call.
+     */
+    get(requestId: string): Promise<Generation>;
+}
+/**
+ * Manage inference keys (`sk-...`). Requires a management key.
+ *
+ * The exception is {@link current}, which answers for whichever credential
+ * made the request.
+ */
+declare class AccountApiKeys {
+    private readonly _opts;
+    constructor(_opts: AccountOptions);
+    /** Describe the credential this client is using. */
+    current(): Promise<CurrentKey>;
+    /**
+     * List inference keys.
+     *
+     * Pages are a fixed 100 keys and no total is returned: request
+     * `offset += 100` until you get a short page.
+     */
+    list(params?: ListKeysParams): Promise<APIKey[]>;
+    /**
+     * Create an inference key.
+     *
+     * The plaintext secret is on `.key` of the result and is never retrievable
+     * again.
+     *
+     * @param name Display name for the key. Required.
+     */
+    create(name: string, params?: CreateKeyParams): Promise<CreatedKey>;
+    /** Get one inference key by its `hash`. */
+    get(hash: string): Promise<APIKey>;
+    /**
+     * Update an inference key. Omitted fields are left unchanged.
+     *
+     * For `limit`, `limit_reset` and `expires_at`, passing `null` clears the
+     * value; leaving the field out leaves it alone.
+     */
+    update(hash: string, patch: UpdateKeyParams): Promise<APIKey>;
+    /** Delete an inference key. Resolves to `true` on success. */
+    delete(hash: string): Promise<boolean>;
+}
+/** Daily usage rollups. Requires a management key. */
+declare class AccountActivity {
+    private readonly _opts;
+    constructor(_opts: AccountOptions);
+    /**
+     * List usage grouped by day, model and provider.
+     *
+     * Covers the last 30 complete UTC days; today is excluded.
+     */
+    list(params?: ActivityParams): Promise<ActivityRow[]>;
+}
+/**
+ * Sign in with Onlist — the PKCE authorization-code exchange.
+ *
+ * Only the exchange lives here. The authorization step itself happens in the
+ * user's browser at `https://onlist.io/auth`; there is no SDK call for it,
+ * because the SDK has no session to authorize with.
+ */
+declare class AccountOAuth {
+    private readonly _opts;
+    constructor(_opts: AccountOptions);
+    /**
+     * Exchange an authorization code for a new inference key.
+     *
+     * Unauthenticated, and single-use: the code is consumed even when the
+     * verifier turns out to be wrong, so a failure means restarting the
+     * browser flow.
+     *
+     * @param code The `code` query parameter from the callback URL.
+     * @param codeVerifier The verifier from {@link generatePkce}. Required
+     *   whenever the authorization request carried a challenge.
+     */
+    exchange(code: string, codeVerifier?: string): Promise<ExchangedKey>;
+}
+
+/** Model pricing in USD per million tokens. */
 interface Pricing {
     prompt: string;
     completion: string;
     request?: string | null;
 }
+/** Model architecture metadata. */
 interface Architecture {
     modality?: string | null;
     input_modalities?: string[] | null;
     output_modalities?: string[] | null;
     tokenizer?: string | null;
 }
+/** Top-provider context limits for a model. */
 interface TopProvider {
     context_length?: number | null;
     max_completion_tokens?: number | null;
     is_moderated?: boolean | null;
 }
+/** A model listed in the marketplace catalog. */
 interface Model {
     id: string;
     name?: string | null;
@@ -32,8 +401,8 @@ interface Model {
     quantization?: string | null;
     top_provider?: TopProvider | null;
     is_ready?: boolean | null;
-    [key: string]: unknown;
 }
+/** A provider's offer for a specific model. */
 interface ProviderOffer {
     listing_id?: number | null;
     provider_id?: number | null;
@@ -44,8 +413,8 @@ interface ProviderOffer {
     price_input_usd?: string | null;
     price_output_usd?: string | null;
     availability_7d?: number | null;
-    [key: string]: unknown;
 }
+/** Detailed model info including all provider offers. */
 interface ModelDetail {
     id: string;
     name?: string | null;
@@ -57,8 +426,8 @@ interface ModelDetail {
     pricing?: Pricing | null;
     description?: string | null;
     providers: ProviderOffer[];
-    [key: string]: unknown;
 }
+/** Paginated list of models. */
 interface ModelListResponse {
     data: Model[];
     total?: number | null;
@@ -66,6 +435,7 @@ interface ModelListResponse {
     limit?: number | null;
 }
 
+/** A provider (seller) on the marketplace. */
 interface Provider {
     id?: number | null;
     slug: string;
@@ -79,59 +449,170 @@ interface Provider {
     sample_count?: number | null;
     max_rpm?: number | null;
     availability_7d?: number | null;
-    [key: string]: unknown;
 }
+/** Detailed provider info including their listings. */
 interface ProviderDetail extends Provider {
     listings: Record<string, unknown>[];
 }
+/** Paginated list of providers. */
 interface ProviderListResponse {
     items: Provider[];
 }
 
-interface MarketplaceOptions {
-    apiKey?: string | null;
-    baseURL: string;
-    timeout?: number;
+/** A single entry in the model usage leaderboard. */
+interface ModelRanking {
+    rank: number;
+    model_name: string;
+    author: string;
+    author_icon: string | null;
+    total_tokens: string;
+    total_requests: number;
+    growth_pct: number | null;
+}
+/** A single data point in the model usage chart series. */
+interface ModelSeriesPoint {
+    bucket: string;
+    value: number;
+    type: string;
+}
+/** Response from GET /api/mkt/rankings/models. */
+interface ModelRankingsResponse {
+    leaderboard: ModelRanking[];
+    series: ModelSeriesPoint[];
+    top_models: string[];
+    sort: string;
+    window: string;
+    start_date: string;
+    end_date: string;
+}
+/** Query parameters for the model rankings endpoint. */
+interface ModelRankingsParams {
+    sort?: "popular" | "trending";
+    window?: "day" | "week" | "month";
+    limit?: number;
+    offset?: number;
+}
+/** A single entry in the app rankings list. */
+interface AppRanking {
+    app_id: number;
+    url_key: string;
+    slug: string | null;
+    title: string;
+    description: string | null;
+    domain: string;
+    icon_url: string | null;
+    categories: string[];
+    rank: number;
+    total_requests: number;
+    total_tokens: string;
+    growth_pct: number | null;
+}
+/** Response from GET /api/mkt/apps. */
+interface AppRankingsResponse {
+    apps: AppRanking[];
+    page: number;
+    limit: number;
+    has_more: boolean;
+    sort: string;
+    window: string;
+    start_date: string;
+    end_date: string;
 }
+/** Query parameters for the app rankings endpoint. */
+interface AppRankingsParams {
+    sort?: "popular" | "trending";
+    window?: "day" | "week" | "month";
+    category?: string;
+    subcategory?: string;
+    page?: number;
+    limit?: number;
+}
+
+/** Options for creating a Marketplace client. */
+type MarketplaceOptions = RequestOptions;
+/** Access to marketplace model data. */
 declare class MarketplaceModels {
     private readonly _opts;
     constructor(_opts: MarketplaceOptions);
+    /** List models in the marketplace catalog. */
     list(params?: {
         limit?: number;
         offset?: number;
         q?: string;
     }): Promise<ModelListResponse>;
+    /** Get detailed info for a specific model, including provider offers. */
     get(modelId: string): Promise<ModelDetail>;
-    private _fetch;
 }
+/** Access to marketplace provider data. */
 declare class MarketplaceProviders {
     private readonly _opts;
     constructor(_opts: MarketplaceOptions);
+    /** List providers on the marketplace. */
     list(params?: {
         sort?: string;
         q?: string;
     }): Promise<ProviderListResponse>;
+    /** Get detailed info for a specific provider. */
     get(slug: string): Promise<ProviderDetail>;
-    private _fetch;
 }
+/** Access to marketplace rankings (models and apps). */
+declare class MarketplaceRankings {
+    private readonly _opts;
+    constructor(_opts: MarketplaceOptions);
+    /** Get the model usage leaderboard and chart series. */
+    models(params?: ModelRankingsParams): Promise<ModelRankingsResponse>;
+    /** Get the app rankings list. */
+    apps(params?: AppRankingsParams): Promise<AppRankingsResponse>;
+}
+/** Client for the Onlist marketplace public API. */
 declare class Marketplace {
+    /** Browse and search models. */
     readonly models: MarketplaceModels;
+    /** Browse and search providers. */
     readonly providers: MarketplaceProviders;
+    /** Model and app usage rankings. */
+    readonly rankings: MarketplaceRankings;
     constructor(opts: MarketplaceOptions);
 }
 
+/** Options for creating an Onlist client. */
 interface OnlistOptions extends Omit<ClientOptions, "apiKey" | "baseURL"> {
+    /** API key. Falls back to ONLIST_API_KEY then OPENAI_API_KEY env vars. */
     apiKey?: string | null;
+    /**
+     * Management key (`mgmt_...`) for the account API. Falls back to
+     * ONLIST_MANAGEMENT_KEY, then to the API key.
+     */
+    managementKey?: string | null;
+    /** Base URL for the API. Defaults to https://onlist.io/v1. */
     baseURL?: string | null;
+    /** Maximum retry attempts for marketplace and account API calls. Defaults to 2. */
+    maxRetries?: number;
 }
+/** Onlist API client, extending the OpenAI SDK with marketplace and account features. */
 declare class Onlist extends OpenAI {
+    /** Access to marketplace data: models, providers, and rankings. */
     readonly marketplace: Marketplace;
+    /** Account balance. */
+    readonly credits: AccountCredits;
+    /** Cost and timing for individual calls. */
+    readonly generations: AccountGenerations;
+    /** Inference key management. */
+    readonly apiKeys: AccountApiKeys;
+    /** Daily usage rollups. */
+    readonly activity: AccountActivity;
+    /** Sign in with Onlist — the PKCE code exchange. */
+    readonly oauth: AccountOAuth;
+    /** The credential the account API is using. */
+    readonly managementKey: string | undefined;
     constructor(opts?: OnlistOptions);
 }
 
+/** Base error class for all Onlist SDK errors. */
 declare class OnlistError extends Error {
     constructor(message: string);
 }
+/** Error thrown when an API request fails. */
 declare class APIError extends OnlistError {
     readonly status: number;
     readonly type: string | null;
@@ -146,23 +627,47 @@ declare class APIError extends OnlistError {
         body?: unknown;
     });
 }
+/** Error thrown when the API key is invalid or missing. */
 declare class AuthenticationError extends APIError {
     constructor(message?: string, opts?: Partial<ConstructorParameters<typeof APIError>[1]>);
 }
+/** Error thrown when the account balance is insufficient. */
 declare class InsufficientBalanceError extends APIError {
     constructor(message?: string, opts?: Partial<ConstructorParameters<typeof APIError>[1]>);
 }
+/** Error thrown when the request is rate-limited. */
 declare class RateLimitError extends APIError {
     constructor(message?: string, opts?: Partial<ConstructorParameters<typeof APIError>[1]>);
 }
+/** Error thrown when no matching provider is available. */
 declare class ProviderError extends APIError {
     constructor(message: string, opts: ConstructorParameters<typeof APIError>[1]);
 }
+/** Error thrown when a requested resource is not found. */
+declare class NotFoundError extends APIError {
+    constructor(message?: string, opts?: Partial<ConstructorParameters<typeof APIError>[1]>);
+}
+/** Error thrown when the request is malformed or its parameters are rejected. */
+declare class BadRequestError extends APIError {
+    constructor(message?: string, opts?: Partial<ConstructorParameters<typeof APIError>[1]>);
+}
+/**
+ * Error thrown when the credential is valid but not allowed here.
+ *
+ * Most commonly: an inference key (`sk-...`) was used on an endpoint that
+ * only accepts a management key (`mgmt_...`). The server's message is passed
+ * through unchanged.
+ */
+declare class PermissionDeniedError extends APIError {
+    constructor(message?: string, opts?: Partial<ConstructorParameters<typeof APIError>[1]>);
+}
 
+/** Maximum price limits per token type (USD per million tokens). */
 interface MaxPrice {
     prompt?: number;
     completion?: number;
 }
+/** Provider routing configuration for the Onlist marketplace. */
 interface ProviderRouting {
     only?: string[];
     sort?: "price" | "throughput";
@@ -173,6 +678,13 @@ interface ProviderRouting {
     max_price?: MaxPrice;
 }
 
-declare const VERSION = "0.1.0";
+declare module "openai/resources/chat/completions/completions" {
+    interface ChatCompletionCreateParamsBase {
+        /** Onlist provider routing configuration. */
+        provider?: ProviderRouting;
+    }
+}
+
+declare const VERSION = "0.3.0";
 
-export { APIError, type Architecture, AuthenticationError, InsufficientBalanceError, Marketplace, MarketplaceModels, type MarketplaceOptions, MarketplaceProviders, type MaxPrice, type Model, type ModelDetail, type ModelListResponse, Onlist, OnlistError, type OnlistOptions, type Pricing, type Provider, type ProviderDetail, ProviderError, type ProviderListResponse, type ProviderOffer, type ProviderRouting, RateLimitError, type TopProvider, VERSION };
+export { APIError, type APIKey, AccountActivity, AccountApiKeys, AccountCredits, AccountGenerations, AccountOAuth, type AccountOptions, type ActivityParams, type ActivityRow, type AppRanking, type AppRankingsParams, type AppRankingsResponse, type Architecture, AuthenticationError, BadRequestError, type CreateKeyParams, type CreatedKey, type Credits, type CurrentKey, type ExchangedKey, type Generation, InsufficientBalanceError, type ListKeysParams, Marketplace, MarketplaceModels, type MarketplaceOptions, MarketplaceProviders, MarketplaceRankings, type MaxPrice, type Model, type ModelDetail, type ModelListResponse, type ModelRanking, type ModelRankingsParams, type ModelRankingsResponse, type ModelSeriesPoint, NotFoundError, Onlist, OnlistError, type OnlistOptions, PermissionDeniedError, type PkcePair, type Pricing, type Provider, type ProviderDetail, ProviderError, type ProviderListResponse, type ProviderOffer, type ProviderRouting, type RateLimit, RateLimitError, type TopProvider, type UpdateKeyParams, VERSION, exchangeAuthCode, generatePkce };