@objectstack/types 17.2.0 → 17.4.0

package/dist/index.js

@@ -20,30 +20,40 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DRIVER_TARGETED_TABLE: () => DRIVER_TARGETED_TABLE,
   GLOBAL_UNIQUE_CONFIRMATION_REQUIRED: () => GLOBAL_UNIQUE_CONFIRMATION_REQUIRED,
   GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION: () => GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION,
   INTERNAL_ERROR_MESSAGE: () => INTERNAL_ERROR_MESSAGE,
+  PLATFORM_OWNER_EMAIL_ENV: () => PLATFORM_OWNER_EMAIL_ENV,
+  SERVER_FAULT_LOG_PREFIX: () => SERVER_FAULT_LOG_PREFIX,
   VALIDATION_FAILED_STATUS: () => VALIDATION_FAILED_STATUS,
   _resetEnvDeprecationWarnings: () => _resetEnvDeprecationWarnings,
   buildGlobalUniqueStopMessage: () => buildGlobalUniqueStopMessage,
   collectConfiguredLocales: () => collectConfiguredLocales,
   collectGlobalUniques: () => collectGlobalUniques,
+  declareTargetedTable: () => declareTargetedTable,
   declaredIndexUniqueIsGlobal: () => declaredIndexUniqueIsGlobal,
   declaredUserMessage: () => declaredUserMessage,
   declaresServerFault: () => declaresServerFault,
   demotedDeclaredCode: () => demotedDeclaredCode,
+  describeFaultRequest: () => describeFaultRequest,
   describeGlobalUniqueFinding: () => describeGlobalUniqueFinding,
   emitDegradedBootBanner: () => emitDegradedBootBanner,
   fieldUniqueIsGlobal: () => fieldUniqueIsGlobal,
   fieldsFromZodIssues: () => fieldsFromZodIssues,
   globalUniqueFindingId: () => globalUniqueFindingId,
+  isEmailVerifiedUserRow: () => isEmailVerifiedUserRow,
   isMcpServerEnabled: () => isMcpServerEnabled,
+  isMissingTableError: () => isMissingTableError,
   isModuleNotFoundError: () => isModuleNotFoundError,
   isPlatformOwnedObject: () => isPlatformOwnedObject,
   isRelationSubObjectPhrase: () => isRelationSubObjectPhrase,
+  isSchemaAlreadyExistsError: () => isSchemaAlreadyExistsError,
+  isServerFault: () => isServerFault,
   isUnbackedConflictTargetError: () => isUnbackedConflictTargetError,
   isUniqueViolationError: () => isUniqueViolationError,
   keysetWalk: () => keysetWalk,
+  logServerFault: () => logServerFault,
   looksLikeInternalErrorLeak: () => looksLikeInternalErrorLeak,
   matchMissingColumnOfRelation: () => matchMissingColumnOfRelation,
   postureGatesGlobalUniques: () => postureGatesGlobalUniques,
@@ -55,13 +65,21 @@ __export(index_exports, {
   resolveMcpStdioAutoStart: () => resolveMcpStdioAutoStart,
   resolveMultiOrgEnabled: () => resolveMultiOrgEnabled,
   resolveOrgLimit: () => resolveOrgLimit,
+  resolveOrgMembershipLimit: () => resolveOrgMembershipLimit,
+  resolvePlatformOwnerEmail: () => resolvePlatformOwnerEmail,
   resolveSandboxTimeoutMs: () => resolveSandboxTimeoutMs,
   resolveSearchPinyinEnabled: () => resolveSearchPinyinEnabled,
   resolveTenancyPosture: () => resolveTenancyPosture,
   resolveThrownHttpError: () => resolveThrownHttpError,
   sendError: () => sendError,
   sendOk: () => sendOk,
+  serverFaultLogMessage: () => serverFaultLogMessage,
+  serverFaultLogMeta: () => serverFaultLogMeta,
+  serverFaultProvenance: () => serverFaultProvenance,
   stampSearchPinyinEnabled: () => stampSearchPinyinEnabled,
+  strandedDecisionDetails: () => strandedDecisionDetails,
+  strandedDecisionFailure: () => strandedDecisionFailure,
+  targetedTableOf: () => targetedTableOf,
   unconfirmedGlobalUniques: () => unconfirmedGlobalUniques,
   uniqueViolationColumn: () => uniqueViolationColumn,
   validationFailure: () => validationFailure,
@@ -86,6 +104,12 @@ function emitDegradedBootBanner(message) {
   }
 }
 
+// src/email-verified.ts
+function isEmailVerifiedUserRow(row) {
+  const v = row?.email_verified;
+  return v === true || v === 1 || v === "1" || v === "true";
+}
+
 // src/env.ts
 var import_security = require("@objectstack/spec/security");
 var _warnedKeys = /* @__PURE__ */ new Set();
@@ -131,6 +155,13 @@ function resolveTenancyPosture() {
   }
   return resolveMultiOrgEnabled() ? "isolated" : "single";
 }
+var PLATFORM_OWNER_EMAIL_ENV = "OS_PLATFORM_OWNER_EMAIL";
+function resolvePlatformOwnerEmail() {
+  const raw = globalThis.process?.env?.[PLATFORM_OWNER_EMAIL_ENV];
+  if (raw == null) return void 0;
+  const trimmed = String(raw).trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
 function resolveAllowDegradedTenancy() {
   const raw = readEnvWithDeprecation("OS_ALLOW_DEGRADED_TENANCY", [], { silent: true });
   if (raw == null) return false;
@@ -170,6 +201,12 @@ function resolveOrgLimit() {
   const n = Number.parseInt(String(raw), 10);
   return Number.isFinite(n) && n > 0 ? n : void 0;
 }
+function resolveOrgMembershipLimit() {
+  const raw = readEnvWithDeprecation("OS_ORG_MEMBERSHIP_LIMIT", [], { silent: true });
+  if (raw == null || String(raw).trim() === "") return void 0;
+  const n = Number.parseInt(String(raw), 10);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
 function resolveSearchPinyinEnabled(opts) {
   const raw = readEnvWithDeprecation("OS_SEARCH_PINYIN_ENABLED", [], { silent: true });
   if (raw != null && String(raw).trim() !== "") {
@@ -321,11 +358,78 @@ function isModuleNotFoundError(err) {
   return msg.includes("Cannot find module") || msg.includes("Cannot find package");
 }
 
+// src/server-fault-log.ts
+var SERVER_FAULT_LOG_PREFIX = "[5xx]";
+function isServerFault(status) {
+  return typeof status === "number" && status >= 500;
+}
+function toError(thrown) {
+  if (thrown === void 0 || thrown === null) return void 0;
+  if (thrown instanceof Error) return thrown;
+  const wrapped = new Error(typeof thrown === "string" ? thrown : safeStringify(thrown));
+  wrapped.stack = void 0;
+  return wrapped;
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function serverFaultLogMessage(input) {
+  const err = toError(input.error);
+  const text = err?.message || input.message || "Unhandled server fault";
+  const where = [input.request?.method, input.request?.path].filter(Boolean).join(" ");
+  return `${SERVER_FAULT_LOG_PREFIX} ${input.status}${where ? ` ${where}` : ""} \u2014 ${text}`;
+}
+function serverFaultLogMeta(input) {
+  return {
+    status: input.status,
+    ...input.code !== void 0 ? { code: input.code } : {},
+    ...input.request?.method !== void 0 ? { method: input.request.method } : {},
+    ...input.request?.path !== void 0 ? { path: input.request.path } : {},
+    ...input.request?.requestId !== void 0 ? { requestId: input.request.requestId } : {}
+  };
+}
+function logServerFault(input, logger) {
+  if (!isServerFault(input.status)) return false;
+  const message = serverFaultLogMessage(input);
+  const meta = serverFaultLogMeta(input);
+  const err = toError(input.error);
+  try {
+    if (logger) {
+      logger.error(message, err, meta);
+      return true;
+    }
+    const sink = globalThis.console;
+    sink?.error?.(message, { ...meta, ...err?.stack ? { stack: err.stack } : {} });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function describeFaultRequest(req) {
+  const r = req;
+  if (!r || typeof r !== "object") return {};
+  const str = (v) => typeof v === "string" && v ? v : void 0;
+  const headerId = r.headers ? str(r.headers["x-request-id"]) ?? str(r.headers["X-Request-Id"]) : void 0;
+  const method = str(r.method);
+  const path = str(r.path) ?? str(r.url) ?? str(r.originalUrl);
+  const requestId = str(r.requestId) ?? headerId;
+  return {
+    ...method !== void 0 ? { method } : {},
+    ...path !== void 0 ? { path } : {},
+    ...requestId !== void 0 ? { requestId } : {}
+  };
+}
+
 // src/response-envelope.ts
 function sendOk(res, data, status = 200) {
   res.status(status).json({ success: true, data });
 }
 function sendError(res, status, code, message, extra) {
+  logServerFault({ status, code, message, ...extra?.requestId ? { request: { requestId: extra.requestId } } : {} });
   res.status(status).json({ success: false, error: { code, message, ...extra } });
 }
 
@@ -390,10 +494,33 @@ function declaredUserMessage(error) {
   const declared = error?.userMessage;
   return typeof declared === "string" && declared.trim().length > 0 ? declared : void 0;
 }
+function serverFaultProvenance(thrown) {
+  if (thrown.status < 500) return void 0;
+  return thrown.declaredStatus === void 0 ? "undeclared" : "declared";
+}
 function demotedDeclaredCode(thrown) {
+  if (serverFaultProvenance(thrown) === "undeclared") return void 0;
   return thrown.declaredCode !== void 0 && thrown.declaredCode !== thrown.code ? thrown.declaredCode : void 0;
 }
 
+// src/stranded-decision.ts
+var CARRIER = "strandedDecision";
+function strandedDecisionDetails(err) {
+  const carried = err?.[CARRIER];
+  if (!carried || typeof carried !== "object") return void 0;
+  const d = carried;
+  if (d.finalized !== true) return void 0;
+  if (typeof d.decision !== "string" || d.decision === "") return void 0;
+  if (typeof d.runId !== "string" || d.runId === "") return void 0;
+  if (typeof d.repairable !== "boolean") return void 0;
+  return { finalized: true, decision: d.decision, runId: d.runId, repairable: d.repairable };
+}
+function strandedDecisionFailure(message, details) {
+  const err = new Error(message);
+  err[CARRIER] = details;
+  return err;
+}
+
 // src/relation-sub-object.ts
 function matchMissingColumnOfRelation(message) {
   return MISSING_COLUMN_OF_RELATION.exec(message)?.[1];
@@ -406,7 +533,7 @@ var RELATION_SUB_OBJECT = /["'`][^"'`]+["'`]\s+of relation\s/i;
 
 // src/unique-violation.ts
 var UNIQUE_VIOLATION = {
-  codes: /* @__PURE__ */ new Set(["23505", "ER_DUP_ENTRY", "SQLITE_CONSTRAINT_UNIQUE"]),
+  codes: /* @__PURE__ */ new Set(["23505", "ER_DUP_ENTRY", "SQLITE_CONSTRAINT_UNIQUE", "UNIQUE_VIOLATION"]),
   errnos: /* @__PURE__ */ new Set([1062]),
   message: /unique constraint failed|violates unique constraint|unique violation|duplicate key|duplicate entry/i
 };
@@ -470,16 +597,199 @@ function uniqueViolationColumn(error) {
   return findUniqueViolationColumn(error, 0);
 }
 
+// src/driver-error-classification.ts
+var RELATION_IN_PHRASE = [
+  // SQLite / libsql: `no such table: sys_metadata_history`, and the
+  // schema-qualified `no such table: main.orders` it uses when it resolved
+  // the name itself (views, triggers) or the caller qualified it.
+  /no such table:\s*([^\s'"`;,()]+)/i,
+  // PostgreSQL: `relation "sys_metadata_history" does not exist`
+  /relation\s+["'`]([^"'`]+)["'`]\s+does not exist/i,
+  // MySQL / MariaDB: `Table 'app.sys_metadata_history' doesn't exist`
+  /table\s+["'`]([^"'`]+)["'`]\s+doesn'?t exist/i,
+  // MySQL / MariaDB: `Unknown table 'app.t'`
+  /unknown table\s+["'`]([^"'`]+)["'`]/i
+];
+function normaliseRelationName(name) {
+  const afterQualifier = name.slice(name.lastIndexOf(".") + 1);
+  const namespaceEnd = afterQualifier.lastIndexOf("__");
+  const bare = namespaceEnd === -1 ? afterQualifier : afterQualifier.slice(namespaceEnd + 2);
+  return bare.toLowerCase();
+}
+function phraseNamesAnotherRelation(message, readObject) {
+  const expected = normaliseRelationName(readObject);
+  if (expected === "") return false;
+  let named = false;
+  for (const pattern of RELATION_IN_PHRASE) {
+    const captured = pattern.exec(message)?.[1];
+    if (captured === void 0) continue;
+    const candidate = normaliseRelationName(captured);
+    if (candidate === "") continue;
+    if (candidate === expected) return false;
+    named = true;
+  }
+  return named;
+}
+var ALREADY_EXISTS = {
+  codes: /* @__PURE__ */ new Set([
+    // PostgreSQL SQLSTATE (class 42 — syntax error or access rule violation)
+    "42P07",
+    // duplicate_table
+    "42701",
+    // duplicate_column
+    "42710",
+    // duplicate_object — index / constraint already exists
+    // MySQL / MariaDB (mysql2 puts the symbolic name on `code`)
+    "ER_TABLE_EXISTS_ERROR",
+    // 1050
+    "ER_DUP_FIELDNAME",
+    // 1060
+    "ER_DUP_KEYNAME"
+    // 1061
+  ]),
+  errnos: /* @__PURE__ */ new Set([1050, 1060, 1061]),
+  /**
+   * Message fallback for drivers that carry no machine-readable code —
+   * notably SQLite, whose `code` is the undifferentiated `SQLITE_ERROR` for
+   * every DDL failure, so the message is the only signal available:
+   *   - `table sys_metadata already exists`
+   *   - `duplicate column name: environment_id`
+   *   - `index idx_x already exists`
+   * Postgres phrases its own as `relation "x" already exists` /
+   * `column "x" of relation "y" already exists`, which matches the same test.
+   */
+  message: /already exists|duplicate column name|duplicate key name/i
+};
+var MISSING_TABLE = {
+  codes: /* @__PURE__ */ new Set([
+    "42P01",
+    // PostgreSQL undefined_table
+    "ER_NO_SUCH_TABLE"
+    // MySQL / MariaDB 1146
+  ]),
+  errnos: /* @__PURE__ */ new Set([1146]),
+  /**
+   *   - SQLite / libsql: `no such table: sys_metadata_history`
+   *   - PostgreSQL:      `relation "sys_metadata_history" does not exist`
+   *   - MySQL/MariaDB:   `Table 'app.sys_metadata_history' doesn't exist`
+   */
+  message: /no such table|relation ["'`][^"'`]+["'`] does not exist|table ["'`][^"'`]+["'`] doesn'?t exist|unknown table/i,
+  excludes: {
+    /**
+     * Exactly the three SQLSTATEs the docblock above already names as
+     * must-stay-loud neighbours of `does not exist`. They are listed here
+     * rather than merely trusted to miss the message test, because two of
+     * them (42703 columns, 42704 constraints/triggers) have a phrasing that
+     * *does* hit it, and because a code is a fact where prose is a guess.
+     *
+     * Postgres-shaped on purpose: measured, neither MySQL
+     * (`Unknown column 'label' in 'field list'`) nor SQLite
+     * (`no such column: bogus`, `table t has no column named label`)
+     * phrases a sub-object failure so that a missing-table phrase falls out
+     * of it, so there is nothing there to exclude. Adding their codes would
+     * be surface with no defect behind it.
+     */
+    codes: /* @__PURE__ */ new Set([
+      "42703",
+      // undefined_column
+      "42704",
+      // undefined_object — constraint, trigger, role, type, …
+      "3D000"
+      // invalid_catalog_name — `database "x" does not exist`
+    ]),
+    /**
+     * `«sub-object» "x" of relation "y" …` — Postgres' phrasing for a
+     * failure about something *inside* a relation, which therefore says the
+     * relation itself is present. The two in-repo siblings that carry this
+     * phrase are `mapDataError` (`packages/rest`, #5352) and
+     * `service-analytics`'s missing-column subtraction (#6035/PR #6346).
+     *
+     * [#6615] All three now read one home — `@objectstack/types` — instead
+     * of three hand-kept copies, so the phrase can no longer be taught to
+     * the repo a fourth time or drift in one package only. [#13279] This
+     * file now lives in that same home, so the read is a sibling import. The **width**
+     * difference that used to justify the copy is preserved and is the
+     * reason the home exports two functions rather than one: those two
+     * *extract* the column name to phrase a better error, so a miss costs a
+     * vaguer message; this one *excludes*, so a miss restores the
+     * corruption. {@link isRelationSubObjectPhrase} is therefore the wider
+     * question — it drops their `column`/`[a-z0-9_]+`/`does not exist`
+     * anchors: any sub-object, any quoted identifier, any verdict.
+     * Over-matching here only ever converts a benign verdict into a loud
+     * one, which is the direction this whole module already errs in.
+     */
+    matchesMessage: isRelationSubObjectPhrase,
+    /**
+     * [#13324] "…and the relation it names is not the one you read."
+     *
+     * The sibling of the phrase above, reached one step further out. That
+     * one recognises a failure about something INSIDE a relation, which
+     * therefore says the relation is present; this one recognises a failure
+     * about a DIFFERENT relation, which says nothing at all about the one
+     * the caller read. Both end the question with `false` for the same
+     * reason: the licence this predicate grants — "there are no rows, so
+     * there is nothing to be inconsistent with" — is about the table that
+     * was READ, and neither phrase is evidence about it.
+     */
+    namesAnotherRelation: phraseNamesAnotherRelation
+  }
+};
+var MAX_CAUSE_DEPTH2 = 4;
+var DRIVER_TARGETED_TABLE = /* @__PURE__ */ Symbol.for("objectstack.driver.targetedTable");
+function declareTargetedTable(error, table) {
+  if (typeof table !== "string" || table === "") return error;
+  if (targetedTableOf(error) !== null) return error;
+  Object.defineProperty(error, DRIVER_TARGETED_TABLE, { value: table, enumerable: false });
+  return error;
+}
+function targetedTableOf(error) {
+  if (error === null || typeof error !== "object" && typeof error !== "function") return null;
+  const table = error[DRIVER_TARGETED_TABLE];
+  return typeof table === "string" && table !== "" ? table : null;
+}
+function excludedByReadObject(message, signature, relation) {
+  if (typeof relation !== "string" || relation === "") return false;
+  return signature.excludes?.namesAnotherRelation?.(message, relation) === true;
+}
+function matchesDriverError(error, signature, depth, readObject) {
+  if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH2) return false;
+  if (typeof error === "string") {
+    if (signature.excludes?.matchesMessage(error)) return false;
+    if (excludedByReadObject(error, signature, readObject)) return false;
+    return signature.message.test(error);
+  }
+  if (typeof error !== "object") return false;
+  const err = error;
+  const relation = targetedTableOf(err) ?? readObject;
+  const excludes = signature.excludes;
+  if (excludes) {
+    if (typeof err.code === "string" && excludes.codes.has(err.code)) return false;
+    if (typeof err.message === "string" && excludes.matchesMessage(err.message)) return false;
+    if (typeof err.message === "string" && excludedByReadObject(err.message, signature, relation))
+      return false;
+  }
+  if (typeof err.code === "string" && signature.codes.has(err.code)) return true;
+  if (typeof err.errno === "number" && signature.errnos.has(err.errno)) return true;
+  if (typeof err.message === "string" && signature.message.test(err.message)) return true;
+  return matchesDriverError(err.cause, signature, depth + 1, relation);
+}
+function isSchemaAlreadyExistsError(error, depth = 0) {
+  return matchesDriverError(error, ALREADY_EXISTS, depth);
+}
+function isMissingTableError(error, readObject, depth = 0) {
+  return matchesDriverError(error, MISSING_TABLE, depth, readObject);
+}
+
 // src/unbacked-conflict-target.ts
 var UNBACKED_CONFLICT_TARGET = {
   message: /ON CONFLICT clause does not match any PRIMARY KEY or UNIQUE constraint|there is no unique or exclusion constraint matching the ON CONFLICT specification/i
 };
-var MAX_CAUSE_DEPTH2 = 4;
+var MAX_CAUSE_DEPTH3 = 4;
 function isUnbackedConflictTargetError(error) {
   return matchesUnbackedConflictTarget(error, 0);
 }
 function matchesUnbackedConflictTarget(error, depth) {
-  if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH2) return false;
+  if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH3) return false;
   if (typeof error === "string") return UNBACKED_CONFLICT_TARGET.message.test(error);
   if (typeof error !== "object") return false;
   const err = error;
@@ -586,30 +896,40 @@ function postureGatesGlobalUniques(posture) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DRIVER_TARGETED_TABLE,
   GLOBAL_UNIQUE_CONFIRMATION_REQUIRED,
   GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION,
   INTERNAL_ERROR_MESSAGE,
+  PLATFORM_OWNER_EMAIL_ENV,
+  SERVER_FAULT_LOG_PREFIX,
   VALIDATION_FAILED_STATUS,
   _resetEnvDeprecationWarnings,
   buildGlobalUniqueStopMessage,
   collectConfiguredLocales,
   collectGlobalUniques,
+  declareTargetedTable,
   declaredIndexUniqueIsGlobal,
   declaredUserMessage,
   declaresServerFault,
   demotedDeclaredCode,
+  describeFaultRequest,
   describeGlobalUniqueFinding,
   emitDegradedBootBanner,
   fieldUniqueIsGlobal,
   fieldsFromZodIssues,
   globalUniqueFindingId,
+  isEmailVerifiedUserRow,
   isMcpServerEnabled,
+  isMissingTableError,
   isModuleNotFoundError,
   isPlatformOwnedObject,
   isRelationSubObjectPhrase,
+  isSchemaAlreadyExistsError,
+  isServerFault,
   isUnbackedConflictTargetError,
   isUniqueViolationError,
   keysetWalk,
+  logServerFault,
   looksLikeInternalErrorLeak,
   matchMissingColumnOfRelation,
   postureGatesGlobalUniques,
@@ -621,13 +941,21 @@ function postureGatesGlobalUniques(posture) {
   resolveMcpStdioAutoStart,
   resolveMultiOrgEnabled,
   resolveOrgLimit,
+  resolveOrgMembershipLimit,
+  resolvePlatformOwnerEmail,
   resolveSandboxTimeoutMs,
   resolveSearchPinyinEnabled,
   resolveTenancyPosture,
   resolveThrownHttpError,
   sendError,
   sendOk,
+  serverFaultLogMessage,
+  serverFaultLogMeta,
+  serverFaultProvenance,
   stampSearchPinyinEnabled,
+  strandedDecisionDetails,
+  strandedDecisionFailure,
+  targetedTableOf,
   unconfirmedGlobalUniques,
   uniqueViolationColumn,
   validationFailure,