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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CIRCLE <https://circle-cyber.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,324 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs-site/public/logo-dark.svg">
+    <img src="docs-site/public/logo-light.svg" alt="CIRCLE auth-ai logo" width="140" />
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">CIRCLE auth-ai</h1>
+
+<p align="center">
+  <em>The TypeScript SDK for CIRCLE auth-service — sign-in, entitlements, billing and LLM credit, in one library.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/circle-rd/auth-ai/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/circle-rd/auth-ai/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/@circle-rd/auth-ai"><img alt="npm" src="https://img.shields.io/npm/v/@circle-rd/auth-ai?logo=npm"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
+  <a href="https://nodejs.org"><img alt="Node" src="https://img.shields.io/badge/node-22-3c873a?logo=node.js&logoColor=white"></a>
+  <a href="https://www.typescriptlang.org"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178C6.svg?logo=typescript&logoColor=white"></a>
+  <a href="https://github.com/circle-rd/auth-service"><img alt="auth-service" src="https://img.shields.io/badge/for-auth--service-black.svg"></a>
+</p>
+
+Let your application sign users in with a self-hosted
+[CIRCLE auth-service](https://github.com/circle-rd/auth-service), read what they
+are entitled to (roles, permissions, plan features), meter what they consume,
+and call LLMs on their behalf through a [LiteLLM](https://docs.litellm.ai)
+gateway that bills their credit wallet — without writing any OAuth, token
+refresh, logout or billing plumbing yourself.
+
+Full documentation: **https://docs.circle-cyber.com/auth-ai/**
+
+```ts
+const handlers = await createAuthHandlers({
+  auth,
+  grants,
+  sessions,
+  secret,
+  ai,
+});
+await app.register(authPlugin, { handlers }); // /auth/login, /callback, /me, /logout…
+
+app.get("/api/models", { preHandler: requireAuth(handlers) }, async (request) =>
+  ai.forUser(request.authSession!.userId).gateway.listModels(),
+);
+```
+
+## Principles
+
+- **Do not reinvent OAuth.** Protocol work stays with the maintained libraries
+  [`openid-client`](https://github.com/panva/openid-client) and
+  [`jose`](https://github.com/panva/jose); the SDK adds what is specific to
+  auth-service on top of them.
+- **Backend-for-frontend by default.** The browser holds one opaque session
+  cookie. Access and refresh tokens never reach it.
+- **Fail loud, leak nothing.** Invalid state is rejected, not repaired. Errors
+  carry stable codes; HTTP responses expose the code and a generic message, and
+  the detail stays in your logs.
+- **Strict at every boundary.** Every external payload (tokens, API answers,
+  cookies, environment) is validated with [Zod](https://zod.dev); `any` is
+  banned.
+- **One package, hard boundaries.** Browser entry points import no server code
+  (a test enforces it); frameworks are optional peer dependencies.
+- **Centralized spending.** The SDK never debits a wallet itself: the gateway
+  bills each call, so margin and pricing stay under the administrator's control.
+
+## Features
+
+**Sign-in and sessions**
+
+- Authorization-code flow with PKCE, `state` and `nonce`, multi-audience
+  tokens ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)), TOTP handled by
+  the provider.
+- One serialized refresh-token chain per user, with per-audience access tokens
+  minted on demand and never stored.
+- Sealed one-shot login cookie, hashed session ids, `__Host-` cookies,
+  same-origin redirect targets, refused cross-site logout.
+- Claims (roles, permissions, features, plan, organization) renewed from the
+  provider on a schedule.
+- **Back-channel logout**: signature, `typ`, audience, event, lifetime and
+  replay checks, then the sessions and grant of the user end.
+
+**Entitlements**
+
+- Typed claims and helpers: `hasRole`, `hasPermission` (write implies read),
+  `hasFeature`, `getFeature`.
+- Bearer-token verification for your own API, with RFC 9728
+  protected-resource metadata and `WWW-Authenticate` challenges (MCP-friendly).
+
+**LLM gateway and credit wallet**
+
+- One switch in auth-service ("LiteLLM support") and one option here
+  (`gatewayUrl`) turn on the gateway and wallet audiences.
+- An origin-locked `fetch` that signs OpenAI-compatible calls with a fresh user
+  token; model listing; MCP endpoint URLs; gateway errors mapped
+  (`402` → `GW_001`, `429` with `Retry-After`, …).
+- Wallet reads: balance, spend statistics, per-session usage, transactions,
+  top-up link. Amounts are exact `bigint` micro-euros.
+
+**Billing and consumption**
+
+- Machine client (`client_credentials`, cached and single-flighted): a user's
+  subscription, metered usage and invoices; usage reporting with idempotency
+  keys for features billed per call.
+
+**Frontend**
+
+- Framework-agnostic browser client and observable stores, React hooks
+  (`useAuth`, `useUser`, `useEntitlements`, `useWallet`, `useModels`…) and Vue
+  composables.
+
+**Delivery**
+
+- Web-standard `Request` → `Response` handlers (mount them anywhere) and a
+  Fastify plugin.
+- ESM, Node 22+, full type declarations, MIT licensed.
+
+## Install
+
+```sh
+pnpm add @circle-rd/auth-ai
+# optional peers, as you need them
+pnpm add fastify react vue
+```
+
+Register your application in auth-service first: a confidential application with
+the **LiteLLM support** switch on (if you call the gateway), the redirect URI
+`https://<host>/auth/callback` and the back-channel logout URI
+`https://<host>/auth/backchannel-logout`.
+
+## Quick start
+
+A Fastify backend (the stores below live in memory: demo only, see
+[Production](#production)):
+
+```ts
+import Fastify from "fastify";
+import {
+  GrantManager,
+  MemoryGrantStore,
+  createAiClient,
+  createAuthClient,
+} from "@circle-rd/auth-ai";
+import { authPlugin, requireAuth } from "@circle-rd/auth-ai/fastify";
+import { MemorySessionStore, createAuthHandlers } from "@circle-rd/auth-ai/web";
+
+const auth = createAuthClient({
+  issuer: "https://auth.example.com",
+  clientId: "my-app",
+  clientSecret: process.env.AUTH_CLIENT_SECRET,
+  redirectUri: "https://app.example.com/auth/callback",
+  gatewayUrl: "https://llm.example.com",
+});
+const grants = new GrantManager({ auth, store: new MemoryGrantStore() });
+const ai = createAiClient({ auth, grants });
+
+const handlers = await createAuthHandlers({
+  auth,
+  grants,
+  ai, // adds /auth/wallet, /auth/wallet/stats and /auth/models for your frontend
+  sessions: new MemorySessionStore(),
+  secret: process.env.COOKIE_SECRET!, // 32+ random characters
+});
+
+const app = Fastify();
+await app.register(authPlugin, { handlers });
+
+app.get("/api/models", { preHandler: requireAuth(handlers) }, async (request) =>
+  ai.forUser(request.authSession!.userId).gateway.listModels(),
+);
+await app.listen({ port: 3000 });
+```
+
+A React frontend:
+
+```tsx
+import { AuthProvider, useAuth, useWallet } from "@circle-rd/auth-ai/react";
+
+function Header() {
+  const { status, user, login, logout } = useAuth();
+  const { data: wallet } = useWallet({ pollIntervalMs: 15_000 });
+  if (status !== "authenticated")
+    return <button onClick={() => login()}>Sign in</button>;
+  return (
+    <p>
+      {user?.name} · canSpend={String(wallet?.canSpend)}{" "}
+      <button onClick={() => void logout()}>Sign out</button>
+    </p>
+  );
+}
+
+root.render(
+  <AuthProvider>
+    <Header />
+  </AuthProvider>,
+);
+```
+
+Calling the gateway with any OpenAI-compatible SDK:
+
+```ts
+const { gateway } = ai.forUser(userId);
+const client = new OpenAI({
+  baseURL: gateway.openAiBaseUrl,
+  apiKey: "unused", // replaced by a fresh user token on every request
+  fetch: gateway.fetch,
+});
+```
+
+A complete, deployable application lives in [`examples/minimal`](examples/minimal).
+
+## Entry points
+
+| Import                       | Runs in             | What it gives you                                                                  |
+| ---------------------------- | ------------------- | ---------------------------------------------------------------------------------- |
+| `@circle-rd/auth-ai`         | Node, edge, browser | OIDC client, grants, claims helpers, wallet and gateway clients, error registry    |
+| `@circle-rd/auth-ai/server`  | Node, edge          | Bearer verification, back-channel logout, protected-resource metadata, machine API |
+| `@circle-rd/auth-ai/web`     | Node, edge          | Sign-in handlers (`Request` → `Response`), session store contract                  |
+| `@circle-rd/auth-ai/fastify` | Node                | Fastify plugin and `requireAuth` / `loadSession` hooks (`fastify` ≥ 5.12.6)        |
+| `@circle-rd/auth-ai/client`  | Browser             | Cookie-only browser client and observable stores                                   |
+| `@circle-rd/auth-ai/react`   | Browser             | `AuthProvider` and hooks (`react` ≥ 18)                                            |
+| `@circle-rd/auth-ai/vue`     | Browser             | `createAuthPlugin` and composables (`vue` ≥ 3.4)                                   |
+
+## Architecture
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant B as Browser
+  participant A as Your backend (auth-ai)
+  participant S as auth-service
+  participant G as LiteLLM gateway
+  B->>A: GET /auth/login
+  A-->>B: 302 to auth-service (PKCE, resources) + sealed cookie
+  B->>S: sign in (password, TOTP…)
+  S-->>B: 302 /auth/callback?code
+  B->>A: GET /auth/callback
+  A->>S: code → tokens (client secret)
+  A-->>B: 303 + opaque session cookie
+  B->>A: GET /auth/wallet (cookie)
+  A->>S: wallet read (user token for auth-service)
+  B->>A: POST /api/chat (cookie)
+  A->>G: call (user token for the gateway)
+  G->>S: debit the wallet after the call
+  S-->>A: back-channel logout on sign-out anywhere
+```
+
+```
+auth-ai/
+├── 📁 src/
+│   ├── client.ts          AuthClient — discovery, PKCE login, refresh, logout, revoke, introspect
+│   ├── config.ts          Zod-validated configuration (gatewayUrl adds the gateway audiences)
+│   ├── grants.ts          GrantManager — serialized refresh rotation, per-audience tokens
+│   ├── claims.ts          Claim schemas and entitlement helpers
+│   ├── wallet.ts          WalletClient and wallet schemas (bigint micro-euros)
+│   ├── gateway.ts         GatewayClient — origin-locked fetch, listings, MCP URLs
+│   ├── ai.ts              createAiClient().forUser(grantId)
+│   ├── errors.ts          AuthAiError + ERR registry (OIDC_*, TOK_*, GW_*, SES_*…)
+│   ├── 📁 server/         Bearer verifier, back-channel logout, machine API
+│   ├── 📁 web/            Sign-in handlers, sealed cookies, session store contract
+│   ├── 📁 fastify/        Fastify adapter
+│   ├── 📁 browser/        Cookie-only client and stores (entry point `/client`)
+│   ├── 📁 react/          React bindings
+│   └── 📁 vue/            Vue bindings
+├── 📁 examples/minimal/   Deployable end-to-end app with a self-test
+└── 📁 docs-site/          Docus documentation (built into a container image)
+```
+
+## Production
+
+The SDK is storage-agnostic on purpose. Before going live:
+
+- **Persist sessions and grants.** Implement `SessionStore` and `GrantStore` on
+  your database. The in-memory stores sign everyone out on restart and cannot
+  be shared by replicas.
+- **Several replicas?** Provide a distributed `GrantLock` (a refresh token
+  rotates on every use; a replayed one revokes the whole family) and a shared
+  `ReplayStore` for back-channel logout tokens.
+- **Secrets from the environment only:** the client secret and a 32+ character
+  cookie secret. Neither is ever logged or returned.
+- **Registered URIs must match:** `redirectUri` is `<origin><basePath>/callback`
+  and the back-channel URI is `<origin><basePath>/backchannel-logout`, reachable
+  over HTTPS by auth-service.
+- **Log with `onError`, answer with `toPublicJSON()`.** Never forward
+  `error.message` or `error.details` to a browser.
+- **Keep `fastify` ≥ 5.12.6** (several 2026 advisories are fixed there).
+
+## Documentation
+
+The full documentation is published at
+[docs.circle-cyber.com/auth-ai](https://docs.circle-cyber.com/auth-ai/):
+concepts, one guide per framework, the configuration and API reference, the
+error-code registry and a production checklist.
+
+**For AI agents** — the documentation is exposed through a built-in MCP server
+(HTTP), so agents can query it directly:
+
+| Environment | MCP endpoint                                                    |
+| ----------- | --------------------------------------------------------------- |
+| Production  | `https://docs.circle-cyber.com/auth-ai/mcp`                     |
+| Local dev   | `http://localhost:3000/mcp` (run `npm run dev` in `docs-site/`) |
+
+**Contributing** — the development rules in [AGENTS.md](AGENTS.md) (naming,
+TypeScript strictness, error handling, testing, security) and the process in
+[CONTRIBUTING.md](CONTRIBUTING.md) are mandatory for any contribution.
+Security reports: see [SECURITY.md](SECURITY.md). Releases are tracked in
+[CHANGELOG.md](CHANGELOG.md).
+
+## Roadmap
+
+- **Python port** of the same behaviours (the test suite pins them), for the
+  Python backends of the CIRCLE stack.
+- **Migration of [gine](https://github.com/circle-rd/gine)** onto the SDK.
+- **npm Trusted Publishing** once the first release is out, replacing the
+  publish token.
+- **More adapters** on top of the Web-standard handlers, as needs appear.
+
+## Credits & license
+
+Built and maintained by [CIRCLE](https://circle-cyber.com). Stands on the
+shoulders of [openid-client](https://github.com/panva/openid-client),
+[jose](https://github.com/panva/jose), [Zod](https://zod.dev) and
+[Fastify](https://fastify.dev).
+
+Licensed under the **MIT License** — see [LICENSE](LICENSE).

package/dist/ai.d.ts

@@ -0,0 +1,32 @@
+import type { AuthClient } from "./client.js";
+import { GatewayClient } from "./gateway.js";
+import type { GrantManager } from "./grants.js";
+import { WalletClient } from "./wallet.js";
+type AiAuth = Pick<AuthClient, "config" | "fetch">;
+type AiGrants = Pick<GrantManager, "getAccessToken" | "invalidate">;
+export interface AiClientOptions {
+    readonly auth: AiAuth;
+    /** Holds the refresh token of each user: access tokens are minted from it. */
+    readonly grants: AiGrants;
+}
+/** What an application does for one signed-in user: read the wallet, call the gateway. */
+export declare class UserAi {
+    #private;
+    readonly wallet: WalletClient;
+    constructor(auth: AiAuth, grants: AiGrants, grantId: string);
+    /** Needs `gatewayUrl` in the client configuration. */
+    get gateway(): GatewayClient;
+}
+/**
+ * Wallet and gateway clients bound to a user's grant. Each call mints (or
+ * reuses) a short-lived access token for the right audience: the wallet is
+ * served by auth-service, the gateway by its own URL.
+ */
+export declare class AiClient {
+    #private;
+    constructor(options: AiClientOptions);
+    /** `grantId` is the key the user's refresh token was saved under (typically `sub`). */
+    forUser(grantId: string): UserAi;
+}
+export declare function createAiClient(options: AiClientOptions): AiClient;
+export {};

package/dist/ai.js

@@ -0,0 +1,65 @@
+import { ERR } from "./errors.js";
+import { GatewayClient } from "./gateway.js";
+import { JsonHttp } from "./http.js";
+import { WalletClient } from "./wallet.js";
+/** What an application does for one signed-in user: read the wallet, call the gateway. */
+export class UserAi {
+    wallet;
+    #auth;
+    #gatewayTokens;
+    #gateway;
+    constructor(auth, grants, grantId) {
+        this.#auth = auth;
+        const { config } = auth;
+        const tokensFor = (resource) => ({
+            getToken: async () => (await grants.getAccessToken(grantId, { resource })).accessToken,
+            invalidate: () => grants.invalidate(grantId, resource),
+        });
+        // A user has a single wallet audience, so the supplier ignores the key.
+        const walletTokens = tokensFor(config.issuer);
+        this.wallet = new WalletClient(new JsonHttp({
+            baseUrl: config.issuer,
+            fetch: auth.fetch,
+            timeoutMs: config.timeoutMs,
+            tokens: {
+                getToken: () => walletTokens.getToken(),
+                invalidate: () => walletTokens.invalidate(),
+            },
+        }), config.issuer);
+        this.#gatewayTokens = config.gatewayUrl
+            ? tokensFor(config.gatewayUrl)
+            : undefined;
+    }
+    /** Needs `gatewayUrl` in the client configuration. */
+    get gateway() {
+        const { gatewayUrl, timeoutMs } = this.#auth.config;
+        if (!gatewayUrl || !this.#gatewayTokens) {
+            throw ERR.CFG_001("The gateway requires `gatewayUrl` in the configuration");
+        }
+        this.#gateway ??= new GatewayClient({
+            gatewayUrl,
+            tokens: this.#gatewayTokens,
+            fetch: this.#auth.fetch,
+            timeoutMs,
+        });
+        return this.#gateway;
+    }
+}
+/**
+ * Wallet and gateway clients bound to a user's grant. Each call mints (or
+ * reuses) a short-lived access token for the right audience: the wallet is
+ * served by auth-service, the gateway by its own URL.
+ */
+export class AiClient {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** `grantId` is the key the user's refresh token was saved under (typically `sub`). */
+    forUser(grantId) {
+        return new UserAi(this.#options.auth, this.#options.grants, grantId);
+    }
+}
+export function createAiClient(options) {
+    return new AiClient(options);
+}

package/dist/browser/client.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { GatewayModel } from "../gateway.js";
+import type { SessionUser } from "../session-user.js";
+import type { WalletStats } from "../wallet.js";
+declare const walletSchema: z.ZodObject<{
+    balance: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+    isUnlimited: z.ZodBoolean;
+    canSpend: z.ZodBoolean;
+    currency: z.ZodLiteral<"eur">;
+    topupUrl: z.ZodString;
+}, z.core.$strip>;
+export type WalletView = z.infer<typeof walletSchema>;
+export interface BrowserAuthOptions {
+    /** Where the backend mounted the sign-in routes. */
+    readonly basePath?: string;
+    readonly fetch?: typeof fetch;
+    /** Navigation target of `login` and `logout`; the page's `location` by default. */
+    readonly location?: Pick<Location, "assign" | "pathname" | "search">;
+}
+export interface BrowserAuth {
+    /** The signed-in user, or null when signed out. */
+    getUser(): Promise<SessionUser | null>;
+    loginUrl(next?: string): string;
+    /** Sends the browser to the sign-in, then back to `next` (the current page by default). */
+    login(next?: string): void;
+    /** Ends the session and the provider's single sign-on session. */
+    logout(): Promise<void>;
+    /** Needs the backend routes enabled with the `ai` option. */
+    getWallet(): Promise<WalletView>;
+    getWalletStats(days?: number): Promise<WalletStats>;
+    listModels(): Promise<GatewayModel[]>;
+}
+/**
+ * The browser side of the backend-for-frontend: it holds no token, only talks
+ * to the application's own routes with the session cookie. Importing it pulls
+ * no server code.
+ */
+export declare function createBrowserAuth(options?: BrowserAuthOptions): BrowserAuth;
+export {};

package/dist/browser/client.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { AuthAiError, ERR, isAuthAiErrorCode } from "../errors.js";
+import { gatewayModelSchema } from "../gateway.js";
+import { sessionUserSchema } from "../session-user.js";
+import { walletAccountSchema, walletStatsSchema } from "../wallet.js";
+const errorEnvelopeSchema = z.object({
+    error: z.object({ code: z.string(), message: z.string() }),
+});
+const meSchema = z.object({ user: sessionUserSchema, expiresAt: z.number() });
+const logoutSchema = z.object({ logoutUrl: z.string().nullable() });
+const walletSchema = walletAccountSchema.extend({ topupUrl: z.string() });
+const modelsSchema = z.object({ models: z.array(gatewayModelSchema) });
+function toError(status, body) {
+    const envelope = errorEnvelopeSchema.safeParse(body);
+    if (!envelope.success) {
+        return ERR.API_001(`The server answered ${status}`, {
+            details: { status },
+        });
+    }
+    const { code, message } = envelope.data.error;
+    return isAuthAiErrorCode(code)
+        ? new AuthAiError(code, message, { details: { status } })
+        : ERR.API_001(message, { details: { status, apiCode: code } });
+}
+/**
+ * The browser side of the backend-for-frontend: it holds no token, only talks
+ * to the application's own routes with the session cookie. Importing it pulls
+ * no server code.
+ */
+export function createBrowserAuth(options = {}) {
+    const basePath = options.basePath ?? "/auth";
+    const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    const where = () => options.location ?? globalThis.location;
+    async function send(path, init = {}) {
+        const response = await doFetch(`${basePath}${path}`, {
+            credentials: "same-origin",
+            redirect: "error",
+            ...init,
+            headers: { accept: "application/json", ...init.headers },
+        });
+        return {
+            status: response.status,
+            ok: response.ok,
+            body: await response.json().catch(() => undefined),
+        };
+    }
+    function parse(schema, body) {
+        const parsed = schema.safeParse(body);
+        if (!parsed.success)
+            throw ERR.API_002(undefined, { cause: parsed.error });
+        return parsed.data;
+    }
+    async function call(path, schema, init) {
+        const result = await send(path, init);
+        if (!result.ok)
+            throw toError(result.status, result.body);
+        return parse(schema, result.body);
+    }
+    const loginUrl = (next) => next === undefined
+        ? `${basePath}/login`
+        : `${basePath}/login?next=${encodeURIComponent(next)}`;
+    return {
+        async getUser() {
+            const result = await send("/me");
+            if (result.status === 401)
+                return null;
+            if (!result.ok)
+                throw toError(result.status, result.body);
+            return parse(meSchema, result.body).user;
+        },
+        loginUrl,
+        login(next) {
+            const { pathname, search } = where();
+            where().assign(loginUrl(next ?? `${pathname}${search}`));
+        },
+        async logout() {
+            const { logoutUrl } = await call("/logout", logoutSchema, {
+                method: "POST",
+            });
+            where().assign(logoutUrl ?? "/");
+        },
+        getWallet: () => call("/wallet", walletSchema),
+        getWalletStats: (days) => call(days === undefined ? "/wallet/stats" : `/wallet/stats?days=${days}`, walletStatsSchema),
+        async listModels() {
+            return (await call("/models", modelsSchema)).models;
+        },
+    };
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,10 @@
+export { createBrowserAuth } from "./client.js";
+export type { BrowserAuth, BrowserAuthOptions, WalletView } from "./client.js";
+export { INITIAL_AUTH_STATE, createAuthStore, createObservable, createResourceStore, } from "./store.js";
+export type { AuthState, AuthStatus, AuthStore, Observable, ResourceOptions, ResourceState, ResourceStatus, ResourceStore, } from "./store.js";
+export { getFeature, hasFeature, hasPermission, hasRole } from "../claims.js";
+export { AuthAiError } from "../errors.js";
+export { formatEuros } from "../wallet.js";
+export type { SessionUser } from "../session-user.js";
+export type { GatewayModel } from "../gateway.js";
+export type { WalletStats } from "../wallet.js";

package/dist/browser/index.js

@@ -0,0 +1,5 @@
+export { createBrowserAuth } from "./client.js";
+export { INITIAL_AUTH_STATE, createAuthStore, createObservable, createResourceStore, } from "./store.js";
+export { getFeature, hasFeature, hasPermission, hasRole } from "../claims.js";
+export { AuthAiError } from "../errors.js";
+export { formatEuros } from "../wallet.js";

package/dist/browser/store.d.ts

@@ -0,0 +1,43 @@
+import { AuthAiError } from "../errors.js";
+import type { SessionUser } from "../session-user.js";
+import type { BrowserAuth } from "./client.js";
+type Listener = () => void;
+/** A value that notifies subscribers when it changes: what React and Vue both bind to. */
+export interface Observable<T> {
+    get(): T;
+    set(value: T): void;
+    subscribe(listener: Listener): () => void;
+}
+export declare function createObservable<T>(initial: T): Observable<T>;
+export type AuthStatus = "loading" | "authenticated" | "unauthenticated" | "error";
+export interface AuthState {
+    readonly status: AuthStatus;
+    readonly user: SessionUser | null;
+    readonly error: AuthAiError | null;
+}
+export declare const INITIAL_AUTH_STATE: AuthState;
+export interface AuthStore {
+    readonly state: Observable<AuthState>;
+    /** Reads the session again: on mount, on focus, or after an API answered 401. */
+    refresh(): Promise<void>;
+}
+export declare function createAuthStore(auth: Pick<BrowserAuth, "getUser">): AuthStore;
+export type ResourceStatus = "idle" | "loading" | "ready" | "error";
+export interface ResourceState<T> {
+    readonly status: ResourceStatus;
+    readonly data: T | null;
+    readonly error: AuthAiError | null;
+}
+export interface ResourceStore<T> {
+    readonly state: Observable<ResourceState<T>>;
+    refresh(): Promise<void>;
+    /** Loads now and, with `pollIntervalMs`, keeps reloading; returns the stop function. */
+    start(): () => void;
+}
+export interface ResourceOptions {
+    readonly pollIntervalMs?: number;
+    /** Called when the load fails: e.g. refresh the session on SES_001. */
+    readonly onError?: (error: AuthAiError) => void;
+}
+export declare function createResourceStore<T>(load: () => Promise<T>, options?: ResourceOptions): ResourceStore<T>;
+export {};