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

package/README.md

@@ -6,17 +6,58 @@ This repo is the successor to the Stainless-generated [`@composio/client`](https
 
 ## Usage
 
-The package root is the Stainless-compatible drop-in surface: `new Composio({ apiKey })`, the Stainless type names, and throwing `APIPromise` semantics (shipped via UXE-163/UXE-164).
+The package root is the Promise client: `new Composio({ auth })`, the Stainless type names, and throwing `APIPromise` semantics (shipped via UXE-163/UXE-164).
 
 ```ts
-import Composio from '@composio/client'
+import Composio, { Auth } from '@composio/client'
 
-const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY })
+const composio = new Composio({ auth: Auth.project(process.env.COMPOSIO_API_KEY!) })
 
 const session = await composio.toolRouter.session.create({ user_id: 'user_123' })
 console.log(session.session_id, session.mcp.url)
 ```
 
+### Authentication and scope
+
+`auth` is required and says how every request authenticates. A request carries at most one Composio
+credential.
+
+| `auth` | Sends |
+| --- | --- |
+| `Auth.project(key)` | `x-api-key` on every request to the API origin |
+| `Auth.user(key)` | `x-user-api-key` on every request to the API origin |
+| `Auth.organization(key)` | `x-org-api-key` on every request to the API origin |
+| `Auth.auto({ project, user, organization })` | one of the keys given, chosen per operation: the project key wherever the operation accepts it, otherwise the first scheme it declares that a key is given for. This is how releases before rc.18 chose |
+| `Auth.none()` | no credential. The credential header names are then ordinary headers, for a client used as a transport for schemes it does not model |
+
+A fixed mode never consults the operation table. A key may be a function that returns one (or a
+promise of one): it is called once per call, after the call starts, and its key is reused across
+retries and same-origin redirects. It is not called for a call that starts off the API origin.
+`client.authMode` reads the mode back; the client never returns a credential it was given as a
+function.
+
+`scope` names the organization and project the client addresses, sent as `x-org-id` and
+`x-project-id` on requests to the API origin: `{ organizationId }`, `{ projectId }`, or both.
+
+```ts
+const composio = new Composio({
+  auth: Auth.user(() => vault.read('composio-user-key')),
+  scope: { organizationId: 'org_123', projectId: 'pr_456' },
+})
+```
+
+A header name is reserved while something is configured to write it: the three credential names
+while `auth` is not `none`, `x-org-id` and `x-project-id` while `scope` is set, and the identity
+names as [below](#identify-the-calling-product). `defaultHeaders` and `COMPOSIO_CUSTOM_HEADERS` that
+name a reserved header fail construction, and a call's `headers` that name one fail the call before
+anything is sent. A client that needs another credential or scope derives one:
+`composio.withOptions({ auth: Auth.project(key) })`. `withOptions` re-runs every construction check.
+
+Three operations declare a credential or scope id as a header parameter
+(`org.consumer.project.resolve`, `org.consumer.listConnectedToolkits`, `cli.createCodactFailure`).
+Their signatures are unchanged: the value replaces the configured credential for that call, and an
+`x-org-id` that disagrees with the configured `scope` fails the call.
+
 ### Pagination
 
 Use the `@composio/client/pagination` subpath to traverse list operations that return the standard
@@ -65,28 +106,30 @@ cursor ends traversal. When a response omits `next_cursor` but numeric `current_
 returning partial results; provide a custom adapter for that response shape. Requests are sequential
 and inherit the normal client retry/backoff path, but this is not proactive/shared rate-limit pacing.
 
-Use `fromEnv` when configuration must come from a specific environment snapshot instead of the
-host process. Explicit options replace mapped values, so this is safe for tests, workers, and
-applications that load configuration themselves:
+The constructor reads nothing from the process. `Composio.fromEnv` is the one reader of the
+environment, and it reads the mapping it is handed:
 
 ```ts
-const composio = Composio.fromEnv(config, { environment: 'staging' })
+const composio = Composio.fromEnv(process.env, { environment: 'staging' })
 ```
 
-`fromEnv` recognizes `COMPOSIO_API_KEY`, `COMPOSIO_USER_API_KEY`, `COMPOSIO_ORG_API_KEY`,
-`COMPOSIO_BASE_URL`, `COMPOSIO_ALLOW_INSECURE_HTTP`, `COMPOSIO_CUSTOM_HEADERS`, and
-`COMPOSIO_LOG_LEVEL`. Derived clients created with `withOptions()` keep using the resolved snapshot and do
-not fall back to ambient values.
+`fromEnv` reads `COMPOSIO_API_KEY`, `COMPOSIO_USER_API_KEY` and `COMPOSIO_ORG_API_KEY` into `auth`
+(one set: that fixed mode; several: `Auth.auto`; none: `Auth.none()`), and `COMPOSIO_BASE_URL`,
+`COMPOSIO_ALLOW_INSECURE_HTTP=1`, `COMPOSIO_CUSTOM_HEADERS` (as `defaultHeaders`) and
+`COMPOSIO_LOG_LEVEL`. It does not read `COMPOSIO_ORG_ID` or `COMPOSIO_PROJECT_ID`: `scope` is always
+an argument. An override replaces the whole field it names, so `{ auth: Auth.none() }` means none
+whatever the mapping holds. Derived clients created with `withOptions()` keep using the resolved
+snapshot.
 
 Inject a `Transport` when an application or test needs to own HTTP dispatch. The transport receives
 a complete `Request`; retries, credential-safe redirects, timeouts, and response parsing stay in the
 client:
 
 ```ts
-import Composio, { createFetchTransport } from '@composio/client'
+import Composio, { Auth, createFetchTransport } from '@composio/client'
 
 const transport = createFetchTransport({ fetch: instrumentedFetch })
-const composio = new Composio({ apiKey, transport })
+const composio = new Composio({ auth: Auth.project(apiKey), transport })
 ```
 
 Without a `transport`, the client resolves `globalThis.fetch` when a request is sent, so late
@@ -133,13 +176,13 @@ subpaths never import it and load without it.
 ```ts
 import { Effect, Layer } from 'effect'
 import * as FetchHttpClient from 'effect/http/FetchHttpClient'
-import { ComposioClient, layer, layerConfig, layerFetch } from '@composio/client/effect'
+import { Auth, ComposioClient, layer, layerConfig, layerFetch } from '@composio/client/effect'
 
 // Explicit options, over a fetch-backed `HttpClient` the layer brings with it.
-const live = layerFetch({ apiKey: 'your-api-key' })
+const live = layerFetch({ auth: Auth.project('your-api-key') })
 
 // Explicit options, over the `HttpClient` the application provides.
-const overMyTransport = layer({ apiKey: 'your-api-key' }).pipe(Layer.provide(FetchHttpClient.layer))
+const overMyTransport = layer({ auth: Auth.project('your-api-key') }).pipe(Layer.provide(FetchHttpClient.layer))
 
 // Options read from the `COMPOSIO_*` settings.
 const fromConfig = layerConfig().pipe(Layer.provide(FetchHttpClient.layer))
@@ -156,15 +199,24 @@ const slug: Promise<string> = Effect.runPromise(program.pipe(Effect.provide(live
 `make(options, httpClient)` builds the same client synchronously from an `HttpClient` you already
 hold, and throws where the layers fail.
 
-Only `layerConfig` reads the environment. It reads `COMPOSIO_API_KEY`, `COMPOSIO_USER_API_KEY`,
-`COMPOSIO_ORG_API_KEY`, `COMPOSIO_BASE_URL` and `COMPOSIO_ALLOW_INSECURE_HTTP=1` through Effect's
-`Config`, so the `ConfigProvider` in context decides where they come from; by default that is the
-process environment. An option passed to `layerConfig` wins over its setting, and `null` for a
-credential means none, whatever is configured. `make`, `layer` and `layerFetch` read nothing.
-
-A credential option takes a `string` or a `Redacted<string>`. Construction fails with a
-`ConfigurationError` when a credentialed origin is not HTTPS (loopback and `allowInsecureHTTP`
-excepted, as on the root client), or when `decode: true` is given without `schemas`.
+`auth` and `scope` mean what they mean on the root client (see
+[Authentication and scope](#authentication-and-scope)), and `Auth` is exported from
+`@composio/client/effect` too. A key may also be a `Redacted<string>`, or a function returning a
+string or a `Redacted<string>`. There is no `withOptions`: a client is a value, and a caller that
+needs another credential calls `make` again with the same `HttpClient`.
+
+Only `layerConfig` reads the environment. It reads `COMPOSIO_API_KEY`, `COMPOSIO_USER_API_KEY` and
+`COMPOSIO_ORG_API_KEY` into `auth` by the rule `Composio.fromEnv` applies, each key `Redacted`
+throughout, and `COMPOSIO_BASE_URL` and `COMPOSIO_ALLOW_INSECURE_HTTP=1`, through Effect's `Config`,
+so the `ConfigProvider` in context decides where they come from; by default that is the process
+environment. An option passed to `layerConfig` replaces the setting it names, so
+`layerConfig({ auth: Auth.none() })` means none whatever is configured. `make`, `layer` and
+`layerFetch` read nothing.
+
+Construction fails with a `ConfigurationError` when a credentialed origin is not HTTPS (loopback and
+`allowInsecureHTTP` excepted, as on the root client), when a key or a header option is refused, or
+when `decode: true` is given without `schemas`. A credential provider that fails, or returns
+something a header cannot carry, fails the call with a `ConfigurationError` before anything is sent.
 
 The resources are plain objects of functions, not classes, so a method can be passed around without
 binding. One thing on the root client has no counterpart here: the resources that hold no operation
@@ -287,7 +339,7 @@ import { make } from '@composio/client/effect'
 import { schemaLoaders } from '@composio/client/effect/schemas'
 
 const checkedCategories = (httpClient: HttpClient.HttpClient) => {
-  const composio = make({ apiKey: 'your-api-key', schemas: schemaLoaders }, httpClient)
+  const composio = make({ auth: Auth.project('your-api-key'), schemas: schemaLoaders }, httpClient)
   return composio.toolkits.retrieveCategories({ decode: true }).pipe(
     Effect.catchTag('@composio/client/DecodeError', (error) =>
       Effect.logError(`${error.operation}: ${JSON.stringify(error.issues)}`).pipe(Effect.as(null)),
@@ -345,10 +397,10 @@ top of the span itself.
 
 ### Credentials and redaction
 
-A request carries one credential header, chosen per operation as on the root client: `x-api-key`,
-`x-user-api-key` or `x-org-api-key`. The client holds all three as `Redacted` values and adds all
-three header names to Effect's redaction list for its requests, so spans and renderings of a request
-show `<redacted>`; Effect's own list knows only `x-api-key`.
+A request carries at most one credential header, chosen by `auth` as on the root client:
+`x-api-key`, `x-user-api-key` or `x-org-api-key`. The client holds every key as a `Redacted` value
+and adds all three header names to Effect's redaction list for its requests, so spans and renderings
+of a request show `<redacted>`; Effect's own list knows only `x-api-key`.
 
 No error the client produces holds the request, the transport's error or a credential value. One
 caveat: `APIConnectionError.description` is the transport's own message text, copied. A transport
@@ -432,6 +484,37 @@ decodes, then with the loader table and every schema it reaches.
 of which 2.1 MB and 328 files are `dist/effect/schemas*`, against 1.1 MB in 176 files for
 `2.0.0-rc.11` as published. None of it is on the root entry's import path.
 
+### Identify the calling product
+
+A product built on the client passes `identity` instead of setting headers by hand. The root client
+and `./effect` take the same option:
+
+```ts
+const composio = new Composio({
+  auth: Auth.project(apiKey),
+  identity: { product: '@composio/core', version: '0.9.0', source: 'TYPESCRIPT_SDK', framework: 'openai' },
+})
+```
+
+| Header | Sent from | Without `identity` |
+| --- | --- | --- |
+| `x-client-provenance`, `x-client-version` | `product`, `version` | the package name and version |
+| `x-sdk-version` | `version` | not sent |
+| `x-source`, `x-framework` | `source`, `framework` | not sent |
+| `x-runtime` | `runtime`, else the detected runtime | the detected runtime |
+| `x-client-runtime`, `x-runtime-version` | the detected runtime | the detected runtime |
+| `x-client-library`, `x-client-library-version`, `x-client-language` | the package | the package |
+
+The three library headers are the package's own: `defaultHeaders`, `COMPOSIO_CUSTOM_HEADERS` and a
+call's `headers` cannot set or delete them. Once `identity` is set, the same holds for every header
+in the table. A refused name fails construction (`ComposioError`, or `ConfigurationError` on
+`./effect`), or the call before anything is sent. Identity values must be non-empty printable ASCII
+with no surrounding whitespace, and are sent to the configured API origin only.
+
+The detected runtime is one of `nodejs`, `bun`, `deno`, `cloudflare`, `vercel_edge`, `netlify`,
+`fastly` or `unknown`, checked in [`std-env`](https://github.com/unjs/std-env)'s order; the
+Python client always reports `python`.
+
 ## Upgrade from Stainless 0.1.x to 2.0
 
 By default, the 2.0 client refuses to send credentials over plain HTTP unless the hostname is
@@ -440,13 +523,13 @@ configured origin:
 
 ```ts
 const composio = new Composio({
-  apiKey,
+  auth: Auth.project(apiKey),
   baseURL: 'http://host.docker.internal:9900',
   allowInsecureHTTP: true,
 })
 ```
 
-The equivalent environment configuration is:
+The equivalent environment configuration, for `Composio.fromEnv`, is:
 
 ```sh
 COMPOSIO_BASE_URL=http://host.docker.internal:9900 \
@@ -457,6 +540,37 @@ The opt-in records the resolved scheme, hostname, and port. Mutating `baseURL` c
 and `withOptions({ baseURL: ... })` requires `allowInsecureHTTP: true` again when the origin
 changes. Redirects to another origin remain credential-free.
 
+### Removed in 2.0.0-rc.18
+
+Each removal is a declared entry in `packages/codegen/assignability-ledger.json`. The other rows are
+behaviour the type check cannot see, listed so an upgrade can find them.
+
+| Removed | Migration |
+| --- | --- |
+| `apiKey` (root `ClientOptions` and `./effect` `ComposioClientOptions`) | `auth: Auth.project(key)` |
+| `userApiKey` | `auth: Auth.user(key)`, which sends the user key on every request. The old per-operation selection is `Auth.auto({ project, user, organization })` |
+| `orgApiKey` | `auth: Auth.organization(key)`, or `Auth.auto({ ... })` |
+| `apiKey: null` plus a credential in `defaultHeaders` | the `auth` that credential is. While `auth` is not `none`, `defaultHeaders`, `COMPOSIO_CUSTOM_HEADERS` and a call's `headers` cannot name `x-api-key`, `x-user-api-key` or `x-org-api-key` |
+| `x-api-key` overriding the credential for one call | a second client: `withOptions({ auth: Auth.project(key) })` on the root, `make({ ...options, auth: Auth.project(key) }, httpClient)` on `./effect` |
+| `x-org-id`, `x-project-id` in `defaultHeaders` | `scope: { organizationId, projectId }`, which reserves both names. Without `scope` they are still ordinary headers |
+| the constructor reading `COMPOSIO_*` from the process | `Composio.fromEnv(process.env, overrides)`; nothing else reads the environment. `new Composio()` with no options is gone with it |
+| `layerConfig({ apiKey: null })` | `layerConfig({ auth: Auth.none() })`; an override replaces the whole `auth` |
+| `layer()`, `layerFetch()` with no options | pass the options, `auth` included |
+| assigning `client.apiKey`, `userApiKey` or `orgApiKey` | `withOptions({ auth })`. The three fields stay readable until rc.19 and read the string keys `auth` holds; keep your own copy of a key you need |
+| `Credential` on `./effect` accepting `null` | `Auth.none()`. It now also accepts a function that returns a key |
+
+Python makes the same change: `auth=ProjectAuth(key)` (and `UserAuth`, `OrganizationAuth`,
+`AutoAuth`, `NoAuth`) and `scope=Scope(...)`, see [`python/README.md`](./python/README.md).
+
+### Changed in 2.0.0-rc.17
+
+`defaultHeaders`, `COMPOSIO_CUSTOM_HEADERS` and per-call `headers` refuse the library headers
+(`x-client-library`, `x-client-library-version`, `x-client-language`), and refuse every identity
+header once `identity` is set. A wrapper that set its product headers through `defaultHeaders`
+moves them into `identity` (see [Identify the calling product](#identify-the-calling-product)).
+Python takes `identity=ClientIdentity(...)` under the same rule. The type surface is unchanged
+apart from the added option, so the release declares no ledger entry.
+
 ### Removed in 2.0.0-rc.16
 
 Each row is a declared entry in `packages/codegen/assignability-ledger.json`, the list of what a

package/dist/{api-key-revocation-CvGpd3Rw.mjs → api-key-revocation-JkA4sOGH.mjs}

@@ -1,4 +1,4 @@
-import { b as withOperation, n as generatedOperation } from "./generated-operations-DrhN6W_k.mjs";
+import { n as generatedOperation, y as withOperation } from "./generated-operations-DKgGT6Dg.mjs";
 
 //#region src/compat/resources/api-key-revocation.ts
 const OP_CREATE = generatedOperation("apiKeyRevocation.create");

package/dist/{auth-C0IYTv5D.mjs → auth-B_K-wdMm.mjs}

@@ -1,4 +1,4 @@
-import { t as Session } from "./session-CtO_BX-m.mjs";
+import { t as Session } from "./session-BT5NJfbm.mjs";
 
 //#region src/compat/resources/auth/auth.ts
 /**

package/dist/{auth-configs-COmbnKYx.mjs → auth-configs-RAgN782Z.mjs}

@@ -1,4 +1,4 @@
-import { b as withOperation, d as path, n as generatedOperation } from "./generated-operations-DrhN6W_k.mjs";
+import { d as path, n as generatedOperation, y as withOperation } from "./generated-operations-DKgGT6Dg.mjs";
 
 //#region src/compat/resources/auth-configs.ts
 const OP_CREATE = generatedOperation("authConfigs.create");

package/dist/{clanker-hE4FKPjg.mjs → clanker-Pgyyh95r.mjs}

@@ -1,4 +1,4 @@
-import { b as withOperation, n as generatedOperation } from "./generated-operations-DrhN6W_k.mjs";
+import { n as generatedOperation, y as withOperation } from "./generated-operations-DKgGT6Dg.mjs";
 
 //#region src/compat/resources/org/clanker.ts
 const OP_CREATE_CLAIM = generatedOperation("org.clanker.createClaim");

package/dist/{cli-CuFaxvp4.mjs → cli-Ca5bRiEN.mjs}

@@ -1,5 +1,5 @@
-import { N as mergeHeaders, b as withOperation, n as generatedOperation } from "./generated-operations-DrhN6W_k.mjs";
-import { t as Realtime } from "./realtime-DQ_gT0q7.mjs";
+import { n as generatedOperation, y as withOperation } from "./generated-operations-DKgGT6Dg.mjs";
+import { t as Realtime } from "./realtime-W-lJ0Vcs.mjs";
 
 //#region src/compat/resources/cli/cli.ts
 const OP_CREATE_CODACT_FAILURE = generatedOperation("cli.createCodactFailure");
@@ -22,9 +22,8 @@ var Cli = class {
 		const { "x-user-api-key": xUserApiKey, ...body } = params;
 		return this.#client.post("/api/v3.1/cli/codact_failures", withOperation(OP_CREATE_CODACT_FAILURE, {
 			body,
-			...options,
-			headers: mergeHeaders([{ ...xUserApiKey != null ? { "x-user-api-key": xUserApiKey } : void 0 }, options?.headers])
-		}));
+			...options
+		}, { "x-user-api-key": xUserApiKey }));
 	}
 	createSession(body = {}, options) {
 		return this.#client.post("/api/v3.1/cli/create-session", withOperation(OP_CREATE_SESSION, {

package/dist/{connected-accounts-BmbcAhdS.mjs → connected-accounts-D6NTwvbi.mjs}

@@ -1,4 +1,4 @@
-import { b as withOperation, d as path, n as generatedOperation } from "./generated-operations-DrhN6W_k.mjs";
+import { d as path, n as generatedOperation, y as withOperation } from "./generated-operations-DKgGT6Dg.mjs";
 
 //#region src/compat/resources/connected-accounts.ts
 const OP_CREATE = generatedOperation("connectedAccounts.create");

package/dist/{consumer-BaJgJBXQ.mjs → consumer-BP4OyJS0.mjs}

@@ -1,5 +1,5 @@
-import { N as mergeHeaders, b as withOperation, n as generatedOperation } from "./generated-operations-DrhN6W_k.mjs";
-import { t as Project } from "./project-7LL6W_tc.mjs";
+import { n as generatedOperation, y as withOperation } from "./generated-operations-DKgGT6Dg.mjs";
+import { t as Project } from "./project-C_YZ-eLI.mjs";
 
 //#region src/compat/resources/org/consumer/consumer.ts
 const OP_LIST_CONNECTED_TOOLKITS = generatedOperation("org.consumer.listConnectedToolkits");
@@ -20,11 +20,10 @@ var Consumer = class {
 		const { "x-user-api-key": xUserApiKey, "x-org-id": xOrgId, ...query } = params;
 		return this.#client.get("/api/v3.1/org/consumer/connected_toolkits", withOperation(OP_LIST_CONNECTED_TOOLKITS, {
 			query,
-			...options,
-			headers: mergeHeaders([{
-				...xUserApiKey != null ? { "x-user-api-key": xUserApiKey } : void 0,
-				...xOrgId != null ? { "x-org-id": xOrgId } : void 0
-			}, options?.headers])
+			...options
+		}, {
+			"x-user-api-key": xUserApiKey,
+			"x-org-id": xOrgId
 		}));
 	}
 };

package/dist/{custom-DIJbIQGR.mjs → custom-BBr7KbCv.mjs}

@@ -1,4 +1,4 @@
-import { b as withOperation, n as generatedOperation } from "./generated-operations-DrhN6W_k.mjs";
+import { n as generatedOperation, y as withOperation } from "./generated-operations-DKgGT6Dg.mjs";
 
 //#region src/compat/resources/mcp/custom.ts
 const OP_CREATE = generatedOperation("mcp.custom.create");

package/dist/{custom-DbEv7dUC.mjs → custom-DA3ABHnI.mjs}

@@ -1,4 +1,4 @@
-import { b as withOperation, d as path, n as generatedOperation } from "./generated-operations-DrhN6W_k.mjs";
+import { d as path, n as generatedOperation, y as withOperation } from "./generated-operations-DKgGT6Dg.mjs";
 
 //#region src/compat/resources/custom.ts
 const OP_DELETE_TOOLKIT = generatedOperation("custom.deleteToolkit");

package/dist/effect.d.mts

@@ -1,5 +1,5 @@
-import { $ as ProjectRegenerateAPIKeyResponse, $n as ToolkitRetrieveChangelogResponse, $r as SessionCreateResponse, $t as McpCreateInstanceParams, A as ClankerCreateClaimResponse, An as TriggersTypeListParams, Ar as FileListResponse$1, At as LogRetrieveToolExecutionResponse, B as ConsumerListConnectedToolkitsParams, Bn as AuthConfigListParams, Br as ToolRetrieveEnumResponse, Ci as FileDeleteResponse, Cn as TriggerInstanceUpsertParams, Cr as ConnectedAccountRevokeResponse, D as OrgListResponse, Dn as ManageDeleteResponse, Dr as FileCreatePresignedURLParams, Dt as UsageRetrieveSummaryResponse, E as OrgListParams, Et as UsageRetrieveSummaryParams, F as UsageRetrieveSummaryResponse$1, Fi as APIErrorBody, Fr as ToolGetInputResponse, Ft as ToolRetrieveResponse$1, Gn as AuthConfigUpdateStatusParams, Gt as CliCreateSessionResponse, Hn as AuthConfigRetrieveResponse, Hr as ToolRetrieveRequiredScopesParams, Ht as CliCreateCodactFailureParams, In as AuthConfigCreateParams, Ir as ToolListParams, J as ProjectCreateResponse, Jn as ToolkitListParams, Jr as SessionAttachParams, Kn as AuthConfigUpdateStatusResponse, Kt as CliGetSessionParams, L as ProjectListParams$1, Ln as AuthConfigCreateResponse, Lr as ToolListResponse, Lt as TriggerListParams, M as UsageRetrieveParams$1, Mn as TriggersTypeRetrieveEnumResponse, Mr as ToolExecuteParams, Mt as ToolListFieldsResponse, N as UsageRetrieveResponse$1, Nn as TriggersTypeRetrieveParams, Nr as ToolExecuteResponse, Nt as ToolListParams$1, On as ManageUpdateParams, Or as FileCreatePresignedURLResponse, Ot as LogCreateToolExecutionParams, P as UsageRetrieveSummaryParams$1, Pn as TriggersTypeRetrieveResponse, Pr as ToolGetInputParams, Pt as ToolListResponse$1, Q as ProjectListResponse, Qn as ToolkitRetrieveCategoriesResponse, Qr as SessionCreateParams, R as ProjectListResponse$1, Rn as AuthConfigDeleteParams, Rr as ToolProxyParams, Rt as TriggerListResponse, Si as FileDeleteParams, Sn as TriggerInstanceListActiveResponse, Sr as ConnectedAccountRetrieveResponse, Ti as FileListResponse, Tr as ConnectedAccountUpdateStatusResponse, Tt as UsageRetrieveResponse, U as ProjectResolveParams, Un as AuthConfigUpdateParams, Ur as ToolRetrieveRequiredScopesResponse, Ut as CliCreateCodactFailureResponse, V as ConsumerListConnectedToolkitsResponse, Vn as AuthConfigListResponse, Vr as ToolRetrieveParams, W as ProjectResolveResponse, Wn as AuthConfigUpdateResponse, Wr as ToolRetrieveResponse, Wt as CliCreateSessionParams, X as ProjectDeleteResponse, Xn as ToolkitRecommendScopesParams, Xr as SessionConfigHistoryParams, Xt as RealtimeAuthResponse, Y as ProjectDeleteParams, Yn as ToolkitListResponse, Yr as SessionAttachResponse, Yt as RealtimeAuthParams, Z as ProjectListParams, Zn as ToolkitRecommendScopesResponse, Zr as SessionConfigHistoryResponse, Zt as RealtimeCredentialsResponse, _ as CustomUpsertParams, _i as SessionToolsResponse, _n as GenerateURLResponse, _r as ConnectedAccountListResponse, _t as WebhookSubscriptionRetrieveResponse, ai as SessionLinkParams, an as McpDeleteResponse, ar as ToolkitRetrieveScopesGrantContextResponse, at as WebhookEndpointReplaceParams, b as ApiKeyRevocationCreateParams, bi as FileCreateUploadURLParams, bn as CustomCreateResponse, br as ConnectedAccountRefreshParams, bt as WebhookSubscriptionUpdateResponse, ci as SessionPatchResponse, cn as McpListParams, cr as LinkCreateParams, ct as WebhookEndpointUpdateParams, d as KeyringListTransferKeysResponse, di as SessionRetrieveResponse, dn as McpRetrieveAppResponse, dr as ConnectedAccountCompleteAuthResponse, dt as WebhookSubscriptionCreateParams, ei as SessionDeleteResponse, en as McpCreateInstanceResponse, er as ToolkitRetrieveMultiParams, et as ProjectRetrieveResponse, fi as SessionSearchParams, fn as McpRetrieveResponse, fr as ConnectedAccountCreateParams, ft as WebhookSubscriptionCreateResponse, g as CustomSyncResponse, gi as SessionToolsParams, gn as GenerateURLParams, gr as ConnectedAccountListParams, gt as WebhookSubscriptionListResponse, h as CustomSyncParams, hi as SessionToolkitsResponse, hr as ConnectedAccountDeleteResponse, ht as WebhookSubscriptionListParams, i as SessionConfigsRetrieveResponse, ii as SessionExecuteResponse, in as McpDeleteInstanceResponse, ir as ToolkitRetrieveScopesGrantContextParams, it as WebhookEndpointListResponse, ji as HeadersLike, jn as TriggersTypeListResponse, k as ClankerCreateClaimParams, kn as ManageUpdateResponse, kr as FileListParams$1, kt as LogCreateToolExecutionResponse, li as SessionProxyExecuteParams, ln as McpListResponse, lr as LinkCreateResponse, lt as WebhookEndpointUpdateResponse, m as CustomDeleteToolkitResponse, mi as SessionToolkitsParams, mn as McpUpdateResponse, mr as ConnectedAccountDeleteParams, mt as WebhookSubscriptionListEventTypesResponse, n as SessionConfigsListParams, ni as SessionExecuteMetaResponse, nn as McpCreateResponse, nr as ToolkitRetrieveParams, nt as WebhookEndpointCreateResponse, oi as SessionLinkResponse, on as McpListInstancesParams, ot as WebhookEndpointReplaceResponse, p as CustomDeleteToolkitParams, pi as SessionSearchResponse, pn as McpUpdateParams, pr as ConnectedAccountCreateResponse, pt as WebhookSubscriptionDeleteResponse, q as ProjectCreateParams, qt as CliGetSessionResponse, r as SessionConfigsListResponse, ri as SessionExecuteParams, rn as McpDeleteInstanceParams, rr as ToolkitRetrieveResponse, rt as WebhookEndpointListParams, si as SessionPatchParams, sn as McpListInstancesResponse, st as WebhookEndpointRetrieveResponse, ti as SessionExecuteMetaParams, tn as McpCreateParams, tr as ToolkitRetrieveMultiResponse, tt as WebhookEndpointCreateParams, ui as SessionProxyExecuteResponse, un as McpRetrieveAppParams, ur as ConnectedAccountCompleteAuthParams, v as CustomUpsertResponse, vi as FileCreateDownloadURLParams, vr as ConnectedAccountPatchParams, vt as WebhookSubscriptionRotateSecretResponse, w as SessionRetrieveInfoResponse, wi as FileListParams, wn as TriggerInstanceUpsertResponse, wr as ConnectedAccountUpdateStatusParams, wt as UsageRetrieveParams, x as ApiKeyRevocationCreateResponse, xi as FileCreateUploadURLResponse, xn as TriggerInstanceListActiveParams, xr as ConnectedAccountRefreshResponse, yi as FileCreateDownloadURLResponse, yn as CustomCreateParams, yr as ConnectedAccountPatchResponse, yt as WebhookSubscriptionUpdateParams, zn as AuthConfigDeleteResponse, zr as ToolProxyResponse, zt as TriggerRetrieveResponse } from "./session-configs-C_A0gUf5.mjs";
-import { t as VERSION } from "./version-BkHUhokz.mjs";
+import { $ as ProjectRegenerateAPIKeyResponse, $i as HeadersLike, $n as ToolkitRetrieveChangelogResponse, $r as SessionCreateResponse, $t as McpCreateInstanceParams, A as ClankerCreateClaimResponse, Ai as AuthOf, An as TriggersTypeListParams, Ar as FileListResponse$1, At as LogRetrieveToolExecutionResponse, B as ConsumerListConnectedToolkitsParams, Bn as AuthConfigListParams, Br as ToolRetrieveEnumResponse, Ci as FileDeleteResponse, Cn as TriggerInstanceUpsertParams, Cr as ConnectedAccountRevokeResponse, D as OrgListResponse, Dn as ManageDeleteResponse, Dr as FileCreatePresignedURLParams, Dt as UsageRetrieveSummaryResponse, E as OrgListParams, Et as UsageRetrieveSummaryParams, F as UsageRetrieveSummaryResponse$1, Fr as ToolGetInputResponse, Ft as ToolRetrieveResponse$1, Gn as AuthConfigUpdateStatusParams, Gt as CliCreateSessionResponse, Hn as AuthConfigRetrieveResponse, Hr as ToolRetrieveRequiredScopesParams, Ht as CliCreateCodactFailureParams, In as AuthConfigCreateParams, Ir as ToolListParams, J as ProjectCreateResponse, Jn as ToolkitListParams, Jr as SessionAttachParams, Kn as AuthConfigUpdateStatusResponse, Kt as CliGetSessionParams, L as ProjectListParams$1, Li as APIErrorBody, Ln as AuthConfigCreateResponse, Lr as ToolListResponse, Lt as TriggerListParams, M as UsageRetrieveParams$1, Mn as TriggersTypeRetrieveEnumResponse, Mr as ToolExecuteParams, Mt as ToolListFieldsResponse, N as UsageRetrieveResponse$1, Ni as Scope, Nn as TriggersTypeRetrieveParams, Nr as ToolExecuteResponse, Nt as ToolListParams$1, Oi as AuthConstructors, On as ManageUpdateParams, Or as FileCreatePresignedURLResponse, Ot as LogCreateToolExecutionParams, P as UsageRetrieveSummaryParams$1, Pn as TriggersTypeRetrieveResponse, Pr as ToolGetInputParams, Pt as ToolListResponse$1, Q as ProjectListResponse, Qi as ClientIdentity, Qn as ToolkitRetrieveCategoriesResponse, Qr as SessionCreateParams, R as ProjectListResponse$1, Rn as AuthConfigDeleteParams, Rr as ToolProxyParams, Rt as TriggerListResponse, Si as FileDeleteParams, Sn as TriggerInstanceListActiveResponse, Sr as ConnectedAccountRetrieveResponse, Ti as FileListResponse, Tr as ConnectedAccountUpdateStatusResponse, Tt as UsageRetrieveResponse, U as ProjectResolveParams, Un as AuthConfigUpdateParams, Ur as ToolRetrieveRequiredScopesResponse, Ut as CliCreateCodactFailureResponse, V as ConsumerListConnectedToolkitsResponse, Vn as AuthConfigListResponse, Vr as ToolRetrieveParams, W as ProjectResolveResponse, Wn as AuthConfigUpdateResponse, Wr as ToolRetrieveResponse, Wt as CliCreateSessionParams, X as ProjectDeleteResponse, Xn as ToolkitRecommendScopesParams, Xr as SessionConfigHistoryParams, Xt as RealtimeAuthResponse, Y as ProjectDeleteParams, Yn as ToolkitListResponse, Yr as SessionAttachResponse, Yt as RealtimeAuthParams, Z as ProjectListParams, Zn as ToolkitRecommendScopesResponse, Zr as SessionConfigHistoryResponse, Zt as RealtimeCredentialsResponse, _ as CustomUpsertParams, _i as SessionToolsResponse, _n as GenerateURLResponse, _r as ConnectedAccountListResponse, _t as WebhookSubscriptionRetrieveResponse, ai as SessionLinkParams, an as McpDeleteResponse, ar as ToolkitRetrieveScopesGrantContextResponse, at as WebhookEndpointReplaceParams, b as ApiKeyRevocationCreateParams, bi as FileCreateUploadURLParams, bn as CustomCreateResponse, br as ConnectedAccountRefreshParams, bt as WebhookSubscriptionUpdateResponse, ci as SessionPatchResponse, cn as McpListParams, cr as LinkCreateParams, ct as WebhookEndpointUpdateParams, d as KeyringListTransferKeysResponse, di as SessionRetrieveResponse, dn as McpRetrieveAppResponse, dr as ConnectedAccountCompleteAuthResponse, dt as WebhookSubscriptionCreateParams, ei as SessionDeleteResponse, en as McpCreateInstanceResponse, er as ToolkitRetrieveMultiParams, et as ProjectRetrieveResponse, fi as SessionSearchParams, fn as McpRetrieveResponse, fr as ConnectedAccountCreateParams, ft as WebhookSubscriptionCreateResponse, g as CustomSyncResponse, gi as SessionToolsParams, gn as GenerateURLParams, gr as ConnectedAccountListParams, gt as WebhookSubscriptionListResponse, h as CustomSyncParams, hi as SessionToolkitsResponse, hr as ConnectedAccountDeleteResponse, ht as WebhookSubscriptionListParams, i as SessionConfigsRetrieveResponse, ii as SessionExecuteResponse, in as McpDeleteInstanceResponse, ir as ToolkitRetrieveScopesGrantContextParams, it as WebhookEndpointListResponse, ji as AutoCredentials, jn as TriggersTypeListResponse, k as ClankerCreateClaimParams, kn as ManageUpdateResponse, kr as FileListParams$1, kt as LogCreateToolExecutionResponse, li as SessionProxyExecuteParams, ln as McpListResponse, lr as LinkCreateResponse, lt as WebhookEndpointUpdateResponse, m as CustomDeleteToolkitResponse, mi as SessionToolkitsParams, mn as McpUpdateResponse, mr as ConnectedAccountDeleteParams, mt as WebhookSubscriptionListEventTypesResponse, n as SessionConfigsListParams, ni as SessionExecuteMetaResponse, nn as McpCreateResponse, nr as ToolkitRetrieveParams, nt as WebhookEndpointCreateResponse, oi as SessionLinkResponse, on as McpListInstancesParams, ot as WebhookEndpointReplaceResponse, p as CustomDeleteToolkitParams, pi as SessionSearchResponse, pn as McpUpdateParams, pr as ConnectedAccountCreateResponse, pt as WebhookSubscriptionDeleteResponse, q as ProjectCreateParams, qt as CliGetSessionResponse, r as SessionConfigsListResponse, ri as SessionExecuteParams, rn as McpDeleteInstanceParams, rr as ToolkitRetrieveResponse, rt as WebhookEndpointListParams, si as SessionPatchParams, sn as McpListInstancesResponse, st as WebhookEndpointRetrieveResponse, ti as SessionExecuteMetaParams, tn as McpCreateParams, tr as ToolkitRetrieveMultiResponse, tt as WebhookEndpointCreateParams, ui as SessionProxyExecuteResponse, un as McpRetrieveAppParams, ur as ConnectedAccountCompleteAuthParams, v as CustomUpsertResponse, vi as FileCreateDownloadURLParams, vr as ConnectedAccountPatchParams, vt as WebhookSubscriptionRotateSecretResponse, w as SessionRetrieveInfoResponse, wi as FileListParams, wn as TriggerInstanceUpsertResponse, wr as ConnectedAccountUpdateStatusParams, wt as UsageRetrieveParams, x as ApiKeyRevocationCreateResponse, xi as FileCreateUploadURLResponse, xn as TriggerInstanceListActiveParams, xr as ConnectedAccountRefreshResponse, yi as FileCreateDownloadURLResponse, yn as CustomCreateParams, yr as ConnectedAccountPatchResponse, yt as WebhookSubscriptionUpdateParams, zn as AuthConfigDeleteResponse, zr as ToolProxyResponse, zt as TriggerRetrieveResponse } from "./session-configs-x3OA4CSe.mjs";
+import { t as VERSION } from "./version-DEAhxVwC.mjs";
 import { Context, Effect, Layer, Redacted, Stream } from "effect";
 import * as HttpClient from "effect/http/HttpClient";
 import * as Schema from "effect/Schema";
@@ -130,6 +130,18 @@ declare const isAPIError: (value: unknown) => value is APIStatusError;
 /** Whether a value is any error this surface produces. Structural, like {@link isAPIError}. */
 declare const isComposioError: (value: unknown) => value is ComposioError;
 //#endregion
+//#region src/effect/credentials.d.ts
+type Key = string | Redacted.Redacted<string>;
+/**
+ * A key, or a function that returns one, as the Effect client takes it: a
+ * string or a `Redacted<string>`. A function is called once per call, after
+ * the call starts, and its key is reused across retries and same-origin
+ * redirects.
+ */
+type Credential = Key | (() => Key | PromiseLike<Key>);
+/** How the Effect client authenticates: `Auth.project(key)` and its siblings, with `Redacted` keys accepted. */
+type Auth$2 = AuthOf<Credential>;
+//#endregion
 //#region src/effect/decode.d.ts
 /**
  * What a client decodes with: an operation's public chain (`toolkits.list`) →
@@ -573,7 +585,7 @@ interface Session {
 //#endregion
 //#region src/effect/generated/resources/auth/auth.d.ts
 /** `client.auth` on the Effect surface. */
-interface Auth {
+interface Auth$1 {
   readonly session: Session;
 }
 //#endregion
@@ -627,7 +639,7 @@ interface ClientResources {
   readonly webhookSubscriptions: WebhookSubscriptions;
   readonly webhookEndpoints: WebhookEndpoints;
   readonly org: Org;
-  readonly auth: Auth;
+  readonly auth: Auth$1;
   readonly apiKeyRevocation: ApiKeyRevocation;
   readonly custom: Custom;
   readonly keyring: Keyring;
@@ -635,15 +647,30 @@ interface ClientResources {
 }
 //#endregion
 //#region src/effect/client.d.ts
-/** A credential as a caller supplies it: `null` means "none". */
-type Credential = string | Redacted.Redacted<string> | null | undefined;
+/** How the client authenticates; a key may be a string, a `Redacted<string>`, or a function that returns either. */
+type Auth = Auth$2;
+/**
+ * The constructors of {@link Auth}, the same as the root entry's: `Auth.project(key)`,
+ * `Auth.user(key)`, `Auth.organization(key)`, `Auth.auto({ ... })` and
+ * `Auth.none()`. A key may be a string, a `Redacted<string>`, or a function
+ * that returns either.
+ */
+declare const Auth: AuthConstructors<Credential>;
 interface ClientSettings {
-  /** Project API key (`ApiKeyAuth`, `x-api-key`). */
-  readonly apiKey?: Credential;
-  /** User API key (`UserApiKeyAuth`, `x-user-api-key`), sent where an operation asks for it. */
-  readonly userApiKey?: Credential;
-  /** Organization API key (`OrgApiKeyAuth`, `x-org-api-key`), sent where an operation asks for it. */
-  readonly orgApiKey?: Credential;
+  /**
+   * How the client authenticates. A fixed mode sends its credential on every
+   * request to the API origin; `Auth.auto` picks one per operation; with
+   * `Auth.none()` the credential header names are the caller's. While `auth`
+   * is not `none`, neither `defaultHeaders` nor a call's `headers` may name a
+   * credential header.
+   */
+  readonly auth: Auth;
+  /**
+   * The organization and project the client addresses, sent as `x-org-id` and
+   * `x-project-id`. While it is set, neither `defaultHeaders` nor a call's
+   * `headers` may name either header.
+   */
+  readonly scope?: Scope | undefined;
   /** The API origin. Defaults to `https://backend.composio.dev`. */
   readonly baseURL?: string | undefined;
   /**
@@ -651,7 +678,19 @@ interface ClientSettings {
    * origin. The permission is limited to the resolved scheme, host, and port.
    */
   readonly allowInsecureHTTP?: boolean | undefined;
-  /** Headers sent on every request; per-call headers win, `null` deletes. */
+  /**
+   * The calling product, sent as the product headers (`x-client-provenance`,
+   * `x-client-version`, `x-sdk-version`, `x-source`, `x-framework`,
+   * `x-runtime`). With it set, neither `defaultHeaders` nor a call's `headers`
+   * may name an identity header; without it the client reports itself.
+   */
+  readonly identity?: ClientIdentity | undefined;
+  /**
+   * Headers sent on every request; per-call headers win, `null` deletes. The
+   * library headers (`x-client-library`, `x-client-library-version`,
+   * `x-client-language`) are the client's own and are refused here, as is
+   * every identity header once `identity` is set.
+   */
   readonly defaultHeaders?: HeadersLike;
   /**
    * Maximum retries for temporary failures of a call whose method is
@@ -687,7 +726,7 @@ interface ClientSettings {
  * ```ts
  * import { schemaLoaders } from '@composio/client/effect/schemas'
  *
- * make({ apiKey, decode: true, schemas: schemaLoaders }, httpClient)
+ * make({ auth: Auth.project(key), decode: true, schemas: schemaLoaders }, httpClient)
  * ```
  */
 type DecodingOptions = {
@@ -728,29 +767,34 @@ declare class ComposioClient extends ComposioClient_base {}
  * Reads no environment variable.
  *
  * @throws {ConfigurationError} when a credentialed origin is not HTTPS, a
- *   credential cannot be sent as a header, or the client is to decode and was
- *   given no schemas.
+ *   credential cannot be sent as a header, `identity` is invalid or
+ *   `defaultHeaders` names an identity header, or the client is to decode and
+ *   was given no schemas.
  */
 declare const make: (options: ComposioClientOptions, httpClient: HttpClient.HttpClient) => ComposioClientShape;
 /**
  * Provides the client from explicit options and the `HttpClient` in context.
  * Reads no environment variable.
  */
-declare const layer: (options?: ComposioClientOptions) => Layer.Layer<ComposioClient, ConfigurationError, HttpClient.HttpClient>;
+declare const layer: (options: ComposioClientOptions) => Layer.Layer<ComposioClient, ConfigurationError, HttpClient.HttpClient>;
 /**
  * {@link layer} over a fetch-backed `HttpClient`, for an application that has
  * no transport of its own to supply. `fetch` is the platform's, or whatever
  * the `FetchHttpClient.Fetch` reference in context names.
  */
-declare const layerFetch: (options?: ComposioClientOptions) => Layer.Layer<ComposioClient, ConfigurationError>;
+declare const layerFetch: (options: ComposioClientOptions) => Layer.Layer<ComposioClient, ConfigurationError>;
 /**
- * Provides the client from the `COMPOSIO_*` settings — `COMPOSIO_API_KEY`,
- * `COMPOSIO_USER_API_KEY`, `COMPOSIO_ORG_API_KEY`, `COMPOSIO_BASE_URL` and
- * `COMPOSIO_ALLOW_INSECURE_HTTP=1` — read through the `ConfigProvider` in
- * context, which is the process environment unless the application says
- * otherwise. An option given here wins over its setting; `null` for a
- * credential means "none", whatever is configured.
+ * Provides the client from the `COMPOSIO_*` settings, read through the
+ * `ConfigProvider` in context, which is the process environment unless the
+ * application says otherwise. `COMPOSIO_API_KEY`, `COMPOSIO_USER_API_KEY` and
+ * `COMPOSIO_ORG_API_KEY` become `auth` by the rule `Composio.fromEnv` applies
+ * (one set: that fixed mode; several: `Auth.auto`; none: `Auth.none()`), each
+ * key `Redacted` throughout; `COMPOSIO_BASE_URL` and
+ * `COMPOSIO_ALLOW_INSECURE_HTTP=1` are read too. `COMPOSIO_ORG_ID` and
+ * `COMPOSIO_PROJECT_ID` are not: `scope` is an argument. An option given here
+ * replaces the whole setting it names, so `{ auth: Auth.none() }` means none
+ * whatever is configured.
  */
-declare const layerConfig: (options?: ComposioClientOptions) => Layer.Layer<ComposioClient, ConfigurationError, HttpClient.HttpClient>;
+declare const layerConfig: (overrides?: Partial<ClientSettings> & DecodingOptions) => Layer.Layer<ComposioClient, ConfigurationError, HttpClient.HttpClient>;
 //#endregion
-export { APIConnectionError, APIConnectionTimeoutError, APIError, type APIErrorBody, type APIErrorFields, type APIStatusError, AuthenticationError, BadRequestError, ComposioClient, type ComposioClientOptions, type ComposioClientShape, type ComposioError, ConfigurationError, ConflictError, type Credential, DecodeError, type DecodeIssue, type DeprecationNotices, type HeadersLike, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, type RawBodyRequestOptions, type RawRequestOptions, type RequestOptions, type SchemaLoaders, type Tracing, UnprocessableEntityError, VERSION, isAPIError, isComposioError, layer, layerConfig, layerFetch, make };
+export { APIConnectionError, APIConnectionTimeoutError, APIError, type APIErrorBody, type APIErrorFields, type APIStatusError, Auth, AuthenticationError, type AutoCredentials, BadRequestError, type ClientIdentity, ComposioClient, type ComposioClientOptions, type ComposioClientShape, type ComposioError, ConfigurationError, ConflictError, type Credential, DecodeError, type DecodeIssue, type DeprecationNotices, type HeadersLike, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, type RawBodyRequestOptions, type RawRequestOptions, type RequestOptions, type SchemaLoaders, type Scope, type Tracing, UnprocessableEntityError, VERSION, isAPIError, isComposioError, layer, layerConfig, layerFetch, make };