@palbase/backend 9.0.0 → 10.0.0

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(src_exports, {
   Database: () => Database,
   Delete: () => Delete,
   Documents: () => Documents,
+  EGRESS_CONFIG_KIND: () => EGRESS_CONFIG_KIND,
   EXTENSION_DEPENDENCIES: () => EXTENSION_DEPENDENCIES,
   FLAGS_CONFIG_KIND: () => FLAGS_CONFIG_KIND,
   Flags: () => Flags,
@@ -59,6 +60,7 @@ __export(src_exports, {
   Resource: () => Resource,
   STORAGE_CONFIG_KIND: () => STORAGE_CONFIG_KIND,
   Storage: () => Storage,
+  TEST_USERS_CONFIG_KIND: () => TEST_USERS_CONFIG_KIND,
   TooManyRequests: () => TooManyRequests,
   TraceId: () => TraceId,
   Unauthorized: () => Unauthorized,
@@ -77,6 +79,7 @@ __export(src_exports, {
   boolean: () => boolean,
   bucket: () => bucket,
   buildProvider: () => buildProvider,
+  defineEgress: () => defineEgress,
   defineError: () => defineError,
   defineFlags: () => defineFlags,
   defineJob: () => defineJob,
@@ -84,12 +87,14 @@ __export(src_exports, {
   defineNotifications: () => defineNotifications,
   defineSchema: () => defineSchema,
   defineStorage: () => defineStorage,
+  defineTestUsers: () => defineTestUsers,
   defineWebhook: () => defineWebhook,
   defineWorker: () => defineWorker,
   documents: () => documents,
   enumType: () => enumType,
   flag: () => flag,
   getErrorRegistry: () => getErrorRegistry,
+  getRoutes: () => getRoutes,
   integer: () => integer,
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
@@ -102,6 +107,7 @@ __export(src_exports, {
   recordThrows: () => recordThrows,
   reservedSecretKey: () => reservedSecretKey,
   storage: () => storage,
+  testUser: () => testUser,
   text: () => text,
   timestamp: () => timestamp,
   uuid: () => uuid,
@@ -402,12 +408,44 @@ var ColumnBuilder = class _ColumnBuilder {
    * `auth.users` lives in the SAME tenant database (palauth-owned), so this is
    * a genuine cross-schema integrity constraint scoped to THIS tenant's users.
    * The referenced `auth.users.id` is `text` (palauth ids are `usr_<uuid>`), so
-   * the referencing column must be `text()` too. Combine with `.onDelete(...)`
-   * for cascade behaviour, e.g. a `user_id` column defined as
-   * `text().notNull().referencesAuthUser().onDelete("cascade")`.
+   * the referencing column must be `text()` too.
+   *
+   * ON DELETE is REQUIRED here and may only be `cascade` or `set null`: an
+   * account-erasure request must never be blocked by a lingering FK, so
+   * `restrict` / `no action` are not accepted (they don't type-check). Example:
+   * `text().notNull().referencesAuthUser("cascade")`, or
+   * `text().nullable().referencesAuthUser("set null")`. The server
+   * (validateAuthUserFK) enforces this — and the remaining rules the type can't
+   * express (referencing column is text, `set null` needs a nullable column) —
+   * as the real boundary; this signature is the compile-time DX mirror.
    */
-  referencesAuthUser() {
-    return this.references("auth.users", "id");
+  referencesAuthUser(onDelete) {
+    this._def.references = { table: "auth.users", column: "id" };
+    this._def.onDeleteAction = onDelete;
+    return new _ColumnBuilder(this._def.type, this._def);
+  }
+  /**
+   * Add a real DB-level foreign key to the canonical, server-minted installation
+   * anchor (`REFERENCES auth.installations(id)`) — the app-scoped verified-device
+   * root (`ins_...`). Sugar for `.references("auth.installations", "id")`.
+   *
+   * An installation is an APP INSTALL, not a user: this FK is NOT user ownership.
+   * A user-owned row STILL needs its own `.referencesAuthUser(...)` FK so account
+   * erasure removes it — an installation reference alone does not tie a row to a
+   * user's deletion. Use this only for install-scoped state (device prefs, push
+   * routing, …), alongside a separate auth-user FK where the row is user-owned.
+   *
+   * `auth.installations` lives in the SAME tenant DB (palauth-owned); its `id` is
+   * `text` (`ins_<uuid>`), so the referencing column must be `text()` too. ON
+   * DELETE is REQUIRED and may only be `cascade` or `set null` (same allowed set
+   * as an auth-user FK): an installation revoke / orphan cleanup must never be
+   * blocked by a lingering FK. The server (validateAuthAnchorFK) is the real
+   * boundary; this signature is the compile-time DX mirror.
+   */
+  referencesInstallation(onDelete) {
+    this._def.references = { table: "auth.installations", column: "id" };
+    this._def.onDeleteAction = onDelete;
+    return new _ColumnBuilder(this._def.type, this._def);
   }
   /** Set the ON DELETE action for a foreign key reference. */
   onDelete(action) {
@@ -515,7 +553,50 @@ function rowType(def) {
 function optionalOnInsert(def) {
   return def.nullable === true || def.defaultRandom === true || def.defaultNow === true || def.defaultValue !== void 0;
 }
-function tableBlock(table, indent) {
+var AUTH_USERS_TABLE = "auth.users";
+function ownerColumnOf(table) {
+  for (const [col, builder] of Object.entries(table.columns)) {
+    if (builder._def.references?.table === AUTH_USERS_TABLE) return col;
+  }
+  return null;
+}
+function buildChildEdges(schema) {
+  const edges = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(schema.tables)) edges.set(name, []);
+  for (const childName of Object.keys(schema.tables)) {
+    const table = schema.tables[childName];
+    if (table === void 0) continue;
+    for (const [col, builder] of Object.entries(table.columns)) {
+      const ref = builder._def.references;
+      if (ref === void 0) continue;
+      if (ref.table === childName) continue;
+      const bucket2 = edges.get(ref.table);
+      if (bucket2 === void 0) continue;
+      if (bucket2.some((e) => e.child === childName)) continue;
+      bucket2.push({ child: childName, column: col });
+    }
+  }
+  return edges;
+}
+function pruneCycles(raw2) {
+  const pruned = /* @__PURE__ */ new Map();
+  for (const table of raw2.keys()) pruned.set(table, []);
+  const state = /* @__PURE__ */ new Map();
+  function visit(table) {
+    state.set(table, "visiting");
+    for (const edge of raw2.get(table) ?? []) {
+      if (state.get(edge.child) === "visiting") continue;
+      pruned.get(table)?.push(edge);
+      if (state.get(edge.child) === void 0) visit(edge.child);
+    }
+    state.set(table, "done");
+  }
+  for (const table of raw2.keys()) {
+    if (state.get(table) === void 0) visit(table);
+  }
+  return pruned;
+}
+function tableBlock(table, children, indent) {
   const cols = Object.entries(table.columns);
   const rowLines = cols.map(([col, builder]) => {
     return `${indent}    ${col}: ${rowType(builder._def)};`;
@@ -525,6 +606,8 @@ function tableBlock(table, indent) {
     const opt = optionalOnInsert(def) ? "?" : "";
     return `${indent}    ${col}${opt}: ${rowType(def)};`;
   });
+  const owner = ownerColumnOf(table);
+  const childEntries = children.map((e) => `${JSON.stringify(e.child)}: ${JSON.stringify(e.column)}`).join("; ");
   return [
     `${indent}${table.name}: {`,
     `${indent}  row: {`,
@@ -533,12 +616,17 @@ function tableBlock(table, indent) {
     `${indent}  insert: {`,
     ...insertLines,
     `${indent}  };`,
+    `${indent}  owner: ${owner === null ? "null" : JSON.stringify(owner)};`,
+    `${indent}  children: {${childEntries === "" ? "" : ` ${childEntries} `}};`,
     `${indent}};`
   ].join("\n");
 }
 function makeEnvDts(schema) {
   const tableNames = Object.keys(schema.tables);
-  const blocks = tableNames.map((name) => tableBlock(schema.tables[name], "    "));
+  const children = pruneCycles(buildChildEdges(schema));
+  const blocks = tableNames.map(
+    (name) => tableBlock(schema.tables[name], children.get(name) ?? [], "    ")
+  );
   const body = blocks.length > 0 ? `
 ${blocks.join("\n")}
   ` : "";
@@ -633,6 +721,22 @@ function defineStorage(input) {
   return { __config: STORAGE_CONFIG_KIND, buckets };
 }
 
+// src/config/egress.ts
+var EGRESS_CONFIG_KIND = "egress";
+function defineEgress(input) {
+  if (input === null || typeof input !== "object" || !Array.isArray(input.hosts)) {
+    throw new Error("defineEgress expects { hosts: string[] }");
+  }
+  const hosts = [];
+  for (const h of input.hosts) {
+    if (typeof h !== "string" || h.trim().length === 0) {
+      throw new Error("defineEgress: every host must be a non-empty string");
+    }
+    hosts.push(h.trim().toLowerCase());
+  }
+  return { __config: EGRESS_CONFIG_KIND, hosts };
+}
+
 // src/config/notifications.ts
 var NOTIFICATIONS_CONFIG_KIND = "notifications";
 var RESERVED_SECRET_PREFIX = "PB_NOTIFICATIONS";
@@ -744,6 +848,98 @@ function camelToUpperSnake(s) {
   return s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
 }
 
+// src/config/test-users.ts
+var TEST_USERS_CONFIG_KIND = "test-users";
+var TEST_USER_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var MIN_PASSWORD_LENGTH = 8;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeSeed(seed, userName) {
+  if (seed === void 0) return {};
+  if (!isPlainObject(seed)) {
+    throw new Error(`testUser ${JSON.stringify(userName)}: seed must be { <table>: [ {...} ] }`);
+  }
+  const out = {};
+  for (const [table, rows] of Object.entries(seed)) {
+    if (!Array.isArray(rows)) {
+      throw new Error(
+        `testUser ${JSON.stringify(userName)}: seed.${table} must be an array of rows`
+      );
+    }
+    if (rows.length === 0) {
+      throw new Error(
+        `testUser ${JSON.stringify(userName)}: seed.${table} is empty \u2014 remove it or add a row`
+      );
+    }
+    for (const row of rows) {
+      if (!isPlainObject(row)) {
+        throw new Error(
+          `testUser ${JSON.stringify(userName)}: every row in seed.${table} must be an object`
+        );
+      }
+    }
+    out[table] = rows;
+  }
+  return out;
+}
+function testUser(opts = {}) {
+  if (!isPlainObject(opts)) {
+    throw new Error("testUser() expects { email?, password?, seed? }");
+  }
+  const hasEmail = opts.email !== void 0;
+  const hasPassword = opts.password !== void 0;
+  if (hasEmail !== hasPassword) {
+    throw new Error(
+      "testUser() needs email AND password together (a fixture with stable credentials) or neither (a template the server generates credentials for)"
+    );
+  }
+  let email = null;
+  let password = null;
+  if (hasEmail) {
+    if (typeof opts.email !== "string" || !EMAIL_RE.test(opts.email)) {
+      throw new Error(`testUser email ${JSON.stringify(opts.email)} is not a valid address`);
+    }
+    if (typeof opts.password !== "string" || opts.password.length < MIN_PASSWORD_LENGTH) {
+      throw new Error(
+        `testUser password must be at least ${MIN_PASSWORD_LENGTH} characters (got ${typeof opts.password === "string" ? opts.password.length : 0})`
+      );
+    }
+    email = opts.email;
+    password = opts.password;
+  }
+  return { email, password, seed: normalizeSeed(opts.seed, email ?? "<template>") };
+}
+function defineTestUsers(input) {
+  if (!isPlainObject(input) || !isPlainObject(input.users)) {
+    throw new Error("defineTestUsers expects { users: { <name>: testUser({...}) } }");
+  }
+  const users = {};
+  const emails = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(input.users)) {
+    if (!TEST_USER_NAME_RE.test(name)) {
+      throw new Error(
+        `test user name ${JSON.stringify(name)} is invalid \u2014 must start with a letter and contain only letters, digits, and underscores`
+      );
+    }
+    const def = input.users[name];
+    if (def === void 0) continue;
+    if (def.email !== null) {
+      const lower = def.email.toLowerCase();
+      const already = emails.get(lower);
+      if (already !== void 0) {
+        throw new Error(
+          `test users ${JSON.stringify(already)} and ${JSON.stringify(name)} declare the same e-mail ${JSON.stringify(def.email)}`
+        );
+      }
+      emails.set(lower, name);
+    }
+    users[name] = def;
+  }
+  return { __config: TEST_USERS_CONFIG_KIND, users };
+}
+
 // src/config/flags.ts
 var FLAGS_CONFIG_KIND = "flags";
 var FLAG_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
@@ -916,10 +1112,42 @@ function recordThrows(target, fnName, throws) {
   const throwsBuffer = carrier[THROWS_BUFFER];
   if (throwsBuffer) throwsBuffer[fnName] = throws;
 }
+function getRoutes(ctor) {
+  const carrier = carrierOf(ctor);
+  const routes = carrier[ROUTES] ?? [];
+  const returnBuffer = carrier[RETURN_BUFFER];
+  if (returnBuffer) {
+    for (const route of routes) {
+      const buffered = returnBuffer[route.fnName];
+      if (buffered && route.returnSchema === void 0) {
+        route.returnSchema = buffered;
+      }
+    }
+  }
+  const throwsBuffer = carrier[THROWS_BUFFER];
+  if (throwsBuffer) {
+    for (const route of routes) {
+      const buffered = throwsBuffer[route.fnName];
+      if (buffered && route.throws === void 0) {
+        route.throws = buffered;
+      }
+    }
+  }
+  return routes.map((r) => ({
+    ...r,
+    params: r.params.slice(),
+    ...r.throws !== void 0 ? { throws: r.throws.slice() } : {}
+  }));
+}
 
 // src/decorators/methods.ts
 function makeMethodDecorator(method) {
   return function(subpath, options = {}) {
+    if (typeof subpath !== "string") {
+      throw new Error(
+        `@${method[0]}${method.slice(1).toLowerCase()}(subpath) expects a string subpath, got ${typeof subpath}.` + (method === "QUERY" ? " If this is a zod schema on a method parameter: the query-string param decorator was renamed @QueryParams(schema) in @palbase/backend 9.0.0." : "")
+      );
+    }
     return function(target, propertyKey) {
       recordRoute(target, String(propertyKey), method, subpath, options);
     };
@@ -1519,6 +1747,7 @@ var import_zod2 = require("zod");
   Database,
   Delete,
   Documents,
+  EGRESS_CONFIG_KIND,
   EXTENSION_DEPENDENCIES,
   FLAGS_CONFIG_KIND,
   Flags,
@@ -1549,6 +1778,7 @@ var import_zod2 = require("zod");
   Resource,
   STORAGE_CONFIG_KIND,
   Storage,
+  TEST_USERS_CONFIG_KIND,
   TooManyRequests,
   TraceId,
   Unauthorized,
@@ -1567,6 +1797,7 @@ var import_zod2 = require("zod");
   boolean,
   bucket,
   buildProvider,
+  defineEgress,
   defineError,
   defineFlags,
   defineJob,
@@ -1574,12 +1805,14 @@ var import_zod2 = require("zod");
   defineNotifications,
   defineSchema,
   defineStorage,
+  defineTestUsers,
   defineWebhook,
   defineWorker,
   documents,
   enumType,
   flag,
   getErrorRegistry,
+  getRoutes,
   integer,
   isPalbaseExtension,
   jsonb,
@@ -1592,6 +1825,7 @@ var import_zod2 = require("zod");
   recordThrows,
   reservedSecretKey,
   storage,
+  testUser,
   text,
   timestamp,
   uuid,