@palbase/backend 18.0.0 → 20.0.0

package/dist/engine/index.d.cts

@@ -1,4 +1,4 @@
-export { A as App, l as AuthVerifier, B as BootRefused, m as CreateAppOptions, E as EgressPolicy, n as EngineConfig, M as ModuleClients, o as RateLimiter, p as RequestDatabase, q as RouteEntry, r as RuntimeHooks, s as ScrubResult, t as SqlDriver, u as SqlTx, v as buildRouteTable, w as createApp, x as createLazyTransaction, y as createOps, z as createRequestDatabase, G as effectiveAuth, H as hostAllowed, I as installEgressFence, J as loadConfig, K as makeMemoryCache, O as matchRoute, Q as quoteIdent, T as scrubSecrets, U as withTables } from '../index-B46CGNvx.cjs';
+export { A as App, l as AuthVerifier, B as BootRefused, m as CreateAppOptions, E as EgressPolicy, n as EngineConfig, M as ModuleClients, o as RateLimiter, p as RequestDatabase, q as RouteEntry, r as RuntimeHooks, s as ScrubResult, t as SqlDriver, u as SqlTx, v as buildRouteTable, w as createApp, x as createLazyTransaction, y as createOps, z as createRequestDatabase, G as effectiveAuth, H as hostAllowed, I as installEgressFence, J as loadConfig, K as makeMemoryCache, O as matchRoute, Q as quoteIdent, T as scrubSecrets, U as withTables } from '../index-Br9P7yRu.cjs';
 import '../endpoint-B0LpZixz.cjs';
 import '../db/env.cjs';
 import 'node:async_hooks';

package/dist/engine/index.d.ts

@@ -1,4 +1,4 @@
-export { A as App, l as AuthVerifier, B as BootRefused, m as CreateAppOptions, E as EgressPolicy, n as EngineConfig, M as ModuleClients, o as RateLimiter, p as RequestDatabase, q as RouteEntry, r as RuntimeHooks, s as ScrubResult, t as SqlDriver, u as SqlTx, v as buildRouteTable, w as createApp, x as createLazyTransaction, y as createOps, z as createRequestDatabase, G as effectiveAuth, H as hostAllowed, I as installEgressFence, J as loadConfig, K as makeMemoryCache, O as matchRoute, Q as quoteIdent, T as scrubSecrets, U as withTables } from '../index-DZDUMth5.js';
+export { A as App, l as AuthVerifier, B as BootRefused, m as CreateAppOptions, E as EgressPolicy, n as EngineConfig, M as ModuleClients, o as RateLimiter, p as RequestDatabase, q as RouteEntry, r as RuntimeHooks, s as ScrubResult, t as SqlDriver, u as SqlTx, v as buildRouteTable, w as createApp, x as createLazyTransaction, y as createOps, z as createRequestDatabase, G as effectiveAuth, H as hostAllowed, I as installEgressFence, J as loadConfig, K as makeMemoryCache, O as matchRoute, Q as quoteIdent, T as scrubSecrets, U as withTables } from '../index-BeHLq2i-.js';
 import '../endpoint-B0LpZixz.js';
 import '../db/env.js';
 import 'node:async_hooks';

package/dist/engine/index.js

@@ -16,7 +16,7 @@ import {
   quoteIdent,
   scrubSecrets,
   withTables
-} from "../chunk-VYH4U7ZQ.js";
+} from "../chunk-PFQJYW6C.js";
 import "../chunk-POYAFBLF.js";
 import "../chunk-W5ODXPY3.js";
 import "../chunk-QMVK4X3V.js";

package/dist/{index-DZDUMth5.d.ts → index-BeHLq2i-.d.ts}

@@ -827,6 +827,11 @@ interface App {
     handle: (req: Request) => Promise<Response>;
     routes: readonly RouteEntry[];
     config: EngineConfig;
+    /**
+     * Run work that has no request behind it — a scheduled job — inside the same
+     * request scope a handler gets, with its own transaction.
+     */
+    runInServiceScope: <T>(fn: () => T | Promise<T>) => Promise<T>;
     /** Close the pool and release resources. */
     shutdown: () => Promise<void>;
 }

package/dist/{index-B46CGNvx.d.cts → index-Br9P7yRu.d.cts}

@@ -827,6 +827,11 @@ interface App {
     handle: (req: Request) => Promise<Response>;
     routes: readonly RouteEntry[];
     config: EngineConfig;
+    /**
+     * Run work that has no request behind it — a scheduled job — inside the same
+     * request scope a handler gets, with its own transaction.
+     */
+    runInServiceScope: <T>(fn: () => T | Promise<T>) => Promise<T>;
     /** Close the pool and release resources. */
     shutdown: () => Promise<void>;
 }

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(src_exports, {
   DEFAULT_TEMPLATE_LOCALE: () => DEFAULT_TEMPLATE_LOCALE,
   Database: () => Database,
   Delete: () => Delete,
+  Deny: () => Deny,
   Documents: () => Documents,
   EGRESS_CONFIG_KIND: () => EGRESS_CONFIG_KIND,
   EGRESS_TIMEOUT_DEFAULT_MS: () => EGRESS_TIMEOUT_DEFAULT_MS,
@@ -40,6 +41,7 @@ __export(src_exports, {
   Forbidden: () => Forbidden,
   Get: () => Get,
   Headers: () => Headers,
+  Hook: () => Hook,
   HttpError: () => HttpError,
   Job: () => Job,
   Log: () => Log,
@@ -111,6 +113,7 @@ __export(src_exports, {
   extractVariables: () => extractVariables,
   flag: () => flag,
   getErrorRegistry: () => getErrorRegistry,
+  getHookConfig: () => getHookConfig,
   getJobConfig: () => getJobConfig,
   getRegisteredControllers: () => getRegisteredControllers,
   getRoutes: () => getRoutes,
@@ -1703,13 +1706,13 @@ function buildBucketClient(http, bucketName) {
     },
     async remove(paths) {
       for (const p of paths) validateStoragePath(p);
-      const removed = [];
+      const removed2 = [];
       for (const p of paths) {
         const res = await http.request("DELETE", objectPath(p));
         if (res.error) return { data: null, error: res.error, status: res.status };
-        removed.push(toFileObject(bucketName, { path: p }));
+        removed2.push(toFileObject(bucketName, { path: p }));
       }
-      return { data: removed, error: null, status: 200 };
+      return { data: removed2, error: null, status: 200 };
     },
     async move(from, to) {
       validateStoragePath(from);
@@ -2297,7 +2300,7 @@ function makeEnvDts(schema) {
 ${blocks.join("\n")}
   ` : "";
   return `// AUTO-GENERATED by @palbase/backend \u2014 DO NOT EDIT.
-// Regenerated from db/schema.ts on every \`palbase db types\` / deploy.
+// Regenerated from db/schema.ts by \`palbase build\` and by every deploy.
 // Augments the @palbase/backend/env \`Tables\` interface so \`Database.tables.*\`
 // is typed with no import and no generic.
 
@@ -3114,6 +3117,155 @@ var Patch = makeMethodDecorator("PATCH");
 var Delete = makeMethodDecorator("DELETE");
 var Query = makeMethodDecorator("QUERY");
 
+// src/decorators/webhook.ts
+var WEBHOOK_META = /* @__PURE__ */ Symbol.for("palbase.backend.webhookMeta");
+var WEBHOOK_EVENTS = /* @__PURE__ */ Symbol.for("palbase.backend.webhookEvents");
+function carrierOf3(ctor) {
+  return ctor;
+}
+function Webhook(options) {
+  return function(ctor) {
+    const carrier = carrierOf3(ctor);
+    Object.defineProperty(carrier, WEBHOOK_META, {
+      value: options,
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+    Object.defineProperty(carrier, "__palbase", {
+      value: "webhook",
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+    return ctor;
+  };
+}
+function On(event) {
+  return function(target, fnName) {
+    const carrier = carrierOf3(target.constructor);
+    const existing = carrier[WEBHOOK_EVENTS];
+    const entries = existing ? [...existing] : [];
+    entries.push({ event, fnName: String(fnName) });
+    Object.defineProperty(carrier, WEBHOOK_EVENTS, {
+      value: entries,
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+  };
+}
+function getWebhookConfig(ctor) {
+  const carrier = carrierOf3(ctor);
+  const meta = carrier[WEBHOOK_META];
+  const entries = carrier[WEBHOOK_EVENTS] ?? [];
+  if (!meta) {
+    throw new Error(
+      `@On used on a class that is not decorated with @Webhook (${ctor.name ?? "anonymous"})`
+    );
+  }
+  if (!meta.provider && !meta.signature) {
+    throw new Error(
+      "@Webhook requires either a `provider` preset or an explicit `signature` \u2014 an endpoint with no verification would accept forged deliveries"
+    );
+  }
+  if (meta.provider && meta.signature) {
+    throw new Error(
+      "@Webhook declares BOTH a `provider` preset and an explicit `signature` \u2014 these are alternatives; keep the one that describes the sender, because only `provider` would be used"
+    );
+  }
+  if (meta.signature) {
+    const sig = meta.signature;
+    if (!sig.header) {
+      throw new Error("@Webhook signature requires `header` \u2014 the header the signature arrives in");
+    }
+    if (sig.algo !== "hmac-sha256" && sig.algo !== "hmac-sha1") {
+      throw new Error(`@Webhook signature has an unsupported algo "${sig.algo}"`);
+    }
+    if (sig.encoding !== "hex" && sig.encoding !== "base64") {
+      throw new Error(`@Webhook signature has an unsupported encoding "${sig.encoding}"`);
+    }
+    if (!sig.signs?.includes("{body}")) {
+      throw new Error("@Webhook signature `signs` must contain {body} \u2014 signing a constant is not a signature");
+    }
+    if (sig.signs.includes("{ts}") && !sig.timestampHeader) {
+      throw new Error("@Webhook signature uses {ts} but declares no `timestampHeader` to read it from");
+    }
+  }
+  if (!meta.secret?.env) {
+    throw new Error('@Webhook requires `secret: { env: "VAR_NAME" }`');
+  }
+  if (entries.length === 0) {
+    throw new Error("@Webhook requires at least one @On handler");
+  }
+  const instance = new ctor();
+  const events = /* @__PURE__ */ Object.create(null);
+  for (const entry of entries) {
+    if (Object.prototype.hasOwnProperty.call(events, entry.event)) {
+      throw new Error(`@On("${entry.event}") declared twice on the same webhook`);
+    }
+    events[entry.event] = (event, metaArg) => instance[entry.fnName].call(instance, event, metaArg);
+  }
+  return {
+    ...meta.provider ? { provider: meta.provider } : {},
+    ...meta.signature ? { signature: meta.signature } : {},
+    secret: meta.secret,
+    events
+  };
+}
+
+// src/decorators/hook.ts
+var Deny = class extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "Deny";
+  }
+};
+var HOOK_BLOCKING = /* @__PURE__ */ Symbol.for("palbase.backend.hookBlocking");
+function Hook(event) {
+  return function(target, fnName) {
+    const carrier = target.constructor;
+    const existing = carrier[HOOK_BLOCKING];
+    const entries = existing ? [...existing] : [];
+    entries.push({ event, fnName: String(fnName) });
+    Object.defineProperty(carrier, HOOK_BLOCKING, {
+      value: entries,
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+  };
+}
+function bind(instance, entries, kind) {
+  const out = /* @__PURE__ */ Object.create(null);
+  for (const entry of entries) {
+    if (Object.prototype.hasOwnProperty.call(out, entry.event)) {
+      throw new Error(`${kind}("${entry.event}") declared twice on the same hook class`);
+    }
+    const fn = instance[entry.fnName];
+    if (typeof fn !== "function") {
+      throw new Error(`${kind}("${entry.event}") names no method "${entry.fnName}" on the class`);
+    }
+    out[entry.event] = (event, meta) => fn.call(instance, event, meta);
+  }
+  return out;
+}
+function getHookConfig(ctor) {
+  const carrier = ctor;
+  const blockingEntries = carrier[HOOK_BLOCKING] ?? [];
+  const listenerEntries = carrier[WEBHOOK_EVENTS] ?? [];
+  if (blockingEntries.length === 0 && listenerEntries.length === 0) {
+    throw new Error(
+      `${ctor.name ?? "a hook class"} carries no handler \u2014 a hook file must declare at least one @Hook (blocking) or @On (listener) method`
+    );
+  }
+  const instance = new ctor();
+  return {
+    blocking: bind(instance, blockingEntries, "@Hook"),
+    listeners: bind(instance, listenerEntries, "@On")
+  };
+}
+
 // src/decorators/upload.ts
 function Upload(subpath, config) {
   const { auth: auth2, rateLimit, ...uploadConfig } = config;
@@ -3333,103 +3485,6 @@ function humanize(code) {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
 
-// src/decorators/webhook.ts
-var WEBHOOK_META = /* @__PURE__ */ Symbol.for("palbase.backend.webhookMeta");
-var WEBHOOK_EVENTS = /* @__PURE__ */ Symbol.for("palbase.backend.webhookEvents");
-function carrierOf3(ctor) {
-  return ctor;
-}
-function Webhook(options) {
-  return function(ctor) {
-    const carrier = carrierOf3(ctor);
-    Object.defineProperty(carrier, WEBHOOK_META, {
-      value: options,
-      enumerable: false,
-      configurable: true,
-      writable: false
-    });
-    Object.defineProperty(carrier, "__palbase", {
-      value: "webhook",
-      enumerable: false,
-      configurable: true,
-      writable: false
-    });
-    return ctor;
-  };
-}
-function On(event) {
-  return function(target, fnName) {
-    const carrier = carrierOf3(target.constructor);
-    const existing = carrier[WEBHOOK_EVENTS];
-    const entries = existing ? [...existing] : [];
-    entries.push({ event, fnName: String(fnName) });
-    Object.defineProperty(carrier, WEBHOOK_EVENTS, {
-      value: entries,
-      enumerable: false,
-      configurable: true,
-      writable: false
-    });
-  };
-}
-function getWebhookConfig(ctor) {
-  const carrier = carrierOf3(ctor);
-  const meta = carrier[WEBHOOK_META];
-  const entries = carrier[WEBHOOK_EVENTS] ?? [];
-  if (!meta) {
-    throw new Error(
-      `@On used on a class that is not decorated with @Webhook (${ctor.name ?? "anonymous"})`
-    );
-  }
-  if (!meta.provider && !meta.signature) {
-    throw new Error(
-      "@Webhook requires either a `provider` preset or an explicit `signature` \u2014 an endpoint with no verification would accept forged deliveries"
-    );
-  }
-  if (meta.provider && meta.signature) {
-    throw new Error(
-      "@Webhook declares BOTH a `provider` preset and an explicit `signature` \u2014 these are alternatives; keep the one that describes the sender, because only `provider` would be used"
-    );
-  }
-  if (meta.signature) {
-    const sig = meta.signature;
-    if (!sig.header) {
-      throw new Error("@Webhook signature requires `header` \u2014 the header the signature arrives in");
-    }
-    if (sig.algo !== "hmac-sha256" && sig.algo !== "hmac-sha1") {
-      throw new Error(`@Webhook signature has an unsupported algo "${sig.algo}"`);
-    }
-    if (sig.encoding !== "hex" && sig.encoding !== "base64") {
-      throw new Error(`@Webhook signature has an unsupported encoding "${sig.encoding}"`);
-    }
-    if (!sig.signs?.includes("{body}")) {
-      throw new Error("@Webhook signature `signs` must contain {body} \u2014 signing a constant is not a signature");
-    }
-    if (sig.signs.includes("{ts}") && !sig.timestampHeader) {
-      throw new Error("@Webhook signature uses {ts} but declares no `timestampHeader` to read it from");
-    }
-  }
-  if (!meta.secret?.env) {
-    throw new Error('@Webhook requires `secret: { env: "VAR_NAME" }`');
-  }
-  if (entries.length === 0) {
-    throw new Error("@Webhook requires at least one @On handler");
-  }
-  const instance = new ctor();
-  const events = /* @__PURE__ */ Object.create(null);
-  for (const entry of entries) {
-    if (Object.prototype.hasOwnProperty.call(events, entry.event)) {
-      throw new Error(`@On("${entry.event}") declared twice on the same webhook`);
-    }
-    events[entry.event] = (event, metaArg) => instance[entry.fnName].call(instance, event, metaArg);
-  }
-  return {
-    ...meta.provider ? { provider: meta.provider } : {},
-    ...meta.signature ? { signature: meta.signature } : {},
-    secret: meta.secret,
-    events
-  };
-}
-
 // src/job.ts
 function validateCronExpression(expression) {
   const trimmed = expression.trim();
@@ -3500,6 +3555,8 @@ function validateCronField(field, name, min, max) {
 // src/decorators/job.ts
 var DEFAULT_TIMEOUT_SECONDS = 30;
 var MAX_TIMEOUT_SECONDS = 300;
+var DEFAULT_RETRY = 5;
+var MAX_RETRY = 10;
 var JOB_META = /* @__PURE__ */ Symbol.for("palbase.backend.jobMeta");
 function Job(options) {
   return function(ctor) {
@@ -3540,12 +3597,19 @@ function getJobConfig(ctor) {
   if (timeout > MAX_TIMEOUT_SECONDS) {
     throw new Error(`@Job \`timeout\` exceeds the ${MAX_TIMEOUT_SECONDS}s sandbox ceiling`);
   }
+  const retry = meta.retry ?? DEFAULT_RETRY;
+  if (!Number.isInteger(retry) || retry < 0) {
+    throw new Error("@Job `retry` must be a whole number of attempts, zero or more");
+  }
+  if (retry > MAX_RETRY) {
+    throw new Error(`@Job \`retry\` exceeds the ceiling of ${MAX_RETRY}`);
+  }
   const instance = new ctor();
   if (typeof instance.run !== "function") {
     throw new Error("@Job class must declare an async run() method");
   }
   const run = instance.run.bind(instance);
-  return { schedule: meta.schedule, timeout, handler: run };
+  return { schedule: meta.schedule, timeout, retry, handler: run };
 }
 
 // src/resource.ts
@@ -3595,38 +3659,31 @@ async function __shutdownResources() {
 }
 
 // src/hooks.ts
-var auth = {
-  onUserCreated(handler) {
-    return { module: "auth", event: "user.created", handler };
-  },
-  onSignIn(handler) {
-    return { module: "auth", event: "user.sign_in", handler };
-  },
-  onSignOut(handler) {
-    return { module: "auth", event: "user.sign_out", handler };
-  },
-  onPasswordReset(handler) {
-    return { module: "auth", event: "user.password_reset", handler };
+function removed(helper, decorator, event) {
+  throw new Error(
+    `${helper}() does not register anything and never did \u2014 nothing in the runtime or the bundler reads what it returns, so the handler you passed would never run. Declare it instead in hooks/<name>.ts:
+
+  export default class MyHooks {
+    ${decorator}("${event}")
+    async handle(event, meta) { /* \u2026 */ }
   }
+`
+  );
+}
+var auth = {
+  onUserCreated: (_h) => removed("auth.onUserCreated", "@Hook", "before.user.create"),
+  onSignIn: (_h) => removed("auth.onSignIn", "@Hook", "before.login"),
+  onSignOut: (_h) => removed("auth.onSignOut", "@On", "after.session.revoke"),
+  onPasswordReset: (_h) => removed("auth.onPasswordReset", "@Hook", "before.password.reset")
 };
 var storage = {
-  onFileUploaded(handler) {
-    return { module: "storage", event: "file.uploaded", handler };
-  },
-  onFileDeleted(handler) {
-    return { module: "storage", event: "file.deleted", handler };
-  }
+  onFileUploaded: (_h) => removed("storage.onFileUploaded", "@On", "file.uploaded"),
+  onFileDeleted: (_h) => removed("storage.onFileDeleted", "@On", "file.deleted")
 };
 var documents = {
-  onDocumentCreated(handler) {
-    return { module: "documents", event: "document.created", handler };
-  },
-  onDocumentUpdated(handler) {
-    return { module: "documents", event: "document.updated", handler };
-  },
-  onDocumentDeleted(handler) {
-    return { module: "documents", event: "document.deleted", handler };
-  }
+  onDocumentCreated: (_h) => removed("documents.onDocumentCreated", "@On", "document.created"),
+  onDocumentUpdated: (_h) => removed("documents.onDocumentUpdated", "@On", "document.updated"),
+  onDocumentDeleted: (_h) => removed("documents.onDocumentDeleted", "@On", "document.deleted")
 };
 
 // src/index.ts
@@ -3642,6 +3699,7 @@ var import_zod2 = require("zod");
   DEFAULT_TEMPLATE_LOCALE,
   Database,
   Delete,
+  Deny,
   Documents,
   EGRESS_CONFIG_KIND,
   EGRESS_TIMEOUT_DEFAULT_MS,
@@ -3653,6 +3711,7 @@ var import_zod2 = require("zod");
   Forbidden,
   Get,
   Headers,
+  Hook,
   HttpError,
   Job,
   Log,
@@ -3724,6 +3783,7 @@ var import_zod2 = require("zod");
   extractVariables,
   flag,
   getErrorRegistry,
+  getHookConfig,
   getJobConfig,
   getRegisteredControllers,
   getRoutes,