@gusnips/react 0.9.4 → 0.9.6

package/README.md

@@ -75,6 +75,10 @@ anywhere that decision is made; the sentence you show is a separate question, an
 — "check your connection" is true of a request that never landed and false of a 502, which is
 ours. auth-js marks "nothing came back", and only that, with status 0.
 
+It is safe to hand it the `error` from a `{ data, error }` result without checking it first:
+`null` answers false. That is worth stating because `null` is the SUCCESS value of every
+supabase-js auth call, so the obvious `if (isAuthOutage(error))` is written against it constantly.
+
 Supabase email links have two complete patterns. Keep either one, never half of each:
 
 - A link carrying `token_hash` needs one explicit `verifyOtp` call. Guard it against React
@@ -82,11 +86,65 @@ Supabase email links have two complete patterns. Keep either one, never half of
 - A link carrying `ConfirmationURL` needs `detectSessionInUrl` enabled. That reader consumes an
   implicit `#access_token` or a PKCE `?code`; it does not consume `token_hash`.
 
+Either pattern can carry a destination — the `token_hash` one has to be asked. GoTrue hands every
+template a `{{ .RedirectTo }}`: the `redirectTo` the app passed, already checked against the
+allowlist, falling back to the Site URL when it was absent or not on it. A `{{ .ConfirmationURL }}`
+link carries it for you. A template that writes its own landing drops it unless it asks:
+
+```
+{{ .SiteURL }}/auth/callback?token_hash={{ .TokenHash }}&type=recovery&next={{ .RedirectTo }}
+```
+
+Leave that parameter off and `redirectTo` and `emailRedirectTo` do nothing on every e-mail flow,
+however carefully the app sets them — four of the codebases this came from pass one that the
+template throws away, so a person bounced off a protected page signs in and lands on the front
+door. Nothing reports it: the app's call is correct, the link works, and the destination was
+dropped in an HTML file hosted somewhere else.
+
+`{{ .RedirectTo }}` arrives as an absolute URL rather than a path, so the landing reads it as one:
+
+```ts
+const raw = new URLSearchParams(location.search).get("next");
+const url = raw ? new URL(raw, location.origin) : null;
+const next = url?.origin === location.origin ? safeInternalPath(url.pathname + url.search) : null;
+```
+
+Validate it on arrival even though GoTrue already did: that check is against a list of origins,
+so it says the link may come back here, not which page it may open.
+
 Recovery and invite links continue to the new-password screen after the session opens. A callback
 must also tell a used or expired link apart from a request that never landed — or one that landed
 and came back 5xx: the first needs a new link, and the other two can retry the same one, because
 the hash was never spent.
 
+`parseAuthCallback` reads a callback address and says what arrived:
+
+```ts
+import { parseAuthCallback } from "@gusnips/react/supabase";
+
+parseAuthCallback("?token_hash=abc&type=recovery");
+// → { kind: "email-link", tokenHash: "abc", type: "recovery" }
+```
+
+There are four kinds. `email-link` needs your one `verifyOtp` call. `session` is a PKCE `code` or
+implicit-flow tokens; in a browser the client has already taken it, so wait for the session, and on
+React Native hand `credential` to `exchangeCodeForSession` or `setSession`. `error` is a failure
+GoTrue wrote into the address. `invalid` is a link that was cut short or edited.
+
+Pass the fragment too — `parseAuthCallback(location.search, location.hash)`. GoTrue writes a
+failure into the fragment every time and into the query only sometimes: after an implicit-flow
+email link it is in the fragment alone, so a query-only reader shows nothing to somebody whose
+link expired.
+
+Choose the words by `code` (GoTrue's `error_code`, such as `otp_expired`), not by `error`.
+`access_denied` covers an expired link, a banned user and a disabled signup as well as a person
+pressing Cancel at Google; only the last one arrives with no code, and that is what `cancelled`
+means. A cancel was their choice, so say nothing or offer the button again.
+
+Every email link type is accepted, `invite` included, even if your templates never send it. An
+operator can still send one from Studio. Name a destination for each with
+`Record<EmailLinkType, string>`, so a new type is a compile error rather than a wrong page.
+
 There is also a deadline on every request, which none of the codebases this came from had. A
 request with no timeout is a spinner with no end.
 
@@ -339,15 +397,15 @@ something.
 `@gusnips/react` itself needs `react` and nothing else. Anything that needs another runtime peer
 lives behind a subpath, so you install a dependency only if you import the thing that uses it:
 
-| Import from               | What is in it                  | What you must have    |
-| ------------------------- | ------------------------------ | --------------------- |
-| `@gusnips/react`          | the client and rest            | react                 |
-| `@gusnips/react/store`    | `createAuthStore`, `authSlice` | zustand               |
-| `@gusnips/react/guards`   | the route guards               | react-router-dom      |
-| `@gusnips/react/hydrate`  | `hydrateOrMount`               | react-dom             |
-| `@gusnips/react/supabase` | the session adapter            | @supabase/supabase-js |
-| `@gusnips/react/ui`       | the seven wrappers             | @base-ui/react        |
-| `@gusnips/react/contract` | two prerender names            | nothing               |
+| Import from               | What is in it                            | What you must have    |
+| ------------------------- | ---------------------------------------- | --------------------- |
+| `@gusnips/react`          | the client and rest                      | react                 |
+| `@gusnips/react/store`    | `createAuthStore`, `authSlice`           | zustand               |
+| `@gusnips/react/guards`   | the route guards                         | react-router-dom      |
+| `@gusnips/react/hydrate`  | `hydrateOrMount`                         | react-dom             |
+| `@gusnips/react/supabase` | the session adapter, `parseAuthCallback` | @supabase/supabase-js |
+| `@gusnips/react/ui`       | the seven wrappers                       | @base-ui/react        |
+| `@gusnips/react/contract` | two prerender names                      | nothing               |
 
 The rule behind that table: **a peer marked optional must not be reachable from the main entry
 point.** An optional peer the barrel imports anyway is not optional — it is a required one whose

package/dist/supabase-session.d.ts

@@ -40,7 +40,8 @@ export interface SupabaseSessionAuth {
  * heading per RESOLVED version; `node_modules` keeps copies the resolver does not serve.
  *
  * Anything that is not an auth error at all answers true: a failure from outside auth-js is not
- * a verdict on the credential either.
+ * a verdict on the credential either. Nothing at all answers false — `null` is what every
+ * supabase-js auth call returns on success, and success is not an outage.
  */
 export declare function isAuthOutage(error: unknown): boolean;
 /**
@@ -52,5 +53,77 @@ export declare function isAuthOutage(error: unknown): boolean;
  * stays on that side of the line too.
  */
 export declare function createSupabaseSessionAdapter(auth: SupabaseSessionAuth): SessionAdapter;
+/**
+ * Every link type a GoTrue email can carry — not only the ones this app's templates send today.
+ * One donor rejected `invite` because "invites are never sent", which was true of the product and
+ * false of the deployment: an operator inviting somebody from Studio sent a branded email whose
+ * link then said it was invalid. A type the templates never emit costs nothing to accept: the hash
+ * is the proof, and GoTrue opens a session only for the person whose one-time token it is.
+ *
+ * Closed on purpose: auth-js's own `EmailOtpType` ends in `(string & {})`, so it cannot make a
+ * destination map name every case. `Record<EmailLinkType, string>` can, and that is where an app
+ * decides that `recovery` and `invite` both continue to the new-password screen — GoTrue creates
+ * an invited account with NO password, so landing one "inside" signs them in once and locks them
+ * out after.
+ */
+export type EmailLinkType = "signup" | "invite" | "magiclink" | "recovery" | "email_change" | "email";
+/** Everything an auth callback address can carry, decided from the address alone. */
+export type AuthCallback = 
+/** An email link with a one-use `token_hash`: trade it with `verifyOtp`, exactly once. */
+{
+    kind: "email-link";
+    tokenHash: string;
+    type: EmailLinkType;
+}
+/**
+ * A session arriving in the address: a PKCE `code`, or the implicit flow's tokens. In a browser
+ * with `detectSessionInUrl` on, the client has already taken it — wait for the session, and do
+ * not trade it again, which would be a second exchange racing the first. Where nothing reads
+ * the address for you (React Native), `credential` is what `exchangeCodeForSession` or
+ * `setSession` takes.
+ */
+ | {
+    kind: "session";
+    type: EmailLinkType | null;
+    credential: {
+        code: string;
+    } | {
+        access_token: string;
+        refresh_token: string;
+    };
+}
+/**
+ * GoTrue, or the provider behind it, reported a failure in the address. `code` is GoTrue's
+ * stable `error_code` (`otp_expired`, `bad_oauth_state`, …) and is what to choose words by;
+ * `error_description` is left out on purpose — it is English-only and often names the wrong
+ * cause.
+ */
+ | {
+    kind: "error";
+    error: string | null;
+    code: string | null;
+    cancelled: boolean;
+}
+/** Nothing usable: cut short between the mail client and here, or edited by hand. */
+ | {
+    kind: "invalid";
+};
+/**
+ * Reads an auth callback address. Pure, so every edge case is testable without a router or a
+ * client — pass `location.search` and `location.hash`, or the two halves of a deep link.
+ *
+ * GoTrue writes a failure into the FRAGMENT on every path and into the query only on some — the
+ * query too after a provider round trip, the fragment alone after an implicit-flow email link —
+ * so a callback reading one of the two misses a failure the other carries, and the person lands
+ * on a screen that says nothing. Both are read here.
+ *
+ * `cancelled` is the provider refusing on its own, which for Google is the person pressing Cancel
+ * — their choice, not a failure to report. It is NOT `error === "access_denied"`: GoTrue writes
+ * that same value for an expired email link, a banned user and a disabled signup, each with an
+ * `error_code` beside it, while a refusal relayed from the provider arrives with none. The obvious
+ * test reads an expired link as a change of mind. And `error` itself is absent for a status
+ * outside GoTrue's OAuth mapping — a rate-limited link arrives with `error_code` alone.
+ */
+export declare function parseAuthCallback(search: string | URLSearchParams, hash?: string): AuthCallback;
 export {};
 //# sourceMappingURL=supabase-session.d.ts.map

package/dist/supabase-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supabase-session.d.ts","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,UAAU,qBAAqB;IAC7B,IAAI,EAAE;QAAE,OAAO,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CACpD;AAED,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC,UAAU,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7C,cAAc,IAAI,OAAO,CAAC,qBAAqB,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,OAAO,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACxC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGpD;AAaD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,cAAc,CAsBtF"}
+{"version":3,"file":"supabase-session.d.ts","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,UAAU,qBAAqB;IAC7B,IAAI,EAAE;QAAE,OAAO,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CACpD;AAED,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC,UAAU,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7C,cAAc,IAAI,OAAO,CAAC,qBAAqB,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,OAAO,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACxC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASpD;AAaD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,cAAc,CAsBtF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GACvB,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,OAAO,CAAC;AAiB5E,qFAAqF;AACrF,MAAM,MAAM,YAAY;AACtB,0FAA0F;AACxF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE;AAChE;;;;;;GAMG;GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF;AACH;;;;;GAKG;GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE;AAClF,qFAAqF;GACnF;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE,IAAI,SAAK,GAAG,YAAY,CA6B3F"}

package/dist/supabase-session.js

@@ -23,9 +23,17 @@ import { isAuthError, isAuthRetryableFetchError } from "@supabase/supabase-js";
  * heading per RESOLVED version; `node_modules` keeps copies the resolver does not serve.
  *
  * Anything that is not an auth error at all answers true: a failure from outside auth-js is not
- * a verdict on the credential either.
+ * a verdict on the credential either. Nothing at all answers false — `null` is what every
+ * supabase-js auth call returns on success, and success is not an outage.
  */
 export function isAuthOutage(error) {
+    // Nothing thrown is not an outage, and this clause exists because the function is exported.
+    // `null` is the SUCCESS value of every supabase-js auth call, so the obvious
+    // `if (isAuthOutage(error))` around a `getUser()` result has to be safe; without this it read
+    // every success as auth being down. An adopter had already written that guard at its own call
+    // site, which is what a check missing from in here looks like from the outside.
+    if (error == null)
+        return false;
     if (!isAuthError(error))
         return true;
     return isAuthRetryableFetchError(error) || (error.status ?? 0) >= 500;
@@ -74,4 +82,59 @@ export function createSupabaseSessionAdapter(auth) {
         },
     };
 }
+const EMAIL_LINK_TYPES = {
+    signup: true,
+    invite: true,
+    magiclink: true,
+    recovery: true,
+    email_change: true,
+    email: true,
+};
+function isEmailLinkType(value) {
+    // Not `in`: `"toString" in EMAIL_LINK_TYPES` is true, and the type is typed by whoever sends
+    // the link.
+    return Object.hasOwn(EMAIL_LINK_TYPES, value);
+}
+/**
+ * Reads an auth callback address. Pure, so every edge case is testable without a router or a
+ * client — pass `location.search` and `location.hash`, or the two halves of a deep link.
+ *
+ * GoTrue writes a failure into the FRAGMENT on every path and into the query only on some — the
+ * query too after a provider round trip, the fragment alone after an implicit-flow email link —
+ * so a callback reading one of the two misses a failure the other carries, and the person lands
+ * on a screen that says nothing. Both are read here.
+ *
+ * `cancelled` is the provider refusing on its own, which for Google is the person pressing Cancel
+ * — their choice, not a failure to report. It is NOT `error === "access_denied"`: GoTrue writes
+ * that same value for an expired email link, a banned user and a disabled signup, each with an
+ * `error_code` beside it, while a refusal relayed from the provider arrives with none. The obvious
+ * test reads an expired link as a change of mind. And `error` itself is absent for a status
+ * outside GoTrue's OAuth mapping — a rate-limited link arrives with `error_code` alone.
+ */
+export function parseAuthCallback(search, hash = "") {
+    const query = new URLSearchParams(search);
+    const fragment = new URLSearchParams(hash.replace(/^#/, ""));
+    const read = (name) => query.get(name) || fragment.get(name) || null;
+    const error = read("error");
+    const code = read("error_code");
+    if (error || code || read("error_description"))
+        return { kind: "error", error, code, cancelled: error === "access_denied" && code === null };
+    const rawType = read("type") ?? "";
+    const type = isEmailLinkType(rawType) ? rawType : null;
+    const tokenHash = query.get("token_hash")?.trim();
+    if (tokenHash)
+        return type ? { kind: "email-link", tokenHash, type } : { kind: "invalid" };
+    const pkceCode = query.get("code");
+    if (pkceCode)
+        return { kind: "session", type, credential: { code: pkceCode } };
+    const accessToken = fragment.get("access_token");
+    const refreshToken = fragment.get("refresh_token");
+    if (accessToken && refreshToken)
+        return {
+            kind: "session",
+            type,
+            credential: { access_token: accessToken, refresh_token: refreshToken },
+        };
+    return { kind: "invalid" };
+}
 //# sourceMappingURL=supabase-session.js.map

package/dist/supabase-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"supabase-session.js","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,yBAAyB,EAAuB,MAAM,uBAAuB,CAAC;AAmBpG;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,yBAAyB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC;AACxE,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,0FAA0F;IAC1F,uFAAuF;IACvF,kFAAkF;IAClF,8EAA8E;IAC9E,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7D,8FAA8F;IAC9F,8FAA8F;IAC9F,OAAO,KAAK,CAAC,IAAI,KAAK,2BAA2B,CAAC;AACpD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAyB;IACpE,OAAO;QACL,QAAQ,EAAE,KAAK,IAAI,EAAE;YACnB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC,OAAO,EAAE,YAAY,IAAI,IAAI,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,IAAI,CAAC;gBACH,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpD,OAAO;oBACL,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,IAAI,IAAI;oBACzC,WAAW,EAAE,KAAK,KAAK,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC;iBAClD,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1D,CAAC;QACH,CAAC;QACD,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACvC,IAAI,KAAK;gBAAE,MAAM,KAAK,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"supabase-session.js","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",

package/src/supabase-session.test.ts

@@ -2,11 +2,13 @@ import {
   AuthApiError,
   AuthRefreshDiscardedError,
   AuthRetryableFetchError,
+  AuthUnknownError,
 } from "@supabase/supabase-js";
 import { describe, expect, it, vi } from "vitest";
 import {
   createSupabaseSessionAdapter,
   isAuthOutage,
+  parseAuthCallback,
   type SupabaseSessionAuth,
 } from "./supabase-session.ts";
 
@@ -130,4 +132,93 @@ describe("isAuthOutage", () => {
     expect(isAuthOutage(new AuthApiError("Insufficient Storage", 507, undefined))).toBe(true);
     expect(isAuthOutage(new AuthApiError("Network Connect Timeout", 599, undefined))).toBe(true);
   });
+
+  it("reads nothing-went-wrong as nothing went wrong", () => {
+    // `null` is the SUCCESS value of every supabase-js auth call, and this function is
+    // exported, so the obvious `if (isAuthOutage(error))` around a `getUser()` result has to
+    // be safe. Before this, it answered true and put an outage on screen over every success.
+    // One adopter had already written the guard at its own call site, which is what a missing
+    // check in here looks like from the outside.
+    expect(isAuthOutage(null)).toBe(false);
+    expect(isAuthOutage(undefined)).toBe(false);
+  });
+
+  it("stays narrow for an error auth-js could not read", () => {
+    // AuthUnknownError is raised whenever the body does not parse as JSON, at ANY status, and
+    // it never fills one in — but `status` is still PRESENT, because the base class declares
+    // it, so `"status" in error` answers true and says nothing. That makes a 507 behind an
+    // HTML-answering proxy indistinguishable from a malformed 400, and the narrow answer is
+    // the right one: widening by class name would call the malformed 400 an outage too, and a
+    // dead session read as retryable is the same failure from the other side.
+    const unreadable = new AuthUnknownError("Unexpected token < in JSON", new Error("parse"));
+    expect(unreadable.status).toBeUndefined();
+    expect(isAuthOutage(unreadable)).toBe(false);
+  });
+});
+
+describe("parseAuthCallback", () => {
+  it("reads an email link, including the types an app's templates may not send yet", () => {
+    expect(parseAuthCallback("?token_hash=pkce_abc&type=recovery")).toEqual({
+      kind: "email-link",
+      tokenHash: "pkce_abc",
+      type: "recovery",
+    });
+    // An operator can invite from Studio whatever the product does; rejecting the type put
+    // "invalid link" on a real, branded invitation.
+    expect(parseAuthCallback(new URLSearchParams("token_hash=abc&type=invite"))).toMatchObject({
+      kind: "email-link",
+      type: "invite",
+    });
+  });
+
+  it("refuses an email link whose type is missing or made up", () => {
+    expect(parseAuthCallback("?token_hash=abc")).toEqual({ kind: "invalid" });
+    expect(parseAuthCallback("?token_hash=abc&type=admin")).toEqual({ kind: "invalid" });
+    // A key every object inherits is still not a link type.
+    expect(parseAuthCallback("?token_hash=abc&type=toString")).toEqual({ kind: "invalid" });
+    expect(parseAuthCallback("", "")).toEqual({ kind: "invalid" });
+  });
+
+  it("hands back the session a URL carries, in either flow", () => {
+    expect(parseAuthCallback("?code=4f1c")).toEqual({
+      kind: "session",
+      type: null,
+      credential: { code: "4f1c" },
+    });
+    // The implicit flow puts the tokens, and a recovery's type, in the fragment.
+    expect(
+      parseAuthCallback("", "#access_token=at&expires_in=3600&refresh_token=rt&type=recovery"),
+    ).toEqual({
+      kind: "session",
+      type: "recovery",
+      credential: { access_token: "at", refresh_token: "rt" },
+    });
+    expect(parseAuthCallback("", "#access_token=at")).toEqual({ kind: "invalid" });
+  });
+
+  it("tells a person who pressed Cancel from a link that expired", () => {
+    // A refusal relayed from the provider: GoTrue writes it to both halves, with no code.
+    const cancel = "error=access_denied&error_description=The+user+denied+the+request";
+    expect(parseAuthCallback(`?${cancel}`, `#${cancel}&sb=`)).toEqual({
+      kind: "error",
+      error: "access_denied",
+      code: null,
+      cancelled: true,
+    });
+    // GoTrue's own refusal of an implicit-flow email link: the SAME error, a code beside it,
+    // and only in the fragment — a query-only reader sees nothing at all.
+    expect(
+      parseAuthCallback(
+        "",
+        "#error=access_denied&error_code=otp_expired&error_description=Email+link+is+invalid+or+has+expired&sb=",
+      ),
+    ).toEqual({ kind: "error", error: "access_denied", code: "otp_expired", cancelled: false });
+  });
+
+  it("reads a failure that carries no `error` at all", () => {
+    // Statuses outside GoTrue's OAuth mapping, a 429 among them, write only the code.
+    expect(
+      parseAuthCallback("", "#error_code=over_email_send_rate_limit&error_description=x&sb="),
+    ).toEqual({ kind: "error", error: null, code: "over_email_send_rate_limit", cancelled: false });
+  });
 });

package/src/supabase-session.ts

@@ -41,9 +41,16 @@ type _SupabaseAuthFitsAdapter = Satisfied<
  * heading per RESOLVED version; `node_modules` keeps copies the resolver does not serve.
  *
  * Anything that is not an auth error at all answers true: a failure from outside auth-js is not
- * a verdict on the credential either.
+ * a verdict on the credential either. Nothing at all answers false — `null` is what every
+ * supabase-js auth call returns on success, and success is not an outage.
  */
 export function isAuthOutage(error: unknown): boolean {
+  // Nothing thrown is not an outage, and this clause exists because the function is exported.
+  // `null` is the SUCCESS value of every supabase-js auth call, so the obvious
+  // `if (isAuthOutage(error))` around a `getUser()` result has to be safe; without this it read
+  // every success as auth being down. An adopter had already written that guard at its own call
+  // site, which is what a check missing from in here looks like from the outside.
+  if (error == null) return false;
   if (!isAuthError(error)) return true;
   return isAuthRetryableFetchError(error) || (error.status ?? 0) >= 500;
 }
@@ -90,3 +97,107 @@ export function createSupabaseSessionAdapter(auth: SupabaseSessionAuth): Session
     },
   };
 }
+
+/**
+ * Every link type a GoTrue email can carry — not only the ones this app's templates send today.
+ * One donor rejected `invite` because "invites are never sent", which was true of the product and
+ * false of the deployment: an operator inviting somebody from Studio sent a branded email whose
+ * link then said it was invalid. A type the templates never emit costs nothing to accept: the hash
+ * is the proof, and GoTrue opens a session only for the person whose one-time token it is.
+ *
+ * Closed on purpose: auth-js's own `EmailOtpType` ends in `(string & {})`, so it cannot make a
+ * destination map name every case. `Record<EmailLinkType, string>` can, and that is where an app
+ * decides that `recovery` and `invite` both continue to the new-password screen — GoTrue creates
+ * an invited account with NO password, so landing one "inside" signs them in once and locks them
+ * out after.
+ */
+export type EmailLinkType =
+  "signup" | "invite" | "magiclink" | "recovery" | "email_change" | "email";
+
+const EMAIL_LINK_TYPES: Record<EmailLinkType, true> = {
+  signup: true,
+  invite: true,
+  magiclink: true,
+  recovery: true,
+  email_change: true,
+  email: true,
+};
+
+function isEmailLinkType(value: string): value is EmailLinkType {
+  // Not `in`: `"toString" in EMAIL_LINK_TYPES` is true, and the type is typed by whoever sends
+  // the link.
+  return Object.hasOwn(EMAIL_LINK_TYPES, value);
+}
+
+/** Everything an auth callback address can carry, decided from the address alone. */
+export type AuthCallback =
+  /** An email link with a one-use `token_hash`: trade it with `verifyOtp`, exactly once. */
+  | { kind: "email-link"; tokenHash: string; type: EmailLinkType }
+  /**
+   * A session arriving in the address: a PKCE `code`, or the implicit flow's tokens. In a browser
+   * with `detectSessionInUrl` on, the client has already taken it — wait for the session, and do
+   * not trade it again, which would be a second exchange racing the first. Where nothing reads
+   * the address for you (React Native), `credential` is what `exchangeCodeForSession` or
+   * `setSession` takes.
+   */
+  | {
+      kind: "session";
+      type: EmailLinkType | null;
+      credential: { code: string } | { access_token: string; refresh_token: string };
+    }
+  /**
+   * GoTrue, or the provider behind it, reported a failure in the address. `code` is GoTrue's
+   * stable `error_code` (`otp_expired`, `bad_oauth_state`, …) and is what to choose words by;
+   * `error_description` is left out on purpose — it is English-only and often names the wrong
+   * cause.
+   */
+  | { kind: "error"; error: string | null; code: string | null; cancelled: boolean }
+  /** Nothing usable: cut short between the mail client and here, or edited by hand. */
+  | { kind: "invalid" };
+
+/**
+ * Reads an auth callback address. Pure, so every edge case is testable without a router or a
+ * client — pass `location.search` and `location.hash`, or the two halves of a deep link.
+ *
+ * GoTrue writes a failure into the FRAGMENT on every path and into the query only on some — the
+ * query too after a provider round trip, the fragment alone after an implicit-flow email link —
+ * so a callback reading one of the two misses a failure the other carries, and the person lands
+ * on a screen that says nothing. Both are read here.
+ *
+ * `cancelled` is the provider refusing on its own, which for Google is the person pressing Cancel
+ * — their choice, not a failure to report. It is NOT `error === "access_denied"`: GoTrue writes
+ * that same value for an expired email link, a banned user and a disabled signup, each with an
+ * `error_code` beside it, while a refusal relayed from the provider arrives with none. The obvious
+ * test reads an expired link as a change of mind. And `error` itself is absent for a status
+ * outside GoTrue's OAuth mapping — a rate-limited link arrives with `error_code` alone.
+ */
+export function parseAuthCallback(search: string | URLSearchParams, hash = ""): AuthCallback {
+  const query = new URLSearchParams(search);
+  const fragment = new URLSearchParams(hash.replace(/^#/, ""));
+  const read = (name: string) => query.get(name) || fragment.get(name) || null;
+
+  const error = read("error");
+  const code = read("error_code");
+  if (error || code || read("error_description"))
+    return { kind: "error", error, code, cancelled: error === "access_denied" && code === null };
+
+  const rawType = read("type") ?? "";
+  const type = isEmailLinkType(rawType) ? rawType : null;
+
+  const tokenHash = query.get("token_hash")?.trim();
+  if (tokenHash) return type ? { kind: "email-link", tokenHash, type } : { kind: "invalid" };
+
+  const pkceCode = query.get("code");
+  if (pkceCode) return { kind: "session", type, credential: { code: pkceCode } };
+
+  const accessToken = fragment.get("access_token");
+  const refreshToken = fragment.get("refresh_token");
+  if (accessToken && refreshToken)
+    return {
+      kind: "session",
+      type,
+      credential: { access_token: accessToken, refresh_token: refreshToken },
+    };
+
+  return { kind: "invalid" };
+}