@tokenite/sdk 1.0.0

package/dist/client.js

@@ -0,0 +1,313 @@
+import { extractErrorMessage } from './error.js';
+const DEFAULT_BASE_URL = 'https://tokenite.ai';
+const DEFAULT_PROXY_URL = 'https://api.tokenite.ai';
+const IFRAME_WIDTH = 480;
+const IFRAME_HEIGHT = 620;
+/**
+ * Tokenite client.
+ *
+ * Two ways to obtain an access token:
+ *
+ * **Modal (single-page apps)** — open an iframe consent screen and
+ * receive an OAuth authorization code. The code must be exchanged
+ * server-side because the exchange requires `clientSecret`:
+ * ```typescript
+ * const { code } = await tk.popup({ suggestedBudget: 5 });
+ * await fetch('/api/auth/exchange', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ code }),
+ * });
+ * ```
+ *
+ * **Redirect (server-side)** — classic OAuth bounce:
+ * ```typescript
+ * res.redirect(tk.getAuthorizeUrl());
+ * // ...later in /callback:
+ * const { access_token } = await tk.exchangeCode(req.query.code);
+ * ```
+ *
+ * Once you have the access token, call the LLM through the proxy:
+ * ```typescript
+ * const result = await tk.call({
+ *   accessToken,
+ *   provider: 'anthropic',
+ *   path: '/v1/messages',
+ *   body: { model: 'claude-3-5-sonnet-latest', max_tokens: 1024, messages: [...] },
+ * });
+ * if (isProxyError(result)) console.error(result.error);
+ * else console.log(result.data);
+ * ```
+ *
+ * For streaming responses, use a vendor SDK with `baseURL: tk.proxyUrl(...)`
+ * — streams bypass the unified envelope and are forwarded as-is.
+ */
+export const Tokenite = (config) => {
+    const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    const proxyBase = config.proxyUrl ?? DEFAULT_PROXY_URL;
+    const buildAuthorizeUrl = (options) => {
+        const state = options?.state ?? generateState();
+        const params = new URLSearchParams({
+            client_id: config.clientId,
+            redirect_uri: config.redirectUri,
+            response_type: 'code',
+            state,
+        });
+        if (options?.suggestedBudget)
+            params.set('suggested_budget', String(options.suggestedBudget));
+        if (options?.mode)
+            params.set('mode', options.mode);
+        return `${baseUrl}/oauth/authorize?${params}`;
+    };
+    return {
+        /**
+         * Build the authorization URL for a full-page redirect.
+         * Supports optional suggested budget that pre-fills the consent screen.
+         */
+        getAuthorizeUrl: (options) => buildAuthorizeUrl(options),
+        /**
+         * Open the consent screen and resolve with an OAuth authorization
+         * code when the user approves. The code must then be exchanged
+         * server-side via `tk.exchangeCode(code)` (the exchange requires
+         * `clientSecret`, which must never run in browser code).
+         *
+         * Two presentation modes:
+         *
+         * - `mode: 'iframe'` (default) — overlay an iframe modal in the
+         *   current window. Cleaner UX, but the consent screen's host must
+         *   allow being framed (no `X-Frame-Options: DENY`).
+         * - `mode: 'window'` — open a separate browser popup window via
+         *   `window.open`. Works regardless of frame policy.
+         *
+         * ```typescript
+         * const { code } = await tk.popup({ suggestedBudget: 5 });
+         * await fetch('/api/auth/exchange', {
+         *   method: 'POST',
+         *   body: JSON.stringify({ code }),
+         * });
+         * ```
+         */
+        popup: (options) => {
+            const mode = options?.mode ?? 'iframe';
+            const width = options?.width ?? IFRAME_WIDTH;
+            const height = options?.height ?? IFRAME_HEIGHT;
+            // The SDK's `window` mode maps to the dashboard's `popup` URL
+            // param (separate browser window with `window.opener`); the
+            // SDK's `iframe` mode maps to the dashboard's `iframe` URL param
+            // (postMessage to `window.parent`).
+            const url = buildAuthorizeUrl({
+                suggestedBudget: options?.suggestedBudget,
+                mode: mode === 'window' ? 'popup' : 'iframe',
+            });
+            return mode === 'window'
+                ? openWindowPopup(url, width, height, baseUrl, config.redirectUri)
+                : openIframeModal(url, width, height, baseUrl);
+        },
+        /**
+         * Exchange an authorization code for an access token.
+         * Call this server-side in your callback handler.
+         * Requires clientSecret to be set in config.
+         */
+        exchangeCode: async (code) => {
+            if (!config.clientSecret)
+                throw new Error('clientSecret is required for exchangeCode (server-side only)');
+            const response = await fetch(`${baseUrl}/api/oauth/token`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    code,
+                    client_id: config.clientId,
+                    client_secret: config.clientSecret,
+                    redirect_uri: config.redirectUri,
+                }),
+            });
+            if (!response.ok) {
+                const body = await response.json().catch(() => null);
+                throw new Error(extractErrorMessage(body, `Token exchange failed (${response.status})`));
+            }
+            return response.json();
+        },
+        /**
+         * Make an authenticated, non-streaming request through the proxy.
+         * Returns a unified envelope: `ProxySuccess` on success, `ProxyError`
+         * on failure. Narrow the result with `isProxyError` / `isProxySuccess`.
+         *
+         * For streaming responses, use a vendor SDK with `baseURL: tk.proxyUrl(...)`
+         * — streams bypass the envelope and are forwarded as-is.
+         *
+         * ```typescript
+         * const result = await tk.call({
+         *   accessToken,
+         *   provider: 'anthropic',
+         *   path: '/v1/messages',
+         *   body: { model: 'claude-3-5-sonnet-latest', max_tokens: 1024, messages: [...] },
+         * });
+         * ```
+         */
+        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());
+        },
+        /**
+         * Fetch the access context for an access token: which app it belongs
+         * to and which providers the user has authorised it to call.
+         *
+         * The returned `providers` list is exactly the set that will succeed
+         * through `tk.call()` (budget permitting). Use it to render a picker,
+         * gate UI, or detect that the user is missing a required provider.
+         *
+         * ```typescript
+         * const { app, providers } = await tk.getAllowedProviders(accessToken);
+         * for (const p of providers) {
+         *   console.log(p.displayName, p.logoUrl);
+         * }
+         * ```
+         */
+        getAllowedProviders: async (accessToken) => {
+            const response = await fetch(`${proxyBase}/me/providers`, {
+                headers: { 'authorization': `Bearer ${accessToken}` },
+            });
+            if (!response.ok) {
+                const body = await response.json().catch(() => null);
+                throw new Error(extractErrorMessage(body, `Failed to fetch allowed providers (${response.status})`));
+            }
+            const data = (await response.json());
+            return {
+                ...data,
+                providers: data.providers.map((p) => ({
+                    ...p,
+                    logoUrl: absoluteUrl(p.logoUrl, baseUrl),
+                })),
+            };
+        },
+        /**
+         * Get the proxy URL for a specific provider.
+         * Use as `baseURL` in a vendor SDK for streaming requests, which
+         * bypass the unified envelope.
+         */
+        proxyUrl: (provider) => `${proxyBase}/${provider}`,
+        /** The Tokenite dashboard base URL */
+        baseUrl,
+        /** The Tokenite proxy base URL */
+        proxyBase,
+    };
+};
+const generateState = () => Array.from(crypto.getRandomValues(new Uint8Array(16)))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+const absoluteUrl = (maybeRelative, base) => /^https?:\/\//i.test(maybeRelative) ? maybeRelative : `${base}${maybeRelative}`;
+// ─── Popup hosts ───
+//
+// Two transports for the consent screen, sharing the same postMessage
+// protocol with the dashboard:
+//   { type: 'tokenite:auth-success', code }
+//   { type: 'tokenite:auth-error',   error }
+const openIframeModal = (url, width, height, baseUrl) => {
+    const overlay = document.createElement('div');
+    overlay.style.cssText = `
+    position: fixed; inset: 0; z-index: 999999;
+    background: rgba(0,0,0,0.5); backdrop-filter: blur(2px);
+    display: flex; align-items: center; justify-content: center;
+  `;
+    const container = document.createElement('div');
+    container.style.cssText = `
+    background: white; border-radius: 12px; overflow: hidden;
+    box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+    width: ${width}px; max-width: calc(100vw - 32px);
+    height: ${height}px; max-height: calc(100vh - 32px);
+  `;
+    const iframe = document.createElement('iframe');
+    iframe.src = url;
+    iframe.style.cssText = `width: 100%; height: 100%; border: none;`;
+    iframe.setAttribute('allow', 'clipboard-write');
+    container.appendChild(iframe);
+    overlay.appendChild(container);
+    document.body.appendChild(overlay);
+    return new Promise((resolve, reject) => {
+        const onMessage = (event) => {
+            if (event.origin !== baseUrl)
+                return;
+            const data = event.data;
+            if (data.type === 'tokenite:auth-success' && data.code) {
+                cleanup();
+                resolve({ code: data.code });
+            }
+            if (data.type === 'tokenite:auth-error') {
+                cleanup();
+                reject(new Error(data.error ?? 'Authorization denied'));
+            }
+        };
+        const cleanup = () => {
+            window.removeEventListener('message', onMessage);
+            overlay.remove();
+        };
+        overlay.addEventListener('click', (e) => {
+            if (e.target === overlay) {
+                cleanup();
+                reject(new Error('Authorization cancelled'));
+            }
+        });
+        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);
+    const popup = window.open(url, 'tokenite-auth', `width=${width},height=${height},left=${left},top=${top},popup=yes`);
+    if (!popup)
+        return Promise.reject(new Error('Popup blocked'));
+    return new Promise((resolve, reject) => {
+        const onMessage = (event) => {
+            if (event.origin !== baseUrl)
+                return;
+            const data = event.data;
+            if (data.type === 'tokenite:auth-success' && data.code) {
+                cleanup();
+                resolve({ code: data.code });
+            }
+            if (data.type === 'tokenite:auth-error') {
+                cleanup();
+                reject(new Error(data.error ?? 'Authorization denied'));
+            }
+        };
+        // Cross-origin popups can't postMessage until they navigate back to
+        // our origin (the redirect URI). As a fallback, poll for that
+        // navigation by trying to read the popup's URL — same-origin reads
+        // succeed, cross-origin throws and we keep polling.
+        const poll = setInterval(() => {
+            if (popup.closed) {
+                cleanup();
+                reject(new Error('Popup closed'));
+                return;
+            }
+            try {
+                const popupUrl = popup.location.href;
+                if (popupUrl.startsWith(redirectUri)) {
+                    const code = new URL(popupUrl).searchParams.get('code');
+                    if (code) {
+                        cleanup();
+                        resolve({ code });
+                    }
+                }
+            }
+            catch {
+                // cross-origin — keep polling
+            }
+        }, 300);
+        const cleanup = () => {
+            window.removeEventListener('message', onMessage);
+            clearInterval(poll);
+            if (!popup.closed)
+                popup.close();
+        };
+        window.addEventListener('message', onMessage);
+    });
+};
+//# sourceMappingURL=client.js.map

package/dist/error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extract a human-readable error message from a Tokenite-style envelope.
+ *
+ * The dashboard returns `{ error: { code, message, status?, details? } }`
+ * for structured errors and (rarely) `{ error: "literal message" }` from
+ * legacy paths. This helper unifies both shapes and falls back to a
+ * caller-supplied default when the body is missing or malformed.
+ */
+export declare const extractErrorMessage: (body: unknown, fallback: string) => string;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.js

@@ -0,0 +1,18 @@
+/**
+ * Extract a human-readable error message from a Tokenite-style envelope.
+ *
+ * The dashboard returns `{ error: { code, message, status?, details? } }`
+ * for structured errors and (rarely) `{ error: "literal message" }` from
+ * legacy paths. This helper unifies both shapes and falls back to a
+ * caller-supplied default when the body is missing or malformed.
+ */
+export const extractErrorMessage = (body, fallback) => {
+    const err = body?.error;
+    if (typeof err === 'string')
+        return err;
+    if (err && typeof err === 'object' && 'message' in err && typeof err.message === 'string') {
+        return err.message;
+    }
+    return fallback;
+};
+//# sourceMappingURL=error.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Tokenite } from './client.js';
+export type { TokeniteConfig, AuthorizeOptions, PopupOptions, PopupResult, TokenResponse, Provider, ProxyCallOptions, ProxyUsage, ProxySuccess, ProxyError, ProxyResponse, ErrorSource, ProviderInfo, AppInfo, AllowedProvidersResponse, } from './types.js';
+export { isProxyError, isProxySuccess } from './types.js';
+export { extractErrorMessage } from './error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Tokenite } from './client.js';
+export { isProxyError, isProxySuccess } from './types.js';
+export { extractErrorMessage } from './error.js';
+//# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -0,0 +1,181 @@
+export type TokeniteConfig = {
+    /** Your app's client ID (from the Tokenite dashboard) */
+    readonly clientId: string;
+    /** Your app's client secret — only needed for server-side code exchange */
+    readonly clientSecret?: string;
+    /** The URL Tokenite redirects back to after authorization */
+    readonly redirectUri: string;
+    /** Tokenite base URL. Default: https://tokenite.ai */
+    readonly baseUrl?: string;
+    /** Tokenite proxy URL. Default: https://api.tokenite.ai */
+    readonly proxyUrl?: string;
+};
+export type AuthorizeOptions = {
+    /** Custom state parameter for CSRF protection. Auto-generated if not provided. */
+    readonly state?: string;
+    /** Suggested budget amount (user can override on consent screen) */
+    readonly suggestedBudget?: number;
+};
+export type PopupOptions = {
+    /** Suggested budget amount (user can override on consent screen) */
+    readonly suggestedBudget?: number;
+    /**
+     * How to host the consent screen.
+     *
+     * - `'iframe'` (default) — overlay an iframe modal in the current
+     *   window. Requires the dashboard to allow being framed by your
+     *   origin (`Content-Security-Policy: frame-ancestors`). Cleaner UX
+     *   but blocked by `X-Frame-Options: DENY`.
+     * - `'window'` — open a separate browser popup window via
+     *   `window.open`. Works regardless of frame policy, but the user
+     *   may be prompted by their popup blocker.
+     */
+    readonly mode?: 'iframe' | 'window';
+    /** Modal/popup width in pixels. Default: 480 */
+    readonly width?: number;
+    /** Modal/popup height in pixels. Default: 620 */
+    readonly height?: number;
+};
+export type PopupResult = {
+    /**
+     * OAuth authorization code returned by the consent screen.
+     * Send this to your backend, which exchanges it for an access token
+     * via `tk.exchangeCode(code)`. The exchange requires `clientSecret`
+     * and must never run in browser code.
+     */
+    readonly code: string;
+};
+export type TokenResponse = {
+    readonly access_token: string;
+    readonly token_type: string;
+};
+export type Provider = 'anthropic' | 'openai' | 'google' | 'grok' | 'bedrock';
+export type ProxyCallOptions = {
+    /** The user's Tokenite access token (returned by `tk.exchangeCode()`) */
+    readonly accessToken: string;
+    /** Which LLM provider to call */
+    readonly provider: Provider;
+    /** Path on the provider's API (e.g. `/v1/messages`, `/v1/chat/completions`) */
+    readonly path: string;
+    /** HTTP method. Default: `POST` */
+    readonly method?: string;
+    /** Request body — the vendor's request shape, JSON-serialised by the SDK */
+    readonly body: unknown;
+};
+/** Normalised token counts (identical across all providers) */
+export type ProxyUsage = {
+    /** Number of tokens in the prompt / input */
+    readonly inputTokens: number;
+    /** Number of tokens in the completion / output */
+    readonly outputTokens: number;
+};
+/**
+ * Successful proxy response.
+ *
+ * `data` contains the original vendor response body (e.g. Anthropic's
+ * message object, OpenAI's chat completion, etc.). `provider`, `model`,
+ * and `usage` are extracted and normalised by the proxy so you don't
+ * need to parse vendor-specific fields.
+ */
+export type ProxySuccess = {
+    /** Which LLM provider handled the request */
+    readonly provider: Provider;
+    /** The model that generated the response */
+    readonly model: string;
+    /** Normalised token usage, or null if the provider didn't report it */
+    readonly usage: ProxyUsage | null;
+    /** The original, unmodified response body from the LLM provider */
+    readonly data: unknown;
+};
+/**
+ * Where the error originated.
+ *
+ * - `"proxy"` — Tokenite rejected the request (auth, budget, config).
+ * - `"provider"` — The upstream LLM returned an error (rate limit, overload, etc.).
+ */
+export type ErrorSource = 'proxy' | 'provider';
+/**
+ * Error response (both proxy-level and provider-level errors share this shape).
+ *
+ * **Proxy error codes** (`source: "proxy"`):
+ * | Code | HTTP | Description |
+ * |---|---|---|
+ * | `TOKEN_INVALID` | 401 | Missing or invalid bearer token |
+ * | `TOKEN_REVOKED` | 401 | Access token was revoked by the user |
+ * | `TOKEN_SUSPENDED` | 403 | Access suspended by the user |
+ * | `TOKEN_EXPIRED` | 401 | Access token past its expiration date |
+ * | `BUDGET_EXCEEDED` | 402 | Spending reached the user-defined budget limit |
+ * | `PROVIDER_KEY_MISSING` | 402 | No API key or credits available for the provider |
+ * | `CREDITS_DEPLETED` | 402 | Insufficient platform credits |
+ * | `APP_NOT_FOUND` | 404 | Application not found |
+ * | `MODEL_NOT_ALLOWED` | 403 | Model not in the app's allowed models list |
+ *
+ * **Provider error codes** (`source: "provider"`):
+ * | Code | HTTP | Description |
+ * |---|---|---|
+ * | `RATE_LIMITED` | 429 | Upstream rate limit hit — retry after backoff |
+ * | `CONTEXT_LENGTH_EXCEEDED` | 400 | Request exceeds model's context window |
+ * | `INVALID_REQUEST` | 400 | Provider rejected the request as malformed |
+ * | `AUTHENTICATION_FAILED` | 401 | Provider rejected the API key |
+ * | `PROVIDER_OVERLOADED` | 503 | Provider temporarily overloaded |
+ * | `CONTENT_FILTERED` | 400 | Content blocked by safety filter |
+ * | `PROVIDER_TIMEOUT` | 504 | Provider did not respond in time |
+ * | `PROVIDER_ERROR` | 502 | Catch-all for other provider errors |
+ */
+export type ProxyError = {
+    readonly error: {
+        /** Machine-readable error code */
+        readonly code: string;
+        /** Human-readable description */
+        readonly message: string;
+        /** Where the error originated */
+        readonly source: ErrorSource;
+        /** Optional structured context (e.g. `retryAfter`, `provider`, `providerMessage`) */
+        readonly details?: Record<string, unknown>;
+    };
+};
+/** Discriminated union for all non-streaming proxy responses */
+export type ProxyResponse = ProxySuccess | ProxyError;
+/** Type guard: returns true if the response is an error */
+export declare const isProxyError: (response: ProxyResponse) => response is ProxyError;
+/** Type guard: returns true if the response is a success */
+export declare const isProxySuccess: (response: ProxyResponse) => response is ProxySuccess;
+/** Visual + identity metadata for a single provider */
+export type ProviderInfo = {
+    /** Stable provider id (same value as the `Provider` union) */
+    readonly id: Provider;
+    /** Human-readable name, e.g. "Anthropic" */
+    readonly displayName: string;
+    /** Brand colour (hex string, e.g. "#d97706") */
+    readonly color: string;
+    /** Absolute URL to the provider's logo (PNG or SVG) */
+    readonly logoUrl: string;
+    /** Whether the logo is a glyph/symbol or a full wordmark */
+    readonly logoStyle: 'symbol' | 'wordmark';
+};
+/** Summary of the app the access token belongs to */
+export type AppInfo = {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string | null;
+    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.
+ *
+ * `providers` lists only the providers the user has an active key for —
+ * exactly the set that will succeed through `tk.call()` (budget permitting).
+ */
+export type AllowedProvidersResponse = {
+    readonly app: AppInfo;
+    readonly providers: readonly ProviderInfo[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,5 @@
+/** Type guard: returns true if the response is an error */
+export const isProxyError = (response) => 'error' in response;
+/** Type guard: returns true if the response is a success */
+export const isProxySuccess = (response) => 'provider' in response;
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@tokenite/sdk",
+  "version": "1.0.0",
+  "description": "SDK for integrating \"Login with Tokenite\" into your app. Your users bring their own AI tokens — you pay nothing.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "import": "./dist/admin/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "tokenite",
+    "llm",
+    "ai",
+    "proxy",
+    "oauth",
+    "byok",
+    "anthropic",
+    "openai",
+    "google"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc && npm run generate-readme",
+    "typecheck": "tsc --noEmit",
+    "generate-readme": "npx tsx scripts/generate-readme.ts"
+  }
+}