@keboola/api-client-react 25.0.0 → 31.0.0

package/AGENTS.md

@@ -0,0 +1,138 @@
+# @keboola/api-client-react
+
+React bindings for [`@keboola/api-client`](../api-client/AGENTS.md). Owns
+the context that holds the typed `ApiClient` instance and the hooks for
+consumers to read it.
+
+## Why a separate package
+
+`@keboola/api-client` is framework-agnostic (used from Node, tests, scripts).
+Keeping React-specific glue out of it lets the SDK stay deployable to
+non-React surfaces. This package is the **only** place that knows about
+`React.Context`.
+
+## Surface
+
+```ts
+import {
+  ApiClientProvider,
+  AuthProvider,
+  LegacyAuthProvider,
+  useApiClient,
+  useAuth,
+  useLegacyAuth,
+  useProject,
+  useStack,
+} from '@keboola/api-client-react';
+```
+
+A keboola client is `{ api, session }`. This package provides the two halves separately:
+
+- `ApiClientProvider` — takes the flow-agnostic `api` and provides it to descendants. A pure
+  pass-through: no lifecycle, no fallback. `useApiClient()` returns that `api`.
+- `LegacyAuthProvider` — takes a **legacy** `session` (+ `baseUrl`, `storageToken`,
+  optional `managementToken`). On mount it drives the session to ready
+  (`setBaseUrl` → `authenticateManagement?` → `authenticateStorageAsync`) and renders `fallback`
+  until `session.isStorageReady()`. Exposes the session via `useLegacyAuth()`.
+- `AuthProvider` — takes a **bearer** `session` (+ `baseUrl`, optional `onAccessTokenChange`). The
+  bearer twin of `LegacyAuthProvider`. On mount it configures the stack and `restore()`s any
+  persisted session, then runs one of two modes, discriminated by whether a credential is supplied:
+  - **programmatic** — `credential` + `projectId` given; it drives itself to ready.
+  - **interactive** — neither given; the session starts unscoped and only the consumer can scope it,
+    so `anonymousFallback` is **required** by the type in this mode. Which slot actually renders at
+    any moment is the table below — restoring and bootstrapping take `loadingFallback` first.
+
+  It renders exactly one of four slots, by state:
+
+  | State                             | Renders             |
+  | --------------------------------- | ------------------- |
+  | scoped + storage build ready      | `children`          |
+  | storage build failed              | `errorFallback`     |
+  | restoring / bootstrapping         | `loadingFallback`   |
+  | not yet scoped (interactive only) | `anonymousFallback` |
+
+  "Not yet scoped" is **not** the same as "signed out": the storage build sits at `idle` both for an
+  anonymous visitor and for an authenticated one with no project selected (zero projects, or just
+  used "Leave project"), and both land in `anonymousFallback`. Consumers that need to tell the two
+  apart have to read the session status themselves.
+
+  `children` may be a function — it is called only in the ready state and receives the scoped
+  `{ projectId, baseUrl }`, so consumers don't re-narrow the session state themselves:
+
+  ```tsx
+  <AuthProvider session={session} baseUrl={url} anonymousFallback={<Login />}>
+    {({ projectId }) => <App projectId={projectId} />}
+  </AuthProvider>
+  ```
+
+  `onAccessTokenChange` fires with the access token on the initial credential and after every
+  in-band rotation, so the host can mirror it (e.g. into a token store). Exposes the session via
+  `useAuth()`.
+
+- `useApiClient()` — returns the `api`; **throws** outside `<ApiClientProvider />`. Use it from
+  query/mutation hooks.
+- `useProject()` / `useStack()` — shortcut hooks for `api.context.project` / `api.context.stack`.
+  Same null-throwing contract.
+
+Nesting: mount the auth provider outermost (it owns drive-to-ready) with `ApiClientProvider` inside
+it, so product code only mounts once the `api` is ready:
+
+```tsx
+<LegacyAuthProvider session={session} baseUrl={url} storageToken={token} fallback={<Loading />}>
+  <ApiClientProvider api={api}>{children}</ApiClientProvider>
+</LegacyAuthProvider>
+```
+
+For credential verification (dev login, project switching) there is no provider —
+construct the real per-service client with the candidate host + token and call its
+verify: `createStorageClient({ baseUrl, auth: { type: 'sapi-token', token } }).tokens.verify()`, or
+`createManagementClient({ baseUrl, auth: { type: 'management-token', token }, withAuthMiddleware: false }).verifyToken()`
+(the flag skips the session-managing auth middleware so it's a plain validity check).
+
+## Conventions
+
+- The context value is typed `KeboolaApi | null` and the hooks throw on
+  null — see [apps/AGENTS.md](../../apps/AGENTS.md) ("State Management"
+  → "Tree-passing"). Don't soften this to optional types or `??` fallbacks;
+  a missing provider is a programming error.
+- React is a **peerDependency** (^19.0.0). Don't import React types from
+  this package's own deps in consumers.
+- The auth provider drives the session to ready exactly once on mount. Changing
+  its props after mount is a no-op by design — if you need a new auth context,
+  mount a fresh provider.
+
+## Non-component access (loaders, services, module scope)
+
+`useApiClient()` is for React components only. A TanStack Router loader, a
+module instantiated at import time, or any code running outside the React tree
+can't call the hook. Don't reach for the context there — construct a client
+directly:
+
+```ts
+// Single service — the common case
+import { createStorageClient } from '@keboola/api-client/storage';
+
+const storage = createStorageClient({ baseUrl, auth: { type: 'sapi-token', token } });
+const tables = await storage.tables.getTables();
+```
+
+If you need several services from non-component code, create one client at app
+bootstrap (`createLegacyKeboola(...)` / `createKeboola(...)`, drive its session to
+ready, and export the `api`) and import that instance where needed — rather than
+re-creating clients per call. See
+[`@keboola/api-client` → Getting a client](../api-client/AGENTS.md#getting-a-client).
+
+## Canonical consumers
+
+- `apps/kbc-ui/src/scripts/app.tsx` — production `ApiClientProvider` mount
+- `apps/kbc-ui/src/scripts/modules/sandboxes/queries.ts` — `useApiClient`
+  inside a TanStack Query hook (the dominant pattern)
+
+## Don'ts
+
+- **Never** create a parallel React context that wraps another client
+  instance. One client per app, mounted once at the top.
+- **Never** drive `session` manually in a consumer — the auth provider
+  (`AuthProvider` / `LegacyAuthProvider`) owns the drive-to-ready lifecycle.
+- **Never** import from a deep path (`@keboola/api-client-react/src/...`).
+  The package only exports `src/index.ts`.

package/CHANGELOG.md

@@ -0,0 +1,337 @@
+# @keboola/api-client-react
+
+## 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