CIRCLE
Reference

Browser, React and Vue

Reference of @circle-rd/auth-ai/client, /react and /vue: the cookie-only browser client, the observable stores and the framework bindings.

These entry points never hold a token. They talk to the routes your backend mounted with createAuthHandlers, using the session cookie. A test pins that they reach no server-only package (openid-client, jose), so importing them adds no server code to a bundle.

createBrowserAuth(options?)

From @circle-rd/auth-ai/client.

OptionTypeDefaultDescription
basePathstring"/auth"Where the backend mounted the routes.
fetchtypeof fetchglobal fetchFor tests or instrumentation. Requests are sent with credentials: "same-origin" and redirect: "error".
locationPick<Location, "assign" | "pathname" | "search">globalThis.locationNavigation target of login and logout.

It returns a BrowserAuth:

MethodDescription
getUser()SessionUser | null. null on a 401; any other failure throws an AuthAiError.
loginUrl(next?)<basePath>/login, with ?next= when given.
login(next?)Navigates to the sign-in, then back to next (the current path and query by default).
logout()POST <basePath>/logout, then navigates to the provider's logout URL, or to /.
getWallet()WalletView: the wallet account plus topupUrl. Needs the ai option on the backend.
getWalletStats(days?)WalletStats. Needs the ai option.
listModels()GatewayModel[]. Needs the ai option.

Failures become AuthAiError: when the answer is the { error: { code, message } } envelope with a known code, the error carries that code and details.status; an unknown code or a non-envelope answer becomes API_001; a body that is not the expected shape becomes API_002. Wallet amounts are bigint micro-euros: format them with formatEuros.

Stores

Framework-agnostic stores, which the React and Vue bindings wrap. Use them directly for vanilla code.

ExportDescription
createObservable(initial){ get, set, subscribe }. Notifies only when the value changes (Object.is). subscribe returns the unsubscribe function.
createAuthStore(auth){ state, refresh() }. state holds an AuthState: status ("loading", "authenticated", "unauthenticated" or "error"), user and error. A failed refresh keeps the last known user: it does not sign anyone out. A slow answer never overwrites a newer one.
createResourceStore(load, options?){ state, refresh(), start() }. state holds status ("idle", "loading", "ready", "error"), data and error; previous data is kept while reloading or after a failure. start() loads now, polls every options.pollIntervalMs when set, and returns the stop function. options.onError is called with the AuthAiError when a load fails.
INITIAL_AUTH_STATEThe loading state: { status: "loading", user: null, error: null }.

@circle-rd/auth-ai/client also re-exports hasRole, hasPermission, hasFeature, getFeature, AuthAiError, formatEuros and the types SessionUser, GatewayModel and WalletStats.

React

From @circle-rd/auth-ai/react. Requires react >=18.

ExportDescription
AuthProviderProps: auth? (a BrowserAuth), basePath?, refreshOnFocus? (default true: re-reads the session when the tab becomes visible) and children. Reads the session on mount.
useAuth(){ status, user, error, login, logout, refresh }.
useUser()The SessionUser, or null while loading and when signed out.
useEntitlements(){ hasRole, hasPermission, hasFeature, getFeature } for the current user; all false when signed out.
useWallet({ pollIntervalMs? }){ status, data, error, refresh } for the WalletView.
useWalletStats(days?)The same for WalletStats.
useModels()The same for GatewayModel[].

Every hook throws Error("Wrap the application in <AuthProvider>") outside the provider. A resource that fails with SES_001 triggers a session refresh, so the auth state reflects the sign-out.

Vue

From @circle-rd/auth-ai/vue. Requires vue >=3.4.

ExportDescription
createAuthPlugin({ auth?, basePath? })A plugin: app.use(createAuthPlugin()). Reads the session once the app runs in a browser (it does nothing without window).
useAuth(){ state, user, login, logout, refresh }. state is a readonly shallowRef<AuthState>, user a computed.
useEntitlements()The four checks, reading the user at call time so templates stay reactive.
useWallet({ pollIntervalMs? }){ state, refresh } where state is a ref to { status, data, error }.
useWalletStats(days?)The same for WalletStats.
useModels()The same for GatewayModel[].

Composables must run in setup() (or an effect scope) so that subscriptions and polling are disposed with the component; they throw Error("Install createAuthPlugin() on the app") when the plugin is missing.

Guides: React app, Vue app, Vanilla browser.

Copyright © 2026