@palbase/backend 10.1.0 → 10.3.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,8 +58,10 @@ __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,
@@ -91,6 +94,7 @@ __export(src_exports, {
   defineWebhook: () => defineWebhook,
   defineWorker: () => defineWorker,
   documents: () => documents,
+  entitlementFor: () => entitlementFor,
   enumType: () => enumType,
   flag: () => flag,
   getErrorRegistry: () => getErrorRegistry,
@@ -99,6 +103,7 @@ __export(src_exports, {
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
   makeEnvDts: () => makeEnvDts,
+  makePurchasesDts: () => makePurchasesDts,
   makeTypedDB: () => makeTypedDB,
   numeric: () => numeric,
   parseFileSizeLimit: () => parseFileSizeLimit,
@@ -106,6 +111,7 @@ __export(src_exports, {
   raw: () => raw,
   recordThrows: () => recordThrows,
   reservedSecretKey: () => reservedSecretKey,
+  spendFor: () => spendFor,
   storage: () => storage,
   testUser: () => testUser,
   text: () => text,
@@ -200,6 +206,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 +237,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;
@@ -631,7 +908,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.
 
@@ -977,6 +1254,8 @@ function valueMatchesType(type, value) {
       return typeof value === "number" && Number.isFinite(value);
     case "string":
       return typeof value === "string";
+    case "json":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
   }
 }
 function flag(opts) {
@@ -984,8 +1263,8 @@ function flag(opts) {
     throw new Error("flag() expects { type, default, variants?, description? }");
   }
   const { type } = opts;
-  if (type !== "boolean" && type !== "number" && type !== "string") {
-    throw new Error(`flag type must be "boolean", "number", or "string", got ${JSON.stringify(type)}`);
+  if (type !== "boolean" && type !== "number" && type !== "string" && type !== "json") {
+    throw new Error(`flag type must be "boolean", "number", "string", or "json", got ${JSON.stringify(type)}`);
   }
   if (!valueMatchesType(type, opts.default)) {
     throw new Error(
@@ -994,7 +1273,7 @@ function flag(opts) {
   }
   let variants = null;
   if (opts.variants !== void 0) {
-    if (type !== "string") {
+    if (opts.type !== "string") {
       throw new Error(`flag variants are only valid for type "string" (got type "${type}")`);
     }
     if (!Array.isArray(opts.variants)) {
@@ -1079,7 +1358,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;
 }
@@ -1096,7 +1375,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);
@@ -1112,7 +1391,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];
@@ -1125,7 +1404,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) {
@@ -1139,7 +1418,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) {
@@ -1275,90 +1554,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");
@@ -1368,7 +1563,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;
@@ -1380,7 +1595,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, {
@@ -1793,6 +2014,7 @@ var import_zod2 = require("zod");
   Patch,
   PolicyBuilder,
   Post,
+  Purchases,
   Put,
   Query,
   QueryParams,
@@ -1801,8 +2023,10 @@ var import_zod2 = require("zod");
   Realtime,
   Req,
   RequestId,
+  RequireEntitlement,
   Resource,
   STORAGE_CONFIG_KIND,
+  Spend,
   Storage,
   TEST_USERS_CONFIG_KIND,
   TooManyRequests,
@@ -1835,6 +2059,7 @@ var import_zod2 = require("zod");
   defineWebhook,
   defineWorker,
   documents,
+  entitlementFor,
   enumType,
   flag,
   getErrorRegistry,
@@ -1843,6 +2068,7 @@ var import_zod2 = require("zod");
   isPalbaseExtension,
   jsonb,
   makeEnvDts,
+  makePurchasesDts,
   makeTypedDB,
   numeric,
   parseFileSizeLimit,
@@ -1850,6 +2076,7 @@ var import_zod2 = require("zod");
   raw,
   recordThrows,
   reservedSecretKey,
+  spendFor,
   storage,
   testUser,
   text,