@devries-cameron20 / composio-1 / commits / 5149161ad
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: document TypeScript SDK 0.26.0 release (#5044)

This PR: - no Linear issue; prepares the authorized TypeScript SDK release - documents core/slim `0.26.0` and the JSON Schema to Zod, Vercel, LlamaIndex, and Claude Agent SDK provider releases - explains direct client access, custom header, Vercel schema, Zod, and deprecated connection-data migration steps - supplies the changelog version required by the pending Changesets release PR independently of Python release preparation Validation: `pnpm test:release-workflow`, changelog formatting, and `git diff --check` pass. The combined release candidate built successfully and passed all 11 providers across the packed compatibility harness's 13 lanes.

Alberto Schiabel committed Oct 22, 2026 at 01:29 UTC 5149161adb6574c76c4ca2fff4dd586c064877f4
1 file changed +43
docs/content/changelog/10-22-26-typescript-sdk-release.mdx new
+43
@@ -0,0 +1,43 @@
1 +---
2 +title: 'TypeScript SDK 0.26.0: toolkit warnings and provider schema fixes'
3 +description: 'Get toolkit sunset warnings, preserve tool schemas across TypeScript providers, and migrate direct API client access.'
4 +date: '2026-10-22'
5 +---
6 +
7 +The TypeScript SDK now warns when the API reports that a toolkit version you use is deprecated. This release also preserves more of your tool schemas and arguments across providers.
8 +
9 +### Release versions
10 +
11 +| SDK | Version |
12 +| ----------------------------------------- | -------- |
13 +| TypeScript `@composio/core` | `0.26.0` |
14 +| TypeScript `@composio/slim` | `0.26.0` |
15 +| TypeScript `@composio/json-schema-to-zod` | `0.4.0` |
16 +| TypeScript `@composio/claude-agent-sdk` | `0.13.0` |
17 +| TypeScript `@composio/vercel` | `0.13.0` |
18 +| TypeScript `@composio/llamaindex` | `0.11.2` |
19 +
20 +### What's new
21 +
22 +- **Toolkit deprecation warnings.** The SDK warns once per process for each deprecated toolkit version reported through the `Composio-Deprecated-Toolkits` response header. The warning names the version, its sunset date, and how to pin a newer version. See [toolkit versioning](/docs/tools-direct/toolkit-versioning#deprecation-and-sunset).
23 +- **Zod v4 schema builder.** Import `jsonSchemaToZod` or `jsonSchemaToZodShape` from `@composio/json-schema-to-zod/v4` to build classic Zod v4 schemas. The root entry continues to build Zod v3 schemas. The v4 builder requires Zod `4.1.13` or newer and preserves schema annotations in metadata for `z.toJSONSchema()`.
24 +- **Provider schema preservation.** The TypeScript Vercel and LlamaIndex providers now give the model the tool's JSON Schema directly, preserving keywords such as `format`, `contentEncoding`, and `contentMediaType`. Claude Agent SDK uses the new Zod v4 builder to preserve those annotations. Existing tool argument validation stays in place.
25 +
26 +### Migration notes
27 +
28 +<Callout type="warn">
29 + This release changes direct API client access, TypeScript Vercel tool schemas, and the Claude
30 + Agent SDK provider's minimum Zod version. Apply the relevant steps below before upgrading.
31 +</Callout>
32 +
33 +1. **TypeScript client access.** Read credentials from `composio.getConfig()` instead of `composio.getClient().apiKey`, `.userApiKey`, or `.orgApiKey`. The client also removes `.logger`. Its `baseURL`, `maxRetries`, `timeout`, and `logLevel` are read-only; derive a client with `withOptions()` to change them. For example, replace `composio.getClient().maxRetries = 0` with `const client = composio.getClient().withOptions({ maxRetries: 0 })` and use the derived client for those calls.
34 +2. **TypeScript custom headers.** Replace `COMPOSIO_CUSTOM_HEADERS` with the SDK's `defaultHeaders` option. Credential and scope headers in `defaultHeaders` or `createSession({ headers })` are folded into SDK configuration and no longer appear under `getConfig().defaultHeaders`. Supply at most one of `x-api-key`, `x-user-api-key`, or `x-org-api-key`; multiple credential headers now throw. Per-call client headers cannot override credentials or scope. With `apiKey: null` and only an organization API key, API calls, trigger authorization, and `session.mcp.headers` now consistently carry `x-org-api-key`.
35 +3. **Vercel tool schemas.** `tool.inputSchema` is now an AI SDK `Schema`. Replace direct `tool.inputSchema.safeParse(value)` calls with `asSchema(tool.inputSchema).validate(value)`, importing `asSchema` from `ai`.
36 +4. **Claude Agent SDK and Zod v4.** Upgrade Zod to `4.1.13` or newer before upgrading `@composio/claude-agent-sdk`. Older Zod v4 versions do not provide the shared metadata registry the builder needs.
37 +5. **Deprecated TypeScript connection data.** For `customConnectionData` with `S2S_OAUTH2`, supply `val.access_token`, which the API requires.
38 +
39 +### Bug fixes
40 +
41 +- **Strict TypeScript tool schemas.** OpenAPI `nullable` is converted into a nullable type or a null branch. Unsupported string formats, including `uri`, custom formats, and `path`, are removed before strict requests reach the model provider. This prevents a single tool schema from causing the whole request to fail.
42 +- **String argument validation.** TypeScript checks a string as base64 only when its `contentEncoding` is `base64`. Fields with `format: "binary"` or another encoding, such as `base16`, accept plain strings instead of being rejected as invalid base64.
43 +- **Zod v3 validation paths.** Errors inside nested object properties report each property name once, including errors from `patternProperties`, `additionalProperties`, and `oneOf`.