@gusnips/react 0.8.1 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "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",
@@ -22,6 +22,10 @@
       "types": "./dist/auth-store.d.ts",
       "default": "./dist/auth-store.js"
     },
+    "./supabase": {
+      "types": "./dist/supabase-session.d.ts",
+      "default": "./dist/supabase-session.js"
+    },
     "./guards": {
       "types": "./dist/guards.d.ts",
       "default": "./dist/guards.js"
@@ -78,6 +82,7 @@
   },
   "peerDependencies": {
     "@base-ui/react": "^1.6.0",
+    "@supabase/supabase-js": "^2",
     "@tanstack/react-query": "^5",
     "i18next": ">=25",
     "react": "^19",
@@ -90,6 +95,9 @@
     "@base-ui/react": {
       "optional": true
     },
+    "@supabase/supabase-js": {
+      "optional": true
+    },
     "@tanstack/react-query": {
       "optional": true
     },
@@ -111,6 +119,7 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1.8.0",
+    "@supabase/supabase-js": "^2.112.4",
     "@tanstack/react-query": "^5.102.8",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",

package/src/api-client.test.ts

@@ -26,7 +26,10 @@ function session(overrides: Partial<SessionAdapter> = {}): SessionAdapter {
   };
 }
 
-afterEach(() => vi.unstubAllGlobals());
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
 
 describe("createApiClient", () => {
   it("unwraps the success envelope", async () => {
@@ -164,6 +167,49 @@ describe("createApiClient", () => {
     expect((error as ApiError).expected).toBe(false);
   });
 
+  it("remembers an auth answer across later failed refresh attempts", async () => {
+    stubFetch(() => unauthorized());
+    const onSessionDead = vi.fn();
+    let refreshes = 0;
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session({
+        refresh: async () =>
+          ++refreshes === 1
+            ? { token: null, reachedAuth: true }
+            : { token: null, reachedAuth: false },
+      }),
+      onSessionDead,
+      refreshRetryDelayMs: 0,
+    });
+
+    const error = await api.get("/me").catch((e: unknown) => e);
+    expect(refreshes).toBe(2);
+    expect(onSessionDead).toHaveBeenCalledTimes(1);
+    expect((error as ApiError).expected).toBe(true);
+  });
+
+  it("uses the fail-safe when sign-out never settles", async () => {
+    vi.useFakeTimers();
+    stubFetch(() => unauthorized());
+    const onSessionDead = vi.fn();
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session({
+        refresh: async () => ({ token: null, reachedAuth: true }),
+        signOut: () => new Promise(() => {}),
+      }),
+      onSessionDead,
+      maxRefreshAttempts: 1,
+      signOutTimeoutMs: 3_000,
+    });
+
+    await api.get("/me").catch(() => {});
+    expect(onSessionDead).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(3_000);
+    expect(onSessionDead).toHaveBeenCalledTimes(1);
+  });
+
   it("signs out once when auth actually says no", async () => {
     stubFetch(() => unauthorized());
     const onSessionDead = vi.fn();

package/src/api-client.ts

@@ -354,7 +354,9 @@ export function createApiClient({
       for (let attempt = 0; attempt < maxRefreshAttempts; attempt++) {
         if (attempt > 0) await sleep(refreshRetryDelayMs);
         const result = await refresh();
-        answered = result.reachedAuth;
+        // A later network miss cannot erase an earlier answer from auth. The attempts are one
+        // investigation of this session, and one definitive "no" settles it.
+        answered ||= result.reachedAuth;
         if (!result.token) continue;
         refused = result.token;
         res = await send(path, result.token, options);

package/src/api-error.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { ApiError, parseRetryAfter, retryAfterSecs } from "./api-error.ts";
+import { ApiError, parseRetryAfter, retryAfterSecs, waitingNeverHelps } from "./api-error.ts";
 
 /**
  * Two APIs, two places for the same fact: one states the wait in the `Retry-After` header (the
@@ -38,6 +38,51 @@ describe("retryAfterSecs", () => {
     expect(retryAfterSecs(new ApiError(429, { code: "X", message: "", details: null }))).toBeNull();
     expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
   });
+
+  // And it keeps answering `null` for a stated never, which is what its callers want: there is
+  // no countdown to show. The claim is a separate question, asked separately.
+  it("answers null for a stated never, same as for silence", () => {
+    const stated = new ApiError(429, {
+      code: "X",
+      message: "",
+      details: { retryAfterSecs: null },
+    });
+    expect(retryAfterSecs(stated)).toBeNull();
+    expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
+  });
+});
+
+/**
+ * The claim `retryAfterSecs` cannot carry: an explicit `null` in the body, meaning waiting will
+ * never fix this. It has to be told apart from an absent key, which is silence.
+ */
+describe("waitingNeverHelps", () => {
+  const withDetails = (details: unknown) => new ApiError(429, { code: "X", message: "", details });
+
+  it("reads a present null as the claim", () => {
+    expect(waitingNeverHelps(withDetails({ retryAfterSecs: null }))).toBe(true);
+  });
+
+  it("reads silence as no claim", () => {
+    expect(waitingNeverHelps(withDetails({ scope: "account" }))).toBe(false);
+    expect(waitingNeverHelps(withDetails({}))).toBe(false);
+    expect(waitingNeverHelps(new ApiError(429, null))).toBe(false);
+  });
+
+  it("reads a stated wait as no claim", () => {
+    expect(waitingNeverHelps(withDetails({ retryAfterSecs: 30 }))).toBe(false);
+    // The header is not a channel for this — there is no `Retry-After` that says "never".
+    expect(waitingNeverHelps(new ApiError(429, null, { retryAfterSecs: 30 }))).toBe(false);
+  });
+
+  // `details` is whatever the server put there, so the shape is a trust boundary. A JSON `null`
+  // is the one that bites: `typeof null` is `"object"`, so a missing guard reads a property off
+  // it and throws inside a retry rule.
+  it("survives a details that is not an object", () => {
+    expect(waitingNeverHelps(withDetails(null))).toBe(false);
+    expect(waitingNeverHelps(withDetails("nope"))).toBe(false);
+    expect(waitingNeverHelps(withDetails(7))).toBe(false);
+  });
 });
 
 /**

package/src/api-error.ts

@@ -70,6 +70,11 @@ export class ApiError extends Error {
  * The header first, because it is the standard one and it is what a limiter emits without being
  * asked; then `details.retryAfterSecs`, which one donor's API sends in the body instead. A
  * caller asking "how long" should not have to know which server it is talking to.
+ *
+ * It deliberately does not answer whether waiting helps at all. `null` here means "no countdown
+ * to show", which is the right answer both for a refusal that said nothing and for one that said
+ * waiting will never fix it — and the adopters' countdown UIs read it for exactly that. Telling
+ * those two apart is {@link waitingNeverHelps}.
  */
 export function retryAfterSecs(error: ApiError): number | null {
   if (error.retryAfterSecs !== undefined) return error.retryAfterSecs;
@@ -79,6 +84,32 @@ export function retryAfterSecs(error: ApiError): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+/**
+ * Did the answer say, in so many words, that waiting will never fix this?
+ *
+ * The server half of this fleet sends `details.retryAfterSecs: null` on a refusal no amount of
+ * time clears — a cap that frees only when somebody deletes something, a concurrency slot that
+ * frees when another job ends. An explicit `null` is a claim somebody has to read; an omitted key
+ * is invisible. That is the whole reason the two must not collapse into one answer: this is the
+ * server naming what `durableLimitCodes` otherwise makes every app name by hand, one code at a
+ * time, and keep in step with a backend it does not own.
+ *
+ * Present-and-`null` is the entire test. An absent key reads as `undefined`, so `=== null`
+ * already separates the claim from the silence and an `in` check would only widen it to every
+ * stated wait. Body-only by design: `Retry-After` has no spelling for "never".
+ *
+ * Not exported from the package, and that is the point: it is not "is this refusal durable?". It
+ * says nothing about a durable CODE or a wait too long to hold, so an error surface branching on
+ * it would answer differently from the retry rule for every limit the app names itself. The one
+ * question worth asking out loud is `shouldRetry`, and `describeError` already derives the
+ * control it offers from exactly that — invariant 8, one rule and two consumers.
+ */
+export function waitingNeverHelps(error: ApiError): boolean {
+  const details = error.details;
+  if (typeof details !== "object" || details === null) return false;
+  return (details as { retryAfterSecs?: unknown }).retryAfterSecs === null;
+}
+
 /**
  * `Retry-After` in either spec form: delay-seconds, or an HTTP-date.
  *

package/src/guards.test.ts

@@ -13,7 +13,7 @@ import {
 // lets the redirect cases assert a destination without rendering anything.
 const router = vi.hoisted(() => ({
   Navigate: vi.fn(),
-  useLocation: vi.fn(() => ({ pathname: "/posts", search: "?page=2" })),
+  useLocation: vi.fn(() => ({ pathname: "/posts", search: "?page=2", hash: "#comments" })),
 }));
 vi.mock("react-router-dom", () => router);
 
@@ -96,13 +96,12 @@ describe("createRequireAuth", () => {
     expect(branch(render(guard(false, true)))).toBe("LOADING");
   });
 
-  // The redirect carries where they were headed, query string included: an adopter's sign-in screen
-  // reads `location.state.from` to land them on the page they actually wanted rather than the home
-  // screen. One donor hardcoded this in four places, which is what made it a factory.
-  it("remembers the address it turned away", () => {
+  // The URL carries the whole destination because router state is lost on reload, OAuth and email
+  // links. The sign-in screen reads `next`, validates it, and replaces this history entry.
+  it("remembers the whole address it turned away", () => {
     expect(branch(render(guard(false)))).toEqual({
-      to: "/login",
-      state: { from: "/posts?page=2" },
+      to: "/login?next=%2Fposts%3Fpage%3D2%23comments",
+      state: undefined,
     });
   });
 
@@ -123,6 +122,27 @@ describe("createRequireAnonymous", () => {
     expect(branch(render(guard(true)))).toEqual({ to: "/", state: undefined });
   });
 
+  it("resumes a carried internal route", () => {
+    router.useLocation.mockReturnValueOnce({
+      pathname: "/login",
+      search: "?next=%2Fposts%3Fpage%3D2%23comments",
+      hash: "",
+    });
+    expect(branch(render(guard(true)))).toEqual({
+      to: "/posts?page=2#comments",
+      state: undefined,
+    });
+  });
+
+  it("falls home instead of following an external target", () => {
+    router.useLocation.mockReturnValueOnce({
+      pathname: "/login",
+      search: "?next=%2F%2Fevil.test",
+      hash: "",
+    });
+    expect(branch(render(guard(true)))).toEqual({ to: "/", state: undefined });
+  });
+
   it("lets an anonymous visitor through", () => {
     expect(branch(render(guard(false)))).toBe("CONTENT");
   });

package/src/guards.tsx

@@ -1,6 +1,7 @@
 import type { UseQueryResult } from "@tanstack/react-query";
 import type { ReactNode } from "react";
 import { Navigate, useLocation } from "react-router-dom";
+import { safeInternalPath } from "./internal-path.ts";
 
 /**
  * Route guards.
@@ -58,6 +59,14 @@ export interface GuardOptions {
   loading: ReactNode;
 }
 
+/** Query parameter carrying the route a sign-in interrupted. */
+export const AUTH_RETURN_PARAM = "next";
+
+function signInUrl(signInPath: string, returnTo: string): string {
+  const separator = signInPath.includes("?") ? "&" : "?";
+  return `${signInPath}${separator}${AUTH_RETURN_PARAM}=${encodeURIComponent(returnTo)}`;
+}
+
 /**
  * Signed in, or off to sign in — remembering where they were headed, so the redirect afterwards
  * lands on the page they actually wanted rather than the home screen.
@@ -71,10 +80,13 @@ export function createRequireAuth(
     const { isAuthenticated, isLoading } = useSession();
     const location = useLocation();
     if (isLoading) return <>{loading}</>;
-    if (!isAuthenticated)
-      return (
-        <Navigate to={signInPath} replace state={{ from: location.pathname + location.search }} />
-      );
+    if (!isAuthenticated) {
+      // Query state survives a reload, an OAuth round trip and an email-link round trip. Router
+      // state survives none of them, so it only looked like a remembered destination on the
+      // password path. The hash belongs too: tabs and anchored settings are real destinations.
+      const returnTo = location.pathname + location.search + location.hash;
+      return <Navigate to={signInUrl(signInPath, returnTo)} replace />;
+    }
     return <>{children}</>;
   };
 }
@@ -87,8 +99,12 @@ export function createRequireAnonymous(
 ) {
   return function RequireAnonymous({ children }: { children: ReactNode }) {
     const { isAuthenticated, isLoading } = useSession();
+    const location = useLocation();
     if (isLoading) return <>{loading}</>;
-    if (isAuthenticated) return <Navigate to={homePath} replace />;
+    if (isAuthenticated) {
+      const carried = new URLSearchParams(location.search).get(AUTH_RETURN_PARAM);
+      return <Navigate to={safeInternalPath(carried) ?? homePath} replace />;
+    }
     return <>{children}</>;
   };
 }

package/src/index.ts

@@ -8,10 +8,11 @@
 // with the error moved from install time to the adopter's first build, which is the worse of the
 // two places to find out.
 //
-//   @gusnips/react/ui       the Base UI wrappers   → @base-ui/react
-//   @gusnips/react/store    createAuthStore        → zustand
-//   @gusnips/react/guards   the route guards       → react-router-dom
-//   @gusnips/react/hydrate  hydrateOrMount         → react-dom
+//   @gusnips/react/ui        the Base UI wrappers   → @base-ui/react
+//   @gusnips/react/store     createAuthStore        → 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
 //
 // `react-dom` is the one the second migration added, and it is the sharpest case yet: that
 // adopter ships a REACT NATIVE app beside its two web apps, and React Native has no react-dom to
@@ -28,6 +29,7 @@
 // identical in source.
 
 export { cn } from "./cn.ts";
+export { safeInternalPath } from "./internal-path.ts";
 
 export { ApiError, isAbortError, retryAfterSecs } from "./api-error.ts";
 export {

package/src/internal-path.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { safeInternalPath } from "./internal-path.ts";
+
+describe("safeInternalPath", () => {
+  it.each([
+    ["/", "/"],
+    ["/posts?page=2#comments", "/posts?page=2#comments"],
+    ["/safe\\child", "/safe/child"],
+    ["/%252f%252fevil.test", "/%252f%252fevil.test"],
+  ])("keeps %s on this origin", (value, expected) => {
+    expect(safeInternalPath(value)).toBe(expected);
+  });
+
+  it.each([
+    null,
+    undefined,
+    7,
+    "",
+    "posts",
+    "https://evil.test",
+    "//evil.test",
+    "/\\evil.test",
+    `/\t/evil.test`,
+    `/\n/evil.test`,
+  ])("refuses an external or malformed target: %s", (value) => {
+    expect(safeInternalPath(value)).toBeNull();
+  });
+});

package/src/internal-path.ts

@@ -0,0 +1,29 @@
+const INTERNAL_ORIGIN = "https://frontkit.invalid";
+
+function containsControl(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code <= 0x1f || code === 0x7f) return true;
+  }
+  return false;
+}
+
+/**
+ * A route the browser can follow without leaving the current origin.
+ *
+ * Return targets cross a trust boundary: query strings, history state and storage are all writable
+ * by somebody outside the app. `startsWith("/")` is not enough — URL parsers read both `//host`
+ * and `/\\host` as another origin, and strip tabs or newlines before making the same decision.
+ * Parsing against a fixed origin applies the browser's own rules rather than trying to copy them.
+ */
+export function safeInternalPath(value: unknown): string | null {
+  if (typeof value !== "string" || !value.startsWith("/") || containsControl(value)) return null;
+
+  try {
+    const url = new URL(value, INTERNAL_ORIGIN);
+    if (url.origin !== INTERNAL_ORIGIN) return null;
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return null;
+  }
+}

package/src/query.test.ts

@@ -9,6 +9,14 @@ const refusal = (status: number, code?: string) =>
 const waited = (status: number, secs: number) =>
   new ApiError(status, null, { retryAfterSecs: secs });
 
+/** A refusal whose body says, in so many words, that waiting will never clear it. */
+const never = (status: number) =>
+  new ApiError(status, { code: "LIMIT_REACHED", message: "", details: { retryAfterSecs: null } });
+
+/** The same body with no such key: details, but no claim either way. */
+const silent = (status: number) =>
+  new ApiError(status, { code: "LIMIT_REACHED", message: "", details: { scope: "account" } });
+
 // Invariant 8, and the reason this module exists: three donors wrote three retry rules and
 // each was right about something the other two got wrong. Every case below is one of those.
 describe("shouldRetry", () => {
@@ -56,6 +64,38 @@ describe("shouldRetry", () => {
     expect(shouldRetry(refusal(503, "QUOTA_EXCEEDED"), ["QUOTA_EXCEEDED"])).toBe(false);
   });
 
+  // The same judgement with the server doing the naming. The server half of this fleet sends
+  // `details.retryAfterSecs: null` on a refusal no amount of time clears — a cap that frees only
+  // when somebody deletes something, a slot that frees when another job ends. Read as "nothing
+  // said how long", which is how every version before this one read it, that 429 gets retried
+  // against a limit that cannot move, and the app has to keep a `durableLimitCodes` entry for a
+  // claim the answer already carries.
+  it("does not retry a refusal whose body says waiting never helps", () => {
+    expect(shouldRetry(never(429))).toBe(false);
+    // And it outranks the status, exactly as a durable code does.
+    expect(shouldRetry(never(503))).toBe(false);
+  });
+
+  // The distinction the rule above rests on: an absent key is silence, not a claim, and silence
+  // has always meant "retry a transient failure". Only a key that is present and `null` is the
+  // claim — which is why this reads `=== null` and not `in`.
+  it("still retries when the body carries details but no stated wait", () => {
+    expect(shouldRetry(silent(500))).toBe(true);
+    expect(shouldRetry(silent(429))).toBe(true);
+  });
+
+  // A header wait and a body `null` contradict each other. The `null` is written by whoever
+  // raised this particular refusal; the number can come from a limiter that attaches one to
+  // every 429 it emits, so the hand-written claim is the more specific one.
+  it("takes an explicit never over a stated wait", () => {
+    const both = new ApiError(
+      429,
+      { code: "LIMIT_REACHED", message: "", details: { retryAfterSecs: null } },
+      { retryAfterSecs: 2 },
+    );
+    expect(shouldRetry(both)).toBe(false);
+  });
+
   // The second migration's rule. Its limiter answers `Retry-After: 60` on a per-minute window,
   // so retrying at 1s and 2s spends two more requests that cannot possibly succeed.
   it("does not retry a stated wait longer than we will hold", () => {

package/src/query.ts

@@ -1,5 +1,5 @@
 import type { DefaultOptions } from "@tanstack/react-query";
-import { ApiError, retryAfterSecs } from "./api-error.ts";
+import { ApiError, retryAfterSecs, waitingNeverHelps } from "./api-error.ts";
 
 /**
  * react-query defaults — the merge of three repos that each got part of this right.
@@ -21,6 +21,11 @@ import { ApiError, retryAfterSecs } from "./api-error.ts";
  * same limiter, and three seconds added before the screen says anything. So a stated wait is
  * waited out when it is short, and is an ANSWER when it is not.
  *
+ * The fifth rule came from the server half of this fleet rather than from a donor: a refusal can
+ * state that waiting will never fix it at all, by sending `details.retryAfterSecs: null`. Read as
+ * "did not say how long" — which is what every version before this one did — that 429 is retried
+ * against a limit no amount of time moves.
+ *
  * This is invariant 8.
  */
 
@@ -34,6 +39,10 @@ export interface QueryDefaultsOptions {
    * Error codes that mean "this limit does not clear by waiting" — a spent monthly quota, a
    * balance that needs topping up. They usually arrive as 402 or 429; the status alone cannot
    * tell them apart from a burst limit, which is why the caller names them.
+   *
+   * Only needed where the server does not say so itself. One that sends
+   * `details.retryAfterSecs: null` has already made the claim and `shouldRetry` reads it, which
+   * is one entry fewer to keep in step with a backend this app does not own.
    */
   durableLimitCodes?: readonly string[];
   /** How many times to retry a transient failure. Two donors used 2, one used 1. */
@@ -74,6 +83,13 @@ export function shouldRetry(
 
   if (error.code !== undefined && durableLimitCodes.includes(error.code)) return false;
 
+  // The same judgement, made by the server instead of by a list the app maintains: an explicit
+  // `details.retryAfterSecs: null` means waiting will never fix this. Checked before the stated
+  // wait because the two can contradict each other, and the `null` is written by whoever raised
+  // this particular refusal where a number can come from a limiter that attaches one to every
+  // 429 it emits.
+  if (waitingNeverHelps(error)) return false;
+
   // It told us when it clears. A wait we are not willing to hold is a refusal, not a hiccup —
   // and it is the same judgement `durableLimitCodes` makes, except the server did the naming.
   const wait = retryAfterSecs(error);

package/src/supabase-session.test.ts

@@ -0,0 +1,91 @@
+import {
+  AuthApiError,
+  AuthRefreshDiscardedError,
+  AuthRetryableFetchError,
+} from "@supabase/supabase-js";
+import { describe, expect, it, vi } from "vitest";
+import { createSupabaseSessionAdapter, type SupabaseSessionAuth } from "./supabase-session.ts";
+
+function auth(overrides: Partial<SupabaseSessionAuth> = {}): SupabaseSessionAuth {
+  return {
+    getSession: async () => ({ data: { session: { access_token: "old-token" } } }),
+    refreshSession: async () => ({
+      data: { session: { access_token: "new-token" } },
+      error: null,
+    }),
+    signOut: async () => ({ error: null }),
+    ...overrides,
+  };
+}
+
+describe("createSupabaseSessionAdapter", () => {
+  it("reads the current token and the refreshed token", async () => {
+    const adapter = createSupabaseSessionAdapter(auth());
+
+    await expect(adapter.getToken()).resolves.toBe("old-token");
+    await expect(adapter.refresh()).resolves.toEqual({
+      token: "new-token",
+      reachedAuth: true,
+    });
+  });
+
+  it("keeps the session when a refresh never reached auth", async () => {
+    const retryable = new AuthRetryableFetchError("offline", 0);
+    const returned = createSupabaseSessionAdapter(
+      auth({
+        refreshSession: async () => ({ data: { session: null }, error: retryable }),
+      }),
+    );
+    const thrown = createSupabaseSessionAdapter(
+      auth({
+        refreshSession: async () => {
+          throw new TypeError("fetch failed");
+        },
+      }),
+    );
+
+    await expect(returned.refresh()).resolves.toEqual({ token: null, reachedAuth: false });
+    await expect(thrown.refresh()).resolves.toEqual({ token: null, reachedAuth: false });
+  });
+
+  it("marks a terminal auth refusal whether it is returned or thrown", async () => {
+    const refusal = new AuthApiError("expired", 401, "refresh_token_not_found");
+    const returned = createSupabaseSessionAdapter(
+      auth({
+        refreshSession: async () => ({ data: { session: null }, error: refusal }),
+      }),
+    );
+    const thrown = createSupabaseSessionAdapter(
+      auth({
+        refreshSession: async () => {
+          throw refusal;
+        },
+      }),
+    );
+
+    await expect(returned.refresh()).resolves.toEqual({ token: null, reachedAuth: true });
+    await expect(thrown.refresh()).resolves.toEqual({ token: null, reachedAuth: true });
+  });
+
+  it("does not kill a session whose rotated refresh was discarded after a local race", async () => {
+    const adapter = createSupabaseSessionAdapter(
+      auth({
+        refreshSession: async () => ({
+          data: { session: null },
+          error: new AuthRefreshDiscardedError(),
+        }),
+      }),
+    );
+
+    await expect(adapter.refresh()).resolves.toEqual({ token: null, reachedAuth: false });
+  });
+
+  it("turns a resolved sign-out error into a rejection", async () => {
+    const refusal = new AuthApiError("unavailable", 503, "unexpected_failure");
+    const signOut = vi.fn(async () => ({ error: refusal }));
+    const adapter = createSupabaseSessionAdapter(auth({ signOut }));
+
+    await expect(adapter.signOut()).rejects.toBe(refusal);
+    expect(signOut).toHaveBeenCalledOnce();
+  });
+});

package/src/supabase-session.ts

@@ -0,0 +1,56 @@
+import { isAuthError, isAuthRetryableFetchError, type SupabaseClient } from "@supabase/supabase-js";
+import type { SessionAdapter } from "./api-client.ts";
+
+interface SupabaseSessionResult {
+  data: { session: { access_token: string } | null };
+}
+
+/** The three auth calls the API client needs, kept structural so any Supabase schema fits. */
+export interface SupabaseSessionAuth {
+  getSession(): Promise<SupabaseSessionResult>;
+  refreshSession(): Promise<SupabaseSessionResult & { error: unknown }>;
+  signOut(): Promise<{ error: unknown }>;
+}
+
+type Satisfied<T extends true> = T;
+type _SupabaseAuthFitsAdapter = Satisfied<
+  SupabaseClient["auth"] extends SupabaseSessionAuth ? true : false
+>;
+
+function reachedAuth(error: unknown): boolean {
+  if (!isAuthError(error) || isAuthRetryableFetchError(error)) return false;
+  // Newer clients name a refresh that reached GoTrue but was deliberately discarded because the
+  // local session changed mid-flight. That race is a no-op, not proof that either session died.
+  return error.name !== "AuthRefreshDiscardedError";
+}
+
+/**
+ * Connects a Supabase auth client to {@link SessionAdapter}.
+ *
+ * The distinction this preserves is the one that decides whether anybody is signed out: a
+ * retryable fetch error never reached GoTrue and says nothing about the session; any other auth
+ * error is an answer. A thrown network error stays on the first side of that line too.
+ */
+export function createSupabaseSessionAdapter(auth: SupabaseSessionAuth): SessionAdapter {
+  return {
+    getToken: async () => {
+      const { data } = await auth.getSession();
+      return data.session?.access_token ?? null;
+    },
+    refresh: async () => {
+      try {
+        const { data, error } = await auth.refreshSession();
+        return {
+          token: data.session?.access_token ?? null,
+          reachedAuth: error === null || reachedAuth(error),
+        };
+      } catch (error) {
+        return { token: null, reachedAuth: reachedAuth(error) };
+      }
+    },
+    signOut: async () => {
+      const { error } = await auth.signOut();
+      if (error) throw error;
+    },
+  };
+}