@palbase/backend 11.0.0 → 12.0.1

package/dist/index.js

@@ -843,6 +843,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",
@@ -1234,12 +1240,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 === "") {
@@ -1305,115 +1398,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
@@ -1517,10 +1551,12 @@ export {
   Get,
   Headers,
   HttpError,
+  Job,
   Log,
   NOTIFICATIONS_CONFIG_KIND,
   NotFound,
   Notifications,
+  On,
   OptionalUser,
   PALBASE_EXTENSIONS,
   PROVIDER_CATALOG,
@@ -1552,6 +1588,7 @@ export {
   Upload,
   UploadedObject,
   User,
+  Webhook,
   __getRuntime,
   __registerResource,
   __requestALS,
@@ -1568,20 +1605,20 @@ export {
   defineEgress,
   defineError,
   defineFlags,
-  defineJob,
   defineMiddleware,
   defineNotifications,
   defineSchema,
   defineStorage,
   defineTestUsers,
-  defineWebhook,
   defineWorker,
   documents,
   entitlementFor,
   enumType,
   flag,
   getErrorRegistry,
+  getJobConfig,
   getRoutes,
+  getWebhookConfig,
   inc,
   integer,
   isPalbaseExtension,