@keboola/api-fixtures 22.0.0 → 27.0.0

package/AGENTS.md

@@ -11,6 +11,10 @@ becomes a TypeScript compile error.
 
 Current slices:
 
+- `storage.bootstrap` — `getStackInfo()`, `verifyStorageToken()`, `getDevBranches()`, the three
+  responses a client's ready gate needs before it is usable. Reach for it in any test that builds a
+  real client over MSW. `getStackInfo()` announces every service by default, which is what keeps a
+  test's service clients from being dummies that throw `ServiceUnavailableError`.
 - `storage.tables` — `getTable()`, `listTables()`, `tableFixtures`
 - `apps.apps` / `apps.deployments` / `apps.runs` — the sandboxes-service `/v2` App Deployments
   surface. The three compose into one coherent app (an app's `production` names a deployment in
@@ -19,11 +23,11 @@ Current slices:
 
 ## When to use fixtures vs MSW vs real API
 
-| Need                                                      | Reach for                                      |
-| --------------------------------------------------------- | ---------------------------------------------- |
-| Unit / component tests, pure rendering                    | **This package** — zero network, deterministic |
-| Integration tests that need request/response interception | **MSW** (`msw` handlers)                       |
-| Full end-to-end or contract validation                    | Real API (see `@keboola/e2e-testing`)          |
+| Need                                         | Reach for                                      |
+| -------------------------------------------- | ---------------------------------------------- |
+| Unit / component tests, pure rendering       | **This package** — zero network, deterministic |
+| Anything exercising a client or a query hook | **MSW handlers, bodies from this package**     |
+| Full end-to-end or contract validation       | Real API (see `@keboola/e2e-testing`)          |
 
 ## Adding a new endpoint slice
 
@@ -34,9 +38,11 @@ Current slices:
    yourself; `unknown` is acceptable only when it propagates from the contract type (e.g.
    `TableDetail['attributes']` is `unknown[]`). Prefer `T['prop']` aliases or contextual
    typing via `satisfies T` over re-asserting the upstream type.
-4. Export a named fixtures object (`<resource>Fixtures`) using
+4. When the slice has distinct variants worth naming (a fresh vs. a large table, a failed vs. a
+   running job), export them as a `<resource>Fixtures` object using
    `satisfies Record<'<key1>' | '<key2>' | …, T>` so missing or renamed keys become a
-   compile-time error.
+   compile-time error. A slice whose factories each return one canonical shape needs no such
+   object — it would only alias their defaults.
 5. Re-export everything from `src/index.ts`.
 6. Add a vitest smoke test in `<resource>.test.ts` that verifies shape + assigns to the
    typed variable (compile-time contract check).

package/CHANGELOG.md

@@ -0,0 +1,287 @@
+# @keboola/api-fixtures
+
+## 27.0.0
+
+### Minor Changes
+
+- Add a `storage.bootstrap` fixture slice — the three responses a client's ready gate needs before
+  it is usable (`GET /v2/storage`, `/v2/storage/tokens/verify`, `/v2/storage/dev-branches`).
+
+  `getStackInfo()`, `verifyStorageToken()` and `getDevBranches()` are typed by
+  `@keboola/api-client/storage/types`, so a field the backend adds arrives with `pnpm gen:types`
+  rather than being transcribed into every MSW test that bootstraps a client. `getStackInfo()`
+  announces every service by default, which is what keeps a test's queue / data-science / vault
+  client from being a dummy that throws `ServiceUnavailableError`; pass `services` to narrow it.
+
+  `@keboola/api-client` gains a runtime `ServiceId` const in `@keboola/api-client/constants`, with
+  the `ServiceId` type now derived from it. Announcing every service is exhaustive by construction:
+  a service added to the client flows into the fixture without an edit.
+
+  `@keboola/api-client-react`'s test fixtures now come from the slice; its published output is unchanged.
+
+### Patch Changes
+
+- The fixtures-vs-MSW decision table routed everything but "integration tests" away from MSW, which
+  read as "unit and component tests never intercept requests". A test whose subject is a client or a
+  query hook has to, or it asserts its own mock — so that row now names clients and query hooks, and
+  says bodies come from this package where a slice exists and `satisfies` the generated type where one
+  does not.
+
+  `AGENTS.md` ships in the tarball, so this is a republish rather than a repo-only doc edit.
+
+- Updated dependencies:
+  - @keboola/api-client@32.0.0
+
+## 26.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@31.0.0
+
+## 25.0.0
+
+### Patch Changes
+
+- The published tarball now carries a `CHANGELOG.md`, so a consumer can read what changed in a release — breaking changes included — without leaving their `node_modules`.
+
+  It could not simply be added to `files`. This repo is private, so every reference `@changesets/changelog-github` emits is a dead link for anyone reading from npm: PR links, commit SHAs, author handles, and the Linear and cross-repo links that changeset prose carries. Across the publishable packages that came to 490 PR links, 863 commit links, 490 author credits and 102 dependency-bump blocks.
+
+  The published file is generated, not maintained. `scripts/public-changelog.mjs` removes those links ahead of the publish and leaves the prose. An identifier the author typed themselves stays as text — `UT-4009`, `connection#8040` — because it is part of the sentence and, without its URL, resolves to nothing outside Keboola. The repo-side `CHANGELOG.md` keeps every link, because that is how a release gets traced internally. It is rewritten only for the moment the tarballs are packed, then restored — which the release also depends on: `changesets/action` reads each changelog back off disk _after_ the publish command returns, to build that version's GitHub Release body, so without the restore the internal releases would carry the public text. A reference the rules do not cover fails the publish rather than shipping.
+
+  One incidental fix: a hex colour written as `#222529` in changeset prose had been autolinked into a link to issue 222529. Unwrapping restores the colour, so the published notes read as the author wrote them.
+
+- Updated dependencies:
+  - @keboola/api-client@30.0.0
+
+## 24.0.1
+
+### Patch Changes
+
+- Build with tsdown (rolldown) instead of the now-unmaintained tsup. Output layout, exports map, and shipped declarations are unchanged (attw-verified per package); chunk byte sizes shift slightly with rolldown's codegen, and `@keboola/design`'s size budgets are trued up to the new measurements (largest delta: the main bundle cap moves 320→330 KB). `@keboola/design` builds with `platform: 'browser'`, so bundled CJS deps (react-dropzone, react-day-picker) resolve to their ESM builds instead of a UMD `main` that would drag a Node-only runtime require into browser loads.
+
+## 24.0.0
+
+### Minor Changes
+
+- New **Developer Portal** support for `apps-api.keboola.com` — the backend behind `components.keboola.com`. Paths and types are generated from the published spec (`https://apps-api.keboola.com/docs/openapi.yaml`, now registered in `redocly.yaml`), so `pnpm gen:types` refreshes them like every other client.
+
+  Two layers, matching the rest of the package:
+
+  ```ts
+  // The client plus the session that keeps it authenticated. Start here.
+  import { createDeveloperPortalSdk } from "@keboola/api-client/sdk/developerPortal";
+  // The pure client: one method per endpoint, no state. Enough for every `security: []` operation.
+  import { createDeveloperPortalClient } from "@keboola/api-client/developerPortal";
+  import type { App, Vendor } from "@keboola/api-client/developerPortal/types";
+  ```
+
+  Covers all 58 spec operations across four namespaces — `auth`, `vendors`, `apps`, `admin` — flat inside each, named `get*` / `create*` / `update*` / `delete*` with the noun on the method (`apps.getPublishedApps`, `admin.approveVendor`), matching `management` and `storage`. `createDeveloperPortalSdk` returns `{ api, session }` the way `createKeboola` does, and for the same reason — the credential is stateful. It stays separate from `createKeboola` because apps-api is its own identity domain (its own Cognito pool, its own token trio), so it is absent from `createServiceClients.ts` and never appears on the `api` proxy.
+
+  Three properties worth knowing:
+  - `Authorization` carries the **raw token with no `Bearer` prefix** — the spec's security schemes are `type: apiKey`, so `createBearerAuthMiddleware` is not reusable and the SDK ships its own.
+  - **Two fetch clients.** The authenticated one stamps the id token; the other carries no auth and backs the operations the spec marks `security: []`, plus the four calls that supply their own `Authorization`: `GET /auth/token` (refresh token), `POST /auth/logout` (access token), and `POST /auth/mfa` + `POST /auth/mfa/confirm` (id token, alongside an access token in the body). Those four take the token as an argument, and the SDK binds them from the session, so `api.auth.logout()` needs nothing from the caller.
+  - **The spec is the source of truth.** `types.ts` derives every shape from the generated schema, with no hand-written overlay. Two vendor shapes fall out of that: `GET /vendors` returns `isTrusted` as the raw MySQL tinyint (`VendorListItem`), every other vendor endpoint converts it to a boolean (`Vendor`). Outgoing payloads are no longer validated at runtime — the generated request types replace the zod schemas, which is how every other client in the package works.
+
+  `@keboola/api-fixtures` gains `fixtures.developerPortal` — apps across every publishing state, vendors including a pending `_v`-prefixed one, users, service accounts, and an app change log. Each is `satisfies`-checked against the generated types, so a fixture cannot carry a field the API does not return.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@29.0.0
+
+## 23.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@28.0.0
+
+## 22.0.0
+
+### Minor Changes
+
+- Add an `apps` slice covering the sandboxes-service `/v2` App Deployments surface: `getApp` / `listApps` / `appFixtures`, `getDeployment` / `listDeployments` / `deploymentFixtures`, and `getAppRun` / `listAppRuns` / `runFixtures`, also reachable as `fixtures.apps.*`.
+
+  The three sub-slices compose into one coherent app rather than standing alone: the app's `production` pointer names a deployment that `listDeployments()` returns, and every non-legacy run names a deployment that exists. `apps.test.ts` enforces that join, because a drifting id there is invisible in a component test and surfaces as an empty timeline.
+
+  The named fixtures are the states the `/v2` model makes distinguishable, several of which cannot be told apart from a single field:
+  - `appFixtures.promoting` — a blue/green promotion in flight. `state` stays `RUNNING` and the rollout is visible only as `production.desiredId !== production.actualId`, so a consumer reading `state` alone will miss it.
+  - `appFixtures.legacyV1Serving` — transcribed verbatim from canary: an app created and started through `/v1` that was serving real traffic at the moment it was read, which `/v2` reports as `NOT_DEPLOYED` with an all-null `production` because it was never adopted into the deployments model. It is the counterexample to deriving "is this app serving" from `state`.
+  - `appFixtures.sleeping` vs `appFixtures.suspended` — both stopped, but only the first wakes on the next request.
+  - `deploymentFixtures.buildFailed` vs `runFailed` — no artifact was ever produced versus an artifact that crashes on every run. Different problems with different fixes, and the first is not reachable on the platform today (every deployment is `PREBUILT`); it exists because the headline-status table in the spec treats it as a contract.
+  - `runFixtures.failed` — a classified failure with `startedAt: null`. A run can be attributed a cause on either side of its container ever executing, so `failureReason` is the field to branch on, not `startedAt`.
+
+  Every fixture is typed against `@keboola/api-client/apps/types`, and `apps.test-d.ts` pins the factories to exactly the generated types. The `/v2` spec is flagged experimental upstream, so that assertion is the alarm for a shape that moves.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@27.0.0
+
+## 21.0.0
+
+### Patch Changes
+
+- These packages now ship their `AGENTS.md` usage contract to npm, so external
+  consumers (and their AI agents) can read it at
+  `node_modules/@keboola/<name>/AGENTS.md`, version-pinned to the release they
+  actually installed.
+
+  Previously only `@keboola/design` published its `AGENTS.md`; every other package
+  omitted it from `files`, so instructions that point agents at that path — such as
+  `apps/boilerplate/AGENTS.md` — silently resolved to nothing outside the monorepo.
+  No code or type changes.
+
+- Updated dependencies:
+  - @keboola/api-client@26.0.0
+
+## 20.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@25.0.0
+
+## 19.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@24.0.0
+
+## 18.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@23.0.0
+
+## 17.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@22.0.0
+
+## 16.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@21.0.0
+
+## 15.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@20.0.0
+
+## 14.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@19.0.0
+
+## 13.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@18.0.0
+
+## 12.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@17.0.0
+
+## 11.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@16.0.0
+
+## 10.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@15.0.0
+
+## 9.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@14.0.0
+
+## 8.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@13.0.0
+
+## 7.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@12.0.0
+
+## 6.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@11.0.0
+
+## 5.0.1
+
+### Patch Changes
+
+- Add `expectTypeOf` type tests binding the exported storage-tables fixtures (`getTable`, `listTables`, `tableFixtures`) to the generated `TableDetail` type from `@keboola/api-client`, and enable Vitest `typecheck` so the assertions are evaluated by `vitest run`. The `getTable`/`listTables` assertions lock the exported API surface to the generated type; the `tableFixtures.*` assertions additionally catch structural drift in the fixture bodies (their narrow inferred literal shapes must stay assignable to `TableDetail`). Contract drift now fails the test suite, not just `tsc`.
+
+## 5.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@10.0.0
+
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@9.0.0
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@8.0.0
+
+## 2.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@7.0.0
+
+## 1.0.0
+
+### Minor Changes
+
+- Publish `@keboola/api-fixtures` to npm (previously workspace-internal). Ships compiled `dist` output (ESM + CJS + type declarations) and declares `@keboola/api-client` as a peer dependency so the re-exported endpoint types resolve in external consumers.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@6.0.0