@tokenite/sdk 2.0.0 → 2.2.0

package/README.md

@@ -85,7 +85,7 @@ await fetch('/api/auth/exchange', {
 
 ### Managed agents (Anthropic)
 
-Tokenite proxies Anthropic's [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) surface — the `/v1/agents`, `/v1/environments`, `/v1/sessions`, `/v1/vaults`, and `/v1/files` endpoints — under the same BYOK model as Messages. The app points the Anthropic SDK at `tk.proxyUrl('anthropic')`; the proxy injects the managed-agents beta header and forwards calls to the user's Anthropic org.
+Tokenite proxies Anthropic's [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) surface — the `/v1/agents`, `/v1/environments`, `/v1/sessions`, `/v1/vaults`, `/v1/files`, and `/v1/skills` endpoints — under the same BYOK model as Messages. The app points the Anthropic SDK at `tk.proxyUrl('anthropic')`; the proxy injects the right beta header per surface (`managed-agents-2026-04-01` for agents/environments/sessions/vaults, `files-api-2025-04-14` for files, `skills-2025-10-02` for skills) and forwards calls to the user's Anthropic org. Client-supplied `anthropic-beta` headers are passed through and merged with the auto-injected ones, so callers can opt into additional betas (e.g. multi-version skills) without losing the proxy-managed defaults.
 
 **Explicit consent required.** Because agent sessions run long-lived, billable server-side work on Anthropic (`$0.08/hr` session runtime on top of tokens), the proxy rejects agent-surface calls unless the app was created with `allowsManagedAgents: true`. The flag sits alongside the other app fields on creation:
 
@@ -93,7 +93,8 @@ Tokenite proxies Anthropic's [Managed Agents](https://platform.claude.com/docs/e
 await admin.apps.create({
   name: 'Life Coach',
   callbackUrl: 'https://lifecoach.ai/callback',
-  requiredProviders: ['anthropic'],
+  modelStrategy: 'models',
+  allowedModels: ['claude-opus-4-7', 'claude-sonnet-4-6'],
   allowsManagedAgents: true,          // ← opt in
 });
 ```
@@ -141,6 +142,57 @@ Tokenite tracks each session for attribution and auto-terminates running session
 
 Budget is checked pre-call but not enforced mid-session: a session that started under budget can run past it. Revoke is the user's hard kill switch.
 
+### Handling the OAuth callback
+
+When Tokenite redirects back to your `redirect_uri`, the URL has one of:
+
+- `?code=...&state=...` — user approved; exchange the code for an access token.
+- `?error=access_denied&error_description=user_denied&state=...` — user clicked **Cancel** on the consent screen.
+- `?error=...&error_description=...&state=...` — any other OAuth failure.
+- nothing (or just `state`) — user landed on your callback path without completing a real OAuth round-trip.
+
+`parseCallback(input, options?)` turns the URL into a typed result so you can switch on it instead of hand-parsing strings. Pure function; works in any runtime (Node, Bun, edge, browser).
+
+```typescript
+import { parseCallback } from '@tokenite/sdk';
+
+// In your /api/auth/callback handler:
+const result = parseCallback(req.url, { expectedState: sessionStoredState });
+
+if (result.ok) {
+  const { access_token } = await tk.exchangeCode(result.code);
+  // ... establish your app's session, redirect to /
+  return;
+}
+
+switch (result.reason) {
+  case 'user_denied':
+    // User clicked Cancel. Don't show a scary error — render a
+    // friendly "you cancelled" screen with a "Try again" button.
+    return renderCancelled();
+  case 'invalid_state':
+    // CSRF check failed (state mismatch). Force a fresh login flow.
+    return renderRetry('Your sign-in session expired. Please try again.');
+  case 'missing_code':
+    // User navigated to /callback directly (bookmark, browser back).
+    return redirectToHome();
+  case 'access_denied':
+  case 'oauth_error':
+    // Real OAuth failure. result.error + result.description have details.
+    return renderError(result);
+}
+```
+
+`parseCallback` accepts:
+
+- A full URL string: `parseCallback('https://yourapp.com/cb?code=…&state=…')`
+- A path + query: `parseCallback(req.url)` (Node's `req.url` works directly)
+- A query string: `parseCallback('?code=…&state=…')` or `parseCallback('code=…&state=…')`
+- A `URL` object: `parseCallback(new URL(...))`
+- A `URLSearchParams`: `parseCallback(params)`
+
+`expectedState` is optional. When you provide it, a mismatch returns `{ ok: false, reason: 'invalid_state' }` even if a `code` is present — treating a stolen code paired with a forged state as a CSRF attempt.
+
 ### Streaming responses
 
 `tk.call()` is for non-streaming requests. Streaming responses bypass the unified envelope and are forwarded as-is, so use any vendor SDK with `baseURL: tk.proxyUrl(...)`:
@@ -253,6 +305,44 @@ export type PopupResult = {
   readonly code: string;
 };
 
+export type TopUpOptions = {
+  /**
+   * How to host the top-up screen.
+   *
+   * - `'popup'` (default) — open in a separate browser window via
+   *   `window.open`. The user completes the form; the SDK resolves
+   *   when Tokenite posts back the new limit.
+   * - `'redirect'` — full-page navigation. The builder's app loses
+   *   in-memory state and must reload from the callback URL.
+   */
+  readonly mode?: 'popup' | 'redirect';
+  /** Pre-fill the new-limit field. Default: 2 × current limit. */
+  readonly suggestedAmount?: number;
+  /** Popup width in pixels. Default: 480 */
+  readonly width?: number;
+  /** Popup height in pixels. Default: 560 */
+  readonly height?: number;
+};
+
+export type TopUpResult =
+  | { readonly ok: true; readonly newLimit: number; readonly remaining: number }
+  | { readonly ok: false; readonly reason: 'cancelled' | 'popup-blocked' | 'closed' | 'redirected' };
+
+export type CallWithRecoveryOptions = {
+  /**
+   * What to do when the proxy returns a recoverable funding error.
+   *
+   * - `'popup'` (default) — open Tokenite's top-up popup, then retry the
+   *   call once on success.
+   * - `'redirect'` — full-page navigation; the call does not retry (the
+   *   builder's app re-loads from the callback and re-invokes manually).
+   * - `'throw'` — disable recovery; surface the original error.
+   */
+  readonly onFundingNeeded?: 'popup' | 'redirect' | 'throw';
+  /** Override the suggested top-up amount. */
+  readonly suggestedAmount?: number;
+};
+
 export type TokenResponse = {
   readonly access_token: string;
   readonly token_type: string;
@@ -405,12 +495,6 @@ export type AppInfo = {
   readonly websiteUrl: string | null;
   /** Absolute URL to the app's icon (PNG/SVG). null when the developer hasn't set one — render initials or a generic glyph. */
   readonly iconUrl: string | null;
-  /** Providers the app declares it needs */
-  readonly requiredProviders: readonly Provider[];
-  /** Fallback order when `allowSubstitution` is true */
-  readonly preferredProviders: readonly Provider[];
-  /** Whether the app accepts substitute providers when a required one isn't available */
-  readonly allowSubstitution: boolean;
 };
 
 /**

package/dist/admin/types.d.ts

@@ -1,14 +1,11 @@
 import type { Provider } from '../types.js';
-export type ModelStrategy = 'any' | 'tier' | 'models';
+export type ModelStrategy = 'any' | 'tier' | 'models' | 'none';
 export type RequiredTier = 'cheap' | 'fast' | 'smart' | 'reasoning';
 export type AppRecord = {
     readonly id: string;
     readonly builderId: string;
     readonly name: string;
     readonly callbackUrl: string;
-    readonly requiredProviders: readonly Provider[];
-    readonly preferredProviders: readonly Provider[];
-    readonly allowSubstitution: boolean;
     readonly allowedModels?: readonly string[];
     readonly modelStrategy: ModelStrategy;
     readonly requiredTier?: RequiredTier;
@@ -24,9 +21,6 @@ export type CreatedApp = AppRecord & {
 export type CreateAppInput = {
     readonly name: string;
     readonly callbackUrl: string;
-    readonly requiredProviders: readonly Provider[];
-    readonly preferredProviders?: readonly Provider[];
-    readonly allowSubstitution?: boolean;
     readonly allowedModels?: readonly string[];
     readonly modelStrategy?: ModelStrategy;
     readonly requiredTier?: RequiredTier;

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { TokeniteConfig, AuthorizeOptions, PopupOptions, PopupResult, TokenResponse, Provider, ProxyCallOptions, ProxyResponse, AccessContext } from './types.js';
+import type { TokeniteConfig, AuthorizeOptions, PopupOptions, PopupResult, TokenResponse, Provider, ProxyCallOptions, ProxyResponse, AccessContext, TopUpOptions, TopUpResult, CallWithRecoveryOptions } from './types.js';
 /**
  * Tokenite client.
  *
@@ -117,6 +117,37 @@ export declare const Tokenite: (config: TokeniteConfig) => {
      * bypass the unified envelope.
      */
     proxyUrl: (provider: Provider) => string;
+    /**
+     * Open a Tokenite-hosted "raise budget" popup for this app.
+     *
+     * When `tk.call()` returns `BUDGET_EXCEEDED`, call this to let the
+     * user authorise a higher spending cap without leaving your app.
+     * The popup resolves once the new limit is committed. The access
+     * token does not change — only its budget ceiling.
+     *
+     * The user must be signed in to Tokenite in the same browser (the
+     * popup uses their session cookie). If not, the popup routes them
+     * through sign-in and returns afterwards.
+     *
+     * ```typescript
+     * const r = await tk.call({ accessToken, provider: 'anthropic', ... });
+     * if (isProxyError(r) && r.error.code === 'BUDGET_EXCEEDED') {
+     *   const top = await tk.topUp();
+     *   if (top.ok) return tk.call({ accessToken, ... });
+     * }
+     * ```
+     */
+    topUp: (options?: TopUpOptions) => Promise<TopUpResult>;
+    /**
+     * Wrap `tk.call()` with automatic recovery when the proxy returns a
+     * recoverable funding error (`BUDGET_EXCEEDED` by default). On a
+     * fundable error, opens the top-up popup and retries the call once
+     * if the user committed a new limit.
+     *
+     * The retry is bounded to one attempt — repeated funding failures
+     * surface back to the caller so misconfigured caps don't loop.
+     */
+    callWithRecovery: (options: ProxyCallOptions, recovery?: CallWithRecoveryOptions) => Promise<ProxyResponse>;
     /** The Tokenite dashboard base URL */
     baseUrl: string;
     /** The Tokenite proxy base URL */

package/dist/client.js

@@ -1,8 +1,21 @@
+import { AuthMessageType, TopupMessageType } from './protocol.js';
 import { extractErrorMessage } from './error.js';
-const DEFAULT_BASE_URL = 'https://tokenite.ai';
-const DEFAULT_PROXY_URL = 'https://api.tokenite.ai';
+import { isProxyError } from './types.js';
+import { isFundingError } from './recovery.js';
+// `tokenite.ai` is the marketing site. The dashboard (which hosts the
+// OAuth consent screen and the API the SDK calls — /oauth/authorize,
+// /api/oauth/token) lives at `app.tokenite.ai`. Older versions of this
+// SDK pointed at `tokenite.ai` and only worked because that hostname
+// was aliased to the dashboard CloudFront; the marketing-site move on
+// 2026-05-06 broke that. Marketing CF now redirects /oauth/* and
+// /api/* to app.tokenite.ai, so older SDK installs continue to work,
+// but new installs should hit the dashboard directly.
+const DEFAULT_BASE_URL = 'https://app.tokenite.ai';
+const DEFAULT_PROXY_URL = 'https://proxy.tokenite.ai';
 const IFRAME_WIDTH = 480;
 const IFRAME_HEIGHT = 620;
+const TOPUP_WIDTH = 480;
+const TOPUP_HEIGHT = 560;
 /**
  * Tokenite client.
  *
@@ -44,6 +57,29 @@ const IFRAME_HEIGHT = 620;
 export const Tokenite = (config) => {
     const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
     const proxyBase = config.proxyUrl ?? DEFAULT_PROXY_URL;
+    const proxyCall = async (options) => {
+        const path = options.path.startsWith('/') ? options.path : `/${options.path}`;
+        const response = await fetch(`${proxyBase}/${options.provider}${path}`, {
+            method: options.method ?? 'POST',
+            headers: {
+                'authorization': `Bearer ${options.accessToken}`,
+                'content-type': 'application/json',
+            },
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+        return (await response.json());
+    };
+    const runTopUp = (options) => {
+        const mode = options?.mode ?? 'popup';
+        const width = options?.width ?? TOPUP_WIDTH;
+        const height = options?.height ?? TOPUP_HEIGHT;
+        const url = buildTopupUrl(baseUrl, config.clientId, mode, options?.suggestedAmount);
+        if (mode === 'redirect') {
+            window.location.href = url;
+            return Promise.resolve({ ok: false, reason: 'redirected' });
+        }
+        return openTopupPopup(url, width, height, baseUrl);
+    };
     const buildAuthorizeUrl = (options) => {
         const state = options?.state ?? generateState();
         const params = new URLSearchParams({
@@ -143,18 +179,7 @@ export const Tokenite = (config) => {
          * });
          * ```
          */
-        call: async (options) => {
-            const path = options.path.startsWith('/') ? options.path : `/${options.path}`;
-            const response = await fetch(`${proxyBase}/${options.provider}${path}`, {
-                method: options.method ?? 'POST',
-                headers: {
-                    'authorization': `Bearer ${options.accessToken}`,
-                    'content-type': 'application/json',
-                },
-                body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
-            });
-            return (await response.json());
-        },
+        call: proxyCall,
         /**
          * Fetch the full access context for an access token: which app it
          * belongs to, who holds the token, and which providers it can call.
@@ -198,6 +223,56 @@ export const Tokenite = (config) => {
          * bypass the unified envelope.
          */
         proxyUrl: (provider) => `${proxyBase}/${provider}`,
+        /**
+         * Open a Tokenite-hosted "raise budget" popup for this app.
+         *
+         * When `tk.call()` returns `BUDGET_EXCEEDED`, call this to let the
+         * user authorise a higher spending cap without leaving your app.
+         * The popup resolves once the new limit is committed. The access
+         * token does not change — only its budget ceiling.
+         *
+         * The user must be signed in to Tokenite in the same browser (the
+         * popup uses their session cookie). If not, the popup routes them
+         * through sign-in and returns afterwards.
+         *
+         * ```typescript
+         * const r = await tk.call({ accessToken, provider: 'anthropic', ... });
+         * if (isProxyError(r) && r.error.code === 'BUDGET_EXCEEDED') {
+         *   const top = await tk.topUp();
+         *   if (top.ok) return tk.call({ accessToken, ... });
+         * }
+         * ```
+         */
+        topUp: runTopUp,
+        /**
+         * Wrap `tk.call()` with automatic recovery when the proxy returns a
+         * recoverable funding error (`BUDGET_EXCEEDED` by default). On a
+         * fundable error, opens the top-up popup and retries the call once
+         * if the user committed a new limit.
+         *
+         * The retry is bounded to one attempt — repeated funding failures
+         * surface back to the caller so misconfigured caps don't loop.
+         */
+        callWithRecovery: async (options, recovery = {}) => {
+            const r = await proxyCall(options);
+            if (!isProxyError(r))
+                return r;
+            const klass = isFundingError(r.error);
+            if (!klass || klass.kind !== 'user-topup')
+                return r;
+            const onNeed = recovery.onFundingNeeded ?? 'popup';
+            if (onNeed === 'throw')
+                return r;
+            const top = await runTopUp({
+                mode: onNeed,
+                ...(recovery.suggestedAmount ?? klass.suggestedAmount
+                    ? { suggestedAmount: (recovery.suggestedAmount ?? klass.suggestedAmount) }
+                    : {}),
+            });
+            if (!top.ok)
+                return r;
+            return proxyCall(options);
+        },
         /** The Tokenite dashboard base URL */
         baseUrl,
         /** The Tokenite proxy base URL */
@@ -212,12 +287,12 @@ const handleAuthMessage = (event, baseUrl, resolve, reject, cleanup) => {
     if (event.origin !== baseUrl)
         return;
     const data = event.data;
-    if (data.type === 'tokenite:auth-success' && data.code) {
+    if (data.type === AuthMessageType.Success && data.code) {
         cleanup();
         resolve({ code: data.code });
         return;
     }
-    if (data.type === 'tokenite:auth-error') {
+    if (data.type === AuthMessageType.Error) {
         cleanup();
         reject(new Error(data.error ?? 'Authorization denied'));
     }
@@ -258,6 +333,50 @@ const openIframeModal = (url, width, height, baseUrl) => {
         window.addEventListener('message', onMessage);
     });
 };
+const buildTopupUrl = (baseUrl, clientId, mode, suggestedAmount) => {
+    const params = new URLSearchParams({ client_id: clientId });
+    if (mode === 'popup')
+        params.set('mode', 'popup');
+    if (suggestedAmount !== undefined)
+        params.set('suggested_amount', String(suggestedAmount));
+    return `${baseUrl}/oauth/topup?${params}`;
+};
+const openTopupPopup = (url, width, height, baseUrl) => {
+    const left = Math.round(window.screenX + (window.innerWidth - width) / 2);
+    const top = Math.round(window.screenY + (window.innerHeight - height) / 2);
+    const popup = window.open(url, 'tokenite-topup', `width=${width},height=${height},left=${left},top=${top},popup=yes`);
+    if (!popup)
+        return Promise.resolve({ ok: false, reason: 'popup-blocked' });
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            window.removeEventListener('message', onMessage);
+            clearInterval(poll);
+            if (!popup.closed)
+                popup.close();
+        };
+        const onMessage = (event) => {
+            if (event.origin !== baseUrl)
+                return;
+            const data = event.data;
+            if (data.type === TopupMessageType.Success && typeof data.newLimit === 'number') {
+                cleanup();
+                resolve({ ok: true, newLimit: data.newLimit, remaining: data.remaining ?? 0 });
+                return;
+            }
+            if (data.type === TopupMessageType.Cancelled) {
+                cleanup();
+                resolve({ ok: false, reason: 'cancelled' });
+            }
+        };
+        const poll = setInterval(() => {
+            if (popup.closed) {
+                cleanup();
+                resolve({ ok: false, reason: 'closed' });
+            }
+        }, 300);
+        window.addEventListener('message', onMessage);
+    });
+};
 const openWindowPopup = (url, width, height, baseUrl, redirectUri) => {
     const left = Math.round(window.screenX + (window.innerWidth - width) / 2);
     const top = Math.round(window.screenY + (window.innerHeight - height) / 2);

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 export { Tokenite } from './client.js';
-export type { TokeniteConfig, AuthorizeOptions, PopupOptions, PopupResult, TokenResponse, Provider, ProxyCallOptions, ProxyUsage, ProxySuccess, ProxyError, ProxyResponse, ErrorSource, ProviderInfo, AppInfo, UserInfo, AccessContext, } from './types.js';
+export type { TokeniteConfig, AuthorizeOptions, PopupOptions, PopupResult, TokenResponse, Provider, ProxyCallOptions, ProxyUsage, ProxySuccess, ProxyError, ProxyResponse, ErrorSource, ProviderInfo, AppInfo, UserInfo, AccessContext, TopUpOptions, TopUpResult, CallWithRecoveryOptions, } from './types.js';
 export { isProxyError, isProxySuccess } from './types.js';
+export { parseCallback } from './parse-callback.js';
+export type { CallbackResult, CallbackSuccess, CallbackError, CallbackReason, ParseCallbackOptions, } from './parse-callback.js';
+export { isFundingError } from './recovery.js';
+export type { RecoveryClass, RecoveryKind } from './recovery.js';
+export { AuthMessageType, TopupMessageType, parseFundingDetails } from './protocol.js';
+export type { AuthMessage, TopupMessage, FundingErrorDetails } from './protocol.js';
 export { extractErrorMessage } from './error.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,7 @@
 export { Tokenite } from './client.js';
 export { isProxyError, isProxySuccess } from './types.js';
+export { parseCallback } from './parse-callback.js';
+export { isFundingError } from './recovery.js';
+export { AuthMessageType, TopupMessageType, parseFundingDetails } from './protocol.js';
 export { extractErrorMessage } from './error.js';
 //# sourceMappingURL=index.js.map

package/dist/parse-callback.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Parse the OAuth redirect callback that Tokenite sends to your app's
+ * `redirect_uri`. Returns a typed result the caller can switch on
+ * instead of hand-checking string params.
+ *
+ * ```typescript
+ * import { parseCallback } from '@tokenite/sdk';
+ *
+ * const result = parseCallback(req.url, { expectedState: storedState });
+ * if (result.ok) {
+ *   const { code } = result;
+ *   const { access_token } = await tk.exchangeCode(code);
+ *   // ...
+ * } else {
+ *   switch (result.reason) {
+ *     case 'user_denied':    return renderCancelled();      // user clicked Cancel
+ *     case 'invalid_state':  return renderRetry();          // CSRF check failed
+ *     case 'missing_code':   return renderRetry();          // user landed here directly
+ *     default:               return renderError(result);    // other OAuth error
+ *   }
+ * }
+ * ```
+ *
+ * Pure function — no side effects, no network, no SDK config needed.
+ * Works server-side (Node, edge runtimes) and in the browser.
+ */
+export type CallbackSuccess = {
+    readonly ok: true;
+    readonly code: string;
+    readonly state: string | null;
+};
+/**
+ * Why an OAuth callback didn't yield a usable authorization code.
+ *
+ * - `user_denied` — the end user clicked "Cancel" on the Tokenite
+ *   consent screen. The most common non-success case. Render a
+ *   friendly "you cancelled" UI with a "Try again" CTA, NOT a
+ *   technical error.
+ *
+ * - `access_denied` — the server returned `error=access_denied`
+ *   without the `user_denied` description. Generic access refusal
+ *   (e.g. the app's `redirect_uri` didn't match, scope was refused
+ *   by policy). Still recoverable with a retry, but the cause is
+ *   server-side rather than the user's choice.
+ *
+ * - `invalid_state` — `expectedState` was provided to `parseCallback`
+ *   and didn't match the returned `state` value. Either a stale
+ *   session or a CSRF attempt. Always reject and force a fresh
+ *   flow; never auto-retry without user interaction.
+ *
+ * - `missing_code` — neither `code` nor `error` was present in the
+ *   callback URL. Usually means the user navigated to the callback
+ *   path directly (e.g. via bookmark or browser back) rather than
+ *   completing a real OAuth round-trip.
+ *
+ * - `oauth_error` — any other OAuth 2.0 error code (`invalid_request`,
+ *   `unauthorized_client`, `server_error`, etc.). Inspect
+ *   `error` / `description` for specifics.
+ */
+export type CallbackReason = 'user_denied' | 'access_denied' | 'invalid_state' | 'missing_code' | 'oauth_error';
+export type CallbackError = {
+    readonly ok: false;
+    readonly reason: CallbackReason;
+    /** Raw OAuth error code from the URL, when present. */
+    readonly error?: string;
+    /** Raw `error_description` from the URL, when present. */
+    readonly description?: string;
+    /** The `state` value returned by Tokenite (may be null if the original flow didn't include one). */
+    readonly state: string | null;
+};
+export type CallbackResult = CallbackSuccess | CallbackError;
+export type ParseCallbackOptions = {
+    /**
+     * If provided, compare against the returned `state` query param.
+     * Mismatch → `{ ok: false, reason: 'invalid_state' }`, even if a
+     * `code` is present (a code + bad state is treated as a CSRF
+     * attempt, not a success).
+     */
+    readonly expectedState?: string;
+};
+/**
+ * Parse an OAuth callback. Accepts any of: a full URL string, a path
+ * with query string (e.g. Node's `req.url`), a `URL` object, a
+ * `URLSearchParams`, or a plain query string (with or without leading
+ * `?`).
+ */
+export declare const parseCallback: (input: string | URL | URLSearchParams, options?: ParseCallbackOptions) => CallbackResult;
+//# sourceMappingURL=parse-callback.d.ts.map

package/dist/parse-callback.js

@@ -0,0 +1,87 @@
+/**
+ * Parse the OAuth redirect callback that Tokenite sends to your app's
+ * `redirect_uri`. Returns a typed result the caller can switch on
+ * instead of hand-checking string params.
+ *
+ * ```typescript
+ * import { parseCallback } from '@tokenite/sdk';
+ *
+ * const result = parseCallback(req.url, { expectedState: storedState });
+ * if (result.ok) {
+ *   const { code } = result;
+ *   const { access_token } = await tk.exchangeCode(code);
+ *   // ...
+ * } else {
+ *   switch (result.reason) {
+ *     case 'user_denied':    return renderCancelled();      // user clicked Cancel
+ *     case 'invalid_state':  return renderRetry();          // CSRF check failed
+ *     case 'missing_code':   return renderRetry();          // user landed here directly
+ *     default:               return renderError(result);    // other OAuth error
+ *   }
+ * }
+ * ```
+ *
+ * Pure function — no side effects, no network, no SDK config needed.
+ * Works server-side (Node, edge runtimes) and in the browser.
+ */
+/**
+ * Parse an OAuth callback. Accepts any of: a full URL string, a path
+ * with query string (e.g. Node's `req.url`), a `URL` object, a
+ * `URLSearchParams`, or a plain query string (with or without leading
+ * `?`).
+ */
+export const parseCallback = (input, options = {}) => {
+    const params = toSearchParams(input);
+    const code = params.get('code');
+    const state = params.get('state');
+    const error = params.get('error');
+    const description = params.get('error_description');
+    // State validation runs first: a returned code paired with a bad
+    // state is more suspicious than no code at all (could be a planted
+    // code from an attacker hijacking the callback). Always reject.
+    if (options.expectedState !== undefined && state !== options.expectedState) {
+        return {
+            ok: false,
+            reason: 'invalid_state',
+            state,
+            ...(error !== null ? { error } : {}),
+            ...(description !== null ? { description } : {}),
+        };
+    }
+    if (error !== null) {
+        return {
+            ok: false,
+            reason: classifyError(error, description),
+            error,
+            state,
+            ...(description !== null ? { description } : {}),
+        };
+    }
+    if (code !== null && code !== '') {
+        return { ok: true, code, state };
+    }
+    return { ok: false, reason: 'missing_code', state };
+};
+const classifyError = (error, description) => {
+    if (error === 'access_denied' && description === 'user_denied')
+        return 'user_denied';
+    if (error === 'access_denied')
+        return 'access_denied';
+    return 'oauth_error';
+};
+const toSearchParams = (input) => {
+    if (input instanceof URLSearchParams)
+        return input;
+    if (input instanceof URL)
+        return input.searchParams;
+    const trimmed = input.trim();
+    // Bare query string ("?foo=bar" or "foo=bar")
+    if (trimmed.startsWith('?'))
+        return new URLSearchParams(trimmed.slice(1));
+    // Path + query ("/cb?foo=bar") or full URL ("https://x/cb?foo=bar")
+    const queryStart = trimmed.indexOf('?');
+    if (queryStart < 0)
+        return new URLSearchParams('');
+    return new URLSearchParams(trimmed.slice(queryStart + 1));
+};
+//# sourceMappingURL=parse-callback.js.map

package/dist/protocol.d.ts

@@ -0,0 +1,29 @@
+export declare const AuthMessageType: {
+    readonly Success: "tokenite:auth-success";
+    readonly Error: "tokenite:auth-error";
+};
+export declare const TopupMessageType: {
+    readonly Success: "tokenite:topup-success";
+    readonly Cancelled: "tokenite:topup-cancelled";
+};
+export type AuthMessage = {
+    readonly type: typeof AuthMessageType.Success;
+    readonly code: string;
+} | {
+    readonly type: typeof AuthMessageType.Error;
+    readonly error: string;
+};
+export type TopupMessage = {
+    readonly type: typeof TopupMessageType.Success;
+    readonly newLimit: number;
+    readonly remaining: number;
+} | {
+    readonly type: typeof TopupMessageType.Cancelled;
+};
+export type FundingErrorDetails = {
+    readonly remaining?: number;
+    readonly currentLimit?: number;
+    readonly currentSpent?: number;
+};
+export declare const parseFundingDetails: (details: unknown) => FundingErrorDetails | null;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.js

@@ -0,0 +1,23 @@
+export const AuthMessageType = {
+    Success: 'tokenite:auth-success',
+    Error: 'tokenite:auth-error',
+};
+export const TopupMessageType = {
+    Success: 'tokenite:topup-success',
+    Cancelled: 'tokenite:topup-cancelled',
+};
+const isRecord = (v) => typeof v === 'object' && v !== null;
+const numericField = (obj, key) => {
+    const v = obj[key];
+    return typeof v === 'number' ? v : undefined;
+};
+export const parseFundingDetails = (details) => {
+    if (!isRecord(details))
+        return null;
+    return {
+        ...(numericField(details, 'remaining') !== undefined ? { remaining: numericField(details, 'remaining') } : {}),
+        ...(numericField(details, 'currentLimit') !== undefined ? { currentLimit: numericField(details, 'currentLimit') } : {}),
+        ...(numericField(details, 'currentSpent') !== undefined ? { currentSpent: numericField(details, 'currentSpent') } : {}),
+    };
+};
+//# sourceMappingURL=protocol.js.map

package/dist/recovery.d.ts

@@ -0,0 +1,13 @@
+import type { ProxyError } from './types.js';
+export type RecoveryKind = 'user-topup' | 'add-key' | 'team-action' | 'sponsored-out';
+export type RecoveryClass = {
+    readonly kind: RecoveryKind;
+    readonly actor: 'user' | 'team-owner' | 'builder';
+    readonly suggestedAmount?: number;
+    readonly currentLimit?: number;
+    readonly currentSpent?: number;
+    readonly message: string;
+    readonly dashboardPath: string;
+};
+export declare const isFundingError: (error: ProxyError["error"]) => RecoveryClass | null;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.js

@@ -0,0 +1,47 @@
+import { parseFundingDetails } from './protocol.js';
+const SUGGESTED_MULTIPLIER = 2;
+export const isFundingError = (error) => {
+    switch (error.code) {
+        case 'BUDGET_EXCEEDED': {
+            const details = parseFundingDetails(error.details);
+            const currentLimit = details?.currentLimit;
+            const currentSpent = details?.currentSpent;
+            const suggestedAmount = currentLimit !== undefined
+                ? Math.max(currentLimit * SUGGESTED_MULTIPLIER, currentLimit + 1)
+                : undefined;
+            return {
+                kind: 'user-topup',
+                actor: 'user',
+                ...(currentLimit !== undefined ? { currentLimit } : {}),
+                ...(currentSpent !== undefined ? { currentSpent } : {}),
+                ...(suggestedAmount !== undefined ? { suggestedAmount } : {}),
+                message: 'Your per-app spending limit is exhausted. Raise it to continue.',
+                dashboardPath: '/oauth/topup',
+            };
+        }
+        case 'POOL_EXHAUSTED':
+            return {
+                kind: 'team-action',
+                actor: 'team-owner',
+                message: 'Your account pool budget is exhausted. The account owner must raise it.',
+                dashboardPath: '/a/_/team/pool',
+            };
+        case 'PROVIDER_KEY_MISSING':
+            return {
+                kind: 'add-key',
+                actor: 'user',
+                message: 'No provider key on file. Add one to continue.',
+                dashboardPath: '/a/_/consumer/keys',
+            };
+        case 'SPONSORED_POOL_EXHAUSTED':
+            return {
+                kind: 'sponsored-out',
+                actor: 'builder',
+                message: 'This app\'s sponsored credits are exhausted. The builder must refill.',
+                dashboardPath: '/builder/apps',
+            };
+        default:
+            return null;
+    }
+};
+//# sourceMappingURL=recovery.js.map

package/dist/types.d.ts

@@ -45,6 +45,46 @@ export type PopupResult = {
      */
     readonly code: string;
 };
+export type TopUpOptions = {
+    /**
+     * How to host the top-up screen.
+     *
+     * - `'popup'` (default) — open in a separate browser window via
+     *   `window.open`. The user completes the form; the SDK resolves
+     *   when Tokenite posts back the new limit.
+     * - `'redirect'` — full-page navigation. The builder's app loses
+     *   in-memory state and must reload from the callback URL.
+     */
+    readonly mode?: 'popup' | 'redirect';
+    /** Pre-fill the new-limit field. Default: 2 × current limit. */
+    readonly suggestedAmount?: number;
+    /** Popup width in pixels. Default: 480 */
+    readonly width?: number;
+    /** Popup height in pixels. Default: 560 */
+    readonly height?: number;
+};
+export type TopUpResult = {
+    readonly ok: true;
+    readonly newLimit: number;
+    readonly remaining: number;
+} | {
+    readonly ok: false;
+    readonly reason: 'cancelled' | 'popup-blocked' | 'closed' | 'redirected';
+};
+export type CallWithRecoveryOptions = {
+    /**
+     * What to do when the proxy returns a recoverable funding error.
+     *
+     * - `'popup'` (default) — open Tokenite's top-up popup, then retry the
+     *   call once on success.
+     * - `'redirect'` — full-page navigation; the call does not retry (the
+     *   builder's app re-loads from the callback and re-invokes manually).
+     * - `'throw'` — disable recovery; surface the original error.
+     */
+    readonly onFundingNeeded?: 'popup' | 'redirect' | 'throw';
+    /** Override the suggested top-up amount. */
+    readonly suggestedAmount?: number;
+};
 export type TokenResponse = {
     readonly access_token: string;
     readonly token_type: string;
@@ -175,12 +215,6 @@ export type AppInfo = {
     readonly websiteUrl: string | null;
     /** Absolute URL to the app's icon (PNG/SVG). null when the developer hasn't set one — render initials or a generic glyph. */
     readonly iconUrl: string | null;
-    /** Providers the app declares it needs */
-    readonly requiredProviders: readonly Provider[];
-    /** Fallback order when `allowSubstitution` is true */
-    readonly preferredProviders: readonly Provider[];
-    /** Whether the app accepts substitute providers when a required one isn't available */
-    readonly allowSubstitution: boolean;
 };
 /**
  * Full access context for a single access token: the app it belongs to,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenite/sdk",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "SDK for integrating \"Login with Tokenite\" into your app. Your users bring their own AI tokens — you pay nothing.",
   "type": "module",
   "exports": {