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

package/README.md

@@ -0,0 +1,125 @@
+# @scayle/storefront-cms-storyblok
+
+Storyblok CMS provider integration for the SCAYLE Storefront Application V3.
+
+> **Requires Storefront Application V3.** This package implements `CMSProviderService` from
+> `@scayle/storefront`. Controllers resolve the constructed provider from the `ServiceRegistry` and call
+> `fetchPageData`/`fetchListingPageData` directly. It has no standalone use outside a Storefront
+> Application V3 project.
+
+## Package entrypoint
+
+| Export                      | Use                                                                                                                                                                                                      |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `StoryblokCMSService`       | Concrete `CMSProviderService` implementation. Generic over the tenant's generated Storyblok content-type shape (`TPageData`), defaulting to `MinimalStoryblokPageData` so the package builds standalone. |
+| `StoryblokCMSServiceConfig` | Configuration object for the service (access token and optional folder mapping).                                                                                                                         |
+| `MinimalStoryblokPageData`  | Minimal interface for Storyblok page data shape.                                                                                                                                                         |
+| `cspConfig`                 | `CMSCspConfig` for the Storyblok Visual Editor: iframe embedding, bridge script, and API connect rules.                                                                                                  |
+
+See [Storyblok's API documentation](https://www.storyblok.com/docs/api/content-delivery/v2) and the
+[`@storyblok/js` package docs](https://www.storyblok.com/docs/packages/storyblok-js) for the underlying client.
+
+## Configuration
+
+The `StoryblokCMSServiceConfig` object is constructed from environment variables in the boilerplate's
+`src/server/cms/providers/storyblok/service.ts` via `getRequiredEnv` and `process.env`. These same variables
+are documented in `.env.example`.
+
+| Field                 | Required | Purpose                                                                                                                                                                                                  | Env Variable                                        | Found In                                                  | Documentation                                                                                       |
+| --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `accessToken`         | Yes      | Content Delivery API access token used to authenticate requests to Storyblok                                                                                                                             | `STORYBLOK_CMS_ACCESS_TOKEN`                        | Storyblok web app: **Space Settings** > **Access Tokens** | [Storyblok API authentication](https://www.storyblok.com/docs/guide/essentials/apis#authentication) |
+| `draftContentEnabled` | Yes      | Whether draft/unpublished content may be served during an editor session                                                                                                                                 | `STOREFRONT_CMS_ALLOW_DRAFTS` (read by boilerplate) | N/A                                                       |                                                                                                     |
+| `folderMapping`       | No       | Maps storefront locale codes to Storyblok folder names. Defaults to `{ de: 'de', en: 'en' }` when omitted, allowing tenants whose folder names differ from their locale codes to supply custom mappings. | Not from env; configured directly in service.ts     | N/A                                                       | [Storyblok folder structure docs](https://www.storyblok.com/docs/guide/essentials/folders)          |
+
+## Usage
+
+The boilerplate's `src/server/cms/providers/storyblok/service.ts` binds the generic and constructs the
+service:
+
+```ts
+import { StoryblokCMSService } from '@scayle/storefront-cms-storyblok'
+import type { StoryblokPageData } from '@shared/types/cms/storyblok'
+
+export const createCMSService = (storefront: StorefrontContext) =>
+  new StoryblokCMSService<StoryblokPageData>(
+    {
+      accessToken: getRequiredEnv('STORYBLOK_CMS_ACCESS_TOKEN'),
+      draftContentEnabled:
+        process.env.STOREFRONT_CMS_ALLOW_DRAFTS?.toLowerCase() === 'true',
+      folderMapping: { de: 'de', en: 'en' },
+    },
+    storefront,
+  )
+```
+
+The `storefront` context is used for the service's own application-level caching.
+
+The boilerplate registers `createCMSService(storefront)` as the `cms` slot on the `ServiceRegistry`
+(`src/server/registries.ts`), alongside every other domain. A controller resolves it from there, calls
+`resolveCmsRequest()` (`src/server/cms/utils/request.ts`) for editor-mode detection and draft handling,
+then calls `fetchPageData`/`fetchListingPageData` directly with the raw request:
+
+```ts
+const { isCmsEditorSession, cmsEditorData } = resolveCmsRequest(
+  this.services.cms,
+  this.ctx.req,
+)
+const pageData = await this.services.cms.fetchPageData(
+  slug,
+  locale,
+  this.ctx.req,
+)
+```
+
+See `@scayle/storefront`'s CMS module for the `CMSProviderService` contract this package implements.
+
+## Architecture
+
+`StoryblokCMSService` implements `CMSProviderService` directly — there is no shared base class. Each
+provider package owns its own caching, error handling, and constructor validation, so this package can
+diverge from Contentful/Contentstack without a `@scayle/storefront` release touching them:
+
+- **`fetchPageData`** wraps the raw fetch with application-level caching (`context.cache.getOrSet(...)`,
+  5-minute TTL, bypassed entirely in draft-content mode) under the cache-key pattern
+  `cms:storyblok:page:${slug}:${locale}`. The raw fetch resolves the tenant's locale-to-folder mapping,
+  fetches the story from the Storyblok Content Delivery API, and throws `CMSContentNotFoundError` on a
+  404 so the caller can distinguish "not found" from a real API failure.
+- **`fetchListingPageData`** wraps the same raw fetch (against a synthetic `c/c-{categoryId}` slug, since
+  Storyblok stores PLP content as regular stories) with caching under
+  `cms:storyblok:plp:${categoryId}:${locale}`, and converts a `CMSContentNotFoundError` into `undefined`
+  (missing PLP content is expected, not an error), logging any other error before rethrowing it.
+- **`getAlternatePaths`** reads locale alternates directly off the
+  fetched story.
+- **`isEditorMode`** detects the Storyblok Visual Editor via the `_storyblok` query parameter.
+- **Draft-content decision**: controlled by the `draftContentEnabled` boolean in the service config,
+  read from the `STOREFRONT_CMS_ALLOW_DRAFTS` environment variable in the boilerplate factory.
+  When both `isEditorMode()` returns true and `draftContentEnabled` is true, the service fetches
+  the draft version; otherwise it fetches published content.
+
+The API client is a lazily initialized static singleton shared across requests, since `@storyblok/js`'s
+client carries no per-request state. Construction goes through `@scayle/storefront/cms`'s `wrapClientInit`,
+so a bad access token fails with a message naming the client and the env var to check, not a bare SDK error.
+
+**Generic content types stay in the boilerplate.** Storyblok's content-type shape is entirely
+tenant-defined (whatever components exist in the tenant's Storyblok space), so `StoryblokCMSService<TPageData>`
+takes the shape as a generic parameter rather than importing it. The tenant's generated types live in
+`src/shared/types/cms/storyblok/gen/`, regenerated per-tenant by `pnpm cms:sync`. They can never ship
+inside this package.
+
+## Extending and customizing
+
+Within a tenant project, all customization happens in the boilerplate's
+`src/server/cms/providers/storyblok/service.ts`, by subclassing `StoryblokCMSService`:
+
+- **Query shape**: override `buildStoryQuery(locale, useDraftContent, request)` to change version resolution, resolved
+  links, or add other `client.get(...)` query params, without touching slug resolution or error handling.
+- **Response shape**: override `transformStoryResponse(response)` to keep additional response fields
+  beyond `story`.
+- **CSP rules**: re-export a modified `cspConfig` (imported from this package as a base) if the tenant's
+  Storyblok space is on a different domain or needs additional directives.
+- **Locale-to-folder mapping**: pass a custom `folderMapping` in the service config if the tenant's
+  Storyblok space uses folder names that don't match its locale codes.
+
+Do not reimplement `fetchPageData` or `fetchListingPageData` from scratch. Override only the method that
+needs to change and call `super` for everything else, so the tenant subclass tracks fixes made to this
+package.

package/dist/index.d.mts

@@ -0,0 +1,123 @@
+import { CMSCspConfig, CMSEditorData, CMSPagePayload, CMSProviderService, CMSRequestLike } from "@scayle/storefront/cms";
+import { StorefrontContext } from "@scayle/storefront/types";
+/**
+ * Configuration for the Storyblok CMS service.
+ */
+interface StoryblokCMSServiceConfig {
+  /** The Storyblok API access token. */
+  accessToken: string;
+  /** Enable draft content in editor mode. */
+  draftContentEnabled: boolean;
+  /** Maps storefront locale codes to Storyblok folder names. Defaults to `{ de: 'de', en: 'en' }` when omitted. */
+  folderMapping?: Record<string, string>;
+}
+/**
+ * Minimal generic default so the package builds and can be used standalone
+ * without a tenant's generated types. A tenant subclass binds `TPageData` to
+ * its own generated `StoryblokPageData` type.
+ */
+interface MinimalStoryblokPageData extends Record<string, unknown> {
+  story?: {
+    content?: {
+      component?: string;
+      [key: string]: unknown;
+    };
+    alternates?: {
+      id: number;
+      slug: string;
+      published: boolean;
+    }[];
+    full_slug?: string;
+  };
+}
+/**
+ * Storyblok CMS provider service.
+ * Manages a singleton API client that is lazily initialized on first use.
+ * Generic over the tenant's generated Storyblok content-type shape
+ * (`TPageData`); the tenant subclass binds this to its own generated types
+ * from `src/shared/types/cms/storyblok`.
+ *
+ * This binding cannot move into this package: `TPageData` is generated by
+ * `pnpm cms:sync` from the tenant's own Storyblok space, so its shape differs
+ * per tenant and is regenerated on demand. A versioned npm package ships one
+ * fixed artifact for every tenant, so it can only stay generic here — the
+ * concrete type has to be supplied where it's generated, in the boilerplate.
+ *
+ * @see https://www.storyblok.com/docs/packages/storyblok-js
+ */
+declare class StoryblokCMSService<TPageData extends MinimalStoryblokPageData = MinimalStoryblokPageData> implements CMSProviderService {
+  /** Shared across all instances so the API client is created once, not per request. */
+  private static client;
+  readonly cspConfig: CMSCspConfig;
+  private readonly accessToken;
+  private readonly context;
+  private readonly draftContentEnabled;
+  private readonly folderMapping;
+  constructor(config: StoryblokCMSServiceConfig, context: StorefrontContext);
+  private getClient;
+  isEditorMode(request: CMSRequestLike): boolean;
+  getCMSEditorData(request: CMSRequestLike): CMSEditorData | undefined;
+  /**
+   * Builds the Storyblok Content Delivery API query for a story lookup.
+   * Override to change version resolution, resolved links, or add other
+   * `client.get(...)` query params.
+   *
+   * @param locale Storefront locale code
+   * @param useDraftContent Whether to fetch draft content version
+   * @param request Incoming request for accessing query parameters
+   * @returns Query object passed to `client.get('cdn/stories/...', query)`
+   */
+  protected buildStoryQuery(locale: string, useDraftContent: boolean, request: CMSRequestLike): Record<string, unknown>;
+  /**
+   * Transforms a Storyblok Content Delivery API response into the page payload.
+   * Override to keep additional response fields beyond `story`.
+   *
+   * @param response Raw response from `client.get('cdn/stories/...')`
+   * @param response.data Response body
+   * @param response.data.story Story payload, or undefined when none matched
+   * @returns Page payload, or undefined when the response has no story
+   */
+  protected transformStoryResponse(response: {
+    data?: {
+      story?: unknown;
+    };
+  }): TPageData | undefined;
+  private fetchRawPageData;
+  /**
+   * Retrieves CMS page data with application-level caching.
+   * Draft content requests bypass the cache entirely.
+   *
+   * @param slug CMS slug
+   * @param locale Storefront locale code
+   * @param request Incoming request, used to detect editor mode and read editor-specific query params
+   * @returns Storyblok page data or undefined
+   */
+  fetchPageData(slug: string, locale: string, request: CMSRequestLike): Promise<TPageData | undefined>;
+  /**
+   * Retrieves CMS content for a product listing page, with caching.
+   * Converts a missing entry into `undefined` rather than throwing, since
+   * missing PLP content is expected, not an error condition.
+   *
+   * @param categoryId SCAYLE category ID
+   * @param locale Storefront locale code
+   * @param request Incoming request, used to detect editor mode and read editor-specific query params
+   * @returns Storyblok listing page data or undefined
+   */
+  fetchListingPageData(categoryId: number, locale: string, request: CMSRequestLike): Promise<TPageData | undefined>;
+  /**
+   * Extracts per-locale page paths from a Storyblok story using its
+   * `alternates` and the configured folder mapping.
+   *
+   * @param data CMS page payload containing a Storyblok story.
+   * @returns Per-locale page path map, or undefined.
+   */
+  getAlternatePaths(data: CMSPagePayload): Record<string, string> | undefined;
+}
+/**
+ * CSP configuration for the Storyblok provider.
+ * Allows the Storyblok visual editor to embed the storefront in an iframe
+ * and load the bridge script for live editing.
+ */
+declare const cspConfig: CMSCspConfig;
+export { type MinimalStoryblokPageData, StoryblokCMSService, type StoryblokCMSServiceConfig, cspConfig };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/StoryblokCMSService.ts","../src/csp.ts"],"mappings":";;;;;UAmCiB;;EAEf;;EAEA;;EAEA,gBAAgB;;;;;;;UAQD,iCAAiC;EAChD;IACE;MAAY;;;IACZ;MAAe;MAAY;MAAc;;IACzC;;;;;;;;;;;;;;;;;;cAmBS,oBACX,kBAAkB,2BAA2B,qCAClC;;iBAEI;WAEN,WAAW;mBAEH;mBACA;mBACA;mBACA;EAEjB,YAAY,QAAQ,2BAA2B,SAAS;UAOhD;EA8BR,aAAa,SAAS;EAItB,iBAAiB,SAAS,iBAAiB;;;;;;;;;;;YAkBjC,gBACR,gBACA,0BACA,SAAS,iBACR;;;;;;;;;;YAmBO,uBAAuB;IAC/B;MAAS;;MACP;UAQU;;;;;;;;;;EAyCd,cACE,cACA,gBACA,SAAS,iBACR,QAAQ;;;;;;;;;;;EAgCX,qBACE,oBACA,gBACA,SAAS,iBACR,QAAQ;;;;;;;;EAqDX,kBAAkB,MAAM,iBAAiB;;;;;;;cChT9B,WAAW"}

package/dist/index.mjs

@@ -0,0 +1,172 @@
+import { apiPlugin, storyblokInit } from "@storyblok/js";
+import { CMSContentNotFoundError, ensureError, extractErrorStatus, wrapClientInit } from "@scayle/storefront/cms";
+import { createLogger } from "@scayle/storefront/shared";
+const extractLanguageCode = (locale) => locale.split("-")[0];
+const HOMEPAGE_SLUG$1 = "homepage";
+const stripSlashes = (value) => value.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+const resolveStoryblokSlug = (locale, slug, folderMapping = {}) => {
+	const localeCode = extractLanguageCode(locale);
+	const folder = folderMapping[localeCode] ?? localeCode;
+	let normalizedSlug = stripSlashes(slug);
+	if (!normalizedSlug) return `${folder}/${HOMEPAGE_SLUG$1}`;
+	const localePrefix = `${localeCode}/`;
+	if (normalizedSlug === localeCode) normalizedSlug = "";
+	else if (normalizedSlug.startsWith(localePrefix)) normalizedSlug = normalizedSlug.slice(localePrefix.length);
+	if (!normalizedSlug) return `${folder}/${HOMEPAGE_SLUG$1}`;
+	if (normalizedSlug.startsWith(`${folder}/`)) return normalizedSlug;
+	return `${folder}/${normalizedSlug}`;
+};
+function getFolderMappingKeysForPath(path, folderMapping) {
+	if (!folderMapping || !path) return [];
+	return Object.keys(folderMapping).filter((key) => folderMapping[key] === path && key !== path);
+}
+function getAllSourceSlugs(story, folderMapping) {
+	return [story.full_slug, ...story.alternates?.map((a) => a.full_slug) ?? []].reduce((acc, sourceSlug) => {
+		if (!sourceSlug) return acc;
+		const [path, ...rest] = sourceSlug.split("/");
+		if (!path) return acc;
+		const slug = rest.join("/");
+		const aliasKeys = getFolderMappingKeysForPath(path, folderMapping);
+		return [
+			...acc,
+			...aliasKeys.map((key) => ({
+				path: key,
+				slug
+			})),
+			{
+				path,
+				slug
+			}
+		];
+	}, []);
+}
+const cspConfig = {
+	isPreviewRequest: (req) => Boolean(req.query("_storyblok")),
+	directives: {
+		"frame-ancestors": "'self' https://app.storyblok.com",
+		"script-src": "'self' 'unsafe-inline' https://app.storyblok.com",
+		"connect-src": "'self' https://api.storyblok.com"
+	}
+};
+const log = createLogger("cms");
+const CACHE_TTL_SECONDS = 300;
+const HOMEPAGE_SLUG = "homepage";
+var StoryblokCMSService = class StoryblokCMSService {
+	static client;
+	cspConfig = cspConfig;
+	accessToken;
+	context;
+	draftContentEnabled;
+	folderMapping;
+	constructor(config, context) {
+		this.accessToken = config.accessToken;
+		this.draftContentEnabled = config.draftContentEnabled;
+		this.context = context;
+		this.folderMapping = config.folderMapping ?? {
+			de: "de",
+			en: "en"
+		};
+	}
+	getClient() {
+		if (StoryblokCMSService.client) return StoryblokCMSService.client;
+		if (!this.accessToken) throw new Error("Storyblok API client initialization failed: missing or empty access token. Check that STORYBLOK_CMS_ACCESS_TOKEN is set.");
+		const { storyblokApi } = wrapClientInit(() => storyblokInit({
+			accessToken: this.accessToken,
+			use: [apiPlugin]
+		}), "Storyblok API client initialization failed");
+		if (!storyblokApi) throw new Error("Storyblok API client initialization failed: storyblokInit() did not return an API client instance. Ensure @storyblok/js package and its apiPlugin are correctly installed and compatible.");
+		StoryblokCMSService.client = storyblokApi;
+		return StoryblokCMSService.client;
+	}
+	isEditorMode(request) {
+		return Boolean(request.query("_storyblok"));
+	}
+	getCMSEditorData(request) {
+		if (!this.isEditorMode(request)) return;
+		return {};
+	}
+	buildStoryQuery(locale, useDraftContent, request) {
+		const rawCv = request.query("_storyblok");
+		return {
+			version: useDraftContent ? "draft" : "published",
+			cv: rawCv ? Number(rawCv) : void 0,
+			language: extractLanguageCode(locale),
+			resolve_links: "url"
+		};
+	}
+	transformStoryResponse(response) {
+		if (!response.data?.story) return;
+		return { story: response.data.story };
+	}
+	async fetchRawPageData(slug, locale, useDraftContent, request) {
+		const storyblokSlug = resolveStoryblokSlug(locale, slug, this.folderMapping);
+		const client = this.getClient();
+		const query = this.buildStoryQuery(locale, useDraftContent, request);
+		try {
+			const response = await client.get(`cdn/stories/${storyblokSlug}`, query);
+			return this.transformStoryResponse(response);
+		} catch (error) {
+			const status = extractErrorStatus(error);
+			if (status === 404) throw new CMSContentNotFoundError("Storyblok content not found", {
+				cause: error,
+				details: {
+					slug,
+					locale,
+					storyblokSlug,
+					version: query.version
+				}
+			});
+			const cause = ensureError(error, "Storyblok API request failed");
+			throw new Error(`Storyblok API request failed (slug: "${slug}", locale: "${locale}", status: ${status ?? "unknown"}): ${cause.message}`, { cause });
+		}
+	}
+	async fetchPageData(slug, locale, request) {
+		const useDraftContent = this.isEditorMode(request) && this.draftContentEnabled;
+		if (useDraftContent) {
+			log.debug({
+				message: "Bypassing CMS cache in preview mode",
+				slug,
+				locale
+			});
+			return this.fetchRawPageData(slug, locale, useDraftContent, request);
+		}
+		return this.context.cache.getOrSet(`cms:storyblok:page:${slug}:${locale}`, () => this.fetchRawPageData(slug, locale, useDraftContent, request), CACHE_TTL_SECONDS);
+	}
+	async fetchListingPageData(categoryId, locale, request) {
+		const slug = `c/c-${categoryId}`;
+		const useDraftContent = this.isEditorMode(request) && this.draftContentEnabled;
+		const fetchListing = async () => {
+			try {
+				return await this.fetchRawPageData(slug, locale, useDraftContent, request);
+			} 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 (useDraftContent) {
+			log.debug({
+				message: "Bypassing CMS PLP cache in preview mode",
+				categoryId,
+				locale
+			});
+			return fetchListing();
+		}
+		return this.context.cache.getOrSet(`cms:storyblok:plp:${categoryId}:${locale}`, () => fetchListing(), CACHE_TTL_SECONDS);
+	}
+	getAlternatePaths(data) {
+		const story = data?.story;
+		if (!story?.alternates?.length) return;
+		const sourceSlugs = getAllSourceSlugs(story, this.folderMapping);
+		if (sourceSlugs.length <= 1) return;
+		return Object.fromEntries(sourceSlugs.map(({ path, slug }) => [path, !slug || slug === HOMEPAGE_SLUG ? "/" : `/${slug}`]));
+	}
+};
+export { StoryblokCMSService, cspConfig };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["HOMEPAGE_SLUG","pageData"],"sources":["../src/utils/slug.ts","../src/csp.ts","../src/StoryblokCMSService.ts"],"sourcesContent":["/**\n * Storyblok story type. Minimal interface for slug resolution.\n * In the boilerplate context, this is imported from `@shared/types/cms/storyblok`.\n * In the standalone package context, callers provide this shape directly.\n */\nexport interface StoryblokStory {\n  full_slug?: string\n  alternates?: Array<{ id: number; full_slug?: string; published: boolean }>\n}\n\n/** Extracts the language code portion of a storefront locale (e.g. `de` from `de-DE`). */\nexport const extractLanguageCode = (locale: string): string =>\n  locale.split('-')[0]\n\n/** Slug used to identify the homepage story; mapped to `/` in generated hreflangs. */\nconst HOMEPAGE_SLUG = 'homepage'\n\n// A single quantifier on one character class anchored at one end of the string\n// can't backtrack (there's nothing to retry against), so this is linear-time\n// regardless of input length - safe even though `slug` is attacker-controlled.\nconst stripSlashes = (value: string): string =>\n  // eslint-disable-next-line sonarjs/super-linear-regex\n  value.trim().replace(/^\\/+/, '').replace(/\\/+$/, '')\n\n/**\n * Resolves a Storyblok slug from storefront locale and requested slug.\n * Used by the Storyblok CMS service before requesting a story from the CDN API.\n *\n * @param locale Storefront locale in BCP-47 format\n * @param slug Requested CMS slug\n * @param folderMapping Optional locale folder mapping\n * @returns Storyblok content slug\n *\n * @example\n * ```ts\n * resolveStoryblokSlug('de-DE', '/content/about', { de: 'de' })\n * // \"de/content/about\"\n * ```\n *\n * @see https://www.storyblok.com/docs/concepts/internationalization\n */\nexport const resolveStoryblokSlug = (\n  locale: string,\n  slug: string,\n  folderMapping: Record<string, string> = {},\n): string => {\n  const localeCode = extractLanguageCode(locale)\n  const folder = folderMapping[localeCode] ?? localeCode\n\n  let normalizedSlug = stripSlashes(slug)\n\n  if (!normalizedSlug) {\n    return `${folder}/${HOMEPAGE_SLUG}`\n  }\n\n  const localePrefix = `${localeCode}/`\n  if (normalizedSlug === localeCode) {\n    normalizedSlug = ''\n  } else if (normalizedSlug.startsWith(localePrefix)) {\n    normalizedSlug = normalizedSlug.slice(localePrefix.length)\n  }\n\n  if (!normalizedSlug) {\n    return `${folder}/${HOMEPAGE_SLUG}`\n  }\n\n  if (normalizedSlug.startsWith(`${folder}/`)) {\n    return normalizedSlug\n  }\n\n  return `${folder}/${normalizedSlug}`\n}\n\n/**\n * Finds folder mapping keys that point to a given folder name.\n * Used to discover locale aliases when building hreflang links\n * (e.g. folder `\"german\"` maps to key `\"de\"`).\n *\n * @param path Folder name from a Storyblok full slug.\n * @param folderMapping Locale-to-folder mapping from provider config.\n * @returns Array of mapping keys whose value matches `path` but differ from `path` itself.\n */\nexport function getFolderMappingKeysForPath(\n  path?: string,\n  folderMapping?: Record<string, string>,\n): string[] {\n  if (!folderMapping || !path) {\n    return []\n  }\n\n  return Object.keys(folderMapping).filter(\n    (key) => folderMapping[key] === path && key !== path,\n  )\n}\n\n/**\n * Extracts all locale-folder/slug pairs from a Storyblok story and its alternates.\n * Extends with aliases from `folderMapping` when a folder name maps to multiple locale\n * keys (e.g. folder `\"german\"` aliased as both `\"de\"` and `\"german\"`).\n *\n * Used to build per-locale hreflang links where each locale may have a different CMS slug.\n *\n * @param story Storyblok story data including `full_slug` and `alternates`.\n * @param folderMapping Optional locale-to-folder mapping from provider config.\n * @returns Array of `{ path, slug }` pairs where `path` is the locale/folder key and\n *   `slug` is the page-relative path (e.g. `\"content/about\"`).\n *\n * @see https://www.storyblok.com/docs/concepts/internationalization\n */\nexport function getAllSourceSlugs(\n  story: StoryblokStory,\n  folderMapping?: Record<string, string>,\n): { path: string; slug: string }[] {\n  const sourceSlugsFromCMS = [\n    story.full_slug,\n    ...(story.alternates?.map((a) => a.full_slug) ?? []),\n  ]\n\n  return sourceSlugsFromCMS.reduce<{ path: string; slug: string }[]>(\n    (acc, sourceSlug) => {\n      if (!sourceSlug) {\n        return acc\n      }\n\n      const [path, ...rest] = sourceSlug.split('/')\n\n      if (!path) {\n        return acc\n      }\n\n      const slug = rest.join('/')\n      const aliasKeys = getFolderMappingKeysForPath(path, folderMapping)\n\n      return [\n        ...acc,\n        ...aliasKeys.map((key) => ({ path: key, slug })),\n        { path, slug },\n      ]\n    },\n    [],\n  )\n}\n","import type { CMSCspConfig } from '@scayle/storefront/cms'\n\n/**\n * CSP configuration for the Storyblok provider.\n * Allows the Storyblok visual editor to embed the storefront in an iframe\n * and load the bridge script for live editing.\n */\nexport const cspConfig: CMSCspConfig = {\n  isPreviewRequest: (req) => Boolean(req.query('_storyblok')),\n  directives: {\n    // Allows Storyblok to embed the storefront in an iframe for the Visual Editor.\n    // https://www.storyblok.com/docs/guide/essentials/visual-editor\n    'frame-ancestors': \"'self' https://app.storyblok.com\",\n    // Allows the Storyblok bridge script and Inertia inline hydration scripts.\n    // 'unsafe-inline' is required because Inertia injects inline scripts for\n    // SSR page data, and CSP may not include it when no upstream script-src exists.\n    // https://www.storyblok.com/docs/guide/essentials/visual-editor#bridge\n    'script-src': \"'self' 'unsafe-inline' https://app.storyblok.com\",\n    // Allows the Storyblok bridge to communicate with the Storyblok API\n    // for real-time content updates in the Visual Editor.\n    // https://www.storyblok.com/docs/api/content-delivery/v2\n    'connect-src': \"'self' https://api.storyblok.com\",\n  },\n}\n","import { storyblokInit, apiPlugin } from '@storyblok/js'\nimport type { StoryblokClient } from '@storyblok/js'\nimport {\n  CMSContentNotFoundError,\n  extractErrorStatus,\n  ensureError,\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 {\n  resolveStoryblokSlug,\n  getAllSourceSlugs,\n  extractLanguageCode,\n} from './utils/slug'\nimport { cspConfig } from './csp'\n\nconst log = createLogger('cms')\n\n/** Cache TTL for published CMS content: 5 minutes. */\nconst CACHE_TTL_SECONDS = 5 * 60\n\n/** Slug used to identify the homepage story; mapped to `/` in generated hreflangs. */\nconst HOMEPAGE_SLUG = 'homepage' as const\n\n/**\n * Configuration for the Storyblok CMS service.\n */\nexport interface StoryblokCMSServiceConfig {\n  /** The Storyblok API access token. */\n  accessToken: string\n  /** Enable draft content in editor mode. */\n  draftContentEnabled: boolean\n  /** Maps storefront locale codes to Storyblok folder names. Defaults to `{ de: 'de', en: 'en' }` when omitted. */\n  folderMapping?: Record<string, string>\n}\n\n/**\n * Minimal generic default so the package builds and can be used standalone\n * without a tenant's generated types. A tenant subclass binds `TPageData` to\n * its own generated `StoryblokPageData` type.\n */\nexport interface MinimalStoryblokPageData extends Record<string, unknown> {\n  story?: {\n    content?: { component?: string; [key: string]: unknown }\n    alternates?: { id: number; slug: string; published: boolean }[]\n    full_slug?: string\n  }\n}\n\n/**\n * Storyblok CMS provider service.\n * Manages a singleton API client that is lazily initialized on first use.\n * Generic over the tenant's generated Storyblok content-type shape\n * (`TPageData`); the tenant subclass binds this to its own generated types\n * from `src/shared/types/cms/storyblok`.\n *\n * This binding cannot move into this package: `TPageData` is generated by\n * `pnpm cms:sync` from the tenant's own Storyblok space, so its shape differs\n * per tenant and is regenerated on demand. A versioned npm package ships one\n * fixed artifact for every tenant, so it can only stay generic here — the\n * concrete type has to be supplied where it's generated, in the boilerplate.\n *\n * @see https://www.storyblok.com/docs/packages/storyblok-js\n */\nexport class StoryblokCMSService<\n  TPageData extends MinimalStoryblokPageData = MinimalStoryblokPageData,\n> implements CMSProviderService {\n  /** Shared across all instances so the API client is created once, not per request. */\n  private static client: StoryblokClient | undefined\n\n  readonly cspConfig: CMSCspConfig = cspConfig\n\n  private readonly accessToken: string\n  private readonly context: StorefrontContext\n  private readonly draftContentEnabled: boolean\n  private readonly folderMapping: Record<string, string>\n\n  constructor(config: StoryblokCMSServiceConfig, context: StorefrontContext) {\n    this.accessToken = config.accessToken\n    this.draftContentEnabled = config.draftContentEnabled\n    this.context = context\n    this.folderMapping = config.folderMapping ?? { de: 'de', en: 'en' }\n  }\n\n  private getClient(): StoryblokClient {\n    if (StoryblokCMSService.client) {\n      return StoryblokCMSService.client\n    }\n\n    if (!this.accessToken) {\n      throw new Error(\n        'Storyblok API client initialization failed: missing or empty access token. Check that STORYBLOK_CMS_ACCESS_TOKEN is set.',\n      )\n    }\n\n    const { storyblokApi } = wrapClientInit(\n      () =>\n        storyblokInit({\n          accessToken: this.accessToken,\n          use: [apiPlugin],\n        }),\n      'Storyblok API client initialization failed',\n    )\n\n    if (!storyblokApi) {\n      throw new Error(\n        'Storyblok API client initialization failed: storyblokInit() did not return an API client instance. Ensure @storyblok/js package and its apiPlugin are correctly installed and compatible.',\n      )\n    }\n\n    StoryblokCMSService.client = storyblokApi\n    return StoryblokCMSService.client\n  }\n\n  isEditorMode(request: CMSRequestLike): boolean {\n    return Boolean(request.query('_storyblok'))\n  }\n\n  getCMSEditorData(request: CMSRequestLike): CMSEditorData | undefined {\n    if (!this.isEditorMode(request)) {\n      return undefined\n    }\n\n    return {}\n  }\n\n  /**\n   * Builds the Storyblok Content Delivery API query for a story lookup.\n   * Override to change version resolution, resolved links, or add other\n   * `client.get(...)` query params.\n   *\n   * @param locale Storefront locale code\n   * @param useDraftContent Whether to fetch draft content version\n   * @param request Incoming request for accessing query parameters\n   * @returns Query object passed to `client.get('cdn/stories/...', query)`\n   */\n  protected buildStoryQuery(\n    locale: string,\n    useDraftContent: boolean,\n    request: CMSRequestLike,\n  ): Record<string, unknown> {\n    const rawCv = request.query('_storyblok')\n    return {\n      version: useDraftContent ? 'draft' : 'published',\n      cv: rawCv ? Number(rawCv) : undefined,\n      language: extractLanguageCode(locale),\n      resolve_links: 'url',\n    }\n  }\n\n  /**\n   * Transforms a Storyblok Content Delivery API response into the page payload.\n   * Override to keep additional response fields beyond `story`.\n   *\n   * @param response Raw response from `client.get('cdn/stories/...')`\n   * @param response.data Response body\n   * @param response.data.story Story payload, or undefined when none matched\n   * @returns Page payload, or undefined when the response has no story\n   */\n  protected transformStoryResponse(response: {\n    data?: { story?: unknown }\n  }): TPageData | undefined {\n    if (!response.data?.story) {\n      return undefined\n    }\n\n    return { story: response.data.story } as TPageData\n  }\n\n  private async fetchRawPageData(\n    slug: string,\n    locale: string,\n    useDraftContent: boolean,\n    request: CMSRequestLike,\n  ): Promise<TPageData | undefined> {\n    const storyblokSlug = resolveStoryblokSlug(locale, slug, this.folderMapping)\n    const client = this.getClient()\n    const query = this.buildStoryQuery(locale, useDraftContent, request)\n\n    try {\n      const response = await client.get(`cdn/stories/${storyblokSlug}`, query)\n\n      return this.transformStoryResponse(response)\n    } catch (error) {\n      const status = extractErrorStatus(error)\n\n      if (status === 404) {\n        throw new CMSContentNotFoundError('Storyblok content not found', {\n          cause: error,\n          details: { slug, locale, storyblokSlug, version: query.version },\n        })\n      }\n\n      const cause = ensureError(error, 'Storyblok API request failed')\n      throw new Error(\n        `Storyblok API request failed (slug: \"${slug}\", locale: \"${locale}\", status: ${status ?? 'unknown'}): ${cause.message}`,\n        { cause },\n      )\n    }\n  }\n\n  /**\n   * Retrieves CMS page data with application-level caching.\n   * Draft content requests bypass the cache entirely.\n   *\n   * @param slug CMS slug\n   * @param locale Storefront locale code\n   * @param request Incoming request, used to detect editor mode and read editor-specific query params\n   * @returns Storyblok page data or undefined\n   */\n  async fetchPageData(\n    slug: string,\n    locale: string,\n    request: CMSRequestLike,\n  ): Promise<TPageData | undefined> {\n    const useDraftContent =\n      this.isEditorMode(request) && this.draftContentEnabled\n\n    if (useDraftContent) {\n      log.debug({\n        message: 'Bypassing CMS cache in preview mode',\n        slug,\n        locale,\n      })\n      return this.fetchRawPageData(slug, locale, useDraftContent, request)\n    }\n\n    return this.context.cache.getOrSet(\n      `cms:storyblok:page:${slug}:${locale}`,\n      // Cast required: StorageValue excludes undefined, but the fetch can return undefined for missing content\n      () =>\n        this.fetchRawPageData(slug, locale, useDraftContent, request) as never,\n      CACHE_TTL_SECONDS,\n    )\n  }\n\n  /**\n   * Retrieves CMS content for a product listing page, with caching.\n   * Converts a missing entry into `undefined` rather than throwing, since\n   * missing PLP content is expected, not an error condition.\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 editor-specific query params\n   * @returns Storyblok listing page data or undefined\n   */\n  async fetchListingPageData(\n    categoryId: number,\n    locale: string,\n    request: CMSRequestLike,\n  ): Promise<TPageData | undefined> {\n    const slug = `c/c-${categoryId}`\n    const useDraftContent =\n      this.isEditorMode(request) && this.draftContentEnabled\n\n    const fetchListing = async () => {\n      try {\n        return await this.fetchRawPageData(\n          slug,\n          locale,\n          useDraftContent,\n          request,\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 (useDraftContent) {\n      log.debug({\n        message: 'Bypassing CMS PLP cache in preview mode',\n        categoryId,\n        locale,\n      })\n      return fetchListing()\n    }\n\n    return this.context.cache.getOrSet(\n      `cms:storyblok:plp:${categoryId}:${locale}`,\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  /**\n   * Extracts per-locale page paths from a Storyblok story using its\n   * `alternates` and the configured folder mapping.\n   *\n   * @param data CMS page payload containing a Storyblok story.\n   * @returns Per-locale page path map, or undefined.\n   */\n  getAlternatePaths(data: CMSPagePayload): Record<string, string> | undefined {\n    const pageData = data as MinimalStoryblokPageData\n    const story = pageData?.story\n\n    if (!story?.alternates?.length) {\n      return undefined\n    }\n\n    const sourceSlugs = getAllSourceSlugs(story, this.folderMapping)\n\n    if (sourceSlugs.length <= 1) {\n      return undefined\n    }\n\n    return Object.fromEntries(\n      sourceSlugs.map(({ path, slug }) => [\n        path,\n        !slug || slug === HOMEPAGE_SLUG ? '/' : `/${slug}`,\n      ]),\n    )\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@scayle/storefront-cms-storyblok",
+  "version": "0.2.0-alpha.0",
+  "description": "Storyblok 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": {
+    "@storyblok/js": "^6.3.0",
+    "@scayle/storefront": "1.0.0-alpha.2"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@storyblok/js": "^6.3.0",
+    "@types/node": "^24",
+    "@vitest/coverage-v8": "4.1.10",
+    "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"
+  }
+}