@onlist/sdk 0.2.0 → 0.3.0

package/README.md

@@ -44,6 +44,15 @@ const client = new Onlist();
 const client = new Onlist();
 ```
 
+For the [Account API](#account-api) there is a second, optional credential —
+a management key, read from the `managementKey` parameter or
+`ONLIST_MANAGEMENT_KEY`, falling back to your API key:
+
+```typescript
+const client = new Onlist({ managementKey: "mgmt_..." });
+// export ONLIST_MANAGEMENT_KEY=mgmt_...
+```
+
 ## Provider Routing
 
 Route requests to specific providers on the Onlist marketplace:
@@ -151,8 +160,121 @@ for (const app of apps.apps) {
 }
 ```
 
-## Error Handling
+## Account API
+
+Balance, API key management, per-call costs and daily usage. These endpoints
+are OpenRouter-compatible: same paths, same field names.
+
+Most of them need a **management key** (`mgmt_...`), which you create at
+[onlist.io/management-keys](https://onlist.io/management-keys). It is a
+separate credential from your inference key and cannot make model calls:
+
+```typescript
+const client = new Onlist({ apiKey: "sk-...", managementKey: "mgmt_..." });
+// or set ONLIST_API_KEY and ONLIST_MANAGEMENT_KEY
+```
+
+If you pass only `apiKey`, it is used for the account endpoints too. That
+matches OpenRouter's single-keyhole shape, and the server returns
+`PermissionDeniedError` where a management key is actually required.
+
+### Credits
+
+```typescript
+const credits = await client.credits.get();
+console.log(`$${(credits.total_credits - credits.total_usage).toFixed(4)} remaining`);
+```
+
+### API keys
 
+```typescript
+// Create — `.key` is the plaintext secret, returned exactly once
+const created = await client.apiKeys.create("ci-runner", { limit: 5, limit_reset: "daily" });
+console.log(created.key);
+
+// List — fixed pages of 100, no total; read until you get a short page
+const keys = await client.apiKeys.list({ offset: 0, include_disabled: true });
+
+// Read one
+const key = await client.apiKeys.get(created.data.hash);
+
+// Update — omitted fields are left unchanged, `null` clears the value
+await client.apiKeys.update(key.hash, { limit: null }); // remove the spend cap
+await client.apiKeys.update(key.hash, { disabled: true }); // stop it spending
+
+await client.apiKeys.delete(key.hash);
+
+// Describe the credential this client is holding
+const me = await client.apiKeys.current();
+```
+
+`update()` distinguishes three states. An omitted (or `undefined`) field is
+left alone; an explicit `null` clears the value. Because of that, `name` and
+`disabled` do not accept `null` at all — the server reads `{"name": null}` as
+an empty name and `{"disabled": null}` as `false`, which would re-enable a
+key you only meant to leave alone.
+
+`limit_reset` accepts `"daily"`, `"weekly"`, or `null` for a lifetime total.
+
+### Generation
+
+What one call cost, and where it went. This one also accepts a plain
+inference key, which can look up the calls it made itself:
+
+```typescript
+const { data, response } = await client.chat.completions
+  .create({ model: "deepseek/deepseek-chat", messages: [{ role: "user", content: "Hi" }] })
+  .withResponse();
+
+const gen = await client.generations.get(response.headers.get("X-Oneapi-Request-Id")!);
+console.log(`${gen.provider_name}: $${gen.total_cost}, ${gen.latency}ms to first token`);
+```
+
+### Activity
+
+Daily usage grouped by model and provider, covering the last 30 complete UTC
+days. Today is excluded, so the same query always returns the same numbers:
+
+```typescript
+for (const row of await client.activity.list()) {
+  console.log(`${row.date} ${row.model} ${row.requests} req $${row.usage}`);
+}
+
+// Narrow to one day or one key
+await client.activity.list({ date: "2026-09-05" });
+await client.activity.list({ api_key_hash: "42" });
+```
+
+## Sign in with Onlist
+
+Let your users authorize your app and get their own inference key, without
+ever pasting one. This is the OAuth PKCE flow, compatible with OpenRouter's:
+
+```typescript
+import { Onlist, exchangeAuthCode, generatePkce } from "@onlist/sdk";
+
+const { verifier, challenge } = await generatePkce();
+
+window.location.href =
+  "https://onlist.io/auth" +
+  "?callback_url=https://yourapp.com/callback" +
+  `&code_challenge=${challenge}&code_challenge_method=S256`;
+
+// ...user approves, your callback receives ?code=...
+
+const result = await exchangeAuthCode(code, { codeVerifier: verifier });
+const client = new Onlist({ apiKey: result.key }); // scoped to that user
+```
+
+`exchangeAuthCode()` is a standalone function, not a client method, because
+an app running this flow has no API key yet — that is the whole point of it —
+and constructing `Onlist` requires one. If you already have a client,
+`client.oauth.exchange()` does the same thing.
+
+The code is single-use and is consumed even when the verifier does not match,
+so a failed exchange means restarting the browser flow.
+
+## Error Handling
 OpenAI-compatible calls (`chat.completions`, `embeddings`, etc.) throw standard `openai` errors. Marketplace calls throw `onlist` errors:
 
 ```typescript
@@ -181,9 +303,25 @@ try {
 }
 ```
 
+Account endpoints throw the same family, plus `BadRequestError` (400) and
+`PermissionDeniedError` (403). The server's message is passed through
+unchanged:
+
+```typescript
+import { PermissionDeniedError } from "@onlist/sdk";
+
+try {
+  await client.credits.get();
+} catch (e) {
+  if (e instanceof PermissionDeniedError) {
+    console.log(e.message); // "Only management keys can perform this operation"
+  }
+}
+```
+
 ## Retry Configuration
 
-Marketplace API calls automatically retry on transient failures (408, 429, 5xx) with exponential backoff:
+Marketplace and account API calls automatically retry on transient failures (408, 429, 5xx) with exponential backoff:
 
 ```typescript
 const client = new Onlist({
@@ -192,6 +330,10 @@ const client = new Onlist({
 });
 ```
 
+Only `GET` requests are retried. Creating a key or exchanging an
+authorization code is never replayed: a duplicate key or a burnt code is
+worse than surfacing the transient error.
+
 ## Migration from OpenAI
 
 Replace the `openai` import with `onlist`:

package/dist/index.cjs

@@ -31,7 +31,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   APIError: () => APIError,
+  AccountActivity: () => AccountActivity,
+  AccountApiKeys: () => AccountApiKeys,
+  AccountCredits: () => AccountCredits,
+  AccountGenerations: () => AccountGenerations,
+  AccountOAuth: () => AccountOAuth,
   AuthenticationError: () => AuthenticationError,
+  BadRequestError: () => BadRequestError,
   InsufficientBalanceError: () => InsufficientBalanceError,
   Marketplace: () => Marketplace,
   MarketplaceModels: () => MarketplaceModels,
@@ -40,9 +46,12 @@ __export(index_exports, {
   NotFoundError: () => NotFoundError,
   Onlist: () => Onlist,
   OnlistError: () => OnlistError,
+  PermissionDeniedError: () => PermissionDeniedError,
   ProviderError: () => ProviderError,
   RateLimitError: () => RateLimitError,
-  VERSION: () => VERSION
+  VERSION: () => VERSION,
+  exchangeAuthCode: () => exchangeAuthCode,
+  generatePkce: () => generatePkce
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -102,6 +111,18 @@ var NotFoundError = class extends APIError {
     this.name = "NotFoundError";
   }
 };
+var BadRequestError = class extends APIError {
+  constructor(message = "Bad request", opts) {
+    super(message, { status: 400, ...opts });
+    this.name = "BadRequestError";
+  }
+};
+var PermissionDeniedError = class extends APIError {
+  constructor(message = "Permission denied", opts) {
+    super(message, { status: 403, ...opts });
+    this.name = "PermissionDeniedError";
+  }
+};
 function raiseForStatus(status, body) {
   let error = {};
   if (body && typeof body === "object" && "error" in body) {
@@ -115,8 +136,10 @@ function raiseForStatus(status, body) {
   const code = typeof error.code === "string" ? error.code : null;
   const param = typeof error.param === "string" ? error.param : null;
   const opts = { status, type, code, param, body };
+  if (status === 400) throw new BadRequestError(message, opts);
   if (status === 401) throw new AuthenticationError(message, opts);
   if (status === 402) throw new InsufficientBalanceError(message, opts);
+  if (status === 403) throw new PermissionDeniedError(message, opts);
   if (status === 404) throw new NotFoundError(message, opts);
   if (status === 429) throw new RateLimitError(message, opts);
   if (code && code.startsWith("no_provider")) throw new ProviderError(message, opts);
@@ -124,9 +147,9 @@ function raiseForStatus(status, body) {
 }
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
-// src/marketplace.ts
+// src/http.ts
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
 var INITIAL_RETRY_DELAY = 500;
@@ -162,6 +185,223 @@ function retryDelay(attempt, retryAfterHeader) {
   const jitter = base * JITTER_FACTOR * (2 * Math.random() - 1);
   return Math.max(0, base + jitter);
 }
+function buildFetchInit(opts, init) {
+  const headers = {
+    "User-Agent": `onlist-js/${VERSION}`,
+    Accept: "application/json",
+    ...init?.headers
+  };
+  if (opts.apiKey) {
+    headers["Authorization"] = `Bearer ${opts.apiKey}`;
+  }
+  const signal = AbortSignal.timeout(opts.timeout ?? DEFAULT_TIMEOUT);
+  return { ...init, headers, signal };
+}
+async function fetchWithRetry(opts, path, init) {
+  const url = `${opts.baseURL.replace(/\/$/, "")}${path}`;
+  const fetchInit = buildFetchInit(opts, init);
+  const method = (init?.method ?? "GET").toUpperCase();
+  const maxRetries = method === "GET" ? opts.maxRetries ?? DEFAULT_MAX_RETRIES : 0;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, fetchInit);
+      if (response.ok || !RETRYABLE_STATUSES.has(response.status) || attempt === maxRetries) {
+        return response;
+      }
+      const delay = retryDelay(attempt, response.headers.get("Retry-After"));
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    } catch (err) {
+      lastError = err;
+      if (attempt === maxRetries) break;
+      const delay = retryDelay(attempt, null);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw lastError;
+}
+function jsonBody(value) {
+  return {
+    body: JSON.stringify(value),
+    headers: { "Content-Type": "application/json" }
+  };
+}
+
+// src/account.ts
+function unwrap(body) {
+  if (body && typeof body === "object" && "data" in body) {
+    return body.data;
+  }
+  return body;
+}
+function base64url(bytes) {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function generatePkce() {
+  const raw = new Uint8Array(32);
+  crypto.getRandomValues(raw);
+  const verifier = base64url(raw);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+}
+var DEFAULT_BASE_URL = "https://onlist.io";
+async function exchangeAuthCode(code, opts) {
+  const resource = new AccountOAuth({
+    baseURL: opts?.baseURL ?? DEFAULT_BASE_URL,
+    timeout: opts?.timeout
+  });
+  return resource.exchange(code, opts?.codeVerifier ?? "");
+}
+var AccountCredits = class {
+  constructor(_opts) {
+    this._opts = _opts;
+  }
+  _opts;
+  /** Get lifetime credits purchased and credits used, in USD. */
+  async get() {
+    const resp = await fetchWithRetry(this._opts, "/api/v1/credits");
+    return unwrap(await parseResponse(resp));
+  }
+};
+var AccountGenerations = class {
+  constructor(_opts) {
+    this._opts = _opts;
+  }
+  _opts;
+  /**
+   * Look up one call by request ID.
+   *
+   * @param requestId The value of the `X-Oneapi-Request-Id` response header
+   *   from the original call.
+   */
+  async get(requestId) {
+    const search = new URLSearchParams({ id: requestId });
+    const resp = await fetchWithRetry(this._opts, `/api/v1/generation?${search}`);
+    return unwrap(await parseResponse(resp));
+  }
+};
+var AccountApiKeys = class {
+  constructor(_opts) {
+    this._opts = _opts;
+  }
+  _opts;
+  /** Describe the credential this client is using. */
+  async current() {
+    const resp = await fetchWithRetry(this._opts, "/api/v1/key");
+    return unwrap(await parseResponse(resp));
+  }
+  /**
+   * List inference keys.
+   *
+   * Pages are a fixed 100 keys and no total is returned: request
+   * `offset += 100` until you get a short page.
+   */
+  async list(params) {
+    const search = new URLSearchParams();
+    search.set("offset", String(params?.offset ?? 0));
+    search.set("include_disabled", String(params?.include_disabled ?? false));
+    const resp = await fetchWithRetry(this._opts, `/api/v1/keys?${search}`);
+    return unwrap(await parseResponse(resp)) ?? [];
+  }
+  /**
+   * 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.
+   */
+  async create(name, params) {
+    const body = { name };
+    if (params?.limit !== void 0) body.limit = params.limit;
+    if (params?.limit_reset !== void 0) body.limit_reset = params.limit_reset;
+    if (params?.expires_at !== void 0) body.expires_at = params.expires_at;
+    const resp = await fetchWithRetry(this._opts, "/api/v1/keys", {
+      method: "POST",
+      ...jsonBody(body)
+    });
+    return await parseResponse(resp);
+  }
+  /** Get one inference key by its `hash`. */
+  async get(hash) {
+    const resp = await fetchWithRetry(this._opts, `/api/v1/keys/${encodePath(hash)}`);
+    return unwrap(await parseResponse(resp));
+  }
+  /**
+   * 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.
+   */
+  async update(hash, patch) {
+    const body = {};
+    if (patch.name !== void 0) body.name = patch.name;
+    if (patch.disabled !== void 0) body.disabled = patch.disabled;
+    if (patch.limit !== void 0) body.limit = patch.limit;
+    if (patch.limit_reset !== void 0) body.limit_reset = patch.limit_reset;
+    if (patch.expires_at !== void 0) body.expires_at = patch.expires_at;
+    const resp = await fetchWithRetry(this._opts, `/api/v1/keys/${encodePath(hash)}`, {
+      method: "PATCH",
+      ...jsonBody(body)
+    });
+    return unwrap(await parseResponse(resp));
+  }
+  /** Delete an inference key. Resolves to `true` on success. */
+  async delete(hash) {
+    const resp = await fetchWithRetry(this._opts, `/api/v1/keys/${encodePath(hash)}`, {
+      method: "DELETE"
+    });
+    const data = unwrap(await parseResponse(resp));
+    return Boolean(data?.deleted);
+  }
+};
+var AccountActivity = class {
+  constructor(_opts) {
+    this._opts = _opts;
+  }
+  _opts;
+  /**
+   * List usage grouped by day, model and provider.
+   *
+   * Covers the last 30 complete UTC days; today is excluded.
+   */
+  async list(params) {
+    const search = new URLSearchParams();
+    if (params?.date) search.set("date", params.date);
+    if (params?.api_key_hash) search.set("api_key_hash", params.api_key_hash);
+    const qs = search.toString();
+    const resp = await fetchWithRetry(this._opts, `/api/v1/activity${qs ? `?${qs}` : ""}`);
+    return unwrap(await parseResponse(resp)) ?? [];
+  }
+};
+var AccountOAuth = class {
+  constructor(_opts) {
+    this._opts = _opts;
+  }
+  _opts;
+  /**
+   * 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.
+   */
+  async exchange(code, codeVerifier = "") {
+    const resp = await fetchWithRetry(this._opts, "/api/v1/auth/keys", {
+      method: "POST",
+      ...jsonBody({ code, code_verifier: codeVerifier })
+    });
+    return await parseResponse(resp);
+  }
+};
+
+// src/marketplace.ts
 var MarketplaceModels = class {
   constructor(_opts) {
     this._opts = _opts;
@@ -253,40 +493,6 @@ var Marketplace = class {
     this.rankings = new MarketplaceRankings(opts);
   }
 };
-function buildFetchInit(opts, init) {
-  const headers = {
-    "User-Agent": `onlist-js/${VERSION}`,
-    Accept: "application/json",
-    ...init?.headers
-  };
-  if (opts.apiKey) {
-    headers["Authorization"] = `Bearer ${opts.apiKey}`;
-  }
-  const signal = AbortSignal.timeout(opts.timeout ?? DEFAULT_TIMEOUT);
-  return { ...init, headers, signal };
-}
-async function fetchWithRetry(opts, path, init) {
-  const url = `${opts.baseURL.replace(/\/$/, "")}${path}`;
-  const fetchInit = buildFetchInit(opts, init);
-  const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
-  let lastError;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      const response = await fetch(url, fetchInit);
-      if (response.ok || !RETRYABLE_STATUSES.has(response.status) || attempt === maxRetries) {
-        return response;
-      }
-      const delay = retryDelay(attempt, response.headers.get("Retry-After"));
-      await new Promise((resolve) => setTimeout(resolve, delay));
-    } catch (err) {
-      lastError = err;
-      if (attempt === maxRetries) break;
-      const delay = retryDelay(attempt, null);
-      await new Promise((resolve) => setTimeout(resolve, delay));
-    }
-  }
-  throw lastError;
-}
 
 // src/client.ts
 var BASE_URL = "https://onlist.io/v1";
@@ -294,6 +500,18 @@ var MARKETPLACE_BASE_URL = "https://onlist.io";
 var Onlist = class extends import_openai.default {
   /** Access to marketplace data: models, providers, and rankings. */
   marketplace;
+  /** Account balance. */
+  credits;
+  /** Cost and timing for individual calls. */
+  generations;
+  /** Inference key management. */
+  apiKeys;
+  /** Daily usage rollups. */
+  activity;
+  /** Sign in with Onlist — the PKCE code exchange. */
+  oauth;
+  /** The credential the account API is using. */
+  managementKey;
   constructor(opts) {
     const apiKey = opts?.apiKey ?? (typeof process !== "undefined" ? process.env?.ONLIST_API_KEY ?? process.env?.OPENAI_API_KEY : void 0) ?? void 0;
     const baseURL = opts?.baseURL ?? BASE_URL;
@@ -313,12 +531,29 @@ var Onlist = class extends import_openai.default {
       baseURL: marketplaceBase,
       maxRetries: opts?.maxRetries
     });
+    this.managementKey = opts?.managementKey ?? (typeof process !== "undefined" ? process.env?.ONLIST_MANAGEMENT_KEY : void 0) ?? this.apiKey ?? void 0;
+    const accountOpts = {
+      apiKey: this.managementKey,
+      baseURL: marketplaceBase,
+      maxRetries: opts?.maxRetries
+    };
+    this.credits = new AccountCredits(accountOpts);
+    this.generations = new AccountGenerations(accountOpts);
+    this.apiKeys = new AccountApiKeys(accountOpts);
+    this.activity = new AccountActivity(accountOpts);
+    this.oauth = new AccountOAuth(accountOpts);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
+  AccountActivity,
+  AccountApiKeys,
+  AccountCredits,
+  AccountGenerations,
+  AccountOAuth,
   AuthenticationError,
+  BadRequestError,
   InsufficientBalanceError,
   Marketplace,
   MarketplaceModels,
@@ -327,8 +562,11 @@ var Onlist = class extends import_openai.default {
   NotFoundError,
   Onlist,
   OnlistError,
+  PermissionDeniedError,
   ProviderError,
   RateLimitError,
-  VERSION
+  VERSION,
+  exchangeAuthCode,
+  generatePkce
 });
 //# sourceMappingURL=index.cjs.map