@cobrastyle/adapter-storyblok 1.0.3 → 2.0.0

package/dist/client.d.ts

@@ -1,7 +1,72 @@
+import StoryblokClient from 'storyblok-js-client';
+import type { ISbCustomFetch, ISbStoriesParams } from 'storyblok-js-client';
 import { type StoryblokVersion } from './config';
-import type { StoryblokStory } from './types';
+import type { FetchStoriesParams, ResolveParams, StoryblokStoriesResult, StoryblokStory } from './types';
 import type { MapContext } from './mappers/blocks';
+/**
+ * Storyblok caps `by_uuids` at 100 ids per request. Beyond that the query
+ * string overflows and the CDN errors, so lists longer than this are split
+ * across requests and merged. Consumers should not have to know this.
+ */
+export declare const UUID_CHUNK_SIZE = 100;
+/** Drop memoised clients. Needed when the config changes (tokens, region). */
+export declare function resetClients(): void;
+/** The version this request should read, unless the caller pins one. */
+export declare function resolveVersion(version?: StoryblokVersion): Promise<StoryblokVersion>;
+/**
+ * The configured client for a version — correct token, region and richtext
+ * resolver. Exported so consumers that render their own components never have
+ * to construct a client (and re-derive token selection) themselves.
+ */
+export declare function getStoryblokClient(version?: StoryblokVersion): Promise<StoryblokClient>;
 /** 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>;
+/**
+ * Cache policy, in one place.
+ *
+ * Draft must never be cached — the Visual Editor would show stale content and
+ * the editor would think their change was lost. Published content is cached for
+ * `revalidate` seconds (from config, or per call).
+ */
+export declare function fetchOptionsFor(version: StoryblokVersion, revalidate?: number): ISbCustomFetch;
+export interface FetchOptions {
+    /** Pin the version instead of resolving it from config. */
+    version?: StoryblokVersion;
+    /** Cache lifetime in seconds. Published only — draft is always uncached. */
+    revalidate?: number;
+}
+export interface FetchStoryOptions extends FetchOptions {
+    /** Relation/link expansion for this story. */
+    params?: ResolveParams;
+}
+/**
+ * Fetch a single story by slug. Returns null on 404.
+ *
+ * Pass `params.resolve_relations` to have Storyblok substitute referenced
+ * stories rather than returning bare uuids — the alternative is batch-fetching
+ * them yourself afterwards.
+ */
+export declare function fetchStory(slug: string, version?: StoryblokVersion, opts?: FetchStoryOptions): Promise<StoryblokStory | null>;
+/** Translate the public params into the SDK's wire shape. */
+export declare function toStoriesParams(params: FetchStoriesParams, version: StoryblokVersion): ISbStoriesParams;
+/** Translate single-story params into the SDK's wire shape. */
+export declare function toStoryParams(params: ResolveParams, version: StoryblokVersion): Record<string, unknown>;
+/**
+ * Query the Content Delivery API for a list of stories.
+ *
+ * Returns raw stories — mapping into `CmsPage`/`CmsBlockNode` is opt-in via
+ * `mapStory`, so consumers rendering their own components keep the full blok
+ * tree (and `_editable`, which the Visual Editor needs).
+ *
+ * `by_uuids` / `by_uuids_ordered` longer than 100 are split and merged
+ * transparently; `by_uuids_ordered` keeps the caller's order across chunks.
+ */
+export declare function fetchStories(params?: FetchStoriesParams, opts?: FetchOptions): Promise<StoryblokStoriesResult>;
+/**
+ * Every story matching the query, paging until the CDN is exhausted.
+ *
+ * `fetchStories` returns one page — fine for a capped list, wrong for "all
+ * recipes" once a space grows past `per_page`. Uuid queries are already
+ * complete (they chunk rather than page), so those short-circuit.
+ */
+export declare function fetchAllStories(params?: FetchStoriesParams, opts?: FetchOptions): Promise<StoryblokStoriesResult>;

package/dist/client.js

@@ -1,30 +1,82 @@
 import StoryblokClient from 'storyblok-js-client';
 import { getConfig } from './config';
-let clientForToken = null;
-function getClient(token) {
-    if (clientForToken?.token === token)
-        return clientForToken.client;
+/**
+ * Storyblok caps `by_uuids` at 100 ids per request. Beyond that the query
+ * string overflows and the CDN errors, so lists longer than this are split
+ * across requests and merged. Consumers should not have to know this.
+ */
+export const UUID_CHUNK_SIZE = 100;
+/**
+ * One client per token. Draft and published use different tokens, so a
+ * single-slot cache would rebuild the client on every alternation — which a
+ * page rendering both preview and published content does constantly.
+ */
+const clients = new Map();
+function clientFor(token) {
     const cfg = getConfig();
+    // Keyed on everything the client is constructed from, so re-configuring with
+    // a different token or region cannot hand back a stale client.
+    const key = `${token}|${cfg.region ?? 'eu'}`;
+    const cached = clients.get(key);
+    if (cached)
+        return cached;
     const client = new StoryblokClient({ accessToken: token, region: cfg.region });
-    clientForToken = { token, client };
+    clients.set(key, client);
     return client;
 }
+/** Drop memoised clients. Needed when the config changes (tokens, region). */
+export function resetClients() {
+    clients.clear();
+}
 function tokenFor(version) {
     const cfg = getConfig();
     return version === 'draft' ? cfg.previewToken : cfg.publicToken;
 }
+/** The version this request should read, unless the caller pins one. */
+export async function resolveVersion(version) {
+    return version ?? getConfig().resolveVersion();
+}
+/**
+ * The configured client for a version — correct token, region and richtext
+ * resolver. Exported so consumers that render their own components never have
+ * to construct a client (and re-derive token selection) themselves.
+ */
+export async function getStoryblokClient(version) {
+    return clientFor(tokenFor(await resolveVersion(version)));
+}
 /** Render context backed by the SDK's richtext resolver. */
 export function mapContext(version) {
-    const client = getClient(tokenFor(version));
+    const client = clientFor(tokenFor(version));
     return {
-        renderRichText: (doc) => doc ? client.richTextResolver.render(doc) : '',
+        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));
+/**
+ * Cache policy, in one place.
+ *
+ * Draft must never be cached — the Visual Editor would show stale content and
+ * the editor would think their change was lost. Published content is cached for
+ * `revalidate` seconds (from config, or per call).
+ */
+export function fetchOptionsFor(version, revalidate) {
+    if (version === 'draft')
+        return { cache: 'no-store' };
+    const seconds = revalidate ?? getConfig().revalidate;
+    // `next` is Next.js's RequestInit extension; harmless on other runtimes.
+    return seconds != null ? { next: { revalidate: seconds } } : {};
+}
+/**
+ * Fetch a single story by slug. Returns null on 404.
+ *
+ * Pass `params.resolve_relations` to have Storyblok substitute referenced
+ * stories rather than returning bare uuids — the alternative is batch-fetching
+ * them yourself afterwards.
+ */
+export async function fetchStory(slug, version, opts = {}) {
+    const v = await resolveVersion(version ?? opts.version);
+    const client = clientFor(tokenFor(v));
     try {
-        const res = await client.get(`cdn/stories/${slug}`, { version });
+        const res = await client.get(`cdn/stories/${slug}`, toStoryParams(opts.params ?? {}, v), fetchOptionsFor(v, opts.revalidate));
         return res.data.story;
     }
     catch (err) {
@@ -33,6 +85,124 @@ export async function fetchStory(slug, version) {
         throw err;
     }
 }
+/** Relation/link expansion, shared by single-story and list fetches. */
+function applyResolveParams(out, params) {
+    // The SDK accepts a comma-joined string or an array; join so the query string
+    // is identical either way and easier to assert on.
+    if (params.resolve_relations?.length)
+        out.resolve_relations = params.resolve_relations.join(',');
+    if (params.resolve_links)
+        out.resolve_links = params.resolve_links;
+    if (params.resolve_links_level)
+        out.resolve_links_level = params.resolve_links_level;
+    if (params.language)
+        out.language = params.language;
+    if (params.fallback_lang)
+        out.fallback_lang = params.fallback_lang;
+}
+/** Translate the public params into the SDK's wire shape. */
+export function toStoriesParams(params, version) {
+    const out = { version };
+    if (params.content_type)
+        out.content_type = params.content_type;
+    if (params.starts_with)
+        out.starts_with = params.starts_with;
+    if (params.by_uuids?.length)
+        out.by_uuids = params.by_uuids.join(',');
+    if (params.by_uuids_ordered?.length)
+        out.by_uuids_ordered = params.by_uuids_ordered.join(',');
+    if (params.filter_query)
+        out.filter_query = params.filter_query;
+    if (params.sort_by)
+        out.sort_by = params.sort_by;
+    if (params.search_term)
+        out.search_term = params.search_term;
+    if (params.excluding_slugs)
+        out.excluding_slugs = params.excluding_slugs;
+    if (params.per_page != null)
+        out.per_page = params.per_page;
+    if (params.page != null)
+        out.page = params.page;
+    applyResolveParams(out, params);
+    return out;
+}
+/** Translate single-story params into the SDK's wire shape. */
+export function toStoryParams(params, version) {
+    const out = { version };
+    applyResolveParams(out, params);
+    return out;
+}
+function chunk(xs, size) {
+    const out = [];
+    for (let i = 0; i < xs.length; i += size)
+        out.push(xs.slice(i, i + size));
+    return out;
+}
+/** Restore the caller's order; ids with no story (deleted, unpublished) drop out. */
+function orderByUuids(stories, uuids) {
+    const byUuid = new Map(stories.map((s) => [s.uuid, s]));
+    return uuids.map((id) => byUuid.get(id)).filter((s) => Boolean(s));
+}
+async function fetchStoriesPage(params, version, revalidate) {
+    const client = clientFor(tokenFor(version));
+    const res = await client.get('cdn/stories', params, fetchOptionsFor(version, revalidate));
+    return {
+        stories: (res.data.stories ?? []),
+        total: res.total ?? 0,
+    };
+}
+/**
+ * Query the Content Delivery API for a list of stories.
+ *
+ * Returns raw stories — mapping into `CmsPage`/`CmsBlockNode` is opt-in via
+ * `mapStory`, so consumers rendering their own components keep the full blok
+ * tree (and `_editable`, which the Visual Editor needs).
+ *
+ * `by_uuids` / `by_uuids_ordered` longer than 100 are split and merged
+ * transparently; `by_uuids_ordered` keeps the caller's order across chunks.
+ */
+export async function fetchStories(params = {}, opts = {}) {
+    const version = await resolveVersion(opts.version);
+    const ordered = params.by_uuids_ordered;
+    const ids = ordered ?? params.by_uuids;
+    if (!ids?.length || ids.length <= UUID_CHUNK_SIZE) {
+        return fetchStoriesPage(toStoriesParams(params, version), version, opts.revalidate);
+    }
+    const key = ordered ? 'by_uuids_ordered' : 'by_uuids';
+    const pages = await Promise.all(chunk(ids, UUID_CHUNK_SIZE).map((slice) => fetchStoriesPage(toStoriesParams({ ...params, [key]: slice }, version), version, opts.revalidate)));
+    const stories = pages.flatMap((p) => p.stories);
+    return {
+        stories: ordered ? orderByUuids(stories, ordered) : stories,
+        total: stories.length,
+    };
+}
+/** Storyblok's hard cap on a single page. */
+const MAX_PER_PAGE = 100;
+/**
+ * Every story matching the query, paging until the CDN is exhausted.
+ *
+ * `fetchStories` returns one page — fine for a capped list, wrong for "all
+ * recipes" once a space grows past `per_page`. Uuid queries are already
+ * complete (they chunk rather than page), so those short-circuit.
+ */
+export async function fetchAllStories(params = {}, opts = {}) {
+    if (params.by_uuids?.length || params.by_uuids_ordered?.length) {
+        return fetchStories(params, opts);
+    }
+    const perPage = Math.min(params.per_page ?? MAX_PER_PAGE, MAX_PER_PAGE);
+    const stories = [];
+    let total = 0;
+    for (let page = params.page ?? 1;; page += 1) {
+        const res = await fetchStories({ ...params, per_page: perPage, page }, opts);
+        stories.push(...res.stories);
+        total = res.total;
+        // Stop on a short page rather than trusting `total` alone — a story
+        // unpublished mid-walk would otherwise loop forever.
+        if (res.stories.length < perPage || stories.length >= total)
+            break;
+    }
+    return { stories, total: total || stories.length };
+}
 function isNotFound(err) {
     const status = err?.status ??
         err?.response?.status;

package/dist/config.d.ts

@@ -10,6 +10,11 @@ export interface StoryblokConfig {
     region?: 'eu' | 'us' | 'ap' | 'ca' | 'cn';
     /** Fallback version when no versionGetter is supplied. Defaults to 'published'. */
     defaultVersion?: StoryblokVersion;
+    /**
+     * Cache lifetime in seconds for PUBLISHED reads. Draft is never cached.
+     * Omit to leave caching to the framework's default.
+     */
+    revalidate?: number;
     /**
      * Per-request version resolver supplied by the app (reads Next.js draftMode).
      * Kept here so the framework-agnostic package never imports next/headers.

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 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';
+export { getStoryblokClient, resolveVersion, fetchStory, fetchStories, fetchAllStories, mapContext, fetchOptionsFor, toStoriesParams, toStoryParams, UUID_CHUNK_SIZE, resetClients, type FetchOptions, type FetchStoryOptions, } from './client';
+export type { FetchStoriesParams, ResolveParams, StoryblokAsset, StoryblokBlok, StoryblokLink, StoryblokPageContent, StoryblokStoriesResult, StoryblokStory, } from './types';
+export { mapStory } from './mappers/story';

package/dist/index.js

@@ -1,4 +1,12 @@
 export { storyblokAdapter } from './adapter';
 export { setConfig, getConfig } from './config';
-export { blockCatalog } from './blocks/catalog';
 export { inertStoryblokAdapter } from './inert';
+// ── Transport ─────────────────────────────────────────────────────────────
+// The configured client and the raw fetches, for consumers that render their
+// own components. Do NOT build your own StoryblokClient — token-per-version,
+// region and cache policy live here.
+export { getStoryblokClient, resolveVersion, fetchStory, fetchStories, fetchAllStories, mapContext, fetchOptionsFor, toStoriesParams, toStoryParams, UUID_CHUNK_SIZE, resetClients, } from './client';
+// ── Normalisation (opt-in) ────────────────────────────────────────────────
+// Map a raw story into cobrastyle's CmsPage/CmsBlockNode. Only needed by
+// consumers using the shared block components.
+export { mapStory } from './mappers/story';

package/dist/types.d.ts

@@ -35,3 +35,49 @@ export interface StoryblokStory {
 export interface StoryblokStoryResponse {
     story: StoryblokStory;
 }
+export interface StoryblokStoriesResponse {
+    stories: StoryblokStory[];
+}
+/** A page of stories plus the total the CDN reports. */
+export interface StoryblokStoriesResult {
+    stories: StoryblokStory[];
+    total: number;
+}
+/**
+ * Relation and link expansion, shared by single-story and list fetches.
+ *
+ * `resolve_relations` is how you avoid hand-rolling a relation resolver:
+ * Storyblok substitutes the referenced stories into the response instead of
+ * leaving bare uuids, so a consumer does not have to batch-fetch them itself.
+ */
+export interface ResolveParams {
+    /** Dot paths to expand, e.g. ['recipe.ingredients', 'page.author']. */
+    resolve_relations?: string[];
+    /** How story links in multilink/richtext fields are expanded. */
+    resolve_links?: 'url' | 'story' | 'link';
+    /** Depth for `resolve_links`. */
+    resolve_links_level?: 1 | 2;
+    /** Space language, for translated content. */
+    language?: string;
+    /** Fallback language when a translation is missing. */
+    fallback_lang?: string;
+}
+/**
+ * The Content Delivery query surface, in the shapes a consumer thinks in —
+ * uuid lists are arrays here and joined internally, and chunked past 100.
+ */
+export interface FetchStoriesParams extends ResolveParams {
+    content_type?: string;
+    starts_with?: string;
+    by_uuids?: string[];
+    /** Same as `by_uuids`, but the response keeps this order. */
+    by_uuids_ordered?: string[];
+    /** e.g. `{ tags: { in_array: 'vegan' } }` */
+    filter_query?: Record<string, unknown>;
+    sort_by?: string;
+    search_term?: string;
+    excluding_slugs?: string;
+    /** Storyblok caps this at 100. */
+    per_page?: number;
+    page?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cobrastyle/adapter-storyblok",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {