@keboola/api-client-react 27.0.0 → 31.0.0

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

package/dist/index.cjs

@@ -1,139 +1,161 @@
-'use strict';
-
-var react = require('react');
-var jsxRuntime = require('react/jsx-runtime');
-
-// src/context.ts
-var MISSING_API_CLIENT_ERROR = "useApiClient must be used within <ApiClientProvider />";
-var MISSING_PROJECT_ERROR = "useProject must be used within <ApiClientProvider />";
-var MISSING_STACK_ERROR = "useStack must be used within <ApiClientProvider />";
-var MISSING_AUTH_ERROR = "useAuth must be used within <AuthProvider />";
-var MISSING_LEGACY_AUTH_ERROR = "useLegacyAuth must be used within <LegacyAuthProvider />";
-var ApiContext = react.createContext(null);
-var ApiProvider = ApiContext;
-var AuthContext = react.createContext(null);
-var AuthContextProvider = AuthContext;
-var LegacyAuthContext = react.createContext(null);
-var LegacyAuthContextProvider = LegacyAuthContext;
-var useApiClient = () => {
-  const api = react.use(ApiContext);
-  if (api === null) throw new Error(MISSING_API_CLIENT_ERROR);
-  return api;
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/context.ts
+const MISSING_API_CLIENT_ERROR = "useApiClient must be used within <ApiClientProvider />";
+const MISSING_PROJECT_ERROR = "useProject must be used within <ApiClientProvider />";
+const MISSING_STACK_ERROR = "useStack must be used within <ApiClientProvider />";
+const MISSING_AUTH_ERROR = "useAuth must be used within <AuthProvider />";
+const MISSING_LEGACY_AUTH_ERROR = "useLegacyAuth must be used within <LegacyAuthProvider />";
+const ApiContext = (0, react.createContext)(null);
+const ApiProvider = ApiContext;
+const AuthContext = (0, react.createContext)(null);
+const AuthContextProvider = AuthContext;
+const LegacyAuthContext = (0, react.createContext)(null);
+const LegacyAuthContextProvider = LegacyAuthContext;
+const useApiClient = () => {
+	const api = (0, react.use)(ApiContext);
+	if (api === null) throw new Error(MISSING_API_CLIENT_ERROR);
+	return api;
 };
-var useProject = () => {
-  const api = react.use(ApiContext);
-  if (api === null) throw new Error(MISSING_PROJECT_ERROR);
-  return api.context.project;
+const useProject = () => {
+	const api = (0, react.use)(ApiContext);
+	if (api === null) throw new Error(MISSING_PROJECT_ERROR);
+	return api.context.project;
 };
-var useStack = () => {
-  const api = react.use(ApiContext);
-  if (api === null) throw new Error(MISSING_STACK_ERROR);
-  return api.context.stack;
+const useStack = () => {
+	const api = (0, react.use)(ApiContext);
+	if (api === null) throw new Error(MISSING_STACK_ERROR);
+	return api.context.stack;
 };
-var useAuth = () => {
-  const session = react.use(AuthContext);
-  if (session === null) throw new Error(MISSING_AUTH_ERROR);
-  return session;
+/** The bearer (OAuth) lifecycle session. Throws outside `<AuthProvider />`. */
+const useAuth = () => {
+	const session = (0, react.use)(AuthContext);
+	if (session === null) throw new Error(MISSING_AUTH_ERROR);
+	return session;
 };
-var useLegacyAuth = () => {
-  const session = react.use(LegacyAuthContext);
-  if (session === null) throw new Error(MISSING_LEGACY_AUTH_ERROR);
-  return session;
+/** The legacy (SAPI) lifecycle session. Throws outside `<LegacyAuthProvider />`. */
+const useLegacyAuth = () => {
+	const session = (0, react.use)(LegacyAuthContext);
+	if (session === null) throw new Error(MISSING_LEGACY_AUTH_ERROR);
+	return session;
 };
-var ApiClientProvider = ({ api, children }) => /* @__PURE__ */ jsxRuntime.jsx(ApiProvider, { value: api, children });
-var AuthProvider = ({
-  session,
-  baseUrl,
-  credential,
-  projectId,
-  onAccessTokenChange,
-  loadingFallback = null,
-  errorFallback = null,
-  anonymousFallback = null,
-  children
-}) => {
-  const [snapshot, setSnapshot] = react.useState(() => session.debug());
-  const [isRestoring, setIsRestoring] = react.useState(() => session.hasPersistedValue());
-  const [restoreStatus, setRestoreStatus] = react.useState(null);
-  const restoreStartedRef = react.useRef(false);
-  react.useEffect(() => session.subscribe(setSnapshot), [session]);
-  react.useEffect(() => {
-    if (baseUrl === void 0) return;
-    if (snapshot.config.baseUrl !== null) return;
-    session.setBaseUrl(baseUrl);
-  }, [session, baseUrl, snapshot.config.baseUrl]);
-  react.useEffect(() => {
-    if (restoreStartedRef.current) return;
-    restoreStartedRef.current = true;
-    session.restore().then((result) => setRestoreStatus(result.status)).catch((error) => {
-      console.error("Keboola bearer session restore failed", error);
-      setRestoreStatus("empty");
-    }).finally(() => setIsRestoring(false));
-  }, [session]);
-  react.useEffect(() => {
-    if (restoreStatus === null || restoreStatus === "restored") return;
-    if (credential === void 0) return;
-    if (snapshot.config.status !== "anonymous") return;
-    session.authenticate(credential);
-  }, [session, restoreStatus, credential, snapshot.config.status]);
-  react.useEffect(() => {
-    if (restoreStatus === null || restoreStatus === "restored") return;
-    if (projectId === void 0) return;
-    if (snapshot.config.status !== "authenticated") return;
-    session.setProject(projectId);
-  }, [session, restoreStatus, projectId, snapshot.config.status]);
-  const accessToken = snapshot.config.status === "anonymous" ? void 0 : snapshot.config.credential.accessToken;
-  react.useEffect(() => {
-    if (accessToken !== void 0) onAccessTokenChange?.(accessToken);
-  }, [accessToken, onAccessTokenChange]);
-  const isProgrammatic = credential !== void 0 && projectId !== void 0;
-  const content = (() => {
-    if (snapshot.storage === "ready") {
-      if (typeof children !== "function") return children;
-      if (snapshot.config.status !== "scoped") return null;
-      const { projectId: scopedProjectId, baseUrl: scopedBaseUrl } = snapshot.config;
-      return children({ projectId: scopedProjectId, baseUrl: scopedBaseUrl });
-    }
-    if (snapshot.storage === "errored") return errorFallback;
-    if (isRestoring || snapshot.storage === "pending" || isProgrammatic) return loadingFallback;
-    return anonymousFallback;
-  })();
-  return /* @__PURE__ */ jsxRuntime.jsx(AuthContextProvider, { value: session, children: content });
+//#endregion
+//#region src/ApiClientProvider.tsx
+/**
+* Provides the product API to `useApiClient()`. A pure pass-through: the auth lifecycle (driving
+* to ready, gating on a fallback) belongs to `AuthProvider` / `LegacyAuthProvider`, which mount
+* this provider once their session is ready.
+*/
+const ApiClientProvider = ({ api, children }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ApiProvider, {
+	value: api,
+	children
+});
+//#endregion
+//#region src/AuthProvider.tsx
+const AuthProvider = ({ session, baseUrl, credential, projectId, onAccessTokenChange, loadingFallback = null, errorFallback = null, anonymousFallback = null, children }) => {
+	const [snapshot, setSnapshot] = (0, react.useState)(() => session.debug());
+	const [isRestoring, setIsRestoring] = (0, react.useState)(() => session.hasPersistedValue());
+	const [restoreStatus, setRestoreStatus] = (0, react.useState)(null);
+	const restoreStartedRef = (0, react.useRef)(false);
+	(0, react.useEffect)(() => session.subscribe(setSnapshot), [session]);
+	(0, react.useEffect)(() => {
+		if (baseUrl === void 0) return;
+		if (snapshot.config.baseUrl !== null) return;
+		session.setBaseUrl(baseUrl);
+	}, [
+		session,
+		baseUrl,
+		snapshot.config.baseUrl
+	]);
+	(0, react.useEffect)(() => {
+		if (restoreStartedRef.current) return;
+		restoreStartedRef.current = true;
+		session.restore().then((result) => setRestoreStatus(result.status)).catch((error) => {
+			console.error("Keboola bearer session restore failed", error);
+			setRestoreStatus("empty");
+		}).finally(() => setIsRestoring(false));
+	}, [session]);
+	(0, react.useEffect)(() => {
+		if (restoreStatus === null || restoreStatus === "restored") return;
+		if (credential === void 0) return;
+		if (snapshot.config.status !== "anonymous") return;
+		session.authenticate(credential);
+	}, [
+		session,
+		restoreStatus,
+		credential,
+		snapshot.config.status
+	]);
+	(0, react.useEffect)(() => {
+		if (restoreStatus === null || restoreStatus === "restored") return;
+		if (projectId === void 0) return;
+		if (snapshot.config.status !== "authenticated") return;
+		session.setProject(projectId);
+	}, [
+		session,
+		restoreStatus,
+		projectId,
+		snapshot.config.status
+	]);
+	const accessToken = snapshot.config.status === "anonymous" ? void 0 : snapshot.config.credential.accessToken;
+	(0, react.useEffect)(() => {
+		if (accessToken !== void 0) onAccessTokenChange?.(accessToken);
+	}, [accessToken, onAccessTokenChange]);
+	const isProgrammatic = credential !== void 0 && projectId !== void 0;
+	const content = (() => {
+		if (snapshot.storage === "ready") {
+			if (typeof children !== "function") return children;
+			if (snapshot.config.status !== "scoped") return null;
+			const { projectId: scopedProjectId, baseUrl: scopedBaseUrl } = snapshot.config;
+			return children({
+				projectId: scopedProjectId,
+				baseUrl: scopedBaseUrl
+			});
+		}
+		if (snapshot.storage === "errored") return errorFallback;
+		if (isRestoring || snapshot.storage === "pending" || isProgrammatic) return loadingFallback;
+		return anonymousFallback;
+	})();
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AuthContextProvider, {
+		value: session,
+		children: content
+	});
 };
-var LegacyAuthProvider = ({
-  session,
-  baseUrl,
-  storageToken,
-  managementToken,
-  fallback = null,
-  errorFallback = fallback,
-  children
-}) => {
-  const [storageState, setStorageState] = react.useState(() => session.debug().storage);
-  const startedRef = react.useRef(false);
-  react.useEffect(() => {
-    const unsubscribe = session.subscribe((snapshot) => setStorageState(snapshot.storage));
-    if (!startedRef.current) {
-      startedRef.current = true;
-      session.setBaseUrl(baseUrl);
-      if (managementToken) session.authenticateManagement(managementToken);
-      void session.authenticateStorageAsync(storageToken).catch((error) => console.error("Keboola session bootstrap failed", error));
-    }
-    return unsubscribe;
-  }, []);
-  react.useEffect(() => {
-    if (storageState === "errored") {
-      console.error("Keboola session bootstrap failed: the storage build errored.");
-    }
-  }, [storageState]);
-  const content = (() => {
-    if (storageState === "ready") return children;
-    if (storageState === "errored") return errorFallback;
-    return fallback;
-  })();
-  return /* @__PURE__ */ jsxRuntime.jsx(LegacyAuthContextProvider, { value: session, children: content });
+//#endregion
+//#region src/LegacyAuthProvider.tsx
+/**
+* Owns the legacy (SAPI) lifecycle: on mount it configures the stack and drives the session to
+* ready, rendering `fallback` until the storage build resolves. The backend-injected SAPI token is
+* known up front, so this drives itself (unlike the interactive bearer `AuthProvider`). Exposes the
+* session via `useLegacyAuth()` and gates `children` behind readiness.
+*/
+const LegacyAuthProvider = ({ session, baseUrl, storageToken, managementToken, fallback = null, errorFallback = fallback, children }) => {
+	const [storageState, setStorageState] = (0, react.useState)(() => session.debug().storage);
+	const startedRef = (0, react.useRef)(false);
+	(0, react.useEffect)(() => {
+		const unsubscribe = session.subscribe((snapshot) => setStorageState(snapshot.storage));
+		if (!startedRef.current) {
+			startedRef.current = true;
+			session.setBaseUrl(baseUrl);
+			if (managementToken) session.authenticateManagement(managementToken);
+			session.authenticateStorageAsync(storageToken).catch((error) => console.error("Keboola session bootstrap failed", error));
+		}
+		return unsubscribe;
+	}, []);
+	(0, react.useEffect)(() => {
+		if (storageState === "errored") console.error("Keboola session bootstrap failed: the storage build errored.");
+	}, [storageState]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LegacyAuthContextProvider, {
+		value: session,
+		children: (() => {
+			if (storageState === "ready") return children;
+			if (storageState === "errored") return errorFallback;
+			return fallback;
+		})()
+	});
 };
-
+//#endregion
 exports.ApiClientProvider = ApiClientProvider;
 exports.AuthProvider = AuthProvider;
 exports.LegacyAuthProvider = LegacyAuthProvider;
@@ -142,5 +164,5 @@ exports.useAuth = useAuth;
 exports.useLegacyAuth = useLegacyAuth;
 exports.useProject = useProject;
 exports.useStack = useStack;
-//# sourceMappingURL=index.cjs.map
+
 //# sourceMappingURL=index.cjs.map