@nifrajs/better-auth 2.2.0 → 2.4.0

package/README.md

@@ -5,7 +5,7 @@ Mount [better-auth](https://better-auth.com) into a [nifra](https://github.com/n
 session, 2FA, magic links, …) under `/api/auth/*`, plus typed `getSession` / `requireSession` guards
 for reading and protecting routes.
 
-This package has **no runtime dependency on better-auth** — it consumes your `auth` object
+This package has **no runtime dependency on better-auth** - it consumes your `auth` object
 structurally, so your better-auth types flow through by inference and your tests need no DB.
 
 ## Install
@@ -51,14 +51,14 @@ works in both core handlers (`c.req`) and `@nifrajs/web` loaders/actions (`reque
 import { getSession } from "@nifrajs/better-auth"
 
 app.get("/me", async (c) => {
-  const session = await getSession(auth, c.req) // { user, session } | null — fully typed
+  const session = await getSession(auth, c.req) // { user, session } | null - fully typed
   return session ? { email: session.user.email } : { email: null }
 })
 ```
 
 ## Protect a route
 
-`requireSession(auth, request, options?)` returns the non-null session or **throws a `Response`** —
+`requireSession(auth, request, options?)` returns the non-null session or **throws a `Response`** -
 nifra returns a thrown `Response` as-is, short-circuiting the handler:
 
 ```ts
@@ -82,7 +82,7 @@ export const loader = async ({ request }) => {
 | Export | Description |
 | --- | --- |
 | `betterAuth(auth, options?)` | Plugin that mounts better-auth's handler at `${basePath}/*` for GET + POST. |
-| `getSession(auth, request)` | `Promise<SessionOf<A> \| null>` — typed wrapper over `auth.api.getSession`. |
+| `getSession(auth, request)` | `Promise<SessionOf<A> \| null>` - typed wrapper over `auth.api.getSession`. |
 | `requireSession(auth, request, options?)` | Returns the session or throws a `Response` (302 `redirectTo` / 401). |
 | `SessionOf<A>` | The non-null session payload type inferred from your `auth`. |
 | `BetterAuthLike` | The structural contract a better-auth instance satisfies. |
@@ -93,7 +93,7 @@ MIT
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { type AnyServer, type Server } from "@nifrajs/core/server";
  * {@link getSession} / {@link requireSession} via inference.
  */
 export interface BetterAuthLike {
-    /** better-auth's catch-all handler — serves every request under `basePath`. */
+    /** better-auth's catch-all handler - serves every request under `basePath`. */
     readonly handler: (request: Request) => Response | Promise<Response>;
     readonly api: {
         /** Resolve the session from request headers (cookie or bearer). Returns a nullable payload. */
@@ -18,7 +18,7 @@ export interface BetterAuthLike {
      * better-auth's resolved options; `basePath` (when set) defaults the mount path. Intersected with
      * `Record<string, unknown>` so a real better-auth instance (whose `options` is a large concrete object
      * with no structural overlap to a bare `{ basePath? }`) stays assignable to `BetterAuthLike` WITHOUT a
-     * cast — keeping `A` concrete so `SessionOf<A>` recovers the real session type instead of collapsing
+     * cast - keeping `A` concrete so `SessionOf<A>` recovers the real session type instead of collapsing
      * to `{}` and forcing per-call session casts downstream.
      */
     readonly options?: {
@@ -36,8 +36,8 @@ export interface BetterAuthOptions {
 }
 /**
  * Mount a better-auth instance into a nifra app: registers its handler at `${basePath}/*`
- * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint — sign-in/up/out, OAuth
- * callbacks, session, 2FA, magic links, … — is served by your nifra server.
+ * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint - sign-in/up/out, OAuth
+ * callbacks, session, 2FA, magic links, … - is served by your nifra server.
  *
  * ```ts
  * import { betterAuth, requireSession } from "@nifrajs/better-auth"
@@ -47,12 +47,12 @@ export interface BetterAuthOptions {
  *   .get("/me", async (c) => (await requireSession(auth, c.req)).user)
  * ```
  *
- * Idempotent (named `"better-auth"` — applying twice mounts once). Read the session with
+ * Idempotent (named `"better-auth"` - applying twice mounts once). Read the session with
  * {@link getSession} / {@link requireSession}, which infer your better-auth types.
  */
 export declare function betterAuth(auth: BetterAuthLike, options?: BetterAuthOptions): import("@nifrajs/core/server").IdentityPlugin;
 /**
- * Resolve the better-auth session for a request — a thin, typed wrapper over `auth.api.getSession`.
+ * Resolve the better-auth session for a request - a thin, typed wrapper over `auth.api.getSession`.
  * Returns `null` when unauthenticated. Takes the raw `Request` so it works in both server handlers
  * (`c.req`) and web loaders/actions (`request`).
  *
@@ -64,14 +64,14 @@ export declare function betterAuth(auth: BetterAuthLike, options?: BetterAuthOpt
 export declare function getSession<A extends BetterAuthLike>(auth: A, request: Request): Promise<SessionOf<A> | null>;
 /**
  * What {@link requireSession} does on a missing session: `302` to `redirectTo` (a same-origin path),
- * or — when omitted — a `401` JSON (`{ ok: false, error: "unauthorized" }`). Mirrors `@nifrajs/auth` guards.
+ * or - when omitted - a `401` JSON (`{ ok: false, error: "unauthorized" }`). Mirrors `@nifrajs/auth` guards.
  */
 export interface RequireSessionOptions {
     readonly redirectTo?: string;
 }
 /**
  * Require an authenticated better-auth session at the top of a protected handler/loader/action.
- * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) — nifra
+ * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) - nifra
  * returns a thrown `Response` as-is, short-circuiting the rest of the handler.
  *
  * ```ts

package/dist/index.js

@@ -3,8 +3,8 @@ import { defineIdentityPlugin } from "@nifrajs/core/server";
 const HANDLED_METHODS = ["GET", "POST"];
 /**
  * Mount a better-auth instance into a nifra app: registers its handler at `${basePath}/*`
- * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint — sign-in/up/out, OAuth
- * callbacks, session, 2FA, magic links, … — is served by your nifra server.
+ * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint - sign-in/up/out, OAuth
+ * callbacks, session, 2FA, magic links, … - is served by your nifra server.
  *
  * ```ts
  * import { betterAuth, requireSession } from "@nifrajs/better-auth"
@@ -14,7 +14,7 @@ const HANDLED_METHODS = ["GET", "POST"];
  *   .get("/me", async (c) => (await requireSession(auth, c.req)).user)
  * ```
  *
- * Idempotent (named `"better-auth"` — applying twice mounts once). Read the session with
+ * Idempotent (named `"better-auth"` - applying twice mounts once). Read the session with
  * {@link getSession} / {@link requireSession}, which infer your better-auth types.
  */
 export function betterAuth(auth, options = {}) {
@@ -22,7 +22,7 @@ export function betterAuth(auth, options = {}) {
     const pattern = `${base.replace(/\/+$/, "")}/*`; // strip trailing slash(es), then wildcard the subtree
     // A type-IDENTITY plugin (see defineIdentityPlugin): mounting the auth handler must NOT change the
     // route registry's type. A plain `definePlugin((app) => app)` would infer `app: Server<any, any>`, so
-    // `use`'s result — and the entire typed client derived from it — collapsed to `any`. This was the #1
+    // `use`'s result - and the entire typed client derived from it - collapsed to `any`. This was the #1
     // reported anti-drift bug: routes declared after `.use(betterAuth(...))` silently lost their types.
     return defineIdentityPlugin("better-auth", (app) => {
         for (const method of HANDLED_METHODS) {
@@ -34,7 +34,7 @@ export function betterAuth(auth, options = {}) {
     });
 }
 /**
- * Resolve the better-auth session for a request — a thin, typed wrapper over `auth.api.getSession`.
+ * Resolve the better-auth session for a request - a thin, typed wrapper over `auth.api.getSession`.
  * Returns `null` when unauthenticated. Takes the raw `Request` so it works in both server handlers
  * (`c.req`) and web loaders/actions (`request`).
  *
@@ -53,7 +53,7 @@ const rejection = (options) => {
     if (to === undefined)
         return Response.json({ ok: false, error: "unauthorized" }, { status: 401 });
     // Same-origin guard (mirrors @nifrajs/web `redirect` + @nifrajs/auth guards): a single leading "/", never
-    // "//host" or an absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug — fail loud.
+    // "//host" or an absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug - fail loud.
     if (!to.startsWith("/") || to.startsWith("//")) {
         throw new Error(`[nifra/better-auth] requireSession redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`);
     }
@@ -61,7 +61,7 @@ const rejection = (options) => {
 };
 /**
  * Require an authenticated better-auth session at the top of a protected handler/loader/action.
- * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) — nifra
+ * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) - nifra
  * returns a thrown `Response` as-is, short-circuiting the rest of the handler.
  *
  * ```ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/better-auth",
-  "version": "2.2.0",
-  "description": "Mount better-auth into a nifra app — one app.use() wires /api/auth/*, plus typed getSession/requireSession guards. Structural typing: no hard dependency on better-auth.",
+  "version": "2.4.0",
+  "description": "Mount better-auth into a nifra app - one app.use() wires /api/auth/*, plus typed getSession/requireSession guards. Structural typing: no hard dependency on better-auth.",
   "keywords": [
     "bun",
     "typescript",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^2.2.0",
+    "@nifrajs/core": "^2.4.0",
     "better-auth": ">=1.0.0"
   },
   "peerDependenciesMeta": {

package/src/index.ts

@@ -7,7 +7,7 @@ import { type AnyServer, defineIdentityPlugin, type Server } from "@nifrajs/core
  * {@link getSession} / {@link requireSession} via inference.
  */
 export interface BetterAuthLike {
-  /** better-auth's catch-all handler — serves every request under `basePath`. */
+  /** better-auth's catch-all handler - serves every request under `basePath`. */
   readonly handler: (request: Request) => Response | Promise<Response>
   readonly api: {
     /** Resolve the session from request headers (cookie or bearer). Returns a nullable payload. */
@@ -17,7 +17,7 @@ export interface BetterAuthLike {
    * better-auth's resolved options; `basePath` (when set) defaults the mount path. Intersected with
    * `Record<string, unknown>` so a real better-auth instance (whose `options` is a large concrete object
    * with no structural overlap to a bare `{ basePath? }`) stays assignable to `BetterAuthLike` WITHOUT a
-   * cast — keeping `A` concrete so `SessionOf<A>` recovers the real session type instead of collapsing
+   * cast - keeping `A` concrete so `SessionOf<A>` recovers the real session type instead of collapsing
    * to `{}` and forcing per-call session casts downstream.
    */
   readonly options?: { readonly basePath?: string } & Record<string, unknown>
@@ -41,8 +41,8 @@ const HANDLED_METHODS = ["GET", "POST"] as const
 
 /**
  * Mount a better-auth instance into a nifra app: registers its handler at `${basePath}/*`
- * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint — sign-in/up/out, OAuth
- * callbacks, session, 2FA, magic links, … — is served by your nifra server.
+ * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint - sign-in/up/out, OAuth
+ * callbacks, session, 2FA, magic links, … - is served by your nifra server.
  *
  * ```ts
  * import { betterAuth, requireSession } from "@nifrajs/better-auth"
@@ -52,7 +52,7 @@ const HANDLED_METHODS = ["GET", "POST"] as const
  *   .get("/me", async (c) => (await requireSession(auth, c.req)).user)
  * ```
  *
- * Idempotent (named `"better-auth"` — applying twice mounts once). Read the session with
+ * Idempotent (named `"better-auth"` - applying twice mounts once). Read the session with
  * {@link getSession} / {@link requireSession}, which infer your better-auth types.
  */
 export function betterAuth(auth: BetterAuthLike, options: BetterAuthOptions = {}) {
@@ -60,7 +60,7 @@ export function betterAuth(auth: BetterAuthLike, options: BetterAuthOptions = {}
   const pattern = `${base.replace(/\/+$/, "")}/*` // strip trailing slash(es), then wildcard the subtree
   // A type-IDENTITY plugin (see defineIdentityPlugin): mounting the auth handler must NOT change the
   // route registry's type. A plain `definePlugin((app) => app)` would infer `app: Server<any, any>`, so
-  // `use`'s result — and the entire typed client derived from it — collapsed to `any`. This was the #1
+  // `use`'s result - and the entire typed client derived from it - collapsed to `any`. This was the #1
   // reported anti-drift bug: routes declared after `.use(betterAuth(...))` silently lost their types.
   return defineIdentityPlugin("better-auth", <S extends AnyServer>(app: S): S => {
     for (const method of HANDLED_METHODS) {
@@ -75,7 +75,7 @@ export function betterAuth(auth: BetterAuthLike, options: BetterAuthOptions = {}
 }
 
 /**
- * Resolve the better-auth session for a request — a thin, typed wrapper over `auth.api.getSession`.
+ * Resolve the better-auth session for a request - a thin, typed wrapper over `auth.api.getSession`.
  * Returns `null` when unauthenticated. Takes the raw `Request` so it works in both server handlers
  * (`c.req`) and web loaders/actions (`request`).
  *
@@ -95,7 +95,7 @@ export function getSession<A extends BetterAuthLike>(
 
 /**
  * What {@link requireSession} does on a missing session: `302` to `redirectTo` (a same-origin path),
- * or — when omitted — a `401` JSON (`{ ok: false, error: "unauthorized" }`). Mirrors `@nifrajs/auth` guards.
+ * or - when omitted - a `401` JSON (`{ ok: false, error: "unauthorized" }`). Mirrors `@nifrajs/auth` guards.
  */
 export interface RequireSessionOptions {
   readonly redirectTo?: string
@@ -105,7 +105,7 @@ const rejection = (options: RequireSessionOptions): Response => {
   const to = options.redirectTo
   if (to === undefined) return Response.json({ ok: false, error: "unauthorized" }, { status: 401 })
   // Same-origin guard (mirrors @nifrajs/web `redirect` + @nifrajs/auth guards): a single leading "/", never
-  // "//host" or an absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug — fail loud.
+  // "//host" or an absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug - fail loud.
   if (!to.startsWith("/") || to.startsWith("//")) {
     throw new Error(
       `[nifra/better-auth] requireSession redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`,
@@ -116,7 +116,7 @@ const rejection = (options: RequireSessionOptions): Response => {
 
 /**
  * Require an authenticated better-auth session at the top of a protected handler/loader/action.
- * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) — nifra
+ * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) - nifra
  * returns a thrown `Response` as-is, short-circuiting the rest of the handler.
  *
  * ```ts