@gusnips/react 0.9.3 → 0.9.5

package/README.md

@@ -57,6 +57,28 @@ 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.
+
+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

package/dist/supabase-session.d.ts

@@ -16,6 +16,34 @@ 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. 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;
 /**
  * Connects a Supabase auth client to {@link SessionAdapter}.
  *

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;AAsBD;;;;;;;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"}

package/dist/supabase-session.js

@@ -1,15 +1,49 @@
 import { isAuthError, isAuthRetryableFetchError } from "@supabase/supabase-js";
-function reachedAuth(error) {
-    if (!isAuthError(error) || isAuthRetryableFetchError(error))
+/**
+ * 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. 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;
-    // A 5xx is auth failing, not auth answering — and the vendor's predicate above cannot be
-    // relied on to say so, because it reads a list it owns and has already changed: at auth-js
-    // 2.91 it covered 502, 503 and 504, and at 2.108 it covers 500 through 530. Code leaning on
-    // it alone is right at whichever version happens to be installed, which is not the same as
-    // being right. Without this clause one bad minute at GoTrue signs out everybody whose token
-    // happened to need refreshing. Measured across the fleet: four backends answered 401 to
-    // their own auth provider's 500 for exactly this reason.
-    if ((error.status ?? 0) >= 500)
+    if (!isAuthError(error))
+        return true;
+    return isAuthRetryableFetchError(error) || (error.status ?? 0) >= 500;
+}
+function reachedAuth(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.

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,yFAAyF;IACzF,2FAA2F;IAC3F,4FAA4F;IAC5F,2FAA2F;IAC3F,4FAA4F;IAC5F,wFAAwF;IACxF,yDAAyD;IACzD,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,GAAG;QAAE,OAAO,KAAK,CAAC;IAC7C,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":"AAAA,OAAO,EAAE,WAAW,EAAE,yBAAyB,EAAuB,MAAM,uBAAuB,CAAC;AAmBpG;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,4FAA4F;IAC5F,6EAA6E;IAC7E,8FAA8F;IAC9F,8FAA8F;IAC9F,gFAAgF;IAChF,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,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.3",
+  "version": "0.9.5",
   "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,9 +2,14 @@ import {
   AuthApiError,
   AuthRefreshDiscardedError,
   AuthRetryableFetchError,
+  AuthUnknownError,
 } 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 {
@@ -103,3 +108,49 @@ 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);
+  });
+
+  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);
+  });
+});

package/src/supabase-session.ts

@@ -17,16 +17,50 @@ 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. 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;
+}
+
 function reachedAuth(error: unknown): boolean {
-  if (!isAuthError(error) || isAuthRetryableFetchError(error)) return false;
-  // A 5xx is auth failing, not auth answering — and the vendor's predicate above cannot be
-  // relied on to say so, because it reads a list it owns and has already changed: at auth-js
-  // 2.91 it covered 502, 503 and 504, and at 2.108 it covers 500 through 530. Code leaning on
-  // it alone is right at whichever version happens to be installed, which is not the same as
-  // being right. Without this clause one bad minute at GoTrue signs out everybody whose token
-  // happened to need refreshing. Measured across the fleet: four backends answered 401 to
-  // their own auth provider's 500 for exactly this reason.
-  if ((error.status ?? 0) >= 500) 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";