npm - @tokenoftrust/storefront-runner - Versions diffs - 1.3.2 - Mend

@tokenoftrust/storefront-runner 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (310) hide show

package/apps/storefront/src/lib/storyblok/provider.ts ADDED Viewed

@@ -0,0 +1,607 @@
+/**
+ * ContentProvider — the Storyblok seam (brief §7 CMS).
+ *
+ * Two implementations behind one interface:
+ *   - StoryblokContentProvider — calls the Storyblok delivery API for a tenant's
+ *     child space, maps stories -> our content model.
+ *   - LocalContentProvider     — reads src/content/pilot/*.json, so the site
+ *     renders fully OFFLINE with no Storyblok token.
+ *
+ * Selection: if the tenant has a usable delivery token AND the Storyblok client
+ * is configured, use Storyblok; otherwise fall back to local. Phase 1 ships with
+ * a placeholder token, so the LOCAL provider is what actually renders. The
+ * mapping layer is the documented swap point — Storyblok story JSON shares the
+ * same `component` discriminators as our blocks, so the parent-space schemas map
+ * 1:1. See DECISIONS.md.
+ */
+import type {
+  EditorialPage,
+  HomeContent,
+  SiteChrome,
+} from "./content-model.js";
+import type { CustomizationEnv, KvGet, TenantConfig } from "@tot/public-runtime";
+import { contentArtifactPath, readPublishedArtifact } from "@tot/public-runtime";
+import { renderRawChrome } from "../rawChrome.js";
+import { parseChromeConfig } from "../chrome/parseConfig.js";
+export interface ContentProvider {
+  getHome(): Promise<HomeContent>;
+  /**
+   * A marketing tenant's self-authored home document (raw HTML), or null. When
+   * present the homepage route serves it VERBATIM (bypassing the block Layout) —
+   * the "vendor injects their own HTML" path. Full `<!doctype html>` document;
+   * the route nonces its inline <style>/<script> so it still satisfies CSP.
+   */
+  getHomeHtml(): Promise<string | null>;
+  /**
+   * A marketing tenant's self-authored SUBPAGE document (raw HTML) for `slug`,
+   * or null. Same verbatim-serve path as getHomeHtml — the catch-all route
+   * (`[...slug].astro`) serves it bypassing the block Layout and nonces its
+   * inline tags. Files live at `content/<tenant>/pages-html/<slug>.html`.
+   */
+  getPageHtml(slug: string): Promise<string | null>;
+  /** Slugs of this tenant's raw subpages (for the sitemap). */
+  listPageHtmlSlugs(): Promise<string[]>;
+  /**
+   * The tenant's shared-chrome WRAPPER document (raw HTML), or null. A full
+   * document containing the CHROME_BODY_MARKER where a body-only page fragment is
+   * spliced in (see lib/rawMarketingHtml.ts). Lets raw pages stop duplicating
+   * chrome: chrome lives once here, pages become fragments. File:
+   * `content/<tenant>/chrome.html`. Tenant-owned (no cross-tenant fallback).
+   */
+  getChromeHtml(): Promise<string | null>;
+  getChrome(): Promise<SiteChrome>;
+  getPage(slug: string): Promise<EditorialPage | null>;
+  listPages(): Promise<EditorialPage[]>;
+}
+// ---------------------------------------------------------------------------
+// LocalContentProvider — static JSON bundled at build time.
+// ---------------------------------------------------------------------------
+// Per-tenant local content lives under the colocated repo-root layout
+// tenants/<tenant_id>/content/. Vite globs bundle every tenant's JSON at build
+// time; a file missing for a tenant falls back to the default scope, so a
+// partially-adopted tenant still renders. Depth: from src/lib/storyblok/ the
+// repo root is five levels up (storyblok→lib→src→storefront→apps→root).
+const homeGlobs = import.meta.glob<HomeContent>("../../../../../tenants/*/content/home.json", {
+  import: "default",
+});
+const chromeGlobs = import.meta.glob<SiteChrome>("../../../../../tenants/*/content/chrome.json", {
+  import: "default",
+});
+const pageGlobs = import.meta.glob<EditorialPage>("../../../../../tenants/*/content/pages/*.json", {
+  import: "default",
+});
+// Raw self-authored home documents (marketing tenants). `?raw` bundles the file
+// as a string; a tenant with no home.html simply has no entry here.
+const homeHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/home.html", {
+  query: "?raw",
+  import: "default",
+});
+// Raw self-authored SUBPAGE documents: tenants/<tenant>/content/pages-html/<slug>.html
+// (e.g. pages-html/pricing.html -> /pricing/). `**` supports nested slugs.
+const pageHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/pages-html/**/*.html", {
+  query: "?raw",
+  import: "default",
+});
+// Shared-chrome wrapper document (marketing tenants that author body-only page
+// fragments). One per tenant; a tenant without it keeps serving full documents.
+const chromeHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/chrome.html", {
+  query: "?raw",
+  import: "default",
+});
+const DEFAULT_SCOPE = "home";
+function pickContent<T>(
+  globs: Record<string, () => Promise<T>>,
+  scope: string,
+): (() => Promise<T>) | null {
+  const seg = `/tenants/${scope}/content/`;
+  const key = Object.keys(globs).find((k) => k.includes(seg));
+  return (key ? globs[key] : null) ?? null;
+}
+function pickPages(scope: string): Array<() => Promise<EditorialPage>> {
+  const seg = `/tenants/${scope}/content/pages/`;
+  return Object.keys(pageGlobs)
+    .filter((k) => k.includes(seg))
+    .map((k) => pageGlobs[k]!);
+}
+/** Normalize a route slug to the file stem: strip surrounding slashes + .html. */
+function normalizeRawPageSlug(slug: string): string {
+  return slug.replace(/^\/+|\/+$/g, "").replace(/\.html$/i, "");
+}
+/** The subpage slug a glob key encodes for `scope`, or null if it's not one. */
+function rawPageSlugForKey(scope: string, key: string): string | null {
+  const seg = `/tenants/${scope}/content/pages-html/`;
+  const start = key.indexOf(seg);
+  if (start < 0 || !key.endsWith(".html")) return null;
+  return key.slice(start + seg.length, -".html".length);
+}
+function pickPageHtml(scope: string, slug: string): (() => Promise<string>) | null {
+  const wanted = normalizeRawPageSlug(slug);
+  if (!wanted) return null;
+  const key = Object.keys(pageHtmlGlobs).find(
+    (k) => rawPageSlugForKey(scope, k) === wanted,
+  );
+  return key ? pageHtmlGlobs[key]! : null;
+}
+/**
+ * DEV hot-reload for raw tenant HTML. The `?raw` import.meta.glob above bundles
+ * each file's contents at server boot, so an edit to tenants/<id>/content/*.html
+ * would NOT preview until a full rebuild — the "magic on save" gap. In dev we read
+ * the file from disk at REQUEST time instead, so an edit shows on the next request.
+ *
+ * Prod: import.meta.env.DEV is statically false, so this whole branch tree-shakes
+ * out and the bundled glob is used — node:fs never enters the Worker. If fs is
+ * unavailable (e.g. the workerd dev runtime) or the file is missing, we return null
+ * and the caller falls back to the glob, so behavior is never worse than before.
+ */
+async function readRawDevFile(scope: string, relative: string): Promise<string | null> {
+  if (!import.meta.env.DEV) return null;
+  try {
+    const [{ readFile }, { fileURLToPath }, { resolve, dirname }] = await Promise.all([
+      import("node:fs/promises"),
+      import("node:url"),
+      import("node:path"),
+    ]);
+    // provider.ts lives at apps/storefront/src/lib/storyblok/ — the repo root is five
+    // levels up, mirroring the import.meta.glob prefix ("../../../../../tenants/...").
+    const here = dirname(fileURLToPath(import.meta.url));
+    const abs = resolve(here, "../../../../..", "tenants", scope, "content", relative);
+    return await readFile(abs, "utf8");
+  } catch {
+    return null;
+  }
+}
+export class LocalContentProvider implements ContentProvider {
+  constructor(private readonly scope: string = DEFAULT_SCOPE) {}
+  async getHome(): Promise<HomeContent> {
+    const loader = pickContent(homeGlobs, this.scope) ?? pickContent(homeGlobs, DEFAULT_SCOPE);
+    if (!loader) throw new Error("no home content");
+    return loader();
+  }
+  async getHomeHtml(): Promise<string | null> {
+    // DEV: serve fresh from disk so an edit previews on save (see readRawDevFile).
+    const dev = await readRawDevFile(this.scope, "home.html");
+    if (dev !== null) return dev;
+    // Tenant-owned only (no cross-tenant fallback): a raw home document is a
+    // whole-page identity, never inherited from the default scope.
+    const loader = pickContent(homeHtmlGlobs, this.scope);
+    return loader ? loader() : null;
+  }
+  async getPageHtml(slug: string): Promise<string | null> {
+    // DEV: serve fresh from disk so a subpage edit previews on save.
+    const dev = await readRawDevFile(this.scope, `pages-html/${normalizeRawPageSlug(slug)}.html`);
+    if (dev !== null) return dev;
+    // Tenant-owned only, like getHomeHtml — raw subpages are whole-page identity.
+    const loader = pickPageHtml(this.scope, slug);
+    return loader ? loader() : null;
+  }
+  async listPageHtmlSlugs(): Promise<string[]> {
+    return Object.keys(pageHtmlGlobs)
+      .map((k) => rawPageSlugForKey(this.scope, k))
+      .filter((slug): slug is string => !!slug)
+      .sort((a, b) => a.localeCompare(b));
+  }
+  async getChromeHtml(): Promise<string | null> {
+    // (1) A hand-authored chrome.html wins — keeps a not-yet-adopted tenant's chrome
+    //     byte-identical (dev: fresh from disk so an edit previews on save).
+    const dev = await readRawDevFile(this.scope, "chrome.html");
+    if (dev !== null) return dev;
+    const loader = pickContent(chromeHtmlGlobs, this.scope);
+    if (loader) return loader();
+    // (2) No chrome.html: render the CANONICAL shared chrome (unit F3) from the
+    //     tenant's chrome.json — but only when it opted in (sharedChrome: true).
+    //     Tenant-owned only, like the raw HTML above (no cross-tenant fallback).
+    const config = await this.loadChromeConfig();
+    return config ? renderRawChrome(config) : null;
+  }
+  /** The tenant's parsed raw-chrome config (chrome.json), or null if not adopted. */
+  private async loadChromeConfig(): Promise<ReturnType<typeof parseChromeConfig>> {
+    // DEV: read chrome.json fresh from disk so a config edit previews on save.
+    const devRaw = await readRawDevFile(this.scope, "chrome.json");
+    if (devRaw !== null) {
+      try {
+        return parseChromeConfig(JSON.parse(devRaw));
+      } catch {
+        return null;
+      }
+    }
+    const loader = pickContent(chromeGlobs, this.scope);
+    return loader ? parseChromeConfig(await loader()) : null;
+  }
+  async getChrome(): Promise<SiteChrome> {
+    const defL = pickContent(chromeGlobs, DEFAULT_SCOPE);
+    const def: SiteChrome = defL
+      ? await defL()
+      : { nav: [], footer: { columns: [], social: [] } };
+    const ownL = pickContent(chromeGlobs, this.scope);
+    if (!ownL) return def;
+    const c = await ownL();
+    if (this.scope === DEFAULT_SCOPE) return c;
+    // Per-field fallback fills only STRUCTURAL scaffolding (nav/footer) so a
+    // partially-adopted tenant still renders. Promotional/identity/legal fields
+    // (announcement, headerCtas, disclaimers) are tenant-OWNED and never inherit
+    // from the default scope — otherwise e.g. a marketing tenant would show the
+    // default store's shipping banner or nicotine disclaimers.
+    return {
+      nav: c.nav?.length ? c.nav : def.nav,
+      footer:
+        c.footer && (c.footer.columns?.length || c.footer.social?.length)
+          ? c.footer
+          : def.footer,
+      headerCtas: c.headerCtas,
+      announcement: c.announcement,
+      disclaimer: c.disclaimer,
+      disclaimers: c.disclaimers,
+    };
+  }
+  async getPage(slug: string): Promise<EditorialPage | null> {
+    return (await this.listPages()).find((p) => p.slug === slug) ?? null;
+  }
+  async listPages(): Promise<EditorialPage[]> {
+    // Editorial pages are NOT cross-tenant: a distinct tenant with no pages of
+    // its own returns none rather than inheriting the default scope's pages.
+    // (Serving e.g. pilot's privacy/legal copy under another brand would be a
+    // content/compliance leak; marketing tenants keep legal pages external.)
+    const loaders = pickPages(this.scope);
+    return Promise.all(loaders.map((l) => l()));
+  }
+}
+// ---------------------------------------------------------------------------
+// StoryblokContentProvider — live delivery API, mapping stories -> our model.
+//
+// Every method tries the Storyblok delivery API and falls back to
+// LocalContentProvider on ANY failure (no token, network error, non-2xx, or a
+// story whose shape doesn't map) — so the site never breaks. The map* fns assume
+// the Storyblok components mirror content-model.ts (same `component`
+// discriminators / shared parent-space schema, per DECISIONS.md). If your space
+// uses different field names, adjust the map* fns — that's the single seam.
+//
+// Config via env: STORYBLOK_REGION (eu|us|ap|ca, default eu),
+// STORYBLOK_VERSION (published|draft, default published).
+// ---------------------------------------------------------------------------
+const STORYBLOK_REGION_BASES: Record<string, string> = {
+  eu: "https://api.storyblok.com",
+  us: "https://api-us.storyblok.com",
+  ap: "https://api-ap.storyblok.com",
+  ca: "https://api-ca.storyblok.com",
+};
+function storyblokBase(): string {
+  const region = (import.meta.env.STORYBLOK_REGION ?? "eu").toLowerCase();
+  return STORYBLOK_REGION_BASES[region] ?? STORYBLOK_REGION_BASES.eu!;
+}
+function storyblokVersion(): "published" | "draft" {
+  return import.meta.env.STORYBLOK_VERSION === "draft" ? "draft" : "published";
+}
+interface StoryblokStory {
+  slug: string;
+  full_slug: string;
+  name: string;
+  content: Record<string, any>;
+}
+// Cap Storyblok latency so a slow/unreachable CMS can't hang the Worker — on
+// timeout (or any error) the caller falls back to LocalContentProvider. The
+// storefront must always render. (Epic S4 / S3.)
+const STORYBLOK_TIMEOUT_MS = 1500;
+async function fetchStoryblokJson<T>(url: string): Promise<T | null> {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(STORYBLOK_TIMEOUT_MS) });
+    if (!res.ok) return null;
+    return (await res.json()) as T;
+  } catch {
+    // Network error, non-2xx already handled, or AbortSignal timeout.
+    return null;
+  }
+}
+async function fetchStory(token: string, slug: string): Promise<StoryblokStory | null> {
+  const url =
+    `${storyblokBase()}/v2/cdn/stories/${slug}` +
+    `?token=${encodeURIComponent(token)}&version=${storyblokVersion()}`;
+  const json = await fetchStoryblokJson<{ story?: StoryblokStory }>(url);
+  return json?.story ?? null;
+}
+async function fetchStories(token: string, startsWith: string): Promise<StoryblokStory[]> {
+  const url =
+    `${storyblokBase()}/v2/cdn/stories` +
+    `?starts_with=${encodeURIComponent(startsWith)}` +
+    `&token=${encodeURIComponent(token)}&version=${storyblokVersion()}&per_page=100`;
+  const json = await fetchStoryblokJson<{ stories?: StoryblokStory[] }>(url);
+  return json?.stories ?? [];
+}
+function mapHome(content: Record<string, any>): HomeContent {
+  // Storyblok nests the block list under `body` (array of bloks, each with its
+  // own `component`); our HomeBlock union uses the same discriminator.
+  const blocks = Array.isArray(content.body)
+    ? content.body
+    : Array.isArray(content.blocks)
+      ? content.blocks
+      : [];
+  if (blocks.length === 0) throw new Error("storyblok home: no blocks");
+  return {
+    seoTitle: content.seoTitle ?? content.seo_title,
+    seoDescription: content.seoDescription ?? content.seo_description,
+    blocks: blocks as HomeContent["blocks"],
+  };
+}
+function mapPage(content: Record<string, any>, slug: string): EditorialPage {
+  // Expect a rendered-HTML field (text/markdown component). A raw richtext object
+  // would need a resolver — we throw so the local fallback serves it instead.
+  const body_html = content.body_html ?? content.body;
+  if (typeof body_html !== "string") throw new Error(`storyblok page ${slug}: body not HTML`);
+  return {
+    slug: slug.replace(/^pages\//, ""),
+    title: content.title ?? slug,
+    seoTitle: content.seoTitle ?? content.seo_title,
+    seoDescription: content.seoDescription ?? content.seo_description,
+    body_html,
+    eyebrow: content.eyebrow,
+    intro: content.intro,
+    isPolicy: !!content.isPolicy,
+  };
+}
+export class StoryblokContentProvider implements ContentProvider {
+  constructor(
+    private readonly token: string,
+    private readonly fallback: ContentProvider = new LocalContentProvider(),
+  ) {}
+  async getHome(): Promise<HomeContent> {
+    try {
+      const story = await fetchStory(this.token, "home");
+      if (story) return mapHome(story.content);
+    } catch {
+      /* fall back */
+    }
+    return this.fallback.getHome();
+  }
+  getHomeHtml(): Promise<string | null> {
+    // Raw home documents live in tenant content files, not Storyblok — delegate.
+    return this.fallback.getHomeHtml();
+  }
+  getPageHtml(slug: string): Promise<string | null> {
+    return this.fallback.getPageHtml(slug);
+  }
+  listPageHtmlSlugs(): Promise<string[]> {
+    return this.fallback.listPageHtmlSlugs();
+  }
+  getChromeHtml(): Promise<string | null> {
+    // The chrome wrapper lives in tenant content files, not Storyblok — delegate.
+    return this.fallback.getChromeHtml();
+  }
+  async getChrome(): Promise<SiteChrome> {
+    // Editorial chrome (nav/footer/tagline) is authored in Storyblok; the
+    // announcement + legal disclaimers are MIGRATION-sourced (written to local
+    // chrome.json), so overlay those from the fallback regardless.
+    const local = await this.fallback.getChrome();
+    try {
+      const story = await fetchStory(this.token, "chrome");
+      const c = story?.content;
+      if (c && Array.isArray(c.nav)) {
+        return {
+          nav: c.nav,
+          footer: c.footer ?? local.footer,
+          announcement: local.announcement ?? c.announcement,
+          disclaimer: local.disclaimer,
+          disclaimers: local.disclaimers,
+        };
+      }
+    } catch {
+      /* fall back */
+    }
+    return local;
+  }
+  async getPage(slug: string): Promise<EditorialPage | null> {
+    try {
+      const story = await fetchStory(this.token, `pages/${slug}`);
+      if (story) return mapPage(story.content, story.full_slug ?? slug);
+    } catch {
+      /* fall back */
+    }
+    return this.fallback.getPage(slug);
+  }
+  async listPages(): Promise<EditorialPage[]> {
+    try {
+      const stories = await fetchStories(this.token, "pages/");
+      const pages = stories
+        .map((s) => {
+          try {
+            return mapPage(s.content, s.full_slug ?? s.slug);
+          } catch {
+            return null;
+          }
+        })
+        .filter((p): p is EditorialPage => p !== null);
+      if (pages.length > 0) return pages;
+    } catch {
+      /* fall back */
+    }
+    return this.fallback.listPages();
+  }
+}
+// ---------------------------------------------------------------------------
+// PublishedContentProvider — overlays published customization content for the
+// resolved environment (store->app wiring). For each content artifact it checks
+// the customization store ({live,test} pointer -> versioned JSON); if present it
+// serves that, otherwise it delegates to the base provider (Storyblok/local).
+// listPages() stays from the base (per-page overrides flow through getPage).
+// ---------------------------------------------------------------------------
+export interface ContentCustomization {
+  get: KvGet;
+  env: CustomizationEnv;
+}
+export class PublishedContentProvider implements ContentProvider {
+  constructor(
+    private readonly base: ContentProvider,
+    private readonly tenantId: string,
+    private readonly cust: ContentCustomization,
+  ) {}
+  /** Raw published-artifact string for a tenant file, or null to fall back to base. */
+  private publishedRaw(relative: string): Promise<string | null> {
+    return readPublishedArtifact(
+      this.cust.get,
+      this.tenantId,
+      this.cust.env,
+      contentArtifactPath(this.tenantId, relative),
+    );
+  }
+  private async published<T>(relative: string): Promise<T | null> {
+    const raw = await this.publishedRaw(relative);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+  async getHome(): Promise<HomeContent> {
+    return (await this.published<HomeContent>("home.json")) ?? this.base.getHome();
+  }
+  // Raw whole-page documents (T0 marketing tenants) publish via KV too, so a
+  // vendor edit previews / goes live with NO Worker rebuild. Artifact path mirrors
+  // the source file: content/<tenant>/home.html and .../pages-html/<slug>.html.
+  async getHomeHtml(): Promise<string | null> {
+    return (await this.publishedRaw("home.html")) ?? this.base.getHomeHtml();
+  }
+  async getPageHtml(slug: string): Promise<string | null> {
+    const rel = `pages-html/${normalizeRawPageSlug(slug)}.html`;
+    return (await this.publishedRaw(rel)) ?? this.base.getPageHtml(slug);
+  }
+  listPageHtmlSlugs(): Promise<string[]> {
+    return this.base.listPageHtmlSlugs();
+  }
+  async getChromeHtml(): Promise<string | null> {
+    // A published raw chrome.html override (parallels the home.html/pages-html
+    // publish path) wins, so a vendor edit previews / goes live with no rebuild.
+    const publishedHtml = await this.publishedRaw("chrome.html");
+    if (publishedHtml) return publishedHtml;
+    // Else, if the PUBLISHED chrome.json opts into shared chrome (unit F3), render
+    // the canonical wrapper from it — so a config edit previews without a rebuild.
+    const config = parseChromeConfig(await this.published<unknown>("chrome.json"));
+    if (config) return renderRawChrome(config);
+    // Otherwise fall back to the base chain (bundled chrome.html or config render).
+    return this.base.getChromeHtml();
+  }
+  async getChrome(): Promise<SiteChrome> {
+    return (await this.published<SiteChrome>("chrome.json")) ?? this.base.getChrome();
+  }
+  async getPage(slug: string): Promise<EditorialPage | null> {
+    return (await this.published<EditorialPage>(`pages/${slug}.json`)) ?? this.base.getPage(slug);
+  }
+  listPages(): Promise<EditorialPage[]> {
+    return this.base.listPages();
+  }
+}
+// ---------------------------------------------------------------------------
+// DevDraftContentProvider — the per-developer DRAFT overlay (decision
+// draft-overlay-same-origin). Wraps the resolved provider chain and serves a
+// draft artifact (written by /api/content-edit/ai-edit into TENANT_CACHE under
+// `dev-draft:<tenantId>:<draftId>:<path>`) when one exists, else delegates.
+// The middleware constructs this ONLY for a request whose signed tot_dev_draft
+// cookie verifies for the resolved tenant — every other viewer gets the base
+// chain untouched. Covers the raw-HTML surfaces the AI edit loop writes
+// (home.html / pages-html); structured content stays base.
+// ---------------------------------------------------------------------------
+export class DevDraftContentProvider implements ContentProvider {
+  constructor(
+    private readonly base: ContentProvider,
+    private readonly tenantId: string,
+    private readonly draftId: string,
+    private readonly get: KvGet,
+  ) {}
+  /** Draft artifact for a tenant-repo-relative path, or null to fall back. */
+  private draftRaw(path: string): Promise<string | null> {
+    // Key shape mirrors lib/dev/devDraft.ts devDraftKey — duplicated as a plain
+    // template to keep this module's imports renderer-safe (public-runtime only).
+    return this.get(`dev-draft:${this.tenantId}:${this.draftId}:${path}`);
+  }
+  async getHomeHtml(): Promise<string | null> {
+    return (await this.draftRaw("content/home.html")) ?? this.base.getHomeHtml();
+  }
+  async getPageHtml(slug: string): Promise<string | null> {
+    const rel = `content/pages-html/${normalizeRawPageSlug(slug)}.html`;
+    return (await this.draftRaw(rel)) ?? this.base.getPageHtml(slug);
+  }
+  getHome(): Promise<HomeContent> {
+    return this.base.getHome();
+  }
+  listPageHtmlSlugs(): Promise<string[]> {
+    return this.base.listPageHtmlSlugs();
+  }
+  getChromeHtml(): Promise<string | null> {
+    return this.base.getChromeHtml();
+  }
+  getChrome(): Promise<SiteChrome> {
+    return this.base.getChrome();
+  }
+  getPage(slug: string): Promise<EditorialPage | null> {
+    return this.base.getPage(slug);
+  }
+  listPages(): Promise<EditorialPage[]> {
+    return this.base.listPages();
+  }
+}
+const PLACEHOLDER_TOKEN_RE = /PLACEHOLDER|^$/i;
+export function createContentProvider(
+  tenant: TenantConfig,
+  customization?: ContentCustomization,
+): ContentProvider {
+  // Content dirs are keyed by tenant_id (the adopter writes content/<tenant>/).
+  const local = new LocalContentProvider(tenant.tenant_id);
+  const token = tenant.storyblok_space_token;
+  const usable = token && !PLACEHOLDER_TOKEN_RE.test(token);
+  const base: ContentProvider = usable
+    ? new StoryblokContentProvider(token, local)
+    : local;
+  return customization
+    ? new PublishedContentProvider(base, tenant.tenant_id, customization)
+    : base;
+}

package/apps/storefront/src/lib/subscription/model.ts ADDED Viewed

@@ -0,0 +1,68 @@
+/**
+ * Subscription / Autopilot education model — the typed input for the platform
+ * subscription-education widgets (<HowItWorksSteps>, <SavingsExplainer>,
+ * <ManageSubscriptionEntry>). These are presentational, EDUCATION-ONLY
+ * widgets: they explain how a recurring/Autopilot order works and hand off to
+ * the tenant's real subscribe/manage flow, but ship NO subscription,
+ * billing, or scheduling mechanics of their own.
+ *
+ * Because a savings headline (a "%", a "$" amount) is a claim, {@link
+ * SubscriptionFigure} is treated as ILLUSTRATIVE by default — same discipline
+ * as the membership tier figures (decision compliance-widgets-platform-owned):
+ * unless a figure explicitly asserts `real: true`, the widget marks it as an
+ * example so it is never presented as a live offer.
+ */
+/**
+ * One step in a "how it works" explainer (e.g. "Choose your products" →
+ * "Set your schedule" → "We ship on autopilot"). Display only.
+ */
+export interface SubscriptionStep {
+  /** Step title, e.g. "Set your schedule". */
+  title: string;
+  /** One or two sentences explaining the step. */
+  description: string;
+}
+/**
+ * A savings/pricing headline figure (e.g. "Save 15%", "$5 off every order").
+ * Display only — a string the widget renders verbatim, NEVER a number it
+ * computes a discount from. Marked illustrative unless `real` is set.
+ */
+export interface SubscriptionFigure {
+  /** The headline figure text, e.g. "Save 15%". Display only. */
+  value: string;
+  /** Optional caption under the figure, e.g. "vs. one-time purchase". */
+  caption?: string;
+  /**
+   * Assert this figure is a REAL, live value (opt out of the illustrative
+   * affordance). Default (undefined/false) → treated as an illustrative
+   * example. Only set when the tenant confirms the number is an accurate
+   * live offer.
+   */
+  real?: boolean;
+}
+/**
+ * One manage-subscription entry point (e.g. "Update delivery date", "Pause or
+ * cancel"). This is an EDUCATION/HANDOFF link only — it points at the
+ * tenant's product-owned manage-subscription flow; the widget never renders
+ * scheduling, billing, or cancellation controls of its own.
+ */
+export interface SubscriptionManageEntry {
+  /** Entry label, e.g. "Pause or cancel anytime". */
+  label: string;
+  /** Optional supporting sentence under the label. */
+  description?: string;
+  /** Handoff URL into the tenant's product-owned manage-subscription flow. */
+  href: string;
+}
+/**
+ * True when the widget should mark this figure as illustrative. A figure
+ * that asserts `real: true` opts out; everything else is illustrative by
+ * default so example numbers are never shown as a live offer.
+ */
+export function isIllustrative(figure: Pick<SubscriptionFigure, "real">): boolean {
+  return figure.real !== true;
+}