@odla-ai/chapter 0.34.0 → 0.35.0

package/dist/worker/index.d.cts

@@ -209,6 +209,56 @@ interface ChapterPolicy {
  * (join, Stripe membership, booking, member area, admin, CRM); `hub` is
  * admin-only and CRM-focused (a directory/registry over the same CRM). */
 type ChapterMode = "chapter" | "hub";
+/** One odla-db transaction op — the wire shape both the real admin client and a
+ *  test double (`FakeDb`) accept. Built as a plain object, never via a `tx` proxy. */
+type DbOp<Id extends string | {
+    ns: string;
+    attr: string;
+    value: string | number | boolean;
+} = string> = {
+    t: "update" | "merge";
+    ns: string;
+    id: Id;
+    attrs: Record<string, unknown>;
+} | {
+    t: "retract";
+    ns: string;
+    id: Id;
+    attrs: string[];
+} | {
+    t: "delete";
+    ns: string;
+    id: Id;
+    attrs?: undefined;
+};
+/** The structural view of the odla-db admin client the worker builds and the
+ *  member routes consume — so route logic is testable against an in-memory fake. */
+interface ChapterDb {
+    query(q: Record<string, unknown>): Promise<Record<string, Array<Record<string, unknown>>>>;
+    /** Optional bounded aggregate supported by the real privileged odla-db
+     * client. Routes use it to prove a result set is non-empty before issuing
+     * an ordered lookup, while small test doubles may continue to omit it. */
+    aggregate?(ns: string, spec: {
+        count?: boolean;
+    }, opts?: {
+        where?: Record<string, unknown>;
+    }): Promise<{
+        count?: number;
+    }>;
+    transact(ops: DbOp<string | {
+        ns: string;
+        attr: string;
+        value: string | number | boolean;
+    }>[], opts?: {
+        mutationId?: string;
+    }): Promise<{
+        txId: number;
+        duplicate: boolean;
+    }>;
+    secrets: {
+        get(name: string): Promise<string>;
+    };
+}
 /** The scalar kinds an odla-db attribute can hold. */
 type AttrType = "string" | "number" | "boolean" | "json";
 /** One odla-db attribute: its type and index/uniqueness/optionality flags. */
@@ -790,6 +840,54 @@ interface SignupControlDeliveryOptions {
 /** Build and send one signed desired-state delivery. Durable retry belongs to the hub outbox. */
 declare function deliverSignupControl(options: SignupControlDeliveryOptions): Promise<SignupControlReceipt>;
 
+/** Identity shared by initial HTML, response caching, and client hydration. */
+interface SignupControlThemeMetadata {
+    source: "active" | "bootstrap";
+    revision: number | null;
+    digest: string | null;
+    /** Include this value in any host-owned cache key for transformed HTML. */
+    cacheKey: string;
+}
+/** A validated style block ready to place in an HTML head. */
+interface SignupControlThemeHead {
+    css: string;
+    head: string;
+    metadata: SignupControlThemeMetadata;
+}
+/** Host-owned fallback inputs shared by server rendering and hydration. */
+interface SignupControlThemeOptions {
+    /** Local site-owned tokens used only when no active managed revision exists. */
+    bootstrapTokens?: Readonly<Record<string, string | number>>;
+}
+
+/** Inputs required to resolve one follower-local active signup theme. */
+interface ActiveSignupControlThemeOptions extends SignupControlThemeOptions {
+    /** Follower-local database client. No controlling-hub request is performed. */
+    db: ChapterDb;
+    chapterId: string;
+    environment: string;
+    /** Optional host marker; defaults to `SIGNUP_CONTROL_THEME_MARKER`. */
+    marker?: string;
+}
+/** Transformed HTML plus the exact theme and cache identity it contains. */
+interface ActiveSignupControlHtml {
+    html: string;
+    theme: SignupControlThemeHead;
+}
+/**
+ * Transform trusted host HTML with the follower-local last-known-good signup
+ * theme. A missing active revision uses the documented bootstrap state; a read
+ * failure or corrupt active row fails closed instead of fetching the hub.
+ */
+declare function renderActiveSignupControlHtml(html: string, options: ActiveSignupControlThemeOptions): Promise<ActiveSignupControlHtml>;
+/**
+ * Transform an HTML response and make the cache contract safe by default.
+ * `no-store` prevents a prior digest from surviving activation; hosts that own
+ * a cache may instead key it with `result.theme.metadata.cacheKey` from
+ * {@link renderActiveSignupControlHtml}.
+ */
+declare function withActiveSignupControlTheme(response: Response, options: ActiveSignupControlThemeOptions): Promise<Response>;
+
 /**
  * Build the Cloudflare `ExportedHandler` for a chapter/hub site: Clerk-JWT
  * verification, the source-aware admin gate, the mounted @odla-ai/crm routes, the
@@ -812,4 +910,4 @@ declare function chapterWorker(options: ChapterWorkerOptions): {
     fetch(req: Request, env: ChapterEnv): Promise<Response>;
 };
 
-export { type ChapterEnv, type ChapterWorkerOptions, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterWorker, createWorkerContext, deliverSignupControl };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, type ChapterEnv, type ChapterWorkerOptions, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterWorker, createWorkerContext, deliverSignupControl, renderActiveSignupControlHtml, withActiveSignupControlTheme };

package/dist/worker/index.d.ts

@@ -209,6 +209,56 @@ interface ChapterPolicy {
  * (join, Stripe membership, booking, member area, admin, CRM); `hub` is
  * admin-only and CRM-focused (a directory/registry over the same CRM). */
 type ChapterMode = "chapter" | "hub";
+/** One odla-db transaction op — the wire shape both the real admin client and a
+ *  test double (`FakeDb`) accept. Built as a plain object, never via a `tx` proxy. */
+type DbOp<Id extends string | {
+    ns: string;
+    attr: string;
+    value: string | number | boolean;
+} = string> = {
+    t: "update" | "merge";
+    ns: string;
+    id: Id;
+    attrs: Record<string, unknown>;
+} | {
+    t: "retract";
+    ns: string;
+    id: Id;
+    attrs: string[];
+} | {
+    t: "delete";
+    ns: string;
+    id: Id;
+    attrs?: undefined;
+};
+/** The structural view of the odla-db admin client the worker builds and the
+ *  member routes consume — so route logic is testable against an in-memory fake. */
+interface ChapterDb {
+    query(q: Record<string, unknown>): Promise<Record<string, Array<Record<string, unknown>>>>;
+    /** Optional bounded aggregate supported by the real privileged odla-db
+     * client. Routes use it to prove a result set is non-empty before issuing
+     * an ordered lookup, while small test doubles may continue to omit it. */
+    aggregate?(ns: string, spec: {
+        count?: boolean;
+    }, opts?: {
+        where?: Record<string, unknown>;
+    }): Promise<{
+        count?: number;
+    }>;
+    transact(ops: DbOp<string | {
+        ns: string;
+        attr: string;
+        value: string | number | boolean;
+    }>[], opts?: {
+        mutationId?: string;
+    }): Promise<{
+        txId: number;
+        duplicate: boolean;
+    }>;
+    secrets: {
+        get(name: string): Promise<string>;
+    };
+}
 /** The scalar kinds an odla-db attribute can hold. */
 type AttrType = "string" | "number" | "boolean" | "json";
 /** One odla-db attribute: its type and index/uniqueness/optionality flags. */
@@ -790,6 +840,54 @@ interface SignupControlDeliveryOptions {
 /** Build and send one signed desired-state delivery. Durable retry belongs to the hub outbox. */
 declare function deliverSignupControl(options: SignupControlDeliveryOptions): Promise<SignupControlReceipt>;
 
+/** Identity shared by initial HTML, response caching, and client hydration. */
+interface SignupControlThemeMetadata {
+    source: "active" | "bootstrap";
+    revision: number | null;
+    digest: string | null;
+    /** Include this value in any host-owned cache key for transformed HTML. */
+    cacheKey: string;
+}
+/** A validated style block ready to place in an HTML head. */
+interface SignupControlThemeHead {
+    css: string;
+    head: string;
+    metadata: SignupControlThemeMetadata;
+}
+/** Host-owned fallback inputs shared by server rendering and hydration. */
+interface SignupControlThemeOptions {
+    /** Local site-owned tokens used only when no active managed revision exists. */
+    bootstrapTokens?: Readonly<Record<string, string | number>>;
+}
+
+/** Inputs required to resolve one follower-local active signup theme. */
+interface ActiveSignupControlThemeOptions extends SignupControlThemeOptions {
+    /** Follower-local database client. No controlling-hub request is performed. */
+    db: ChapterDb;
+    chapterId: string;
+    environment: string;
+    /** Optional host marker; defaults to `SIGNUP_CONTROL_THEME_MARKER`. */
+    marker?: string;
+}
+/** Transformed HTML plus the exact theme and cache identity it contains. */
+interface ActiveSignupControlHtml {
+    html: string;
+    theme: SignupControlThemeHead;
+}
+/**
+ * Transform trusted host HTML with the follower-local last-known-good signup
+ * theme. A missing active revision uses the documented bootstrap state; a read
+ * failure or corrupt active row fails closed instead of fetching the hub.
+ */
+declare function renderActiveSignupControlHtml(html: string, options: ActiveSignupControlThemeOptions): Promise<ActiveSignupControlHtml>;
+/**
+ * Transform an HTML response and make the cache contract safe by default.
+ * `no-store` prevents a prior digest from surviving activation; hosts that own
+ * a cache may instead key it with `result.theme.metadata.cacheKey` from
+ * {@link renderActiveSignupControlHtml}.
+ */
+declare function withActiveSignupControlTheme(response: Response, options: ActiveSignupControlThemeOptions): Promise<Response>;
+
 /**
  * Build the Cloudflare `ExportedHandler` for a chapter/hub site: Clerk-JWT
  * verification, the source-aware admin gate, the mounted @odla-ai/crm routes, the
@@ -812,4 +910,4 @@ declare function chapterWorker(options: ChapterWorkerOptions): {
     fetch(req: Request, env: ChapterEnv): Promise<Response>;
 };
 
-export { type ChapterEnv, type ChapterWorkerOptions, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterWorker, createWorkerContext, deliverSignupControl };
+export { type ActiveSignupControlHtml, type ActiveSignupControlThemeOptions, type ChapterEnv, type ChapterWorkerOptions, type Route, type SignupControlDeliveryOptions, type WorkerContext, chapterWorker, createWorkerContext, deliverSignupControl, renderActiveSignupControlHtml, withActiveSignupControlTheme };

package/dist/worker/index.js

@@ -1727,12 +1727,18 @@ function themeOf(value, errors) {
   }
   unknownKeys(input, /* @__PURE__ */ new Set(["tokens"]), "document.theme", errors);
   if (Object.keys(tokens).length > 256) errors.push("document.theme.tokens supports at most 256 entries");
+  let serializedLength = 0;
   for (const [key, token] of Object.entries(tokens)) {
-    if (!/^--[a-z0-9-]{1,100}$/.test(key)) errors.push(`document.theme.tokens.${key} must be a CSS custom-property name`);
-    if (typeof token !== "string" && typeof token !== "number" || String(token).length > 1e3) {
-      errors.push(`document.theme.tokens.${key} must be a bounded string or number`);
+    if (!/^--ui-[a-z0-9][a-z0-9-]{0,94}$/.test(key)) {
+      errors.push(`document.theme.tokens.${key} must be an allowlisted --ui-* custom property`);
+    }
+    const rendered = String(token).trim();
+    serializedLength += key.length + rendered.length + 4;
+    if (typeof token !== "string" && typeof token !== "number" || typeof token === "number" && !Number.isFinite(token) || !rendered || rendered.length > 1e3 || /[\u0000-\u001f\u007f\\<>{};]|\/\*|\*\/|(?:^|[^a-z])(?:url|expression)\s*\(|@import/i.test(rendered)) {
+      errors.push(`document.theme.tokens.${key} must be a bounded breakout-safe CSS value`);
     }
   }
+  if (serializedLength > 65536) errors.push("document.theme.tokens exceeds the serialized size bound");
   return { tokens };
 }
 function validateSignupControlDocument(input) {
@@ -4058,6 +4064,137 @@ async function deliverSignupControl(options) {
   return result;
 }
 
+// src/signup-control-theme.ts
+var SIGNUP_CONTROL_THEME_MARKER = "<!--odla:signup-control-theme-->";
+var SIGNUP_CONTROL_THEME_STYLE_ID = "odla-signup-control-theme";
+var TOKEN_NAME = /^--ui-[a-z0-9][a-z0-9-]{0,94}$/;
+var DIGEST = /^sha256:[0-9a-f]{64}$/;
+var UNSAFE_VALUE = /[\u0000-\u001f\u007f\\<>{};]|\/\*|\*\/|(?:^|[^a-z])(?:url|expression)\s*\(|@import/i;
+var MAX_TOKENS = 256;
+var MAX_VALUE_LENGTH = 1e3;
+var MAX_SERIALIZED_LENGTH = 65536;
+function validatedTokens(input) {
+  const entries = Object.entries(input ?? {});
+  if (entries.length > MAX_TOKENS) {
+    throw new TypeError(`signup-control theme supports at most ${MAX_TOKENS} tokens`);
+  }
+  const tokens = {};
+  let serializedLength = 0;
+  for (const [name, raw] of entries.sort(([left], [right]) => left.localeCompare(right))) {
+    if (!TOKEN_NAME.test(name)) {
+      throw new TypeError(`signup-control theme token "${name}" must be an allowlisted --ui-* property`);
+    }
+    if (typeof raw !== "string" && typeof raw !== "number" || typeof raw === "number" && !Number.isFinite(raw)) {
+      throw new TypeError(`signup-control theme token "${name}" must be a finite string or number`);
+    }
+    const value = String(raw).trim();
+    if (!value || value.length > MAX_VALUE_LENGTH || UNSAFE_VALUE.test(value)) {
+      throw new TypeError(`signup-control theme token "${name}" has an unsafe or oversized value`);
+    }
+    serializedLength += name.length + value.length + 4;
+    if (serializedLength > MAX_SERIALIZED_LENGTH) {
+      throw new TypeError("signup-control theme exceeds the serialized size bound");
+    }
+    tokens[name] = value;
+  }
+  return tokens;
+}
+function cssFor(tokens) {
+  const declarations = Object.entries(tokens).map(([name, value]) => `  ${name}: ${value};`);
+  return declarations.length ? `:root {
+${declarations.join("\n")}
+}` : "";
+}
+function stateFor(revision, options) {
+  if (!revision) {
+    return {
+      css: cssFor(validatedTokens(options.bootstrapTokens)),
+      metadata: { source: "bootstrap", revision: null, digest: null, cacheKey: "signup-control:bootstrap" }
+    };
+  }
+  if (!Number.isSafeInteger(revision.revision) || revision.revision < 1 || !DIGEST.test(revision.digest)) {
+    throw new TypeError("signup-control theme revision metadata is invalid");
+  }
+  return {
+    css: cssFor(validatedTokens(revision.theme?.tokens)),
+    metadata: {
+      source: "active",
+      revision: revision.revision,
+      digest: revision.digest,
+      cacheKey: `signup-control:${revision.digest}`
+    }
+  };
+}
+function attributes(metadata) {
+  return [
+    `id="${SIGNUP_CONTROL_THEME_STYLE_ID}"`,
+    `data-signup-control-source="${metadata.source}"`,
+    `data-signup-control-cache-key="${metadata.cacheKey}"`,
+    ...metadata.revision === null ? [] : [`data-signup-control-revision="${metadata.revision}"`],
+    ...metadata.digest === null ? [] : [`data-signup-control-digest="${metadata.digest}"`]
+  ].join(" ");
+}
+function renderSignupControlThemeHead(revision, options = {}) {
+  const { css, metadata } = stateFor(revision, options);
+  return { css, metadata, head: `<style ${attributes(metadata)}>${css}</style>` };
+}
+function injectSignupControlThemeHead(html, rendered, marker = SIGNUP_CONTROL_THEME_MARKER) {
+  const existing = /<style\b(?=[^>]*\bid\s*=\s*["']odla-signup-control-theme["'])[^>]*>[\s\S]*?<\/style>/gi;
+  const existingBlocks = html.match(existing) ?? [];
+  if (existingBlocks.length > 1) {
+    throw new TypeError("signup-control theme style block must appear at most once");
+  }
+  if (existingBlocks.length === 1) return html.replace(existing, rendered.head);
+  const markerIndex = html.indexOf(marker);
+  if (markerIndex >= 0) {
+    if (html.indexOf(marker, markerIndex + marker.length) >= 0) {
+      throw new TypeError("signup-control theme marker must appear exactly once");
+    }
+    return `${html.slice(0, markerIndex)}${rendered.head}${html.slice(markerIndex + marker.length)}`;
+  }
+  const closingHead = html.search(/<\/head\s*>/i);
+  if (closingHead < 0) throw new TypeError("signup-control theme requires an HTML head");
+  return `${html.slice(0, closingHead)}${rendered.head}${html.slice(closingHead)}`;
+}
+
+// src/signup-control-theme-worker.ts
+async function activeTheme(options) {
+  const active = await loadActiveSignupControl(options.db, options.chapterId, options.environment);
+  if (!active) return null;
+  const checked = validateSignupControlDocument(active.document);
+  if (!checked.ok) throw new TypeError(`active signup-control document is invalid: ${checked.errors.join("; ")}`);
+  const document = checked.value;
+  if (document.revision !== active.revision || document.target.chapterId !== options.chapterId || document.target.environment !== options.environment || active.digest !== await signupControlDigest(document)) {
+    throw new TypeError("active signup-control revision metadata or digest is invalid");
+  }
+  return { revision: active.revision, digest: active.digest, theme: document.theme };
+}
+async function renderActiveSignupControlHtml(html, options) {
+  const theme = renderSignupControlThemeHead(await activeTheme(options), {
+    bootstrapTokens: options.bootstrapTokens
+  });
+  return { html: injectSignupControlThemeHead(html, theme, options.marker), theme };
+}
+async function contentEtag(html) {
+  const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(html));
+  const hex = Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `W/"sha256-${hex}"`;
+}
+async function withActiveSignupControlTheme(response, options) {
+  if (!response.ok || !(response.headers.get("content-type") ?? "").toLowerCase().includes("text/html")) {
+    throw new TypeError("signup-control theme can only transform a successful HTML response");
+  }
+  const rendered = await renderActiveSignupControlHtml(await response.text(), options);
+  const headers = new Headers(response.headers);
+  headers.delete("content-length");
+  headers.set("cache-control", "no-store");
+  headers.set("etag", await contentEtag(rendered.html));
+  headers.set("x-odla-signup-control-digest", rendered.theme.metadata.digest ?? "bootstrap");
+  if (rendered.theme.metadata.revision === null) headers.delete("x-odla-signup-control-revision");
+  else headers.set("x-odla-signup-control-revision", String(rendered.theme.metadata.revision));
+  return new Response(rendered.html, { status: response.status, statusText: response.statusText, headers });
+}
+
 // src/worker.ts
 var BUILTIN_ROUTES = [
   handleHealth,
@@ -4124,6 +4261,8 @@ function chapterWorker(options) {
 export {
   chapterWorker,
   createWorkerContext,
-  deliverSignupControl
+  deliverSignupControl,
+  renderActiveSignupControlHtml,
+  withActiveSignupControlTheme
 };
 //# sourceMappingURL=index.js.map