@keboola/api-client 31.0.0 → 33.0.0

package/dist/index.js

@@ -1,53 +1,51 @@
 import { t as createProject } from "./project-DWwZv66D.js";
-import { a as poller, c as Result, d as delay, i as poll, l as asError, n as emitter, o as clamp, r as failureOf, s as finiteOr, t as jobStatus, u as lazy } from "./jobStatus-DbMupQEK.js";
-import { n as collect, t as createQueueClient } from "./queue-DpZTm7U7.js";
+import { a as poller, c as Result, d as delay, i as poll, l as asError, n as emitter, o as clamp, r as failureOf, s as finiteOr, t as jobStatus, u as lazy } from "./jobStatus-PSZJMTiA.js";
+import { n as collect, t as createQueueClient } from "./queue-DrLUbk98.js";
 import { t as concurrent } from "./concurrent-CH9fbNr3.js";
 import { t as dedupe } from "./dedupe-DYIHgZoG.js";
-import { a as shallowEqual, i as createStore, n as createDerivedStore, r as createEmitter, t as createDerivedAsyncStore } from "./createStore-BNiCRQXa.js";
-import { a as series, i as ServiceUnavailableError, t as createStorageClient } from "./storage-CQxu0EY3.js";
+import { n as createEmitter, t as createStore } from "./store-C9FQCHGe.js";
+import { a as series, i as ServiceUnavailableError, t as createStorageClient } from "./storage--cVaecFq.js";
 import { n as keboolaUID, t as createTagSdk } from "./tag-DCsoewjL.js";
 import { t as generateUUID } from "./generateUUID-Dr8l-aoc.js";
 import { t as isPlainObject } from "./isPlainObject-LYW-03uB.js";
-import { n as schemaGuidedMerge, r as isEmptyDeep, t as createConfigurationSdk } from "./configurations-Byt59bIa.js";
+import { n as schemaGuidedMerge, r as isEmptyDeep, t as createConfigurationSdk } from "./configurations-ZwBXilW-.js";
 import { t as UserError } from "./UserError-By_Zckmc.js";
-import { a as HttpContentType, f as HttpStatus, i as isFetchClientError, l as normalizeBaseUrl, m as ApiError, n as isAbortError, o as HttpHeader, p as KeboolaHttpHeader, r as isApiError } from "./createFetchClient-B1h3-p65.js";
-import { n as HtmlResponseError, r as isHtmlResponseError } from "./validateConnectionStatus-CBhXmvWC.js";
-import { t as ManagementClientAuthError } from "./ManagementClientAuthError-90pvsej0.js";
+import { a as isTimeoutError, h as ApiError, i as isFetchClientError, m as KeboolaHttpHeader, n as isAbortError, o as HttpContentType, p as HttpStatus, r as isApiError, s as HttpHeader, u as normalizeBaseUrl } from "./createFetchClient-DdyZMhxO.js";
+import { n as HtmlResponseError, r as isHtmlResponseError } from "./validateConnectionStatus-DhkWg6Eq.js";
+import { t as ManagementClientAuthError } from "./ManagementClientAuthError-iKbBugKC.js";
 import { i as isQueryJobError, n as isQueryJobTimeoutError, r as QueryJobError, t as QueryJobTimeoutError } from "./QueryJobTimeoutError-C7JbNGOM.js";
 import { n as isSyncActionError, t as SyncActionError } from "./SyncActionError-CoZFsdUk.js";
 import { n as isValidationError, r as parseOrThrow, t as ValidationError } from "./ValidationError-CzPWydEb.js";
-import { t as createGenericFetchClient } from "./createGenericFetchClient-DhpvUSlX.js";
-import { t as createImportClient } from "./import-CExRbskw.js";
-import { t as createOpenapiFetchClient } from "./createOpenapiFetchClient-0_oqhdPv.js";
-import { t as createAuthClient } from "./authClient-XBAUz9g-.js";
-import { n as isManagementClientAuthError, t as createManagementClient } from "./management-Cc8mKfnf.js";
-import { t as createAuthHeaders } from "./auth-CE6Hlc9W.js";
-import { o as ProjectFeature } from "./constants-qeWGfk_7.js";
+import { t as createGenericFetchClient } from "./createGenericFetchClient-MQeLRiNW.js";
+import { t as createImportClient } from "./import-2nqxQ9Rt.js";
+import { t as createAuthClient } from "./authClient-DEyqR7GW.js";
+import { n as isManagementClientAuthError, t as createManagementClient } from "./management-DNEKhR6a.js";
+import { s as ProjectFeature } from "./constants-ByEwVtGf.js";
 import { t as createStorageTable } from "./storageTable-DslXtqNL.js";
 import { createSemanticLayerSdk } from "./sdk/semanticLayer/index.js";
 import { createStorageSdk } from "./sdk/storage/index.js";
 import { createVaultSdk } from "./sdk/vault/index.js";
 import { createAiClient } from "./ai/index.js";
-import { t as parseLogLines } from "./appLogs-CLHhkQJn.js";
+import { t as parseLogLines } from "./appLogs-D72eD8vP.js";
 import { createAppsClient } from "./apps/index.js";
 import { createChatClient } from "./chat/index.js";
-import { t as createDataScienceClient } from "./dataScience-jdbSSPYF.js";
+import { t as createDataScienceClient } from "./dataScience-B_TA7wCB.js";
 import { createEditorClient } from "./editor/index.js";
 import { createEncryptionClient } from "./encryption/index.js";
-import { t as createMetastoreClient } from "./metastore-CNf1412Z.js";
+import { t as createKaiAgentClient } from "./kaiAgent-CYYn0QJW.js";
+import { t as createMetastoreClient } from "./metastore-CjwktHvw.js";
 import { createNotificationsClient } from "./notifications/index.js";
-import { t as createOauthClient } from "./oauth-ClksaYRY.js";
+import { t as createOauthClient } from "./oauth-Bg5zro5S.js";
 import { createOmnisearchClient } from "./omnisearch/index.js";
-import { t as createQueryServiceClient } from "./queryService-BlyAcBxP.js";
+import { t as createQueryServiceClient } from "./queryService-DX6zeAs_.js";
 import { createSchedulerClient } from "./scheduler/index.js";
 import { createStreamClient } from "./stream/index.js";
-import { t as createSyncActionsClient } from "./syncActions-AgFiMjRS.js";
-import { t as createTelemetryClient } from "./telemetry-CPiGWpLi.js";
+import { t as createSyncActionsClient } from "./syncActions-CkMHM-jB.js";
+import { t as createTelemetryClient } from "./telemetry-Ca6j0i9w.js";
 import { createVaultClient } from "./vault/index.js";
-import { n as isUnauthorized, t as createBearerCredential } from "./credential-dKxArMic.js";
+import { n as isUnauthorized, t as createBearerCredential } from "./credential-Bxv7yxOZ.js";
 import { createQueryServiceSdk } from "./sdk/queryService/index.js";
 import * as z$1 from "zod";
-import { z } from "zod";
 //#region src/utils/assert.ts
 function assert(value, message) {
 	if (value == null) throw new Error(message);
@@ -93,6 +91,111 @@ const coalesce = (task) => {
 	};
 };
 //#endregion
+//#region src/utils/store/derivedStore.ts
+const isPlainObjectOrArray = (value) => {
+	if (Array.isArray(value)) return true;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+};
+const shallowEqual = (a, b) => {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+	if (!isPlainObjectOrArray(a) || !isPlainObjectOrArray(b)) return false;
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	return aKeys.length === bKeys.length && aKeys.every((key) => Object.is(a[key], b[key]));
+};
+const createDerivedStore = ({ source, dependsOn, build, keyEquals = shallowEqual }) => {
+	let key = dependsOn(source.get());
+	const store = createStore(build(key));
+	const unsubscribe = source.subscribe((state) => {
+		const next = dependsOn(state);
+		if (keyEquals(key, next)) return;
+		key = next;
+		store.set(build(next));
+	});
+	const get = store.get;
+	const subscribe = store.subscribe;
+	const dispose = () => {
+		unsubscribe();
+		store.dispose();
+	};
+	return {
+		get,
+		subscribe,
+		dispose
+	};
+};
+//#endregion
+//#region src/utils/store/derivedAsyncStore.ts
+const createDerivedAsyncStore = ({ source, dependsOn, build, keyEquals = shallowEqual }) => {
+	const store = createStore({ state: "idle" });
+	let currentKey = null;
+	let generation = 0;
+	let controller = null;
+	const run = (key) => {
+		controller?.abort();
+		controller = new AbortController();
+		const runGeneration = ++generation;
+		store.set({ state: "pending" });
+		build(key, controller.signal).then((value) => {
+			if (runGeneration === generation) store.set({
+				state: "ready",
+				value
+			});
+		}, (error) => {
+			if (runGeneration === generation) store.set({
+				state: "errored",
+				error
+			});
+		});
+	};
+	const sync = (state) => {
+		const next = dependsOn(state);
+		if (next === null) {
+			if (currentKey === null) return;
+			controller?.abort();
+			controller = null;
+			generation += 1;
+			currentKey = null;
+			store.set({ state: "idle" });
+			return;
+		}
+		if (currentKey !== null && keyEquals(currentKey, next)) return;
+		currentKey = next;
+		run(next);
+	};
+	sync(source.get());
+	const unsubscribe = source.subscribe(sync);
+	const get = store.get;
+	const subscribe = store.subscribe;
+	const dispose = () => {
+		controller?.abort();
+		unsubscribe();
+		store.dispose();
+	};
+	const readable = {
+		get,
+		subscribe,
+		dispose
+	};
+	const settled = () => new Promise((resolve) => {
+		let unsubscribeSettled = () => {};
+		const check = (state) => {
+			if (state.state === "ready" || state.state === "errored") {
+				unsubscribeSettled();
+				resolve(state);
+			}
+		};
+		unsubscribeSettled = store.subscribe(check);
+		check(store.get());
+	});
+	return {
+		store: readable,
+		settled
+	};
+};
+//#endregion
 //#region src/utils/async/poll/registry.ts
 const DEFAULT_LIMIT = 50;
 const isFinished = ({ snapshot }) => snapshot.state !== "idle" && snapshot.state !== "polling";
@@ -603,6 +706,7 @@ const stamp = (tokens) => ({
 const createConfig$1 = (initial = INITIAL) => {
 	const store = createStore(initial);
 	let expiredNotified = false;
+	let epoch = 0;
 	const setBaseUrl = (baseUrl) => {
 		if (store.get().status !== "anonymous") throw new KeboolaError(KeboolaErrorType.AlreadyAuthenticated);
 		store.set({
@@ -615,6 +719,7 @@ const createConfig$1 = (initial = INITIAL) => {
 		if (state.status !== "anonymous") throw new KeboolaError(KeboolaErrorType.AlreadyAuthenticated);
 		if (!state.baseUrl) throw new KeboolaError(KeboolaErrorType.Unconfigured);
 		expiredNotified = false;
+		epoch += 1;
 		store.set({
 			status: "authenticated",
 			baseUrl: state.baseUrl,
@@ -648,6 +753,7 @@ const createConfig$1 = (initial = INITIAL) => {
 	};
 	/** Drop the credential (sign out); keeps the configured baseUrl. */
 	const reset = () => {
+		epoch += 1;
 		store.set({
 			status: "anonymous",
 			baseUrl: store.get().baseUrl
@@ -689,6 +795,15 @@ const createConfig$1 = (initial = INITIAL) => {
 	};
 	const getBaseUrl = () => store.get().baseUrl;
 	/**
+	* Which sign-in this is — a counter, bumped by `authenticate` and `reset`.
+	*
+	* - For anything long-lived that must not outlive the credential it was built against: capture it,
+	*   compare it later. A rotation does not move it; only a new session or a sign-out does.
+	* - Distinct from `notifyExpired`'s latch, which answers "report this death once" rather than
+	*   "which session are we in".
+	*/
+	const getEpoch = () => epoch;
+	/**
 	* Session-expiry latch (fire-once):
 	* - why: concurrent 401s all report expiry, but the app must sign out once; and the credential /
 	*   auth middleware are long-lived singletons, so the latch can't live in them — it must reset
@@ -717,6 +832,7 @@ const createConfig$1 = (initial = INITIAL) => {
 		forceExpire,
 		requireCredential,
 		getBaseUrl,
+		getEpoch,
 		notifyExpired,
 		debug
 	};
@@ -857,216 +973,6 @@ const createVariablesSdk = ({ storageClient }) => {
 	};
 };
 //#endregion
-//#region src/clients/kaiAgent/kaiAgentClient.ts
-const agentSettingsSchema = z.object({
-	projectId: z.string(),
-	customInstructions: z.string().nullable(),
-	createdAt: z.string(),
-	updatedAt: z.string()
-});
-const toolPermissionValueSchema = z.enum([
-	"always_allow",
-	"always_ask",
-	"blocked"
-]);
-const userAgentSettingsSchema = z.object({
-	projectId: z.string(),
-	userId: z.string(),
-	customInstructions: z.string().nullable(),
-	toolPermissions: z.record(z.string(), toolPermissionValueSchema).nullable(),
-	createdAt: z.string(),
-	updatedAt: z.string()
-});
-const toolInfoSchema = z.object({
-	name: z.string(),
-	description: z.string(),
-	readOnly: z.boolean()
-});
-const toolsListResponseSchema = z.object({ tools: z.array(toolInfoSchema) });
-const skillInfoSchema = z.object({
-	name: z.string(),
-	description: z.string().nullable(),
-	source: z.enum([
-		"first-party",
-		"vendored",
-		"project"
-	])
-});
-const builtInCommandSchema = z.object({
-	name: z.string(),
-	description: z.string()
-});
-const skillsListResponseSchema = z.object({
-	skills: z.array(skillInfoSchema),
-	commands: z.array(builtInCommandSchema)
-});
-const sandboxFileEntrySchema = z.object({
-	name: z.string(),
-	path: z.string(),
-	type: z.enum(["file", "dir"]),
-	size: z.number().int().nonnegative().optional()
-});
-const sandboxFileListingSchema = z.object({ entries: z.array(sandboxFileEntrySchema) });
-const sandboxFileContentSchema = z.object({
-	content: z.string(),
-	encoding: z.enum(["utf-8", "binary"]),
-	truncated: z.boolean(),
-	size: z.number().int().nonnegative()
-});
-const sandboxGitBranchSchema = z.object({ branch: z.string().nullable() });
-const votesResponseSchema = z.array(z.object({
-	chatId: z.string(),
-	messageId: z.string(),
-	isUpvoted: z.boolean()
-}));
-const createKaiAgentClient = ({ baseUrl, middlewares, auth }) => {
-	const clientOptions = {
-		baseUrl,
-		middlewares,
-		headers: createAuthHeaders(auth)
-	};
-	const client = createOpenapiFetchClient(clientOptions);
-	const genericClient = createGenericFetchClient(clientOptions);
-	const getHistory = async (params) => {
-		const { data } = await client.get("/api/history", { query: params });
-		return data;
-	};
-	const getChat = async (chatId, signal) => {
-		const { data } = await client.get("/api/chat/{id}", { path: { id: chatId } }, { signal });
-		return data;
-	};
-	const deleteChat = async (chatId) => {
-		const { data } = await client.delete("/api/chat", { query: { id: chatId } });
-		return data;
-	};
-	const createChat = async (request) => {
-		const { response } = await client.post("/api/chat", { body: request });
-		return response;
-	};
-	const getVotes = async (chatId) => {
-		const { data } = await client.get("/api/vote", { query: { chatId } });
-		const result = votesResponseSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid votes response format");
-		return result.data;
-	};
-	const submitVote = async (params) => {
-		await client.patch("/api/vote", { body: params });
-	};
-	const getUsage = async (signal) => {
-		const { data } = await client.get("/api/usage", {}, { signal });
-		return data;
-	};
-	const approveToolCall = async (chatId, body) => {
-		await client.post("/api/chat/{id}/approval", {
-			path: { id: chatId },
-			body
-		});
-	};
-	const submitToolOutput = async (chatId, body) => {
-		await client.post("/api/chat/{id}/ui-tool-result", {
-			path: { id: chatId },
-			body
-		});
-	};
-	const stopChat = async (chatId) => {
-		const { data } = await client.post("/api/chat/{id}/stop", { path: { id: chatId } });
-		return data;
-	};
-	const getSuggestions = async (request, signal) => {
-		const { data } = await client.post("/api/suggestions", { body: request }, { signal });
-		return data;
-	};
-	const getAgentSettings = async (signal) => {
-		const { data } = await genericClient.get("/api/settings", {}, { signal });
-		const result = agentSettingsSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid agent settings response format");
-		return result.data;
-	};
-	const updateAgentSettings = async (request, signal) => {
-		const { data } = await genericClient.patch("/api/settings", { body: request }, { signal });
-		const result = agentSettingsSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid agent settings response format");
-		return result.data;
-	};
-	const getUserAgentSettings = async (signal) => {
-		const { data } = await genericClient.get("/api/settings/user", {}, { signal });
-		const result = userAgentSettingsSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid user agent settings response format");
-		return result.data;
-	};
-	const updateUserAgentSettings = async (request, signal) => {
-		const { data } = await genericClient.patch("/api/settings/user", { body: request }, { signal });
-		const result = userAgentSettingsSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid user agent settings response format");
-		return result.data;
-	};
-	const getToolsList = async (signal) => {
-		const { data } = await genericClient.get("/api/settings/tools", {}, { signal });
-		const result = toolsListResponseSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid tools list response format");
-		return result.data;
-	};
-	const getSkillsList = async (signal) => {
-		const { data } = await genericClient.get("/api/skills", {}, { signal });
-		const result = skillsListResponseSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid skills list response format");
-		return result.data;
-	};
-	const listSandboxFiles = async (chatId, path, signal) => {
-		const { data } = await genericClient.get(`/api/chat/${encodeURIComponent(chatId)}/sandbox/files`, { query: path ? { path } : void 0 }, { signal });
-		const result = sandboxFileListingSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid sandbox files response format");
-		return result.data;
-	};
-	const readSandboxFile = async (chatId, path, signal) => {
-		const { data } = await genericClient.get(`/api/chat/${encodeURIComponent(chatId)}/sandbox/file`, { query: { path } }, { signal });
-		const result = sandboxFileContentSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid sandbox file response format");
-		return result.data;
-	};
-	const downloadSandboxFile = async (chatId, path, signal) => {
-		const { data } = await genericClient.get(`/api/chat/${encodeURIComponent(chatId)}/sandbox/file/download`, { query: { path } }, { signal });
-		if (!(data instanceof Blob)) throw new Error("Invalid sandbox file download response format");
-		return data;
-	};
-	const getSandboxGitBranch = async (chatId, signal) => {
-		const { data } = await genericClient.get(`/api/chat/${encodeURIComponent(chatId)}/sandbox/git-branch`, {}, { signal });
-		const result = sandboxGitBranchSchema.safeParse(data);
-		if (!result.success) throw new Error("Invalid sandbox git-branch response format");
-		return result.data;
-	};
-	const chatStreamUrl = clientOptions.baseUrl + "/api/chat";
-	const healthCheck = async (signal) => {
-		const { data } = await genericClient.get("/health", {}, { signal });
-		return data;
-	};
-	return {
-		healthCheck,
-		getHistory,
-		getChat,
-		deleteChat,
-		createChat,
-		getVotes,
-		submitVote,
-		getUsage,
-		approveToolCall,
-		submitToolOutput,
-		stopChat,
-		getSuggestions,
-		getAgentSettings,
-		updateAgentSettings,
-		getUserAgentSettings,
-		updateUserAgentSettings,
-		getToolsList,
-		getSkillsList,
-		listSandboxFiles,
-		readSandboxFile,
-		downloadSandboxFile,
-		getSandboxGitBranch,
-		chatStreamUrl
-	};
-};
-//#endregion
 //#region src/keboola/createServiceClients.ts
 const createServiceClients = ({ baseUrl, auth, getServiceBaseUrl, middlewareFor, attachTokenMiddleware }) => createServiceClientRegistry()({
 	getServiceBaseUrl,
@@ -1397,7 +1303,12 @@ const createKeboola = (options = {}) => {
 	const refresh = async () => {
 		const client = authClientBare.get();
 		assert$1(client, KeboolaErrorType.NotReady);
-		const refreshed = await client.token.refresh(config.requireCredential().refreshToken);
+		const epoch = config.getEpoch();
+		const refreshed = await client.token.refresh(config.requireCredential().refreshToken).catch((error) => {
+			if (config.getEpoch() !== epoch) throw new KeboolaError(KeboolaErrorType.NotAuthenticated);
+			throw error;
+		});
+		if (config.getEpoch() !== epoch) throw new KeboolaError(KeboolaErrorType.NotAuthenticated);
 		config.applyRefresh(refreshed);
 		return refreshed.accessToken;
 	};
@@ -1413,8 +1324,36 @@ const createKeboola = (options = {}) => {
 			}
 		};
 	};
+	/**
+	* The project this session is scoped to, right now.
+	*
+	* - Read at every point that stamps a project, never snapshotted across an `await`: the scope moves
+	*   with `setProject`/`clearProject`, and neither ends the session, so it is not in the epoch and
+	*   `assertSameSession` cannot see it change.
+	* - `NotReady` rather than `NotAuthenticated` when merely unscoped — the credential is fine, the
+	*   project is what is missing. A credential alone does not authorize a project request: kai-agent
+	*   reads the project from the header, not the token, and cannot attribute a call that omits it.
+	*/
+	const requireScopedProject = () => {
+		const state = config.store.get();
+		if (state.status === "anonymous") throw new KeboolaError(KeboolaErrorType.NotAuthenticated);
+		if (state.status !== "scoped") throw new KeboolaError(KeboolaErrorType.NotReady);
+		return state.projectId;
+	};
+	/**
+	* The project client sets `forProject` has handed out, keyed by project id.
+	*
+	* - Not keyed by stack: `setBaseUrl` throws once authenticated and `signOut` empties this, so one
+	*   entry can never belong to a different `baseUrl` than the live session.
+	* - A `lazy` per key, not a bare promise: concurrent callers share one bootstrap, later ones replay
+	*   the resolved set, and a rejected build clears only its own slot — so a build orphaned by a
+	*   sign-out cannot evict the entry that replaced it.
+	*/
+	const extraProjects = /* @__PURE__ */ new Map();
 	const signOut = () => {
 		config.reset();
+		credential.abandonRefresh();
+		extraProjects.clear();
 		persistor.clear();
 	};
 	const onSessionExpired = () => {
@@ -1425,13 +1364,75 @@ const createKeboola = (options = {}) => {
 		getToken,
 		onSessionExpired
 	});
-	const authMiddleware = createBearerAuthMiddleware(credential);
+	const sessionGuard = (epoch) => () => {
+		if (config.getEpoch() !== epoch) throw new KeboolaError(KeboolaErrorType.NotAuthenticated);
+	};
+	/**
+	* The auth middleware, refusing to carry a request across a change of session.
+	*
+	* - The middleware holds no token — it reads the credential live — so anything built on it acts as
+	*   whoever is signed in *at request time*, not whoever built it. Rebuilding a store on sign-out
+	*   only stops new reads; a request already in flight completes as the next user, still stamped
+	*   with the old project. `config`'s epoch moves on `authenticate` and `reset` and never on a
+	*   rotation, so it is exactly "which sign-in is this".
+	* - `epochFor` says which sign-in a request answers to, resolved per request:
+	*   1. a client set pins to the sign-in that *built* it (`pinToSession`) — a set the caller still
+	*      holds must not ride the session that replaced it;
+	*   2. `api.auth` pins to the sign-in the request *started* on, because its store is keyed on
+	*      `baseUrl` alone: it is built once, while anonymous, so a build-time pin would freeze at that
+	*      epoch and refuse every authenticated call.
+	* - The guard covers every credential read, not only the wire request, so it wraps the credential
+	*   rather than sitting beside it. The 401 path rotates the token by calling the credential
+	*   directly: a straggler from a dead session would otherwise spend the *live* session's
+	*   single-use refresh token, and sign that session out if the rotation itself came back 401.
+	* - `expiresSession` decides whether a 401 that survives a rotation means the session is dead.
+	*   True for this session's own realms; false where the 401 may be about the project instead of
+	*   the credential (see `forProject`).
+	* - `inner` is for middleware that **re-invokes `next`** — a retry. Composed outside the pin it
+	*   would re-enter it per attempt, and with a per-request `epochFor` each attempt would re-pin to
+	*   whoever is signed in by then: a 503 backoff is exactly long enough for a sign-out to land, and
+	*   the retry then goes out as the next user. Inside, one epoch covers every attempt and each
+	*   attempt still passes the guard. Anything new that retries belongs here, not in the array.
+	*/
+	const createPinnedAuthMiddleware = (epochFor, { expiresSession = true, inner = [] } = {}) => {
+		return (next) => (request) => {
+			const assertSameSession = sessionGuard(epochFor());
+			const pinnedCredential = {
+				...credential,
+				getAccessToken: async (options) => {
+					assertSameSession();
+					return credential.getAccessToken(options);
+				},
+				notifyExpired: expiresSession ? credential.notifyExpired : () => {}
+			};
+			const guarded = (wire) => (repeated) => {
+				assertSameSession();
+				return wire(repeated);
+			};
+			const chain = inner.reduceRight((acc, middleware) => middleware(acc), guarded(next));
+			return createBearerAuthMiddleware(pinnedCredential)(chain)(request);
+		};
+	};
+	/**
+	* Pin something long-lived to the sign-in live right now.
+	*
+	* - `assertSameSession` is for whatever no middleware chain covers: a bootstrap whose every
+	*   request passed the guard before the sign-out resolves anyway and must not be handed back, and
+	*   `getAuthHeaders`, which emits the credential by hand.
+	*/
+	const pinToSession = (options) => {
+		const epoch = config.getEpoch();
+		return {
+			assertSameSession: sessionGuard(epoch),
+			pinnedAuthMiddleware: createPinnedAuthMiddleware(() => epoch, options)
+		};
+	};
 	const authClient = createDerivedStore({
 		source: config.store,
 		dependsOn: (state) => state.baseUrl,
 		build: (baseUrl) => baseUrl ? createAuthClient({
 			baseUrl,
-			middlewares: middlewareFor("auth", [retryContention, authMiddleware])
+			middlewares: middlewareFor("auth", [createPinnedAuthMiddleware(config.getEpoch, { inner: [retryContention] })])
 		}) : null
 	});
 	const management = createDerivedStore({
@@ -1443,7 +1444,7 @@ const createKeboola = (options = {}) => {
 				type: "bearer",
 				token: ""
 			},
-			middlewares: middlewareFor("management", [authMiddleware])
+			middlewares: middlewareFor("management", [pinToSession().pinnedAuthMiddleware])
 		}) : null
 	});
 	const projectClientsAsync = createDerivedAsyncStore({
@@ -1455,13 +1456,33 @@ const createKeboola = (options = {}) => {
 		build: ({ baseUrl, projectId }) => {
 			return createProjectClients$1({
 				baseUrl,
-				authMiddleware,
+				authMiddleware: pinToSession().pinnedAuthMiddleware,
 				projectId,
 				middlewareFor,
 				clientServiceUrls: options.clientServiceUrls
 			});
 		}
 	});
+	const forProject = async (projectId) => {
+		const state = config.store.get();
+		if (state.status === "anonymous") throw new KeboolaError(KeboolaErrorType.NotAuthenticated);
+		const cached = extraProjects.get(projectId);
+		if (cached) return cached();
+		const { assertSameSession, pinnedAuthMiddleware } = pinToSession({ expiresSession: false });
+		const build = lazy(async () => {
+			const clients = await createProjectClients$1({
+				baseUrl: state.baseUrl,
+				authMiddleware: pinnedAuthMiddleware,
+				projectId,
+				middlewareFor,
+				clientServiceUrls: options.clientServiceUrls
+			});
+			assertSameSession();
+			return clients;
+		});
+		extraProjects.set(projectId, build);
+		return build();
+	};
 	if (options.baseUrl) config.setBaseUrl(options.baseUrl);
 	config.store.subscribe((state) => {
 		if (state.status === "anonymous") return;
@@ -1495,6 +1516,19 @@ const createKeboola = (options = {}) => {
 		* re-entering the project. Use `reset` to sign out instead.
 		*/
 		clearProject: config.clearProjectId,
+		/**
+		* The clients for one project, off this session — for reaching a second project without leaving
+		* the first.
+		*
+		* - `setProjectAsync` *moves* the session (and `api`) to another project; this *adds* one. The
+		*   returned set is the caller's to hold and never appears on `api`.
+		* - Every set shares this session's auth middleware, so one rotation serves all of them. A second
+		*   `createKeboola()` does not: both hold the same single-use refresh token, and the first to
+		*   rotate invalidates the other's, whose next refresh 401s and signs it out.
+		* - Independent of the scope, including for the scoped project itself — asking for that one
+		*   builds a second set with its own `liveProject`, so prefer `api.*` there.
+		*/
+		forProject,
 		reset: signOut,
 		/**
 		* Dev/test only: mark the current access token as expired so the bearer credential rotates it on
@@ -1502,6 +1536,35 @@ const createKeboola = (options = {}) => {
 		* the rotation immediately and observe the new credential.
 		*/
 		debugForceRefresh: config.forceExpire,
+		/**
+		* The headers that authorize one off-client request, resolved fresh each call.
+		*
+		* - For a transport this package does not own — the chat SSE stream, whose `fetch` the AI SDK
+		*   holds. Anything with a service client on `api` should use that instead.
+		* - Returns the assembled bag, never the bare token: no caller handles the credential as a
+		*   string, and `X-KBC-ProjectId` is composed here rather than in every consuming app.
+		* - Resolved per call, through the credential — so a near-expiry token rotates and a revoked
+		*   one is never re-sent. A snapshot held by the caller would do neither.
+		* - Throws rather than emitting a half-formed `Bearer null`: an unauthenticated or unscoped
+		*   session has nothing to authorize with.
+		* - Pinned to the sign-in it was called on, like every client here. This is the one
+		*   credential-emitting surface with no middleware chain for the guard to sit in, so the check
+		*   is written out around the `await` that rotates the token.
+		* - The scope is re-read after that `await`, not carried across it. The epoch the pin compares
+		*   moves on a sign-in and a sign-out only, so a project switch mid-rotation is invisible to it.
+		*/
+		getAuthHeaders: async () => {
+			const { assertSameSession } = pinToSession();
+			requireScopedProject();
+			const accessToken = await credential.getAccessToken();
+			assertSameSession();
+			const projectId = requireScopedProject();
+			assert$1(accessToken, KeboolaErrorType.NotAuthenticated);
+			return {
+				[HttpHeader.AUTHORIZATION]: `Bearer ${accessToken}`,
+				[KeboolaHttpHeader.PROJECT_ID]: String(projectId)
+			};
+		},
 		restore: async () => {
 			const persisted = persistor.hydrate();
 			if (!persisted.refreshToken || !persisted.baseUrl) return { status: "empty" };
@@ -1513,8 +1576,10 @@ const createKeboola = (options = {}) => {
 			if (!configured) config.setBaseUrl(persisted.baseUrl);
 			const client = authClientBare.get();
 			assert$1(client, KeboolaErrorType.NotReady);
+			const startedOn = config.getEpoch();
 			try {
 				const refreshed = await client.token.refresh(persisted.refreshToken);
+				if (config.getEpoch() !== startedOn) return { status: "empty" };
 				config.authenticate(refreshed);
 				if (persisted.projectId !== null) {
 					config.setProjectId(persisted.projectId);
@@ -1522,6 +1587,7 @@ const createKeboola = (options = {}) => {
 				}
 				return { status: "restored" };
 			} catch (err) {
+				if (config.getEpoch() !== startedOn) return { status: "empty" };
 				if (isUnauthorized(err)) {
 					persistor.clear();
 					return { status: "expired" };
@@ -1758,6 +1824,6 @@ const createLegacyKeboola = (options = {}) => {
 	};
 };
 //#endregion
-export { ApiError, HtmlResponseError, HttpContentType, HttpHeader, KeboolaError, KeboolaErrorType, KeboolaHttpHeader, ManagementClientAuthError, QueryJobError, QueryJobTimeoutError, Result, ServiceUnavailableError, SyncActionError, UserError, ValidationError, asError, assert, coalesce, collect, concurrent, createDerivedAsyncStore, createDerivedStore, createEmitter, createGenericFetchClient, createKeboola, createLegacyKeboola, createLocalStorage, createLoggingMiddleware, createMemoryStorage, createNullStorage, createPersistor, createPollRegistry, createQueryServiceSdk, createRetryMiddleware, createSessionStorage, createStorageSdk, createStore, dedupe, deepMerge, delay, emitter, failureOf, generateUUID, isAbortError, isApiError, isEmptyDeep, isFetchClientError, isHtmlResponseError, isKeboolaError, isManagementClientAuthError, isPlainObject, isQueryJobError, isQueryJobTimeoutError, isStorageTokenMutatingRequest, isSyncActionError, isValidationError, jobStatus, keboolaUID, lazy, parseLogLines, parseOrThrow, poll, poller, schemaGuidedMerge, series, shallowEqual };
+export { ApiError, HtmlResponseError, HttpContentType, HttpHeader, KeboolaError, KeboolaErrorType, KeboolaHttpHeader, ManagementClientAuthError, QueryJobError, QueryJobTimeoutError, Result, ServiceUnavailableError, SyncActionError, UserError, ValidationError, asError, assert, coalesce, collect, concurrent, createDerivedAsyncStore, createDerivedStore, createEmitter, createGenericFetchClient, createKeboola, createLegacyKeboola, createLocalStorage, createLoggingMiddleware, createMemoryStorage, createNullStorage, createPersistor, createPollRegistry, createQueryServiceSdk, createRetryMiddleware, createSessionStorage, createStorageSdk, createStore, dedupe, deepMerge, delay, emitter, failureOf, generateUUID, isAbortError, isApiError, isEmptyDeep, isFetchClientError, isHtmlResponseError, isKeboolaError, isManagementClientAuthError, isPlainObject, isQueryJobError, isQueryJobTimeoutError, isStorageTokenMutatingRequest, isSyncActionError, isTimeoutError, isValidationError, jobStatus, keboolaUID, lazy, parseLogLines, parseOrThrow, poll, poller, schemaGuidedMerge, series, shallowEqual };
 
 //# sourceMappingURL=index.js.map