@composio/client 2.0.0-rc.21 → 2.0.0-rc.23

package/README.md

@@ -2,7 +2,7 @@
 
 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 113 released operations — in **both** languages: TypeScript at the package root, and Python in [`python/`](./python/README.md) (PyPI takeover pending).
+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 114 released operations — in **both** languages: TypeScript at the package root, and Python in [`python/`](./python/README.md) (PyPI takeover pending).
 
 ## Usage
 
@@ -54,7 +54,8 @@ 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`).
+(`_internal.org.consumer.project.resolve`, `_internal.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.
 
@@ -137,6 +138,23 @@ polyfills and test interceptors keep working. A custom `fetch` or extra `Request
 through `createFetchTransport({ fetch, defaults })`; the former `fetch`, `fetchOptions` and
 `defaultQuery` constructor options are gone (see the upgrade section).
 
+### 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
+import type {} from '@composio/client/internal' // `@composio/client/effect/internal` for the Effect client
+
+const session = await composio._internal.cli.getSession({ id })
+```
+
+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(...)`.
+
 ## Effect
 
 `@composio/client/effect` is the same API surface for applications written with
@@ -149,7 +167,7 @@ dependency, loads faster and spends less time per request (see [Performance](#pe
 
 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.
+input. All 114 operations of the spec are there.
 
 ### Install
 
@@ -542,6 +560,50 @@ 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.
 
+### Changed in 2.0.0-rc.23
+
+| Change | Migration |
+| --- | --- |
+| `client.cli.createCodactFailure` moved to `client._internal.cli.createCodactFailure` (Apollo now tags it `x-internal`) | Import `@composio/client/internal` and call it there. Its types come from `@composio/client/resources/_internal/cli`; `@composio/client/resources/cli` no longer exists. Its Effect response schema moved to `@composio/client/effect/schemas/_internal/cli/create-codact-failure`. The wire is unchanged |
+| `client.org.clanker.createClaim` is removed, with `@composio/client/resources/org/clanker` (Apollo removed `POST /api/v3.1/org/clanker/create_claim`) | None: the endpoint no longer exists |
+| `sessionConfigs.list` no longer accepts `search` (Apollo removed the filter) | Drop `search` from the query and filter the returned configs yourself |
+
+Two new internal operations are under `client._internal`: `consumer.permissions.resolve()` and
+`org.consumer.retrieveConfig()`. Each removal has a ledger entry; `search` is a `properties-removed`
+entry.
+
+### Moved in 2.0.0-rc.22
+
+The operations the spec tags `x-internal` moved under `client._internal`, which is typed only through
+`@composio/client/internal` (see [Internal operations](#internal-operations)). The wire is unchanged.
+The ledger declares each as a removal; `pnpm test:pack` holds the subpaths.
+
+| Moved | Now |
+| --- | --- |
+| `client.cli.createSession`, `getSession` | `client._internal.cli.createSession`, `getSession` |
+| `client.cli.realtime.*` | `client._internal.cli.realtime.*` |
+| `client.logs.tools.*`, `client.logs.triggers.*` | `client._internal.logs.tools.*`, `client._internal.logs.triggers.*` |
+| `client.org.consumer.*` | `client._internal.org.consumer.*` |
+| Their types, from `@composio/client/resources/cli`, `resources/cli/realtime`, `resources/logs`, `resources/logs/tools`, `resources/logs/triggers`, `resources/org/consumer*` | The same names from `@composio/client/resources/_internal/<same path>` |
+
+`client.logs.createToolExecution` and `client.logs.retrieveToolExecution` are not tagged and stay
+where they were. `client.cli.createCodactFailure` stayed too, until rc.23.
+
+### Changed in 2.0.0-rc.22
+
+| Change | Migration |
+| --- | --- |
+| `toolRouter.session.execute`, `executeMeta` and `proxyExecute` can return `result_type: 'blocked'` | Handle that branch before reading `data`, `error`, `status` or `headers`. Read `reason.type`, `reason.hook_id` and `message` instead. `request_blocked` means the tool did not run; `response_blocked` means it ran and its response was withheld. `log_id` is optional on blocked tool executions |
+| Execution outcomes may include `hook_results` | Treat it as optional. An entry with `status: 'evaluated'` has `outcome: 'continue' \| 'block'`; `status: 'unavailable'` has no outcome. Python callers must also handle the new `SessionExecuteBlockedResponse`, `SessionExecuteMetaBlockedResponse` and `SessionProxyExecuteBlockedResponse` members of each `*Result` union |
+| Trigger-type list items and retrieve responses require `types` | Add a non-empty `types` array of `'webhook'` and/or `'poll'` to typed fixtures and mocks. The older `type` field is deprecated |
+| `org.consumer.project.resolve` requires response `user_id` | Add the authenticated user's id to typed response fixtures and mocks; `consumer_user_id` remains a separate field |
+| Saved session configurations include `require_approval` lists | Handle toolkit/tool entries containing only `{ require_approval: [...] }`, as well as entries with `enable`, `disable` or tool tags. Session-wide and per-toolkit tags may also contain `require_approval` |
+| Project creation no longer declares `config.require_mcp_api_key` | Remove it from project-creation inputs. The upstream schema declares no replacement. `config.enable_instant` controls Instant Toolkits and is unrelated to MCP authentication |
+
+The removed project property has a `properties-removed` ledger entry. The previous-release gate
+checks named property paths as well as assignability, so removing an optional key cannot silently
+pass both structural checks.
+
 ### Removed in 2.0.0-rc.21
 
 The last members of the `Composio` class that existed only to look like the Stainless build. None is a