@ai-matrx/records 0.46.0 → 0.47.0

package/dist/react/index.d.cts

@@ -3424,6 +3424,18 @@ type RecordsErrorCode =
  * through the ORDINARY write door — which is most of them.
  */
  | "needs_approval"
+/**
+ * THE CALL NEVER REACHED THE STORE. Not a refusal — a transport failure: the
+ * browser lost the network, the gateway answered with an HTTP status and no
+ * body, the request was cancelled. supabase-js hands these back with an EMPTY
+ * `code` (a `FetchError`) or with the HTTP status in it (`"404"`, `"502"`),
+ * neither of which is a SQLSTATE, and until 2026-09-22 they all landed in
+ * `internal` — which is the one classification that tells a screen nothing,
+ * and which made the package print a sentence about ITSELF to the person
+ * (lane TAILS-6). Nothing was written, and the same call can simply be made
+ * again, which is what separates it from `internal`.
+ */
+ | "unreachable"
 /** Anything the mapper could not place. It still carries the store's own words. */
  | "internal";
 /** A refusal, in the store's own words. */
@@ -3437,6 +3449,26 @@ interface RecordsError {
     sqlstate?: string;
     /** Whatever the store put in DETAIL, parsed when it was json. */
     detail?: unknown;
+    /**
+     * TRUE when this package did not recognise the class it was handed, so a
+     * caller can say so instead of reading the silence as "handled".
+     *
+     * 🚨 IT IS A FLAG AND A SEPARATE SENTENCE, NEVER AN APPENDIX TO `hint`
+     * (lane TAILS-6, 2026-09-22). `mapPgError` used to append "@ai-matrx/records
+     * did not recognise SQLSTATE … from checklistTemplates" ONTO `hint`, and
+     * `hint` is the field every screen treats as THE REMEDY — the sentence a
+     * person is told to act on. So a dropped connection on the Checklists tab
+     * showed a plumbing company "Something went wrong at our end" over a line
+     * about a TypeScript package and a SQLSTATE. A note this package writes about
+     * ITSELF is for whoever debugs it and belongs nowhere a person reads.
+     */
+    unmapped?: boolean;
+    /**
+     * THIS PACKAGE'S OWN NOTE, for an engineer. Never the store's words and never
+     * a person's: screens render it out of sight (a `title` attribute, a
+     * screen-reader line) or not at all.
+     */
+    diagnostic?: string;
 }
 type RecordsResult<T> = {
     ok: true;

package/dist/react/index.d.ts

@@ -3424,6 +3424,18 @@ type RecordsErrorCode =
  * through the ORDINARY write door — which is most of them.
  */
  | "needs_approval"
+/**
+ * THE CALL NEVER REACHED THE STORE. Not a refusal — a transport failure: the
+ * browser lost the network, the gateway answered with an HTTP status and no
+ * body, the request was cancelled. supabase-js hands these back with an EMPTY
+ * `code` (a `FetchError`) or with the HTTP status in it (`"404"`, `"502"`),
+ * neither of which is a SQLSTATE, and until 2026-09-22 they all landed in
+ * `internal` — which is the one classification that tells a screen nothing,
+ * and which made the package print a sentence about ITSELF to the person
+ * (lane TAILS-6). Nothing was written, and the same call can simply be made
+ * again, which is what separates it from `internal`.
+ */
+ | "unreachable"
 /** Anything the mapper could not place. It still carries the store's own words. */
  | "internal";
 /** A refusal, in the store's own words. */
@@ -3437,6 +3449,26 @@ interface RecordsError {
     sqlstate?: string;
     /** Whatever the store put in DETAIL, parsed when it was json. */
     detail?: unknown;
+    /**
+     * TRUE when this package did not recognise the class it was handed, so a
+     * caller can say so instead of reading the silence as "handled".
+     *
+     * 🚨 IT IS A FLAG AND A SEPARATE SENTENCE, NEVER AN APPENDIX TO `hint`
+     * (lane TAILS-6, 2026-09-22). `mapPgError` used to append "@ai-matrx/records
+     * did not recognise SQLSTATE … from checklistTemplates" ONTO `hint`, and
+     * `hint` is the field every screen treats as THE REMEDY — the sentence a
+     * person is told to act on. So a dropped connection on the Checklists tab
+     * showed a plumbing company "Something went wrong at our end" over a line
+     * about a TypeScript package and a SQLSTATE. A note this package writes about
+     * ITSELF is for whoever debugs it and belongs nowhere a person reads.
+     */
+    unmapped?: boolean;
+    /**
+     * THIS PACKAGE'S OWN NOTE, for an engineer. Never the store's words and never
+     * a person's: screens render it out of sight (a `title` attribute, a
+     * screen-reader line) or not at all.
+     */
+    diagnostic?: string;
 }
 type RecordsResult<T> = {
     ok: true;

package/dist/react/index.js

@@ -2329,19 +2329,34 @@ function parseDetail(details) {
     return details;
   }
 }
+function isNotASqlstate(code) {
+  if (!code) return true;
+  return /^[0-9]{3}$/.test(code);
+}
 function mapPgError(error, where) {
-  const sqlstate = error.code ?? void 0;
-  const code = (sqlstate ? BY_SQLSTATE[sqlstate] : void 0) ?? "internal";
+  const raw = error.code ?? void 0;
+  const sqlstate = raw && raw !== "" ? raw : void 0;
   const mapped = {
-    code,
+    code: "internal",
     message: error.message,
     ...error.hint ? { hint: error.hint } : {},
     ...sqlstate ? { sqlstate } : {}
   };
+  if (isNotASqlstate(sqlstate)) {
+    mapped.code = "unreachable";
+  } else {
+    mapped.code = BY_SQLSTATE[sqlstate] ?? "internal";
+  }
   const detail = parseDetail(error.details);
   if (detail !== void 0) mapped.detail = detail;
-  if (code === "internal") {
-    mapped.hint = (mapped.hint ? `${mapped.hint} ` : "") + `(@ai-matrx/records did not recognise SQLSTATE ${sqlstate ?? "(none)"} from ${where}; the message above is the store's own and is the thing to act on.)`;
+  if (mapped.code === "internal") {
+    mapped.unmapped = true;
+    mapped.diagnostic = `@ai-matrx/records did not recognise SQLSTATE ${sqlstate ?? "(none)"} from ${where}; the store's own message is the thing to act on.`;
+  } else if (mapped.code === "unreachable") {
+    mapped.unmapped = true;
+    mapped.diagnostic = `@ai-matrx/records never reached the store from ${where}: ${raw ? `the transport answered ${raw}` : "no response"} \u2014 ${error.message}`;
+    mapped.message = "We could not reach your data.";
+    delete mapped.hint;
   }
   return mapped;
 }