@ai-matrx/records 0.46.0 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog — @ai-matrx/records
 
+## 0.48.0
+
+**A portal principal carries the link the office copies for them.** (lane TAILS-5.)
+
+* **`PortalPrincipal.accept_path`** — `/invitations/portal/accept/<token>`, the same path
+  `custom.portal_invite` hands back when somebody is asked, read off the same `iam.invitations`
+  row and never re-templated. `custom.portal_card` carries it per person as of the migration
+  `tails5b_the_portal_card_carries_the_link.sql`.
+* **`null` is an answer, not an absence.** It is null when they have already followed the link,
+  when the office took it back (a revoke withdraws the invitation in the same statement), when
+  it expired, or when they arrived through the server's own magic-link route, which binds
+  without an invitation at all. A screen that meets `null` says so in words — it never draws a
+  dead control.
+* **Why it exists**: PORTAL-BIND left this named — *"the office's own copy-link is one line
+  short"*. The door answered the office once, with one sentence and one link, and the moment
+  that sentence scrolled away the link was gone: the panel redraws from `portal_card`, which
+  knew somebody was "invited and waiting" and had no way to say what they were waiting on. So
+  texting a customer their link — which INVITE-DELIVERY measured as the ORDINARY case, not the
+  fallback — meant inviting them a second time to see it again.
+
+**Consumer action:** none. `accept_path` is a new field on an existing answer; nothing that
+reads `PortalPrincipal` today has to change. A surface that offers a copy-link must handle the
+`null` case with a sentence.
+
+## 0.47.0
+
+**A refusal this package does not recognise no longer becomes a sentence about this package.**
+(lane TAILS-6.)
+
+* **`mapPgError` wrote its own note ONTO `hint` — and `hint` is what every screen treats as
+  THE REMEDY.** So when the client met a code it did not know, the person acting on the screen
+  was handed this to act on:
+
+  > `@ai-matrx/records did not recognise SQLSTATE  from checklistTemplates`
+
+  Watched on the live seat by the GUIDE lane on 2026-09-21, on the Checklists tab of a table's
+  rail, under the title "Something went wrong at our end". Reproduced here from the shapes
+  supabase-js actually returns.
+* **The note moves to `RecordsError.diagnostic`, with `unmapped: true` beside it.** It is still
+  said out loud — nobody reads the silence as "handled" — but it is said to whoever debugs
+  this and to nobody else. `hint` is the STORE's own words or it is absent.
+* **New code `unreachable`, and it is how the bug got out.** A SQLSTATE is five characters;
+  supabase-js puts `""` in `code` for a `FetchError` and the HTTP status (`"404"`, `"502"`) when
+  the gateway answers with no body. Neither is a SQLSTATE, both used to land in `internal`, and
+  `""` is not nullish so it was carried as one. They now classify as `unreachable` — the call
+  never reached the store, nothing was written, and the same call can simply be made again,
+  which is a thing a screen can honestly offer. `TypeError: Failed to fetch` is the browser
+  talking to itself, so the message becomes "We could not reach your data." and the raw text
+  goes to `diagnostic`.
+
+**Consumer action:** none required. A host that reads `error.hint` gets the store's hint or
+nothing, never this package's commentary; a host that switches on `error.code` should add
+`unreachable` beside `internal` (`@ai-matrx/records-ui` 0.66.0 already has its title and remedy).
+
 ## 0.46.0
 
 **A portal can say which Tables it shows.**

package/dist/core/index.cjs

@@ -3070,19 +3070,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;
 }