@keboola/api-client 47.0.0 → 48.0.0

package/dist/index.cjs

@@ -7,11 +7,11 @@ const require_concurrent = require("./concurrent-CdVfR1N5.cjs");
 const require_dedupe = require("./dedupe-OSnnst2u.cjs");
 const require_transientRetries = require("./transientRetries-DdJfH9QK.cjs");
 const require_store = require("./store-xS-Cu_VS.cjs");
-const require_storage = require("./storage-yovv11k6.cjs");
+const require_storage = require("./storage-CVBXivpB.cjs");
 const require_tag = require("./tag-DHS_soa7.cjs");
 const require_generateUUID = require("./generateUUID-C6qKBPIv.cjs");
 const require_isPlainObject = require("./isPlainObject-BB3iy87C.cjs");
-const require_configurations = require("./configurations-D_Rbs0Wl.cjs");
+const require_configurations = require("./configurations-B2O8AAy0.cjs");
 const require_UserError = require("./UserError-CSGO1qII.cjs");
 const require_createFetchClient = require("./createFetchClient-lZ_93Yrb.cjs");
 const require_validateConnectionStatus = require("./validateConnectionStatus-BalWEyRk.cjs");
@@ -22,7 +22,7 @@ const require_SyncActionError = require("./SyncActionError-BG0zwchi.cjs");
 const require_ValidationError = require("./ValidationError-D65QU0uq.cjs");
 const require_createGenericFetchClient = require("./createGenericFetchClient-MOx97wi-.cjs");
 const require_import = require("./import-BahNYv91.cjs");
-const require_management = require("./management-BUGPJ1Bu.cjs");
+const require_management = require("./management-CXHnxVaZ.cjs");
 const require_constants = require("./constants-a0jswUeK.cjs");
 const require_storageTable = require("./storageTable-BNOR2FCh.cjs");
 const require_kaiMemory = require("./kaiMemory-Qch09f-m.cjs");
@@ -37,7 +37,7 @@ const require_componentsMcp = require("./componentsMcp-pG-PcQrg.cjs");
 const require_dataScience = require("./dataScience-BjS1p8WO.cjs");
 const require_editor_index = require("./editor/index.cjs");
 const require_encryption_index = require("./encryption/index.cjs");
-const require_kaiAgent = require("./kaiAgent-BmfUG8bB.cjs");
+const require_kaiAgent = require("./kaiAgent-N2qbUFZm.cjs");
 const require_metastore = require("./metastore-BXHg33ku.cjs");
 const require_notifications_index = require("./notifications/index.cjs");
 const require_oauth = require("./oauth-DKZPuUlt.cjs");
@@ -49,7 +49,7 @@ const require_stream_index = require("./stream/index.cjs");
 const require_syncActions = require("./syncActions-C1rE4R3f.cjs");
 const require_telemetry_index = require("./telemetry/index.cjs");
 const require_vault_index = require("./vault/index.cjs");
-const require_middleware = require("./middleware-DU_5pFDW.cjs");
+const require_middleware = require("./middleware-CEP6uu_D.cjs");
 const require_sdk_queryService_index = require("./sdk/queryService/index.cjs");
 let zod = require("zod");
 zod = require_rolldown_runtime.__toESM(zod, 1);
@@ -263,6 +263,47 @@ const createPollRegistry = ({ limit = DEFAULT_LIMIT } = {}) => {
 	};
 };
 //#endregion
+//#region src/utils/async/queueSeries.ts
+const isPromiseLike = (value) => (typeof value === "object" && value !== null || typeof value === "function") && "then" in value && typeof value.then === "function";
+/**
+* Queues tasks added over time so a slower earlier task cannot finish after and overwrite a later one.
+* Each `add` returns its task's result; a rejection does not stop the remaining queue.
+*/
+const queueSeries = () => {
+	let tail = null;
+	const add = (task) => {
+		if (tail !== null) {
+			const result = tail.then(task);
+			tail = result.then(() => void 0, () => void 0);
+			return result;
+		}
+		let value;
+		try {
+			value = task();
+		} catch (error) {
+			return Promise.reject(error);
+		}
+		if (!isPromiseLike(value)) return Promise.resolve(value);
+		const result = Promise.resolve(value);
+		tail = result.then(() => void 0, () => void 0);
+		return result;
+	};
+	const onIdle = async () => {
+		while (tail !== null) {
+			const current = tail;
+			await current;
+			if (tail === current) {
+				tail = null;
+				return;
+			}
+		}
+	};
+	return {
+		add,
+		onIdle
+	};
+};
+//#endregion
 //#region src/utils/deepMerge.ts
 /**
 * Recursively merge `patch` into `base`. Plain-object values are merged key-by-key; every
@@ -320,6 +361,10 @@ const createWebStorage = (pick) => {
 		},
 		removeItem: (key) => {
 			storage.removeItem(key);
+		},
+		withLock: async (name, task) => {
+			if (typeof navigator === "undefined" || !("locks" in navigator)) return task();
+			return navigator.locks.request(`keboola:${name}`, { mode: "exclusive" }, task);
 		}
 	};
 };
@@ -328,62 +373,56 @@ const createSessionStorage = () => createWebStorage(() => "sessionStorage" in gl
 //#endregion
 //#region src/utils/persistor/persistor.ts
 const createPersistor = ({ storage = createNullStorage(), key, schema, defaultValue, encode = JSON.stringify, decode = JSON.parse }) => {
-	const clear = () => {
-		try {
-			storage.removeItem(key);
-		} catch (err) {
-			console.warn(`createPersistor: failed to clear "${key}"`, err);
-		}
-	};
-	const hasPersistedValue = () => {
-		try {
-			return !!storage.getItem(key);
-		} catch (err) {
-			console.warn(`createPersistor: failed to read "${key}", assuming empty`, err);
-			return false;
-		}
-	};
-	const hydrate = () => {
-		let raw;
-		try {
-			raw = storage.getItem(key);
-		} catch (err) {
-			console.warn(`createPersistor: failed to read "${key}", using default`, err);
-			return defaultValue;
-		}
-		if (raw === null) return defaultValue;
+	const writes = queueSeries();
+	const _load = async () => {
+		const raw = await storage.getItem(key);
+		if (raw === null) return {
+			value: defaultValue,
+			corrupt: false
+		};
 		let decoded;
 		try {
 			decoded = decode(raw);
 		} catch (err) {
-			console.warn(`createPersistor: failed to decode "${key}", resetting`, err);
-			clear();
-			return defaultValue;
+			console.warn(`createPersistor: failed to decode "${key}"`, err);
+			return {
+				value: defaultValue,
+				corrupt: true
+			};
 		}
 		const parsed = schema.safeParse(decoded);
-		if (parsed.success) return parsed.data;
-		clear();
-		return defaultValue;
+		return parsed.success ? {
+			value: parsed.data,
+			corrupt: false
+		} : {
+			value: defaultValue,
+			corrupt: true
+		};
 	};
-	const persist = (value) => {
-		let raw;
-		try {
-			raw = encode(value);
-		} catch (err) {
-			console.warn(`createPersistor: failed to encode "${key}", not persisting`, err);
-			return;
-		}
-		try {
-			storage.setItem(key, raw);
-		} catch (err) {
-			console.warn(`createPersistor: failed to write "${key}"`, err);
-		}
+	const remove = () => writes.add(() => storage.removeItem(key));
+	const write = (value) => writes.add(() => storage.setItem(key, encode(value)));
+	const read = async () => {
+		await writes.onIdle();
+		const parsed = await _load();
+		if (parsed.corrupt) remove().catch((err) => {
+			console.warn(`createPersistor: failed to drop the corrupt "${key}"`, err);
+		});
+		return parsed.value;
 	};
+	const modify = (change) => writes.add(async () => {
+		const next = change((await _load()).value);
+		await storage.setItem(key, encode(next));
+	});
+	const cell = {
+		read,
+		write,
+		modify,
+		remove
+	};
+	const locked = (task) => storage.withLock ? storage.withLock(key, () => task(cell)) : task(cell);
 	return {
-		hydrate,
-		persist,
-		clear,
-		hasPersistedValue
+		...cell,
+		locked
 	};
 };
 //#endregion
@@ -1075,159 +1114,6 @@ const createLegacyKeboola = (options = {}) => {
 	};
 };
 //#endregion
-//#region src/keboola/bearer/credentials/renewal.ts
-const renewalGrant = (credential) => credential.type === "token" ? {
-	type: "token",
-	refreshToken: credential.refreshToken
-} : {
-	type: "cookie",
-	sessionId: credential.sessionId
-};
-const renew = async (client, grant) => {
-	if (grant.type === "cookie") {
-		const { accessToken, expiresIn, sessionId } = await client.token.refreshWithSession({ sessionId: grant.sessionId });
-		return {
-			type: "cookie",
-			accessToken,
-			expiresIn,
-			sessionId
-		};
-	}
-	const { accessToken, expiresIn, refreshToken } = await client.token.refreshWithToken({ refreshToken: grant.refreshToken });
-	if (!refreshToken) throw new KeboolaError(KeboolaErrorType.NotAuthenticated);
-	return {
-		type: "token",
-		accessToken,
-		expiresIn,
-		refreshToken
-	};
-};
-//#endregion
-//#region src/keboola/bearer/credentials/credentials.ts
-const DEFAULT_REFRESH_THRESHOLD = .9;
-const signInEnded = () => new KeboolaError(KeboolaErrorType.SignInEnded);
-const toRestoreStatus = (outcome) => {
-	if (outcome === void 0 || outcome === "skipped") return "empty";
-	if (outcome === "refused") return "expired";
-	return outcome;
-};
-const createCredentials = ({ state, persistor, middlewares, refreshThreshold = DEFAULT_REFRESH_THRESHOLD, onSignedOut, onExpired }) => {
-	const rotationMap = /* @__PURE__ */ new Map();
-	const generations = /* @__PURE__ */ new Map();
-	const generationOf = (baseUrl) => generations.get(baseUrl) ?? 0;
-	const refresh = async (baseUrl, grant) => {
-		const client = require_authClient.createAuthClient({
-			baseUrl,
-			middlewares
-		});
-		const epochBefore = require_transientRetries.Result.unwrap(state.auth.getEpoch(baseUrl));
-		const generationBefore = generationOf(baseUrl);
-		const refreshed = await require_transientRetries.Result.tryCatchAsync(() => renew(client, grant));
-		return require_transientRetries.Result.unwrapOr(state.auth.getEpoch(baseUrl), -1) === epochBefore && generationOf(baseUrl) === generationBefore ? refreshed : require_transientRetries.Result.failure(signInEnded());
-	};
-	/**
-	* A stack's teardown, from the credential's side.
-	*
-	* - Bumps the generation, so an in-flight rotation can no longer write.
-	* - Drops the deduped entry, so nothing joins that rotation.
-	*/
-	const forget = (baseUrl) => {
-		generations.set(baseUrl, generationOf(baseUrl) + 1);
-		rotationMap.delete(baseUrl);
-	};
-	/**
-	* The rotation, and the one place a credential is declared dead.
-	*
-	* - Renews by the credential's own kind: the refresh token, or the session id with the cookie.
-	* - A refused refresh token or session is unambiguous.
-	* - The triggering 401 is not (an unreachable project answers the same), so never sign out on a replay.
-	*/
-	const rotateOnce = async (baseUrl) => {
-		const credential = state.auth.requireCredential(baseUrl);
-		if (!credential.success) return credential;
-		const refreshed = await refresh(baseUrl, renewalGrant(credential.data));
-		if (!refreshed.success) {
-			if (require_middleware.isUnauthorized(refreshed.error)) expire(baseUrl);
-			return refreshed;
-		}
-		return require_transientRetries.Result.map(state.auth.applyRefresh(baseUrl, refreshed.data), () => refreshed.data.accessToken);
-	};
-	const rotate = (baseUrl) => ensure(rotationMap, baseUrl, () => require_dedupe.dedupe(() => rotateOnce(baseUrl)))();
-	const restoreStack = async (baseUrl, grant) => {
-		if (!state.auth.startRestore(baseUrl).success) return "unreachable";
-		const refreshed = await refresh(baseUrl, grant);
-		if (!refreshed.success) {
-			state.auth.cancelRestore(baseUrl);
-			return require_middleware.isUnauthorized(refreshed.error) ? "refused" : "unreachable";
-		}
-		state.auth.authenticate(baseUrl, refreshed.data);
-		return "restored";
-	};
-	const restoreProjects = (baseUrl, projects) => {
-		for (const { projectId } of projects) state.projects.open(baseUrl, projectId);
-	};
-	/**
-	* Every persisted stack back into the table, with whatever credential it can hand back.
-	*
-	* - Never writes the scope. `lastActive` is what was scoped when the session was stored, for the
-	*   caller to select.
-	* - `status` reports what became of `lastActive`'s credential; the client reads it to decide
-	*   when persistence may start.
-	*/
-	const restore = async () => {
-		const { stacks, current } = persistor.hydrate();
-		const scoped = stacks.find(({ baseUrl }) => baseUrl === current?.baseUrl);
-		const restored = stacks.map(async ({ baseUrl, credential, projects }) => {
-			state.stacks.ensure(baseUrl);
-			if (!credential) return "unreachable";
-			if (require_transientRetries.Result.unwrapOr(state.auth.getEpoch(baseUrl), 0) > 0) return "skipped";
-			const outcome = await restoreStack(baseUrl, credential);
-			if (outcome === "restored") restoreProjects(baseUrl, projects);
-			return outcome;
-		});
-		const results = await Promise.all(restored);
-		const scopedOutcome = scoped?.credential ? results[stacks.indexOf(scoped)] : void 0;
-		return {
-			lastActive: current,
-			status: toRestoreStatus(scopedOutcome)
-		};
-	};
-	const isStale = (baseUrl) => {
-		const ageing = require_transientRetries.Result.map(state.auth.requireCredential(baseUrl), ({ issuedAt, expiresIn }) => Date.now() >= issuedAt + expiresIn * 1e3 * refreshThreshold);
-		return require_transientRetries.Result.unwrapOr(ageing, false);
-	};
-	const signOut = (baseUrl) => {
-		rotationMap.delete(baseUrl);
-		const signedOut = state.auth.signOut(baseUrl);
-		onSignedOut?.(baseUrl);
-		return signedOut;
-	};
-	const expire = (baseUrl) => {
-		if (!state.auth.notifyExpired(baseUrl)) return;
-		signOut(baseUrl);
-		onExpired?.(baseUrl);
-	};
-	const renewIfStale = async (baseUrl) => {
-		if (isStale(baseUrl)) await rotate(baseUrl);
-	};
-	const middleware = (baseUrl) => require_middleware.createBearerAuthMiddleware({ getAccessToken: async ({ forceRefresh = false } = {}) => {
-		if (forceRefresh) {
-			if (!state.auth.requireCredential(baseUrl).success) return null;
-			return require_transientRetries.Result.unwrap(await rotate(baseUrl));
-		}
-		await renewIfStale(baseUrl);
-		return state.auth.getAccessToken(baseUrl);
-	} });
-	return {
-		middleware,
-		rotate,
-		renewIfStale,
-		restore,
-		signOut,
-		forget
-	};
-};
-//#endregion
 //#region src/keboola/bearer/state/factories.ts
 /**
 * Everything the table constructs: the entries themselves, and the failures reading them produces.
@@ -1245,10 +1131,17 @@ const authenticatedAuth = (credential) => ({
 	status: "authenticated",
 	credential
 });
-const bearerCredential = (input) => ({
+const credential = (input) => ({
 	...input,
 	issuedAt: Date.now()
 });
+const grant = (credential) => credential.type === "token" ? {
+	type: "token",
+	refreshToken: credential.refreshToken
+} : {
+	type: "cookie",
+	sessionId: credential.sessionId
+};
 const expiredCredential = (credential) => ({
 	...credential,
 	issuedAt: Date.now() - credential.expiresIn * 1e3
@@ -1257,7 +1150,8 @@ const stack = (baseUrl) => ({
 	baseUrl,
 	context: "idle",
 	epoch: 0,
-	auth: anonymousAuth()
+	auth: anonymousAuth(),
+	retained: null
 });
 const project = (baseUrl, projectId) => ({
 	id: projectEntryId(baseUrl, projectId),
@@ -1289,7 +1183,8 @@ const Entry = {
 	anonymousAuth,
 	restoringAuth,
 	authenticatedAuth,
-	bearerCredential,
+	credential,
+	grant,
 	expiredCredential
 };
 /**
@@ -1307,7 +1202,8 @@ const Errors = {
 	notReady: () => new KeboolaError(KeboolaErrorType.NotReady),
 	alreadyRestoring: (baseUrl) => /* @__PURE__ */ new Error(`Stack "${baseUrl}" is already being restored`),
 	notRestoring: (baseUrl) => /* @__PURE__ */ new Error(`Stack "${baseUrl}" is not being restored`),
-	credentialKindChanged: (from, to) => /* @__PURE__ */ new Error(`A ${from} credential cannot become ${to}`),
+	grantTypeChanged: (from, to) => /* @__PURE__ */ new Error(`A ${from} grant cannot become ${to}`),
+	nothingRetained: (baseUrl) => /* @__PURE__ */ new Error(`Stack "${baseUrl}" retains no credential`),
 	missingProject: (id) => /* @__PURE__ */ new Error(`No project "${id}"`)
 };
 const authenticated = (auth) => auth.status === "authenticated" ? require_transientRetries.Result.success(auth.credential) : require_transientRetries.Result.failure(Errors.notAuthenticated());
@@ -1352,25 +1248,37 @@ const createAuth = ({ stacks, projects, expiry }) => {
 		return stacks.set({
 			...stack,
 			epoch: stack.epoch + 1,
-			auth: Entry.authenticatedAuth(Entry.bearerCredential(input))
+			auth: Entry.authenticatedAuth(Entry.credential(input)),
+			retained: null
 		});
 	});
-	const applyRefresh = (baseUrl, input) => require_transientRetries.Result.andThen(stacks.requireCredential(baseUrl), (credential) => credential.type !== input.type ? require_transientRetries.Result.failure(Errors.credentialKindChanged(credential.type, input.type)) : require_transientRetries.Result.map(stacks.get(baseUrl), (stack) => stacks.set({
+	const applyRefresh = (baseUrl, input) => require_transientRetries.Result.andThen(stacks.requireCredential(baseUrl), (credential) => credential.type !== input.type ? require_transientRetries.Result.failure(Errors.grantTypeChanged(credential.type, input.type)) : require_transientRetries.Result.map(stacks.get(baseUrl), (stack) => stacks.set({
 		...stack,
-		auth: Entry.authenticatedAuth(Entry.bearerCredential(input))
+		auth: Entry.authenticatedAuth(Entry.credential(input))
 	})));
 	const forceExpire = (baseUrl) => require_transientRetries.Result.andThen(stacks.requireCredential(baseUrl), (credential) => require_transientRetries.Result.map(stacks.get(baseUrl), (stack) => stacks.set({
 		...stack,
 		auth: Entry.authenticatedAuth(Entry.expiredCredential(credential))
 	})));
-	const signOut = (baseUrl) => require_transientRetries.Result.map(stacks.get(baseUrl), (stack) => {
+	const signOut = (baseUrl, { retain = false } = {}) => require_transientRetries.Result.map(stacks.get(baseUrl), (stack) => {
 		projects.closeAll(baseUrl);
+		const retained = retain ? require_transientRetries.Result.unwrapOr(require_transientRetries.Result.map(authenticated(stack.auth), (credential) => ({ grant: Entry.grant(credential) })), stack.retained) : null;
 		return stacks.set({
 			...stack,
 			epoch: stack.epoch + 1,
-			auth: Entry.anonymousAuth()
+			auth: Entry.anonymousAuth(),
+			retained
 		});
 	});
+	const retain = (baseUrl, retained) => require_transientRetries.Result.map(stacks.get(baseUrl), (stack) => stacks.set({
+		...stack,
+		retained
+	}));
+	const dropRetained = (baseUrl) => require_transientRetries.Result.map(stacks.get(baseUrl), (stack) => stacks.set({
+		...stack,
+		retained: null
+	}));
+	const requireRetained = (baseUrl) => require_transientRetries.Result.andThen(stacks.get(baseUrl), (stack) => stack.retained ? require_transientRetries.Result.success(stack.retained) : require_transientRetries.Result.failure(Errors.nothingRetained(baseUrl)));
 	const getEpoch = (baseUrl) => require_transientRetries.Result.map(stacks.get(baseUrl), (stack) => stack.epoch);
 	const getAccessToken = (baseUrl) => require_transientRetries.Result.unwrapOr(require_transientRetries.Result.map(stacks.requireCredential(baseUrl), ({ accessToken }) => accessToken), null);
 	return {
@@ -1380,6 +1288,9 @@ const createAuth = ({ stacks, projects, expiry }) => {
 		applyRefresh,
 		forceExpire,
 		signOut,
+		retain,
+		dropRetained,
+		requireRetained,
 		notifyExpired: expiry.report,
 		requireCredential: stacks.requireCredential,
 		getEpoch,
@@ -1633,6 +1544,204 @@ const createState = (defaultBaseUrl) => {
 	};
 };
 //#endregion
+//#region src/keboola/bearer/credentials/renewal.ts
+const renew = async (client, grant) => {
+	if (grant.type === "cookie") {
+		const { accessToken, expiresIn, sessionId } = await client.token.refreshWithSession({ sessionId: grant.sessionId });
+		return {
+			type: "cookie",
+			accessToken,
+			expiresIn,
+			sessionId
+		};
+	}
+	const { accessToken, expiresIn, refreshToken } = await client.token.refreshWithToken({ refreshToken: grant.refreshToken });
+	if (!refreshToken) throw new KeboolaError(KeboolaErrorType.NotAuthenticated);
+	return {
+		type: "token",
+		accessToken,
+		expiresIn,
+		refreshToken
+	};
+};
+//#endregion
+//#region src/keboola/bearer/credentials/credentials.ts
+const DEFAULT_REFRESH_THRESHOLD = .9;
+const signInEnded = () => new KeboolaError(KeboolaErrorType.SignInEnded);
+const toRestoreStatus = (outcome) => {
+	if (outcome === void 0 || outcome === "skipped") return "empty";
+	if (outcome === "refused") return "expired";
+	return outcome;
+};
+const createCredentials = ({ state, persistor, middlewares, refreshThreshold = DEFAULT_REFRESH_THRESHOLD, onSignedOut, onExpired }) => {
+	const rotationMap = /* @__PURE__ */ new Map();
+	const generations = /* @__PURE__ */ new Map();
+	const generationOf = (baseUrl) => generations.get(baseUrl) ?? 0;
+	const refresh = async (baseUrl, grant) => {
+		const client = require_authClient.createAuthClient({
+			baseUrl,
+			middlewares
+		});
+		const epochBefore = require_transientRetries.Result.unwrap(state.auth.getEpoch(baseUrl));
+		const generationBefore = generationOf(baseUrl);
+		const refreshed = await require_transientRetries.Result.tryCatchAsync(() => renew(client, grant));
+		return require_transientRetries.Result.unwrapOr(state.auth.getEpoch(baseUrl), -1) === epochBefore && generationOf(baseUrl) === generationBefore ? refreshed : require_transientRetries.Result.failure(signInEnded());
+	};
+	/**
+	* A stack's teardown, from the credential's side.
+	*
+	* - Bumps the generation, so an in-flight rotation can no longer write.
+	* - Drops the deduped entry, so nothing joins that rotation.
+	*/
+	const forget = (baseUrl) => {
+		generations.set(baseUrl, generationOf(baseUrl) + 1);
+		rotationMap.delete(baseUrl);
+	};
+	/**
+	* The rotation, and the one place a credential is declared dead.
+	*
+	* - Renews by the credential's grant: the refresh token, or the session id with the cookie.
+	* - A refused refresh token or session is unambiguous.
+	* - The triggering 401 is not (an unreachable project answers the same), so never sign out on a replay.
+	*/
+	const getGrantForRotation = async (store, baseUrl, credential) => {
+		const epochBefore = require_transientRetries.Result.unwrap(state.auth.getEpoch(baseUrl));
+		const generationBefore = generationOf(baseUrl);
+		const hydrated = await require_transientRetries.Result.tryCatchAsync(() => store.read());
+		if (!hydrated.success) return hydrated;
+		if (require_transientRetries.Result.unwrapOr(state.auth.getEpoch(baseUrl), -1) !== epochBefore || generationOf(baseUrl) !== generationBefore) return require_transientRetries.Result.failure(signInEnded());
+		const persistedStack = hydrated.data.stacks.find((stack) => stack.baseUrl === baseUrl);
+		if (persistedStack && persistedStack.credential === null) return require_transientRetries.Result.failure(signInEnded());
+		return require_transientRetries.Result.success(persistedStack?.credential ?? Entry.grant(credential));
+	};
+	const rotateOnce = async (baseUrl) => persistor.locked(async (store) => {
+		const credential = state.auth.requireCredential(baseUrl);
+		if (!credential.success) return credential;
+		const grant = await getGrantForRotation(store, baseUrl, credential.data);
+		if (!grant.success) return grant;
+		const refreshed = await refresh(baseUrl, grant.data);
+		if (!refreshed.success) {
+			if (require_middleware.isUnauthorized(refreshed.error)) await expire(baseUrl, store);
+			return refreshed;
+		}
+		const accessToken = require_transientRetries.Result.map(state.auth.applyRefresh(baseUrl, refreshed.data), () => refreshed.data.accessToken);
+		await store.persistStack(baseUrl, state.store.get());
+		return accessToken;
+	});
+	const rotate = (baseUrl) => ensure(rotationMap, baseUrl, () => require_dedupe.dedupe(() => rotateOnce(baseUrl)))();
+	const restoreStack = async (baseUrl, grant, retained = false) => persistor.locked(async (store) => {
+		const storedStack = (await store.read()).stacks.find((stack) => stack.baseUrl === baseUrl);
+		const latestGrant = retained ? storedStack?.retained?.grant : storedStack?.credential;
+		if (storedStack && !latestGrant) return "skipped";
+		if (!state.auth.startRestore(baseUrl).success) return "unreachable";
+		const refreshed = await refresh(baseUrl, latestGrant ?? grant);
+		if (!refreshed.success) {
+			state.auth.cancelRestore(baseUrl);
+			if (require_middleware.isUnauthorized(refreshed.error)) {
+				if (retained) state.auth.dropRetained(baseUrl);
+				await store.persistStack(baseUrl, state.store.get());
+				return "refused";
+			}
+			return "unreachable";
+		}
+		state.auth.authenticate(baseUrl, refreshed.data);
+		if (!state.auth.requireCredential(baseUrl).success) return "unreachable";
+		if (retained) state.auth.dropRetained(baseUrl);
+		await store.persistStack(baseUrl, state.store.get());
+		return "restored";
+	});
+	const restoreProjects = (baseUrl, projects) => {
+		for (const { projectId } of projects) state.projects.open(baseUrl, projectId);
+	};
+	/**
+	* Every persisted stack back into the table, with whatever credential it can hand back.
+	*
+	* - Never writes the scope. `lastActive` is what was scoped when the session was stored, for the
+	*   caller to select.
+	* - `status` reports what became of `lastActive`'s credential; the client reads it to decide
+	*   when persistence may start.
+	*/
+	const restore = async () => {
+		const hydrated = await persistor.locked((store) => store.read()).catch((error) => {
+			console.warn("createCredentials: the stored session could not be read", error);
+			return null;
+		});
+		if (hydrated === null) return {
+			lastActive: null,
+			status: "unreachable"
+		};
+		const { stacks, current } = hydrated;
+		const scoped = stacks.find(({ baseUrl }) => baseUrl === current?.baseUrl);
+		const restored = stacks.map(async ({ baseUrl, credential, retained, projects }) => {
+			state.stacks.ensure(baseUrl);
+			if (!credential && !retained) return "unreachable";
+			if (require_transientRetries.Result.unwrapOr(state.auth.getEpoch(baseUrl), 0) > 0) return "skipped";
+			if (retained) state.auth.retain(baseUrl, retained);
+			if (!credential) return "unreachable";
+			const outcome = await restoreStack(baseUrl, credential);
+			if (outcome === "restored") restoreProjects(baseUrl, projects);
+			return outcome;
+		});
+		const results = await Promise.all(restored);
+		const scopedOutcome = scoped?.credential ? results[stacks.indexOf(scoped)] : void 0;
+		return {
+			lastActive: current,
+			status: toRestoreStatus(scopedOutcome)
+		};
+	};
+	/**
+	* Signs a retained stack back in from the grant it kept.
+	*
+	* - `restored` and `refused` empty the slot; `unreachable` keeps it for another try.
+	* - Throws when the stack retains nothing.
+	*/
+	const restoreRetained = async (baseUrl) => {
+		const { grant } = require_transientRetries.Result.unwrap(state.auth.requireRetained(baseUrl));
+		return restoreStack(baseUrl, grant, true);
+	};
+	const isStale = (baseUrl) => {
+		const ageing = require_transientRetries.Result.map(state.auth.requireCredential(baseUrl), ({ issuedAt, expiresIn }) => Date.now() >= issuedAt + expiresIn * 1e3 * refreshThreshold);
+		return require_transientRetries.Result.unwrapOr(ageing, false);
+	};
+	/**
+	* Drops the slot so the next sign-in's requests don't join the dying rotation.
+	*
+	* - Writes nothing: the caller persists the stack, under the lock it holds or takes.
+	*/
+	const signOut = (baseUrl, options) => {
+		rotationMap.delete(baseUrl);
+		const signedOut = state.auth.signOut(baseUrl, options);
+		onSignedOut?.(baseUrl);
+		return signedOut;
+	};
+	const expire = async (baseUrl, store) => {
+		if (!state.auth.notifyExpired(baseUrl)) return;
+		signOut(baseUrl);
+		await store.persistStack(baseUrl, state.store.get());
+		onExpired?.(baseUrl);
+	};
+	const renewIfStale = async (baseUrl) => {
+		if (isStale(baseUrl)) await rotate(baseUrl);
+	};
+	const middleware = (baseUrl) => require_middleware.createBearerAuthMiddleware({ getAccessToken: async ({ forceRefresh = false } = {}) => {
+		if (forceRefresh) {
+			if (!state.auth.requireCredential(baseUrl).success) return null;
+			return require_transientRetries.Result.unwrap(await rotate(baseUrl));
+		}
+		await renewIfStale(baseUrl);
+		return state.auth.getAccessToken(baseUrl);
+	} });
+	return {
+		middleware,
+		rotate,
+		renewIfStale,
+		restore,
+		restoreRetained,
+		signOut,
+		forget
+	};
+};
+//#endregion
 //#region src/keboola/bearer/context/resource.ts
 /**
 * Owns fetching one async value per key — a caller names what it needs and never orchestrates the
@@ -1949,14 +2058,16 @@ const createPerProject = ({ state, credentials, middlewareFor, stack, clientServ
 */
 const SESSION_STORAGE_KEY = "keboola:session";
 /**
-* What survives a reload, per credential kind.
+* What survives a reload, per grant type.
+*
+* - Written under `credential`: the key every blob already stored carries.
 *
 * - `token`: the refresh token. It rotates, is single-use and is server-revocable, so a leaked
 *   snapshot has limited and revocable value. The access token is never written.
 * - `cookie`: the session id. The session cookie is the durable half and the browser keeps it;
 *   the id alone renews nothing.
 */
-const persistedCredentialSchema = zod.discriminatedUnion("type", [zod.object({
+const persistedGrantSchema = zod.discriminatedUnion("type", [zod.object({
 	type: zod.literal("token"),
 	refreshToken: zod.string()
 }), zod.object({
@@ -1965,32 +2076,68 @@ const persistedCredentialSchema = zod.discriminatedUnion("type", [zod.object({
 })]);
 /** A record per project rather than a bare id, so a project can grow a field without a migration. */
 const persistedProjectSchema = zod.object({ projectId: zod.number() });
+const persistedStackSchema = zod.object({
+	baseUrl: zod.string(),
+	credential: persistedGrantSchema.nullable().catch(null),
+	retained: zod.object({ grant: persistedGrantSchema }).nullable().default(null).catch(null),
+	projects: zod.array(persistedProjectSchema)
+});
 const persistedSessionSchema = zod.object({
 	current: zod.object({
 		baseUrl: zod.string(),
 		projectId: zod.number().nullable()
 	}).nullable(),
-	stacks: zod.array(zod.object({
-		baseUrl: zod.string(),
-		credential: persistedCredentialSchema.nullable().catch(null),
-		projects: zod.array(persistedProjectSchema)
-	}))
+	stacks: zod.array(persistedStackSchema)
 });
 const EMPTY_PERSISTED_SESSION = {
 	current: null,
 	stacks: []
 };
-const durableCredential = (stack) => {
-	if (stack.auth.status !== "authenticated") return null;
-	const { credential } = stack.auth;
-	return credential.type === "token" ? {
-		type: "token",
-		refreshToken: credential.refreshToken
-	} : {
-		type: "cookie",
-		sessionId: credential.sessionId
+const projectsOf = (projects, baseUrl) => Object.values(projects).filter((project) => project.baseUrl === baseUrl).map(({ projectId }) => ({ projectId }));
+const grantsOf = (stack) => ({
+	credential: stack.auth.status === "authenticated" ? Entry.grant(stack.auth.credential) : null,
+	retained: stack.retained
+});
+/**
+* The stored session, rewritten from the table except for the grants.
+*
+* - Scope, stack list and open projects come from memory.
+* - `credential` and `retained` stay as stored: a grant another document rotated must not be put
+*   back by a snapshot of this one's older table.
+*/
+const mergeSnapshot = (stored, { active, stacks, projects }) => ({
+	current: {
+		baseUrl: active.baseUrl,
+		projectId: active.projectId
+	},
+	stacks: Object.values(stacks).map(({ baseUrl }) => {
+		const kept = stored.stacks.find((stack) => stack.baseUrl === baseUrl);
+		return {
+			baseUrl,
+			credential: kept?.credential ?? null,
+			retained: kept?.retained ?? null,
+			projects: projectsOf(projects, baseUrl)
+		};
+	})
+});
+const upsertStack = (stored, baseUrl, update) => {
+	const index = stored.stacks.findIndex((stack) => stack.baseUrl === baseUrl);
+	const stacks = [...stored.stacks];
+	if (index < 0) stacks.push(update(void 0));
+	else stacks[index] = update(stacks[index]);
+	return {
+		...stored,
+		stacks
 	};
 };
+/**
+* The stored session, reached in two ways.
+*
+* - `locked`: the only way to read, and the only way to a grant write. Rotation and restore hold
+*   it across the refresh; sign-in, sign-out and the boot restore open it for one step.
+* - `snapshot`: the table minus its grants, under the lock, coalesced; what the store subscription
+*   feeds, and what a scope change awaits before the document leaves.
+*/
 const createSessionPersistor = (storage) => {
 	const persistor = createPersistor({
 		storage,
@@ -1998,20 +2145,35 @@ const createSessionPersistor = (storage) => {
 		schema: persistedSessionSchema,
 		defaultValue: EMPTY_PERSISTED_SESSION
 	});
-	const persist = ({ active, stacks, projects }) => persistor.persist({
-		current: {
-			baseUrl: active.baseUrl,
-			projectId: active.projectId
-		},
-		stacks: Object.values(stacks).map((stack) => ({
-			baseUrl: stack.baseUrl,
-			credential: durableCredential(stack),
-			projects: Object.values(projects).filter((project) => project.baseUrl === stack.baseUrl).map(({ projectId }) => ({ projectId }))
-		}))
-	});
+	const persistStack = (cell, baseUrl, { stacks, projects }) => {
+		const stack = stacks[baseUrl];
+		if (stack === void 0) return Promise.resolve();
+		return cell.modify((stored) => upsertStack(stored, baseUrl, (existing) => ({
+			baseUrl,
+			...grantsOf(stack),
+			projects: existing?.projects ?? projectsOf(projects, baseUrl)
+		})));
+	};
+	const locked = (task) => persistor.locked((cell) => task({
+		read: cell.read,
+		persistStack: (baseUrl, state) => persistStack(cell, baseUrl, state)
+	}));
+	let latest = null;
+	let pending = null;
+	const snapshot = (state) => {
+		latest = state;
+		if (pending) return pending;
+		const write = persistor.locked((cell) => {
+			pending = null;
+			const table = latest ?? state;
+			return cell.modify((stored) => mergeSnapshot(stored, table));
+		});
+		pending = write;
+		return write;
+	};
 	return {
-		...persistor,
-		persist
+		locked,
+		snapshot
 	};
 };
 //#endregion
@@ -2129,15 +2291,22 @@ const createKeboola = ({ defaultBaseUrl, storage, middlewares, clientServiceUrls
 		await credentials.renewIfStale(project.baseUrl);
 		return headersFor(require_transientRetries.Result.unwrap(state.projects.get(project.id)));
 	};
-	const authenticate = (input) => {
-		const stack = state.scope.getActiveStack();
-		if (input.type !== "token") return require_transientRetries.Result.unwrap(state.auth.authenticate(stack.baseUrl, input));
+	const toCredential = (input) => {
+		if (input.type !== "token") return input;
 		const { refreshToken } = input;
 		if (!refreshToken) throw new KeboolaError(KeboolaErrorType.NotAuthenticated);
-		return require_transientRetries.Result.unwrap(state.auth.authenticate(stack.baseUrl, {
+		return {
 			...input,
 			refreshToken
-		}));
+		};
+	};
+	const authenticate = (input) => {
+		const { baseUrl } = state.scope.getActiveStack();
+		const signedIn = require_transientRetries.Result.unwrap(state.auth.authenticate(baseUrl, toCredential(input)));
+		persistor.locked((store) => store.persistStack(baseUrl, state.store.get())).catch((error) => {
+			console.warn("createKeboola: the sign-in could not be stored", error);
+		});
+		return signedIn;
 	};
 	/**
 	* The flat product surface: `auth` and `management` per stack, the rest per project.
@@ -2177,11 +2346,21 @@ const createKeboola = ({ defaultBaseUrl, storage, middlewares, clientServiceUrls
 		require_transientRetries.Result.unwrapOr(state.projects.open(baseUrl, projectId), null);
 		return perProject.get(project).api;
 	};
-	/** The scope's sign-in, or a named stack's — and everything that sign-in derived. */
-	const signOut = (baseUrl) => {
+	/**
+	* The scope's sign-in, or a named stack's — and everything that sign-in derived.
+	*
+	* - `retain` keeps the grant on the stack, persisted beside the sign-in it ended, for
+	*   `restoreRetained`; the next sign-in on the stack replaces it.
+	* - The table is signed out on return; the promise resolves once that is stored, so a caller
+	*   leaving the document waits for it.
+	*/
+	const signOut = ({ baseUrl, ...options } = {}) => {
 		const target = requireStackUrl(baseUrl);
-		return require_transientRetries.Result.unwrap(credentials.signOut(target));
+		const signedOut = require_transientRetries.Result.unwrap(credentials.signOut(target, options));
+		return persistor.locked((store) => store.persistStack(target, state.store.get())).then(() => signedOut);
 	};
+	/** Signs a stack back in from what a retained sign-out kept; `unreachable` leaves it to retry. */
+	const restoreRetained = (baseUrl) => credentials.restoreRetained(require_createFetchClient.normalizeBaseUrl(baseUrl));
 	/**
 	* `input` replaces the active stack's sign-in, whatever it holds.
 	*
@@ -2218,16 +2397,22 @@ const createKeboola = ({ defaultBaseUrl, storage, middlewares, clientServiceUrls
 	/**
 	* Persistence starts only once the restore has settled.
 	*
-	* - Mid-hydration an unexchanged stack is `anonymous`; `durableCredential` would erase the
+	* - Mid-hydration an unexchanged stack is `anonymous`; the persistor would erase the
 	*   refresh token the exchange is about to spend.
 	* - Writes the settled table once: the subscription fires only on the next change.
 	*/
 	const enablePersistence = () => {
 		if (persisting) return;
 		persisting = true;
-		persistor.persist(state.store.get());
-		state.store.subscribe(persistor.persist);
+		snapshot(state.store.get());
+		state.store.subscribe(snapshot);
+	};
+	const snapshot = (table) => {
+		persistor.snapshot(table).catch((error) => {
+			console.warn("createKeboola: the session could not be stored", error);
+		});
 	};
+	const persistScope = () => persisting ? persistor.snapshot(state.store.get()) : Promise.resolve();
 	/**
 	* The same, deferred until a sign-in.
 	*
@@ -2281,14 +2466,22 @@ const createKeboola = ({ defaultBaseUrl, storage, middlewares, clientServiceUrls
 			resume,
 			stack: {
 				getActive: getActiveStack,
-				select: byCaller(selectStack),
+				/** Scoped on return; resolves once that is stored, for a caller leaving the document. */
+				select: byCaller((baseUrl) => {
+					const stack = selectStack(baseUrl);
+					return persistScope().then(() => stack);
+				}),
 				close: closeStack,
 				retryContext: perStack.context.retry,
 				getContext: (baseUrl) => perStack.context.get(requireStackUrl(baseUrl)),
 				getContextAsync: (baseUrl) => perStack.context.getAsync(requireStackUrl(baseUrl))
 			},
 			project: {
-				select: byCaller(selectProject),
+				/** Scoped on return; resolves once that is stored, for a caller leaving the document. */
+				select: byCaller((projectId) => {
+					const project = selectProject(projectId);
+					return persistScope().then(() => project);
+				}),
 				close: closeProject,
 				deactivate: state.scope.deactivate,
 				retryContext: perProject.context.retry,
@@ -2299,6 +2492,7 @@ const createKeboola = ({ defaultBaseUrl, storage, middlewares, clientServiceUrls
 				authenticate: byCaller(authenticate),
 				replace: byCaller(replace),
 				signOut: byCaller(signOut),
+				restoreRetained: byCaller(restoreRetained),
 				/** Whether the active stack holds a credential — `restoring` is not one yet. */
 				isAuthenticated,
 				isAuthenticatedAsync: () => resume().then(isAuthenticated),
@@ -2565,6 +2759,7 @@ exports.nextCursorOf = require_authClient.nextCursorOf;
 exports.parseLogLines = require_appLogs.parseLogLines;
 exports.parseOrThrow = require_ValidationError.parseOrThrow;
 exports.poller = require_transientRetries.poller;
+exports.queueSeries = queueSeries;
 exports.readableReason = require_storage.readableReason;
 exports.schemaGuidedMerge = require_configurations.schemaGuidedMerge;
 exports.series = require_storage.series;