@palbase/backend 10.3.0 → 12.0.0

package/dist/index.cjs

@@ -37,10 +37,12 @@ __export(src_exports, {
   Get: () => Get,
   Headers: () => Headers,
   HttpError: () => HttpError,
+  Job: () => Job,
   Log: () => Log,
   NOTIFICATIONS_CONFIG_KIND: () => NOTIFICATIONS_CONFIG_KIND,
   NotFound: () => NotFound,
   Notifications: () => Notifications,
+  On: () => On,
   OptionalUser: () => OptionalUser,
   PALBASE_EXTENSIONS: () => PALBASE_EXTENSIONS,
   PROVIDER_CATALOG: () => PROVIDER_CATALOG,
@@ -66,10 +68,13 @@ __export(src_exports, {
   TEST_USERS_CONFIG_KIND: () => TEST_USERS_CONFIG_KIND,
   TooManyRequests: () => TooManyRequests,
   TraceId: () => TraceId,
+  TxPlanError: () => TxPlanError,
+  TxRefError: () => TxRefError,
   Unauthorized: () => Unauthorized,
   Upload: () => Upload,
   UploadedObject: () => UploadedObject,
   User: () => User,
+  Webhook: () => Webhook,
   __getRuntime: () => __getRuntime,
   __registerResource: () => __registerResource,
   __requestALS: () => __requestALS,
@@ -82,29 +87,32 @@ __export(src_exports, {
   boolean: () => boolean,
   bucket: () => bucket,
   buildProvider: () => buildProvider,
+  dec: () => dec,
   defineEgress: () => defineEgress,
   defineError: () => defineError,
   defineFlags: () => defineFlags,
-  defineJob: () => defineJob,
   defineMiddleware: () => defineMiddleware,
   defineNotifications: () => defineNotifications,
   defineSchema: () => defineSchema,
   defineStorage: () => defineStorage,
   defineTestUsers: () => defineTestUsers,
-  defineWebhook: () => defineWebhook,
   defineWorker: () => defineWorker,
   documents: () => documents,
   entitlementFor: () => entitlementFor,
   enumType: () => enumType,
   flag: () => flag,
   getErrorRegistry: () => getErrorRegistry,
+  getJobConfig: () => getJobConfig,
   getRoutes: () => getRoutes,
+  getWebhookConfig: () => getWebhookConfig,
+  inc: () => inc,
   integer: () => integer,
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
   makeEnvDts: () => makeEnvDts,
   makePurchasesDts: () => makePurchasesDts,
   makeTypedDB: () => makeTypedDB,
+  now: () => now,
   numeric: () => numeric,
   parseFileSizeLimit: () => parseFileSizeLimit,
   policy: () => policy,
@@ -124,6 +132,416 @@ module.exports = __toCommonJS(src_exports);
 
 // src/runtime.ts
 var import_node_async_hooks = require("async_hooks");
+
+// src/db/tx-plan.ts
+var TxRefError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TxRefError";
+  }
+};
+var TxPlanError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TxPlanError";
+  }
+};
+var EXPR = /* @__PURE__ */ Symbol.for("palbase.tx.expr");
+var REF = /* @__PURE__ */ Symbol.for("palbase.tx.ref");
+var ROW = /* @__PURE__ */ Symbol.for("palbase.tx.row");
+var ROWS = /* @__PURE__ */ Symbol.for("palbase.tx.rows");
+var TRAPPED_PROPS = [
+  "then",
+  "valueOf",
+  "toString",
+  "toJSON",
+  Symbol.toPrimitive
+];
+function trap(prop, what, hint) {
+  const name = typeof prop === "symbol" ? prop.description ?? String(prop) : prop;
+  throw new TxRefError(
+    `${what} was used as a value (via \`${name}\`). Nothing in a transaction callback has run yet, so there is no value to read. ${hint}`
+  );
+}
+function now() {
+  return makeExpr({ fn: "now" });
+}
+function inc(by) {
+  assertFiniteNumber(by, "inc");
+  return makeExpr({ fn: "inc", by });
+}
+function dec(by) {
+  assertFiniteNumber(by, "dec");
+  return makeExpr({ fn: "dec", by });
+}
+function assertFiniteNumber(by, fn) {
+  if (typeof by !== "number" || !Number.isFinite(by)) {
+    throw new TxPlanError(`${fn}() needs a finite number, got ${String(by)}`);
+  }
+}
+function makeExpr(expr) {
+  return new Proxy(
+    { [EXPR]: expr },
+    {
+      get(target, prop) {
+        if (prop === EXPR) return target[EXPR];
+        if (TRAPPED_PROPS.includes(prop)) {
+          trap(prop, "A plan expression", "Write it into an operation instead.");
+        }
+        return void 0;
+      }
+    }
+  );
+}
+function makeRef(op, field) {
+  const target = { [REF]: { op, field } };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === REF) return t[REF];
+      if (TRAPPED_PROPS.includes(prop)) {
+        trap(
+          prop,
+          `\`${field}\` of a row this transaction has not written yet`,
+          "Pass it to another operation in the same plan, or return it from the callback and read it after `transaction()` resolves."
+        );
+      }
+      return void 0;
+    }
+  });
+}
+function makeRowHandle(op) {
+  const target = { [ROW]: op };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === ROW) return t[ROW];
+      if (TRAPPED_PROPS.includes(prop)) {
+        trap(
+          prop,
+          "A row this transaction has not written yet",
+          "Read one of its columns to reference it, or return the row from the callback and read it after `transaction()` resolves."
+        );
+      }
+      if (typeof prop === "symbol") return void 0;
+      return makeRef(op, prop);
+    }
+  });
+}
+function refDescriptor(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const d = v[REF];
+  return isRefDescriptor(d) ? d : null;
+}
+function isRefDescriptor(d) {
+  return typeof d === "object" && d !== null && typeof d.op === "number" && typeof d.field === "string";
+}
+function rowOpIndex(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const op = v[ROW];
+  return typeof op === "number" ? op : null;
+}
+function exprOf(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const e = v[EXPR];
+  return typeof e === "object" && e !== null ? e : null;
+}
+function isRowsHandle(v) {
+  return typeof v === "object" && v !== null && v[ROWS] !== void 0;
+}
+function encodeValue(value, column, allowColumnExpr) {
+  const ref = refDescriptor(value);
+  if (ref) return { $ref: { op: ref.op, field: ref.field } };
+  const expr = exprOf(value);
+  if (expr) {
+    if (expr.fn !== "now" && !allowColumnExpr) {
+      throw new TxPlanError(
+        `\`${column}\`: ${expr.fn}() reads the column's current value, so it is only valid in updateWhere(where, set).`
+      );
+    }
+    return { $expr: expr };
+  }
+  if (rowOpIndex(value) !== null) {
+    throw new TxPlanError(
+      `\`${column}\`: a row handle is not a value. Read the column you meant (e.g. \`row.id\`).`
+    );
+  }
+  if (isRowsHandle(value)) {
+    throw new TxPlanError(
+      `\`${column}\`: an operation result is not a value. Declare an expectation first (\`.expectOne(err)\`) and read a column from the row.`
+    );
+  }
+  assertNoNestedHandles(value, column);
+  return value;
+}
+function assertNoNestedHandles(value, column) {
+  if (typeof value !== "object" || value === null) return;
+  if (value instanceof Date) return;
+  if (refDescriptor(value) || exprOf(value) || rowOpIndex(value) !== null || isRowsHandle(value)) {
+    throw new TxPlanError(
+      `\`${column}\`: a plan handle is nested inside a value. The server would store it as literal JSON, not resolve it. Put the reference directly in the column.`
+    );
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) assertNoNestedHandles(item, column);
+    return;
+  }
+  for (const item of Object.values(value)) {
+    assertNoNestedHandles(item, column);
+  }
+}
+function encodeMap(map, allowColumnExpr) {
+  const out = {};
+  for (const key of Object.keys(map).sort()) {
+    const value = map[key];
+    if (value === void 0) continue;
+    out[key] = encodeValue(value, key, allowColumnExpr);
+  }
+  return out;
+}
+var SKIPPED_OP = -1;
+var TxRowsImpl = class {
+  constructor(builder, opIndex, what) {
+    this.builder = builder;
+    this.opIndex = opIndex;
+    this.what = what;
+  }
+  builder;
+  opIndex;
+  what;
+  // Present so `isRowsHandle` recognises the object; never read for its value.
+  [ROWS] = true;
+  guarded = false;
+  // The type-level `await` guard made real: TS rejects `await rows` at compile
+  // time, and reaching this means someone called `.then(...)` by hand.
+  then() {
+    throw new TxRefError(
+      `${this.what} cannot be awaited: a transaction callback builds a plan, it does not run statements. Remove the \`await\`.`
+    );
+  }
+  expectOne(error) {
+    this.declareGuard("one", 1, error);
+    if (this.opIndex === SKIPPED_OP) throw error;
+    return makeRowHandle(this.opIndex);
+  }
+  expectNone(error) {
+    this.declareGuard("none", 0, error);
+  }
+  expectAtLeast(n, error) {
+    assertGuardCount(n, "expectAtLeast");
+    this.declareGuard("atLeast", n, error);
+    if (this.opIndex === SKIPPED_OP && n > 0) throw error;
+  }
+  expectAtMost(n, error) {
+    assertGuardCount(n, "expectAtMost");
+    this.declareGuard("atMost", n, error);
+  }
+  declareGuard(kind, n, error) {
+    if (!(error instanceof Error)) {
+      throw new TxPlanError(
+        `${this.what}: an expectation needs the Error to throw when it does not hold (e.g. \`.expect\u2026(new Conflict("already accepted"))\`).`
+      );
+    }
+    if (this.guarded) {
+      throw new TxPlanError(
+        `${this.what} already has an expectation. One operation carries one expectation; declare the second one on its own operation.`
+      );
+    }
+    this.guarded = true;
+    if (this.opIndex === SKIPPED_OP) return;
+    this.builder.attachGuard(this.opIndex, kind, n, error);
+  }
+};
+function assertGuardCount(n, fn) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TxPlanError(`${fn}(n) needs a non-negative integer, got ${String(n)}`);
+  }
+}
+var MAX_OPS = 1e3;
+var MAX_ROWS = 5e3;
+var TxPlanBuilder = class {
+  ops = [];
+  /** Errors handed to expectations, indexed by the `slot` the server echoes. */
+  slots = [];
+  /** The table surface handed to the callback. Untyped here; the public
+   * `transaction()` signatures put the schema types on top. */
+  table(name) {
+    return {
+      insert: (values) => {
+        const encoded = encodeMap(values, false);
+        if (Object.keys(encoded).length === 0) {
+          throw new TxPlanError(`${name}.insert() needs at least one column`);
+        }
+        return this.push({ op: "insert", table: name, values: encoded }, `${name}.insert()`);
+      },
+      insertMany: (rows) => {
+        if (rows.length === 0) {
+          return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
+        }
+        if (rows.length > MAX_ROWS) {
+          throw new TxPlanError(
+            `${name}.insertMany() has ${rows.length} rows; the limit is ${MAX_ROWS}. Split the write across requests.`
+          );
+        }
+        const encoded = rows.map((row) => encodeMap(row, false));
+        assertUniformRows(encoded, name);
+        return this.push({ op: "insertMany", table: name, rows: encoded }, `${name}.insertMany()`);
+      },
+      updateWhere: (where, set) => {
+        const encodedWhere = encodeMap(where, false);
+        const encodedSet = encodeMap(set, true);
+        if (Object.keys(encodedWhere).length === 0) {
+          throw new TxPlanError(
+            `${name}.updateWhere() needs a filter. An update with no filter rewrites the whole table.`
+          );
+        }
+        if (Object.keys(encodedSet).length === 0) {
+          throw new TxPlanError(`${name}.updateWhere() needs at least one column to set`);
+        }
+        return this.push(
+          { op: "update", table: name, set: encodedSet, where: encodedWhere },
+          `${name}.updateWhere()`
+        );
+      },
+      deleteWhere: (where) => {
+        const encodedWhere = encodeMap(where, false);
+        if (Object.keys(encodedWhere).length === 0) {
+          throw new TxPlanError(
+            `${name}.deleteWhere() needs a filter. A delete with no filter empties the table.`
+          );
+        }
+        return this.push(
+          { op: "delete", table: name, where: encodedWhere },
+          `${name}.deleteWhere()`
+        );
+      },
+      select: (where, options) => {
+        const op = { op: "select", table: name };
+        const encodedWhere = encodeMap(where ?? {}, false);
+        if (Object.keys(encodedWhere).length > 0) op.where = encodedWhere;
+        if (options?.limit !== void 0) {
+          if (!Number.isInteger(options.limit) || options.limit < 0) {
+            throw new TxPlanError(
+              `${name}.select(): limit needs a non-negative integer, got ${String(options.limit)}`
+            );
+          }
+          op.limit = options.limit;
+        }
+        if (options?.lock !== void 0) op.lock = options.lock;
+        return this.push(op, `${name}.select()`);
+      }
+    };
+  }
+  push(op, what) {
+    if (this.ops.length >= MAX_OPS) {
+      throw new TxPlanError(
+        `this transaction has ${MAX_OPS} operations, which is the limit. Use insertMany() for bulk writes, or split the work across requests.`
+      );
+    }
+    const index = this.ops.length;
+    this.ops.push(op);
+    return new TxRowsImpl(this, index, what);
+  }
+  /** Attach an expectation to an op and record its error in the slot table. */
+  attachGuard(opIndex, kind, n, error) {
+    const op = this.ops[opIndex];
+    if (!op) throw new TxPlanError(`internal: expectation on unknown operation ${opIndex}`);
+    const slot = this.slots.length;
+    this.slots.push(error);
+    op.guard = { kind, n, slot };
+  }
+  /** The serialisable plan. Empty when the callback described no writes. */
+  body() {
+    return { ops: this.ops };
+  }
+  /** The error the server's `slot` selects, or `null` when it names one this
+   * plan never declared (a server/client disagreement, not a tenant error). */
+  errorForSlot(slot) {
+    return this.slots[slot] ?? null;
+  }
+};
+function assertUniformRows(rows, table) {
+  const first = rows[0];
+  if (!first) return;
+  const want = Object.keys(first);
+  const wantKey = want.join(",");
+  for (let i = 1; i < rows.length; i++) {
+    const got = Object.keys(rows[i]);
+    if (got.join(",") !== wantKey) {
+      throw new TxPlanError(
+        `${table}.insertMany(): every row must set the same columns. Row 0 sets [${want.join(", ")}] but row ${i} sets [${got.join(", ")}]. (A property set to \`undefined\` counts as absent \u2014 use \`null\`.)`
+      );
+    }
+  }
+}
+function materializeResult(value, results) {
+  const ref = refDescriptor(value);
+  if (ref) {
+    const row = rowOf(results, ref.op, `\`${ref.field}\``);
+    if (!(ref.field in row)) {
+      throw new TxPlanError(
+        `the transaction's operation ${ref.op} returned no column \`${ref.field}\`.`
+      );
+    }
+    return row[ref.field];
+  }
+  const rowOp = rowOpIndex(value);
+  if (rowOp !== null) return rowOf(results, rowOp, "a row");
+  if (isRowsHandle(value)) {
+    throw new TxPlanError(
+      "an operation result cannot be returned from a transaction callback: its row count is not known until the plan runs. Declare an expectation (`.expectOne(err)`) and return the row, or a column of it."
+    );
+  }
+  if (Array.isArray(value)) return value.map((item) => materializeResult(item, results));
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) out[key] = materializeResult(item, results);
+    return out;
+  }
+  return value;
+}
+function rowOf(results, opIndex, what) {
+  const result = results[opIndex];
+  if (!result) {
+    throw new TxPlanError(
+      `the transaction returned no result for operation ${opIndex}, so ${what} cannot be read.`
+    );
+  }
+  const row = result.rows[0];
+  if (!row) {
+    throw new TxPlanError(
+      `the transaction's operation ${opIndex} returned no row, so ${what} cannot be read.`
+    );
+  }
+  return row;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+async function runTxPlan(transport, tables, builder, fn) {
+  const returned = fn({ tables });
+  const body = builder.body();
+  if (body.ops.length === 0) {
+    return materializeResult(returned, []);
+  }
+  let response;
+  try {
+    response = await transport.txPlan(body);
+  } catch (err) {
+    throw translateRejection(err, builder);
+  }
+  return materializeResult(returned, response.results);
+}
+function translateRejection(err, builder) {
+  if (typeof err !== "object" || err === null) return err;
+  const rejection = err;
+  if (rejection.error_code !== "tx_guard_failed" || typeof rejection.slot !== "number") {
+    return err;
+  }
+  return builder.errorForSlot(rejection.slot) ?? err;
+}
+
+// src/runtime.ts
 var __requestALS = new import_node_async_hooks.AsyncLocalStorage();
 var runtime = null;
 function __setRuntime(services) {
@@ -184,10 +602,23 @@ function makeTypedSurface(raw2) {
   return Object.assign(ops, {
     tables: makeTablesAccessor(() => raw2),
     transaction(fn) {
-      return raw2.transaction((rawTx) => fn({ tables: makeTablesAccessor(() => rawTx) }));
+      const builder = new TxPlanBuilder();
+      return runTxPlan(raw2, makeTxTablesAccessor(builder), builder, fn);
     }
   });
 }
+function makeTxTablesAccessor(builder) {
+  const tablesProxy = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        return builder.table(prop);
+      }
+    }
+  );
+  return tablesProxy;
+}
 var Database = Object.assign(makeTypedSurface(rawDatabase), {
   /**
    * Lazily resolve the runtime's service-role sibling on each call. We do NOT
@@ -782,19 +1213,29 @@ function makeTypedTable(name, raw2) {
   };
 }
 function makeTypedDB(schema, raw2) {
-  function buildTables(client) {
-    const tables = {};
-    for (const key of Object.keys(schema.tables)) {
-      const tableDef = schema.tables[key];
-      if (tableDef !== void 0) {
-        tables[key] = makeTypedTable(tableDef.name, client);
-      }
+  const tables = {};
+  for (const key of Object.keys(schema.tables)) {
+    const tableDef = schema.tables[key];
+    if (tableDef !== void 0) {
+      tables[key] = makeTypedTable(tableDef.name, raw2);
     }
-    return tables;
   }
   const result = {
-    tables: buildTables(raw2),
-    transaction: (fn) => raw2.transaction((rawTx) => fn({ tables: buildTables(rawTx) }))
+    tables,
+    transaction(fn) {
+      const builder = new TxPlanBuilder();
+      const planTables = {};
+      for (const key of Object.keys(schema.tables)) {
+        const tableDef = schema.tables[key];
+        if (tableDef !== void 0) planTables[key] = builder.table(tableDef.name);
+      }
+      return runTxPlan(
+        raw2,
+        planTables,
+        builder,
+        fn
+      );
+    }
   };
   return result;
 }
@@ -1133,12 +1574,12 @@ var E164_RE = /^\+[1-9]\d{1,14}$/;
 var OTP_LENGTH = 6;
 var OTP_RE = /^\d{6}$/;
 var MIN_PASSWORD_LENGTH = 8;
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function normalizeSeed(seed, userName) {
   if (seed === void 0) return {};
-  if (!isPlainObject(seed)) {
+  if (!isPlainObject2(seed)) {
     throw new Error(`testUser ${JSON.stringify(userName)}: seed must be { <table>: [ {...} ] }`);
   }
   const out = {};
@@ -1154,7 +1595,7 @@ function normalizeSeed(seed, userName) {
       );
     }
     for (const row of rows) {
-      if (!isPlainObject(row)) {
+      if (!isPlainObject2(row)) {
         throw new Error(
           `testUser ${JSON.stringify(userName)}: every row in seed.${table} must be an object`
         );
@@ -1165,7 +1606,7 @@ function normalizeSeed(seed, userName) {
   return out;
 }
 function testUser(opts = {}) {
-  if (!isPlainObject(opts)) {
+  if (!isPlainObject2(opts)) {
     throw new Error("testUser() expects { email?, password?, phone?, otp?, seed? }");
   }
   const hasEmail = opts.email !== void 0;
@@ -1215,7 +1656,7 @@ function testUser(opts = {}) {
   return { email, password, phone, otp, seed: normalizeSeed(opts.seed, email ?? "<template>") };
 }
 function defineTestUsers(input) {
-  if (!isPlainObject(input) || !isPlainObject(input.users)) {
+  if (!isPlainObject2(input) || !isPlainObject2(input.users)) {
     throw new Error("defineTestUsers expects { users: { <name>: testUser({...}) } }");
   }
   const users = {};
@@ -1331,6 +1772,12 @@ function defineFlags(input) {
 var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
 function Controller(basePath, options = {}) {
   return function(ctor) {
+    const normalized = basePath.replace(/\/+$/, "");
+    if (normalized === "/webhooks" || normalized.startsWith("/webhooks/")) {
+      throw new Error(
+        `@Controller("${basePath}") uses the reserved /webhooks path \u2014 inbound webhooks are served there`
+      );
+    }
     const carrier = ctor;
     const meta = {
       __palbase: "controller",
@@ -1718,12 +2165,81 @@ function defineWorker(config) {
   };
 }
 
+// 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.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
-var VALID_JOB_NAME = /^[a-zA-Z0-9_-]+$/;
-var MAX_TIMEOUT_SECONDS = 300;
-var JOB_DEFAULTS = {
-  timeout: 30
-};
 function validateCronExpression(expression) {
   const trimmed = expression.trim();
   if (trimmed === "") {
@@ -1789,115 +2305,56 @@ function validateCronField(field, name, min, max) {
   }
   return null;
 }
-function defineJob(config) {
-  if (!config.name || config.name.trim() === "") {
-    throw new Error("Job name is required");
-  }
-  if (!VALID_JOB_NAME.test(config.name)) {
-    throw new Error(
-      `Invalid job name "${config.name}": must match [a-zA-Z0-9_-]+`
-    );
-  }
-  if (!config.schedule || config.schedule.trim() === "") {
-    throw new Error("Job schedule is required");
-  }
-  const cronError = validateCronExpression(config.schedule);
-  if (cronError !== null) {
-    throw new Error(cronError);
-  }
-  if (!config.handler) {
-    throw new Error("Job handler is required");
-  }
-  if (config.timeout !== void 0 && config.timeout <= 0) {
-    throw new Error("Job timeout must be a positive number");
-  }
-  if (config.timeout !== void 0 && !Number.isInteger(config.timeout)) {
-    throw new Error("Job timeout must be an integer");
-  }
-  if (config.timeout !== void 0 && config.timeout > MAX_TIMEOUT_SECONDS) {
-    throw new Error(
-      `Job timeout ${config.timeout}s exceeds maximum ${MAX_TIMEOUT_SECONDS}s`
-    );
-  }
-  return {
-    name: config.name,
-    schedule: config.schedule.trim(),
-    timeout: config.timeout ?? JOB_DEFAULTS.timeout,
-    handler: config.handler
+
+// src/decorators/job.ts
+var DEFAULT_TIMEOUT_SECONDS = 30;
+var MAX_TIMEOUT_SECONDS = 300;
+var JOB_META = /* @__PURE__ */ Symbol.for("palbase.backend.jobMeta");
+function Job(options) {
+  return function(ctor) {
+    const carrier = ctor;
+    Object.defineProperty(carrier, JOB_META, {
+      value: options,
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+    Object.defineProperty(carrier, "__palbase", {
+      value: "job",
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+    return ctor;
   };
 }
-
-// src/webhook.ts
-var VALID_WEBHOOK_PATH = /^\/[a-zA-Z0-9/_-]+$/;
-function defineWebhook(config) {
-  if ("provider" in config) {
-    return validateProviderWebhook(config);
-  }
-  return validateCustomWebhook(config);
-}
-function validateProviderWebhook(config) {
-  if (!config.provider) {
-    throw new Error("Webhook provider is required");
-  }
-  const validProviders = [
-    "stripe",
-    "github",
-    "twilio",
-    "sendgrid",
-    "slack",
-    "discord",
-    "livekit"
-  ];
-  if (!validProviders.includes(config.provider)) {
+function getJobConfig(ctor) {
+  const meta = ctor[JOB_META];
+  if (!meta) {
     throw new Error(
-      `Invalid webhook provider "${config.provider}": must be one of ${validProviders.join(", ")}`
+      `getJobConfig on a class with no @Job decorator (${ctor.name ?? "anonymous"})`
     );
   }
-  if (!config.secret) {
-    throw new Error('Webhook secret is required (use { env: "SECRET_NAME" })');
+  if (!meta.schedule || meta.schedule.trim() === "") {
+    throw new Error("@Job requires a `schedule` cron expression");
   }
-  if (typeof config.secret.env !== "string" || config.secret.env.trim() === "") {
-    throw new Error("Webhook secret env name must be a non-empty string");
+  const cronError = validateCronExpression(meta.schedule);
+  if (cronError) {
+    throw new Error(`@Job has an invalid cron schedule: ${cronError}`);
   }
-  if (!config.events || Object.keys(config.events).length === 0) {
-    throw new Error("At least one event handler is required");
+  const timeout = meta.timeout ?? DEFAULT_TIMEOUT_SECONDS;
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    throw new Error("@Job `timeout` must be a positive whole number of seconds");
   }
-  for (const [eventName, handler] of Object.entries(config.events)) {
-    if (typeof handler !== "function") {
-      throw new Error(`Event handler for "${eventName}" must be a function`);
-    }
+  if (timeout > MAX_TIMEOUT_SECONDS) {
+    throw new Error(`@Job \`timeout\` exceeds the ${MAX_TIMEOUT_SECONDS}s sandbox ceiling`);
   }
-  return {
-    type: "provider",
-    provider: config.provider,
-    secret: config.secret,
-    events: config.events
-  };
-}
-function validateCustomWebhook(config) {
-  if (!config.path || config.path.trim() === "") {
-    throw new Error("Webhook path is required");
-  }
-  if (!VALID_WEBHOOK_PATH.test(config.path)) {
-    throw new Error(
-      `Invalid webhook path "${config.path}": must start with / and contain only alphanumeric, hyphen, underscore, slash`
-    );
+  const instance = new ctor();
+  if (typeof instance.run !== "function") {
+    throw new Error("@Job class must declare an async run() method");
   }
-  if (!config.handler) {
-    throw new Error("Webhook handler is required");
-  }
-  if (typeof config.handler !== "function") {
-    throw new Error("Webhook handler must be a function");
-  }
-  if (config.verify !== void 0 && typeof config.verify !== "function") {
-    throw new Error("Webhook verify must be a function");
-  }
-  return {
-    type: "custom",
-    path: config.path,
-    verify: config.verify,
-    handler: config.handler
-  };
+  const run = instance.run.bind(instance);
+  return { schedule: meta.schedule, timeout, handler: run };
 }
 
 // src/resource.ts
@@ -2002,10 +2459,12 @@ var import_zod2 = require("zod");
   Get,
   Headers,
   HttpError,
+  Job,
   Log,
   NOTIFICATIONS_CONFIG_KIND,
   NotFound,
   Notifications,
+  On,
   OptionalUser,
   PALBASE_EXTENSIONS,
   PROVIDER_CATALOG,
@@ -2031,10 +2490,13 @@ var import_zod2 = require("zod");
   TEST_USERS_CONFIG_KIND,
   TooManyRequests,
   TraceId,
+  TxPlanError,
+  TxRefError,
   Unauthorized,
   Upload,
   UploadedObject,
   User,
+  Webhook,
   __getRuntime,
   __registerResource,
   __requestALS,
@@ -2047,29 +2509,32 @@ var import_zod2 = require("zod");
   boolean,
   bucket,
   buildProvider,
+  dec,
   defineEgress,
   defineError,
   defineFlags,
-  defineJob,
   defineMiddleware,
   defineNotifications,
   defineSchema,
   defineStorage,
   defineTestUsers,
-  defineWebhook,
   defineWorker,
   documents,
   entitlementFor,
   enumType,
   flag,
   getErrorRegistry,
+  getJobConfig,
   getRoutes,
+  getWebhookConfig,
+  inc,
   integer,
   isPalbaseExtension,
   jsonb,
   makeEnvDts,
   makePurchasesDts,
   makeTypedDB,
+  now,
   numeric,
   parseFileSizeLimit,
   policy,