@palbase/backend 17.3.0 → 18.0.0

package/dist/index.cjs

@@ -51,6 +51,7 @@ __export(src_exports, {
   PALBASE_EXTENSIONS: () => PALBASE_EXTENSIONS,
   PROVIDER_CATALOG: () => PROVIDER_CATALOG,
   PalError: () => PalError,
+  PalbaseModuleError: () => PalbaseModuleError,
   Param: () => Param,
   Patch: () => Patch,
   PolicyBuilder: () => PolicyBuilder,
@@ -65,7 +66,9 @@ __export(src_exports, {
   RequestId: () => RequestId,
   RequireEntitlement: () => RequireEntitlement,
   Resource: () => Resource,
+  SECRETS_CONFIG_KIND: () => SECRETS_CONFIG_KIND,
   STORAGE_CONFIG_KIND: () => STORAGE_CONFIG_KIND,
+  Secrets: () => Secrets,
   Spend: () => Spend,
   Storage: () => Storage,
   TEST_USERS_CONFIG_KIND: () => TEST_USERS_CONFIG_KIND,
@@ -81,6 +84,7 @@ __export(src_exports, {
   __getRuntime: () => __getRuntime,
   __registerResource: () => __registerResource,
   __requestALS: () => __requestALS,
+  __resetRegisteredControllers: () => __resetRegisteredControllers,
   __runResourceBoot: () => __runResourceBoot,
   __runWithRuntime: () => __runWithRuntime,
   __setRuntime: () => __setRuntime,
@@ -89,6 +93,7 @@ __export(src_exports, {
   bigint: () => bigint,
   boolean: () => boolean,
   bucket: () => bucket,
+  buildModuleClients: () => buildModuleClients,
   buildProvider: () => buildProvider,
   dec: () => dec,
   defineEgress: () => defineEgress,
@@ -97,6 +102,7 @@ __export(src_exports, {
   defineMiddleware: () => defineMiddleware,
   defineNotifications: () => defineNotifications,
   defineSchema: () => defineSchema,
+  defineSecrets: () => defineSecrets,
   defineStorage: () => defineStorage,
   defineTestUsers: () => defineTestUsers,
   documents: () => documents,
@@ -106,6 +112,7 @@ __export(src_exports, {
   flag: () => flag,
   getErrorRegistry: () => getErrorRegistry,
   getJobConfig: () => getJobConfig,
+  getRegisteredControllers: () => getRegisteredControllers,
   getRoutes: () => getRoutes,
   getWebhookConfig: () => getWebhookConfig,
   inc: () => inc,
@@ -113,6 +120,7 @@ __export(src_exports, {
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
   makeEnvDts: () => makeEnvDts,
+  makeHttpClient: () => makeHttpClient,
   makePurchasesDts: () => makePurchasesDts,
   makeTypedDB: () => makeTypedDB,
   now: () => now,
@@ -122,11 +130,13 @@ __export(src_exports, {
   raw: () => raw,
   recordThrows: () => recordThrows,
   reservedSecretKey: () => reservedSecretKey,
+  secret: () => secret,
   spendFor: () => spendFor,
   storage: () => storage,
   testUser: () => testUser,
   text: () => text,
   timestamp: () => timestamp,
+  toSchemaJSON: () => toSchemaJSON,
   uuid: () => uuid,
   validateUploadAgainstStorage: () => validateUploadAgainstStorage,
   z: () => import_zod2.z
@@ -635,8 +645,35 @@ var Database = Object.assign(makeTypedSurface(rawDatabase), {
   }
 });
 var Documents = makeServiceProxy("Documents");
-var Storage = makeServiceProxy("Storage");
+function makeBucketsAccessor(storage2) {
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        return storage2().bucket(prop);
+      }
+    }
+  );
+}
+var rawStorage = makeServiceProxy("Storage");
+var Storage = Object.assign(
+  {
+    // FORWARDED explicitly, not assigned onto the service proxy.
+    //
+    // `Object.assign(rawStorage, {buckets})` writes onto the proxy's TARGET, and
+    // the proxy's only trap is `get`, which forwards every read to the module
+    // client — so the property landed somewhere nothing reads and
+    // `Storage.buckets.docs` was `undefined` in a deployed handler. It
+    // typechecked, every test passed, and the live call answered
+    // "TypeError: undefined is not an object". `Database` never had the bug
+    // because it builds a plain surface the same way this now does.
+    bucket: (name) => rawStorage.bucket(name)
+  },
+  { buckets: makeBucketsAccessor(() => rawStorage) }
+);
 var Cache = makeServiceProxy("Cache");
+var Secrets = makeServiceProxy("Secrets");
 var Log = makeServiceProxy("Log");
 var Notifications = makeServiceProxy("Notifications");
 var Purchases = makeServiceProxy("Purchases");
@@ -652,6 +689,19 @@ var Flags = Object.assign(
     getAll(context) {
       return rawFlags.getAll(context);
     },
+    /**
+     * Resolve a flag's value, with an optional fallback.
+     *
+     * FORWARDED as of 2026-08-15. This surface is written out by hand, method
+     * by method, and `get` was missing from it — so the client implemented it,
+     * thirty assertions covered it, and `Flags.get("x")` was `undefined` in a
+     * deployed handler. Exactly the shape of the `Storage.buckets` defect found
+     * the same day: a hand-maintained forwarding list is a list somebody has to
+     * remember to update.
+     */
+    get(flagName, defaultOrContext, maybeContext) {
+      return rawFlags.get(flagName, defaultOrContext, maybeContext);
+    },
     setOverride(key, value) {
       return rawFlags.setOverride(key, value);
     }
@@ -671,11 +721,14 @@ var Flags = Object.assign(
 var Realtime = makeServiceProxy("Realtime");
 
 // src/errors.ts
+var HTTP_ERROR_BRAND = /* @__PURE__ */ Symbol.for("palbase.backend.httpError");
 var HttpError = class extends Error {
   status;
   error;
   errorDescription;
   data;
+  /** See {@link HTTP_ERROR_BRAND} — how the engine recognises this across SDK copies. */
+  [HTTP_ERROR_BRAND] = true;
   constructor(status, error, errorDescription, data) {
     super(errorDescription);
     this.name = "HttpError";
@@ -911,6 +964,795 @@ function Spend(key) {
   };
 }
 
+// src/clients/http.ts
+var PalbaseModuleError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(code, message, status, details = {}) {
+    super(message);
+    this.name = "PalbaseModuleError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+function makeHttpClient(cfg) {
+  async function request(method, path, options = {}) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...options.headers ?? {}
+    };
+    if (cfg.apiKey) headers["apikey"] = cfg.apiKey;
+    const init = { method, headers };
+    if (options.body !== void 0) {
+      if (typeof options.body === "string" || options.body instanceof Uint8Array) {
+        init.body = options.body;
+      } else if (typeof FormData !== "undefined" && options.body instanceof FormData) {
+        delete headers["Content-Type"];
+        init.body = options.body;
+      } else if (typeof Blob !== "undefined" && options.body instanceof Blob) {
+        delete headers["Content-Type"];
+        init.body = options.body;
+      } else {
+        init.body = JSON.stringify(options.body);
+      }
+    }
+    if (options.signal) init.signal = options.signal;
+    const doFetch = cfg.fetchImpl ?? globalThis.fetch;
+    let response;
+    try {
+      response = await doFetch(`${cfg.baseUrl}${path}`, init);
+    } catch (err) {
+      return {
+        data: null,
+        error: new PalbaseModuleError(
+          "network_error",
+          err instanceof Error ? err.message : "Network request failed",
+          0
+        ),
+        status: 0
+      };
+    }
+    const contentType = response.headers.get("Content-Type") ?? "";
+    let parsed = null;
+    if (method !== "HEAD" && contentType.includes("json")) {
+      parsed = await response.json().catch(() => null);
+    } else if (method !== "HEAD" && contentType.startsWith("image/")) {
+      parsed = new Uint8Array(await response.arrayBuffer());
+    } else if (method !== "HEAD" && response.body) {
+      parsed = await response.text().catch(() => null);
+    }
+    if (!response.ok) {
+      const body = parsed && typeof parsed === "object" ? parsed : {};
+      const code = typeof body.error === "string" && body.error ? body.error : "unknown_error";
+      const message = typeof body.error_description === "string" && body.error_description || response.statusText || "request failed";
+      return {
+        data: null,
+        error: new PalbaseModuleError(code, message, response.status, body),
+        status: response.status
+      };
+    }
+    return { data: parsed, error: null, status: response.status };
+  }
+  return { baseUrl: cfg.baseUrl, request };
+}
+
+// src/clients/documents.ts
+var SEGMENT_RE = /^[A-Za-z0-9_-]+$/;
+function validateSegment(segment, label) {
+  if (!SEGMENT_RE.test(segment)) {
+    throw new Error(`Invalid ${label}: "${segment}". Must match ${SEGMENT_RE.source}`);
+  }
+}
+function buildDocumentRef(http, path) {
+  return {
+    path,
+    async set(data) {
+      return http.request("PUT", `/v1/docs/${path}`, { body: data });
+    },
+    async get() {
+      const response = await http.request("GET", `/v1/docs/${path}`);
+      if (response.error) return { data: null, error: response.error, status: response.status };
+      const raw2 = response.data ?? {};
+      const exists = raw2.exists !== void 0 ? raw2.exists : Boolean(raw2.data || raw2.id);
+      const segments = path.split("/");
+      const id = raw2.id || segments[segments.length - 1] || "";
+      return {
+        data: { id, exists, data: () => raw2.data, ref: { path } },
+        error: null,
+        status: response.status
+      };
+    },
+    async update(data) {
+      return http.request("PATCH", `/v1/docs/${path}`, { body: data });
+    },
+    async delete() {
+      return http.request("DELETE", `/v1/docs/${path}`);
+    },
+    collection(name) {
+      validateSegment(name, "subcollection name");
+      return buildCollectionRef(http, `${path}/${name}`);
+    }
+  };
+}
+function buildCollectionRef(http, path, state = { where: [], orderBy: [] }) {
+  function snapshot(doc) {
+    return {
+      id: doc.id,
+      exists: true,
+      data: () => doc.data,
+      ref: { path: `${path}/${doc.id}` }
+    };
+  }
+  function querySnapshot(docs) {
+    return {
+      docs,
+      empty: docs.length === 0,
+      size: docs.length,
+      docChanges: () => docs.map((doc) => ({ type: "added", doc }))
+    };
+  }
+  return {
+    path,
+    doc(id) {
+      validateSegment(id, "document ID");
+      return buildDocumentRef(http, `${path}/${id}`);
+    },
+    async add(data) {
+      const resp = await http.request("POST", `/v1/docs/${path}`, { body: data });
+      if (resp.error || !resp.data) {
+        return { data: null, error: resp.error, status: resp.status };
+      }
+      return {
+        data: buildDocumentRef(http, `${path}/${resp.data.id}`),
+        error: null,
+        status: resp.status
+      };
+    },
+    // Each narrowing returns a NEW ref. A builder that mutated in place would
+    // leak one caller's filter into a query another caller had already held.
+    where(field, op, value) {
+      return buildCollectionRef(http, path, {
+        ...state,
+        where: [...state.where, { field, op, value }]
+      });
+    },
+    orderBy(field, direction = "asc") {
+      return buildCollectionRef(http, path, {
+        ...state,
+        orderBy: [...state.orderBy, { field, direction }]
+      });
+    },
+    limit(n) {
+      return buildCollectionRef(http, path, { ...state, limit: n });
+    },
+    async get() {
+      const narrowed = state.where.length > 0 || state.orderBy.length > 0 || state.limit !== void 0;
+      const resp = narrowed ? await http.request(
+        "POST",
+        `/v1/docs/${path}/query`,
+        { body: queryBody(state) }
+      ) : await http.request(
+        "GET",
+        `/v1/docs/${path}`
+      );
+      if (resp.error) return { data: null, error: resp.error, status: resp.status };
+      const docs = (resp.data?.documents ?? []).map(snapshot);
+      return { data: querySnapshot(docs), error: null, status: resp.status };
+    }
+  };
+}
+function queryBody(state) {
+  const body = {};
+  if (state.where.length > 0) {
+    body.where = state.where.map((w) => ({ field: w.field, op: w.op, value: w.value }));
+  }
+  if (state.orderBy.length > 0) {
+    body.orderBy = state.orderBy.map((o) => ({ field: o.field, direction: o.direction }));
+  }
+  if (state.limit !== void 0) body.limit = state.limit;
+  return body;
+}
+var MAX_BATCH = 500;
+function buildDocumentsClient(http) {
+  return {
+    /**
+     * `Documents.doc("users/alice")` — segments are collection/documentId PAIRS,
+     * so an odd count addresses a COLLECTION and is refused. Accepting it would
+     * write a document whose id happens to be a collection's name.
+     */
+    doc(path) {
+      const segments = String(path).split("/").filter((s) => s.length > 0);
+      if (segments.length === 0 || segments.length % 2 !== 0) {
+        throw new Error(
+          `Invalid document path: "${path}". Expected collection/documentId pairs, got ${segments.length} segment(s).`
+        );
+      }
+      segments.forEach((s, i) => validateSegment(s, i % 2 === 0 ? "collection name" : "document ID"));
+      return buildDocumentRef(http, segments.join("/"));
+    },
+    collection(name) {
+      validateSegment(name, "collection name");
+      return buildCollectionRef(http, name);
+    },
+    async batch(operations) {
+      if (operations.length > MAX_BATCH) {
+        return {
+          data: null,
+          error: new PalbaseModuleError(
+            "batch_too_large",
+            `Batch size ${operations.length} exceeds maximum of ${MAX_BATCH}`,
+            400
+          ),
+          status: 400
+        };
+      }
+      if (operations.length === 0) return { data: null, error: null, status: 200 };
+      return http.request("POST", "/v1/docs/batch", {
+        body: operations.map((op) => ({ op: op.op, path: op.ref.path, data: op.data }))
+      });
+    }
+  };
+}
+
+// src/clients/flags.ts
+var FLAG_NAME_RE = /^[A-Za-z0-9_.-]+$/;
+function assertFlagName(flagName) {
+  if (!FLAG_NAME_RE.test(flagName)) {
+    throw new Error(`Invalid flag name: "${flagName}". Flag names must match ${FLAG_NAME_RE.source}`);
+  }
+}
+function flagEnabled(value) {
+  if (typeof value === "boolean") return value;
+  return value != null && value !== 0 && value !== "";
+}
+function flagVariant(value) {
+  return typeof value === "string" ? { name: value } : null;
+}
+function isContextObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) && ("userId" in v || "properties" in v);
+}
+function buildFlagsClient(http, cfg) {
+  function resolveUserId(context) {
+    if (context && "userId" in context) return context.userId ?? null;
+    return cfg.getCurrentUserId() || void 0;
+  }
+  function mergedPath(context) {
+    const uid = resolveUserId(context);
+    return uid ? `/v1/user-flags/users/${encodeURIComponent(uid)}` : "/v1/user-flags";
+  }
+  function fetchMerged(context) {
+    return http.request("GET", mergedPath(context));
+  }
+  const service = {
+    async setOverrideForUser(userId, key, value) {
+      return http.request(
+        "PUT",
+        `/v1/user-flags/users/${encodeURIComponent(userId)}/${encodeURIComponent(key)}`,
+        { body: { value } }
+      );
+    },
+    async setOverridesForUser(userId, values) {
+      return http.request("PUT", `/v1/user-flags/users/${encodeURIComponent(userId)}`, {
+        body: { values }
+      });
+    },
+    async clearOverrideForUser(userId, key) {
+      return http.request(
+        "DELETE",
+        `/v1/user-flags/users/${encodeURIComponent(userId)}/${encodeURIComponent(key)}`
+      );
+    },
+    async clearAllOverridesForUser(userId) {
+      return http.request("DELETE", `/v1/user-flags/users/${encodeURIComponent(userId)}`);
+    },
+    async batchSetOverrides(operations) {
+      const ops = (operations ?? []).map((op) => {
+        const raw2 = op;
+        return { user_id: raw2.userId ?? raw2.user_id, values: raw2.values };
+      });
+      return http.request("POST", "/v1/user-flags/batch", { body: { operations: ops } });
+    }
+  };
+  return {
+    async isEnabled(flagName, context) {
+      assertFlagName(flagName);
+      const res = await fetchMerged(context);
+      if (res.error || res.data == null) return { data: null, error: res.error, status: res.status };
+      return { data: flagEnabled(res.data.values?.[flagName]), error: null, status: res.status };
+    },
+    async getVariant(flagName, context) {
+      assertFlagName(flagName);
+      const res = await fetchMerged(context);
+      if (res.error || res.data == null) return { data: null, error: res.error, status: res.status };
+      return { data: flagVariant(res.data.values?.[flagName]), error: null, status: res.status };
+    },
+    /**
+     * `get(key)` · `get(key, default)` · `get(key, default, ctx)` · `get(key, ctx)`.
+     *
+     * The default is substituted when the flag is ABSENT or when the flags
+     * service is unreachable — a product that hides a feature because a lookup
+     * timed out is behaving correctly; one that crashes is not.
+     */
+    async get(flagName, defaultOrContext, maybeContext) {
+      assertFlagName(flagName);
+      let defaultValue;
+      let context;
+      let hasDefault = false;
+      if (maybeContext !== void 0) {
+        defaultValue = defaultOrContext;
+        hasDefault = true;
+        context = maybeContext;
+      } else if (isContextObject(defaultOrContext)) {
+        context = defaultOrContext;
+      } else if (defaultOrContext !== void 0) {
+        defaultValue = defaultOrContext;
+        hasDefault = true;
+      }
+      const resp = await fetchMerged(context);
+      if (resp.error !== null) {
+        if (hasDefault) return { data: defaultValue ?? null, error: null, status: resp.status };
+        return { data: null, error: resp.error, status: resp.status };
+      }
+      const values = resp.data?.values ?? {};
+      const value = values[flagName];
+      if (value === void 0) {
+        return { data: hasDefault ? defaultValue ?? null : null, error: null, status: resp.status };
+      }
+      return { data: value, error: null, status: resp.status };
+    },
+    async getAll(context) {
+      const res = await fetchMerged(context);
+      if (res.error || res.data == null) return { data: null, error: res.error, status: res.status };
+      const values = res.data.values ?? {};
+      return {
+        data: Object.keys(values).map((name) => {
+          const value = values[name];
+          const flag2 = {
+            name,
+            enabled: flagEnabled(value)
+          };
+          if (typeof value === "string") flag2.variant = { name: value };
+          return flag2;
+        }),
+        error: null,
+        status: res.status
+      };
+    },
+    /**
+     * Override a flag for the CURRENT request user.
+     *
+     * On an anonymous request this does not silently no-op and does not write
+     * for nobody: it refuses and names the call that does cross-user writes.
+     */
+    async setOverride(key, value) {
+      const uid = cfg.getCurrentUserId();
+      if (!uid) {
+        return {
+          data: null,
+          error: {
+            message: "setOverride requires a signed-in user; use Flags.asService().setOverrideForUser(userId, key, value) for cross-user writes"
+          },
+          status: 400
+        };
+      }
+      return http.request(
+        "PUT",
+        `/v1/user-flags/users/${encodeURIComponent(uid)}/${encodeURIComponent(key)}`,
+        { body: { value } }
+      );
+    },
+    asService() {
+      return service;
+    }
+  };
+}
+
+// src/clients/notifications.ts
+function mapEnvelope(res, map) {
+  if (res.error !== null || res.data === null || res.data === void 0) {
+    return { data: null, error: res.error, status: res.status };
+  }
+  return { data: map(res.data), error: null, status: res.status };
+}
+function toEmailTemplate(wire) {
+  const view = {
+    id: wire.id,
+    slug: wire.slug,
+    locale: wire.locale,
+    subject: wire.subject,
+    htmlBody: wire.html_body,
+    variables: wire.variables ?? [],
+    isDefault: wire.is_default,
+    createdAt: wire.created_at,
+    updatedAt: wire.updated_at
+  };
+  if (wire.text_body !== void 0) view.textBody = wire.text_body;
+  return view;
+}
+function toSmsTemplate(wire) {
+  return {
+    id: wire.id,
+    slug: wire.slug,
+    locale: wire.locale,
+    body: wire.body,
+    variables: wire.variables ?? [],
+    isDefault: wire.is_default,
+    createdAt: wire.created_at,
+    updatedAt: wire.updated_at
+  };
+}
+function buildNotificationsClient(http) {
+  const push = {
+    async send(params) {
+      return http.request("POST", "/v1/notifications/push", { body: params });
+    }
+  };
+  const email = {
+    async send(params) {
+      const { templateSlug, html, text: text2, ...rest } = params;
+      const body = { ...rest };
+      if (templateSlug !== void 0) body.template_slug = templateSlug;
+      if (html !== void 0) body.html_body = html;
+      if (text2 !== void 0) body.text_body = text2;
+      return http.request("POST", "/v1/notifications/email", { body });
+    }
+  };
+  const sms = {
+    async send(params) {
+      const { templateSlug, ...rest } = params;
+      const body = templateSlug !== void 0 ? { ...rest, template_slug: templateSlug } : rest;
+      return http.request("POST", "/v1/notifications/sms", { body });
+    }
+  };
+  const verifications = {
+    async start(params) {
+      return http.request("POST", "/v1/notifications/verifications", { body: params });
+    },
+    async check(params) {
+      return http.request("POST", "/v1/notifications/verifications/check", { body: params });
+    }
+  };
+  const inbox = {
+    async send(params) {
+      return http.request("POST", "/v1/notifications/inbox", { body: params });
+    },
+    async list(options) {
+      const opts = options ?? {};
+      const params = new URLSearchParams();
+      if (opts.cursor) params.set("cursor", opts.cursor);
+      if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+      if (opts.is_read !== void 0) params.set("is_read", opts.is_read ? "true" : "false");
+      if (opts.category) params.set("category", opts.category);
+      if (opts.include_archived) params.set("include_archived", "true");
+      const query = params.toString();
+      return http.request("GET", `/v1/notifications/inbox${query ? `?${query}` : ""}`);
+    },
+    async unreadCount() {
+      return http.request("GET", "/v1/notifications/inbox/unread-count");
+    },
+    async markRead(id) {
+      return http.request("PATCH", `/v1/notifications/inbox/${encodeURIComponent(id)}/read`);
+    },
+    async markAllRead() {
+      return http.request("POST", "/v1/notifications/inbox/read-all");
+    },
+    async archive(id) {
+      return http.request("DELETE", `/v1/notifications/inbox/${encodeURIComponent(id)}`);
+    }
+  };
+  const preferences = {
+    async get() {
+      return http.request("GET", "/v1/notifications/preferences");
+    },
+    async update(params) {
+      return http.request("PUT", "/v1/notifications/preferences", { body: params });
+    }
+  };
+  const emailTemplates = {
+    async list() {
+      const resp = await http.request("GET", "/v1/notifications/templates");
+      return mapEnvelope(resp, (rows) => (rows ?? []).map(toEmailTemplate));
+    },
+    async get(id) {
+      const resp = await http.request(
+        "GET",
+        `/v1/notifications/templates/${encodeURIComponent(id)}`
+      );
+      return mapEnvelope(resp, toEmailTemplate);
+    },
+    async create(input) {
+      const body = {
+        slug: input.slug,
+        subject: input.subject,
+        html_body: input.htmlBody
+      };
+      if (input.textBody !== void 0) body.text_body = input.textBody;
+      if (input.variables !== void 0) body.variables = input.variables;
+      const resp = await http.request("POST", "/v1/notifications/templates", { body });
+      return mapEnvelope(resp, toEmailTemplate);
+    },
+    async update(id, input) {
+      const body = {};
+      if (input.subject !== void 0) body.subject = input.subject;
+      if (input.htmlBody !== void 0) body.html_body = input.htmlBody;
+      if (input.textBody !== void 0) body.text_body = input.textBody;
+      if (input.variables !== void 0) body.variables = input.variables;
+      const resp = await http.request(
+        "PUT",
+        `/v1/notifications/templates/${encodeURIComponent(id)}`,
+        { body }
+      );
+      return mapEnvelope(resp, toEmailTemplate);
+    },
+    async delete(id) {
+      return http.request("DELETE", `/v1/notifications/templates/${encodeURIComponent(id)}`);
+    }
+  };
+  const smsTemplates = {
+    async list() {
+      const resp = await http.request("GET", "/v1/notifications/sms-templates");
+      return mapEnvelope(resp, (rows) => (rows ?? []).map(toSmsTemplate));
+    },
+    async get(id) {
+      const resp = await http.request(
+        "GET",
+        `/v1/notifications/sms-templates/${encodeURIComponent(id)}`
+      );
+      return mapEnvelope(resp, toSmsTemplate);
+    },
+    async create(input) {
+      const body = { slug: input.slug, body: input.body };
+      if (input.variables !== void 0) body.variables = input.variables;
+      const resp = await http.request("POST", "/v1/notifications/sms-templates", { body });
+      return mapEnvelope(resp, toSmsTemplate);
+    },
+    async update(id, input) {
+      const body = {};
+      if (input.body !== void 0) body.body = input.body;
+      if (input.variables !== void 0) body.variables = input.variables;
+      const resp = await http.request(
+        "PUT",
+        `/v1/notifications/sms-templates/${encodeURIComponent(id)}`,
+        { body }
+      );
+      return mapEnvelope(resp, toSmsTemplate);
+    },
+    async delete(id) {
+      return http.request("DELETE", `/v1/notifications/sms-templates/${encodeURIComponent(id)}`);
+    }
+  };
+  return {
+    push,
+    email,
+    sms,
+    verifications,
+    inbox,
+    preferences,
+    templates: { email: emailTemplates, sms: smsTemplates },
+    async registerDevice(params) {
+      return http.request("POST", "/v1/notifications/devices", { body: params });
+    },
+    async unregisterDevice(deviceId) {
+      return http.request("DELETE", `/v1/notifications/devices/${encodeURIComponent(deviceId)}`);
+    }
+  };
+}
+
+// src/clients/realtime.ts
+var import_node_crypto = require("crypto");
+function mintToken(secret2) {
+  const now2 = Math.floor(Date.now() / 1e3);
+  const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
+  const payload = Buffer.from(
+    JSON.stringify({ iss: "backend-runtime", role: "service_role", iat: now2, exp: now2 + 60 })
+  ).toString("base64url");
+  const sig = (0, import_node_crypto.createHmac)("sha256", secret2).update(`${header}.${payload}`).digest("base64url");
+  return `${header}.${payload}.${sig}`;
+}
+function buildRealtimeClient(cfg) {
+  const url = `${cfg.baseUrl}/realtime/api/broadcast`;
+  return {
+    async broadcast(channel, event, payload) {
+      if (typeof channel !== "string" || channel.length === 0) {
+        return {
+          data: null,
+          error: new PalbaseModuleError("invalid_argument", "channel must be a non-empty string", 400)
+        };
+      }
+      if (typeof event !== "string" || event.length === 0) {
+        return {
+          data: null,
+          error: new PalbaseModuleError("invalid_argument", "event must be a non-empty string", 400)
+        };
+      }
+      if (!cfg.apiJwtSecret) {
+        return {
+          data: null,
+          error: new PalbaseModuleError(
+            "realtime_unconfigured",
+            "Realtime.broadcast is unavailable: realtime is not provisioned for this Environment (PALBASE_REALTIME_API_JWT_SECRET unset).",
+            503
+          )
+        };
+      }
+      let token;
+      try {
+        token = mintToken(cfg.apiJwtSecret);
+      } catch (err) {
+        return {
+          data: null,
+          error: new PalbaseModuleError(
+            "realtime_token_error",
+            err instanceof Error ? err.message : "token mint failed",
+            500
+          )
+        };
+      }
+      const body = JSON.stringify({
+        messages: [{ topic: channel, event, payload: payload ?? {}, private: false }]
+      });
+      const doFetch = cfg.fetchImpl ?? globalThis.fetch;
+      let response;
+      try {
+        response = await doFetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+          body
+        });
+      } catch (err) {
+        return {
+          data: null,
+          error: new PalbaseModuleError(
+            "network_error",
+            err instanceof Error ? err.message : "broadcast request failed",
+            0
+          )
+        };
+      }
+      if (response.status === 202 || response.status === 200) {
+        return { data: void 0, error: null };
+      }
+      const detail = await response.text().catch(() => "");
+      return {
+        data: null,
+        error: new PalbaseModuleError(
+          "realtime_broadcast_failed",
+          `broadcast returned ${response.status}: ${detail.slice(0, 200)}`,
+          response.status
+        )
+      };
+    }
+  };
+}
+
+// src/clients/storage.ts
+var BUCKET_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+var STORAGE_PATH_RE = /^[a-zA-Z0-9_./-]+$/;
+var STORAGE_TRAVERSAL_RE = /(?:^|\/)\.\.(?:\/|$)/;
+function validateStoragePath(p) {
+  if (!STORAGE_PATH_RE.test(p) || STORAGE_TRAVERSAL_RE.test(p)) {
+    throw new Error(
+      `Invalid file path: "${p}". Paths must not contain traversal sequences and must match ${STORAGE_PATH_RE.source}`
+    );
+  }
+}
+function toFileObject(bucket2, row) {
+  return {
+    name: row.path ?? "",
+    path: row.path ?? "",
+    bucket: row.bucket ?? bucket2,
+    size: typeof row.size === "number" ? row.size : 0,
+    contentType: row.contentType ?? "",
+    checksum: row.checksum ?? "",
+    width: row.width,
+    height: row.height,
+    thumbhash: row.thumbhash,
+    variants: row.variants ?? {}
+  };
+}
+function mapResponse(res, map) {
+  if (res.error || res.data === null || res.data === void 0) {
+    return { data: null, error: res.error, status: res.status };
+  }
+  return { data: map(res.data), error: null, status: res.status };
+}
+function buildBucketClient(http, bucketName) {
+  const objectPath = (path) => `/v1/storage/object/${bucketName}/${path}`;
+  return {
+    async upload(path, file, options) {
+      validateStoragePath(path);
+      const headers = {
+        "Content-Type": options?.contentType ?? "application/octet-stream"
+      };
+      if (options?.upsert) headers["x-upsert"] = "true";
+      const body = file instanceof ArrayBuffer ? new Uint8Array(file) : file;
+      const res = await http.request("PUT", objectPath(path), {
+        body,
+        headers
+      });
+      return mapResponse(res, (r) => toFileObject(bucketName, r ?? {}));
+    },
+    async download(path) {
+      validateStoragePath(path);
+      return http.request("GET", objectPath(path), { headers: { Accept: "*/*" } });
+    },
+    getPublicUrl(path, options) {
+      validateStoragePath(path);
+      const variant = options?.variant ? `?variant=${encodeURIComponent(options.variant)}` : "";
+      return `/v1/files/${bucketName}/${path}${variant}`;
+    },
+    async createSignedUrl(path, options) {
+      validateStoragePath(path);
+      return http.request("POST", `/v1/storage/sign/${bucketName}/${path}`, {
+        body: { expiresIn: options.expiresIn }
+      });
+    },
+    async list(prefix, options) {
+      if (prefix) validateStoragePath(prefix);
+      const params = new URLSearchParams();
+      if (prefix) params.set("prefix", prefix);
+      if (options?.limit !== void 0) params.set("limit", String(options.limit));
+      const query = params.toString();
+      const res = await http.request(
+        "GET",
+        `/v1/storage/bucket/${bucketName}${query ? `?${query}` : ""}`
+      );
+      return mapResponse(res, (body) => (body?.objects ?? []).map((row) => toFileObject(bucketName, row)));
+    },
+    async remove(paths) {
+      for (const p of paths) validateStoragePath(p);
+      const removed = [];
+      for (const p of paths) {
+        const res = await http.request("DELETE", objectPath(p));
+        if (res.error) return { data: null, error: res.error, status: res.status };
+        removed.push(toFileObject(bucketName, { path: p }));
+      }
+      return { data: removed, error: null, status: 200 };
+    },
+    async move(from, to) {
+      validateStoragePath(from);
+      validateStoragePath(to);
+      return http.request("POST", `/v1/storage/move/${bucketName}`, { body: { from, to } });
+    },
+    async copy(from, to) {
+      validateStoragePath(from);
+      validateStoragePath(to);
+      return http.request("POST", `/v1/storage/copy/${bucketName}`, { body: { from, to } });
+    }
+  };
+}
+function buildStorageClient(http) {
+  return {
+    bucket(name) {
+      if (!BUCKET_NAME_RE.test(name)) {
+        throw new Error(`Invalid bucket name: "${name}". Bucket names must match ${BUCKET_NAME_RE.source}`);
+      }
+      return buildBucketClient(http, name);
+    }
+  };
+}
+
+// src/clients/index.ts
+function buildModuleClients(cfg) {
+  const baseUrl = (cfg.baseUrl || "").replace(/\/+$/, "");
+  if (!baseUrl) return {};
+  const apiKey = cfg.serviceRoleKey || cfg.apiKey || "";
+  const http = makeHttpClient({ baseUrl, apiKey, fetchImpl: cfg.fetchImpl });
+  return {
+    Documents: buildDocumentsClient(http),
+    Storage: buildStorageClient(http),
+    Notifications: buildNotificationsClient(http),
+    Flags: buildFlagsClient(http, { getCurrentUserId: cfg.getCurrentUserId }),
+    Realtime: buildRealtimeClient({
+      baseUrl,
+      apiJwtSecret: cfg.realtimeApiJwtSecret,
+      fetchImpl: cfg.fetchImpl
+    })
+  };
+}
+
 // src/purchases/keys-gen.ts
 function liveKeys(entries) {
   return Object.entries(entries ?? {}).filter(([, def]) => def?.removed !== true).map(([key]) => key).sort();
@@ -1020,6 +1862,89 @@ function defineSchema(input) {
   return { tables, extensions };
 }
 
+// src/db/schema-json.ts
+function defOf(column) {
+  return "_def" in column ? column._def : column;
+}
+function columnToJSON(column) {
+  const def = defOf(column);
+  const out = {
+    type: def.type,
+    nullable: def.nullable,
+    primaryKey: def.primaryKey
+  };
+  if (def.defaultValue !== void 0) out.defaultValue = def.defaultValue;
+  if (def.defaultRandom === true) out.defaultRandom = true;
+  if (def.defaultNow === true) out.defaultNow = true;
+  if (def.renamedFrom !== void 0) out.renamedFrom = def.renamedFrom;
+  if (def.references !== void 0) {
+    out.references = { table: def.references.table, column: def.references.column };
+  }
+  if (def.onDeleteAction !== void 0) out.onDeleteAction = def.onDeleteAction;
+  if (def.enumName !== void 0) out.enumName = def.enumName;
+  if (def.enumValues !== void 0) out.enumValues = [...def.enumValues];
+  if (def.unique === true) out.unique = true;
+  return out;
+}
+function policyToJSON(policy2) {
+  return {
+    name: policy2.name,
+    command: policy2.command ?? "all",
+    roles: policy2.roles ? [...policy2.roles] : [],
+    // null rather than omitted: a policy with no USING clause is a different
+    // thing from one whose clause the emitter forgot, and Go reads the
+    // difference.
+    using: policy2.using ?? null,
+    withCheck: policy2.withCheck ?? null,
+    permissive: policy2.permissive !== false
+  };
+}
+function tableToJSON(table) {
+  const columns = {};
+  for (const [name, column] of Object.entries(table.columns)) {
+    columns[name] = columnToJSON(column);
+  }
+  const out = {
+    name: table.name,
+    columns,
+    // Read, not re-derived. `defineSchema` already resolves the fail-closed
+    // default (RLS on unless the author wrote `rls: false`, and forced on by any
+    // policy), and a second copy of a SECURITY default is exactly the thing that
+    // drifts — the direction it drifted last time was "expose everything", and
+    // the live proof was one user reading another's rows.
+    rls: table.rls,
+    policies: (table.policies ?? []).map(policyToJSON)
+  };
+  if (table.primaryKey !== void 0 && table.primaryKey.length > 0) {
+    out.primaryKey = [...table.primaryKey];
+  }
+  if (table.unique !== void 0 && table.unique.length > 0) {
+    out.uniqueConstraints = table.unique.map((u) => ({ name: u.name, columns: [...u.columns] }));
+  }
+  if (table.raw !== void 0 && table.raw.length > 0) {
+    out.rawConstraints = table.raw.map((r) => ({
+      name: r.name,
+      up: r.up,
+      down: r.down ?? null
+    }));
+  }
+  if (table.checks !== void 0 && table.checks.length > 0) {
+    out.checks = table.checks.map((c) => ({ name: c.name, expr: c.expr }));
+  }
+  if (table.indexes !== void 0 && table.indexes.length > 0) {
+    out.indexes = table.indexes.map((i) => ({ name: i.name, columns: [...i.columns] }));
+  }
+  return out;
+}
+function toSchemaJSON(schema) {
+  const tables = {};
+  for (const table of Object.values(schema.tables)) {
+    const json = tableToJSON(table);
+    tables[json.name] = json;
+  }
+  return { tables, extensions: [...new Set(schema.extensions ?? [])] };
+}
+
 // src/db/extensions.ts
 var PALBASE_EXTENSIONS = [
   // Search & text
@@ -1105,6 +2030,21 @@ var ColumnBuilder = class _ColumnBuilder {
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /** Add a foreign key reference. */
+  /**
+   * Declares that this column used to be called `previous`.
+   *
+   * A schema diff sees one name gone and another present; it cannot know whether
+   * you renamed a column or dropped one and added another, and the two are very
+   * different — the second loses every value. Saying so here turns the plan into
+   * `ALTER TABLE … RENAME COLUMN` instead.
+   *
+   * Once the rename has been applied the annotation is inert (the old name is no
+   * longer there to rename), so it can be deleted at your leisure.
+   */
+  renamedFrom(previous) {
+    this._def.renamedFrom = previous;
+    return this;
+  }
   references(table, column) {
     this._def.references = { table, column };
     return new _ColumnBuilder(this._def.type, this._def);
@@ -1372,6 +2312,7 @@ export {};
 // src/config/storage.ts
 var STORAGE_CONFIG_KIND = "storage";
 var VARIANT_FORMATS = ["webp", "avif", "jpeg", "png"];
+var VARIANT_FITS = ["cover", "contain", "inside"];
 function normalizeVariants(input) {
   if (input === null || typeof input !== "object" || Array.isArray(input)) {
     throw new Error("bucket variants must be an object of { <name>: { width?, height?, format? } }");
@@ -1401,10 +2342,26 @@ function normalizeVariants(input) {
         `bucket variant "${name}" format must be one of ${VARIANT_FORMATS.join(", ")}, got "${String(spec.format)}"`
       );
     }
+    if (spec.fit !== void 0 && !VARIANT_FITS.includes(spec.fit)) {
+      throw new Error(
+        `bucket variant "${name}" fit must be one of ${VARIANT_FITS.join(", ")}, got "${String(spec.fit)}"`
+      );
+    }
+    if (spec.quality !== void 0) {
+      const q = spec.quality;
+      if (typeof q !== "number" || !Number.isInteger(q) || q < 1 || q > 100) {
+        throw new Error(`bucket variant "${name}" quality must be an integer 1\u2013100, got ${String(q)}`);
+      }
+    }
+    if (spec.fit === "cover" && (spec.width === void 0 || spec.height === void 0)) {
+      throw new Error(`bucket variant "${name}" uses fit "cover", which needs BOTH width and height`);
+    }
     out[name] = {
       ...spec.width !== void 0 ? { width: spec.width } : {},
       ...spec.height !== void 0 ? { height: spec.height } : {},
-      ...spec.format !== void 0 ? { format: spec.format } : {}
+      ...spec.fit !== void 0 ? { fit: spec.fit } : {},
+      ...spec.format !== void 0 ? { format: spec.format } : {},
+      ...spec.quality !== void 0 ? { quality: spec.quality } : {}
     };
   }
   return out;
@@ -1935,6 +2892,57 @@ function defineFlags(input) {
   return { __config: FLAGS_CONFIG_KIND, flags };
 }
 
+// src/config/secrets.ts
+var SECRETS_CONFIG_KIND = "secrets";
+var SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+function secret(name, opts = {}) {
+  if (typeof name !== "string" || !SECRET_NAME_RE.test(name)) {
+    throw new Error(
+      `secret name ${JSON.stringify(name)} is invalid \u2014 must be an environment-variable name: an uppercase letter, then uppercase letters, digits, and underscores (e.g. "NEO4J_PASSWORD")`
+    );
+  }
+  if (opts === null || typeof opts !== "object") {
+    throw new Error(`secret("${name}") expects { required?, description? }`);
+  }
+  let required = true;
+  if (opts.required !== void 0) {
+    if (typeof opts.required !== "boolean") {
+      throw new Error(`secret("${name}") required must be a boolean`);
+    }
+    required = opts.required;
+  }
+  let description = null;
+  if (opts.description !== void 0) {
+    if (typeof opts.description !== "string") {
+      throw new Error(`secret("${name}") description must be a string`);
+    }
+    const trimmed = opts.description.trim();
+    description = trimmed.length > 0 ? trimmed : null;
+  }
+  return { name, required, description };
+}
+function defineSecrets(input) {
+  if (input === null || typeof input !== "object" || !Array.isArray(input.secrets)) {
+    throw new Error('defineSecrets expects { secrets: [secret("NAME"), ...] }');
+  }
+  const byName = /* @__PURE__ */ new Map();
+  for (const def of input.secrets) {
+    if (def === null || typeof def !== "object" || typeof def.name !== "string" || typeof def.required !== "boolean") {
+      throw new Error(
+        `defineSecrets: every entry must come from secret() \u2014 got ${JSON.stringify(def)}`
+      );
+    }
+    if (byName.has(def.name)) {
+      throw new Error(
+        `secret "${def.name}" is declared twice in config/secrets.ts \u2014 remove one; a name has exactly one requirement`
+      );
+    }
+    byName.set(def.name, def);
+  }
+  const secrets = [...byName.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  return { __config: SECRETS_CONFIG_KIND, secrets };
+}
+
 // src/decorators/registry.ts
 var ROUTES = /* @__PURE__ */ Symbol.for("palbase.backend.routes");
 var PARAM_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.paramBuffer");
@@ -2029,6 +3037,21 @@ function getRoutes(ctor) {
 
 // src/decorators/controller.ts
 var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
+var REGISTRY = /* @__PURE__ */ Symbol.for("palbase.backend.allControllers");
+function registry() {
+  const g = globalThis;
+  const existing = g[REGISTRY];
+  if (existing) return existing;
+  const fresh = [];
+  g[REGISTRY] = fresh;
+  return fresh;
+}
+function getRegisteredControllers() {
+  return registry().slice();
+}
+function __resetRegisteredControllers() {
+  registry().length = 0;
+}
 var RESERVED_FIRST_SEGMENT = "webhooks";
 function assertNotReserved(path, subject) {
   const [first] = path.split("/").filter(Boolean);
@@ -2065,6 +3088,8 @@ function Controller(basePath, options = {}) {
       configurable: true,
       writable: false
     });
+    const all = registry();
+    if (!all.includes(ctor)) all.push(ctor);
     return ctor;
   };
 }
@@ -2246,8 +3271,8 @@ function defineError(code, status, dataSchema) {
       `defineError: status for "${code}" must be a 4xx/5xx integer, got ${status} \u2014 error responses must not clobber success responses in the project spec.`
     );
   }
-  const registry2 = getErrorRegistry();
-  const existing = registry2.get(code);
+  const registry3 = getErrorRegistry();
+  const existing = registry3.get(code);
   const className = defaultClassName(code);
   const dataDigest = dataSchema ? digestOf(code, dataSchema) : void 0;
   if (existing) {
@@ -2276,7 +3301,7 @@ function defineError(code, status, dataSchema) {
   };
   const cls = dataSchema ? makeWithData(dataSchema) : makeWithoutData();
   Object.defineProperty(cls, "name", { value: className });
-  registry2.set(code, {
+  registry3.set(code, {
     code,
     status,
     className,
@@ -2533,16 +3558,16 @@ function hasSecrets(value) {
   const secrets = value.secrets;
   return secrets === void 0 || Array.isArray(secrets);
 }
-var registry = [];
+var registry2 = [];
 function __registerResource(resource) {
-  registry.push({ resource, booted: false });
+  registry2.push({ resource, booted: false });
 }
 function declaredSecrets(resource) {
   const ctor = resource.constructor;
   return hasSecrets(ctor) ? ctor.secrets ?? [] : [];
 }
 async function __runResourceBoot(envMap) {
-  for (const entry of registry) {
+  for (const entry of registry2) {
     if (entry.booted) continue;
     const secrets = declaredSecrets(entry.resource);
     const env = {};
@@ -2560,13 +3585,13 @@ async function __runResourceBoot(envMap) {
   }
 }
 async function __shutdownResources() {
-  for (let i = registry.length - 1; i >= 0; i -= 1) {
-    const entry = registry[i];
+  for (let i = registry2.length - 1; i >= 0; i -= 1) {
+    const entry = registry2[i];
     if (entry.booted && entry.resource.shutdown) {
       await entry.resource.shutdown();
     }
   }
-  registry.length = 0;
+  registry2.length = 0;
 }
 
 // src/hooks.ts
@@ -2639,6 +3664,7 @@ var import_zod2 = require("zod");
   PALBASE_EXTENSIONS,
   PROVIDER_CATALOG,
   PalError,
+  PalbaseModuleError,
   Param,
   Patch,
   PolicyBuilder,
@@ -2653,7 +3679,9 @@ var import_zod2 = require("zod");
   RequestId,
   RequireEntitlement,
   Resource,
+  SECRETS_CONFIG_KIND,
   STORAGE_CONFIG_KIND,
+  Secrets,
   Spend,
   Storage,
   TEST_USERS_CONFIG_KIND,
@@ -2669,6 +3697,7 @@ var import_zod2 = require("zod");
   __getRuntime,
   __registerResource,
   __requestALS,
+  __resetRegisteredControllers,
   __runResourceBoot,
   __runWithRuntime,
   __setRuntime,
@@ -2677,6 +3706,7 @@ var import_zod2 = require("zod");
   bigint,
   boolean,
   bucket,
+  buildModuleClients,
   buildProvider,
   dec,
   defineEgress,
@@ -2685,6 +3715,7 @@ var import_zod2 = require("zod");
   defineMiddleware,
   defineNotifications,
   defineSchema,
+  defineSecrets,
   defineStorage,
   defineTestUsers,
   documents,
@@ -2694,6 +3725,7 @@ var import_zod2 = require("zod");
   flag,
   getErrorRegistry,
   getJobConfig,
+  getRegisteredControllers,
   getRoutes,
   getWebhookConfig,
   inc,
@@ -2701,6 +3733,7 @@ var import_zod2 = require("zod");
   isPalbaseExtension,
   jsonb,
   makeEnvDts,
+  makeHttpClient,
   makePurchasesDts,
   makeTypedDB,
   now,
@@ -2710,11 +3743,13 @@ var import_zod2 = require("zod");
   raw,
   recordThrows,
   reservedSecretKey,
+  secret,
   spendFor,
   storage,
   testUser,
   text,
   timestamp,
+  toSchemaJSON,
   uuid,
   validateUploadAgainstStorage,
   z