@composio/client 0.1.0-alpha.8 → 2.0.0-rc.1

package/README.md

@@ -1,373 +1,51 @@
-# Composio TypeScript API Library
+# composio-client
 
-[![NPM version](https://img.shields.io/npm/v/@composio/client.svg)](https://npmjs.org/package/@composio/client) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@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).
 
-This library provides convenient access to the Composio REST API from server-side TypeScript or JavaScript.
-
-The REST API documentation can be found on [docs.composio.com](https://docs.composio.com). The full API of this library can be found in [api.md](api.md).
-
-It is generated with [Stainless](https://www.stainless.com/).
-
-## Installation
-
-```sh
-npm install @composio/client
-```
+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).
 
 ## Usage
 
-The full API of this library can be found in [api.md](api.md).
-
-<!-- prettier-ignore -->
-```js
-import Composio from '@composio/client';
-
-const client = new Composio({
-  apiKey: process.env['COMPOSIO_API_KEY'], // This is the default and can be omitted
-  environment: 'staging', // or 'production' | 'local'; defaults to 'production'
-});
-
-async function main() {
-  const response = await client.tools.execute('action');
-
-  console.log(response.log_id);
-}
-
-main();
-```
-
-### Request & Response types
-
-This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
-
-<!-- prettier-ignore -->
-```ts
-import Composio from '@composio/client';
-
-const client = new Composio({
-  apiKey: process.env['COMPOSIO_API_KEY'], // This is the default and can be omitted
-  environment: 'staging', // or 'production' | 'local'; defaults to 'production'
-});
-
-async function main() {
-  const response: Composio.ToolExecuteResponse = await client.tools.execute('action');
-}
-
-main();
-```
-
-Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
-
-## Handling errors
+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).
 
-When the library is unable to connect to the API,
-or if the API returns a non-success status code (i.e., 4xx or 5xx response),
-a subclass of `APIError` will be thrown:
-
-<!-- prettier-ignore -->
 ```ts
-async function main() {
-  const response = await client.tools.execute('action').catch(async (err) => {
-    if (err instanceof Composio.APIError) {
-      console.log(err.status); // 400
-      console.log(err.name); // BadRequestError
-      console.log(err.headers); // {server: 'nginx', ...}
-    } else {
-      throw err;
-    }
-  });
-}
-
-main();
-```
-
-Error codes are as followed:
-
-| Status Code | Error Type                 |
-| ----------- | -------------------------- |
-| 400         | `BadRequestError`          |
-| 401         | `AuthenticationError`      |
-| 403         | `PermissionDeniedError`    |
-| 404         | `NotFoundError`            |
-| 422         | `UnprocessableEntityError` |
-| 429         | `RateLimitError`           |
-| >=500       | `InternalServerError`      |
-| N/A         | `APIConnectionError`       |
-
-### Retries
+import Composio from '@composio/client'
 
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
-429 Rate Limit, and >=500 Internal errors will all be retried by default.
+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY })
 
-You can use the `maxRetries` option to configure or disable this:
-
-<!-- prettier-ignore -->
-```js
-// Configure the default for all requests:
-const client = new Composio({
-  maxRetries: 0, // default is 2
-});
-
-// Or, configure per-request:
-await client.tools.execute('action', {
-  maxRetries: 5,
-});
+const session = await composio.toolRouter.session.create({ user_id: 'user_123' })
+console.log(session.session_id, session.mcp.url)
 ```
 
-### Timeouts
-
-Requests time out after 1 minute by default. You can configure this with a `timeout` option:
-
-<!-- prettier-ignore -->
-```ts
-// Configure the default for all requests:
-const client = new Composio({
-  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
-});
-
-// Override per-request:
-await client.tools.execute('action', {
-  timeout: 5 * 1000,
-});
-```
-
-On timeout, an `APIConnectionTimeoutError` is thrown.
-
-Note that requests which time out will be [retried twice by default](#retries).
-
-## Advanced Usage
-
-### Accessing raw Response data (e.g., headers)
-
-The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
-This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
-
-You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
-Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
-
-<!-- prettier-ignore -->
-```ts
-const client = new Composio();
-
-const response = await client.tools.execute('action').asResponse();
-console.log(response.headers.get('X-My-Header'));
-console.log(response.statusText); // access the underlying Response object
-
-const { data: response, response: raw } = await client.tools.execute('action').withResponse();
-console.log(raw.headers.get('X-My-Header'));
-console.log(response.log_id);
-```
-
-### Logging
-
-> [!IMPORTANT]
-> All log messages are intended for debugging only. The format and content of log messages
-> may change between releases.
-
-#### Log levels
-
-The log level can be configured in two ways:
-
-1. Via the `COMPOSIO_LOG` environment variable
-2. Using the `logLevel` client option (overrides the environment variable if set)
-
-```ts
-import Composio from '@composio/client';
-
-const client = new Composio({
-  logLevel: 'debug', // Show all log messages
-});
-```
-
-Available log levels, from most to least verbose:
-
-- `'debug'` - Show debug messages, info, warnings, and errors
-- `'info'` - Show info messages, warnings, and errors
-- `'warn'` - Show warnings and errors (default)
-- `'error'` - Show only errors
-- `'off'` - Disable all logging
-
-At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
-Some authentication-related headers are redacted, but sensitive data in request and response bodies
-may still be visible.
-
-#### Custom logger
-
-By default, this library logs to `globalThis.console`. You can also provide a custom logger.
-Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
-
-When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
-below the configured level will not be sent to your logger.
-
-```ts
-import Composio from '@composio/client';
-import pino from 'pino';
+## Development
 
-const logger = pino();
+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).
 
-const client = new Composio({
-  logger: logger.child({ name: 'Composio' }),
-  logLevel: 'debug', // Send all messages to pino, allowing it to filter
-});
-```
-
-### Making custom/undocumented requests
-
-This library is typed for convenient access to the documented API. If you need to access undocumented
-endpoints, params, or response properties, the library can still be used.
-
-#### Undocumented endpoints
-
-To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.
-Options on the client, such as retries, will be respected when making these requests.
-
-```ts
-await client.post('/some/path', {
-  body: { some_prop: 'foo' },
-  query: { some_query_arg: 'bar' },
-});
-```
-
-#### Undocumented request params
-
-To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
-parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
-send will be sent as-is.
-
-```ts
-client.foo.create({
-  foo: 'my_param',
-  bar: 12,
-  // @ts-expect-error baz is not yet public
-  baz: 'undocumented option',
-});
-```
-
-For requests with the `GET` verb, any extra params will be in the query, all other requests will send the
-extra param in the body.
-
-If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
-options.
-
-#### Undocumented response properties
-
-To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
-the response object, or cast the response object to the requisite type. Like the request params, we do not
-validate or strip extra properties from the response from the API.
-
-### Customizing the fetch client
-
-By default, this library expects a global `fetch` function is defined.
-
-If you want to use a different `fetch` function, you can either polyfill the global:
-
-```ts
-import fetch from 'my-fetch';
-
-globalThis.fetch = fetch;
-```
-
-Or pass it to the client:
-
-```ts
-import Composio from '@composio/client';
-import fetch from 'my-fetch';
-
-const client = new Composio({ fetch });
-```
-
-### Fetch options
-
-If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
-
-```ts
-import Composio from '@composio/client';
-
-const client = new Composio({
-  fetchOptions: {
-    // `RequestInit` options
-  },
-});
-```
-
-#### Configuring proxies
-
-To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
-options to requests:
-
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
-
-```ts
-import Composio from '@composio/client';
-import * as undici from 'undici';
-
-const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
-const client = new Composio({
-  fetchOptions: {
-    dispatcher: proxyAgent,
-  },
-});
+```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 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 build          # tsdown → dist/ (runs publint + arethetypeswrong)
+pnpm test:pack      # pack the real tarball, typecheck + import every drop-in subpath
+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
 ```
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
-
-```ts
-import Composio from '@composio/client';
-
-const client = new Composio({
-  fetchOptions: {
-    proxy: 'http://localhost:8888',
-  },
-});
-```
+`src/generated/` and `src/compat/resources/` are regenerated output — never edit them by hand; CI fails if they drift from `spec/openapi.json`.
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+### Python lane
 
-```ts
-import Composio from 'npm:@composio/client';
+The Python client lives in the [`python/`](./python/README.md) workspace (uv-managed):
 
-const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
-const client = new Composio({
-  fetchOptions: {
-    client: httpClient,
-  },
-});
+```sh
+pnpm generate:python   # from the repo root: spec snapshot → python/src/composio_client/_generated
+cd python
+uv sync
+uv run ruff check
+uv run mypy src scripts
+uv run pytest
 ```
-
-## Frequently Asked Questions
-
-## Semantic versioning
-
-This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
-
-1. Changes that only affect static types, without breaking runtime behavior.
-2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
-3. Changes that we do not expect to impact the vast majority of users in practice.
-
-We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
-
-We are keen for your feedback; please open an [issue](https://www.github.com/ComposioHQ/composio-base-ts/issues) with questions, bugs, or suggestions.
-
-## Requirements
-
-TypeScript >= 4.9 is supported.
-
-The following runtimes are supported:
-
-- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 18 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
-- Deno v1.28.0 or higher.
-- Bun 1.0 or later.
-- Cloudflare Workers.
-- Vercel Edge Runtime.
-- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
-- Nitro v2.6 or greater.
-
-Note that React Native is not supported at this time.
-
-If you are interested in other runtime environments, please open or upvote an issue on GitHub.
-
-## Contributing
-
-See [the contributing documentation](./CONTRIBUTING.md).

package/dist/api-key-revocation-BZL5FAx7.mjs

@@ -0,0 +1,24 @@
+import { r as path } from "./request-DwPfYYNF.mjs";
+
+//#region src/compat/resources/api-key-revocation.ts
+/**
+* Spec-surface `client.apiKeyRevocation` resource: the 1-method public
+* leaked-key revocation surface of the v3.1 spec
+* (`POST /api_key_revocation` — POST-on-collection stays `create`), never
+* published by Stainless — wayfinder ticket 32.
+*/
+var ApiKeyRevocation = class {
+	#client;
+	constructor(client) {
+		this.#client = client;
+	}
+	create(body, options) {
+		return this.#client.post(path`/api/v3.1/api_key_revocation`, {
+			body,
+			...options
+		});
+	}
+};
+
+//#endregion
+export { ApiKeyRevocation as t };

package/dist/auth-CEq4JqWm.mjs

@@ -0,0 +1,17 @@
+import { t as Session } from "./session-DNm4GFO-.mjs";
+
+//#region src/compat/resources/auth/auth.ts
+/**
+* Spec-surface `client.auth` resource: a method-less container for the
+* `session` sub-resource — wayfinder ticket 32.
+*/
+var Auth = class {
+	session;
+	constructor(client) {
+		this.session = new Session(client);
+	}
+};
+Auth.Session = Session;
+
+//#endregion
+export { Auth as t };

package/dist/auth-configs-CyksMqNB.mjs

@@ -0,0 +1,48 @@
+import { r as path } from "./request-DwPfYYNF.mjs";
+
+//#region src/compat/resources/auth-configs.ts
+/**
+* Stainless-shaped `client.authConfigs` resource: the exact 6-method surface of
+* `@composio/client` (create/retrieve/update/list/delete/updateStatus),
+* dispatched through the handwritten kernel.
+*/
+var AuthConfigs = class {
+	#client;
+	constructor(client) {
+		this.#client = client;
+	}
+	create(body, options) {
+		return this.#client.post(path`/api/v3.1/auth_configs`, {
+			body,
+			...options
+		});
+	}
+	retrieve(nanoid, options) {
+		return this.#client.get(path`/api/v3.1/auth_configs/${nanoid}`, { ...options });
+	}
+	update(nanoid, body, options) {
+		return this.#client.patch(path`/api/v3.1/auth_configs/${nanoid}`, {
+			body,
+			...options
+		});
+	}
+	list(query = {}, options) {
+		return this.#client.get(path`/api/v3.1/auth_configs`, {
+			query,
+			...options
+		});
+	}
+	delete(nanoid, query = {}, options) {
+		return this.#client.delete(path`/api/v3.1/auth_configs/${nanoid}`, {
+			query,
+			...options
+		});
+	}
+	updateStatus(status, params, options) {
+		const { nanoid } = params;
+		return this.#client.patch(path`/api/v3.1/auth_configs/${nanoid}/${status}`, { ...options });
+	}
+};
+
+//#endregion
+export { AuthConfigs as t };

package/dist/clanker-4wByThQJ.mjs

@@ -0,0 +1,23 @@
+import { r as path } from "./request-DwPfYYNF.mjs";
+
+//#region src/compat/resources/org/clanker.ts
+/**
+* Spec-surface `client.org.clanker` resource: the 1-method claim surface of
+* the v3.1 spec (`POST /org/clanker/create_claim`), never published by
+* Stainless — wayfinder ticket 31.
+*/
+var Clanker = class {
+	#client;
+	constructor(client) {
+		this.#client = client;
+	}
+	createClaim(body, options) {
+		return this.#client.post(path`/api/v3.1/org/clanker/create_claim`, {
+			body,
+			...options
+		});
+	}
+};
+
+//#endregion
+export { Clanker as t };

package/dist/cli-Bi4_ORQO.mjs

@@ -0,0 +1,45 @@
+import { r as path } from "./request-DwPfYYNF.mjs";
+import { t as Realtime } from "./realtime-BcHoYszT.mjs";
+
+//#region src/compat/resources/cli/cli.ts
+/**
+* Stainless-shaped `client.cli` resource: the 2-method published CLI
+* authentication surface of `@composio/client` (createSession/getSession)
+* plus the spec-surface `createCodactFailure` (`POST /cli/codact_failures`,
+* never published by Stainless — wayfinder ticket 29).
+*/
+var Cli = class {
+	realtime;
+	#client;
+	constructor(client) {
+		this.#client = client;
+		this.realtime = new Realtime(client);
+	}
+	createCodactFailure(params, options) {
+		const { "x-user-api-key": xUserApiKey, ...body } = params;
+		return this.#client.post(path`/api/v3.1/cli/codact_failures`, {
+			body,
+			...options,
+			headers: {
+				...xUserApiKey != null ? { "x-user-api-key": xUserApiKey } : void 0,
+				...options?.headers
+			}
+		});
+	}
+	createSession(body = {}, options) {
+		return this.#client.post(path`/api/v3.1/cli/create-session`, {
+			body,
+			...options
+		});
+	}
+	getSession(query, options) {
+		return this.#client.get(path`/api/v3.1/cli/get-session`, {
+			query,
+			...options
+		});
+	}
+};
+Cli.Realtime = Realtime;
+
+//#endregion
+export { Cli as t };