@cobrastyle/adapter-storyblok 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cobrastyle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapter.d.ts

@@ -0,0 +1,2 @@
+import type { PartialStorefrontAdapter } from '@cobrastyle/shared-types';
+export declare const storyblokAdapter: PartialStorefrontAdapter;

package/dist/adapter.js

@@ -0,0 +1,25 @@
+import { getConfig } from './config';
+import { fetchStory, mapContext } from './client';
+import { mapStory } from './mappers/story';
+async function getByUrlKey(urlKey) {
+    const version = await getConfig().resolveVersion();
+    const story = await fetchStory(urlKey, version);
+    return story ? mapStory(story, mapContext(version)) : null;
+}
+export const storyblokAdapter = {
+    cms: {
+        // Storyblok identifies pages by slug, so getPage and getPageByUrlKey are the same lookup.
+        getPage: (identifier) => getByUrlKey(identifier),
+        getPageByUrlKey: (urlKey) => getByUrlKey(urlKey),
+        // Implemented for CmsAdapter contract completeness. Storefront routing keeps
+        // resolveUrl on the commerce adapter and falls through via getPageByUrlKey
+        // (see storefront.config.ts), so this is not called by the catch-all route.
+        resolveUrl: async (urlKey) => {
+            const version = await getConfig().resolveVersion();
+            const story = await fetchStory(urlKey, version);
+            return story
+                ? { type: 'CMS_PAGE', id: String(story.id), urlKey }
+                : { type: 'NOT_FOUND', id: '', urlKey };
+        },
+    },
+};

package/dist/blocks/catalog.d.ts

@@ -0,0 +1,11 @@
+export interface BlockDefinition {
+    /** Storyblok component key. */
+    name: string;
+    /** Schema version. */
+    version: string;
+    /** Required field keys (mappers downgrade to `unknown` if missing). */
+    requiredFields: string[];
+    /** Optional field keys. */
+    optionalFields: string[];
+}
+export declare const blockCatalog: BlockDefinition[];

package/dist/blocks/catalog.js

@@ -0,0 +1,9 @@
+export const blockCatalog = [
+    { name: 'hero', version: 'v1', requiredFields: ['headline'], optionalFields: ['subline', 'image', 'cta'] },
+    { name: 'rich_text', version: 'v1', requiredFields: ['body'], optionalFields: [] },
+    { name: 'image', version: 'v1', requiredFields: ['asset'], optionalFields: [] },
+    { name: 'cta_button', version: 'v1', requiredFields: ['label', 'link'], optionalFields: ['variant'] },
+    { name: 'section', version: 'v1', requiredFields: [], optionalFields: ['blocks'] },
+    { name: 'textBlock', version: 'v1', requiredFields: ['text'], optionalFields: ['buttons', 'textAlign'] },
+    { name: 'textColumnBlock', version: 'v1', requiredFields: [], optionalFields: ['title', 'text', 'text2', 'buttons', 'textAlign'] },
+];

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+import { type StoryblokVersion } from './config';
+import type { StoryblokStory } from './types';
+import type { MapContext } from './mappers/blocks';
+/** Render context backed by the SDK's richtext resolver. */
+export declare function mapContext(version: StoryblokVersion): MapContext;
+/** Fetch a single story by slug. Returns null on 404. */
+export declare function fetchStory(slug: string, version: StoryblokVersion): Promise<StoryblokStory | null>;

package/dist/client.js

@@ -0,0 +1,40 @@
+import StoryblokClient from 'storyblok-js-client';
+import { getConfig } from './config';
+let clientForToken = null;
+function getClient(token) {
+    if (clientForToken?.token === token)
+        return clientForToken.client;
+    const cfg = getConfig();
+    const client = new StoryblokClient({ accessToken: token, region: cfg.region });
+    clientForToken = { token, client };
+    return client;
+}
+function tokenFor(version) {
+    const cfg = getConfig();
+    return version === 'draft' ? cfg.previewToken : cfg.publicToken;
+}
+/** Render context backed by the SDK's richtext resolver. */
+export function mapContext(version) {
+    const client = getClient(tokenFor(version));
+    return {
+        renderRichText: (doc) => doc ? client.richTextResolver.render(doc) : '',
+    };
+}
+/** Fetch a single story by slug. Returns null on 404. */
+export async function fetchStory(slug, version) {
+    const client = getClient(tokenFor(version));
+    try {
+        const res = await client.get(`cdn/stories/${slug}`, { version });
+        return res.data.story;
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return null;
+        throw err;
+    }
+}
+function isNotFound(err) {
+    const status = err?.status ??
+        err?.response?.status;
+    return status === 404;
+}

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export type StoryblokVersion = 'draft' | 'published';
+export interface StoryblokConfig {
+    /** Public token — published content. */
+    publicToken: string;
+    /** Preview token — draft content. Server-only. */
+    previewToken: string;
+    /** Shared secret used to validate the publish webhook. Optional for read-only usage. */
+    webhookSecret?: string;
+    /** Storyblok space region. Defaults to 'eu'. */
+    region?: 'eu' | 'us' | 'ap' | 'ca' | 'cn';
+    /** Fallback version when no versionGetter is supplied. Defaults to 'published'. */
+    defaultVersion?: StoryblokVersion;
+    /**
+     * Per-request version resolver supplied by the app (reads Next.js draftMode).
+     * Kept here so the framework-agnostic package never imports next/headers.
+     */
+    versionGetter?: () => Promise<StoryblokVersion>;
+}
+interface ResolvedConfig extends StoryblokConfig {
+    resolveVersion: () => Promise<StoryblokVersion>;
+}
+export declare function setConfig(newConfig: StoryblokConfig): void;
+export declare function getConfig(): ResolvedConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,19 @@
+let config = null;
+export function setConfig(newConfig) {
+    if (!newConfig) {
+        config = null;
+        return;
+    }
+    config = {
+        ...newConfig,
+        resolveVersion: async () => newConfig.versionGetter
+            ? newConfig.versionGetter()
+            : (newConfig.defaultVersion ?? 'published'),
+    };
+}
+export function getConfig() {
+    if (!config) {
+        throw new Error('Storyblok adapter not configured. Call setConfig() with publicToken and previewToken.');
+    }
+    return config;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { storyblokAdapter } from './adapter';
+export { setConfig, getConfig } from './config';
+export type { StoryblokConfig, StoryblokVersion } from './config';
+export { blockCatalog, type BlockDefinition } from './blocks/catalog';
+export { inertStoryblokAdapter } from './inert';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { storyblokAdapter } from './adapter';
+export { setConfig, getConfig } from './config';
+export { blockCatalog } from './blocks/catalog';
+export { inertStoryblokAdapter } from './inert';

package/dist/inert.d.ts

@@ -0,0 +1,7 @@
+import type { PartialStorefrontAdapter } from '@cobrastyle/shared-types';
+/**
+ * Inert CMS adapter used when Storyblok is not configured. Never throws — every
+ * lookup resolves to "nothing here", so the storefront keeps working and Storyblok
+ * CMS simply stays inactive until tokens are provided.
+ */
+export declare const inertStoryblokAdapter: PartialStorefrontAdapter;

package/dist/inert.js

@@ -0,0 +1,16 @@
+/**
+ * Inert CMS adapter used when Storyblok is not configured. Never throws — every
+ * lookup resolves to "nothing here", so the storefront keeps working and Storyblok
+ * CMS simply stays inactive until tokens are provided.
+ */
+export const inertStoryblokAdapter = {
+    cms: {
+        getPage: async () => null,
+        getPageByUrlKey: async () => null,
+        resolveUrl: async (urlKey) => ({
+            type: 'NOT_FOUND',
+            id: '',
+            urlKey,
+        }),
+    },
+};

package/dist/mappers/blocks.d.ts

@@ -0,0 +1,8 @@
+import type { CmsBlockNode } from '@cobrastyle/shared-types';
+import type { StoryblokBlok } from '../types';
+export interface MapContext {
+    /** Renders a Storyblok richtext document to HTML. NOTE: output is trusted-editor HTML and is NOT sanitized — it is rendered via dangerouslySetInnerHTML downstream. */
+    renderRichText: (doc: unknown) => string;
+}
+export declare function mapBlok(blok: StoryblokBlok, ctx: MapContext): CmsBlockNode;
+export declare function mapBloks(bloks: StoryblokBlok[] | undefined, ctx: MapContext): CmsBlockNode[];

package/dist/mappers/blocks.js

@@ -0,0 +1,151 @@
+function str(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function asset(v) {
+    const a = v;
+    if (!a || !a.filename)
+        return undefined;
+    return { src: a.filename, alt: a.alt ?? '' };
+}
+function href(v) {
+    const link = v;
+    if (!link)
+        return undefined;
+    if (link.url)
+        return link.url;
+    if (link.cached_url) {
+        // story links arrive as a slug; make them root-relative.
+        return link.cached_url.startsWith('http') ? link.cached_url : `/${link.cached_url}`;
+    }
+    return undefined;
+}
+function firstBlok(v) {
+    return Array.isArray(v) ? v[0] : undefined;
+}
+function unknown(blok) {
+    const b = (blok && typeof blok === 'object' ? blok : {});
+    return {
+        _type: 'unknown',
+        id: typeof b._uid === 'string' ? b._uid : '',
+        component: typeof b.component === 'string' ? b.component : 'unknown',
+        raw: blok,
+    };
+}
+function mapCta(blok) {
+    const label = str(blok.label);
+    const linkHref = href(blok.link);
+    if (!label || !linkHref)
+        return unknown(blok);
+    const variant = blok.variant === 'secondary' ? 'secondary' : 'primary';
+    return { _type: 'cta_button', id: blok._uid, label, href: linkHref, variant };
+}
+function mapHero(blok, ctx) {
+    const headline = str(blok.headline);
+    if (!headline)
+        return unknown(blok);
+    const node = { _type: 'hero', id: blok._uid, headline };
+    const subline = str(blok.subline);
+    if (subline)
+        node.subline = subline;
+    const image = asset(blok.image);
+    if (image)
+        node.image = image;
+    const ctaBlok = firstBlok(blok.cta);
+    if (ctaBlok) {
+        const cta = mapCta(ctaBlok);
+        if (cta._type === 'cta_button')
+            node.cta = cta;
+    }
+    return node;
+}
+function mapRichText(blok, ctx) {
+    return { _type: 'rich_text', id: blok._uid, html: ctx.renderRichText(blok.body) };
+}
+function mapImage(blok) {
+    const img = asset(blok.asset);
+    if (!img)
+        return unknown(blok);
+    return { _type: 'image', id: blok._uid, src: img.src, alt: img.alt };
+}
+function mapSection(blok, ctx) {
+    const raw = Array.isArray(blok.blocks) ? blok.blocks : [];
+    return { _type: 'section', id: blok._uid, children: raw.map((b) => mapBlok(b, ctx)) };
+}
+function mapAlign(v) {
+    return v === 'left' || v === 'center' || v === 'right' ? v : undefined;
+}
+function mapButtons(v, _ctx) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const entry of v) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const b = entry;
+        const label = str(b.label) ?? str(b.text) ?? str(b.title);
+        const linkHref = href(b.link) ?? href(b.url);
+        if (label && linkHref) {
+            out.push({
+                _type: 'cta_button',
+                id: typeof b._uid === 'string' ? b._uid : '',
+                label,
+                href: linkHref,
+                variant: b.variant === 'secondary' ? 'secondary' : 'primary',
+            });
+        }
+    }
+    return out;
+}
+function mapText(blok, ctx) {
+    const node = {
+        _type: 'text',
+        id: blok._uid,
+        html: ctx.renderRichText(blok.text),
+        buttons: mapButtons(blok.buttons, ctx),
+    };
+    const align = mapAlign(blok.textAlign);
+    if (align)
+        node.align = align;
+    return node;
+}
+function mapTextColumn(blok, ctx) {
+    const node = {
+        _type: 'text_column',
+        id: blok._uid,
+        htmlLeft: ctx.renderRichText(blok.text),
+        htmlRight: ctx.renderRichText(blok.text2),
+        buttons: mapButtons(blok.buttons, ctx),
+    };
+    const titleHtml = ctx.renderRichText(blok.title);
+    if (titleHtml)
+        node.titleHtml = titleHtml;
+    const align = mapAlign(blok.textAlign);
+    if (align)
+        node.align = align;
+    return node;
+}
+export function mapBlok(blok, ctx) {
+    if (!blok || typeof blok !== 'object')
+        return unknown(blok);
+    switch (blok.component) {
+        case 'hero':
+            return mapHero(blok, ctx);
+        case 'rich_text':
+            return mapRichText(blok, ctx);
+        case 'image':
+            return mapImage(blok);
+        case 'cta_button':
+            return mapCta(blok);
+        case 'section':
+            return mapSection(blok, ctx);
+        case 'textBlock':
+            return mapText(blok, ctx);
+        case 'textColumnBlock':
+            return mapTextColumn(blok, ctx);
+        default:
+            return unknown(blok);
+    }
+}
+export function mapBloks(bloks, ctx) {
+    return (bloks ?? []).map((b) => mapBlok(b, ctx));
+}

package/dist/mappers/story.d.ts

@@ -0,0 +1,4 @@
+import type { CmsPage } from '@cobrastyle/shared-types';
+import type { StoryblokStory } from '../types';
+import { type MapContext } from './blocks';
+export declare function mapStory(story: StoryblokStory, ctx: MapContext): CmsPage;

package/dist/mappers/story.js

@@ -0,0 +1,14 @@
+import { mapBloks } from './blocks';
+export function mapStory(story, ctx) {
+    const content = story.content;
+    return {
+        id: String(story.id),
+        identifier: story.full_slug,
+        title: story.name,
+        content: '', // block-based; HTML field intentionally empty
+        metaTitle: content.meta_title || undefined,
+        metaDescription: content.meta_description || undefined,
+        urlKey: story.full_slug,
+        blocks: mapBloks(content.body, ctx),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/** A Storyblok content block ("blok"). Fields vary by component. */
+export interface StoryblokBlok {
+    _uid: string;
+    component: string;
+    [field: string]: unknown;
+}
+/** Storyblok asset field. */
+export interface StoryblokAsset {
+    filename: string | null;
+    alt?: string | null;
+    title?: string | null;
+}
+/** Storyblok multilink field. */
+export interface StoryblokLink {
+    url?: string;
+    cached_url?: string;
+    linktype?: 'url' | 'story' | 'asset' | 'email';
+}
+/** The body of a Storyblok story for a CMS page. */
+export interface StoryblokPageContent {
+    _uid: string;
+    component: string;
+    body?: StoryblokBlok[];
+    meta_title?: string;
+    meta_description?: string;
+}
+export interface StoryblokStory {
+    id: number;
+    uuid: string;
+    name: string;
+    slug: string;
+    full_slug: string;
+    content: StoryblokPageContent;
+}
+export interface StoryblokStoryResponse {
+    story: StoryblokStory;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@cobrastyle/adapter-storyblok",
+  "version": "1.0.1",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "storyblok-js-client": "^6.10.4",
+    "@cobrastyle/shared-types": "1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eComero/cobrastyle-express-next.git",
+    "directory": "packages/adapters/storyblok"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "type-check": "tsc --noEmit"
+  }
+}