@composio/client 2.0.0-rc.9 → 2.0.0

package/README.md

@@ -1,22 +1,76 @@
 # composio-client
 
-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).
+TypeScript and Python clients for the Composio v3.1 API. The checked-in OpenAPI snapshot supplies
+114 operations, including explicitly unsupported internal operations used by Composio's own SDKs.
+Use the Promise client at the package root, the optional [Effect client](#effect), or the
+[Python sync and async clients](./python/README.md).
 
-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).
+## Install
+
+Node.js 22 or newer is required.
+
+```sh
+pnpm add @composio/client
+```
+
+See [Upgrading to 2.0](#upgrading-to-20) for intentional compatibility changes from the previous
+Stainless client and earlier 2.0 release candidates.
 
 ## 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).
+Construct a Promise client with explicit authentication:
 
 ```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
+(`_internal.org.consumer.project.resolve`, `_internal.org.consumer.listConnectedToolkits`,
+`_internal.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,79 +119,480 @@ 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, { baseURL: 'https://staging-backend.composio.dev' })
 ```
 
-`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 })
 ```
 
-Existing `fetch` and `fetchOptions` constructor options remain supported. They cannot be combined
-with `transport` because a request can have only one HTTP dispatcher.
+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).
 
-## Upgrade from Stainless 0.1.x to 2.0
+### Retries and timeouts
 
-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:
+GET, HEAD, OPTIONS, PUT and DELETE calls retry up to twice on connection errors, timeouts and
+retryable HTTP responses. POST and PATCH calls are sent once by default, including tool execution:
+a lost response may hide a successful write. A client-level `maxRetries` only applies to idempotent
+methods. A call that is safe to repeat opts in with `{ maxRetries: 2 }` in its request options.
+An `idempotencyKey` sends a header; server deduplication is not guaranteed, and it does not opt a
+write into retries. Timeouts default to one minute per attempt.
+
+### Internal operations
+
+The spec publishes some operations for Composio's own CLI and SDKs and tags them `x-internal`: CLI
+login sessions, realtime credentials, the execution and trigger logs, and the consumer-project
+routes. They are under `client._internal`, they carry no compatibility promise, and any release may
+change them. The property exists on every client, but the root types do not name it, so it stays
+out of autocompletion. A program that needs it imports the opt-in subpath once:
 
 ```ts
-const composio = new Composio({
-  apiKey,
-  baseURL: 'http://host.docker.internal:9900',
-  allowInsecureHTTP: true,
-})
+import type {} from '@composio/client/internal' // `@composio/client/effect/internal` for the Effect client
+
+const session = await composio._internal.cli.getSession({ id })
 ```
 
-The equivalent environment configuration is:
+Their types are under `@composio/client/resources/_internal/*`. The previous-release gate does not
+pin them. In Python the same operations are `client._internal.cli.get_session(...)`.
+
+## Handle API errors
+
+Awaiting a failed call throws an `APIError` subclass, such as `NotFoundError` or `RateLimitError`,
+exported from `@composio/client`. Status errors carry `status`, `requestId`, and `details` when the
+API returned a Composio error envelope. Connection failures, timeouts and caller cancellation use
+`APIConnectionError`, `APIConnectionTimeoutError` and `APIUserAbortError` respectively.
+
+Use `.withResponse()` for parsed data plus response metadata. Use `.asResponse()` to inspect the raw
+response, including a non-success HTTP status, without parsing it into an exception.
+
+## 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 114 operations of the spec are there.
+
+### Install
 
 ```sh
-COMPOSIO_BASE_URL=http://host.docker.internal:9900 \
-COMPOSIO_ALLOW_INSECURE_HTTP=1
+pnpm add @composio/client 'effect@>=4.0.3 <4.2.0'
+```
+
+`effect` is an optional peer dependency. Effect 4.1 requires Node.js 22.19 or newer.
+The root entry and the `./pagination` and `./resources/*` subpaths never import it and load without it.
+
+- **Supported range: `effect >=4.0.3 <4.2.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 and retries follow the root client's policy: one minute per attempt by default. 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. 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 { Auth, 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' },
+})
 ```
 
-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.
+| 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`.
+
+## Upgrading to 2.0
+
+Authentication is explicit, several legacy exports are removed, internal operations have moved,
+and POST/PATCH retries now require per-call opt-in. Read the [TypeScript migration guide](./MIGRATION.md)
+or [Python migration guide](./python/MIGRATION.md) before upgrading from Stainless or an earlier RC.
 
 ## 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).
+Toolchain is pinned via [mise](https://mise.jdx.dev) (`mise install`): Node, Bun, pnpm, Python and uv. Exact versions live in `mise.toml`. 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 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 test           # unit tests (MSW mocks) + codegen tests
+pnpm codegen:check  # verify every committed generated tree matches the generator
+pnpm test           # offline unit, codegen, parity-harness and demo suites
 pnpm build          # tsdown → dist/ (runs publint + arethetypeswrong)
-pnpm test:pack      # pack the real tarball, typecheck + import every drop-in subpath
+pnpm test:pack      # installed export inventory, Effect consumers and optional-peer matrix
 pnpm benchmark:baseline # capture the dist/ a benchmark run compares against
-pnpm benchmark      # score SDK overhead against that baseline and against Stainless
+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
 
@@ -155,3 +610,8 @@ 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.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup and verification,
+[SECURITY.md](./SECURITY.md) for private vulnerability reports, and [LICENSE](./LICENSE) for Apache-2.0.