@palbase/backend 11.0.0 → 12.0.1

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,
@@ -72,6 +74,7 @@ __export(src_exports, {
   Upload: () => Upload,
   UploadedObject: () => UploadedObject,
   User: () => User,
+  Webhook: () => Webhook,
   __getRuntime: () => __getRuntime,
   __registerResource: () => __registerResource,
   __requestALS: () => __requestALS,
@@ -88,20 +91,20 @@ __export(src_exports, {
   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,
@@ -1769,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",
@@ -2156,12 +2165,99 @@ 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.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
-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 === "") {
@@ -2227,115 +2323,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`
-    );
-  }
-  if (!config.handler) {
-    throw new Error("Webhook handler is required");
+  const instance = new ctor();
+  if (typeof instance.run !== "function") {
+    throw new Error("@Job class must declare an async run() method");
   }
-  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
@@ -2440,10 +2477,12 @@ var import_zod2 = require("zod");
   Get,
   Headers,
   HttpError,
+  Job,
   Log,
   NOTIFICATIONS_CONFIG_KIND,
   NotFound,
   Notifications,
+  On,
   OptionalUser,
   PALBASE_EXTENSIONS,
   PROVIDER_CATALOG,
@@ -2475,6 +2514,7 @@ var import_zod2 = require("zod");
   Upload,
   UploadedObject,
   User,
+  Webhook,
   __getRuntime,
   __registerResource,
   __requestALS,
@@ -2491,20 +2531,20 @@ var import_zod2 = require("zod");
   defineEgress,
   defineError,
   defineFlags,
-  defineJob,
   defineMiddleware,
   defineNotifications,
   defineSchema,
   defineStorage,
   defineTestUsers,
-  defineWebhook,
   defineWorker,
   documents,
   entitlementFor,
   enumType,
   flag,
   getErrorRegistry,
+  getJobConfig,
   getRoutes,
+  getWebhookConfig,
   inc,
   integer,
   isPalbaseExtension,