feat(capi-client): add typed Content Delivery API client package (#428)

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

Author: maoberlehner

.claude/skills/qa-engineer-manual/SKILL.md

@@ -129,7 +129,6 @@ scenarios/
 - Clean up local artifacts with `./scripts/cleanup-local.sh`. Don't hesitate to clean up between tests to start with a clean slate.
 - Place test scripts in `./.claude/tmp/`. Import from the built package: `../../packages/PACKAGE_NAME/dist/index.mjs`.
 - Export env vars before running: `set -a && source ./.env.qa-engineer-manual && set +a && node ./.claude/tmp/test-name.mjs`.
-- Create the MAPI client with `new ManagementApiClient({ token: { accessToken: token } })` — the token must be wrapped in `{ accessToken: ... }`. Do NOT use `createClient` directly.
 - The stories list endpoint does NOT return `content` by default — `story.content?.component` will be `undefined` in list responses. Fetch individual stories for full content.
 - When using two spaces (for example, mapping references between source and target), use `STORYBLOK_SPACE_ID_TARGET` for the target (loaded via `.env.qa-engineer-manual`).
 
@@ -148,7 +147,7 @@ Paths are relative to this `SKILL.md`.
 
 ## Troubleshooting
 
-- Load the `STORYBLOK_SPACE_ID`, `STORYBLOK_SPACE_ID_TARGET`, `STORYBLOK_ASSET_TOKEN`, `STORYBLOK_ASSET_TOKEN_TARGET` and `STORYBLOK_TOKEN` environment variables by running `source ./.env.qa-engineer-manual` (do not attempt to read this file).
+- Load the `STORYBLOK_SPACE_ID`, `STORYBLOK_SPACE_ID_TARGET`, `STORYBLOK_ASSET_TOKEN`, `STORYBLOK_ASSET_TOKEN_TARGET`, `STORYBLOK_TOKEN`, `STORYBLOK_PREVIEW_TOKEN`, and `STORYBLOK_PREVIEW_TOKEN_TARGET` environment variables by running `source ./.env.qa-engineer-manual` (do not attempt to read this file).
 - When running `.mjs` test files, env vars must be **exported** (`set -a && source ./.env.qa-engineer-manual && set +a`) — plain `source` does not propagate to `node` subprocesses.
 
 **MAPI:**

….claude/skills/qa-engineer-unit/SKILL.md .claude/skills/qa-engineer-unit/SKILL.mdpackages/cli/.claude/skills/qa-engineer-unit/SKILL.md renamed to .claude/skills/qa-engineer-unit/SKILL.md packages/cli/.claude/skills/qa-engineer-unit/SKILL.md renamed to .claude/skills/qa-engineer-unit/SKILL.md

@@ -1,4 +1,6 @@
 STORYBLOK_TOKEN=
+STORYBLOK_PREVIEW_TOKEN=
+STORYBLOK_PREVIEW_TOKEN_TARGET=
 STORYBLOK_ASSET_TOKEN=
 STORYBLOK_ASSET_TOKEN_TARGET=
 STORYBLOK_SPACE_ID=

.env.qa-engineer-manual.template

@@ -32,4 +32,4 @@ jobs:
         run: pnpm nx run-many --target=build --parallel=5 -p="tag:npm:public"
       - 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

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

@@ -19,7 +19,7 @@ Inspect the root `package.json` and the `packages/` directory to identify active
 
 ## Code style and conventions
 
-Always use linting and type-checking scripts for affected packages after making changes.
+Always use linting and type-checking scripts for affected packages after making changes. When encountering lint errors, run the lint command with `--fix` first before attempting to fix issues manually.
 
 ### General
 

AGENTS.md

@@ -50,7 +50,7 @@ If you'd like to contribute, please refer to the [contributing guidelines](CONTR
 
 For help, discussion about best practices, or any other conversation that would benefit from being searchable:
 
-- [Discuss Storyblok on Github Discussions](https://github.com/storyblok/monoblok/discussions)
+- [Discuss Storyblok on GitHub Discussions](https://github.com/storyblok/monoblok/discussions)
 
 For community support, chatting with other users, please visit:
 
@@ -65,7 +65,7 @@ For bugs or feature requests, please [submit an issue](https://github.com/storyb
 
 ### I can't share my company project code
 
-We understand that you might not be able to share your company's project code. Please provide a minimal reproducible example that demonstrates the issue by using tools like [Stackblitz](https://stackblitz.com) or a link to a Github Repo lease make sure you include a README file with the instructions to build and run the project, important not to include any access token, password or personal information of any kind.
+We understand that you might not be able to share your company's project code. Please provide a minimal reproducible example that demonstrates the issue by using tools like [Stackblitz](https://stackblitz.com) or a link to a GitHub repo. Please make sure you include a README file with the instructions to build and run the project, important not to include any access token, password or personal information of any kind.
 
 ### Feedback
 

packages/astro/README.md

@@ -0,0 +1 @@
+src/generated

packages/capi-client/.gitignore

@@ -0,0 +1,5 @@
+*
+!dist/
+!dist/**
+!package.json
+!README.md

packages/capi-client/.npmignore

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Storyblok GmbH
+
+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.

packages/capi-client/LICENSE

@@ -0,0 +1,74 @@
+<div align="center">
+
+![Storyblok ImagoType](https://raw.githubusercontent.com/storyblok/.github/refs/heads/main/profile/public/github-banner.png)
+
+<h1 align="center">@storyblok/api-client</h1>
+ <p>
+    A modern TypeScript client for the Storyblok Content Delivery API with built-in caching, retry logic, and rate limiting
+  </p>
+  <br />
+</div>
+
+<p align="center">
+  <a href="https://npmjs.com/package/@storyblok/api-client">
+    <img src="https://img.shields.io/npm/v/@storyblok/api-client/latest.svg?style=flat-square&color=8d60ff" alt="@storyblok/api-client" />
+  </a>
+  <a href="https://npmjs.com/package/@storyblok/api-client" rel="nofollow">
+    <img src="https://img.shields.io/npm/dt/@storyblok/api-client.svg?style=appveyor&color=8d60ff" alt="npm">
+  </a>
+  <a href="https://storyblok.com/join-discord">
+   <img src="https://img.shields.io/discord/700316478792138842?label=Join%20Our%20Discord%20Community&style=appveyor&logo=discord&color=8d60ff">
+   </a>
+  <a href="https://twitter.com/intent/follow?screen_name=storyblok">
+    <img src="https://img.shields.io/badge/Follow-%40storyblok-8d60ff?style=appveyor&logo=twitter" alt="Follow @Storyblok" />
+  </a><br/>
+  <a href="https://app.storyblok.com/#!/signup?utm_source=github.com&utm_medium=readme&utm_campaign=@storyblok/api-client">
+    <img src="https://img.shields.io/badge/Try%20Storyblok-Free-8d60ff?style=appveyor&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB4AAAAeCAYAAAA7MK6iAAAABGdBTUEAALGPC/xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAHqADAAQAAAABAAAAHgAAAADpiRU/AAACRElEQVRIDWNgGGmAEd3D3Js3LPrP8D8WXZwSPiMjw6qvPoHhyGYwIXNAbGpbCjbzP0MYuj0YFqMroBV/wCxmIeSju64eDNzMBJUxvP/9i2Hnq5cM1devMnz984eQsQwETeRhYWHgIcJiXqC6VHlFBjUeXgav40cIWkz1oLYXFmGwFBImaDFBHyObcOzdW4aSq5eRhRiE2dgYlpuYoYSKJi8vw3GgWnyAJIs/AuPu4scPGObd/fqVQZ+PHy7+6udPOBsXgySLDfn5GRYYmaKYJcXBgWLpsx8/GPa8foWiBhuHJIsl2DkYQqWksZkDFgP5PObcKYYff//iVAOTIDlx/QPqRMb/YSYBaWlOToZIaVkGZmAZSQiQ5OPtwHwacuo4iplMQEu6tXUZMhSUGDiYmBjylFQYvv/7x9B04xqKOnQOyT5GN+Df//8M59ASXKyMHLoyDD5JPtbj42OYrm+EYgg70JfuYuIoYmLs7AwMjIzA+uY/zjAnyWJpDk6GOFnCvrn86SOwmsNtKciVFAc1ileBHFDC67lzG10Yg0+SjzF0ownsf/OaofvOLYaDQJoQIGix94ljv1gIZI8Pv38zPvj2lQWYf3HGKbpDCFp85v07NnRN1OBTPY6JdRSGxcCw2k6sZuLVMZ5AV4s1TozPnGGFKbz+/PE7IJsHmC//MDMyhXBw8e6FyRFLv3Z0/IKuFqvFyIqAzd1PwBzJw8jAGPfVx38JshwlbIygxmYY43/GQmpais0ODDHuzevLMARHBcgIAQAbOJHZW0/EyQAAAABJRU5ErkJggg==" alt="Follow @Storyblok" />
+  </a>
+</p>
+
+## Features
+
+- **Type-Safe**: Generated from OpenAPI specifications with full TypeScript support
+- **Caching**: Pluggable cache providers with `cache-first`, `network-first`, and `swr` strategies
+- **Retry Logic**: Built-in retry with exponential backoff and jitter
+- **Rate Limiting**: Preventive rate limiting with automatic tier detection
+- **Region Support**: Automatic regional endpoint selection (`eu`, `us`, `ap`, `ca`, `cn`)
+- **Relation Inlining**: Optional inlining of resolved relations directly into story content
+
+## Documentation
+
+For complete documentation, please visit [package reference](https://www.storyblok.com/docs/packages/storyblok-api-client)
+
+## Contributing
+
+If you'd like to contribute, please refer to the [contributing guidelines](../../CONTRIBUTING.md).
+
+## Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+- [Discuss Storyblok on GitHub Discussions](https://github.com/storyblok/monoblok/discussions)
+
+For community support, chatting with other users, please visit:
+
+- [Discuss Storyblok on Discord](https://storyblok.com/join-discord)
+
+## Support
+
+For bugs or feature requests, please [submit an issue](https://github.com/storyblok/monoblok/issues/new/choose).
+
+> [!IMPORTANT]
+> Please search existing issues before submitting a new one. Issues without a minimal reproducible example will be closed. [Why reproductions are Required](https://antfu.me/posts/why-reproductions-are-required).
+
+### I can't share my company project code
+
+We understand that you might not be able to share your company's project code. Please provide a minimal reproducible example that demonstrates the issue by using tools like [Stackblitz](https://stackblitz.com) or a link to a GitHub repo. Please make sure you include a README file with the instructions to build and run the project, important not to include any access token, password or personal information of any kind.
+
+### Feedback
+
+If you have a question, please ask in the [Discuss Storyblok on Discord](https://storyblok.com/join-discord) channel.
+
+## License
+
+[License](/LICENSE)