@bgub/fig-better-auth

Small, experimental Fig integration pieces for the vanilla Better Auth client:

• /development-oauth: opt-in Convex OAuth callback relay for HTTPS .test development. See auth setup.
• /client: createSessionReader(store, serverSnapshot) adapts the vanilla client's useSession atom to a Fig hook. Supply a stable request-specific SSR snapshot; the reader uses it during hydration before adopting browser state.
• /convex: createConvexTokenFetcher({ initialToken, fetchToken }) provides Convex's token callback with forced refresh, shared pending work, and generation checks. Call clear() when the session changes and retire the old query registry.
• /server: createAuthRequest(request, options) memoizes the upstream Convex Better Auth token helper per request, preserving its JWT-cache options. proxyAuthRequest forwards the existing /api/auth/* endpoint while preserving cookies, origins and manual redirects. It strips incoming body framing headers, sets public host/protocol forwarding headers from the request URL, and requests uncompressed responses. Decoded responses still have stale compression metadata removed. It does not depend on React Start.

Use createAuthClient from better-auth/client and keep app-specific plugins, claims, redirects and session-identity policy in the app. For TinyLingo, preserve the existing reload after logout. TinyLingo wires these pieces in its per-router data context and initializes auth before hydrated descendants read queries. Tests cover session changes, transient session failures, token refresh, and compressed proxy responses. Live signed-in deployment checks remain a release gate.

Build before consuming with pnpm --filter @bgub/fig-better-auth build.

Compatibility was audited against Better Auth 1.6.33, the Convex Better Auth component 0.12.5, and Convex 1.46.0. The vanilla client's useSession remains a store. The upstream token helper still returns { token, isFresh }; basePath, cookiePrefix, and JWT expiration tolerance pass through unchanged. A custom token basePath does not change this package's /api/auth/* proxy route.

callWithToken deliberately retains the upstream 0.12.5 retry contract: jwtCache.isAuthError(error) === true prevents retry, despite its name. Only failures with a cached token and a false predicate result are retried, once with a fresh token. Fresh-token failures and disabled caching never retry. Callers must account for possible repeated operations when enabling this cache. See the versioned upstream adapter.

For coordinated app upgrades, follow the official 0.11 guide and 0.12 guide. The 0.11 passkey extraction and OIDC redirectURLs → redirectUrls migration apply only to apps using those features. In 0.12, cross-domain apps must set baseURL in their server betterAuth() options; local installs also require schema regeneration with the new auth CLI. Those backend changes belong to the consuming app, not these framework adapters.