@palbase/backend 4.0.0 → 5.1.0

package/dist/index.cjs

@@ -30,16 +30,19 @@ __export(src_exports, {
   Delete: () => Delete,
   Documents: () => Documents,
   EXTENSION_DEPENDENCIES: () => EXTENSION_DEPENDENCIES,
+  FLAGS_CONFIG_KIND: () => FLAGS_CONFIG_KIND,
   Flags: () => Flags,
   Forbidden: () => Forbidden,
   Get: () => Get,
   Headers: () => Headers,
   HttpError: () => HttpError,
   Log: () => Log,
+  NOTIFICATIONS_CONFIG_KIND: () => NOTIFICATIONS_CONFIG_KIND,
   NotFound: () => NotFound,
   Notifications: () => Notifications,
   OptionalUser: () => OptionalUser,
   PALBASE_EXTENSIONS: () => PALBASE_EXTENSIONS,
+  PROVIDER_CATALOG: () => PROVIDER_CATALOG,
   PalError: () => PalError,
   Param: () => Param,
   Patch: () => Patch,
@@ -48,10 +51,11 @@ __export(src_exports, {
   Put: () => Put,
   Query: () => Query,
   Queue: () => Queue,
+  RESERVED_SECRET_PREFIX: () => RESERVED_SECRET_PREFIX,
   Req: () => Req,
   RequestId: () => RequestId,
   Resource: () => Resource,
-  Returns: () => Returns,
+  STORAGE_CONFIG_KIND: () => STORAGE_CONFIG_KIND,
   Storage: () => Storage,
   TooManyRequests: () => TooManyRequests,
   TraceId: () => TraceId,
@@ -66,19 +70,27 @@ __export(src_exports, {
   __shutdownResources: () => __shutdownResources,
   auth: () => auth,
   boolean: () => boolean,
+  bucket: () => bucket,
+  buildProvider: () => buildProvider,
+  defineFlags: () => defineFlags,
   defineJob: () => defineJob,
   defineMiddleware: () => defineMiddleware,
+  defineNotifications: () => defineNotifications,
   defineSchema: () => defineSchema,
+  defineStorage: () => defineStorage,
   defineWebhook: () => defineWebhook,
   defineWorker: () => defineWorker,
   documents: () => documents,
   enumType: () => enumType,
+  flag: () => flag,
   integer: () => integer,
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
   makeEnvDts: () => makeEnvDts,
   makeTypedDB: () => makeTypedDB,
+  parseFileSizeLimit: () => parseFileSizeLimit,
   policy: () => policy,
+  reservedSecretKey: () => reservedSecretKey,
   storage: () => storage,
   text: () => text,
   timestamp: () => timestamp,
@@ -460,6 +472,277 @@ export {};
 `;
 }
 
+// src/config/storage.ts
+var STORAGE_CONFIG_KIND = "storage";
+var UNIT_BYTES = {
+  b: 1,
+  kb: 1024,
+  mb: 1024 ** 2,
+  gb: 1024 ** 3,
+  tb: 1024 ** 4
+};
+function parseFileSizeLimit(input) {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input) || input < 0 || !Number.isInteger(input)) {
+      throw new Error(
+        `bucket fileSizeLimit must be a non-negative integer number of bytes, got ${input}`
+      );
+    }
+    return input;
+  }
+  const trimmed = input.trim();
+  const match = /^(\d+(?:\.\d+)?)\s*([a-zA-Z]+)?$/.exec(trimmed);
+  if (!match) {
+    throw new Error(
+      `bucket fileSizeLimit string must be "<number><unit>" like "5MB" or "1GB", got "${input}"`
+    );
+  }
+  const value = Number.parseFloat(match[1]);
+  const unit = (match[2] ?? "b").toLowerCase();
+  const multiplier = UNIT_BYTES[unit];
+  if (multiplier === void 0) {
+    throw new Error(
+      `bucket fileSizeLimit has an unknown unit "${match[2]}" \u2014 use B, KB, MB, GB, or TB (e.g. "5MB")`
+    );
+  }
+  const bytes = value * multiplier;
+  if (!Number.isFinite(bytes) || bytes < 0) {
+    throw new Error(`bucket fileSizeLimit resolved to an invalid byte count: ${bytes}`);
+  }
+  return Math.round(bytes);
+}
+var MIME_RE = /^[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]*\/(?:\*|[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]*)$/;
+function bucket(opts = {}) {
+  const fileSizeLimit = opts.fileSizeLimit === void 0 ? null : parseFileSizeLimit(opts.fileSizeLimit);
+  let allowedMimeTypes = null;
+  if (opts.allowedMimeTypes !== void 0) {
+    if (!Array.isArray(opts.allowedMimeTypes)) {
+      throw new Error("bucket allowedMimeTypes must be an array of MIME-type strings");
+    }
+    for (const mime of opts.allowedMimeTypes) {
+      if (typeof mime !== "string" || !MIME_RE.test(mime.trim())) {
+        throw new Error(
+          `bucket allowedMimeTypes entry "${mime}" is not a valid MIME type (expected "type/subtype", e.g. "image/png")`
+        );
+      }
+    }
+    allowedMimeTypes = [...new Set(opts.allowedMimeTypes.map((m) => m.trim()))];
+  }
+  return {
+    public: opts.public ?? false,
+    fileSizeLimit,
+    allowedMimeTypes
+  };
+}
+function defineStorage(input) {
+  if (input === null || typeof input !== "object" || typeof input.buckets !== "object") {
+    throw new Error("defineStorage expects { buckets: { <name>: bucket({...}) } }");
+  }
+  const buckets = {};
+  for (const name of Object.keys(input.buckets)) {
+    if (name.length === 0) {
+      throw new Error("bucket name must be a non-empty string");
+    }
+    const def = input.buckets[name];
+    if (def === void 0) continue;
+    buckets[name] = def;
+  }
+  return { __config: STORAGE_CONFIG_KIND, buckets };
+}
+
+// src/config/notifications.ts
+var NOTIFICATIONS_CONFIG_KIND = "notifications";
+var RESERVED_SECRET_PREFIX = "PB_NOTIFICATIONS";
+var PROVIDER_CATALOG = {
+  apns: {
+    channel: "push",
+    required: ["teamId", "keyId", "bundleId"],
+    optional: ["isProduction"],
+    secrets: ["p8"]
+  },
+  fcm: {
+    channel: "push",
+    required: [],
+    optional: [],
+    secrets: ["serviceAccount"]
+  },
+  sendgrid: {
+    channel: "email",
+    required: ["fromDomain"],
+    optional: [],
+    secrets: ["apiKey"]
+  },
+  ses: {
+    channel: "email",
+    required: ["region", "accessKeyId", "fromDomain"],
+    optional: [],
+    secrets: ["secretAccessKey"]
+  },
+  smtp: {
+    channel: "email",
+    required: ["host", "port", "fromEmail"],
+    optional: ["username", "useStarttls"],
+    secrets: ["password"]
+  },
+  acs: {
+    channel: "email",
+    required: ["fromEmail"],
+    optional: ["fromName"],
+    secrets: ["connectionString"]
+  },
+  twilio: {
+    channel: "sms",
+    // account_sid required; one of from_number / messaging_service_sid required
+    // (enforced by the refine in buildProvider, not by the flat `required` list).
+    required: ["accountSid"],
+    optional: ["fromNumber", "messagingServiceSid"],
+    secrets: ["authToken"]
+  }
+};
+function buildProvider(name, opts) {
+  const entry = PROVIDER_CATALOG[name];
+  const src = { ...opts };
+  const enabled = src.enabled === void 0 ? false : Boolean(src.enabled);
+  if (!enabled) {
+    return { enabled: false };
+  }
+  const def = { enabled: true };
+  for (const field of entry.required) {
+    const value = src[field];
+    if (value === void 0 || value === null || value === "") {
+      throw new Error(
+        `notifications: provider "${name}" is enabled but missing required field "${field}"`
+      );
+    }
+    def[field] = value;
+  }
+  for (const field of entry.optional) {
+    if (src[field] !== void 0) {
+      def[field] = src[field];
+    }
+  }
+  if (name === "twilio") {
+    const hasFrom = Boolean(def.fromNumber);
+    const hasMsg = Boolean(def.messagingServiceSid);
+    if (!hasFrom && !hasMsg) {
+      throw new Error(
+        'notifications: provider "twilio" requires one of "fromNumber" or "messagingServiceSid"'
+      );
+    }
+  }
+  return def;
+}
+function defineNotifications(input) {
+  if (input === null || typeof input !== "object") {
+    throw new Error("defineNotifications expects { push?, email?, sms? }");
+  }
+  const config = {
+    __config: NOTIFICATIONS_CONFIG_KIND,
+    push: {},
+    email: {},
+    sms: {}
+  };
+  const push = input.push ?? {};
+  if (push.apns !== void 0) config.push.apns = buildProvider("apns", push.apns);
+  if (push.fcm !== void 0) config.push.fcm = buildProvider("fcm", push.fcm);
+  const email = input.email ?? {};
+  if (email.sendgrid !== void 0) config.email.sendgrid = buildProvider("sendgrid", email.sendgrid);
+  if (email.ses !== void 0) config.email.ses = buildProvider("ses", email.ses);
+  if (email.smtp !== void 0) config.email.smtp = buildProvider("smtp", email.smtp);
+  if (email.acs !== void 0) config.email.acs = buildProvider("acs", email.acs);
+  const sms = input.sms ?? {};
+  if (sms.twilio !== void 0) config.sms.twilio = buildProvider("twilio", sms.twilio);
+  return config;
+}
+function reservedSecretKey(provider, secretField) {
+  return `${RESERVED_SECRET_PREFIX}_${camelToUpperSnake(provider)}_${camelToUpperSnake(secretField)}`;
+}
+function camelToUpperSnake(s) {
+  return s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+}
+
+// src/config/flags.ts
+var FLAGS_CONFIG_KIND = "flags";
+var FLAG_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+function valueMatchesType(type, value) {
+  switch (type) {
+    case "boolean":
+      return typeof value === "boolean";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "string":
+      return typeof value === "string";
+  }
+}
+function flag(opts) {
+  if (opts === null || typeof opts !== "object") {
+    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 (!valueMatchesType(type, opts.default)) {
+    throw new Error(
+      `flag default ${JSON.stringify(opts.default)} does not match type "${type}"`
+    );
+  }
+  let variants = null;
+  if (opts.variants !== void 0) {
+    if (type !== "string") {
+      throw new Error(`flag variants are only valid for type "string" (got type "${type}")`);
+    }
+    if (!Array.isArray(opts.variants)) {
+      throw new Error("flag variants must be an array of strings");
+    }
+    for (const v of opts.variants) {
+      if (typeof v !== "string" || v.length === 0) {
+        throw new Error(`flag variant ${JSON.stringify(v)} must be a non-empty string`);
+      }
+    }
+    variants = [...new Set(opts.variants)];
+    if (variants.length === 0) {
+      throw new Error("flag variants must be a non-empty list when supplied");
+    }
+    if (!variants.includes(opts.default)) {
+      throw new Error(
+        `flag default ${JSON.stringify(opts.default)} is not one of its variants [${variants.map((v) => JSON.stringify(v)).join(", ")}]`
+      );
+    }
+  }
+  let description = null;
+  if (opts.description !== void 0) {
+    if (typeof opts.description !== "string") {
+      throw new Error("flag description must be a string");
+    }
+    const trimmed = opts.description.trim();
+    description = trimmed.length > 0 ? trimmed : null;
+  }
+  return {
+    type,
+    default: opts.default,
+    variants,
+    description
+  };
+}
+function defineFlags(input) {
+  if (input === null || typeof input !== "object" || typeof input.flags !== "object") {
+    throw new Error("defineFlags expects { flags: { <key>: flag({...}) } }");
+  }
+  const flags = {};
+  for (const key of Object.keys(input.flags)) {
+    if (!FLAG_KEY_RE.test(key)) {
+      throw new Error(
+        `flag key ${JSON.stringify(key)} is invalid \u2014 must start with a letter and contain only letters, digits, and underscores`
+      );
+    }
+    const def = input.flags[key];
+    if (def === void 0) continue;
+    flags[key] = def;
+  }
+  return { __config: FLAGS_CONFIG_KIND, flags };
+}
+
 // src/decorators/controller.ts
 var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
 function Controller(basePath, options = {}) {
@@ -489,6 +772,7 @@ function Controller(basePath, options = {}) {
 // src/decorators/registry.ts
 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");
 function carrierOf(target) {
   const ctor = typeof target === "function" ? target : target.constructor ?? target;
   return ctor;
@@ -510,7 +794,12 @@ function recordRoute(target, fnName, method, subpath, options) {
   const routes = ownRoutes(carrier);
   const buffer = ownParamBuffer(carrier);
   const params = (buffer[fnName] ?? []).slice().sort((a, b) => a.index - b.index);
-  routes.push({ method, subpath, fnName, options, params });
+  const route = { method, subpath, fnName, options, params };
+  const returnBuffer = carrier[RETURN_BUFFER];
+  if (returnBuffer && returnBuffer[fnName] !== void 0) {
+    route.returnSchema = returnBuffer[fnName];
+  }
+  routes.push(route);
 }
 function recordParam(target, fnName, meta) {
   const carrier = carrierOf(target);
@@ -525,20 +814,6 @@ function recordParam(target, fnName, meta) {
     }
   }
 }
-var RETURN_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.returnBuffer");
-function recordReturn(target, fnName, schema) {
-  const carrier = carrierOf(target);
-  const routes = carrier[ROUTES];
-  const route = routes?.find((r) => r.fnName === fnName);
-  if (route) {
-    route.returnSchema = schema;
-    return;
-  }
-  if (!Object.prototype.hasOwnProperty.call(carrier, RETURN_BUFFER)) {
-    carrier[RETURN_BUFFER] = {};
-  }
-  carrier[RETURN_BUFFER][fnName] = schema;
-}
 
 // src/decorators/methods.ts
 function makeMethodDecorator(method) {
@@ -553,11 +828,6 @@ var Post = makeMethodDecorator("POST");
 var Put = makeMethodDecorator("PUT");
 var Patch = makeMethodDecorator("PATCH");
 var Delete = makeMethodDecorator("DELETE");
-function Returns(schema) {
-  return function(target, propertyKey) {
-    recordReturn(target, String(propertyKey), schema);
-  };
-}
 
 // src/decorators/params.ts
 function makeParamDecorator(kind, extra) {
@@ -1001,16 +1271,19 @@ var import_zod = require("zod");
   Delete,
   Documents,
   EXTENSION_DEPENDENCIES,
+  FLAGS_CONFIG_KIND,
   Flags,
   Forbidden,
   Get,
   Headers,
   HttpError,
   Log,
+  NOTIFICATIONS_CONFIG_KIND,
   NotFound,
   Notifications,
   OptionalUser,
   PALBASE_EXTENSIONS,
+  PROVIDER_CATALOG,
   PalError,
   Param,
   Patch,
@@ -1019,10 +1292,11 @@ var import_zod = require("zod");
   Put,
   Query,
   Queue,
+  RESERVED_SECRET_PREFIX,
   Req,
   RequestId,
   Resource,
-  Returns,
+  STORAGE_CONFIG_KIND,
   Storage,
   TooManyRequests,
   TraceId,
@@ -1037,19 +1311,27 @@ var import_zod = require("zod");
   __shutdownResources,
   auth,
   boolean,
+  bucket,
+  buildProvider,
+  defineFlags,
   defineJob,
   defineMiddleware,
+  defineNotifications,
   defineSchema,
+  defineStorage,
   defineWebhook,
   defineWorker,
   documents,
   enumType,
+  flag,
   integer,
   isPalbaseExtension,
   jsonb,
   makeEnvDts,
   makeTypedDB,
+  parseFileSizeLimit,
   policy,
+  reservedSecretKey,
   storage,
   text,
   timestamp,