@circle-rd/auth-ai 0.0.0-stage → 0.1.0

package/dist/server/protected-resource.d.ts

@@ -0,0 +1,27 @@
+import type { AuthClient } from "../client.js";
+export interface ProtectedResourceMetadataOptions {
+    /** The audience this API accepts: its RFC 8707 resource identifier. */
+    readonly resource: string;
+    readonly scopesSupported?: readonly string[];
+}
+export interface ProtectedResourceMetadata {
+    readonly resource: string;
+    readonly authorization_servers: readonly string[];
+    readonly bearer_methods_supported: readonly ["header"];
+    readonly scopes_supported?: readonly string[];
+}
+/** RFC 9728 metadata, which lets MCP and OAuth clients find the authorization server. */
+export declare function protectedResourceMetadata(auth: Pick<AuthClient, "config">, options: ProtectedResourceMetadataOptions): ProtectedResourceMetadata;
+/**
+ * Where RFC 9728 §3 serves the metadata of `resource`: the well-known segment
+ * sits between the host and the resource path.
+ */
+export declare function protectedResourceMetadataPath(resource: string): string;
+export interface BearerChallengeOptions {
+    /** Absolute URL of the metadata document, advertised to unauthenticated clients. */
+    readonly resourceMetadataUrl: string;
+    readonly error?: "invalid_token" | "insufficient_scope";
+    readonly scope?: string;
+}
+/** Value of the `WWW-Authenticate` header of a 401 or 403 response. */
+export declare function bearerChallenge(options: BearerChallengeOptions): string;

package/dist/server/protected-resource.js

@@ -0,0 +1,37 @@
+import { ERR } from "../errors.js";
+/** RFC 9728 metadata, which lets MCP and OAuth clients find the authorization server. */
+export function protectedResourceMetadata(auth, options) {
+    return {
+        resource: options.resource,
+        authorization_servers: [auth.config.issuer],
+        bearer_methods_supported: ["header"],
+        ...(options.scopesSupported
+            ? { scopes_supported: options.scopesSupported }
+            : {}),
+    };
+}
+/**
+ * Where RFC 9728 §3 serves the metadata of `resource`: the well-known segment
+ * sits between the host and the resource path.
+ */
+export function protectedResourceMetadataPath(resource) {
+    const { pathname } = new URL(resource);
+    return `/.well-known/oauth-protected-resource${pathname === "/" ? "" : pathname}`;
+}
+const UNSAFE_PARAMETER = /["\\\r\n]/;
+/** Value of the `WWW-Authenticate` header of a 401 or 403 response. */
+export function bearerChallenge(options) {
+    const parameters = [
+        ["resource_metadata", options.resourceMetadataUrl],
+    ];
+    if (options.error)
+        parameters.push(["error", options.error]);
+    if (options.scope)
+        parameters.push(["scope", options.scope]);
+    for (const [name, value] of parameters) {
+        if (UNSAFE_PARAMETER.test(value)) {
+            throw ERR.CFG_001(`Invalid ${name} in a Bearer challenge`);
+        }
+    }
+    return `Bearer ${parameters.map(([name, value]) => `${name}="${value}"`).join(", ")}`;
+}

package/dist/session-user.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { IdTokenClaims } from "./claims.js";
+/**
+ * What a signed-in user looks like to the application's frontend: profile and
+ * entitlements, with the absent claims normalised to empty values. Tokens,
+ * `sid` and timestamps never reach the browser.
+ */
+export declare const sessionUserSchema: z.ZodObject<{
+    sub: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    emailVerified: z.ZodOptional<z.ZodBoolean>;
+    picture: z.ZodOptional<z.ZodString>;
+    roles: z.ZodArray<z.ZodString>;
+    permissions: z.ZodArray<z.ZodString>;
+    features: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    plan: z.ZodOptional<z.ZodString>;
+    orgId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SessionUser = z.infer<typeof sessionUserSchema>;
+export declare function toSessionUser(claims: IdTokenClaims): SessionUser;

package/dist/session-user.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+const featureValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+/**
+ * What a signed-in user looks like to the application's frontend: profile and
+ * entitlements, with the absent claims normalised to empty values. Tokens,
+ * `sid` and timestamps never reach the browser.
+ */
+export const sessionUserSchema = z.object({
+    sub: z.string(),
+    name: z.string().optional(),
+    email: z.string().optional(),
+    emailVerified: z.boolean().optional(),
+    picture: z.string().optional(),
+    roles: z.array(z.string()),
+    permissions: z.array(z.string()),
+    features: z.record(z.string(), featureValueSchema),
+    plan: z.string().optional(),
+    orgId: z.string().optional(),
+});
+export function toSessionUser(claims) {
+    return {
+        sub: claims.sub,
+        roles: claims.roles ?? [],
+        permissions: claims.permissions ?? [],
+        features: claims.features ?? {},
+        ...(claims.name === undefined ? {} : { name: claims.name }),
+        ...(claims.email === undefined ? {} : { email: claims.email }),
+        ...(claims.email_verified === undefined
+            ? {}
+            : { emailVerified: claims.email_verified }),
+        ...(claims.picture === undefined ? {} : { picture: claims.picture }),
+        ...(claims.plan === undefined ? {} : { plan: claims.plan }),
+        ...(claims.org_id === undefined ? {} : { orgId: claims.org_id }),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+import type { IdTokenClaims } from "./claims.js";
+export interface TokenSet {
+    readonly accessToken: string;
+    readonly tokenType: string;
+    /** Unix seconds. */
+    readonly expiresAt: number;
+    readonly scope?: string;
+    /** Absent when the provider issued none (no `offline_access`, or no rotation). */
+    readonly refreshToken?: string;
+    readonly idToken?: string;
+}
+/**
+ * Secrets of one sign-in attempt. The caller persists them (typically in a
+ * short-lived sealed cookie) between the redirect and the callback.
+ */
+export interface LoginHandshake {
+    readonly state: string;
+    readonly nonce: string;
+    readonly codeVerifier: string;
+}
+export interface LoginRequest {
+    readonly url: string;
+    readonly handshake: LoginHandshake;
+}
+export interface StartLoginOptions {
+    readonly prompt?: "login" | "consent" | "select_account" | "create" | "none";
+    readonly loginHint?: string;
+}
+export interface LoginResult {
+    readonly tokens: TokenSet & {
+        readonly idToken: string;
+    };
+    readonly claims: IdTokenClaims;
+    /** The provider session, only present when end-session or back-channel logout is enabled for the application. */
+    readonly sessionId: string | undefined;
+}
+export interface RefreshOptions {
+    /** Narrows the new access token to one RFC 8707 audience. */
+    readonly resource?: string;
+}
+export interface ClientCredentialsOptions {
+    /** Space-separated machine scopes, e.g. `billing:read`. */
+    readonly scope?: string;
+    readonly resource?: string;
+}
+export interface LogoutUrlOptions {
+    readonly idTokenHint?: string;
+    readonly state?: string;
+}
+export type TokenTypeHint = "access_token" | "refresh_token";

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/vue/index.d.ts

@@ -0,0 +1,42 @@
+import type { App, ComputedRef, ShallowRef } from "vue";
+import type { BrowserAuth, WalletView } from "../browser/client.js";
+import type { AuthState, ResourceState } from "../browser/store.js";
+import type { FeatureValue, PermissionAction } from "../claims.js";
+import type { GatewayModel } from "../gateway.js";
+import type { SessionUser } from "../session-user.js";
+import type { WalletStats } from "../wallet.js";
+export interface AuthPluginOptions {
+    /** Defaults to a client on `basePath`. */
+    readonly auth?: BrowserAuth;
+    readonly basePath?: string;
+}
+/** `app.use(createAuthPlugin())` reads the session once the app is mounted in a browser. */
+export declare function createAuthPlugin(options?: AuthPluginOptions): {
+    install(app: App): void;
+};
+export interface UseAuthResult {
+    readonly state: Readonly<ShallowRef<AuthState>>;
+    readonly user: ComputedRef<SessionUser | null>;
+    readonly login: (next?: string) => void;
+    readonly logout: () => Promise<void>;
+    readonly refresh: () => Promise<void>;
+}
+export declare function useAuth(): UseAuthResult;
+export interface Entitlements {
+    hasRole(role: string): boolean;
+    hasPermission(resource: string, action?: PermissionAction): boolean;
+    hasFeature(key: string): boolean;
+    getFeature(key: string): FeatureValue | undefined;
+}
+/** Entitlement checks reading the current user at call time, so templates stay reactive. */
+export declare function useEntitlements(): Entitlements;
+export interface UseResourceResult<T> {
+    readonly state: Readonly<ShallowRef<ResourceState<T>>>;
+    readonly refresh: () => Promise<void>;
+}
+export interface UseWalletOptions {
+    readonly pollIntervalMs?: number;
+}
+export declare function useWallet(options?: UseWalletOptions): UseResourceResult<WalletView>;
+export declare function useWalletStats(days?: number): UseResourceResult<WalletStats>;
+export declare function useModels(): UseResourceResult<GatewayModel[]>;

package/dist/vue/index.js

@@ -0,0 +1,82 @@
+import { computed, getCurrentScope, inject, onScopeDispose, shallowRef, } from "vue";
+import { createBrowserAuth } from "../browser/client.js";
+import { createAuthStore, createResourceStore } from "../browser/store.js";
+import { getFeature, hasFeature, hasPermission, hasRole } from "../claims.js";
+const AUTH_KEY = Symbol("auth-ai");
+/** `app.use(createAuthPlugin())` reads the session once the app is mounted in a browser. */
+export function createAuthPlugin(options = {}) {
+    return {
+        install(app) {
+            const auth = options.auth ??
+                createBrowserAuth(options.basePath ? { basePath: options.basePath } : {});
+            const store = createAuthStore(auth);
+            app.provide(AUTH_KEY, { auth, store });
+            if (typeof window !== "undefined")
+                void store.refresh();
+        },
+    };
+}
+function useContext() {
+    const context = inject(AUTH_KEY, null);
+    if (!context)
+        throw new Error("Install createAuthPlugin() on the app");
+    return context;
+}
+/** A ref that follows an observable until the calling scope is disposed. */
+function follow(source) {
+    const state = shallowRef(source.get());
+    const stop = source.subscribe(() => {
+        state.value = source.get();
+    });
+    if (getCurrentScope())
+        onScopeDispose(stop);
+    return state;
+}
+export function useAuth() {
+    const { auth, store } = useContext();
+    const state = follow(store.state);
+    return {
+        state,
+        user: computed(() => state.value.user),
+        login: (next) => auth.login(next),
+        logout: () => auth.logout(),
+        refresh: () => store.refresh(),
+    };
+}
+/** Entitlement checks reading the current user at call time, so templates stay reactive. */
+export function useEntitlements() {
+    const { user } = useAuth();
+    return {
+        hasRole: (role) => hasRole(user.value ?? {}, role),
+        hasPermission: (resource, action) => hasPermission(user.value ?? {}, resource, action),
+        hasFeature: (key) => hasFeature(user.value ?? {}, key),
+        getFeature: (key) => getFeature(user.value ?? {}, key),
+    };
+}
+function useResource(load, options = {}) {
+    const { auth, store } = useContext();
+    const resource = createResourceStore(() => load(auth), {
+        ...options,
+        onError: (error) => {
+            if (error.code === "SES_001")
+                void store.refresh();
+        },
+    });
+    const state = follow(resource.state);
+    if (getCurrentScope())
+        onScopeDispose(resource.start());
+    else
+        void resource.refresh();
+    return { state, refresh: resource.refresh };
+}
+export function useWallet(options = {}) {
+    return useResource((auth) => auth.getWallet(), options.pollIntervalMs === undefined
+        ? {}
+        : { pollIntervalMs: options.pollIntervalMs });
+}
+export function useWalletStats(days) {
+    return useResource((auth) => auth.getWalletStats(days));
+}
+export function useModels() {
+    return useResource((auth) => auth.listModels());
+}

package/dist/wallet.d.ts

@@ -0,0 +1,182 @@
+import { z } from "zod";
+import type { JsonHttp } from "./http.js";
+/** 1 EUR in the ledger unit. */
+export declare const MICRO_PER_EUR = 1000000n;
+export declare const walletTransactionTypeSchema: z.ZodEnum<{
+    topup: "topup";
+    grant: "grant";
+    refund: "refund";
+    usage: "usage";
+    adjust: "adjust";
+    reversal: "reversal";
+}>;
+export declare const walletAccountSchema: z.ZodObject<{
+    balance: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    isUnlimited: z.ZodBoolean;
+    canSpend: z.ZodBoolean;
+    currency: z.ZodLiteral<"eur">;
+}, z.core.$strip>;
+export declare const walletTransactionSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        topup: "topup";
+        grant: "grant";
+        refund: "refund";
+        usage: "usage";
+        adjust: "adjust";
+        reversal: "reversal";
+    }>;
+    amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    delta: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    balanceAfter: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    applicationId: z.ZodNullable<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const walletTransactionPageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            topup: "topup";
+            grant: "grant";
+            refund: "refund";
+            usage: "usage";
+            adjust: "adjust";
+            reversal: "reversal";
+        }>;
+        amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        delta: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        balanceAfter: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        applicationId: z.ZodNullable<z.ZodString>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const walletStatsSchema: z.ZodObject<{
+    days: z.ZodNumber;
+    total: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    notBilled: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    calls: z.ZodNumber;
+    series: z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    byApplication: z.ZodArray<z.ZodObject<{
+        applicationId: z.ZodNullable<z.ZodString>;
+        name: z.ZodNullable<z.ZodString>;
+        slug: z.ZodNullable<z.ZodString>;
+        amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    byKind: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    byModel: z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        count: z.ZodNumber;
+        promptTokens: z.ZodNumber;
+        completionTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+    daily: z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        count: z.ZodNumber;
+        byApplication: z.ZodArray<z.ZodObject<{
+            applicationId: z.ZodNullable<z.ZodString>;
+            name: z.ZodNullable<z.ZodString>;
+            slug: z.ZodNullable<z.ZodString>;
+            amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+        byModel: z.ZodArray<z.ZodObject<{
+            model: z.ZodString;
+            amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+            count: z.ZodNumber;
+            promptTokens: z.ZodNumber;
+            completionTokens: z.ZodNumber;
+            totalTokens: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const walletSessionUsageSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    applicationSlug: z.ZodNullable<z.ZodString>;
+    days: z.ZodNumber;
+    total: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    notBilled: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    calls: z.ZodNumber;
+    byModel: z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        count: z.ZodNumber;
+        promptTokens: z.ZodNumber;
+        completionTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const topupOptionsSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    currency: z.ZodLiteral<"eur">;
+    minCents: z.ZodNumber;
+    maxCents: z.ZodNumber;
+}, z.core.$strip>;
+export type WalletAccount = z.infer<typeof walletAccountSchema>;
+export type WalletTransaction = z.infer<typeof walletTransactionSchema>;
+export type WalletTransactionPage = z.infer<typeof walletTransactionPageSchema>;
+export type WalletTransactionType = z.infer<typeof walletTransactionTypeSchema>;
+export type WalletStats = z.infer<typeof walletStatsSchema>;
+export type WalletSessionUsage = z.infer<typeof walletSessionUsageSchema>;
+export type TopupOptions = z.infer<typeof topupOptionsSchema>;
+export interface WalletStatsOptions {
+    /** 1 to 90, 30 by default. */
+    readonly days?: number;
+}
+export interface WalletSessionUsageOptions {
+    /** 1 to 90, 30 by default. */
+    readonly days?: number;
+}
+export interface ListTransactionsOptions {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly type?: WalletTransactionType;
+}
+/**
+ * Exact decimal euros of a micro-euro amount, e.g. `5000000n` gives `"5.00"`.
+ * The amount is truncated toward zero at `fractionDigits` (0 to 6, 2 by
+ * default): rounding up could show a user more credit than they hold.
+ */
+export declare function formatEuros(amount: bigint, fractionDigits?: number): string;
+/**
+ * The signed-in user's own wallet, read with their access token for the
+ * auth-service audience and the `wallet:self:read` scope. Debits are made by
+ * the gateway after each call: an application only reads, and refills by
+ * sending the user to `topupUrl()`.
+ */
+export declare class WalletClient {
+    #private;
+    constructor(http: JsonHttp, issuer: string);
+    /** Decide with `canSpend` rather than recomputing it from the balance. */
+    getAccount(): Promise<WalletAccount>;
+    getStats(options?: WalletStatsOptions): Promise<WalletStats>;
+    /**
+     * What one chat session spent, for the calling application only. The id is
+     * the one passed to the gateway as `metadata.session_id`.
+     */
+    getSessionUsage(sessionId: string, options?: WalletSessionUsageOptions): Promise<WalletSessionUsage>;
+    /** Newest first, keyset-paginated: pass `nextCursor` back until it is null. */
+    listTransactions(options?: ListTransactionsOptions): Promise<WalletTransactionPage>;
+    getTopupOptions(): Promise<TopupOptions>;
+    /**
+     * The Credit tab of the user's profile. Checkout needs the user's session,
+     * not a bearer token, so an application links there instead of creating it.
+     */
+    topupUrl(): string;
+}
+/** Key handed to the token supplier: the wallet audience of auth-service. */
+export declare const WALLET_SCOPE_KEY = "wallet";

package/dist/wallet.js

@@ -0,0 +1,184 @@
+import { z } from "zod";
+/** 1 EUR in the ledger unit. */
+export const MICRO_PER_EUR = 1000000n;
+// Amounts travel as integer strings of micro-euros: a JSON number cannot carry them exactly.
+const amountSchema = z
+    .string()
+    .regex(/^-?[0-9]{1,19}$/, "must be an integer string of micro-euros")
+    .transform((value) => BigInt(value));
+const isoDateSchema = z.iso.datetime();
+export const walletTransactionTypeSchema = z.enum([
+    "topup",
+    "grant",
+    "refund",
+    "usage",
+    "adjust",
+    "reversal",
+]);
+export const walletAccountSchema = z.object({
+    /** Negative when usage or a refund exceeded the credit. */
+    balance: amountSchema,
+    isUnlimited: z.boolean(),
+    /** Whether new spending is allowed: unlimited, or a strictly positive balance. */
+    canSpend: z.boolean(),
+    currency: z.literal("eur"),
+});
+export const walletTransactionSchema = z.object({
+    id: z.string(),
+    type: walletTransactionTypeSchema,
+    amount: amountSchema,
+    delta: amountSchema,
+    balanceAfter: amountSchema,
+    applicationId: z.string().nullable(),
+    metadata: z.record(z.string(), z.unknown()),
+    createdAt: isoDateSchema,
+});
+export const walletTransactionPageSchema = z.object({
+    items: z.array(walletTransactionSchema),
+    nextCursor: z.string().nullable(),
+});
+const modelEntrySchema = z.object({
+    /** `mcp` for tool calls, `other` when the gateway reported no model. */
+    model: z.string(),
+    amount: amountSchema,
+    count: z.number(),
+    promptTokens: z.number(),
+    completionTokens: z.number(),
+    totalTokens: z.number(),
+});
+const applicationEntrySchema = z.object({
+    applicationId: z.string().nullable(),
+    name: z.string().nullable(),
+    slug: z.string().nullable(),
+    amount: amountSchema,
+    count: z.number(),
+});
+export const walletStatsSchema = z.object({
+    days: z.number(),
+    total: amountSchema,
+    /** Part of `total` never deducted: usage on an unlimited account. */
+    notBilled: amountSchema,
+    calls: z.number(),
+    series: z.array(z.object({ date: z.string(), amount: amountSchema, count: z.number() })),
+    byApplication: z.array(applicationEntrySchema),
+    byKind: z.array(z.object({ kind: z.string(), amount: amountSchema, count: z.number() })),
+    byModel: z.array(modelEntrySchema),
+    daily: z.array(z.object({
+        date: z.string(),
+        amount: amountSchema,
+        count: z.number(),
+        byApplication: z.array(applicationEntrySchema),
+        byModel: z.array(modelEntrySchema),
+    })),
+});
+export const walletSessionUsageSchema = z.object({
+    sessionId: z.string(),
+    applicationSlug: z.string().nullable(),
+    days: z.number(),
+    total: amountSchema,
+    notBilled: amountSchema,
+    calls: z.number(),
+    byModel: z.array(modelEntrySchema),
+});
+export const topupOptionsSchema = z.object({
+    enabled: z.boolean(),
+    currency: z.literal("eur"),
+    minCents: z.number(),
+    maxCents: z.number(),
+});
+/**
+ * Exact decimal euros of a micro-euro amount, e.g. `5000000n` gives `"5.00"`.
+ * The amount is truncated toward zero at `fractionDigits` (0 to 6, 2 by
+ * default): rounding up could show a user more credit than they hold.
+ */
+export function formatEuros(amount, fractionDigits = 2) {
+    if (!Number.isInteger(fractionDigits) ||
+        fractionDigits < 0 ||
+        fractionDigits > 6) {
+        throw new RangeError("fractionDigits must be an integer from 0 to 6");
+    }
+    const negative = amount < 0n;
+    const magnitude = negative ? -amount : amount;
+    const whole = magnitude / MICRO_PER_EUR;
+    const micro = (magnitude % MICRO_PER_EUR).toString().padStart(6, "0");
+    const fraction = micro.slice(0, fractionDigits);
+    const text = fractionDigits === 0 ? `${whole}` : `${whole}.${fraction}`;
+    // A negative amount truncated to zero is not a debt worth a minus sign.
+    return negative && /[1-9]/.test(text) ? `-${text}` : text;
+}
+/**
+ * The signed-in user's own wallet, read with their access token for the
+ * auth-service audience and the `wallet:self:read` scope. Debits are made by
+ * the gateway after each call: an application only reads, and refills by
+ * sending the user to `topupUrl()`.
+ */
+export class WalletClient {
+    #http;
+    #issuer;
+    constructor(http, issuer) {
+        this.#http = http;
+        this.#issuer = issuer;
+    }
+    /** Decide with `canSpend` rather than recomputing it from the balance. */
+    getAccount() {
+        return this.#http.request({
+            method: "GET",
+            path: "/api/user/wallet",
+            scope: WALLET_SCOPE_KEY,
+            schema: walletAccountSchema,
+        });
+    }
+    getStats(options = {}) {
+        return this.#http.request({
+            method: "GET",
+            path: "/api/user/wallet/stats",
+            scope: WALLET_SCOPE_KEY,
+            query: { days: options.days },
+            schema: walletStatsSchema,
+        });
+    }
+    /**
+     * What one chat session spent, for the calling application only. The id is
+     * the one passed to the gateway as `metadata.session_id`.
+     */
+    getSessionUsage(sessionId, options = {}) {
+        return this.#http.request({
+            method: "GET",
+            path: "/api/user/wallet/usage",
+            scope: WALLET_SCOPE_KEY,
+            query: { sessionId, days: options.days },
+            schema: walletSessionUsageSchema,
+        });
+    }
+    /** Newest first, keyset-paginated: pass `nextCursor` back until it is null. */
+    listTransactions(options = {}) {
+        return this.#http.request({
+            method: "GET",
+            path: "/api/user/wallet/transactions",
+            scope: WALLET_SCOPE_KEY,
+            query: {
+                limit: options.limit,
+                cursor: options.cursor,
+                type: options.type,
+            },
+            schema: walletTransactionPageSchema,
+        });
+    }
+    getTopupOptions() {
+        return this.#http.request({
+            method: "GET",
+            path: "/api/user/wallet/topup-options",
+            scope: WALLET_SCOPE_KEY,
+            schema: topupOptionsSchema,
+        });
+    }
+    /**
+     * The Credit tab of the user's profile. Checkout needs the user's session,
+     * not a bearer token, so an application links there instead of creating it.
+     */
+    topupUrl() {
+        return `${this.#issuer}/profile`;
+    }
+}
+/** Key handed to the token supplier: the wallet audience of auth-service. */
+export const WALLET_SCOPE_KEY = "wallet";

package/dist/web/ai-routes.d.ts

@@ -0,0 +1,8 @@
+import type { AiClient } from "../ai.js";
+import type { Session } from "./sessions.js";
+export type RouteHandler = (request: Request) => Promise<Response>;
+/**
+ * Wallet and model reads for the application's own frontend, which holds no
+ * token: the backend calls auth-service and the gateway on the user's behalf.
+ */
+export declare function createAiRoutes(ai: AiClient, requireSession: (request: Request) => Promise<Session>): Record<string, RouteHandler>;