@ai-matrx/data 0.18.34 → 0.18.36

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.18.36
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/data/v0.18.35..npm/data/v0.18.36 -- apps/shared/data`).
+No source changes intended and no consumer action required.
+
+## 0.18.35
+### Unreleased
+
+- `/db` gains `writeOne`, `tryWriteOne`, `writeOneRow`, `writeFailureStatus`, `WriteDidNotLandError`,
+  `BulkWriteError` and the write-failure words (`WriteRefusedError`, `describeWriteFailure`,
+  `assertWriteLanded`, `personSentence`, `serverMessageFromBody`) — moved verbatim from
+  matrx-frontend so `@ai-matrx/chat` stops reaching into the app for them.
+- `@supabase/supabase-js` is now a peer dependency (external, never bundled) so `PostgrestError`
+  is the consumer's own class and `instanceof` checks hold.
+- `/db` gains `RecordUnavailableError`, `recordUnavailableMessage`, `isRecordUnavailableError`
+  (the zero-row single-record read shape), moved from matrx-frontend `lib/records/recordUnavailable.ts`.
+- **Consumer action:** none required; matrx-frontend's old modules re-export these.
+
 ## 0.18.34
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/db.cjs

@@ -20,28 +20,42 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/db.ts
 var db_exports = {};
 __export(db_exports, {
+  BulkWriteError: () => BulkWriteError,
   DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE: () => DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE,
   DEFAULT_ACTIVE_ORG_COOKIE_NAME: () => DEFAULT_ACTIVE_ORG_COOKIE_NAME,
   DEFAULT_AUTH_COOKIE_NAME: () => DEFAULT_AUTH_COOKIE_NAME,
   IncompleteReadError: () => IncompleteReadError,
+  RecordUnavailableError: () => RecordUnavailableError,
   SessionUnavailableError: () => SessionUnavailableError,
+  WriteDidNotLandError: () => WriteDidNotLandError,
+  WriteRefusedError: () => WriteRefusedError,
   asJsonObject: () => asJsonObject,
+  assertWriteLanded: () => assertWriteLanded,
   createActiveOrgCookie: () => createActiveOrgCookie,
   createAuthCookie: () => createAuthCookie,
   createOAuthRefreshFetch: () => createOAuthRefreshFetch,
   createSessionRetry: () => createSessionRetry,
   decodeActiveOrgSelection: () => decodeActiveOrgSelection,
   decodeOAuthRefreshClaims: () => decodeOAuthRefreshClaims,
+  describeWriteFailure: () => describeWriteFailure,
   encodeActiveOrgSelection: () => encodeActiveOrgSelection,
   guardedUpdate: () => guardedUpdate,
   isMissingSessionError: () => isMissingSessionError,
+  isRecordUnavailableError: () => isRecordUnavailableError,
   mergeJsonColumn: () => mergeJsonColumn,
   parseCookieHeader: () => parseCookieHeader,
+  personSentence: () => personSentence,
   readAllRows: () => readAllRows,
   readAllRowsRest: () => readAllRowsRest,
+  recordUnavailableMessage: () => recordUnavailableMessage,
+  serverMessageFromBody: () => serverMessageFromBody,
   tryReadAllRows: () => tryReadAllRows,
   tryReadAllRowsRest: () => tryReadAllRowsRest,
-  uniqueChannelTopic: () => import_realtime.uniqueChannelTopic
+  tryWriteOne: () => tryWriteOne,
+  uniqueChannelTopic: () => import_realtime.uniqueChannelTopic,
+  writeFailureStatus: () => writeFailureStatus,
+  writeOne: () => writeOne,
+  writeOneRow: () => writeOneRow
 });
 module.exports = __toCommonJS(db_exports);
 
@@ -675,4 +689,267 @@ function createOAuthRefreshFetch(args) {
     return normalizeOAuthResponse(adopted, responseSession, clientId);
   };
 }
+
+// src/db/write-failure.ts
+var WriteRefusedError = class extends Error {
+  status;
+  /** What the server said for a person, when it said something a person can read. */
+  serverMessage;
+  /** The developer line (method, path, status, body) — for diagnostics, never for the screen. */
+  technical;
+  constructor(args) {
+    super(refusalSentence(args.status, args.serverMessage ?? null));
+    this.name = "WriteRefusedError";
+    this.status = args.status;
+    this.serverMessage = args.serverMessage ?? null;
+    this.technical = args.technical;
+  }
+};
+function serverMessageFromBody(body) {
+  if (!body || typeof body !== "object") return null;
+  const b = body;
+  const detail = b.detail;
+  const pick = (v) => typeof v === "string" && v.trim() !== "" ? v.trim() : null;
+  if (detail && typeof detail === "object" && !Array.isArray(detail)) {
+    const d = detail;
+    return pick(d.user_message) ?? pick(d.message);
+  }
+  return pick(b.user_message) ?? pick(detail) ?? pick(b.message);
+}
+var LOOKS_TECHNICAL = /(^|\s)(GET|POST|PUT|PATCH|DELETE)\s+\/|https?:\/\/|\bHTTP \d{3}\b|Traceback|Exception\b|permission denied for|violates|row-level security|\brelation "|\bcolumn "|\bfunction .* does not exist|\bPGRST\d+|\bJWT\b|duplicate key|syntax error|invalid input syntax|JSON object requested|rows returned|\bnull value in column|\bundefined\b|\bat [\w.]+ \(/i;
+function personSentence(text2) {
+  if (typeof text2 !== "string") return null;
+  let said = text2.trim();
+  const named = /^[a-z][a-z0-9_]*[a-z0-9]: (.+)$/s.exec(said);
+  if (named) said = (named[1] ?? "").trim().replace(/^[a-z]/, (c) => c.toUpperCase());
+  if (said.length < 8 || LOOKS_TECHNICAL.test(said) || !/^[A-Z"“']/.test(said) || !/\s/.test(said)) return null;
+  return /[.!?]["”']?$/.test(said) ? said : `${said}.`;
+}
+function isPostgrestShaped(err) {
+  if (!err || typeof err !== "object") return false;
+  const code = err.code;
+  return typeof code === "string" && /^(PGRST\d{3}|[0-9A-Z]{5})$/.test(code) && !("status" in err && typeof err.status === "number");
+}
+function isSerializedRefusal(err) {
+  if (!err || typeof err !== "object" || err instanceof Error) return false;
+  const e = err;
+  if (typeof e.message !== "string" || e.message.trim() === "") return false;
+  if (e.name === "WriteRefusedError" || e.name === "WriteDidNotLandError") return true;
+  return e.name === "Error" && !LOOKS_TECHNICAL.test(e.message);
+}
+function postgrestSentence(code) {
+  if (code === "42501" || code === "PGRST301" || code === "PGRST302") return "You do not have permission to do this.";
+  if (code === "PGRST303" || code === "PGRST300") return "Your sign-in has expired. Sign in again, then try again.";
+  if (code === "PGRST116") return "It is no longer there \u2014 it may have been deleted.";
+  if (code === "23505") return "Something with the same name or key already exists.";
+  if (code === "23503") return "It refers to something that no longer exists.";
+  if (code === "23514" || code === "23502" || code === "22P02") return "The database would not accept that value.";
+  if (code === "57014") return "The database took too long to answer.";
+  if (code === "40001" || code === "40P01") return "It changed while you were working. Reload to see the latest.";
+  return "The database refused it.";
+}
+function assertWriteLanded(rows, technical) {
+  const n = Array.isArray(rows) ? rows.length : rows == null ? 0 : 1;
+  if (n > 0) return;
+  throw new WriteRefusedError({
+    status: 403,
+    serverMessage: "Nothing was saved: you may not have permission to change this, or it no longer exists.",
+    technical: `${technical} matched 0 rows`
+  });
+}
+function refusalSentence(status, serverMessage) {
+  const said = serverMessage && !LOOKS_TECHNICAL.test(serverMessage) ? serverMessage : null;
+  if (status === 401) return "Your sign-in has expired. Sign in again, then try again.";
+  if (status === 403) return said ?? "You do not have permission to do this.";
+  if (status === 404) return said ?? "It is no longer there \u2014 it may have been deleted.";
+  if (status === 409 || status === 412) return said ?? "It changed while you were working. Reload to see the latest.";
+  if (status >= 500) return "The server refused the request.";
+  if (said) return `The server said: ${said.replace(/\.?$/, ".")}`;
+  return "The server did not accept it.";
+}
+function describeWriteFailure(err, { action, remedy = "Try again." }) {
+  const title = `Could not ${action}.`;
+  let why;
+  if (err instanceof WriteRefusedError) {
+    why = err.message;
+  } else if (isSerializedRefusal(err)) {
+    why = /[.!?]["”']?$/.test(err.message.trim()) ? err.message.trim() : `${err.message.trim()}.`;
+  } else if (isPostgrestShaped(err)) {
+    why = personSentence(err.message) ?? postgrestSentence(err.code);
+  } else if (err && typeof err === "object" && "status" in err && typeof err.status === "number") {
+    const e = err;
+    why = refusalSentence(e.status, typeof e.userMessage === "string" ? e.userMessage : null);
+  } else if (err instanceof TypeError || err instanceof Error && /Failed to fetch|NetworkError|Load failed/i.test(err.message)) {
+    why = "The server could not be reached. Check your connection.";
+  } else if (err instanceof Error && err.message && !LOOKS_TECHNICAL.test(err.message)) {
+    why = err.message.replace(/\.?$/, ".");
+  } else if (typeof err === "string" && err.trim() && !LOOKS_TECHNICAL.test(err)) {
+    why = err.trim().replace(/\.?$/, ".");
+  } else {
+    why = "Something went wrong on our side.";
+  }
+  return { title, description: `${why} ${remedy}`.trim() };
+}
+
+// src/db/write-one.ts
+var import_supabase_js = require("@supabase/supabase-js");
+var PAST = {
+  save: "saved",
+  update: "updated",
+  rename: "renamed",
+  move: "moved",
+  delete: "deleted",
+  remove: "removed",
+  archive: "archived",
+  restore: "restored",
+  publish: "published",
+  unpublish: "unpublished",
+  change: "changed"
+};
+var GERUND = {
+  save: "saving",
+  update: "updating",
+  rename: "renaming",
+  move: "moving",
+  delete: "deleting",
+  remove: "removing",
+  archive: "archiving",
+  restore: "restoring",
+  publish: "publishing",
+  unpublish: "unpublishing",
+  change: "changing"
+};
+var WriteDidNotLandError = class extends WriteRefusedError {
+  action;
+  noun;
+  reason;
+  constructor({ action, noun }, reason = "refused") {
+    super({
+      status: reason === "taken" ? 409 : 403,
+      serverMessage: reason === "taken" ? `This ${noun} was already handled \u2014 refresh to see the latest.` : `Nothing was ${PAST[action]}: this ${noun} no longer exists, or your access does not allow ${GERUND[action]} it.`,
+      technical: reason === "taken" ? `writeOne(${action} ${noun}) compare-and-set matched 0 rows \u2014 another writer got there first` : `writeOne(${action} ${noun}) matched 0 rows \u2014 RLS refused or the row is gone`
+    });
+    this.name = "WriteDidNotLandError";
+    this.action = action;
+    this.noun = noun;
+    this.reason = reason;
+  }
+};
+async function writeOne(write, options) {
+  const { data, error } = await write;
+  if (error) throw error;
+  if (Array.isArray(data) && data.length > 0) return data[0];
+  if (options.alreadyDone) {
+    const current = await options.alreadyDone.reread();
+    if (current.error) throw current.error;
+    const row = Array.isArray(current.data) ? current.data[0] : current.data;
+    if (row && options.alreadyDone.isDone(row)) return row;
+  }
+  throw new WriteDidNotLandError(options, options.compareAndSet ? "taken" : "refused");
+}
+async function tryWriteOne(write, options) {
+  try {
+    return { row: await writeOne(write, options), error: null };
+  } catch (caught) {
+    if (caught instanceof Error) return { row: null, error: caught };
+    if (caught && typeof caught === "object" && "code" in caught && typeof caught.code === "string" && "message" in caught && typeof caught.message === "string") {
+      return { row: null, error: new import_supabase_js.PostgrestError({
+        code: caught.code,
+        message: caught.message,
+        details: "details" in caught && typeof caught.details === "string" ? caught.details : "",
+        hint: "hint" in caught && typeof caught.hint === "string" ? caught.hint : ""
+      }) };
+    }
+    const message = caught && typeof caught === "object" && "message" in caught && typeof caught.message === "string" ? caught.message : String(caught);
+    const error = new Error(message);
+    error.cause = caught;
+    return { row: null, error };
+  }
+}
+function writeFailureStatus(error) {
+  if (error instanceof WriteDidNotLandError) return error.status;
+  if (error && typeof error === "object" && "code" in error) {
+    if (error.code === "42501") return 403;
+    if (error.code === "PGRST301" || error.code === "PGRST302" || error.code === "PGRST303") return 401;
+    if (error.code === "PGRST116") return 404;
+    if (error.code === "23505" || error.code === "40001" || error.code === "40P01") return 409;
+  }
+  return 500;
+}
+var BulkWriteError = class extends Error {
+  failures;
+  attempted;
+  constructor(failures, attempted) {
+    super(
+      `${failures.length} of ${attempted} ${attempted === 1 ? "change was" : "changes were"} not saved. ${failures[0]?.message ?? ""}`.trim()
+    );
+    this.name = "BulkWriteError";
+    this.failures = failures;
+    this.attempted = attempted;
+  }
+};
+async function writeOneRow(write, options) {
+  const { data, error } = await write;
+  if (error) {
+    if (error instanceof import_supabase_js.PostgrestError) return { data: null, error };
+    const e = error;
+    return {
+      data: null,
+      error: new import_supabase_js.PostgrestError({
+        message: typeof e.message === "string" ? e.message : String(error),
+        details: typeof e.details === "string" ? e.details : "",
+        hint: typeof e.hint === "string" ? e.hint : "",
+        code: typeof e.code === "string" ? e.code : ""
+      })
+    };
+  }
+  const rows = Array.isArray(data) ? data : [];
+  if (rows.length === 1) return { data: rows[0], error: null };
+  const refusal = new WriteDidNotLandError(options, options.compareAndSet ? "taken" : "refused");
+  return {
+    data: null,
+    error: new import_supabase_js.PostgrestError({
+      message: rows.length === 0 ? refusal.serverMessage ?? refusal.message : `${rows.length} records matched where one ${options.noun} was expected, and all of them were changed. Reload to see the result.`,
+      details: rows.length === 0 ? refusal.technical : `writeOneRow(${options.action} ${options.noun}) matched ${rows.length} rows`,
+      hint: "",
+      code: "PGRST116"
+    })
+  };
+}
+
+// src/db/record-unavailable.ts
+var RecordUnavailableError = class extends Error {
+  entity;
+  reason;
+  recordId;
+  /**
+   * Canonical entity token, when the read site knows it. With a token AND a
+   * recordId the renderer stops describing the ambiguity and ASKS the platform
+   * instead — an access gate resolves which of the four it really is.
+   * Without one, honest ambiguity is still the best available answer.
+   */
+  token;
+  /** Diagnostics identity for reconciling this exact capture in place. */
+  captureId;
+  /** Last truth written to diagnostics; avoids duplicate reconciliation. */
+  captureResolution;
+  constructor(input) {
+    super(recordUnavailableMessage(input.entity, input.reason));
+    this.name = "RecordUnavailableError";
+    this.entity = input.entity;
+    this.reason = input.reason;
+    this.recordId = input.recordId;
+    this.token = input.token;
+    this.captureResolution = input.reason;
+  }
+};
+function recordUnavailableMessage(entity, reason) {
+  if (reason === "deleted") {
+    return `This ${entity} was deleted, so it can no longer be opened.`;
+  }
+  return `We couldn't open this ${entity}. It may have been deleted, or it may belong to an organization you don't have access to.`;
+}
+function isRecordUnavailableError(value) {
+  return value instanceof RecordUnavailableError;
+}
 //# sourceMappingURL=db.cjs.map