# Manually Test the @storyblok/management-api-client Package

`@storyblok/management-api-client` is the Management API (MAPI) client. The key things to validate
manually are that the schema-aware `.withTypes()` integration correctly narrows story content, that
every define helper produces a valid creation payload, and that Zod schemas accept real API
responses.

## Automated e2e tests

The `@storyblok/mapi-integration-tests` package
(`packages/mapi-client/playground/integration-tests`) covers the full round-trip against a real
Storyblok space in `test/specs/mapi-round-trip.spec.e2e.ts`:

- Seeds components, datasources, internal tags, presets, and stories via the MAPI.
- Validates runtime values, type narrowing, nested bloks (two- and three-level), unwhitelisted
  bloks, and update round-trips.
- Validates MAPI Zod schemas (`componentSchema`, `storySchema`, `datasourceSchema`,
  `datasourceEntrySchema`) against real API responses.

Run manually:

```bash
pnpm --filter @storyblok/mapi-integration-tests test:e2e
```

### Prerequisites

- A `.env.qa-engineer-manual` file at the repo root with `STORYBLOK_TOKEN` and `STORYBLOK_SPACE_ID`.
- `@storyblok/management-api-client` must be built first.

## Fetch via MAPI client and check content types

`stories.get(storyId)` takes a numeric/string ID as its first positional argument — there is no
`getBySlug`. Fetch the ID from `stories.list` first:

```ts
import { createManagementApiClient } from "@storyblok/management-api-client";

const client = createManagementApiClient({
  personalAccessToken: process.env.STORYBLOK_TOKEN,
  spaceId,
});
const list = await client.stories.list({ query: { per_page: 100 } });
const story = list.data?.stories?.find((s) => s.slug === "home");
const result = await client.stories.get(story.id);
console.info(result.data?.story?.content);
```

## Push component JSONs via the CLI

To push `defineComponent` components, serialize the component objects to JSON and stage them under
`.storyblok/components/<space_id>/`:

```bash
node packages/cli/dist/index.mjs components push \
  --from qa-test \
  --space $STORYBLOK_SPACE_ID \
  --separate-files
```

**Always push components before stories.** The CLI validates that each story's `content.component`
(and any nested block components) exist in the space. Pushing stories first fails if the referenced
components are not yet present.

You can do the same with stories. **Story filename convention:** the CLI requires files named
`{slug}_{uuid}.json` where the part after the last `_` exactly matches `story.uuid` in the JSON. Use
hyphens (not underscores) in UUIDs. A mismatch causes Pass 2 of the push (reference mapping +
content update) to silently skip all stories.

## Known quirks

- **Stories require a content type component (`is_root: true`).** The MAPI rejects story creation
  with `"please select a content type component as your root component"` if the component used as
  the story root does not have `is_root: true`.
- **MAPI `stories.get` takes a positional ID, not an options object:** `client.stories.get(id)` —
  there is no `getBySlug`. The `list` response does not include `content`; call `get(id)` for full
  content.
- **MAPI client constructor uses `personalAccessToken`:**
  `createManagementApiClient({ personalAccessToken: '...', spaceId: ... })`.
- **Delete methods are `delete`:** Use `client.RESOURCE.delete(id)`.
- **Each story JSON must have a unique `id`.** If multiple story files share the same `id`, the
  CLI's manifest maps all of them to the same `old_id` entry, causing "slug already taken" errors.