@gusnips/react 0.9.2 → 0.9.4

package/README.md

@@ -34,9 +34,11 @@ token when you use it, so the losers of that race each invalidate the winner —
 signed out in the middle of a load that was working. Three separate codebases arrived at
 single-flight refresh independently. This is that.
 
-**A refresh that never reached the server is not a "no".** Dropping a packet tells you nothing
-about whether a session is good. So `refresh()` answers `{ token, reachedAuth }`, and only a real
-refusal signs anyone out. Before that split, a Wi-Fi blip logged people out mid-load.
+**Only auth ANSWERING is a "no".** Dropping a packet tells you nothing about whether a session is
+good, and neither does a 500 — that is auth failing, not auth answering. So `refresh()` answers
+`{ token, reachedAuth }`, and only a real refusal signs anyone out. Before that split, a Wi-Fi
+blip logged people out mid-load; without the second half, one bad minute at the auth server signs
+out everybody whose token happened to need refreshing.
 
 **A sign-out has a fail-safe timer.** Awaiting `signOut()` before redirecting covers a rejection,
 not a hang — and a hang leaves someone signed out in name only: every request 401ing, nothing
@@ -55,6 +57,24 @@ out. More importantly, it keeps a network failure separate from GoTrue refusing
 so losing Wi-Fi does not become a logout. It lives behind a subpath because it imports
 `@supabase/supabase-js`; the main entry does not.
 
+The test it makes that decision with is exported, because a refresh is not the only place an app
+asks it:
+
+```ts
+import { isAuthOutage } from "@gusnips/react/supabase";
+
+// A callback that just failed to trade its one-use link.
+if (isAuthOutage(error))
+  showRetry(); // the link was never spent — the same one still works
+else showLinkSpent(); // auth said no: only a new link helps
+```
+
+`isAuthOutage` is true when auth FAILED rather than answered — a request that never landed, or a
+5xx. Only a real refusal is an answer, and only an answer may end a session or a link. Use it
+anywhere that decision is made; the sentence you show is a separate question, and a narrower one
+— "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.
+
 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
@@ -63,8 +83,9 @@ Supabase email links have two complete patterns. Keep either one, never half of
   implicit `#access_token` or a PKCE `?code`; it does not consume `token_hash`.
 
 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 reached GoTrue: the first
-needs a new link, while the second can retry the same one.
+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.
 
 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.

package/dist/supabase-session.d.ts

@@ -16,12 +16,40 @@ export interface SupabaseSessionAuth {
         error: unknown;
     }>;
 }
+/**
+ * Auth FAILED rather than answered, so nothing is known about the credential it was handed:
+ * either the request never landed, or GoTrue failed on its own.
+ *
+ * This is the question every site that ends a session has to ask — a token refresh, an API
+ * door, and a callback choosing between "try again" and "that link is spent". Without it one
+ * bad minute at GoTrue signs out everybody whose token happened to need refreshing, and tells
+ * everybody clicking a recovery link that it has expired, which sends them to ask the service
+ * that is down for a replacement.
+ *
+ * Both clauses carry weight, and the second is why this is a function rather than one call.
+ * `isAuthRetryableFetchError` is a NAME check, and the statuses that earn that name are a list
+ * auth-js owns. The list has drifted — 502, 503 and 504 at 2.91; those plus the 52x family and
+ * still no 500 at 2.106; 500 through 530 at 2.108 — so code leaning on it alone is right at
+ * whichever version happens to be installed, which is not the same as being right, and a fleet
+ * installs several versions at once. It is also a LIST rather than a range, so it has holes at
+ * every version, drift or no drift: at 2.112 nothing covers 505 through 519 or 531 up, and a
+ * 507 or a 599 out of a proxy in front of GoTrue arrives as a plain `AuthApiError`. Pinning a
+ * recent SDK does not make the status clause redundant.
+ *
+ * Read the version a tree really serves with `bun why @supabase/auth-js`, which prints one
+ * 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.
+ */
+export declare function isAuthOutage(error: unknown): boolean;
 /**
  * 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.
+ * The distinction this preserves is the one that decides whether anybody is signed out: only
+ * auth ANSWERING proves a session is gone. A fetch that never landed says nothing about it, and
+ * neither does a 5xx, which is auth failing rather than auth answering. A thrown network error
+ * stays on that side of the line too.
  */
 export declare function createSupabaseSessionAdapter(auth: SupabaseSessionAuth): SessionAdapter;
 export {};

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;AAcD;;;;;;GAMG;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;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGpD;AAaD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,cAAc,CAsBtF"}

package/dist/supabase-session.js

@@ -1,6 +1,41 @@
 import { isAuthError, isAuthRetryableFetchError } from "@supabase/supabase-js";
+/**
+ * Auth FAILED rather than answered, so nothing is known about the credential it was handed:
+ * either the request never landed, or GoTrue failed on its own.
+ *
+ * This is the question every site that ends a session has to ask — a token refresh, an API
+ * door, and a callback choosing between "try again" and "that link is spent". Without it one
+ * bad minute at GoTrue signs out everybody whose token happened to need refreshing, and tells
+ * everybody clicking a recovery link that it has expired, which sends them to ask the service
+ * that is down for a replacement.
+ *
+ * Both clauses carry weight, and the second is why this is a function rather than one call.
+ * `isAuthRetryableFetchError` is a NAME check, and the statuses that earn that name are a list
+ * auth-js owns. The list has drifted — 502, 503 and 504 at 2.91; those plus the 52x family and
+ * still no 500 at 2.106; 500 through 530 at 2.108 — so code leaning on it alone is right at
+ * whichever version happens to be installed, which is not the same as being right, and a fleet
+ * installs several versions at once. It is also a LIST rather than a range, so it has holes at
+ * every version, drift or no drift: at 2.112 nothing covers 505 through 519 or 531 up, and a
+ * 507 or a 599 out of a proxy in front of GoTrue arrives as a plain `AuthApiError`. Pinning a
+ * recent SDK does not make the status clause redundant.
+ *
+ * Read the version a tree really serves with `bun why @supabase/auth-js`, which prints one
+ * 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.
+ */
+export function isAuthOutage(error) {
+    if (!isAuthError(error))
+        return true;
+    return isAuthRetryableFetchError(error) || (error.status ?? 0) >= 500;
+}
 function reachedAuth(error) {
-    if (!isAuthError(error) || isAuthRetryableFetchError(error))
+    // Measured across the fleet: four backends answered 401 to their own auth provider's 500,
+    // and every client reads a 401 as a dead session, so one bad minute at auth signed out
+    // everybody who was signed in. `isAuthError` leads only for the narrowing below —
+    // `isAuthOutage` already answers true for anything that is not an auth error.
+    if (!isAuthError(error) || isAuthOutage(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.
@@ -9,9 +44,10 @@ function reachedAuth(error) {
 /**
  * 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.
+ * The distinction this preserves is the one that decides whether anybody is signed out: only
+ * auth ANSWERING proves a session is gone. A fetch that never landed says nothing about it, and
+ * neither does a 5xx, which is auth failing rather than auth answering. A thrown network error
+ * stays on that side of the line too.
  */
 export function createSupabaseSessionAdapter(auth) {
     return {

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,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,yBAAyB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1E,8FAA8F;IAC9F,8FAA8F;IAC9F,OAAO,KAAK,CAAC,IAAI,KAAK,2BAA2B,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "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

@@ -4,7 +4,11 @@ import {
   AuthRetryableFetchError,
 } from "@supabase/supabase-js";
 import { describe, expect, it, vi } from "vitest";
-import { createSupabaseSessionAdapter, type SupabaseSessionAuth } from "./supabase-session.ts";
+import {
+  createSupabaseSessionAdapter,
+  isAuthOutage,
+  type SupabaseSessionAuth,
+} from "./supabase-session.ts";
 
 function auth(overrides: Partial<SupabaseSessionAuth> = {}): SupabaseSessionAuth {
   return {
@@ -67,6 +71,20 @@ describe("createSupabaseSessionAdapter", () => {
     await expect(thrown.refresh()).resolves.toEqual({ token: null, reachedAuth: true });
   });
 
+  it("keeps the session when auth answers with a failure of its own", async () => {
+    // `isAuthRetryableFetchError` says false for this one — it is an API error, not a fetch
+    // failure — so what holds the session is the status clause beside it. A 5xx is auth
+    // failing, never auth answering, and reading it as an answer signs the person out.
+    const outage = new AuthApiError("Internal Server Error", 500, undefined);
+    const adapter = createSupabaseSessionAdapter(
+      auth({
+        refreshSession: async () => ({ data: { session: null }, error: outage }),
+      }),
+    );
+
+    await expect(adapter.refresh()).resolves.toEqual({ token: null, reachedAuth: false });
+  });
+
   it("does not kill a session whose rotated refresh was discarded after a local race", async () => {
     const adapter = createSupabaseSessionAdapter(
       auth({
@@ -89,3 +107,27 @@ describe("createSupabaseSessionAdapter", () => {
     expect(signOut).toHaveBeenCalledOnce();
   });
 });
+
+describe("isAuthOutage", () => {
+  it("lets a real refusal through as an answer", () => {
+    expect(
+      isAuthOutage(new AuthApiError("Invalid login credentials", 400, "invalid_credentials")),
+    ).toBe(false);
+    expect(
+      isAuthOutage(new AuthApiError("Token has expired or is invalid", 403, "otp_expired")),
+    ).toBe(false);
+  });
+
+  it("refuses to read a failure as an answer", () => {
+    // Nothing came back, and the two shapes that carries.
+    expect(isAuthOutage(new AuthRetryableFetchError("Failed to fetch", 0))).toBe(true);
+    expect(isAuthOutage(new TypeError("Load failed"))).toBe(true);
+    // A gateway between us and GoTrue, which auth-js wraps by name.
+    expect(isAuthOutage(new AuthRetryableFetchError("Bad Gateway", 502))).toBe(true);
+    // And the reason the status clause is not redundant: the statuses earning that name are a
+    // LIST, so it has holes at every version. 507 and 599 are on no version of it, and arrive
+    // as ordinary AuthApiErrors that `isAuthRetryableFetchError` answers false for.
+    expect(isAuthOutage(new AuthApiError("Insufficient Storage", 507, undefined))).toBe(true);
+    expect(isAuthOutage(new AuthApiError("Network Connect Timeout", 599, undefined))).toBe(true);
+  });
+});

package/src/supabase-session.ts

@@ -17,8 +17,43 @@ type _SupabaseAuthFitsAdapter = Satisfied<
   SupabaseClient["auth"] extends SupabaseSessionAuth ? true : false
 >;
 
+/**
+ * Auth FAILED rather than answered, so nothing is known about the credential it was handed:
+ * either the request never landed, or GoTrue failed on its own.
+ *
+ * This is the question every site that ends a session has to ask — a token refresh, an API
+ * door, and a callback choosing between "try again" and "that link is spent". Without it one
+ * bad minute at GoTrue signs out everybody whose token happened to need refreshing, and tells
+ * everybody clicking a recovery link that it has expired, which sends them to ask the service
+ * that is down for a replacement.
+ *
+ * Both clauses carry weight, and the second is why this is a function rather than one call.
+ * `isAuthRetryableFetchError` is a NAME check, and the statuses that earn that name are a list
+ * auth-js owns. The list has drifted — 502, 503 and 504 at 2.91; those plus the 52x family and
+ * still no 500 at 2.106; 500 through 530 at 2.108 — so code leaning on it alone is right at
+ * whichever version happens to be installed, which is not the same as being right, and a fleet
+ * installs several versions at once. It is also a LIST rather than a range, so it has holes at
+ * every version, drift or no drift: at 2.112 nothing covers 505 through 519 or 531 up, and a
+ * 507 or a 599 out of a proxy in front of GoTrue arrives as a plain `AuthApiError`. Pinning a
+ * recent SDK does not make the status clause redundant.
+ *
+ * Read the version a tree really serves with `bun why @supabase/auth-js`, which prints one
+ * 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.
+ */
+export function isAuthOutage(error: unknown): boolean {
+  if (!isAuthError(error)) return true;
+  return isAuthRetryableFetchError(error) || (error.status ?? 0) >= 500;
+}
+
 function reachedAuth(error: unknown): boolean {
-  if (!isAuthError(error) || isAuthRetryableFetchError(error)) return false;
+  // Measured across the fleet: four backends answered 401 to their own auth provider's 500,
+  // and every client reads a 401 as a dead session, so one bad minute at auth signed out
+  // everybody who was signed in. `isAuthError` leads only for the narrowing below —
+  // `isAuthOutage` already answers true for anything that is not an auth error.
+  if (!isAuthError(error) || isAuthOutage(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";
@@ -27,9 +62,10 @@ function reachedAuth(error: unknown): boolean {
 /**
  * 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.
+ * The distinction this preserves is the one that decides whether anybody is signed out: only
+ * auth ANSWERING proves a session is gone. A fetch that never landed says nothing about it, and
+ * neither does a 5xx, which is auth failing rather than auth answering. A thrown network error
+ * stays on that side of the line too.
  */
 export function createSupabaseSessionAdapter(auth: SupabaseSessionAuth): SessionAdapter {
   return {