@scayle/storefront-cms-amplience 0.2.0-alpha.0

package/README.md

@@ -0,0 +1,163 @@
+# @scayle/storefront-cms-amplience
+
+Amplience CMS provider integration for the SCAYLE Storefront Application V3. Implements
+`CMSProviderService` from `@scayle/storefront` on top of Amplience Content Delivery 2, plus the
+Virtual Staging Environment helpers the provider's visualization paths need.
+
+## Package entrypoint
+
+| Export                                                           | Use                                                                                                                                                 |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AmplienceCMSService`                                            | Concrete `CMSProviderService` implementation. No abstract members, so it is usable without a subclass.                                              |
+| `AmplienceCMSServiceConfig`                                      | Constructor config shape: `{hubName, draftContentEnabled}`.                                                                                         |
+| `cspConfig`                                                      | `CMSCspConfig` for Amplience visualization: Dynamic Content iframe embedding plus the Dynamic Media `connect-src` the video metadata request needs. |
+| `parseCategoryIdFromAmplienceDeliveryKey`                        | Parses the category ID back out of a PLP delivery key, which is all Amplience exposes in `{{delivery.key}}`.                                        |
+| `isAmplienceCategoryRoutePath`, `resolveAmpliencePlpPreviewPath` | Category-route detection, and rewriting the PLP visualization placeholder path to carry the real category ID.                                       |
+
+VSE parsing and editor detection stay internal; editor detection is reachable through
+`AmplienceCMSService.isEditorMode()`.
+
+**Dynamic Media URL building lives in the application**, not here:
+`src/client/cms/providers/amplience/utils/media.ts`, next to the other providers' media helpers and on
+top of the shared `getSources` breakpoint logic. Those builders touch no vendor SDK, and the
+breakpoints, formats, and quality defaults they encode are presentation choices a tenant edits, so
+freezing them behind a package release would be the wrong boundary.
+
+See [Amplience's Content Delivery documentation](https://amplience.com/developers/docs/apis/content-delivery/)
+and the [Dynamic Media reference](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/)
+for the underlying APIs.
+
+## Configuration
+
+| Option                | Required | Description                                                            |
+| --------------------- | -------- | ---------------------------------------------------------------------- |
+| `hubName`             | Yes      | Content Delivery 2 hub name, used as the delivery subdomain.           |
+| `draftContentEnabled` | Yes      | Whether a visualization request may serve unpublished staging content. |
+
+The package never reads `process.env` itself. The boilerplate is the sole place reading environment
+variables (`AMPLIENCE_CMS_HUB_NAME`, `STOREFRONT_CMS_ALLOW_DRAFTS`) and passes plain values in.
+
+## Usage
+
+`AmplienceCMSService` has no abstract members, so it works without a subclass. The boilerplate's
+`src/server/cms/providers/amplience/service.ts` still wraps it in a thin subclass for consistency with
+the other providers and as the tenant's override point:
+
+```ts
+import { AmplienceCMSService as BaseAmplienceCMSService } from '@scayle/storefront-cms-amplience'
+
+export class AmplienceCMSService extends BaseAmplienceCMSService {}
+
+export const createCMSService = (storefront: StorefrontContext) =>
+  new AmplienceCMSService(
+    {
+      hubName: getRequiredEnv('AMPLIENCE_CMS_HUB_NAME'),
+      draftContentEnabled:
+        process.env.STOREFRONT_CMS_ALLOW_DRAFTS?.toLowerCase() === 'true',
+    },
+    storefront,
+  )
+```
+
+The boilerplate registers `createCMSService(storefront)` as the `cms` slot on the `ServiceRegistry`
+(`src/server/registries.ts`). Controllers resolve it from there and pass the raw request through:
+
+```ts
+const pageData = await services.cms.fetchPageData(slug, locale, ctx.req)
+```
+
+## Architecture
+
+`AmplienceCMSService` implements `CMSProviderService` directly. Each provider package owns its own
+caching, error handling, and constructor validation, so this package can diverge from the others
+without a `@scayle/storefront` release touching them.
+
+### Content items are locale-bound, so lookups go through delivery keys
+
+Amplience Content Delivery 2 localizes at the content-item level rather than by delivery endpoint. The
+client is therefore locale-agnostic, and every lookup is a locale-prefixed delivery key:
+
+- Content pages: `{locale}/{slug}`, for example `de-DE/content/about` or `en-GB/homepage`.
+- Category pages: `{locale}/c/c-{categoryId}`, for example `en-US/c/c-91825`.
+
+Both come from `protected buildPageDeliveryKey` / `buildListingDeliveryKey`, so a subclass can change
+the delivery-key layout without reimplementing the fetch path.
+
+**Category pages do not use Amplience's Filter API.** Because Content Delivery 2 binds items to a
+locale, an item with no explicit locale assignment falls outside the delivery-layer locale filter and is
+simply not returned, even though it exists in the hub. That made filter-based resolution unreliable. The
+V2 provider reached the same conclusion; its reasoning is recorded in
+`v2/boilerplate/modules/cms/providers/amplience/AMPLIENCE.md`.
+
+### Caching
+
+`fetchPageData` and `fetchListingPageData` wrap the raw fetch in `context.cache.getOrSet(...)` with a
+5-minute TTL, under `cms:amplience:page:{deliveryKey}` and `cms:amplience:plp:{deliveryKey}`. The key is
+the delivery key rather than slug plus locale, because the delivery key already encodes both. Preview
+requests bypass the cache entirely.
+
+`fetchListingPageData` converts a `CMSContentNotFoundError` into `undefined` — most categories have no
+CMS content, and that is not an error. Any other error is logged and rethrown.
+
+### Client instances
+
+Published delivery clients are lazily initialized and cached statically, keyed by hub name, so they are
+reused across requests without two hubs in one process sharing a client. A
+Virtual Staging Environment client is built per request instead, because the staging domain is issued
+per editor session and a shared instance would serve one editor's drafts to another. Both go through
+`@scayle/storefront/cms`'s `wrapClientInit`, so a bad hub name fails with a message naming the config
+field to check rather than a bare SDK error.
+
+The delivery SDK returns content wrapped in classes carrying `toJSON` hooks, which do not survive
+serialization into Inertia page props. The payload is round-tripped through JSON to get plain objects.
+
+### Preview
+
+Amplience drives in-CMS preview by loading the storefront in an iframe with two query parameters:
+
+- `vse` (or `_vse` on older visualization templates) — the per-session staging domain. Its presence is
+  the editor-mode signal, and `isEditorMode()` keys off it. The value becomes the base URL the delivery
+  SDK fetches from, so it is accepted only when it matches an Amplience staging domain
+  (`<session>.staging.bigcontent.io`); any other host is logged and ignored as if no `vse` had been
+  passed.
+- `key` — the delivery key of the item the editor currently has open, substituted from
+  `{{delivery.key}}`. In a draft-enabled preview session this wins over the delivery key derived from
+  the URL, so the editor sees exactly the item it has open.
+
+Draft preview requires **both** a `vse` parameter and `draftContentEnabled`. Without the flag the
+service ignores the VSE domain and serves published content, which is what keeps production safe if a
+visualization URL leaks. Leave `STOREFRONT_CMS_ALLOW_DRAFTS` unset in production.
+
+`getCMSEditorData()` returns the VSE hostname and open delivery key for the client-side visualization
+bridge, under the same staging check the fetch path uses. With `draftContentEnabled` off it returns
+`undefined`, so the client is not told to talk to an environment the server just declined to read from.
+
+### Product listing page visualization
+
+Amplience cannot inject a custom schema field into a visualization `templatedUri`, so the Product
+Listing Page content type opens preview at a placeholder path (`/c/cms-preview-0`) and passes the real
+delivery key as `?key=`. `parseCategoryIdFromAmplienceDeliveryKey` recovers the category ID from that
+key and `resolveAmpliencePlpPreviewPath` rewrites the path to `/c/cms-preview-{categoryId}`, preserving
+any country prefix, so the category route can load products, filters, and navigation.
+
+`getPreviewRedirectPath(request, path)` is the entry point that applies those two helpers, and it is what
+the application's preview redirect middleware calls (`createCmsPreviewRedirectMiddleware` from
+`@scayle/storefront/cms`). It returns the rewritten path in a visualization session on a category route
+whose `key` holds a category ID, and `undefined` otherwise, so any other request is served as-is. A path
+that already ends in that category ID is served as-is too, so the redirect does not fight the canonical
+path redirect the listing controller issues for a non-canonical slug.
+
+### Dynamic Media
+
+Image and video URLs are built in the application
+(`src/client/cms/providers/amplience/utils/media.ts`), the same place the Storyblok, Contentful, and
+Contentstack media helpers live. The service itself never builds a media URL: it returns content
+payloads, and the components turn image-link and video-link objects into Dynamic Media URLs.
+
+## Extending and customizing
+
+- Override `buildPageDeliveryKey` / `buildListingDeliveryKey` to change the delivery-key layout.
+- Augment `CMSEditorData` with a `declare module '@scayle/storefront/cms'` block to add fields for a
+  custom client-side editor bridge. This package already contributes `vse` and `deliveryKey`.
+- SEO metadata extraction lives in the boilerplate (`getPageMeta` in the provider's `service.ts`), not
+  here, since the field names come from the tenant's content model.

package/dist/index.d.mts

@@ -0,0 +1,241 @@
+import { CMSCspConfig, CMSEditorData, CMSPagePayload, CMSProviderService, CMSRequestLike } from "@scayle/storefront/cms";
+import { StorefrontContext } from "@scayle/storefront/types";
+declare module "@scayle/storefront/cms" {
+  interface CMSEditorData {
+    /** Virtual Staging Environment hostname for the current visualization session. */
+    vse?: string;
+    /** Delivery key of the content item the editor currently has open. */
+    deliveryKey?: string;
+  }
+}
+/**
+ * Configuration accepted by {@link AmplienceCMSService}'s constructor.
+ * The boilerplate reads these from environment variables and passes plain
+ * values in, so this package never touches `process.env` directly.
+ */
+interface AmplienceCMSServiceConfig {
+  /** Content Delivery 2 hub name, used as the delivery subdomain. */
+  hubName: string;
+  /** Whether to serve staging content when the request is in editor mode. */
+  draftContentEnabled: boolean;
+}
+/**
+ * Amplience CMS provider service.
+ *
+ * Amplience localizes at the content-item level rather than by delivery
+ * endpoint, so the client itself is locale-agnostic and every lookup goes
+ * through a locale-prefixed delivery key (`de-DE/content/about`). The published
+ * client is a static singleton; a Virtual Staging Environment client is built
+ * per request because the staging domain is issued per visualization session.
+ *
+ * Category pages resolve by delivery key (`{locale}/c/c-{categoryId}`), not
+ * through Amplience's Filter API. Content Delivery 2 binds content items to a
+ * locale, and items without an explicit locale assignment fall outside the
+ * delivery-layer locale filter entirely, which made filter-based resolution
+ * unreliable. The V2 provider reached the same conclusion; see
+ * `v2/boilerplate/modules/cms/providers/amplience/AMPLIENCE.md`.
+ *
+ * @see https://amplience.com/developers/docs/apis/content-delivery/
+ */
+declare class AmplienceCMSService implements CMSProviderService {
+  /** Published clients keyed by hub name, so two hubs in one process do not share a client. */
+  private static deliveryClients;
+  readonly cspConfig: CMSCspConfig;
+  private readonly config;
+  private readonly context;
+  constructor(config: AmplienceCMSServiceConfig, context: StorefrontContext);
+  /**
+   * Checks whether the current request originates from the Amplience
+   * visualization iframe, detected via the `vse` query parameter.
+   *
+   * @param request Incoming request
+   * @returns True when the request is an Amplience editor session
+   */
+  isEditorMode(request: CMSRequestLike): boolean;
+  /**
+   * Builds editor data for the current request.
+   * The client-side visualization bridge needs the staging domain and the
+   * delivery key of the open item to subscribe to editor updates.
+   *
+   * Gated on the same staging check the fetch path uses, so a deployment with
+   * drafts disabled does not ship a staging domain to the client after the server
+   * has already refused to read from it.
+   *
+   * @param request Incoming request, used to detect editor mode
+   * @returns Editor data fields for Inertia page props, or undefined outside an editor session
+   */
+  getCMSEditorData(request: CMSRequestLike): CMSEditorData | undefined;
+  /**
+   * Resolves the category route a product listing page visualization belongs on.
+   *
+   * The Product Listing Page content type opens preview at a placeholder path
+   * (`/c/cms-preview-0`), because Amplience can only substitute the delivery key
+   * into the visualization URI, not the category ID the route needs. The category
+   * ID is parsed back out of that delivery key so the request can be redirected
+   * onto the real category route, where products, filters, and navigation load
+   * as they do outside preview.
+   *
+   * Only the placeholder path is rewritten. A path whose trailing ID is already the
+   * category the delivery key names is served as-is, because the listing controller
+   * redirects a non-canonical slug to the canonical one and keeps the query string:
+   * rewriting `/de/c/women-50350` back to `/de/c/cms-preview-50350` would bounce
+   * between the two forever.
+   *
+   * @param request Incoming request, used to detect editor mode and read the preview delivery key
+   * @param path Current request path
+   * @returns Category route path carrying the parsed category ID, or undefined when the
+   *   request is not a category page visualization
+   */
+  getPreviewRedirectPath(request: CMSRequestLike, path: string): string | undefined;
+  private getDeliveryClient;
+  /**
+   * Builds a Virtual Staging Environment client for one visualization session.
+   *
+   * Not cached: the staging domain is issued per editor session, so a shared
+   * instance would serve one editor's drafts to another.
+   *
+   * The hostname must already have passed `getVseFromRequest`, which is what
+   * keeps an attacker-supplied `vse` parameter from reaching `ContentClient`.
+   * Any new call site has to validate first.
+   *
+   * @param stagingEnvironment Validated VSE hostname from the request
+   * @returns Content client targeting the staging environment
+   */
+  private createStagingClient;
+  /**
+   * Decides whether this request should be served staging content, and from where.
+   *
+   * Draft preview needs both an Amplience-supplied VSE domain and
+   * `draftContentEnabled`. Without the flag the storefront ignores the VSE domain
+   * and serves published content, which is what keeps production safe when a
+   * visualization URL leaks.
+   *
+   * @param request Incoming request
+   * @returns Staging hostname when staging content should be served, otherwise undefined
+   */
+  private resolveStagingEnvironment;
+  /**
+   * Builds the locale-prefixed delivery key for a content page.
+   * Override to change the delivery-key layout without touching the fetch path.
+   *
+   * @param slug CMS slug (for example `content/about` or `homepage`)
+   * @param locale Storefront locale code
+   * @returns Delivery key to look up
+   */
+  protected buildPageDeliveryKey(slug: string, locale: string): string;
+  /**
+   * Builds the locale-prefixed delivery key for a category page.
+   * Override to change the delivery-key layout without touching the fetch path.
+   *
+   * @param categoryId SCAYLE category ID
+   * @param locale Storefront locale code
+   * @returns Delivery key to look up
+   */
+  protected buildListingDeliveryKey(categoryId: number, locale: string): string;
+  /**
+   * Fetches one content item by delivery key.
+   *
+   * The delivery SDK returns content wrapped in classes that carry `toJSON`
+   * hooks. Those do not survive serialization into Inertia page props, so the
+   * payload is round-tripped through JSON to get plain objects.
+   *
+   * @param deliveryKey Delivery key to look up
+   * @param stagingEnvironment VSE hostname, when serving staging content
+   * @param details Context attached to a thrown `CMSContentNotFoundError`
+   * @returns Plain content payload
+   * @throws {CMSContentNotFoundError} When no content item matches the delivery key
+   */
+  private fetchByDeliveryKey;
+  /**
+   * Retrieves CMS page content from Amplience by slug, with caching.
+   *
+   * In an editor session the delivery key Amplience passes as `?key=` wins over
+   * the one derived from the slug, so the editor previews exactly the item it has
+   * open even when that item is not the one the URL maps to.
+   *
+   * @param slug CMS slug
+   * @param locale Storefront locale code
+   * @param request Incoming request, used to detect editor mode and read the preview delivery key
+   * @returns Amplience page data. Never undefined in practice: the wider return type
+   * comes from the `CMSProviderService` contract, and a missing item throws instead.
+   * @throws {CMSContentNotFoundError} When no content item matches the delivery key
+   */
+  fetchPageData(slug: string, locale: string, request: CMSRequestLike): Promise<CMSPagePayload | undefined>;
+  /**
+   * Retrieves CMS content for a product listing page, with caching.
+   *
+   * Converts a missing content item into `undefined` rather than throwing, since
+   * most categories have no CMS content and that is not an error.
+   *
+   * @param categoryId SCAYLE category ID
+   * @param locale Storefront locale code
+   * @param request Incoming request, used to detect editor mode and read the preview delivery key
+   * @returns Amplience listing page data, or undefined when the category has no content
+   */
+  fetchListingPageData(categoryId: number, locale: string, request: CMSRequestLike): Promise<CMSPagePayload | undefined>;
+}
+/**
+ * CSP configuration for the Amplience provider.
+ * Allows the Dynamic Content app to embed the storefront in a visualization
+ * iframe, and allows the storefront to load Dynamic Media assets while previewing.
+ *
+ * The app origins are the only embedders: `app.amplience.net` is the current
+ * Dynamic Content app and `app.bigcontent.io` the legacy one. The client bridge
+ * (`dc-visualization-sdk`, used by `useAmplienceEditor`) is bundled with the
+ * application and talks to the parent frame over `postMessage`, which CSP does not
+ * gate, so no script or connection to an app origin is allowed. `connect-src` covers the Dynamic Media
+ * video metadata request `VideoComponent` makes. That request goes to
+ * `*.adis.ws` on hubs provisioned before Amplience moved Dynamic Media to
+ * `*.amplience.net`, so both hosts stay listed. Drop `*.adis.ws` once no hub in
+ * use serves media from it.
+ *
+ * No `img-src` or `media-src` entry is declared. The middleware appends
+ * directives, so naming either one would start restricting image and video
+ * sources for visualization requests only, and CMS blocks that render product
+ * cards (single product, product sliders, recently viewed) load their images
+ * from the shop's own CDN rather than from Dynamic Media. Preview would show
+ * broken product images while the published page renders fine.
+ */
+declare const cspConfig: CMSCspConfig;
+/**
+ * Parses a category ID from an Amplience PLP delivery key or slug.
+ *
+ * Amplience only exposes the full delivery key (for example `en-US/c/c-91825`) in
+ * `{{delivery.key}}`, never the category ID on its own, so the ID has to be parsed
+ * back out to build a usable category route.
+ *
+ * @param deliveryKeyOrSlug Full delivery key or relative slug (for example `c/c-100`)
+ * @returns Parsed category ID, or undefined when the value does not match the PLP pattern
+ *
+ * @example
+ * ```ts
+ * parseCategoryIdFromAmplienceDeliveryKey('en-US/c/c-91825')
+ * // Returns: 91825
+ * ```
+ */
+declare const parseCategoryIdFromAmplienceDeliveryKey: (deliveryKeyOrSlug: string) => number | undefined;
+/**
+ * Checks whether a path targets the storefront category page route pattern.
+ *
+ * @param path Route path (for example `/c/cms-preview-0` or `/de/c/women-123`)
+ * @returns True when the path ends with a `{slug}-{id}` segment under `/c/`
+ */
+declare const isAmplienceCategoryRoutePath: (path: string) => boolean;
+/**
+ * Builds a PLP visualization path with the parsed category ID in the route param.
+ *
+ * The Product Listing Page content type opens preview at a placeholder path
+ * (`/c/cms-preview-0`) because Amplience cannot inject a schema field into
+ * `templatedUri`. This rewrites that placeholder to carry the real category ID so
+ * the category route can load products, filters, and navigation. Any locale prefix
+ * before `/c/` is preserved (for example `/de/c/cms-preview-91825`).
+ *
+ * @param path Current route path containing a `/c/` segment
+ * @param categoryId Category ID extracted from the PLP delivery key
+ * @returns Path whose trailing segment is `cms-preview-{categoryId}`. A `path` with no
+ *   `/c/` segment falls back to a bare `/c/{segment}`, which carries no country prefix
+ *   and is therefore not a servable route; callers check the path first.
+ */
+declare const resolveAmpliencePlpPreviewPath: (path: string, categoryId: number) => string;
+export { AmplienceCMSService, type AmplienceCMSServiceConfig, cspConfig, isAmplienceCategoryRoutePath, parseCategoryIdFromAmplienceDeliveryKey, resolveAmpliencePlpPreviewPath };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/AmplienceCMSService.ts","../src/csp.ts","../src/preview.ts"],"mappings":";;;YAqCmB;;IAEf;;IAEA;;;;;;;;UASa;;EAEf;;EAEA;;;;;;;;;;;;;;;;;;;;cAqBW,+BAA+B;;iBAE3B;WAEN,WAAW;mBAEH;mBAEA;EAEjB,YAAY,QAAQ,2BAA2B,SAAS;;;;;;;;EAkBxD,aAAa,SAAS;;;;;;;;;;;;;EAgBtB,iBAAiB,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;EAkC3C,uBACE,SAAS,gBACT;UA4BM;;;;;;;;;;;;;;UA8BA;;;;;;;;;;;;UAsBA;;;;;;;;;YAkBE,qBAAqB,cAAc;;;;;;;;;YAYnC,wBACR,oBACA;;;;;;;;;;;;;;UAkBY;;;;;;;;;;;;;;;EA8Cd,cACE,cACA,gBACA,SAAS,iBACR,QAAQ;;;;;;;;;;;;EA4CX,qBACE,oBACA,gBACA,SAAS,iBACR,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;cCtWA,WAAW;;;;;;;;;;;;;;;;;cCkFX,0CACX;;;;;;;cAkBW,+BAAgC;;;;;;;;;;;;;;;;cAmBhC,iCACX,cACA"}

package/dist/index.mjs

@@ -0,0 +1,173 @@
+import { ContentClient, ContentNotFoundError } from "dc-delivery-sdk-js";
+import { CMSContentNotFoundError, extractErrorStatus, wrapClientInit } from "@scayle/storefront/cms";
+import { createLogger } from "@scayle/storefront/shared";
+const log$1 = createLogger("cms");
+const PLP_PREVIEW_SLUG_PREFIX = "cms-preview";
+const PLP_DELIVERY_KEY_CATEGORY_ID = /(?:^|\/)c\/c-(\d+)\/?$/;
+const VSE_HOSTNAME = /^[\w-]+\.staging\.bigcontent\.io$/i;
+const getVseFromRequest = (request) => {
+	const vse = request.query("vse") || request.query("_vse");
+	if (!vse) return;
+	const hostname = vse.replace(/^https?:\/\//, "").replace(/\/$/, "");
+	if (!VSE_HOSTNAME.test(hostname)) {
+		log$1.warn({
+			message: "Ignoring vse query parameter: not an Amplience staging domain",
+			vse
+		});
+		return;
+	}
+	return hostname;
+};
+const isAmplienceEditorRequest = (request) => {
+	return Boolean(getVseFromRequest(request));
+};
+const getPreviewDeliveryKeyFromRequest = (request) => {
+	return request.query("key") || void 0;
+};
+const parseCategoryIdFromAmplienceDeliveryKey = (deliveryKeyOrSlug) => {
+	const match = deliveryKeyOrSlug.trim().match(PLP_DELIVERY_KEY_CATEGORY_ID);
+	if (!match?.[1]) return;
+	const categoryId = Number.parseInt(match[1], 10);
+	return Number.isNaN(categoryId) ? void 0 : categoryId;
+};
+const isAmplienceCategoryRoutePath = (path) => {
+	return /\/c\/[^/]+-\d+$/.test(path);
+};
+const resolveAmpliencePlpPreviewPath = (path, categoryId) => {
+	const previewSegment = `${PLP_PREVIEW_SLUG_PREFIX}-${categoryId}`;
+	const match = path.match(/^(.*\/c\/)[^/]*$/);
+	if (match?.[1]) return `${match[1]}${previewSegment}`;
+	return `/c/${previewSegment}`;
+};
+const cspConfig = {
+	isPreviewRequest: isAmplienceEditorRequest,
+	directives: {
+		"frame-ancestors": "'self' https://app.amplience.net https://app.bigcontent.io",
+		"connect-src": "'self' https://*.amplience.net https://*.adis.ws"
+	}
+};
+const log = createLogger("cms");
+const CACHE_TTL_SECONDS = 300;
+var AmplienceCMSService = class AmplienceCMSService {
+	static deliveryClients = /* @__PURE__ */ new Map();
+	cspConfig = cspConfig;
+	config;
+	context;
+	constructor(config, context) {
+		if (!config.hubName) throw new Error("Amplience CMS initialization failed: missing or empty hub name. Check that AMPLIENCE_CMS_HUB_NAME is set.");
+		this.config = config;
+		this.context = context;
+	}
+	isEditorMode(request) {
+		return isAmplienceEditorRequest(request);
+	}
+	getCMSEditorData(request) {
+		const vse = this.resolveStagingEnvironment(request);
+		if (!vse) return;
+		return {
+			vse,
+			deliveryKey: getPreviewDeliveryKeyFromRequest(request)
+		};
+	}
+	getPreviewRedirectPath(request, path) {
+		if (!this.isEditorMode(request) || !isAmplienceCategoryRoutePath(path)) return;
+		const deliveryKey = getPreviewDeliveryKeyFromRequest(request);
+		if (!deliveryKey) return;
+		const categoryId = parseCategoryIdFromAmplienceDeliveryKey(deliveryKey);
+		if (categoryId === void 0) return;
+		if (path.match(/-(\d+)$/)?.[1] === String(categoryId)) return;
+		return resolveAmpliencePlpPreviewPath(path, categoryId);
+	}
+	getDeliveryClient() {
+		const cached = AmplienceCMSService.deliveryClients.get(this.config.hubName);
+		if (cached) return cached;
+		const client = wrapClientInit(() => new ContentClient({ hubName: this.config.hubName }), "Amplience delivery client initialization failed. Check that AMPLIENCE_CMS_HUB_NAME is a valid Content Delivery 2 hub name");
+		AmplienceCMSService.deliveryClients.set(this.config.hubName, client);
+		return client;
+	}
+	createStagingClient(stagingEnvironment) {
+		return wrapClientInit(() => new ContentClient({
+			hubName: this.config.hubName,
+			stagingEnvironment
+		}), "Amplience staging client initialization failed. Check that the vse query parameter holds a valid Virtual Staging Environment domain");
+	}
+	resolveStagingEnvironment(request) {
+		if (!this.config.draftContentEnabled) return;
+		return getVseFromRequest(request);
+	}
+	buildPageDeliveryKey(slug, locale) {
+		return `${locale}/${slug}`;
+	}
+	buildListingDeliveryKey(categoryId, locale) {
+		return `${locale}/c/c-${categoryId}`;
+	}
+	async fetchByDeliveryKey(deliveryKey, stagingEnvironment, details) {
+		const client = stagingEnvironment ? this.createStagingClient(stagingEnvironment) : this.getDeliveryClient();
+		try {
+			const content = await client.getContentItemByKey(deliveryKey);
+			return JSON.parse(JSON.stringify(content));
+		} catch (error) {
+			if (error instanceof ContentNotFoundError || extractErrorStatus(error) === 404) throw new CMSContentNotFoundError("Amplience content not found", {
+				cause: error,
+				details: {
+					...details,
+					deliveryKey
+				}
+			});
+			const cause = error instanceof Error ? error : new Error(String(error));
+			throw new Error(`Amplience API request failed (delivery key: "${deliveryKey}"): ${cause.message}`, { cause });
+		}
+	}
+	async fetchPageData(slug, locale, request) {
+		const stagingEnvironment = this.resolveStagingEnvironment(request);
+		const deliveryKey = stagingEnvironment ? getPreviewDeliveryKeyFromRequest(request) || this.buildPageDeliveryKey(slug, locale) : this.buildPageDeliveryKey(slug, locale);
+		if (stagingEnvironment) {
+			log.debug({
+				message: "Bypassing CMS cache in preview mode",
+				slug,
+				locale
+			});
+			return await this.fetchByDeliveryKey(deliveryKey, stagingEnvironment, {
+				slug,
+				locale
+			});
+		}
+		return await this.context.cache.getOrSet(`cms:amplience:page:${deliveryKey}`, () => this.fetchByDeliveryKey(deliveryKey, void 0, {
+			slug,
+			locale
+		}), CACHE_TTL_SECONDS);
+	}
+	async fetchListingPageData(categoryId, locale, request) {
+		const stagingEnvironment = this.resolveStagingEnvironment(request);
+		const deliveryKey = stagingEnvironment ? getPreviewDeliveryKeyFromRequest(request) || this.buildListingDeliveryKey(categoryId, locale) : this.buildListingDeliveryKey(categoryId, locale);
+		const fetchListing = async () => {
+			try {
+				return await this.fetchByDeliveryKey(deliveryKey, stagingEnvironment, {
+					categoryId,
+					locale
+				});
+			} catch (error) {
+				if (error instanceof CMSContentNotFoundError) return;
+				log.error({
+					message: "Failed to fetch CMS listing page data",
+					err: error instanceof Error ? error : new Error(String(error)),
+					categoryId,
+					locale
+				});
+				throw error;
+			}
+		};
+		if (stagingEnvironment) {
+			log.debug({
+				message: "Bypassing CMS PLP cache in preview mode",
+				categoryId,
+				locale
+			});
+			return await fetchListing();
+		}
+		return await this.context.cache.getOrSet(`cms:amplience:plp:${deliveryKey}`, () => fetchListing(), CACHE_TTL_SECONDS);
+	}
+};
+export { AmplienceCMSService, cspConfig, isAmplienceCategoryRoutePath, parseCategoryIdFromAmplienceDeliveryKey, resolveAmpliencePlpPreviewPath };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["log"],"sources":["../src/preview.ts","../src/csp.ts","../src/AmplienceCMSService.ts"],"sourcesContent":["/**\n * Amplience Virtual Staging Environment (VSE) and visualization helpers.\n *\n * Amplience drives in-CMS preview by loading the storefront in an iframe with a\n * `vse` query parameter holding a per-session staging domain, and a `key` query\n * parameter holding the delivery key of the item being edited. These helpers read\n * those parameters and translate them into delivery keys and route paths.\n */\n\nimport type { CMSRequestLike } from '@scayle/storefront/cms'\nimport { createLogger } from '@scayle/storefront/shared'\n\nconst log = createLogger('cms')\n\n/** Slug prefix used in PLP visualization placeholder paths (`cms-preview-{categoryId}`). */\nexport const PLP_PREVIEW_SLUG_PREFIX = 'cms-preview'\n\n/** Matches the category ID suffix in a PLP delivery key or slug (`c/c-{id}`). */\nconst PLP_DELIVERY_KEY_CATEGORY_ID = /(?:^|\\/)c\\/c-(\\d+)\\/?$/\n\n/** Matches an Amplience-issued Virtual Staging Environment domain. */\nconst VSE_HOSTNAME = /^[\\w-]+\\.staging\\.bigcontent\\.io$/i\n\n/**\n * Resolves the Virtual Staging Environment domain from the request query string.\n *\n * The protocol and any trailing slash are stripped because the delivery SDK expects a\n * bare hostname for `stagingEnvironment`, while Amplience sometimes passes a full URL.\n * The result is checked against the Amplience VSE domain pattern: the delivery SDK\n * turns this value into the base URL it fetches content from, so an unchecked query\n * parameter would let anyone make the server render content from a host of their\n * choosing. A rejected value is logged, since preview then falls back to published\n * content and would otherwise look like drafts are switched off.\n *\n * @param request Incoming request\n * @returns VSE hostname when present and Amplience-issued, otherwise undefined\n */\nexport const getVseFromRequest = (\n  request: CMSRequestLike,\n): string | undefined => {\n  // `||` rather than `??`: an empty `vse` should still fall back to the legacy `_vse`.\n  const vse = request.query('vse') || request.query('_vse')\n\n  if (!vse) {\n    return undefined\n  }\n\n  const hostname = vse.replace(/^https?:\\/\\//, '').replace(/\\/$/, '')\n\n  if (!VSE_HOSTNAME.test(hostname)) {\n    log.warn({\n      message: 'Ignoring vse query parameter: not an Amplience staging domain',\n      vse,\n    })\n\n    return undefined\n  }\n\n  return hostname\n}\n\n/**\n * Checks whether the current request is an Amplience visualization session.\n *\n * Amplience injects `vse` (or `_vse` on older visualization templates) into the\n * iframe URL, so the presence of either parameter is the editor-mode signal.\n *\n * @param request Incoming request\n * @returns True when the storefront is being rendered inside the Amplience editor\n */\nexport const isAmplienceEditorRequest = (request: CMSRequestLike): boolean => {\n  return Boolean(getVseFromRequest(request))\n}\n\n/**\n * Reads the delivery key Amplience passes for the item being visualized.\n *\n * Amplience substitutes `{{delivery.key}}` into the visualization URI as `?key=`,\n * which is the only way the storefront learns which content item the editor has\n * open. Used in preview to fetch that exact item instead of deriving a delivery\n * key from the route.\n *\n * @param request Incoming request\n * @returns Delivery key when present, otherwise undefined\n */\nexport const getPreviewDeliveryKeyFromRequest = (\n  request: CMSRequestLike,\n): string | undefined => {\n  return request.query('key') || undefined\n}\n\n/**\n * Parses a category ID from an Amplience PLP delivery key or slug.\n *\n * Amplience only exposes the full delivery key (for example `en-US/c/c-91825`) in\n * `{{delivery.key}}`, never the category ID on its own, so the ID has to be parsed\n * back out to build a usable category route.\n *\n * @param deliveryKeyOrSlug Full delivery key or relative slug (for example `c/c-100`)\n * @returns Parsed category ID, or undefined when the value does not match the PLP pattern\n *\n * @example\n * ```ts\n * parseCategoryIdFromAmplienceDeliveryKey('en-US/c/c-91825')\n * // Returns: 91825\n * ```\n */\nexport const parseCategoryIdFromAmplienceDeliveryKey = (\n  deliveryKeyOrSlug: string,\n): number | undefined => {\n  const match = deliveryKeyOrSlug.trim().match(PLP_DELIVERY_KEY_CATEGORY_ID)\n\n  if (!match?.[1]) {\n    return undefined\n  }\n\n  const categoryId = Number.parseInt(match[1], 10)\n  return Number.isNaN(categoryId) ? undefined : categoryId\n}\n\n/**\n * Checks whether a path targets the storefront category page route pattern.\n *\n * @param path Route path (for example `/c/cms-preview-0` or `/de/c/women-123`)\n * @returns True when the path ends with a `{slug}-{id}` segment under `/c/`\n */\nexport const isAmplienceCategoryRoutePath = (path: string): boolean => {\n  return /\\/c\\/[^/]+-\\d+$/.test(path)\n}\n\n/**\n * Builds a PLP visualization path with the parsed category ID in the route param.\n *\n * The Product Listing Page content type opens preview at a placeholder path\n * (`/c/cms-preview-0`) because Amplience cannot inject a schema field into\n * `templatedUri`. This rewrites that placeholder to carry the real category ID so\n * the category route can load products, filters, and navigation. Any locale prefix\n * before `/c/` is preserved (for example `/de/c/cms-preview-91825`).\n *\n * @param path Current route path containing a `/c/` segment\n * @param categoryId Category ID extracted from the PLP delivery key\n * @returns Path whose trailing segment is `cms-preview-{categoryId}`. A `path` with no\n *   `/c/` segment falls back to a bare `/c/{segment}`, which carries no country prefix\n *   and is therefore not a servable route; callers check the path first.\n */\nexport const resolveAmpliencePlpPreviewPath = (\n  path: string,\n  categoryId: number,\n): string => {\n  const previewSegment = `${PLP_PREVIEW_SLUG_PREFIX}-${categoryId}`\n  const match = path.match(/^(.*\\/c\\/)[^/]*$/)\n\n  if (match?.[1]) {\n    return `${match[1]}${previewSegment}`\n  }\n\n  return `/c/${previewSegment}`\n}\n","import type { CMSCspConfig } from '@scayle/storefront/cms'\nimport { isAmplienceEditorRequest } from './preview'\n\n/**\n * CSP configuration for the Amplience provider.\n * Allows the Dynamic Content app to embed the storefront in a visualization\n * iframe, and allows the storefront to load Dynamic Media assets while previewing.\n *\n * The app origins are the only embedders: `app.amplience.net` is the current\n * Dynamic Content app and `app.bigcontent.io` the legacy one. The client bridge\n * (`dc-visualization-sdk`, used by `useAmplienceEditor`) is bundled with the\n * application and talks to the parent frame over `postMessage`, which CSP does not\n * gate, so no script or connection to an app origin is allowed. `connect-src` covers the Dynamic Media\n * video metadata request `VideoComponent` makes. That request goes to\n * `*.adis.ws` on hubs provisioned before Amplience moved Dynamic Media to\n * `*.amplience.net`, so both hosts stay listed. Drop `*.adis.ws` once no hub in\n * use serves media from it.\n *\n * No `img-src` or `media-src` entry is declared. The middleware appends\n * directives, so naming either one would start restricting image and video\n * sources for visualization requests only, and CMS blocks that render product\n * cards (single product, product sliders, recently viewed) load their images\n * from the shop's own CDN rather than from Dynamic Media. Preview would show\n * broken product images while the published page renders fine.\n */\nexport const cspConfig: CMSCspConfig = {\n  isPreviewRequest: isAmplienceEditorRequest,\n  directives: {\n    'frame-ancestors':\n      \"'self' https://app.amplience.net https://app.bigcontent.io\",\n    'connect-src': \"'self' https://*.amplience.net https://*.adis.ws\",\n  },\n}\n","import { ContentClient, ContentNotFoundError } from 'dc-delivery-sdk-js'\nimport {\n  CMSContentNotFoundError,\n  extractErrorStatus,\n  wrapClientInit,\n} from '@scayle/storefront/cms'\nimport type {\n  CMSCspConfig,\n  CMSEditorData,\n  CMSPagePayload,\n  CMSProviderService,\n  CMSRequestLike,\n} from '@scayle/storefront/cms'\nimport { createLogger } from '@scayle/storefront/shared'\nimport type { StorefrontContext } from '@scayle/storefront/types'\nimport { cspConfig } from './csp'\nimport {\n  getPreviewDeliveryKeyFromRequest,\n  getVseFromRequest,\n  isAmplienceCategoryRoutePath,\n  isAmplienceEditorRequest,\n  parseCategoryIdFromAmplienceDeliveryKey,\n  resolveAmpliencePlpPreviewPath,\n} from './preview'\n\nconst log = createLogger('cms')\n\n/** Cache TTL for published CMS content: 5 minutes. */\nconst CACHE_TTL_SECONDS = 5 * 60\n\ndeclare module '@scayle/storefront/cms' {\n  /**\n   * Fields added by `AmplienceCMSService.getCMSEditorData()` for the client-side\n   * visualization bridge. A tenant project can layer further fields onto\n   * `CMSEditorData` with its own `declare module` block; TypeScript merges\n   * augmentations from every file in the program.\n   */\n  export interface CMSEditorData {\n    /** Virtual Staging Environment hostname for the current visualization session. */\n    vse?: string\n    /** Delivery key of the content item the editor currently has open. */\n    deliveryKey?: string\n  }\n}\n\n/**\n * Configuration accepted by {@link AmplienceCMSService}'s constructor.\n * The boilerplate reads these from environment variables and passes plain\n * values in, so this package never touches `process.env` directly.\n */\nexport interface AmplienceCMSServiceConfig {\n  /** Content Delivery 2 hub name, used as the delivery subdomain. */\n  hubName: string\n  /** Whether to serve staging content when the request is in editor mode. */\n  draftContentEnabled: boolean\n}\n\n/**\n * Amplience CMS provider service.\n *\n * Amplience localizes at the content-item level rather than by delivery\n * endpoint, so the client itself is locale-agnostic and every lookup goes\n * through a locale-prefixed delivery key (`de-DE/content/about`). The published\n * client is a static singleton; a Virtual Staging Environment client is built\n * per request because the staging domain is issued per visualization session.\n *\n * Category pages resolve by delivery key (`{locale}/c/c-{categoryId}`), not\n * through Amplience's Filter API. Content Delivery 2 binds content items to a\n * locale, and items without an explicit locale assignment fall outside the\n * delivery-layer locale filter entirely, which made filter-based resolution\n * unreliable. The V2 provider reached the same conclusion; see\n * `v2/boilerplate/modules/cms/providers/amplience/AMPLIENCE.md`.\n *\n * @see https://amplience.com/developers/docs/apis/content-delivery/\n */\nexport class AmplienceCMSService implements CMSProviderService {\n  /** Published clients keyed by hub name, so two hubs in one process do not share a client. */\n  private static deliveryClients = new Map<string, ContentClient>()\n\n  readonly cspConfig: CMSCspConfig = cspConfig\n\n  private readonly config: AmplienceCMSServiceConfig\n\n  private readonly context: StorefrontContext\n\n  constructor(config: AmplienceCMSServiceConfig, context: StorefrontContext) {\n    if (!config.hubName) {\n      throw new Error(\n        'Amplience CMS initialization failed: missing or empty hub name. Check that AMPLIENCE_CMS_HUB_NAME is set.',\n      )\n    }\n\n    this.config = config\n    this.context = context\n  }\n\n  /**\n   * Checks whether the current request originates from the Amplience\n   * visualization iframe, detected via the `vse` query parameter.\n   *\n   * @param request Incoming request\n   * @returns True when the request is an Amplience editor session\n   */\n  isEditorMode(request: CMSRequestLike): boolean {\n    return isAmplienceEditorRequest(request)\n  }\n\n  /**\n   * Builds editor data for the current request.\n   * The client-side visualization bridge needs the staging domain and the\n   * delivery key of the open item to subscribe to editor updates.\n   *\n   * Gated on the same staging check the fetch path uses, so a deployment with\n   * drafts disabled does not ship a staging domain to the client after the server\n   * has already refused to read from it.\n   *\n   * @param request Incoming request, used to detect editor mode\n   * @returns Editor data fields for Inertia page props, or undefined outside an editor session\n   */\n  getCMSEditorData(request: CMSRequestLike): CMSEditorData | undefined {\n    const vse = this.resolveStagingEnvironment(request)\n\n    if (!vse) {\n      return undefined\n    }\n\n    return {\n      vse,\n      deliveryKey: getPreviewDeliveryKeyFromRequest(request),\n    }\n  }\n\n  /**\n   * Resolves the category route a product listing page visualization belongs on.\n   *\n   * The Product Listing Page content type opens preview at a placeholder path\n   * (`/c/cms-preview-0`), because Amplience can only substitute the delivery key\n   * into the visualization URI, not the category ID the route needs. The category\n   * ID is parsed back out of that delivery key so the request can be redirected\n   * onto the real category route, where products, filters, and navigation load\n   * as they do outside preview.\n   *\n   * Only the placeholder path is rewritten. A path whose trailing ID is already the\n   * category the delivery key names is served as-is, because the listing controller\n   * redirects a non-canonical slug to the canonical one and keeps the query string:\n   * rewriting `/de/c/women-50350` back to `/de/c/cms-preview-50350` would bounce\n   * between the two forever.\n   *\n   * @param request Incoming request, used to detect editor mode and read the preview delivery key\n   * @param path Current request path\n   * @returns Category route path carrying the parsed category ID, or undefined when the\n   *   request is not a category page visualization\n   */\n  getPreviewRedirectPath(\n    request: CMSRequestLike,\n    path: string,\n  ): string | undefined {\n    if (!this.isEditorMode(request) || !isAmplienceCategoryRoutePath(path)) {\n      return undefined\n    }\n\n    const deliveryKey = getPreviewDeliveryKeyFromRequest(request)\n\n    if (!deliveryKey) {\n      return undefined\n    }\n\n    const categoryId = parseCategoryIdFromAmplienceDeliveryKey(deliveryKey)\n\n    // Any other content type visualized on a category path (a `page` item opened\n    // there by hand, for instance) keeps the path it was opened on.\n    if (categoryId === undefined) {\n      return undefined\n    }\n\n    // The canonical category path already carries this ID, so it needs no rewrite.\n    if (path.match(/-(\\d+)$/)?.[1] === String(categoryId)) {\n      return undefined\n    }\n\n    return resolveAmpliencePlpPreviewPath(path, categoryId)\n  }\n\n  private getDeliveryClient(): ContentClient {\n    const cached = AmplienceCMSService.deliveryClients.get(this.config.hubName)\n\n    if (cached) {\n      return cached\n    }\n\n    const client = wrapClientInit(\n      () => new ContentClient({ hubName: this.config.hubName }),\n      'Amplience delivery client initialization failed. Check that AMPLIENCE_CMS_HUB_NAME is a valid Content Delivery 2 hub name',\n    )\n\n    AmplienceCMSService.deliveryClients.set(this.config.hubName, client)\n\n    return client\n  }\n\n  /**\n   * Builds a Virtual Staging Environment client for one visualization session.\n   *\n   * Not cached: the staging domain is issued per editor session, so a shared\n   * instance would serve one editor's drafts to another.\n   *\n   * The hostname must already have passed `getVseFromRequest`, which is what\n   * keeps an attacker-supplied `vse` parameter from reaching `ContentClient`.\n   * Any new call site has to validate first.\n   *\n   * @param stagingEnvironment Validated VSE hostname from the request\n   * @returns Content client targeting the staging environment\n   */\n  private createStagingClient(stagingEnvironment: string): ContentClient {\n    return wrapClientInit(\n      () =>\n        new ContentClient({\n          hubName: this.config.hubName,\n          stagingEnvironment,\n        }),\n      'Amplience staging client initialization failed. Check that the vse query parameter holds a valid Virtual Staging Environment domain',\n    )\n  }\n\n  /**\n   * Decides whether this request should be served staging content, and from where.\n   *\n   * Draft preview needs both an Amplience-supplied VSE domain and\n   * `draftContentEnabled`. Without the flag the storefront ignores the VSE domain\n   * and serves published content, which is what keeps production safe when a\n   * visualization URL leaks.\n   *\n   * @param request Incoming request\n   * @returns Staging hostname when staging content should be served, otherwise undefined\n   */\n  private resolveStagingEnvironment(\n    request: CMSRequestLike,\n  ): string | undefined {\n    if (!this.config.draftContentEnabled) {\n      return undefined\n    }\n\n    return getVseFromRequest(request)\n  }\n\n  /**\n   * Builds the locale-prefixed delivery key for a content page.\n   * Override to change the delivery-key layout without touching the fetch path.\n   *\n   * @param slug CMS slug (for example `content/about` or `homepage`)\n   * @param locale Storefront locale code\n   * @returns Delivery key to look up\n   */\n  protected buildPageDeliveryKey(slug: string, locale: string): string {\n    return `${locale}/${slug}`\n  }\n\n  /**\n   * Builds the locale-prefixed delivery key for a category page.\n   * Override to change the delivery-key layout without touching the fetch path.\n   *\n   * @param categoryId SCAYLE category ID\n   * @param locale Storefront locale code\n   * @returns Delivery key to look up\n   */\n  protected buildListingDeliveryKey(\n    categoryId: number,\n    locale: string,\n  ): string {\n    return `${locale}/c/c-${categoryId}`\n  }\n\n  /**\n   * Fetches one content item by delivery key.\n   *\n   * The delivery SDK returns content wrapped in classes that carry `toJSON`\n   * hooks. Those do not survive serialization into Inertia page props, so the\n   * payload is round-tripped through JSON to get plain objects.\n   *\n   * @param deliveryKey Delivery key to look up\n   * @param stagingEnvironment VSE hostname, when serving staging content\n   * @param details Context attached to a thrown `CMSContentNotFoundError`\n   * @returns Plain content payload\n   * @throws {CMSContentNotFoundError} When no content item matches the delivery key\n   */\n  private async fetchByDeliveryKey(\n    deliveryKey: string,\n    stagingEnvironment: string | undefined,\n    details: Record<string, unknown>,\n  ): Promise<CMSPagePayload> {\n    const client = stagingEnvironment\n      ? this.createStagingClient(stagingEnvironment)\n      : this.getDeliveryClient()\n\n    try {\n      const content = await client.getContentItemByKey(deliveryKey)\n\n      return JSON.parse(JSON.stringify(content)) as CMSPagePayload\n    } catch (error) {\n      if (\n        error instanceof ContentNotFoundError ||\n        extractErrorStatus(error) === 404\n      ) {\n        throw new CMSContentNotFoundError('Amplience content not found', {\n          cause: error,\n          details: { ...details, deliveryKey },\n        })\n      }\n\n      const cause = error instanceof Error ? error : new Error(String(error))\n      throw new Error(\n        `Amplience API request failed (delivery key: \"${deliveryKey}\"): ${cause.message}`,\n        { cause },\n      )\n    }\n  }\n\n  /**\n   * Retrieves CMS page content from Amplience by slug, with caching.\n   *\n   * In an editor session the delivery key Amplience passes as `?key=` wins over\n   * the one derived from the slug, so the editor previews exactly the item it has\n   * open even when that item is not the one the URL maps to.\n   *\n   * @param slug CMS slug\n   * @param locale Storefront locale code\n   * @param request Incoming request, used to detect editor mode and read the preview delivery key\n   * @returns Amplience page data. Never undefined in practice: the wider return type\n   * comes from the `CMSProviderService` contract, and a missing item throws instead.\n   * @throws {CMSContentNotFoundError} When no content item matches the delivery key\n   */\n  async fetchPageData(\n    slug: string,\n    locale: string,\n    request: CMSRequestLike,\n  ): Promise<CMSPagePayload | undefined> {\n    const stagingEnvironment = this.resolveStagingEnvironment(request)\n    // In preview, prefer the key of the item the editor has open, otherwise derive it from the URL.\n    const deliveryKey = stagingEnvironment\n      ? getPreviewDeliveryKeyFromRequest(request) ||\n        this.buildPageDeliveryKey(slug, locale)\n      : this.buildPageDeliveryKey(slug, locale)\n\n    if (stagingEnvironment) {\n      log.debug({\n        message: 'Bypassing CMS cache in preview mode',\n        slug,\n        locale,\n      })\n\n      return await this.fetchByDeliveryKey(deliveryKey, stagingEnvironment, {\n        slug,\n        locale,\n      })\n    }\n\n    return await this.context.cache.getOrSet(\n      `cms:amplience:page:${deliveryKey}`,\n      // Cast required: StorageValue excludes undefined, but the fetch can return undefined for missing content\n      () =>\n        this.fetchByDeliveryKey(deliveryKey, undefined, {\n          slug,\n          locale,\n        }) as never,\n      CACHE_TTL_SECONDS,\n    )\n  }\n\n  /**\n   * Retrieves CMS content for a product listing page, with caching.\n   *\n   * Converts a missing content item into `undefined` rather than throwing, since\n   * most categories have no CMS content and that is not an error.\n   *\n   * @param categoryId SCAYLE category ID\n   * @param locale Storefront locale code\n   * @param request Incoming request, used to detect editor mode and read the preview delivery key\n   * @returns Amplience listing page data, or undefined when the category has no content\n   */\n  async fetchListingPageData(\n    categoryId: number,\n    locale: string,\n    request: CMSRequestLike,\n  ): Promise<CMSPagePayload | undefined> {\n    const stagingEnvironment = this.resolveStagingEnvironment(request)\n    // In preview, prefer the key of the item the editor has open, otherwise derive it from the category.\n    const deliveryKey = stagingEnvironment\n      ? getPreviewDeliveryKeyFromRequest(request) ||\n        this.buildListingDeliveryKey(categoryId, locale)\n      : this.buildListingDeliveryKey(categoryId, locale)\n\n    const fetchListing = async () => {\n      try {\n        return await this.fetchByDeliveryKey(deliveryKey, stagingEnvironment, {\n          categoryId,\n          locale,\n        })\n      } catch (error) {\n        if (error instanceof CMSContentNotFoundError) {\n          return undefined\n        }\n\n        log.error({\n          message: 'Failed to fetch CMS listing page data',\n          err: error instanceof Error ? error : new Error(String(error)),\n          categoryId,\n          locale,\n        })\n\n        throw error\n      }\n    }\n\n    if (stagingEnvironment) {\n      log.debug({\n        message: 'Bypassing CMS PLP cache in preview mode',\n        categoryId,\n        locale,\n      })\n\n      return await fetchListing()\n    }\n\n    return await this.context.cache.getOrSet(\n      `cms:amplience:plp:${deliveryKey}`,\n      // Cast required: StorageValue excludes undefined, but the fetch can return undefined for missing content\n      () => fetchListing() as never,\n      CACHE_TTL_SECONDS,\n    )\n  }\n}\n"],"mappings":";;;AAYA,MAAMA,QAAM,aAAa,KAAK;AAG9B,MAAa,0BAA0B;AAGvC,MAAM,+BAA+B;AAGrC,MAAM,eAAe;;;;;;;;;;;;;;AAoBnB,MAAA,4BAA+B,YAAa;CAE5C,OAAK,QACH,kBAAA,OAAA,CAAA;AAGF;AAGE,MAAA,oCAAS,YAAA;CACP,OAAA,QAAS,MAAA,KAAA,KAAA,KAAA;AACT;AAGF,MAAA,2CAAA,sBAAA;CACF,MAAA,QAAA,kBAAA,KAAA,CAAA,CAAA,MAAA,4BAAA;CAEA,IAAA,CAAA,QAAO,IAAA;CACT,MAAA,aAAA,OAAA,SAAA,MAAA,IAAA,EAAA;;;;;;;;CAWA,MAAa,QAAA,KAAA,MAAA,kBAA4B;CACvC,IAAA,QAAO,IAAQ,OAAA,GAAA,MAAA,KAAkB;CACnC,OAAA,MAAA;;;;;;;;;AAaA,MAAa,MAAA,aAAA,KAAA;AAIb,MAAA,oBAAA;;;;;;;;;;;;;;CAqBE,iBAAc,SAAA;EAEd,MAAK,MAAQ,KACX,0BAAA,OAAA;EAGF,IAAA,CAAM,KAAA;EACN,OAAO;GACT;;;;;;EAQA,MAAa,cAAA,iCAA0D,OAAA;EACrE,IAAA,CAAA,aAAO;EACT,MAAA,aAAA,wCAAA,WAAA;;;;;;;;;;;;;;;GAiBA;EAIE,CAAA,GAAA,qIAAqD;CACrD;CAMA,0BAAa,SAAA;EACf,IAAA,CAAA,KAAA,OAAA,qBAAA;;;;;;;;;;;;;;;;;;;;;GCpIA,CAAA;GACE,MAAA,QAAA,iBAAkB,QAAA,QAAA,IAAA,MAAA,OAAA,KAAA,CAAA;GAClB,MAAA,IAAY,MAAA,gDAAA,YAAA,MAAA,MAAA,WAAA,EAAA,MAAA,CAAA;EACV;CAEA;CAEJ,MAAA,cAAA,MAAA,QAAA,SAAA;;ECPA,MAAM,cAAM,qBAAkB,iCAAA,OAAA,KAAA,KAAA,qBAAA,MAAA,MAAA,IAAA,KAAA,qBAAA,MAAA,MAAA;;GAG9B,IAAM,MAAA;;;;;;;;;;;;;;;;;;EA+CN,MAAa,eAAA,YAAA;;IAEX,OAAe,MAAA,KAAA,mBAAA,aAAiD,oBAAA;KAEvD;KAEQ;IAEA,CAAA;GAEjB,SAAA,OAAY;IACV,IAAK,iBACH,yBACE;IAIJ,IAAK,MAAA;KACL,SAAK;KACP,KAAA,iBAAA,QAAA,QAAA,IAAA,MAAA,OAAA,KAAA,CAAA;;;;;;;;GASA,IAAA,MAAA;IACE,SAAO;IACT"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@scayle/storefront-cms-amplience",
+  "version": "0.2.0-alpha.0",
+  "description": "Amplience CMS provider integration for the SCAYLE Storefront Application V3",
+  "author": "SCAYLE Commerce Engine",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "files": [
+    "CHANGELOG.md",
+    "dist"
+  ],
+  "engines": {
+    "node": ">= 24.0.0"
+  },
+  "peerDependencies": {
+    "dc-delivery-sdk-js": "^1.4.0",
+    "@scayle/storefront": "1.0.0-alpha.2"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@types/node": "^24",
+    "@vitest/coverage-v8": "4.1.10",
+    "dc-delivery-sdk-js": "^1.4.0",
+    "eslint": "10.8.1",
+    "eslint-formatter-gitlab": "7.2.0",
+    "publint": "0.3.23",
+    "typescript": "6.0.3",
+    "obuild": "0.4.38",
+    "vitest": "4.1.10",
+    "@scayle/eslint-config-storefront": "4.8.3-alpha.0",
+    "@scayle/storefront": "1.0.0-alpha.2",
+    "@scayle/vitest-config-storefront": "1.0.0"
+  },
+  "scripts": {
+    "build": "obuild",
+    "lint": "eslint .",
+    "lint:ci": "eslint . --format gitlab",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "package:lint": "publint",
+    "verify-packaging": "attw --pack . --profile esm-only"
+  }
+}