Browser, React and Vue
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.
| Option | Type | Default | Description |
|---|---|---|---|
basePath | string | "/auth" | Where the backend mounted the routes. |
fetch | typeof fetch | global fetch | For tests or instrumentation. Requests are sent with credentials: "same-origin" and redirect: "error". |
location | Pick<Location, "assign" | "pathname" | "search"> | globalThis.location | Navigation target of login and logout. |
It returns a BrowserAuth:
| Method | Description |
|---|---|
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.
| Export | Description |
|---|---|
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_STATE | The 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.
| Export | Description |
|---|---|
AuthProvider | Props: 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.
| Export | Description |
|---|---|
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.