@composio/client 2.0.0-rc.2 → 2.0.0-rc.20

package/README.md

@@ -2,40 +2,645 @@
 
 Composio API client for TypeScript, generated from the [v3.1 OpenAPI spec](https://staging-backend.composio.dev/api/v3.1/openapi.json) with [hey-api](https://heyapi.dev).
 
-This repo is the successor to the Stainless-generated [`@composio/client`](https://www.npmjs.com/package/@composio/client) (Stainless is sunsetting). Current scope: the full `/api/v3.1` surface — all 104 released operations — in **both** languages: TypeScript at the package root, and Python in [`python/`](./python/README.md) (PyPI takeover pending). Migration is tracked on the wayfinder map [UXE-152](https://linear.app/composio/issue/UXE-152).
+This repo is the successor to the Stainless-generated [`@composio/client`](https://www.npmjs.com/package/@composio/client) (Stainless is sunsetting). Current scope: the full `/api/v3.1` surface — all 113 released operations — in **both** languages: TypeScript at the package root, and Python in [`python/`](./python/README.md) (PyPI takeover pending).
 
 ## 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 params and response 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
+`items` and `next_cursor` fields:
+
+```ts
+import { paginate } from '@composio/client/pagination'
+
+const toolkits = paginate(({ cursor }) =>
+  composio.toolkits.list({ cursor, limit: 100 }),
+)
+
+for await (const toolkit of toolkits) {
+  console.log(toolkit.slug)
+}
+```
+
+Item iteration is lazy. Each traversal starts from the first page, and breaking early stops fetching
+more pages. Use `iterPages()` when page metadata matters, or `toArray()` to collect every item; avoid
+`toArray()` when the full result may not fit comfortably in memory.
+
+```ts
+for await (const page of toolkits.iterPages()) {
+  console.log(page.items.length)
+}
+
+const allToolkits = await toolkits.toArray()
+```
+
+For another response shape, provide an adapter. Custom cursors must be strings or numbers so repeated
+values can be detected reliably across independently decoded pages:
+
+```ts
+const results = paginate(
+  ({ cursor }) => loadPage(cursor),
+  {
+    items: page => page.data,
+    nextCursor: page => page.nextCursor,
+  },
+)
+```
+
+A repeated cursor cycle throws `ComposioError` instead of requesting pages indefinitely. An empty
+cursor ends traversal. When a response omits `next_cursor` but numeric `current_page` and
+`total_pages` metadata shows that more pages exist, the default adapter fails instead of silently
+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.
+
+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(process.env, { baseURL: 'https://staging-backend.composio.dev' })
+```
+
+`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, { Auth, createFetchTransport } from '@composio/client'
+
+const transport = createFetchTransport({ fetch: instrumentedFetch })
+const composio = new Composio({ auth: Auth.project(apiKey), transport })
+```
+
+Without a `transport`, the client resolves `globalThis.fetch` when a request is sent, so late
+polyfills and test interceptors keep working. A custom `fetch` or extra `RequestInit` defaults go
+through `createFetchTransport({ fetch, defaults })`; the former `fetch`, `fetchOptions` and
+`defaultQuery` constructor options are gone (see the upgrade section).
+
+## Effect
+
+`@composio/client/effect` is the same API surface for applications written with
+[Effect](https://effect.website). Every operation returns an `Effect` whose failures are tagged
+errors, the transport is the `HttpClient` in context, and interrupting a call aborts its request.
+
+Use it when the calling code is already Effect code and would otherwise wrap each call in
+`Effect.tryPromise` and inspect what was thrown. Otherwise use the package root: it needs no peer
+dependency, loads faster and spends less time per request (see [Performance](#performance)).
+
+The accessor chains, method names, argument order and request and response types are the root
+client's, and a call sends the same method, URL, body and headers as the root client does for the same
+input. All 113 operations of the spec are there.
+
+### Install
+
+```sh
+pnpm add @composio/client effect
+```
+
+`effect` is an optional peer dependency. The root entry and the `./pagination` and `./resources/*`
+subpaths never import it and load without it.
+
+- **Supported range: `effect >=4.0.3 <4.1.0`.** The manifest declares the peer as `*`, because a
+  bounded optional peer makes npm refuse the whole install for a project that lists some other
+  `effect` and never imports this subpath. The cost is that a package manager does not warn about an
+  unsupported version. The range above is the one the subpath is tested against.
+- **Install exactly one copy of `effect`.** With two copies, even one patch apart, the project does
+  not type-check: the client's `Effect`, `Layer` and `HttpClient` are not assignable to the
+  application's. At run time `Redacted` values do not cross between copies and `instanceof` is false,
+  and nothing warns about it.
+- **The supported range bounds your Effect upgrades.** The client runs on the application's `effect`,
+  so moving to a new Effect minor waits for a client release whose supported range includes it.
+
+### Construct a client
+
+```ts
+import { Effect, Layer } from 'effect'
+import * as FetchHttpClient from 'effect/http/FetchHttpClient'
+import { Auth, ComposioClient, layer, layerConfig } from '@composio/client/effect'
+
+// Explicit options, over the `HttpClient` the application provides; here a fetch-backed one.
+const live = 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))
+
+const program = Effect.gen(function* () {
+  const composio = yield* ComposioClient
+  const toolkit = yield* composio.toolkits.retrieve('github')
+  return toolkit.slug
+})
+
+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.
+
+`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` and `layer` 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. The root client's resources are the same since rc.20.
+
+### Errors
+
+Every call fails with a `ComposioError`, a union of tagged errors. The tags are namespaced:
+
+| Tag | When |
+| --- | --- |
+| `@composio/client/BadRequestError` | 400 |
+| `@composio/client/AuthenticationError` | 401 |
+| `@composio/client/PermissionDeniedError` | 403 |
+| `@composio/client/NotFoundError` | 404 |
+| `@composio/client/ConflictError` | 409 |
+| `@composio/client/UnprocessableEntityError` | 422 |
+| `@composio/client/RateLimitError` | 429 |
+| `@composio/client/InternalServerError` | 500 and above |
+| `@composio/client/APIError` | any other non-success status |
+| `@composio/client/APIConnectionError` | the transport failed before a response |
+| `@composio/client/APIConnectionTimeoutError` | an attempt outlived its time budget |
+| `@composio/client/DecodeError` | a success body failed validation (only with `decode: true`) |
+| `@composio/client/ConfigurationError` | no request can be made from this client or call |
+
+```ts
+import { Effect } from 'effect'
+import { isAPIError, type ComposioClientShape } from '@composio/client/effect'
+
+const slugOrNull = (composio: ComposioClientShape, slug: string) =>
+  composio.toolkits.retrieve(slug).pipe(
+    Effect.map((toolkit) => toolkit.slug),
+    Effect.catchTag('@composio/client/NotFoundError', () => Effect.succeed(null)),
+    Effect.tapError((error) =>
+      isAPIError(error) ? Effect.logWarning(`${error.status} ${error.requestId}`) : Effect.void,
+    ),
+  )
+```
+
+A status error carries `status`, `requestId`, `details` (the Composio error envelope, when the body
+is one), `body`, `message`, `method` and `url`. `isAPIError` matches any status error and
+`isComposioError` any error of the union; both test the tag, not the class. There is no access to the
+raw response of a successful call.
+
+Timeouts follow the root client's policy: one minute per attempt by default. Retries do not. A
+call whose method is idempotent (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`) is retried up to 2 times
+on a connection failure, a timeout, or a 408, 409, 429 or 5xx response, as the root client retries
+every call. Any other call, `POST` and `PATCH` included, is sent once, because a write that failed in
+flight may already have acted. A call that is safe to repeat opts back in with its own `maxRetries`:
+
+```ts
+composio.toolRouter.session.search(sessionId, { queries }, { maxRetries: 2 })
+```
+
+### Streams
+
+Fourteen cursor-paginated operations have a `<method>Stream` beside them that yields items across
+pages:
+
+- `authConfigs.listStream`, `connectedAccounts.listStream`, `files.listStream`,
+  `sessionConfigs.listStream`, `toolkits.listStream`, `toolkits.retrieveMultiStream`,
+  `tools.listStream`, `triggerInstances.listActiveStream`, `triggersTypes.listStream`,
+  `webhookSubscriptions.listStream`
+- `toolRouter.session.configHistoryStream`, `toolRouter.session.toolkitsStream`,
+  `toolRouter.session.toolsStream`, `toolRouter.session.files.listStream`
+
+```ts
+import { Stream } from 'effect'
+import type { ComposioClientShape } from '@composio/client/effect'
+
+const firstSlugs = (composio: ComposioClientShape) =>
+  composio.toolkits.listStream({ limit: 100 }).pipe(
+    Stream.map((toolkit) => toolkit.slug),
+    Stream.take(250),
+    Stream.runCollect,
+  )
+```
+
+A page is requested only when the stream is pulled that far, so `Stream.take` above stops after the
+third page. The cursor rules are those of `@composio/client/pagination`, and a traversal that cannot
+continue — a cursor the server repeats, a page with no `items` array — fails with a
+`ConfigurationError`.
+
+No other operation has a stream. That includes the list operations whose page is not the standard
+`items` and `next_cursor` shape: `org.list` (`organizations`), `org.project.list` and
+`org.owner.project.list` (`data`), and `logs.createToolExecution` (`logs`). Page those by passing
+`next_cursor` back yourself.
+
+### Per-call options
+
+The last argument of every operation and raw method:
+
+```ts
+import type { ComposioClientShape } from '@composio/client/effect'
+
+const once = (composio: ComposioClientShape) =>
+  composio.toolkits.retrieve(
+    'github',
+    {},
+    {
+      headers: { 'x-trace-id': 'abc', 'x-team': null }, // `null` removes a default header
+      maxRetries: 0,
+      timeout: 10_000, // milliseconds, per attempt
+    },
+  )
+```
+
+Per-call headers win over the client's `defaultHeaders`. `decode` is the fourth option, described
+next.
+
+### Decoding
+
+By default a response body is returned as parsed and nothing checks it. Decoding is opt-in, per call
+or as a client default, and needs the response schemas, which are a separate entry:
+
+```ts
+import * as HttpClient from 'effect/http/HttpClient'
+import { Effect } from 'effect'
+import { make } from '@composio/client/effect'
+import { schemaLoaders } from '@composio/client/effect/schemas'
+
+const checkedCategories = (httpClient: HttpClient.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)),
+    ),
+  )
+}
+```
+
+- **It validates and changes nothing.** A call that passes returns the body exactly as it was parsed;
+  a field the API returns ahead of the spec is not stripped. The response type is the same either way.
+- **`DecodeError`** carries `operation` (`toolkits.retrieveCategories`), `status`, `requestId`,
+  `method`, `url` and `issues`, each a `path` and a `kind` such as `MissingKey` or `InvalidType`. It
+  never carries the body or the value found: a success body is where this API returns secrets.
+- **`decode: true` needs `schemas`.** As a client option without `schemas` it is a compile error, and a
+  `ConfigurationError` at construction for a caller the types did not reach. A per-call
+  `decode: true` on a client built without `schemas` fails with a `ConfigurationError` before
+  anything is sent.
+- **Schemas load lazily.** `schemaLoaders` is a table of `import()` calls, one per operation. A schema
+  module is loaded by the first call that decodes its operation. A single schema can also be imported
+  directly, for example
+  `import { ToolkitRetrieveCategoriesResponse } from '@composio/client/effect/schemas/toolkits/retrieve-categories'`.
+  A decoding call also checks that the table contains its operation before sending the request. The
+  loader itself runs only after a non-204 success; a failed dynamic import can therefore fail a call
+  after the server has already processed it.
+- **An application that never imports `@composio/client/effect/schemas` ships no schema.** The
+  `./effect` entry does not reach the table, so a bundler has no path to it.
+- A 204 has no body to validate. A raw call is validated when its path is a declared operation's.
+
+A schema is generated from the spec snapshot this version was built from, so decoding holds a
+response to that snapshot. A response from before a required field existed fails: replaying stored
+production responses through the schemas, the four `toolRouter.session` operations `create`,
+`retrieve`, `attach` and `patch` failed on a missing `config.instant` for every capture through
+2026-09-11, taken before the spec declared that field, and passed for the 2026-10-08 capture, taken
+after. The record is in [`docs/upstream-asks.md`](./docs/upstream-asks.md).
+
+### Tracing
+
+One option, `tracing`, says what the client's own requests add to a trace:
+
+| Value | Effect |
+| --- | --- |
+| `'off'` (default) | No span is opened for a request and no trace header is sent, so the request carries exactly the headers the root client sends. |
+| `'span'` | Effect's `HttpClient` opens its client span around each request, a child of the span the call runs in. Nothing about it goes on the wire. |
+| `'propagate'` | The span, also sent to the API as `b3` and `traceparent` headers. |
+
+The option only ever reduces tracing, and only for this client's requests. A span asked for here is
+still subject to the application's own `HttpClient.TracerDisabledWhen` and
+`HttpClient.TracerPropagationEnabled`.
+
+With a span on, the span ends on the client's own error, not on Effect's `HttpClientError`. That
+error holds the request and its credential headers, and a tracer keeps what a span ended on. To do
+this the client reassigns `end` on the span object the tracer returns, so a tracer that returns
+frozen spans throws when a request starts. The replacement costs about a microsecond per request on
+top of the span itself.
+
+### Credentials and redaction
+
+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
+that writes a header value into its error messages would put it there.
+
+The credential is applied before the request reaches the `HttpClient`, so a transform the application
+puts on its `HttpClient` sees it.
+
+### Redirects
+
+The client follows redirects itself and withdraws credentials once a chain changes origin. It does so
+by dispatching with `redirect: 'manual'`, which a fetch-backed `HttpClient` honors. The guarantee
+holds only when nothing between the client and the wire follows redirects. An `HttpClient` wrapped in
+`HttpClient.followRedirects`, or a transport that follows redirects on its own, forwards the
+credential headers across origins and is unsupported for a credentialed client. Headers an
+application places in `FetchHttpClient.RequestInit` are outside the client's credential handling:
+the credential check does not see them, and they are not withdrawn on a cross-origin redirect.
+
+### Deprecation notices
+
+A deprecated input, or a response carrying `Deprecation`, `Sunset` and `Link` headers, is reported
+through `Effect.logWarning`, once per operation and notice for each client. The application's
+`Logger` and `References.MinimumLogLevel` decide what becomes of it; there is no client option.
+`isDeprecationNotice` recognises a notice, so a logger can drop or route the notices alone:
+
+```ts
+import { isDeprecationNotice } from '@composio/client/effect'
+
+const quiet = Logger.make((options) => (isDeprecationNotice(options) ? undefined : base.log(options)))
+```
+
+### Raw methods
+
+`get`, `post`, `put`, `patch` and `delete` reach any path through the same kernel: credentials,
+retries, timeouts, redirects and errors behave as for a generated method.
+
+```ts
+import type { ComposioClientShape } from '@composio/client/effect'
+
+const raw = (composio: ComposioClientShape) =>
+  composio.post<{ id: string }>('/api/v3.1/some/path', {
+    query: { dry_run: true },
+    body: { name: 'example' },
+    maxRetries: 0,
+  })
+```
+
+The type argument is an assertion, not a check.
+
+### Performance
+
+Measured against a mocked transport, so these are client overhead and say nothing about network
+latency. The full tables and method are in
+[`docs/benchmarks/client-overhead.md`](./docs/benchmarks/client-overhead.md); the figures below are
+its 2026-10-13 runs on Node 24.17.0 and Bun 1.4.0, `effect` 4.0.3, one Apple M1 Pro.
+
+**The Effect surface is slower per request than the root client.** Typed geometric mean over two
+runs: 154.1% and 153.2% of the root client by default, 173.8% and 171.1% with `tracing: 'span'`. In
+absolute terms that is 10 to 14 microseconds more per request, and 3 to 5 more with the span on. It
+is a measurement, not a win; what it buys is the typed failure channel, interruption and a transport
+taken from context.
+
+**Decoding costs more than the request.** Validating a twenty-item `toolkits.list` page took a call
+from 77.7 / 78.9 µs to 187.3 / 192.4 µs, about 110 µs or 5.5 µs per item.
+
+**Import time**, over what Effect's own HTTP modules already cost, minimum / median of thirty in
+milliseconds:
+
+| | Node, modules | Node, bundle | Bun, modules | Bun, bundle |
+| --- | ---: | ---: | ---: | ---: |
+| `./effect`, never decodes | 4.2 / 4.5 | 4.7 / 4.8 | 3.6 / 2.8 | 11.2 / 11.7 |
+| plus importing `schemaLoaders` | 2.4 / 0.2 | 5.3 / 5.2 | 0.2 / −0.7 | 3.6 / 3.8 |
+
+The published-module lanes are noisy, which is how a difference comes out negative. Effect itself
+is the larger part: 122.2 / 128.3 ms as modules on Node and 22.0 / 23.8 ms bundled, against 9.6 /
+10.5 ms and 4.0 / 4.4 ms for the root client.
+
+**Bundle size** of a single-file consumer: Effect's HTTP modules alone, then with a client that never
+decodes, then with the loader table and every schema it reaches.
+
+| Bundler | Effect alone | never decodes | decodes |
+| --- | ---: | ---: | ---: |
+| rolldown | 498 kB | 732 kB | 893 kB |
+| `bun build` | 266 kB | 705 kB | 1088 kB |
+
+**Package weight.** The schema modules make the package larger on disk: 3.4 MB unpacked in 509 files,
+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
+loopback. For a trusted development backend such as Docker's host gateway, opt in to the exact
+configured origin:
+
+```ts
+const composio = new Composio({
+  auth: Auth.project(apiKey),
+  baseURL: 'http://host.docker.internal:9900',
+  allowInsecureHTTP: true,
+})
+```
+
+The equivalent environment configuration, for `Composio.fromEnv`, is:
+
+```sh
+COMPOSIO_BASE_URL=http://host.docker.internal:9900 \
+COMPOSIO_ALLOW_INSECURE_HTTP=1
+```
+
+The opt-in records the resolved scheme, hostname, and port. Mutating `baseURL` cannot broaden it,
+and `withOptions({ baseURL: ... })` requires `allowInsecureHTTP: true` again when the origin
+changes. Redirects to another origin remain credential-free.
+
+### Removed in 2.0.0-rc.20
+
+The Stainless structure goes. The two removal classes are declared rule entries in
+`packages/codegen/assignability-ledger.json`; the export spellings are held by `pnpm test:pack`.
+
+| Removed | Migration |
+| --- | --- |
+| Resource classes (`ToolRouter`, `Tools`, `ConnectedAccounts`, ... as values) and `Composio.Tools`-style statics | A resource is a plain object typed by an interface of the same name. `import type { Tools } from '@composio/client/resources/tools'` still works as a type; `Composio['tools']` is the same type. `instanceof` a resource class has no replacement |
+| Namespace-merged nested types (`SessionToolkitsResponse.Item`, `LinkCreateParams.Experimental`) | Indexed access: `SessionToolkitsResponse['items'][number]`, `NonNullable<LinkCreateParams['experimental']>` |
+| The `Composio` namespace (`Composio.RequestOptions`, `Composio.ToolListResponse`, ...) | Import the type: `import type { RequestOptions } from '@composio/client'`, `import type { ToolListResponse } from '@composio/client/resources/tools'` |
+| `@composio/client/resources`, `/resources.js`, `/resources.mjs`, `/resources/index` | The resource's own subpath: `@composio/client/resources/mcp` |
+| `.js` and `.mjs` deep subpaths (`/resources/tool-router/session/session.mjs`), `/pagination.js`, `/pagination.mjs` | The extensionless spelling: `/resources/tool-router/session/session`, `/pagination` |
+| `client.migration`, `client.project.config` | None: neither held an operation |
+
+### Removed in 2.0.0-rc.19
+
+The two option removals are declared entries in `packages/codegen/assignability-ledger.json`. The
+other rows are class members the type check does not pin, listed so an upgrade can find them.
+
+| Removed | Migration |
+| --- | --- |
+| `environment: 'production' \| 'staging' \| 'local'` (root `ClientOptions`) | `baseURL: ENVIRONMENTS.staging` or `ENVIRONMENTS.local` — the frozen origin table, exported since rc.20; omitting it means production |
+| `Logger` (exported interface) | `logger` takes a `Console`-shaped object (`Pick<Console, 'debug' \| 'info' \| 'warn' \| 'error'>`) and defaults to `console`. An adapter that forwards to another logger is the same four methods |
+| `client.apiKey`, `userApiKey`, `orgApiKey` (read-only since rc.18) | Keep your own copy of the key; `client.authMode` says which mode is configured |
+| `client.logger` | None: the sink is the client's own. Pass a different one to `withOptions({ logger })` |
+| Assigning `client.baseURL`, `maxRetries`, `timeout` or `logLevel` | `withOptions({ ... })`, which re-runs every validation. The four stay readable; `logLevel` reads the effective level (`'warn'` by default) |
+| `deprecationNotices: 'warn' \| 'off'` (`./effect` `ComposioClientOptions`) | The application's `Logger` and `References.MinimumLogLevel`; a logger that drops records matching `isDeprecationNotice` is `'off'` |
+| `layerFetch(options)` (`./effect`) | `layer(options).pipe(Layer.provide(FetchHttpClient.layer))` |
+
+Python removes `default_query` and the `api_key`, `user_api_key` and `org_api_key` reads, and makes
+`base_url`, `max_retries` and `timeout` read-only; `environment=` stays. See
+[`python/README.md`](./python/README.md).
+
+### 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 stayed readable until rc.19; 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
+release changes against the previous published version.
+
+| Removed | Migration |
+| --- | --- |
+| `fetch: f` (constructor) | `transport: createFetchTransport({ fetch: f })` |
+| `fetchOptions: { cache: 'no-store' }` (constructor) | `transport: createFetchTransport({ defaults: { cache: 'no-store' } })`. The defaults cannot set `method`, `headers`, `body`, `signal` or `redirect`, which the client owns |
+| `fetchOptions` (per call, in `RequestOptions`) | None: `headers`, `timeout`, `signal` and `idempotencyKey` stay, and transport-level defaults go through `createFetchTransport({ defaults })` |
+| `defaultQuery` (root `ClientOptions` and `./effect` `ComposioClientOptions`) | None: generated methods own their query, and the raw methods (`get`, `post`, ...) take an explicit `query` |
+| `custom.deleteToolkit(slug, options)` | `custom.deleteToolkit(slug, query, options)` — pass request options third, as on every other `(id, params?, options?)` method. The runtime guard that recognized an options bag in the params position is gone with the overload |
+
 ## Development
 
 Toolchain is pinned via [mise](https://mise.jdx.dev) (`mise install`): Node 24, pnpm 11, Python 3.13, uv. ESM-only, TypeScript 7 (native compiler for typechecking, `typescript@6` retained for tooling until 7.1 restores the compiler API).
 
 ```sh
 pnpm install
-pnpm generate       # hey-api + compat codegen: spec/openapi.json → src/generated + src/compat/resources (do not edit)
-pnpm lint           # eslint over src, test, packages/codegen
-pnpm typecheck      # tsgo (TS native) over src+test, incl. type tests
+pnpm generate       # hey-api + compat and Effect codegen: spec/openapi.json → src/generated, src/compat/resources, src/effect/generated (do not edit)
+pnpm lint           # eslint over src, test, codegen, parity, and demo
+pnpm typecheck      # tsgo (TS native), including type tests and demo
 pnpm typecheck:tsc  # same programs under tsc — both compilers must pass
-pnpm codegen:check  # verify committed src/compat/resources matches the generator
+pnpm codegen:check  # verify every committed generated tree matches the generator
 pnpm test           # unit tests (MSW mocks) + codegen tests
 pnpm build          # tsdown → dist/ (runs publint + arethetypeswrong)
 pnpm test:pack      # pack the real tarball, typecheck + import every drop-in subpath
+pnpm benchmark:baseline # capture the dist/ a benchmark run compares against
+pnpm benchmark      # score SDK overhead against that baseline
+pnpm benchmark:import # time what importing each entry costs, on Node and Bun
 pnpm test:contract  # live API tests; requires COMPOSIO_API_KEY (copy .env.example to .env)
 pnpm refresh-spec   # re-fetch spec/openapi.json from the live backend
 ```
 
-`src/generated/` and `src/compat/resources/` are regenerated output — never edit them by hand; CI fails if they drift from `spec/openapi.json`.
+`src/generated/`, `src/compat/resources/` and `src/effect/generated/` are regenerated output — never edit them by hand; CI fails if they drift from `spec/openapi.json`.
 
 ### Python lane
 
@@ -49,3 +654,7 @@ uv run ruff check
 uv run mypy src scripts
 uv run pytest
 ```
+
+Client-overhead measurements use a deterministic in-memory transport and are documented in
+[`docs/benchmarks/client-overhead.md`](./docs/benchmarks/client-overhead.md). They do not measure API
+latency.