@palbase/backend 10.2.0 → 11.0.0

package/dist/index.cjs

@@ -49,6 +49,7 @@ __export(src_exports, {
   Patch: () => Patch,
   PolicyBuilder: () => PolicyBuilder,
   Post: () => Post,
+  Purchases: () => Purchases,
   Put: () => Put,
   Query: () => Query,
   QueryParams: () => QueryParams,
@@ -57,12 +58,16 @@ __export(src_exports, {
   Realtime: () => Realtime,
   Req: () => Req,
   RequestId: () => RequestId,
+  RequireEntitlement: () => RequireEntitlement,
   Resource: () => Resource,
   STORAGE_CONFIG_KIND: () => STORAGE_CONFIG_KIND,
+  Spend: () => Spend,
   Storage: () => Storage,
   TEST_USERS_CONFIG_KIND: () => TEST_USERS_CONFIG_KIND,
   TooManyRequests: () => TooManyRequests,
   TraceId: () => TraceId,
+  TxPlanError: () => TxPlanError,
+  TxRefError: () => TxRefError,
   Unauthorized: () => Unauthorized,
   Upload: () => Upload,
   UploadedObject: () => UploadedObject,
@@ -79,6 +84,7 @@ __export(src_exports, {
   boolean: () => boolean,
   bucket: () => bucket,
   buildProvider: () => buildProvider,
+  dec: () => dec,
   defineEgress: () => defineEgress,
   defineError: () => defineError,
   defineFlags: () => defineFlags,
@@ -91,21 +97,26 @@ __export(src_exports, {
   defineWebhook: () => defineWebhook,
   defineWorker: () => defineWorker,
   documents: () => documents,
+  entitlementFor: () => entitlementFor,
   enumType: () => enumType,
   flag: () => flag,
   getErrorRegistry: () => getErrorRegistry,
   getRoutes: () => getRoutes,
+  inc: () => inc,
   integer: () => integer,
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
   makeEnvDts: () => makeEnvDts,
+  makePurchasesDts: () => makePurchasesDts,
   makeTypedDB: () => makeTypedDB,
+  now: () => now,
   numeric: () => numeric,
   parseFileSizeLimit: () => parseFileSizeLimit,
   policy: () => policy,
   raw: () => raw,
   recordThrows: () => recordThrows,
   reservedSecretKey: () => reservedSecretKey,
+  spendFor: () => spendFor,
   storage: () => storage,
   testUser: () => testUser,
   text: () => text,
@@ -118,6 +129,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) {
@@ -178,10 +599,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
@@ -200,6 +634,7 @@ var Cache = makeServiceProxy("Cache");
 var Queue = makeServiceProxy("Queue");
 var Log = makeServiceProxy("Log");
 var Notifications = makeServiceProxy("Notifications");
+var Purchases = makeServiceProxy("Purchases");
 var rawFlags = makeServiceProxy("Flags");
 var Flags = Object.assign(
   {
@@ -230,6 +665,276 @@ var Flags = Object.assign(
 );
 var Realtime = makeServiceProxy("Realtime");
 
+// src/errors.ts
+var HttpError = class extends Error {
+  status;
+  error;
+  errorDescription;
+  data;
+  constructor(status, error, errorDescription, data) {
+    super(errorDescription);
+    this.name = "HttpError";
+    this.status = status;
+    this.error = error;
+    this.errorDescription = errorDescription;
+    if (data !== void 0) {
+      this.data = data;
+    }
+  }
+  /**
+   * Serialize to the standard Palbase error response format.
+   * The `requestId` is injected by the runtime layer from the request context.
+   * When called without arguments (e.g. JSON.stringify), request_id is omitted.
+   * When `data` is set, it is appended as a strict-superset field.
+   */
+  toJSON(requestId) {
+    const result = {
+      error: this.error,
+      error_description: this.errorDescription,
+      status: this.status
+    };
+    if (requestId) {
+      result.request_id = requestId;
+    }
+    if (this.data !== void 0) {
+      result.data = this.data;
+    }
+    return result;
+  }
+};
+var PalError = class extends HttpError {
+  constructor(status, code, description, data) {
+    super(status, code, description, data);
+    this.name = "PalError";
+  }
+};
+var NamedHttpError = class extends HttpError {
+  constructor(status, defaultCode, name, message, code, data) {
+    super(status, code ?? defaultCode, message ?? defaultMessage(name), data);
+    this.name = name;
+  }
+};
+function defaultMessage(name) {
+  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
+}
+var BadRequest = class extends NamedHttpError {
+  constructor(data, message) {
+    super(400, "bad_request", "BadRequest", message, void 0, data);
+  }
+};
+var Unauthorized = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(401, "unauthorized", "Unauthorized", message, code, data);
+  }
+};
+var Forbidden = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(403, "forbidden", "Forbidden", message, code, data);
+  }
+};
+var NotFound = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(404, "not_found", "NotFound", message, code, data);
+  }
+};
+var Conflict = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(409, "conflict", "Conflict", message, code, data);
+  }
+};
+var TooManyRequests = class extends NamedHttpError {
+  constructor(data, message) {
+    super(429, "too_many_requests", "TooManyRequests", message, void 0, data);
+  }
+};
+
+// src/purchases/errors.ts
+function asPalstoreError(err) {
+  if (!(err instanceof Error)) return null;
+  const e = err;
+  if (typeof e.code !== "string" || typeof e.status !== "number") return null;
+  return { code: e.code, status: e.status, message: e.message };
+}
+function toHttpError(err) {
+  if (err instanceof HttpError) return err;
+  const p = asPalstoreError(err);
+  if (!p) return err;
+  switch (p.code) {
+    case "entitlement_required": {
+      const entitlement = err.entitlement ?? null;
+      return new PalError(403, "entitlement_required", p.message, { entitlement });
+    }
+    case "quota_exceeded":
+    case "credit_insufficient": {
+      const state = err.state;
+      return new PalError(429, p.code, p.message, state);
+    }
+    default:
+      return err;
+  }
+}
+
+// src/purchases/registry.ts
+var ENTITLEMENTS = /* @__PURE__ */ Symbol.for("palbase.backend.purchases.entitlements");
+var SPENDS = /* @__PURE__ */ Symbol.for("palbase.backend.purchases.spends");
+function carrierOf(target) {
+  return typeof target === "function" ? target : target.constructor ?? target;
+}
+function own(carrier, slot) {
+  if (!Object.prototype.hasOwnProperty.call(carrier, slot)) {
+    carrier[slot] = {};
+  }
+  return carrier[slot];
+}
+function recordEntitlement(target, fnName, key) {
+  own(carrierOf(target), ENTITLEMENTS)[fnName] = key;
+}
+function recordSpend(target, fnName, meta) {
+  own(carrierOf(target), SPENDS)[fnName] = meta;
+}
+function entitlementFor(ctor, fnName) {
+  return carrierOf(ctor)[ENTITLEMENTS]?.[fnName];
+}
+function spendFor(ctor, fnName) {
+  return carrierOf(ctor)[SPENDS]?.[fnName];
+}
+
+// src/purchases/subject.ts
+var subjectByRequest = /* @__PURE__ */ new WeakMap();
+function storeEnv() {
+  return process.env.PALSTORE_STORE_ENV === "sandbox" ? "sandbox" : "production";
+}
+async function currentSubjectId() {
+  const store = __requestALS.getStore();
+  if (!store) {
+    throw new Error(
+      "Purchases decorators used outside a request scope. @RequireEntitlement/@Spend resolve the subject from the request's authenticated user, so they only work inside an endpoint handler."
+    );
+  }
+  const memoized = subjectByRequest.get(store);
+  if (memoized) return memoized;
+  const userId = store.userId;
+  if (!userId) {
+    throw new Unauthorized(
+      "This endpoint requires an authenticated user: purchases entitlements and quota are per-user, and the subject is resolved from the request's identity."
+    );
+  }
+  const resolving = Purchases.resolveSubject({ userRef: userId, storeEnv: storeEnv() }).then(
+    (r) => r.subjectId
+  );
+  subjectByRequest.set(store, resolving);
+  resolving.catch(() => subjectByRequest.delete(store));
+  return resolving;
+}
+
+// src/purchases/decorators.ts
+var WRAPPED = /* @__PURE__ */ Symbol.for("palbase.backend.purchases.wrapped");
+function idempotencyKeyFor(key) {
+  const store = __requestALS.getStore();
+  const base = store?.idempotencyKey || store?.requestId;
+  if (!base) {
+    throw new Error(
+      "@Spend needs a request-scoped idempotency key, and the runtime supplied neither an Idempotency-Key header nor a request id. Spending without one would let a retried request charge the user twice."
+    );
+  }
+  return `${base}:${key}`;
+}
+function ensureWrapper(target, fnName, descriptor) {
+  const original = descriptor.value;
+  if (typeof original !== "function") {
+    throw new Error(
+      `@RequireEntitlement/@Spend can only decorate a method; "${fnName}" is not one.`
+    );
+  }
+  if (original[WRAPPED]) return;
+  const wrapper = async function(...args) {
+    const ctor = this.constructor;
+    const entitlement = entitlementFor(ctor, fnName);
+    const spend = spendFor(ctor, fnName);
+    let subjectId;
+    try {
+      subjectId = await currentSubjectId();
+    } catch (err) {
+      throw toHttpError(err);
+    }
+    if (entitlement !== void 0) {
+      try {
+        await Purchases.require(subjectId, entitlement);
+      } catch (err) {
+        throw toHttpError(err);
+      }
+    }
+    if (spend === void 0) {
+      return original.apply(this, args);
+    }
+    let handlerFailure;
+    try {
+      return await Purchases.withSpend(
+        subjectId,
+        spend.key,
+        { count: spend.count, idempotencyKey: idempotencyKeyFor(spend.key) },
+        async () => {
+          try {
+            return await original.apply(this, args);
+          } catch (err) {
+            handlerFailure = { err };
+            throw err;
+          }
+        }
+      );
+    } catch (err) {
+      if (handlerFailure !== void 0 && handlerFailure.err === err) throw err;
+      throw toHttpError(err);
+    }
+  };
+  wrapper[WRAPPED] = true;
+  descriptor.value = wrapper;
+}
+function RequireEntitlement(key) {
+  return function(target, propertyKey, descriptor) {
+    const fnName = String(propertyKey);
+    recordEntitlement(target, fnName, key);
+    ensureWrapper(target, fnName, descriptor);
+  };
+}
+function Spend(key) {
+  return function(target, propertyKey, descriptor) {
+    const fnName = String(propertyKey);
+    recordSpend(target, fnName, { key, count: 1 });
+    ensureWrapper(target, fnName, descriptor);
+  };
+}
+
+// src/purchases/keys-gen.ts
+function liveKeys(entries) {
+  return Object.entries(entries ?? {}).filter(([, def]) => def?.removed !== true).map(([key]) => key).sort();
+}
+function memberName(key) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}
+function members(keys) {
+  if (keys.length === 0) return "";
+  return `
+${keys.map((k) => `    ${memberName(k)}: true;`).join("\n")}
+  `;
+}
+function makePurchasesDts(manifest) {
+  const entitlements = liveKeys(manifest.entitlements);
+  const limits = liveKeys({ ...manifest.limits, ...manifest.credits });
+  return `// palbase-purchases.d.ts \u2014 GENERATED by @palbase/backend. Do not edit.
+// Source: the project's palstore catalog revision.
+
+declare module "@palbase/backend/purchases" {
+  interface Entitlements {${members(entitlements)}}
+
+  interface Limits {${members(limits)}}
+}
+
+export {};
+`;
+}
+
 // src/db/policy.ts
 var PolicyBuilder = class {
   _def;
@@ -505,19 +1210,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;
 }
@@ -631,7 +1346,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 serve\` / deploy.
+// Regenerated from db/schema.ts on every \`palbase db types\` / deploy.
 // Augments the @palbase/backend/env \`Tables\` interface so \`Database.tables.*\`
 // is typed with no import and no generic.
 
@@ -856,12 +1571,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 = {};
@@ -877,7 +1592,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`
         );
@@ -888,7 +1603,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;
@@ -938,7 +1653,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 = {};
@@ -1081,7 +1796,7 @@ var ROUTES = /* @__PURE__ */ Symbol.for("palbase.backend.routes");
 var PARAM_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.paramBuffer");
 var RETURN_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.returnBuffer");
 var THROWS_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.throwsBuffer");
-function carrierOf(target) {
+function carrierOf2(target) {
   const ctor = typeof target === "function" ? target : target.constructor ?? target;
   return ctor;
 }
@@ -1098,7 +1813,7 @@ function ownParamBuffer(carrier) {
   return carrier[PARAM_BUFFER];
 }
 function recordRoute(target, fnName, method, subpath, options) {
-  const carrier = carrierOf(target);
+  const carrier = carrierOf2(target);
   const routes = ownRoutes(carrier);
   const buffer = ownParamBuffer(carrier);
   const params = (buffer[fnName] ?? []).slice().sort((a, b) => a.index - b.index);
@@ -1114,7 +1829,7 @@ function recordRoute(target, fnName, method, subpath, options) {
   routes.push(route);
 }
 function recordParam(target, fnName, meta) {
-  const carrier = carrierOf(target);
+  const carrier = carrierOf2(target);
   const buffer = ownParamBuffer(carrier);
   (buffer[fnName] ??= []).push(meta);
   const routes = carrier[ROUTES];
@@ -1127,7 +1842,7 @@ function recordParam(target, fnName, meta) {
   }
 }
 function recordThrows(target, fnName, throws) {
-  const carrier = carrierOf(target);
+  const carrier = carrierOf2(target);
   const routes = carrier[ROUTES];
   const route = routes?.find((r) => r.fnName === fnName);
   if (route) {
@@ -1141,7 +1856,7 @@ function recordThrows(target, fnName, throws) {
   if (throwsBuffer) throwsBuffer[fnName] = throws;
 }
 function getRoutes(ctor) {
-  const carrier = carrierOf(ctor);
+  const carrier = carrierOf2(ctor);
   const routes = carrier[ROUTES] ?? [];
   const returnBuffer = carrier[RETURN_BUFFER];
   if (returnBuffer) {
@@ -1277,90 +1992,6 @@ function defineMiddleware(fn) {
   return fn;
 }
 
-// src/errors.ts
-var HttpError = class extends Error {
-  status;
-  error;
-  errorDescription;
-  data;
-  constructor(status, error, errorDescription, data) {
-    super(errorDescription);
-    this.name = "HttpError";
-    this.status = status;
-    this.error = error;
-    this.errorDescription = errorDescription;
-    if (data !== void 0) {
-      this.data = data;
-    }
-  }
-  /**
-   * Serialize to the standard Palbase error response format.
-   * The `requestId` is injected by the runtime layer from the request context.
-   * When called without arguments (e.g. JSON.stringify), request_id is omitted.
-   * When `data` is set, it is appended as a strict-superset field.
-   */
-  toJSON(requestId) {
-    const result = {
-      error: this.error,
-      error_description: this.errorDescription,
-      status: this.status
-    };
-    if (requestId) {
-      result.request_id = requestId;
-    }
-    if (this.data !== void 0) {
-      result.data = this.data;
-    }
-    return result;
-  }
-};
-var PalError = class extends HttpError {
-  constructor(status, code, description, data) {
-    super(status, code, description, data);
-    this.name = "PalError";
-  }
-};
-var NamedHttpError = class extends HttpError {
-  constructor(status, defaultCode, name, message, code, data) {
-    super(status, code ?? defaultCode, message ?? defaultMessage(name), data);
-    this.name = name;
-  }
-};
-function defaultMessage(name) {
-  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
-  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
-}
-var BadRequest = class extends NamedHttpError {
-  constructor(data, message) {
-    super(400, "bad_request", "BadRequest", message, void 0, data);
-  }
-};
-var Unauthorized = class extends NamedHttpError {
-  constructor(message, code, data) {
-    super(401, "unauthorized", "Unauthorized", message, code, data);
-  }
-};
-var Forbidden = class extends NamedHttpError {
-  constructor(message, code, data) {
-    super(403, "forbidden", "Forbidden", message, code, data);
-  }
-};
-var NotFound = class extends NamedHttpError {
-  constructor(message, code, data) {
-    super(404, "not_found", "NotFound", message, code, data);
-  }
-};
-var Conflict = class extends NamedHttpError {
-  constructor(message, code, data) {
-    super(409, "conflict", "Conflict", message, code, data);
-  }
-};
-var TooManyRequests = class extends NamedHttpError {
-  constructor(data, message) {
-    super(429, "too_many_requests", "TooManyRequests", message, void 0, data);
-  }
-};
-
 // src/error-registry.ts
 var import_zod_to_openapi = require("@asteasolutions/zod-to-openapi");
 var import_zod = require("zod");
@@ -1370,7 +2001,27 @@ var BUILTIN_DATA_SCHEMAS = {
   bad_request: import_zod.z.object({
     fields: import_zod.z.array(import_zod.z.object({ field: import_zod.z.string(), message: import_zod.z.string() }))
   }),
-  too_many_requests: import_zod.z.object({ retryAfter: import_zod.z.number().int() })
+  too_many_requests: import_zod.z.object({ retryAfter: import_zod.z.number().int() }),
+  // Purchases (@RequireEntitlement / @Spend). Their payloads are what make a
+  // paywall renderable on the client: WHICH entitlement was missing, and for a
+  // spend the real ceiling and reset time rather than a guessed retry delay.
+  entitlement_required: import_zod.z.object({ entitlement: import_zod.z.string().nullable() }),
+  quota_exceeded: import_zod.z.object({
+    key: import_zod.z.string(),
+    scope: import_zod.z.string(),
+    window: import_zod.z.string(),
+    used: import_zod.z.number().int(),
+    reserved: import_zod.z.number().int(),
+    max: import_zod.z.number().int(),
+    remaining: import_zod.z.number().int(),
+    resetAt: import_zod.z.string()
+  }),
+  credit_insufficient: import_zod.z.object({
+    key: import_zod.z.string(),
+    balance: import_zod.z.number().int(),
+    reserved: import_zod.z.number().int(),
+    remaining: import_zod.z.number().int()
+  })
 };
 function getErrorRegistry() {
   const g = globalThis;
@@ -1382,7 +2033,13 @@ function getErrorRegistry() {
       ["forbidden", 403, "Forbidden"],
       ["not_found", 404, "NotFound"],
       ["conflict", 409, "Conflict"],
-      ["too_many_requests", 429, "TooManyRequests"]
+      ["too_many_requests", 429, "TooManyRequests"],
+      // Thrown by the purchases decorators, so they are pre-seeded like the
+      // other built-ins: a project never declares them, but every gated or
+      // metered route must surface them as TYPED errors on the client.
+      ["entitlement_required", 403, "EntitlementRequired"],
+      ["quota_exceeded", 429, "QuotaExceeded"],
+      ["credit_insufficient", 429, "CreditInsufficient"]
     ]) {
       const dataSchema = BUILTIN_DATA_SCHEMAS[code];
       m.set(code, {
@@ -1795,6 +2452,7 @@ var import_zod2 = require("zod");
   Patch,
   PolicyBuilder,
   Post,
+  Purchases,
   Put,
   Query,
   QueryParams,
@@ -1803,12 +2461,16 @@ var import_zod2 = require("zod");
   Realtime,
   Req,
   RequestId,
+  RequireEntitlement,
   Resource,
   STORAGE_CONFIG_KIND,
+  Spend,
   Storage,
   TEST_USERS_CONFIG_KIND,
   TooManyRequests,
   TraceId,
+  TxPlanError,
+  TxRefError,
   Unauthorized,
   Upload,
   UploadedObject,
@@ -1825,6 +2487,7 @@ var import_zod2 = require("zod");
   boolean,
   bucket,
   buildProvider,
+  dec,
   defineEgress,
   defineError,
   defineFlags,
@@ -1837,21 +2500,26 @@ var import_zod2 = require("zod");
   defineWebhook,
   defineWorker,
   documents,
+  entitlementFor,
   enumType,
   flag,
   getErrorRegistry,
   getRoutes,
+  inc,
   integer,
   isPalbaseExtension,
   jsonb,
   makeEnvDts,
+  makePurchasesDts,
   makeTypedDB,
+  now,
   numeric,
   parseFileSizeLimit,
   policy,
   raw,
   recordThrows,
   reservedSecretKey,
+  spendFor,
   storage,
   testUser,
   text,