@palbase/backend 18.0.1 → 21.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,
@@ -89,7 +91,6 @@ __export(src_exports, {
   __runWithRuntime: () => __runWithRuntime,
   __setRuntime: () => __setRuntime,
   __shutdownResources: () => __shutdownResources,
-  auth: () => auth,
   bigint: () => bigint,
   boolean: () => boolean,
   bucket: () => bucket,
@@ -105,12 +106,12 @@ __export(src_exports, {
   defineSecrets: () => defineSecrets,
   defineStorage: () => defineStorage,
   defineTestUsers: () => defineTestUsers,
-  documents: () => documents,
   entitlementFor: () => entitlementFor,
   enumType: () => enumType,
   extractVariables: () => extractVariables,
   flag: () => flag,
   getErrorRegistry: () => getErrorRegistry,
+  getHookConfig: () => getHookConfig,
   getJobConfig: () => getJobConfig,
   getRegisteredControllers: () => getRegisteredControllers,
   getRoutes: () => getRoutes,
@@ -132,7 +133,6 @@ __export(src_exports, {
   reservedSecretKey: () => reservedSecretKey,
   secret: () => secret,
   spendFor: () => spendFor,
-  storage: () => storage,
   testUser: () => testUser,
   text: () => text,
   timestamp: () => timestamp,
@@ -645,13 +645,13 @@ var Database = Object.assign(makeTypedSurface(rawDatabase), {
   }
 });
 var Documents = makeServiceProxy("Documents");
-function makeBucketsAccessor(storage2) {
+function makeBucketsAccessor(storage) {
   return new Proxy(
     {},
     {
       get(_t, prop) {
         if (typeof prop !== "string") return void 0;
-        return storage2().bucket(prop);
+        return storage().bucket(prop);
       }
     }
   );
@@ -2297,7 +2297,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,13 +3114,162 @@ 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;
+  const { auth, rateLimit, ...uploadConfig } = config;
   validateUploadConfigShape(uploadConfig);
   const options = {
     uploadConfig,
-    ...auth2 !== void 0 ? { auth: auth2 } : {},
+    ...auth !== void 0 ? { auth } : {},
     ...rateLimit !== void 0 ? { rateLimit } : {}
   };
   return function(target, propertyKey) {
@@ -3146,10 +3295,10 @@ function validateUploadConfigShape(c) {
     throw new Error("@Upload config.pathTemplate must be a non-empty key template");
   }
 }
-function validateUploadAgainstStorage(uploadConfig, storage2, routeLabel) {
-  const def = storage2.buckets[uploadConfig.bucket];
+function validateUploadAgainstStorage(uploadConfig, storage, routeLabel) {
+  const def = storage.buckets[uploadConfig.bucket];
   if (def === void 0) {
-    const known = Object.keys(storage2.buckets);
+    const known = Object.keys(storage.buckets);
     throw new Error(
       `@Upload route ${routeLabel} targets bucket "${uploadConfig.bucket}" which is not declared in defineStorage(...). ` + (known.length ? `Known buckets: ${known.join(", ")}.` : "No buckets are declared.")
     );
@@ -3333,103 +3482,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 +3552,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 +3594,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
@@ -3594,41 +3655,6 @@ async function __shutdownResources() {
   registry2.length = 0;
 }
 
-// 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 };
-  }
-};
-var storage = {
-  onFileUploaded(handler) {
-    return { module: "storage", event: "file.uploaded", handler };
-  },
-  onFileDeleted(handler) {
-    return { module: "storage", event: "file.deleted", handler };
-  }
-};
-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 };
-  }
-};
-
 // src/index.ts
 var import_zod2 = require("zod");
 // Annotate the CommonJS export names for ESM import in node:
@@ -3642,6 +3668,7 @@ var import_zod2 = require("zod");
   DEFAULT_TEMPLATE_LOCALE,
   Database,
   Delete,
+  Deny,
   Documents,
   EGRESS_CONFIG_KIND,
   EGRESS_TIMEOUT_DEFAULT_MS,
@@ -3653,6 +3680,7 @@ var import_zod2 = require("zod");
   Forbidden,
   Get,
   Headers,
+  Hook,
   HttpError,
   Job,
   Log,
@@ -3702,7 +3730,6 @@ var import_zod2 = require("zod");
   __runWithRuntime,
   __setRuntime,
   __shutdownResources,
-  auth,
   bigint,
   boolean,
   bucket,
@@ -3718,12 +3745,12 @@ var import_zod2 = require("zod");
   defineSecrets,
   defineStorage,
   defineTestUsers,
-  documents,
   entitlementFor,
   enumType,
   extractVariables,
   flag,
   getErrorRegistry,
+  getHookConfig,
   getJobConfig,
   getRegisteredControllers,
   getRoutes,
@@ -3745,7 +3772,6 @@ var import_zod2 = require("zod");
   reservedSecretKey,
   secret,
   spendFor,
-  storage,
   testUser,
   text,
   timestamp,