feat(capi-client): add typed Content Delivery API client package by maoberlehner · Pull Request #428 · storyblok/monoblok

maoberlehner · 2026-02-06T14:21:17Z

Introduce a new @storyblok/api-client package that provides a modern, typed TS client for the Content Delivery (CAPI) stories endpoints, generated from our OpenAPI spec. This improves DX and consistency when consuming the Stories API.

Add OpenAPI CAPI stories spec and shared schemas for story field types
Generate typed CAPI client (fetch-based) and SDK with get and getAll helpers
Implement createApiClient wrapper with region-aware base URL and access token handling
Add basic tests using MSW + OpenAPI mocks to validate stories.get and stories.getAll
Configure build (tsdown), linting, testing, and npm packaging for the new package

Fixes WDX-281

packages/capi-client/src/index.ts

Copilot

Pull request overview

Adds a new typed @storyblok/api-client package generated from an OpenAPI spec for the CAPI Stories endpoints, plus shared story schemas and supporting build/test tooling.

Changes:

Added/expanded OpenAPI spec files for CAPI Stories + shared story/object field type schemas.
Introduced a generated, fetch-based TypeScript client wrapper with stories.get / stories.getAll.
Added package tooling (tsdown, eslint, vitest) and basic MSW/OpenAPI-driven tests.

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
packages/openapi/resources/shared/stories/story-translated-slug.yaml	Adds shared schema for translated slugs in story objects.
packages/openapi/resources/shared/stories/story-localized-path.yaml	Adds shared schema for localized paths in story objects.
packages/openapi/resources/shared/stories/story-content.yaml	Defines output schema for `story.content` and supported field types.
packages/openapi/resources/shared/stories/story-content-input.yaml	Defines input schema for `story.content` (create/update).
packages/openapi/resources/shared/stories/story-base.yaml	Adds common story fields used across APIs.
packages/openapi/resources/shared/stories/story-alternate.yaml	Adds minimal schema for alternate stories.
packages/openapi/resources/shared/stories/field-types/table-field.yaml	Adds schema for Storyblok table field output.
packages/openapi/resources/shared/stories/field-types/table-field-input.yaml	Adds schema for Storyblok table field input.
packages/openapi/resources/shared/stories/field-types/richtext-field.yaml	Adds schema for Storyblok richtext field output.
packages/openapi/resources/shared/stories/field-types/richtext-field-input.yaml	Adds schema for Storyblok richtext field input.
packages/openapi/resources/shared/stories/field-types/plugin-field.yaml	Adds schema for plugin/custom fields output.
packages/openapi/resources/shared/stories/field-types/plugin-field-input.yaml	Adds schema for plugin/custom fields input.
packages/openapi/resources/shared/stories/field-types/multilink-field.yaml	Adds multilink field output schema.
packages/openapi/resources/shared/stories/field-types/multilink-field-input.yaml	Adds multilink field input schema.
packages/openapi/resources/shared/stories/field-types/asset-field.yaml	Adds asset field output schema.
packages/openapi/resources/shared/stories/field-types/asset-field-input.yaml	Adds asset field input schema.
packages/openapi/resources/shared/responses.yaml	Introduces shared error response schemas.
packages/openapi/resources/shared/parameters.yaml	Introduces shared path parameter definitions.
packages/openapi/resources/shared/pagination.yaml	Introduces shared pagination param/header definitions.
packages/openapi/resources/capi/stories/main.yaml	Adds OpenAPI spec for CAPI stories endpoints.
packages/openapi/resources/capi/shared/stories/story-capi.yaml	Defines CAPI-specific story schema that composes story-base.
packages/openapi/resources/capi/shared/servers.yaml	Adds region-specific server base URLs.
packages/openapi/resources/capi/shared/security.yaml	Adds security requirement definition for CAPI spec.
packages/openapi/resources/capi/shared/security-schemes.yaml	Adds security scheme for `token` query auth.
packages/openapi/redocly.yaml	Registers the new CAPI Stories OpenAPI build output.
packages/capi-client/vitest.config.ts	Configures Vitest for the new client package.
packages/capi-client/tsdown.config.ts	Configures tsdown build for ESM/CJS + d.ts.
packages/capi-client/tsconfig.json	Adds strict TS config for the new package.
packages/capi-client/src/index.ts	Implements `createApiClient` wrapper around generated client/sdk.
packages/capi-client/src/index.test.ts	Adds MSW/OpenAPI-based tests for `stories.get` and `stories.getAll`.
packages/capi-client/package.json	Defines package metadata, scripts, deps, and Nx targets.
packages/capi-client/openapi-ts.config.ts	Configures `@hey-api/openapi-ts` generation from bundled spec.
packages/capi-client/eslint.config.js	Adds package-local ESLint configuration + ignores.
packages/capi-client/README.md	Documents installation, usage, configuration, and support.
packages/capi-client/.npmignore	Restricts published files to `dist/`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/openapi/resources/shared/responses.yaml

packages/openapi/resources/shared/parameters.yaml

packages/openapi/resources/shared/stories/story-content.yaml

packages/openapi/resources/shared/stories/story-content-input.yaml

packages/capi-client/src/index.ts

packages/capi-client/README.md

packages/capi-client/package.json

maoberlehner · 2026-02-24T08:39:22Z

.github/workflows/pkg.pr.new.yml

      - run: |
          PATHS=$(pnpm list --recursive --depth=0 --json | jq -r '.[] | select(.private == false) | .path' | tr '\n' ' ')
-          pnpx pkg-pr-new publish $PATHS --compact --pnpm
+          pnpx pkg-pr-new publish $PATHS --pnpm


This led to CI failing because the package does not exist (yet) on npm. We might revert this when we've created the package on npm.

@maoberlehner actually, during the work on richtext PR I realized it might not be necessary

pkg-pr-new · 2026-02-24T08:40:28Z

Open in StackBlitz

@storyblok/astro

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/astro@428

@storyblok/api-client

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/api-client@428

storyblok

npm i https://pkg.pr.new/storyblok/monoblok/storyblok@428

@storyblok/eslint-config

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/eslint-config@428

@storyblok/js

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/js@428

storyblok-js-client

npm i https://pkg.pr.new/storyblok/monoblok/storyblok-js-client@428

@storyblok/management-api-client

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/management-api-client@428

@storyblok/nuxt

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/nuxt@428

@storyblok/react

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/react@428

@storyblok/region-helper

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/region-helper@428

@storyblok/richtext

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/richtext@428

@storyblok/svelte

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/svelte@428

@storyblok/vue

npm i https://pkg.pr.new/storyblok/monoblok/@storyblok/vue@428

commit: ce5eab3

packages/capi-client/package.json

packages/capi-client/README.md

packages/capi-client/src/index.ts

cursor · 2026-02-24T11:21:11Z

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on March 1.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

dipankarmaikap · 2026-02-26T13:05:59Z

@maoberlehner I left a few small comments, but otherwise this looks good to be merged. Great work!

Introduce a new `@storyblok/api-client` package that provides a modern, typed TS client for the Content Delivery (CAPI) stories endpoints, generated from our OpenAPI spec. This improves DX and consistency when consuming the Stories API. - Add OpenAPI CAPI stories spec and shared schemas for story field types - Generate typed CAPI client (fetch-based) and SDK with `get` and `getAll` helpers - Implement `createApiClient` wrapper with region-aware base URL and access token handling - Add basic tests using MSW + OpenAPI mocks to validate `stories.get` and `stories.getAll` - Configure build (tsdown), linting, testing, and npm packaging for the new package Fixes WDX-281

Switch to the ky-based client plugin and configure automatic retries (including 429s) with backoff to make the CAPI client more resilient to transient failures. Extend tests to cover retry behavior and error handling with and without `throwOnError`, and ignore generated sources in git.

The API accepts both numeric IDs and string identifiers; update the OpenAPI schema so clients generate correct types and validation matches actual behavior

Use fileURLToPath with import.meta.url instead of __dirname so tests can resolve the OpenAPI spec path correctly in an ES module environment

Align GitHub branding across package READMEs to improve documentation consistency and professionalism

Fix typo and standardize "GitHub repo" phrasing to improve clarity for users creating minimal reproducible examples when they can't share company code

Use local CONTRIBUTING.md and correct package naming so contributors see repo-specific guidelines instead of central .github docs

Align CAPI client and OpenAPI spec with personal access token security by moving authentication from query parameters to the client auth configuration, avoiding token leakage in URLs and keeping docs consistent.

… input model

- Remove unused input type schemas that were never referenced by MAPI or CAPI - Delete story-content-input and all field-type-input variants (231 lines) - Remove duplicate components.yaml (BearerAuth already in security-schemes) - Fix China region server URL (storyblok.cn → storyblokchina.cn) - Normalize indentation in shared responses.yaml

Ensure story schema required fields and properties reflect actual Storyblok responses and metadata, and document pagination headers on the stories list endpoint to keep API docs accurate and complete

Introduce reusable cache strategy handlers (cache-first, network-first, swr) so cache behavior is explicit, easier to reason about, and override. Simplify SWR semantics to always return cached data when present and revalidate in the background with per-key deduplication, and improve in-memory cache defaults (implicit storedAt, documented eviction).

Add optional relation inlining for stories.get and stories.getAll. Also fetch missing rel_uuids automatically and resolve relation cycles safely.

Remove --compact from preview publishing so CI does not require packages to be pre-published on npm.

Align tests and utilities with the new stories client generation path after directory restructuring.

The documented behavior for handling relation UUIDs no longer matches the current client implementation, so removing it prevents misleading usage assumptions and keeps the README accurate.

Prepare @storyblok/api-client for a 0.1.0 release so it can be published and consumed as a publicly usable package

…ction

…ly client

alexjoverm

@maoberlehner this is a solid improvement over current one. Well structured, with cache strategies, and the full jitter you already established in the mapi client, just to highlight a few niceties.

There are a few things that require further thought and polishing, mostly around the cv, cache and concurrency areas.

alexjoverm · 2026-02-27T09:51:52Z

packages/capi-client/src/utils/fetch-rel-uuids.ts

+const UUID_CHUNK_SIZE = 50;
+const MAX_CONCURRENT_REQUESTS = 50;


suggestion(non-blocking): shall we have these in a separate constants file?

alexjoverm · 2026-02-27T10:25:57Z

packages/capi-client/src/index.ts

+    rawQuery: Record<string, unknown>,
+    fetchFn: (query: Record<string, unknown>) => Promise<ApiResponse<TData>>,
+  ): Promise<ApiResponse<TData>> => {
+    const query = currentCv ? applyCvToQuery(rawQuery, currentCv) : rawQuery;


(blocking): heads up here - cv can be 0 (actually, it's a common pattern to bypass CDN cache so this would fail in that case. Better currentCV !== undefined

alexjoverm · 2026-02-27T10:44:45Z

packages/capi-client/src/index.ts

+  throwOnError?: ThrowOnError;
+  cache?: CacheConfig;
+  inlineRelations?: InlineRelations;
+  retry?: RetryOptions;


(blocking): @maoberlehner is possible the client doesn't have any rate limit/throttling logic ATM? It's important as, for at-scale scenarios, like SSG or high peaks in SSR, we need to provide the user both a reactive (retry mechanism) and a preventive (rate limits) they can use to avoid extra costs and proper management they way each needs.

What do you think about option for same strategy we have in current js-client? (providing tiers as default, but overrideable by user)

alexjoverm · 2026-02-27T10:48:18Z

packages/capi-client/src/cache.ts

@@ -0,0 +1,137 @@
+export type CacheStrategy = 'cache-first' | 'network-first' | 'swr';


praise: love the strategies! gives mature default behaviours

alexjoverm · 2026-02-27T11:00:48Z

packages/capi-client/src/index.ts

@@ -0,0 +1,492 @@
+import { createClient, createConfig } from './generated/stories/client';


(blocking) @maoberlehner correct me if I'm wrong, but ATM the flushing behavior is auto and the user cannot opt out from it, correct? That can be problematic as, at-scale scenarios, often users want to have external control of the CV and the flush behavior.

For example:

Often they have a CV stored in a distributed Redis, with multiple load-balanced API's (thus multiple capi-client instances). the capi client shouldn't either auto-flush, rather user need to have manual control of flushing and cv management

Flushing immediately after a webhook is triggered (story published, deleted, updated, etc)

Rare, but imagine that during a SSG build, a content editor publishes a set of stories. Likely part of the generated website would have version A, and other part version B
etc etc

In current js-client, that's customizable via an option, say like:

cache: { flush: 'auto' | 'manual' }

Of course, the manual would need some kind of client.flushCache() so users can handle it themselves.

alexjoverm · 2026-02-27T11:08:56Z

packages/capi-client/README.md

@@ -0,0 +1,584 @@
+# Storyblok Content Delivery API Client


(blocking): we need to keep the usual Readme template, and instead move this content into a pkg ref in the Docs platform

alexjoverm · 2026-02-27T11:17:01Z

packages/openapi/resources/capi/datasources/main.yaml

+      summary: Retrieve Multiple Datasources
+      description: Returns an array of all datasources with pagination support.
+      parameters:
+        - name: page


@maoberlehner I think we're missing the cv param, both in /datasources and /datasources/{id} requests (they're in the response already)

alexjoverm · 2026-02-27T11:43:08Z

packages/capi-client/src/index.ts

+      return networkResult;
+    }
+
+    const key = createCacheKey(method, path, rawQuery);


@maoberlehner do you think we need to include cv (the full query) in the cache key? How would it behave if we're querying /story-a?version=published first with cv=1 and then gets revalidated and we request with cv=2? As CV is out of the key, would it still get the one with cv=1?

maoberlehner requested a review from Copilot February 6, 2026 14:21

maoberlehner temporarily deployed to test February 6, 2026 14:21 — with GitHub Actions Inactive

maoberlehner force-pushed the feature/capi-client branch from 4945d5f to 093cf73 Compare February 6, 2026 14:22

maoberlehner had a problem deploying to test February 6, 2026 14:22 — with GitHub Actions Failure

maoberlehner commented Feb 6, 2026

View reviewed changes

packages/capi-client/src/index.ts Outdated Show resolved Hide resolved

Copilot AI reviewed Feb 6, 2026

View reviewed changes

maoberlehner commented Feb 6, 2026

View reviewed changes

packages/capi-client/package.json Show resolved Hide resolved

maoberlehner had a problem deploying to test February 10, 2026 09:16 — with GitHub Actions Failure

maoberlehner temporarily deployed to test February 11, 2026 14:05 — with GitHub Actions Inactive

maoberlehner had a problem deploying to test February 24, 2026 08:32 — with GitHub Actions Failure

maoberlehner had a problem deploying to test February 24, 2026 08:38 — with GitHub Actions Failure

maoberlehner commented Feb 24, 2026

View reviewed changes

packages/capi-client/package.json Outdated Show resolved Hide resolved

maoberlehner commented Feb 24, 2026

View reviewed changes

packages/capi-client/README.md Outdated Show resolved Hide resolved

maoberlehner commented Feb 24, 2026

View reviewed changes

packages/capi-client/src/index.ts Outdated Show resolved Hide resolved

maoberlehner temporarily deployed to test February 24, 2026 09:00 — with GitHub Actions Inactive

maoberlehner temporarily deployed to test February 24, 2026 10:50 — with GitHub Actions Inactive

maoberlehner marked this pull request as ready for review February 24, 2026 11:21

maoberlehner requested review from alexjoverm and dipankarmaikap February 24, 2026 11:21

maoberlehner added 7 commits February 27, 2026 08:29

fix(openapi): allow story identifier to be integer or string

db10910

The API accepts both numeric IDs and string identifiers; update the OpenAPI schema so clients generate correct types and validation matches actual behavior

test(capi-client): resolve openapi spec path via file url

5ba5784

Use fileURLToPath with import.meta.url instead of __dirname so tests can resolve the OpenAPI spec path correctly in an ES module environment

docs: standardize GitHub capitalization in READMEs

46b7542

Align GitHub branding across package READMEs to improve documentation consistency and professionalism

docs: clarify issue reproduction instructions in package READMEs

be7abb3

Fix typo and standardize "GitHub repo" phrasing to improve clarity for users creating minimal reproducible examples when they can't share company code

docs: point package docs to local contributing guidelines

e2bf8ca

Use local CONTRIBUTING.md and correct package naming so contributors see repo-specific guidelines instead of central .github docs

maoberlehner added 18 commits February 27, 2026 08:29

fix(capi): use personal access token auth instead of query param

716e15e

Align CAPI client and OpenAPI spec with personal access token security by moving authentication from query parameters to the client auth configuration, avoiding token leakage in URLs and keeping docs consistent.

chore(openapi): align story field schemas with OpenAPI 3.1 and shared…

42e30a3

… input model

fix(openapi): align story schemas and list response with API behavior

acb63de

Ensure story schema required fields and properties reflect actual Storyblok responses and metadata, and document pagination headers on the stories list endpoint to keep API docs accurate and complete

feat(capi-client): add generic HTTP methods to API client

5199a6b

qs: Add CDN caching, cv helpers and SWR strategy

1f33b7e

qs: Add memory cache TTL, LRU, and cv cache tests

c3eaa9e

chore(ai): move unit test skill to root directory

7f5aa47

feat(capi-client): inline resolved relations in story content

e4f8e51

Add optional relation inlining for stories.get and stories.getAll. Also fetch missing rel_uuids automatically and resolve relation cycles safely.

feat(capi-client): add links, spaces, datasources, and tags support

468d53b

fix(ci): stop forcing compact pkg-pr-new URLs

5999af8

Remove --compact from preview publishing so CI does not require packages to be pre-published on npm.

chore(capi-client): update imports to use stories-generated types

92a2a24

Align tests and utilities with the new stories client generation path after directory restructuring.

docs(capi-client): remove outdated relation fetching details from README

0729a4b

The documented behavior for handling relation UUIDs no longer matches the current client implementation, so removing it prevents misleading usage assumptions and keeps the README accurate.

feat(capi-client): make retry config configurable with defaults

145cb80

chore(capi-client): bump version for initial minor release

77eaeae

Prepare @storyblok/api-client for a 0.1.0 release so it can be published and consumed as a publicly usable package

docs(capi-client): link LRU eviction note to custom cache provider se…

23715aa

…ction

fix(openapi): remove uuid format from story content _uid field

ce5eab3

maoberlehner force-pushed the feature/capi-client branch from d162096 to ce5eab3 Compare February 27, 2026 08:06

maoberlehner had a problem deploying to test February 27, 2026 08:06 — with GitHub Actions Failure

maoberlehner temporarily deployed to test February 27, 2026 08:06 — with GitHub Actions Inactive

fix(capi-client): align exports with tsdown output and enforce GET-on…

bf9bfef

…ly client

maoberlehner temporarily deployed to test February 27, 2026 10:37 — with GitHub Actions Inactive

maoberlehner had a problem deploying to test February 27, 2026 10:37 — with GitHub Actions Failure

alexjoverm requested changes Feb 27, 2026

View reviewed changes

alexjoverm reviewed Feb 27, 2026

View reviewed changes

		const UUID_CHUNK_SIZE = 50;
		const MAX_CONCURRENT_REQUESTS = 50;

		@@ -0,0 +1,137 @@
		export type CacheStrategy = 'cache-first' \| 'network-first' \| 'swr';

		@@ -0,0 +1,492 @@
		import { createClient, createConfig } from './generated/stories/client';

Conversation

maoberlehner commented Feb 6, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot commented Feb 24, 2026

Uh oh!

dipankarmaikap commented Feb 26, 2026

Uh oh!

alexjoverm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexjoverm Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pkg-pr-new bot commented Feb 24, 2026 •

edited

Loading

alexjoverm Feb 27, 2026 •

edited

Loading