@composio/client 2.0.0-rc.16 → 2.0.0-rc.18

package/dist/{generated-operations-DrhN6W_k.mjs → generated-operations-DKgGT6Dg.mjs}

@@ -1,74 +1,5 @@
-import { i as APIUserAbortError, n as APIConnectionTimeoutError, s as ComposioError, t as APIConnectionError } from "./error-D9cG225M.mjs";
+import { i as APIUserAbortError, n as APIConnectionTimeoutError, s as ComposioError, t as APIConnectionError } from "./error-Bw7_G2NZ.mjs";
 
-//#region src/compat/headers.ts
-const hasEntries = (value) => typeof value === "object" && value !== null && "append" in value && typeof value.append === "function" && "delete" in value && typeof value.delete === "function" && "entries" in value && typeof value.entries === "function" && "get" in value && typeof value.get === "function";
-const isHeaders = (value) => value instanceof Headers || hasEntries(value);
-const isNullableHeadersLike = (headers) => {
-	if (!("values" in headers) || !isHeaders(headers.values) || !("nulls" in headers)) return false;
-	const nulls = headers.nulls;
-	return typeof nulls === "object" && nulls !== null && Symbol.iterator in nulls;
-};
-/**
-* Iterates every supported input while preserving explicit deletions. Plain
-* objects replace an older value for a key; tuple inputs append duplicate
-* values, matching the published client.
-*/
-function* iterateHeaders(headers) {
-	if (!headers) return;
-	if (isNullableHeadersLike(headers)) {
-		yield* headers.values.entries();
-		for (const name of headers.nulls) yield [name, null];
-		return;
-	}
-	const shouldReplace = !isHeaders(headers) && !Array.isArray(headers);
-	const entries = isHeaders(headers) ? headers.entries() : Array.isArray(headers) ? headers : Object.entries(headers);
-	for (const entry of entries) {
-		const name = entry[0];
-		if (typeof name !== "string") throw new TypeError("expected header name to be a string");
-		const rawValue = entry[1];
-		const values = Array.isArray(rawValue) ? rawValue : [rawValue];
-		let replaced = false;
-		for (const value of values) {
-			if (value === void 0) continue;
-			if (shouldReplace && !replaced) {
-				replaced = true;
-				yield [name, null];
-			}
-			yield [name, value];
-		}
-	}
-}
-/** Merge sources while retaining names explicitly deleted by the last source. */
-const mergeHeaders = (sources) => {
-	const values = new Headers();
-	const nulls = /* @__PURE__ */ new Set();
-	for (const source of sources) {
-		if (!source) continue;
-		const seen = /* @__PURE__ */ new Set();
-		for (const [name, value] of iterateHeaders(source)) {
-			const lowerName = name.toLowerCase();
-			if (!seen.has(lowerName)) {
-				values.delete(name);
-				seen.add(lowerName);
-			}
-			if (value === null) {
-				values.delete(name);
-				nulls.add(lowerName);
-			} else {
-				values.append(name, value);
-				nulls.delete(lowerName);
-			}
-		}
-	}
-	return {
-		values,
-		nulls
-	};
-};
-/** Merge sources into the native header collection sent to fetch. */
-const buildHeaders = (sources) => mergeHeaders(sources).values;
-
-//#endregion
 //#region src/compat/credentials.ts
 /**
 * The credential transport boundary.
@@ -90,8 +21,8 @@ const buildHeaders = (sources) => mergeHeaders(sources).values;
 *    caller opts into with `allowInsecureHTTP` or
 *    `COMPOSIO_ALLOW_INSECURE_HTTP=1`.
 *    Enforced by {@link assertCredentialTransport} at construction and again
-*    by {@link credentialForRequest} at dispatch, because `apiKey` and
-*    `baseURL` are both public mutable fields on the client.
+*    by {@link credentialForRequest} at dispatch, because `baseURL` is a
+*    public mutable field on the client.
 * 2. **The credential is attached only to requests whose origin matches the
 *    configured API origin.** {@link credentialForRequest} returns `null`
 *    off-origin, and the header is simply not sent.
@@ -154,22 +85,10 @@ const SCHEME_HEADERS = {
 };
 /** The scheme a request authenticates with when its operation names none. */
 const DEFAULT_SCHEME = "ApiKeyAuth";
-const valueFor = (scheme, credentials) => scheme === "ApiKeyAuth" ? credentials.apiKey : scheme === "UserApiKeyAuth" ? credentials.userApiKey : credentials.orgApiKey;
-/**
-* Whether anything beyond the project key is configured — the condition that
-* makes per-operation selection able to change an outcome at all.
-*
-* Load-bearing rather than an optimization. With only `apiKey` set, every
-* branch of {@link selectScheme} lands on `ApiKeyAuth`: it wins wherever it is
-* an accepted alternative, and where it is not, the alternative is unconfigured
-* and the fallback is `ApiKeyAuth` again. So the client that every existing
-* caller constructs never consults the operation table, and "an `apiKey`-only
-* client emits byte-identical requests on all 104 operations" is a property of
-* the code shape rather than a claim tests have to keep re-establishing.
-*/
-const hasAlternateCredential = (credentials) => credentials.userApiKey !== null || credentials.orgApiKey !== null;
 /**
-* Which credential a request declaring `schemes` should carry.
+* Which credential a request declaring `schemes` should carry, for a client in
+* `auto` mode holding the schemes `held` answers `true` for. A fixed mode never
+* asks: it always sends its own.
 *
 * **Exactly one, always** — and the API says so itself. Measured against
 * production on 2026-08-06, `GET /toolkits` answers 200 for `x-api-key` alone
@@ -187,37 +106,38 @@ const hasAlternateCredential = (credentials) => credentials.userApiKey !== null
 * model available, and the choice has to be made per request rather than
 * accumulated.
 *
-* The precedence exists to make the change free where it must be free:
+* The precedence is the one every release before `rc.18` applied:
 *
-* 1. **`ApiKeyAuth` wins wherever the operation accepts it** and an `apiKey` is
-*    configured — 85 of the 104 operations, every wire byte preserved.
+* 1. **`ApiKeyAuth` wins wherever the operation accepts it** and a project key
+*    is held.
 * 2. Otherwise the first scheme the operation names that this client both
-*    recognizes *and* holds a credential for. That is what makes the 16
+*    recognizes *and* holds a credential for. That is what makes the
 *    `UserApiKeyAuth`-only and `OrgApiKeyAuth`-only operations reachable.
 * 3. Otherwise `ApiKeyAuth`, which is what this client did before any of this
 *    existed. A `UserApiKeyAuth`-only operation called by a client with no user
-*    key still sends `x-api-key` and still fails the same way — which is what
-*    keeps `cli.realtime.auth` and `cli.realtime.credentials` pinned against
-*    the Stainless oracle in `test/unit/differential-wire.test.ts`.
+*    key still sends `x-api-key` and still fails the same way.
 *
 * Rule 3 is also where a scheme name this client does not know lands. Three of
 * them exist: `security` references `no_auth` (3 operations) and
 * `workbench_access_key` (1) and `components.securitySchemes` declares neither.
-* Those four operations receive `x-api-key` today and are differentially
-* pinned doing so, so resolving an unknown name to "no credential" would be a
-* wire change made on the strength of a spec defect. A later generator pass
-* must not "fix" that.
+* Those four operations receive `x-api-key`, so resolving an unknown name to
+* "no credential" would be a wire change made on the strength of a spec defect.
+* A later generator pass must not "fix" that.
 */
-const selectScheme = (schemes, credentials) => {
+const selectScheme = (schemes, held) => {
 	if (schemes === void 0 || schemes.length === 0) return DEFAULT_SCHEME;
-	if (schemes.includes(DEFAULT_SCHEME) && credentials.apiKey !== null) return DEFAULT_SCHEME;
+	if (schemes.includes(DEFAULT_SCHEME) && held(DEFAULT_SCHEME)) return DEFAULT_SCHEME;
 	for (const scheme of schemes) {
 		if (!Object.hasOwn(SCHEME_HEADERS, scheme)) continue;
 		const known = scheme;
-		if (valueFor(known, credentials) !== null) return known;
+		if (held(known)) return known;
 	}
 	return DEFAULT_SCHEME;
 };
+/** The header `scheme` is sent as. */
+const schemeHeader = (scheme) => SCHEME_HEADERS[scheme];
+/** The scheme a credential header name belongs to, or `undefined` for any other name. */
+const schemeOfHeader = (name) => Object.keys(SCHEME_HEADERS).find((scheme) => SCHEME_HEADERS[scheme] === name);
 /**
 * What counts as loopback, pinned rather than assumed. `localhost` is not the
 * whole set:
@@ -272,8 +192,6 @@ const resolveHTTPURL = (target, base) => {
 const isCredentialSafeOrigin = (url, allowedHTTPOrigin = null) => url.protocol === "https:" || url.protocol === "http:" && (isLoopbackHostname(url.hostname) || allowedHTTPOrigin !== null && url.origin === allowedHTTPOrigin);
 const LOOPBACK_DESCRIPTION = "localhost, *.localhost, 127.0.0.0/8, [::1]";
 const insecureOriginMessage = (baseURL) => `Refusing to send a Composio API credential to ${baseURL}: a credentialed API origin must use HTTPS. By default, plain http:// is permitted only for loopback development endpoints (${LOOPBACK_DESCRIPTION}). Pass an https:// baseURL, use environment: 'local', set allowInsecureHTTP: true (or COMPOSIO_ALLOW_INSECURE_HTTP=1) for the configured development origin, or construct the client without credentials.`;
-/** Whether the client holds anything at all that rule 1 has to protect. */
-const anyCredential = (credentials) => credentials.apiKey !== null || hasAlternateCredential(credentials);
 /**
 * Rule 1 at construction time: a client that holds a credential must be
 * pointed at an origin that can carry one. Knowable before any request is
@@ -282,13 +200,9 @@ const anyCredential = (credentials) => credentials.apiKey !== null || hasAlterna
 * A `baseURL` that is not an absolute http(s) URL fails the same way — a
 * credential cannot be sent over a scheme this client does not speak, and the
 * alternative is a `TypeError` from `new URL()` one layer down.
-*
-* Every configured credential counts, not just `apiKey`: which one a given
-* request carries is decided per operation, so a client holding *any* of them
-* is a client that can put one on the wire.
 */
-const assertCredentialTransport = (baseURL, credentials, allowedHTTPOrigin = null) => {
-	if (!anyCredential(credentials)) return;
+const assertCredentialTransport = (baseURL, credentialed, allowedHTTPOrigin = null) => {
+	if (!credentialed) return;
 	const url = parseHTTPURL(baseURL);
 	if (url === null || !isCredentialSafeOrigin(url, allowedHTTPOrigin)) throw new ComposioError(insecureOriginMessage(baseURL));
 };
@@ -296,7 +210,7 @@ const assertCredentialTransport = (baseURL, credentials, allowedHTTPOrigin = nul
 * The credential this request may carry, or `null` for none.
 *
 * Rules 1 and 2 at dispatch time. Both re-checks are load-bearing rather than
-* belt-and-braces: `apiKey` and `baseURL` are public mutable fields, so the
+* belt-and-braces: `baseURL` is a public mutable field, so the
 * construction-time check can be invalidated by an assignment, and the request
 * URL is *not* guaranteed to sit on the configured origin. `buildURL`
 * concatenates `baseURL + path` and the escape hatch (`client.get(path)`)
@@ -310,18 +224,14 @@ const assertCredentialTransport = (baseURL, credentials, allowedHTTPOrigin = nul
 * with credentials, so that one dies at the transport instead. httpx has no
 * such objection, which is why the Python port checks the same thing.)
 */
-const credentialForRequest = (baseURL, scheme, credentials, requestURL, allowedHTTPOrigin = null) => {
-	const value = valueFor(scheme, credentials);
-	if (value === null) return null;
+const credentialForRequest = (baseURL, credential, requestURL, allowedHTTPOrigin = null) => {
+	if (credential === null) return null;
 	const base = parseHTTPURL(baseURL);
 	const target = parseHTTPURL(requestURL);
 	if (base === null || target === null) return null;
 	if (base.origin !== target.origin) return null;
 	if (!isCredentialSafeOrigin(target, allowedHTTPOrigin)) throw new ComposioError(insecureOriginMessage(baseURL));
-	return {
-		name: SCHEME_HEADERS[scheme],
-		value
-	};
+	return credential;
 };
 /**
 * Whether two absolute http(s) URLs share an origin, by the same test
@@ -333,34 +243,6 @@ const sameOrigin = (a, b) => {
 	return origin !== void 0 && origin === parseHTTPURL(b)?.origin;
 };
 /**
-* The credential headers a *caller* can place that are not the one this client
-* attaches — `x-api-key` is excluded because a caller setting it is overriding
-* the client's own value in the same slot, which is pinned Stainless behaviour,
-* not a second credential.
-*/
-const FOREIGN_CREDENTIAL_HEADERS = ["x-user-api-key", "x-org-api-key"];
-/**
-* Whether the caller has placed a credential of their own, in which case the
-* client must not add one beside it.
-*
-* Not a courtesy: this API answers a request carrying two credential headers
-* with `401 HTTP_Unauthorized`, so attaching `x-api-key` next to a caller's
-* `x-user-api-key` does not weaken the call, it *breaks* it. Three released
-* methods make that reachable without any `defaultHeaders` at all —
-* `cli.createCodactFailure`, `org.consumer.project.resolve` and
-* `org.consumer.listConnectedToolkits` declare `x-user-api-key` as a `required`
-* header parameter, which the generator folds into their params object. Calling
-* them the way their signature asks for returned 401 until this rule existed.
-*
-* Header merging is replayed rather than approximated, because a later source
-* may carry `null` to delete what an earlier one set (`buildHeaders`).
-*/
-const callerPlacedCredential = (sources) => {
-	if (!sources.some(Boolean)) return false;
-	const headers = buildHeaders(sources);
-	return FOREIGN_CREDENTIAL_HEADERS.some((name) => headers.has(name));
-};
-/**
 * Header names that carry a credential and must not survive an origin change.
 *
 * The first three are what `fetch` itself would have stripped had it been
@@ -433,6 +315,211 @@ const withdrawCredentials = (headers) => {
 */
 const carriesCredentials = (headers) => CREDENTIAL_HEADERS.some((name) => headers.has(name));
 
+//#endregion
+//#region src/compat/auth.ts
+/**
+* Who a client authenticates as (`Auth`) and which organization or project it
+* addresses (`Scope`).
+*
+* A request carries zero or one Composio credential. A fixed mode sends that
+* credential class on every request to the API origin and never consults the
+* operation table; `auto` picks one configured credential from the operation's
+* declared schemes, which is how `rc.17` and earlier chose. `none` sends no
+* credential, and leaves the credential header names to the caller.
+*/
+const NONE = Object.freeze({ mode: "none" });
+/** The constructors, typed for one entry's credential. Every entry's behave the same. */
+const authConstructors = () => Object.freeze({
+	none: () => NONE,
+	project: (credential) => Object.freeze({
+		mode: "project",
+		credential
+	}),
+	user: (credential) => Object.freeze({
+		mode: "user",
+		credential
+	}),
+	organization: (credential) => Object.freeze({
+		mode: "organization",
+		credential
+	}),
+	auto: (credentials) => Object.freeze({
+		mode: "auto",
+		credentials: Object.freeze({ ...credentials })
+	})
+});
+/** The constructors of {@link Auth}: `Auth.project(key)`, `Auth.user(key)`, `Auth.organization(key)`, `Auth.auto({ ... })`, `Auth.none()`. */
+const Auth = authConstructors();
+/**
+* The rule `fromEnv` and the Effect `layerConfig` share: one credential given
+* is that fixed mode, several is `auto` over them, none is `none`. Generic over
+* what a credential is, so the Effect entry keeps its `Redacted` values.
+*/
+const authFromCredentials = (credentials) => {
+	const given = [
+		"project",
+		"user",
+		"organization"
+	].filter((key) => credentials[key] !== void 0);
+	if (given.length === 0) return NONE;
+	if (given.length > 1) return authConstructors().auto(Object.fromEntries(given.map((key) => [key, credentials[key]])));
+	const [only] = given;
+	return authConstructors()[only](credentials[only]);
+};
+const MODE_SCHEME = {
+	project: "ApiKeyAuth",
+	user: "UserApiKeyAuth",
+	organization: "OrgApiKeyAuth"
+};
+/** The scheme each credential class authenticates with, keyed by mode. */
+const schemeOfMode = (mode) => MODE_SCHEME[mode];
+const MIGRATION = "Pass `auth`: `Auth.project(key)`, `Auth.user(key)`, `Auth.organization(key)`, `Auth.auto({ project, user, organization })` or `Auth.none()`.";
+/** The credential options `rc.18` removed, each with the `auth` that replaces it. */
+const REMOVED_OPTIONS = {
+	apiKey: "Auth.project(key)",
+	userApiKey: "Auth.user(key)",
+	orgApiKey: "Auth.organization(key)"
+};
+/**
+* Refuses a removed credential option, which TypeScript already rejects, for
+* a caller it did not reach.
+*/
+const assertNoRemovedCredentialOptions = (options) => {
+	for (const [option, replacement] of Object.entries(REMOVED_OPTIONS)) if (Object.hasOwn(options, option)) throw new ComposioError(`The \`${option}\` option was removed in 2.0.0-rc.18. Pass \`auth: ${replacement}\` instead, or \`Auth.auto({ ... })\` for per-operation selection.`);
+};
+/**
+* Validates `auth` and lays it out by scheme. `isCredential` decides what a
+* credential may be on the calling entry; `checkKey` validates a key that is
+* already known, so a bad literal fails here rather than on the first request.
+*/
+const resolveAuth = (auth, isCredential, checkKey) => {
+	if (typeof auth !== "object" || auth === null || !("mode" in auth)) throw new ComposioError(`\`auth\` is required. ${MIGRATION}`);
+	const value = auth;
+	const held = (credential, option) => {
+		if (!isCredential(credential)) throw new ComposioError(`\`${option}\` must be a key or a function that returns one.`);
+		checkKey(credential, option);
+		return credential;
+	};
+	switch (value.mode) {
+		case "none": return {
+			mode: "none",
+			credentials: {}
+		};
+		case "project":
+		case "user":
+		case "organization": return {
+			mode: value.mode,
+			credentials: { [MODE_SCHEME[value.mode]]: held(value.credential, "auth.credential") }
+		};
+		case "auto": {
+			const given = value.credentials;
+			if (typeof given !== "object" || given === null) throw new ComposioError("`Auth.auto` needs at least one of `project`, `user` and `organization`.");
+			const credentials = {};
+			for (const [key, scheme] of Object.entries(MODE_SCHEME)) {
+				const credential = given[key];
+				if (credential !== void 0) credentials[scheme] = held(credential, `auth.credentials.${key}`);
+			}
+			if (Object.keys(credentials).length === 0) throw new ComposioError("`Auth.auto` needs at least one of `project`, `user` and `organization`.");
+			return {
+				mode: "auto",
+				credentials
+			};
+		}
+		default: throw new ComposioError(`\`auth.mode\` must be 'none', 'project', 'user', 'organization' or 'auto'. ${MIGRATION}`);
+	}
+};
+/** Whether the platform's `Headers` takes `value` under `name`. Its refusal quotes the value, so it stays here. */
+const isSendable = (name, value) => {
+	try {
+		new globalThis.Headers().set(name, value);
+		return true;
+	} catch {
+		return false;
+	}
+};
+/**
+* Whether `key` can be sent as `scheme`'s header: a string with a
+* non-whitespace character that the platform's `Headers` accepts. It is sent
+* as given.
+*/
+const isUsableKey = (scheme, key) => typeof key === "string" && /\S/.test(key) && isSendable(SCHEME_HEADERS[scheme], key);
+/** The error for a key that cannot be sent. It names where the key came from and never the key. */
+const unusableKeyError = (source) => new ComposioError(`${source} is not a usable key: it must be a string with a non-whitespace character and no line break, NUL or character outside Latin-1.`);
+const SCOPE_ID = /^\S(?:.*\S)?$/s;
+/** Validates `scope` (an id must be non-empty with no surrounding whitespace) and returns the headers it sends. */
+const resolveScope = (scope) => {
+	if (scope === void 0) return void 0;
+	if (typeof scope !== "object" || scope === null) throw new ComposioError("`scope` must be an object with an `organizationId`, a `projectId`, or both.");
+	const { organizationId, projectId } = scope;
+	if (organizationId === void 0 && projectId === void 0) throw new ComposioError("`scope` must name an `organizationId`, a `projectId`, or both.");
+	const headers = {};
+	for (const [field, header, value] of [[
+		"organizationId",
+		"x-org-id",
+		organizationId
+	], [
+		"projectId",
+		"x-project-id",
+		projectId
+	]]) {
+		if (value === void 0) continue;
+		if (typeof value !== "string" || !SCOPE_ID.test(value) || !isSendable(header, value)) throw new ComposioError(`\`scope.${field}\` must be a non-empty string with no surrounding whitespace.`);
+		headers[header] = value;
+	}
+	return headers;
+};
+/** The header names `auth` owns while it is not `none`. */
+const CREDENTIAL_HEADER_NAMES = Object.values(SCHEME_HEADERS);
+/** The header names `scope` owns while it is set. */
+const SCOPE_HEADER_NAMES = ["x-org-id", "x-project-id"];
+/**
+* Fails a generated call whose operation requires an owned header parameter it
+* did not supply. It does not fall back to the configured `auth` or `scope`:
+* the operation asked for a value of its own.
+*/
+const assertRequiredOperationHeaders = (operation, supplied) => {
+	for (const name of operation?.requiredHeaders ?? []) if (supplied?.[name] == null) throw new ComposioError(`\`${operation?.chain.join(".")}\` requires the \`${name}\` parameter.`);
+};
+const chooseCredential = (auth, operation, supplied) => {
+	for (const [name, value] of Object.entries(supplied ?? {})) {
+		const scheme = schemeOfHeader(name);
+		if (scheme === void 0 || value == null) continue;
+		if (!isUsableKey(scheme, value)) throw unusableKeyError(`The \`${name}\` parameter`);
+		return {
+			kind: "operation",
+			scheme,
+			key: value
+		};
+	}
+	if (auth.mode === "none") return null;
+	const scheme = auth.mode === "auto" ? selectScheme(operation?.schemes, (candidate) => auth.credentials[candidate] !== void 0) : schemeOfMode(auth.mode);
+	const credential = auth.credentials[scheme];
+	return credential === void 0 ? null : {
+		kind: "configured",
+		scheme,
+		credential
+	};
+};
+/**
+* The routing headers one call sends: the configured scope, with any operation
+* scope id the call supplied in its place. Where both name the same id they
+* must agree; a call that disagrees with its own client fails before dispatch.
+*/
+const scopeForCall = (configured, supplied) => {
+	let merged = configured;
+	for (const name of SCOPE_HEADER_NAMES) {
+		const value = supplied?.[name];
+		if (value == null) continue;
+		const current = configured?.[name];
+		if (current !== void 0 && current !== value) throw new ComposioError(`The \`${name}\` parameter disagrees with the client's \`scope\`. Derive a client with \`withOptions({ scope })\` to address another one.`);
+		merged = {
+			...merged,
+			[name]: value
+		};
+	}
+	return merged;
+};
+
 //#endregion
 //#region src/compat/deprecation.ts
 /**
@@ -903,45 +990,266 @@ const inspectDeprecatedInputs = ({ operation, query, body, headers, table, seen,
 	}
 };
 
+//#endregion
+//#region src/compat/headers.ts
+const hasEntries = (value) => typeof value === "object" && value !== null && "append" in value && typeof value.append === "function" && "delete" in value && typeof value.delete === "function" && "entries" in value && typeof value.entries === "function" && "get" in value && typeof value.get === "function";
+const isHeaders = (value) => value instanceof Headers || hasEntries(value);
+const isNullableHeadersLike = (headers) => {
+	if (!("values" in headers) || !isHeaders(headers.values) || !("nulls" in headers)) return false;
+	const nulls = headers.nulls;
+	return typeof nulls === "object" && nulls !== null && Symbol.iterator in nulls;
+};
+/**
+* Iterates every supported input while preserving explicit deletions. Plain
+* objects replace an older value for a key; tuple inputs append duplicate
+* values, matching the published client.
+*/
+function* iterateHeaders(headers) {
+	if (!headers) return;
+	if (isNullableHeadersLike(headers)) {
+		yield* headers.values.entries();
+		for (const name of headers.nulls) yield [name, null];
+		return;
+	}
+	const shouldReplace = !isHeaders(headers) && !Array.isArray(headers);
+	const entries = isHeaders(headers) ? headers.entries() : Array.isArray(headers) ? headers : Object.entries(headers);
+	for (const entry of entries) {
+		const name = entry[0];
+		if (typeof name !== "string") throw new TypeError("expected header name to be a string");
+		const rawValue = entry[1];
+		const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+		let replaced = false;
+		for (const value of values) {
+			if (value === void 0) continue;
+			if (shouldReplace && !replaced) {
+				replaced = true;
+				yield [name, null];
+			}
+			yield [name, value];
+		}
+	}
+}
+/** Merge sources while retaining names explicitly deleted by the last source. */
+const mergeHeaders = (sources) => {
+	const values = new Headers();
+	const nulls = /* @__PURE__ */ new Set();
+	for (const source of sources) {
+		if (!source) continue;
+		const seen = /* @__PURE__ */ new Set();
+		for (const [name, value] of iterateHeaders(source)) {
+			const lowerName = name.toLowerCase();
+			if (!seen.has(lowerName)) {
+				values.delete(name);
+				seen.add(lowerName);
+			}
+			if (value === null) {
+				values.delete(name);
+				nulls.add(lowerName);
+			} else {
+				values.append(name, value);
+				nulls.delete(lowerName);
+			}
+		}
+	}
+	return {
+		values,
+		nulls
+	};
+};
+/** Merge sources into the native header collection sent to fetch. */
+const buildHeaders = (sources) => mergeHeaders(sources).values;
+/** Every header name a source mentions, lowercased, a `null` deletion included. */
+function* headerNames(headers) {
+	for (const [name] of iterateHeaders(headers)) yield name.toLowerCase();
+}
+
 //#endregion
 //#region src/version.ts
-const VERSION = "2.0.0-rc.16";
+const VERSION = "2.0.0-rc.18";
 
 //#endregion
-//#region src/compat/telemetry.ts
+//#region src/compat/identity.ts
+/**
+* The runtime keys `std-env` detects, in its order, each with the label this
+* client sends as `x-client-runtime`. Ported from std-env 4.3.0
+* (https://github.com/unjs/std-env, MIT) rather than imported: std-env reads
+* `process.env` when it is imported, which throws under Deno without
+* `--allow-env`, and this needs only the runtime check.
+*
+* The labels are the ones released clients already send and the platform
+* already normalizes (`nodejs`, `cloudflare`, `vercel_edge`, ...), so a
+* dashboard groups old and new traffic together. Edge runtimes come before
+* Node because `nodejs_compat` and edge polyfills expose `process.versions.node`.
+*/
+const RUNTIMES = [
+	[
+		"netlify",
+		"netlify",
+		(g) => "Netlify" in g
+	],
+	[
+		"edge-light",
+		"vercel_edge",
+		(g) => "EdgeRuntime" in g
+	],
+	[
+		"workerd",
+		"cloudflare",
+		(g) => g.navigator?.userAgent === "Cloudflare-Workers"
+	],
+	[
+		"fastly",
+		"fastly",
+		(g) => "fastly" in g
+	],
+	[
+		"deno",
+		"deno",
+		(g) => "Deno" in g
+	],
+	[
+		"bun",
+		"bun",
+		(g) => "Bun" in g
+	],
+	[
+		"node",
+		"nodejs",
+		(g) => Boolean(g.process?.versions?.node)
+	]
+];
 /**
-* The runtime label and version, first match wins. Workers and Vercel Edge are
-* checked before Node because `nodejs_compat` and edge polyfills can expose
-* `process.versions.node`; neither reports a version, so a polyfilled Node
-* version is never sent as theirs.
+* The runtime label and its version. The version is `process.versions[key]`,
+* which Node, Bun and Deno each set for themselves; an edge runtime reports
+* none, so a polyfilled Node version is never sent as its own.
 */
 const detectRuntime = () => {
 	const g = globalThis;
-	if (g.Bun !== void 0) return ["bun", g.Bun.version];
-	if (g.Deno !== void 0) return ["deno", g.Deno.version?.deno];
-	if (g.navigator?.userAgent === "Cloudflare-Workers" || g.caches !== void 0 && g.WebSocketPair !== void 0) return ["cloudflare", void 0];
-	if (g.EdgeRuntime !== void 0) return ["vercel_edge", void 0];
-	if (typeof process !== "undefined" && process.versions?.node) return ["nodejs", process.versions.node];
-	if (typeof g.ServiceWorkerGlobalScope === "function" && globalThis instanceof g.ServiceWorkerGlobalScope) return ["service_worker", void 0];
-	if (g.WorkerGlobalScope !== void 0 && typeof g.importScripts === "function") return ["web_worker", void 0];
-	if (g.navigator?.product === "ReactNative") return ["react_native", void 0];
-	if (g.window !== void 0 && g.document !== void 0) return ["browser", void 0];
+	for (const [key, label, detect] of RUNTIMES) if (detect(g)) return [label, g.process?.versions?.[key]];
 	return ["unknown", void 0];
 };
-/** Caller headers override these defaults, including the calling SDK's identity. */
-const clientTelemetryHeaders = () => {
-	const [runtime, version] = detectRuntime();
-	const headers = {
-		"x-client-provenance": "@composio/client",
-		"x-client-version": VERSION,
+/** The library sending the request. Never caller-settable, with or without an identity. */
+const PACKAGE_HEADERS = [
+	"x-client-library",
+	"x-client-library-version",
+	"x-client-language"
+];
+/**
+* The calling product and its runtime. Reserved once a client has an
+* `identity`; without one they default to the package and stay
+* caller-settable, which is how a wrapper identified itself before `identity`.
+*/
+const PRODUCT_HEADERS = [
+	"x-client-provenance",
+	"x-client-version",
+	"x-sdk-version",
+	"x-source",
+	"x-framework",
+	"x-runtime",
+	"x-client-runtime",
+	"x-runtime-version"
+];
+const PACKAGE_RESERVED = new Set(PACKAGE_HEADERS);
+const IDENTITY_RESERVED = /* @__PURE__ */ new Set([...PACKAGE_HEADERS, ...PRODUCT_HEADERS]);
+/** Printable ASCII with no leading or trailing whitespace: what every runtime's `Headers` sends unchanged. */
+const HEADER_SAFE = /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/;
+const IDENTITY_FIELDS = [
+	"product",
+	"version",
+	"source",
+	"framework",
+	"runtime"
+];
+const REQUIRED_FIELDS = /* @__PURE__ */ new Set(["product", "version"]);
+const validateIdentity = (identity) => {
+	if (typeof identity !== "object" || identity === null) throw new ComposioError("`identity` must be an object with a `product` and a `version`.");
+	const fields = identity;
+	for (const field of IDENTITY_FIELDS) {
+		const value = fields[field];
+		if (value === void 0 && !REQUIRED_FIELDS.has(field)) continue;
+		if (typeof value !== "string" || !HEADER_SAFE.test(value)) throw new ComposioError(`\`identity.${field}\` must be a non-empty string of printable ASCII with no leading or trailing whitespace.`);
+	}
+	return identity;
+};
+/**
+* Validates `identity` and resolves the headers it owns, once per client.
+*
+* Without an identity the client reports itself, as it always has. With one,
+* the product fields replace the package's; the runtime the package detected
+* stays in `x-client-runtime` and `x-runtime-version` either way, since
+* `identity.runtime` is the legacy `x-runtime` label and the platform does not
+* read the two as aliases.
+*/
+const resolveIdentity = (identity) => {
+	const [runtime, runtimeVersion] = detectRuntime();
+	const library = {
 		"x-client-library": "@composio/client",
 		"x-client-library-version": VERSION,
 		"x-client-language": "typescript",
-		"x-client-runtime": runtime,
-		"x-runtime": runtime
+		"x-client-runtime": runtime
 	};
-	if (version) headers["x-runtime-version"] = version;
-	return headers;
+	if (identity === void 0) {
+		const headers = {
+			"x-client-provenance": "@composio/client",
+			"x-client-version": VERSION,
+			...library,
+			"x-runtime": runtime
+		};
+		if (runtimeVersion) headers["x-runtime-version"] = runtimeVersion;
+		return {
+			headers,
+			reserved: PACKAGE_RESERVED
+		};
+	}
+	const valid = validateIdentity(identity);
+	const headers = {
+		"x-client-provenance": valid.product,
+		"x-client-version": valid.version,
+		...library,
+		"x-runtime": valid.runtime ?? runtime
+	};
+	if (runtimeVersion) headers["x-runtime-version"] = runtimeVersion;
+	headers["x-sdk-version"] = valid.version;
+	if (valid.source !== void 0) headers["x-source"] = valid.source;
+	if (valid.framework !== void 0) headers["x-framework"] = valid.framework;
+	return {
+		headers,
+		reserved: IDENTITY_RESERVED
+	};
+};
+/**
+* The reserved names, as a function of what is configured. The identity names
+* are rc.17's. The credential names are reserved while `auth` is not `none`,
+* and the routing ids while a `scope` is set; with neither configured they are
+* ordinary headers, which is how a client is used as a transport for schemes
+* it does not model.
+*/
+const reservedHeaders = (identity, configured) => {
+	const reserved = /* @__PURE__ */ new Map();
+	for (const name of identity.reserved) reserved.set(name, PACKAGE_RESERVED.has(name) ? "client" : "identity");
+	if (configured.auth) for (const name of CREDENTIAL_HEADER_NAMES) reserved.set(name, "auth");
+	if (configured.scope) for (const name of SCOPE_HEADER_NAMES) reserved.set(name, "scope");
+	return reserved;
+};
+const REMEDY = {
+	client: " Pass `identity` to describe the calling product.",
+	identity: "",
+	auth: " Configure the credential through `auth`; derive a client with `withOptions({ auth })` for another one.",
+	scope: " Configure the organization and project through `scope`; derive a client with `withOptions({ scope })` for another one."
+};
+/**
+* Refuses a generic header source that names a reserved header, whether it
+* sets one or deletes one with `null`. Constructor validation runs it over
+* `defaultHeaders`; request validation over a call's `headers`, before any
+* network work.
+*/
+const assertNoReservedHeaders = (headers, reserved, option) => {
+	if (!headers) return;
+	for (const name of headerNames(headers)) {
+		const owner = reserved.get(name);
+		if (owner === void 0) continue;
+		throw new ComposioError(`The \`${name}\` header is set by ${owner === "client" ? "the client" : `\`${owner}\``} and cannot be passed in \`${option}\`.${REMEDY[owner]}`);
+	}
 };
 
 //#endregion
@@ -1011,19 +1319,31 @@ const createFetchTransport = (options = {}) => {
 */
 const OPERATION = Symbol("composio.operation");
 /**
-* Attach a generated call's operation to the options bag it dispatches with.
+* Beside the descriptor, the owned header parameters the call supplied
+* (`x-user-api-key`, `x-org-id`): the generated method takes them out of the
+* generic header bag and hands them over here, so the kernel can let an
+* operation credential replace `auth` and hold an operation scope id to the
+* configured `scope`. A raw call has no way to set it.
+*/
+const OPERATION_HEADERS = Symbol("composio.operationHeaders");
+/**
+* Attach a generated call's operation, and the owned header parameters it
+* supplied, to the options bag it dispatches with.
 *
 * Called with the freshly built literal — never with the caller's own object —
 * and *after* the caller's options have been spread into it, so a caller
 * cannot pre-empt the descriptor: the write happens last, and the key it
 * writes to is not one a caller can name.
 */
-const withOperation = (operation, options) => {
+const withOperation = (operation, options, headers) => {
 	options[OPERATION] = operation;
+	if (headers !== void 0) options[OPERATION_HEADERS] = headers;
 	return options;
 };
 /** The operation a generated call recorded, or `undefined` for a raw one. */
 const readOperation = (options) => options[OPERATION];
+/** The owned header parameters a generated call supplied, or `undefined`. */
+const readOperationHeaders = (options) => options[OPERATION_HEADERS];
 /** A request label safe to print: dynamic path values and URL secrets are excluded. */
 const printableURL = (url, operation) => `${new URL(url).origin}${operation?.path ?? "/<custom>"}`;
 const emitLog = (config, level, message, metadata) => {
@@ -1286,24 +1606,27 @@ const kernelInternals = { sleep };
 * The headers for one hop, built fresh from the URL that hop is going to.
 *
 * This is where rule 3 mostly stops needing machinery of its own: the
-* credential is re-derived per hop from the *request* URL rather than carried
-* along from the last one, so a hop that leaves the configured API origin
-* simply does not get a key. `withdrawn` covers what that cannot — the
+* credential is re-checked per hop against the *request* URL rather than
+* carried along from the last one, so a hop that leaves the configured API
+* origin simply does not get a key. `withdrawn` covers what that cannot — the
 * caller's own credential headers, which are legitimate on the URL the caller
 * chose and are dropped once the *server* has chosen one.
 *
-* The client's identity headers follow the same per-hop rule: they describe
-* this client to its own API, so a hop off the configured origin (a presigned
-* storage URL, a redirect target) goes without them.
+* The client's identity and scope headers follow the same per-hop rule: they
+* describe this client to its own API, so a hop off the configured origin (a
+* presigned storage URL, a redirect target) goes without them.
 */
-const buildRequestHeaders = (config, options, requestURL, bodyHeaders, withdrawn, scheme, callerPlaced) => {
-	const credential = withdrawn || callerPlaced ? null : credentialForRequest(config.baseURL, scheme, config.credentials, requestURL, config.allowedHTTPOrigin);
-	const identity = sameOrigin(config.baseURL, requestURL) ? clientTelemetryHeaders() : void 0;
+const buildRequestHeaders = (config, options, requestURL, bodyHeaders, withdrawn, call) => {
+	const credential = withdrawn ? null : credentialForRequest(config.baseURL, call.credential, requestURL, config.allowedHTTPOrigin);
+	const own = sameOrigin(config.baseURL, requestURL);
+	const identity = own ? config.identity.headers : void 0;
+	const scope = own ? call.scope : void 0;
 	if (!withdrawn && bodyHeaders === void 0 && !config.defaultHeaders && !options.headers && options.idempotencyKey === void 0) {
 		const direct = new Headers({
 			...identity,
 			accept: "application/json",
-			"user-agent": config.userAgent
+			"user-agent": config.userAgent,
+			...scope
 		});
 		if (credential !== null) direct.set(credential.name, credential.value);
 		return direct;
@@ -1316,6 +1639,7 @@ const buildRequestHeaders = (config, options, requestURL, bodyHeaders, withdrawn
 			"user-agent": config.userAgent
 		},
 		credential === null ? void 0 : { [credential.name]: credential.value },
+		scope,
 		config.defaultHeaders,
 		bodyHeaders,
 		options.headers
@@ -1323,28 +1647,55 @@ const buildRequestHeaders = (config, options, requestURL, bodyHeaders, withdrawn
 	if (withdrawn) withdrawCredentials(headers);
 	return headers;
 };
+/** The error for a provider that failed; the provider's own error is its `cause`. */
+const providerFailed = (cause) => {
+	const error = new ComposioError("The `auth` credential provider failed.");
+	Object.defineProperty(error, "cause", {
+		value: cause,
+		configurable: true,
+		writable: true
+	});
+	return error;
+};
 /**
-* The credential class this logical request authenticates with, decided once
-* from the operation the *caller* invoked.
+* The credential one logical call carries, its provider asked at most once,
+* and before any network work.
 *
-* Deliberately not re-derived per redirect hop. A hop's URL was chosen by the
-* server, so matching it back to a template would let the server's choice
-* change which of the caller's credentials goes out; the operation the caller
-* asked for is the honest answer for the whole chain, and rule 3 already
-* withdraws everything once a hop leaves the origin.
-*
-* `operation` is the match `makeRequest` already computed for the static
-* deprecated-input check, threaded in rather than re-derived: the two
-* features need the same fact, so `matchOperation` runs once per logical call
-* regardless of which of them a given client configuration actually uses.
-* With only `apiKey` set the scheme answer is still `ApiKeyAuth` down every
-* branch of {@link selectScheme}, so an existing caller's requests stay
-* byte-identical by construction; what changed is that the match itself is no
-* longer skippable, because the deprecated-input warning needs it too.
-*/
-const schemeForRequest = (config, operation) => {
-	if (!hasAlternateCredential(config.credentials)) return "ApiKeyAuth";
-	return selectScheme(operation?.schemes, config.credentials);
+* A configured credential is asked for only when the call starts on the API
+* origin: a call that starts anywhere else never carries it (rule 2), and a
+* redirect back onto the origin arrives after the chain has left it, so the
+* withdrawal holds. An operation credential is the call's own and is returned
+* as given; the origin rules still decide, per hop, whether it is sent.
+*/
+const resolveCallCredential = (config, operation, supplied, requestURL) => {
+	const choice = chooseCredential(config.auth, operation, supplied);
+	if (choice === null) return null;
+	const name = schemeHeader(choice.scheme);
+	if (choice.kind === "operation") return {
+		name,
+		value: choice.key
+	};
+	if (!sameOrigin(config.baseURL, requestURL)) return null;
+	if (typeof choice.credential === "string") return {
+		name,
+		value: choice.credential
+	};
+	const usable = (key) => {
+		if (!isUsableKey(choice.scheme, key)) throw unusableKeyError("The key the `auth` credential provider returned");
+		return {
+			name,
+			value: key
+		};
+	};
+	let key;
+	try {
+		key = choice.credential();
+	} catch (cause) {
+		throw providerFailed(cause);
+	}
+	return typeof key === "string" ? usable(key) : Promise.resolve(key).then(usable, (cause) => {
+		throw providerFailed(cause);
+	});
 };
 /**
 * One attempt: the request, plus however many redirects it takes to land on a
@@ -1362,15 +1713,14 @@ const schemeForRequest = (config, operation) => {
 * rewrite), and the query, which is left to the `Location` URL because the
 * server picked it.
 */
-const dispatchWithRedirects = async (config, options, initialURL, initialBody, initialBodyHeaders, signal, scheme) => {
+const dispatchWithRedirects = async (config, options, initialURL, initialBody, initialBodyHeaders, signal, call) => {
 	let url = initialURL;
 	let method = options.method.toUpperCase();
 	let body = initialBody;
 	let bodyHeaders = initialBodyHeaders;
 	let withdrawn = false;
-	const callerPlaced = callerPlacedCredential([config.defaultHeaders, options.headers]);
 	for (let hop = 0;; hop++) {
-		const headers = buildRequestHeaders(config, options, url, bodyHeaders, withdrawn, scheme, callerPlaced);
+		const headers = buildRequestHeaders(config, options, url, bodyHeaders, withdrawn, call);
 		const delegated = hop === 0 && !carriesCredentials(headers);
 		const init = {
 			method,
@@ -1415,6 +1765,7 @@ const dispatchWithRedirects = async (config, options, initialURL, initialBody, i
 * which is what `deprecation.ts` resolves relative `Link` targets against.
 */
 async function makeRequest(config, options) {
+	assertNoReservedHeaders(options.headers, config.reserved, "headers");
 	if (options.timeout !== void 0) validatePositiveInteger("timeout", options.timeout);
 	const maxRetries = options.maxRetries ?? config.maxRetries;
 	validatePositiveInteger("maxRetries", maxRetries);
@@ -1430,7 +1781,14 @@ async function makeRequest(config, options) {
 		url: printableURL(url, operation),
 		maxAttempts: maxRetries + 1
 	};
-	const scheme = schemeForRequest(config, operation);
+	const supplied = readOperationHeaders(options);
+	assertRequiredOperationHeaders(threaded ?? null, supplied);
+	const scope = scopeForCall(config.scope, supplied);
+	const resolving = resolveCallCredential(config, operation, supplied, url);
+	const call = {
+		scope,
+		credential: resolving instanceof Promise ? await resolving : resolving
+	};
 	if (config.onRequest !== void 0 && (threaded === void 0 || threaded.hasDeprecatedInputs === true)) config.onRequest(operation, query, options.body, buildHeaders([config.defaultHeaders, options.headers]));
 	for (let numRetries = 0;; numRetries++) {
 		if (userSignal?.aborted) throw new APIUserAbortError();
@@ -1448,7 +1806,7 @@ async function makeRequest(config, options) {
 		const timer = setTimeout(abort, timeout);
 		let result;
 		try {
-			result = await dispatchWithRedirects(config, options, url, body, bodyHeaders, controller.signal, scheme);
+			result = await dispatchWithRedirects(config, options, url, body, bodyHeaders, controller.signal, call);
 		} catch (cause) {
 			if (cause instanceof ComposioError) {
 				if (attemptLog !== void 0) emitLog(config, "info", "Request failed", {
@@ -1708,7 +2066,8 @@ const GENERATED_OPERATIONS = [
 			"consumer",
 			"listConnectedToolkits"
 		],
-		schemes: ["UserApiKeyAuth"]
+		schemes: ["UserApiKeyAuth"],
+		requiredHeaders: ["x-user-api-key", "x-org-id"]
 	},
 	{
 		method: "get",
@@ -1973,7 +2332,8 @@ const GENERATED_OPERATIONS = [
 		method: "post",
 		path: "/api/v3.1/cli/codact_failures",
 		chain: ["cli", "createCodactFailure"],
-		schemes: ["UserApiKeyAuth"]
+		schemes: ["UserApiKeyAuth"],
+		requiredHeaders: ["x-user-api-key"]
 	},
 	{
 		method: "post",
@@ -2105,7 +2465,8 @@ const GENERATED_OPERATIONS = [
 			"project",
 			"resolve"
 		],
-		schemes: ["UserApiKeyAuth"]
+		schemes: ["UserApiKeyAuth"],
+		requiredHeaders: ["x-user-api-key", "x-org-id"]
 	},
 	{
 		method: "post",
@@ -2345,4 +2706,4 @@ const generatedOperation = (chainKey) => {
 };
 
 //#endregion
-export { parseHTTPURL as A, inspectDeprecatedInputs as C, assertCredentialTransport as D, SCHEME_HEADERS as E, buildHeaders as M, mergeHeaders as N, callerPlacedCredential as O, VERSION as S, matchOperation as T, schemeForRequest as _, TOO_MANY_REDIRECTS as a, withOperation as b, buildURL as c, path as d, printableURL as f, safeJSON as g, rewriteForRedirect as h, REDIRECT_STATUSES as i, resolveHTTPURL as j, carriesCredentials as k, castToError as l, retryDelayMillis as m, generatedOperation as n, buildBody as o, readOperation as p, OPAQUE_REDIRECT as r, buildRequestHeaders as s, GENERATED_OPERATIONS as t, makeRequest as u, shouldRetryResponse as v, inspectDeprecation as w, createFetchTransport as x, validatePositiveInteger as y };
+export { Auth as A, unusableKeyError as B, resolveIdentity as C, inspectDeprecatedInputs as D, mergeHeaders as E, chooseCredential as F, resolveHTTPURL as G, assertCredentialTransport as H, isUsableKey as I, sameOrigin as K, resolveAuth as L, assertRequiredOperationHeaders as M, authConstructors as N, inspectDeprecation as O, authFromCredentials as P, resolveScope as R, reservedHeaders as S, buildHeaders as T, carriesCredentials as U, SCHEME_HEADERS as V, parseHTTPURL as W, shouldRetryResponse as _, TOO_MANY_REDIRECTS as a, createFetchTransport as b, buildURL as c, path as d, printableURL as f, safeJSON as g, rewriteForRedirect as h, REDIRECT_STATUSES as i, assertNoRemovedCredentialOptions as j, matchOperation as k, castToError as l, retryDelayMillis as m, generatedOperation as n, buildBody as o, readOperation as p, schemeHeader as q, OPAQUE_REDIRECT as r, buildRequestHeaders as s, GENERATED_OPERATIONS as t, makeRequest as u, validatePositiveInteger as v, VERSION as w, assertNoReservedHeaders as x, withOperation as y, scopeForCall as z };