@keboola/api-client-react 27.0.0 → 32.0.0

package/AGENTS.md

@@ -69,6 +69,12 @@ A keboola client is `{ api, session }`. This package provides the two halves sep
   in-band rotation, so the host can mirror it (e.g. into a token store). Exposes the session via
   `useAuth()`.
 
+  `onRestore` fires once with the boot `restore()`'s `{ status }`. The slot that renders cannot
+  stand in for it — `expired` and `empty` both land in `anonymousFallback`, and so does a `restored`
+  session that carried no project — so an app that wants to say "your session expired" rather than
+  show a bare sign-in screen needs this callback. A `restore()` that throws reports `empty`, the
+  same value the provider acts on, so a transport failure is never reported as an expiry.
+
 - `useApiClient()` — returns the `api`; **throws** outside `<ApiClientProvider />`. Use it from
   query/mutation hooks.
 - `useProject()` / `useStack()` — shortcut hooks for `api.context.project` / `api.context.stack`.

package/CHANGELOG.md

@@ -0,0 +1,374 @@
+# @keboola/api-client-react
+
+## 32.0.0
+
+### Minor Changes
+
+- Add `onRestore` to `AuthProvider`, so a consumer can act on the outcome of the boot `restore()`.
+
+  The provider owns that call and kept the result to itself, but `{ status: 'empty' | 'restored' |
+'expired' }` are three different things to say to a user and the rendered slot cannot tell them
+  apart: `expired` and `empty` both land in `anonymousFallback`, and so does a `restored` session that
+  carried no project. An app wanting to say "your session expired" rather than a bare sign-in screen
+  had to reconstruct the outcome from `hasPersistedValue()` sampled before mount — which reads a
+  cleared-because-corrupt entry, a stack mismatch and a transport failure all as an expiry.
+
+  A `restore()` that throws reports `empty`, matching what the provider itself acts on, so being
+  offline at boot is never dressed up as a session expiry. The callback fires once, including under
+  StrictMode's double-invoked effects.
+
+### Patch 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.
+
+- Updated dependencies:
+  - @keboola/api-client@32.0.0
+
+## 31.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@31.0.0
+
+## 30.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
+
+## 29.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@29.0.0
+
+## 28.0.0
+
+### Patch Changes
+
+- Build with tsdown instead of tsup. Fixes declaration bundling against the new `@keboola/api-client` output: tsup's dts pass inlined `@keboola/api-client/*` subpath types and leaked unresolvable relative chunk imports into `dist/index.d.ts` (attw red in all four modes); with tsdown, peer dependencies stay external in declarations — subpaths included.
+
+- Updated dependencies:
+  - @keboola/api-client@28.0.0
+
+## 27.0.0
+
+### Minor Changes
+
+- `LegacyAuthProvider` gained an `errorFallback` slot, the counterpart of the one its bearer twin `AuthProvider` already had.
+
+  It previously asked only `session.isStorageReady()`, so an errored storage build was indistinguishable from a pending one and kept rendering `fallback` — a consumer whose SAPI token had expired showed a loading state forever. It now reads the build state from `debug()`/`subscribe`, renders `errorFallback` on failure (defaulting to `fallback`, so the old behaviour stands when it is omitted) and logs the failure, which nothing else did.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@27.0.0
+
+## 26.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
+
+## 25.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@25.0.0
+
+## 24.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@24.0.0
+
+## 23.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@23.0.0
+
+## 22.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@22.0.0
+
+## 21.0.0
+
+### Major Changes
+
+- Reshape the SDK lifecycle around two authentication flows behind one product surface.
+  - **Breaking:** the entry points are now `createKeboola()` (bearer / OAuth) and `createLegacyKeboola()` (legacy SAPI + management token). Each returns `{ api, session }` — `api` is the flow-agnostic product surface (`auth`, `management`, `storage`, `queue`, `context`, `sdk`, …); `session` is the flow-specific lifecycle (bearer: `authenticate(credential)` → `setProject(id)`; legacy: `authenticateStorage(sapiToken)` / `authenticateManagement(manageToken)`). The old `createApiClient()` / `init()` lifecycle and the `ApiClient` type are removed.
+  - **Breaking:** per-service factories take an `auth` strategy instead of a bare token — `createStorageClient({ baseUrl, auth: { type: 'sapi-token', token } })`, `createManagementClient({ baseUrl, auth: { type: 'management-token', token } })` (bearer: `{ type: 'bearer', token }`). `createManagementClient` keeps `withAuthMiddleware` (default `true`; pass `false` for a raw validity-check client).
+  - `@keboola/api-client-react` exposes three providers: `ApiClientProvider` (propagates `api` to `useApiClient()`), `LegacyAuthProvider` (drives the legacy session to ready and gates on a fallback), and `AuthProvider` (bearer; finished with the login flow in a follow-up). `useApiClient` / `useProject` / `useStack` return the `api` surface.
+  - **Breaking:** the token-less public clients `assets` / `status` are not part of the keboola client — import `createAssetsClient` / `createStatusClient` from `@keboola/api-client/assets` and `@keboola/api-client/status`. `metastore` is a stack-discovered service, exposed as `api.metastore`.
+  - `KeboolaError` / `isKeboolaError` are exported from the package root and are the errors the client actually throws (lifecycle gating: `NotReady`, `Unconfigured`, `NoManagementToken`, …).
+
+  Migration: `const api = createApiClient(); await api.init(opts)` → `const { api, session } = createLegacyKeboola(opts); await session.authenticateStorageAsync(token)` (or `createKeboola` for the bearer flow). Per-service: `createStorageClient({ baseUrl, token })` → `createStorageClient({ baseUrl, auth: { type: 'sapi-token', token } })`.
+
+- Give `AuthProvider` one slot per session state, and make the interactive mode's login slot mandatory.
+  - **Breaking:** the single `fallback` prop is replaced by three, so a genuine failure is no longer indistinguishable from "not signed in yet": `loadingFallback` (restoring / bootstrapping), `anonymousFallback` (no session — render the sign-in UI), and `errorFallback` (the storage build failed). `children` still render only once the session is scoped and storage is ready.
+  - **Breaking:** props are a discriminated union over the two bootstrap modes. Programmatic (`credential` + `projectId`) requires `baseUrl`, since a credential is bound to the stack that issued it. Interactive takes neither credential nor `baseUrl` — the stack comes from the restored session or from the login UI — and **requires** `anonymousFallback`, so omitting the login UI is a compile error instead of a permanently blank screen.
+  - `children` may now be a function receiving the scoped `{ projectId, baseUrl }`, so consumers don't re-narrow session state to read the project they landed on.
+  - The loading state is seeded from `session.hasPersistedValue()`: with nothing persisted there is nothing to wait for, so the login UI paints on the first render instead of flashing a loader for an empty, network-free restore.
+
+### Minor Changes
+
+- Finish the bearer (programmatic) auth flow. `AuthProvider` is now the bearer twin of `LegacyAuthProvider`: it takes `baseUrl` / `credential` / `projectId` (plus optional `onAccessTokenChange` and `fallback`), drives the session to ready on mount, mirrors the rotating access token out via `onAccessTokenChange`, and gates its children behind readiness.
+
+- Rework the bearer (OAuth) auth internals for a cleaner separation of concerns. Token handling now lives in a `TokenCredential`-style provider — `getAccessToken({ forceRefresh })` always returns a usable access token, refreshing (deduped) on near-expiry or when forced — consumed by a thin auth middleware that stamps the live token on every request and replays once on a 401. The bearer session config is a discriminated-union state machine (`anonymous` / `authenticated` / `scoped`) that owns its own credential model and the fire-once session-expiry latch: `session.authenticate` now takes a `TokenSet` (`accessToken`, `refreshToken`, `expiresIn`) rather than the full login credential, and `SessionSnapshot.config` is that state union. Also adds a `dedupe` (single-flight) util.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@21.0.0
+
+## 20.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@20.0.0
+
+## 19.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@19.0.0
+
+## 18.0.0
+
+### Major Changes
+
+- Discover the metastore service from stack info instead of taking a `metastoreBaseUrl` option.
+  - **Breaking:** `metastoreBaseUrl` is removed from `ApiClientOptions`. `createApiClient`/`init()` no longer accept it, and `ApiClientProvider` no longer accepts the `metastoreBaseUrl` prop.
+  - `metastore` is now a stack-discovered service client (like `queue`, `vault`, …): its base URL comes from `getStackInfo` service discovery, exposed on the client as `api.metastore` and consumed by the tag SDK. On stacks that don't advertise a metastore service, the client resolves to a lazy no-op that throws only when a metastore method is actually called.
+
+  Migration: drop `metastoreBaseUrl` from every `createApiClient`/`init()`/`ApiClientProvider` call — the URL is resolved automatically from the stack.
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@18.0.0
+
+## 17.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@17.0.0
+
+## 16.0.0
+
+### Major Changes
+
+- Remove `createDevApiClient` (and, in `@keboola/api-client-react`, `DevApiClientProvider` / `useDevApiClient`).
+
+  `createDevApiClient` was a stateless pass-through — `{ verify: { storageApiToken, managementApiToken } }` with no lifecycle, no base-URL registry, no `init()`. It doesn't fit the client model; it's just two host-parameterized verify calls. The React dev-provider layer existed only to carry that object through context.
+
+  Verify a candidate token with the real per-service clients directly (host-parameterized per call, no provider):
+  - storage: `createStorageClient({ baseUrl: host, token }).tokens.verify()`
+  - management: `createManagementClient({ baseUrl: host, token, withAuthMiddleware: false }).verifyToken()`
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@16.0.0
+
+## 15.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@15.0.0
+
+## 14.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@14.0.0
+
+## 13.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@13.0.0
+
+## 12.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@12.0.0
+
+## 11.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@11.0.0
+
+## 10.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@10.0.0
+
+## 9.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@9.0.0
+
+## 8.0.2
+
+### Patch Changes
+
+- docs: document the sanctioned non-component data-access pattern (loaders / module-scope services) — use a per-service client or a bootstrap `createApiClient` instance, not the `useApiClient` hook
+
+- Updated dependencies:
+  - @keboola/api-client@8.0.2
+
+## 8.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@8.0.0
+
+## 7.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@7.0.0
+
+## 6.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@6.0.0
+
+## 5.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@5.0.0
+
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@4.0.0
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies:
+  - @keboola/api-client@3.0.0
+
+## 2.0.0
+
+### Patch Changes
+
+- Re-publish to scrub `workspace:^` from the npm tarball manifests.
+
+  `@keboola/design@1.2.0` shipped with literal `workspace:^` strings in
+  `dependencies` (`codemirror-lang-sfsql`, `codemirror-lang-sql`,
+  `tailwind-config`), making `npm install @keboola/design` fail with
+  `EUNSUPPORTEDPROTOCOL` — npm has no way to resolve the yarn-only
+  workspace protocol against a public registry.
+  `@keboola/api-client-react@1.0.1` shipped with the same
+  leak in `peerDependencies` (`@keboola/api-client`) — less fatal
+  because peerDeps are warnings, not errors, but still wrong.
+
+  Root cause was the publish workflow invoking plain `npm publish`
+  (which doesn't understand `workspace:^`) instead of
+  `yarn npm publish` (which rewrites it just-in-time). This changeset
+  rides alongside the workflow script fix, so the next release cycle
+  republishes both packages cleanly through the corrected path.
+
+  The other recently-bumped packages (`api-client`, `brand-registry`,
+  `brand-audit`, `codemirror-lang-*`, `agent-precheck`,
+  `oxlint-config`) don't need patches — they happen to have no
+  `@keboola/*` runtime or peer deps, so the bug couldn't bite them.
+
+- Updated dependencies:
+  - @keboola/api-client@2.0.0
+
+## 1.0.1
+
+### Patch Changes
+
+- Re-publish to fix unresolved `workspace:^` protocol references in the npm tarball manifests.
+
+  The initial bootstrap publishes (2026-05-18 for `@keboola/api-client` and `@keboola/api-client-react`, later for the rest) were run manually with `npm publish` from a maintainer machine. Bare `npm publish` doesn't understand yarn's `workspace:` protocol, so the published `package.json` files shipped with literal `workspace:^` strings in `dependencies`, `peerDependencies`, and `devDependencies`.
+
+  The blocker is `@keboola/api-client-react@1.0.0`'s `peerDependencies` declaring `@keboola/api-client: workspace:^`. Running `npm install @keboola/api-client-react` from outside the monorepo fails with `EUNSUPPORTEDPROTOCOL` because npm can't resolve the `workspace:` protocol. The same string also appears in `@keboola/api-client`, `@keboola/brand-registry`, and `@keboola/oxlint-config` `devDependencies` — npm ignores those for transitive installs, but they're still wrong in the published manifests and worth cleaning up in the same release.
+
+  This patch bump triggers a regular changesets-driven release. When `changeset publish` runs in CI, it rewrites `workspace:*` references to the actual resolved version ranges before calling `npm publish`, restoring a consumable npm surface for every package.
+
+  `@keboola/codemirror-lang-sql` has the same issue but is already covered by an existing pending changeset (`codemirror-lang-sql-publish.md`, minor bump for initial publish setup); the next release will fix it through that bump.
+
+  No source code or runtime behavior changes. The local `workspace:^` references in source `package.json` files stay (they're correct for monorepo workspace deps; the rewrite happens only at publish time).
+
+- Updated dependencies:
+  - @keboola/api-client@1.0.1
+
+## 1.0.0
+
+### Patch Changes
+
+- Initial publish setup for `@keboola/api-client-react` — React provider + hooks (`useApiClient`, `useProject`, `useStack`, `useDevApiClient`) for the Keboola SDK. Ships dual ESM/CJS bundles via `tsup` with React 18/19 as peer dependencies. Linked with `@keboola/api-client` so both packages release together.
+
+- Updated dependencies:
+  - @keboola/api-client@1.0.0