@devries-cameron20 / composio Mirror · read-only / commits / a5a1fc867
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 07:15 UTC

feat(core,python): add custom toolkit create/update, deprecate upsert (PLEN-4785)

Wrap the v3.1 custom toolkit create (POST /api/v3.1/custom/toolkits) and update (PATCH /api/v3.1/custom/toolkits/{slug}) endpoints as experimental.customToolkits.create()/update() in TypeScript and experimental.custom_toolkits.create()/update() in Python. upsert() is deprecated and warns once per process. Bumps @composio/client and composio-client to 2.0.1, which add the two operations. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H6YzWq98kCUE5K3atCRATH

Bharath committed Nov 3, 2026 at 11:34 UTC a5a1fc867410fcb0d190d3c23869d4e977876a45
14 files changed +585 -48
.changeset/custom-toolkit-create-update.md new
+6
@@ -0,0 +1,6 @@
1 +---
2 +'@composio/core': minor
3 +'@composio/slim': minor
4 +---
5 +
6 +Requires `@composio/client` `2.0.1`. Adds `composio.experimental.customToolkits.create()` and `update()`, which call the v3.1 custom toolkit create and update endpoints. `create()` takes `userId` (`'all'` to share the toolkit, or the user it is private to), generates the slug, and returns a `connectLink` for a private toolkit. `upsert()` is deprecated and logs a warning once per process; it keeps working.
pnpm-lock.yaml
+9 -9
@@ -28,8 +28,8 @@ catalogs:
28 specifier: ^5.20261019.1
29 version: 5.20261019.1
30 '@composio/client':
31 - specifier: 2.0.0
32 - version: 2.0.0
31 + specifier: 2.0.1
32 + version: 2.0.1
33 '@effect/language-service':
34 specifier: ^0.87.5
35 version: 0.87.5
@@ -998,7 +998,7 @@ importers:
998 dependencies:
999 '@composio/client':
1000 specifier: 'catalog:'
1001 - version: 2.0.0(effect@4.1.1)
1001 + version: 2.0.1(effect@4.1.1)
1002 '@composio/core':
1003 specifier: workspace:*
1004 version: link:../../packages/core
@@ -1246,7 +1246,7 @@ importers:
1246 version: link:../cli-keyring
1247 '@composio/client':
1248 specifier: 'catalog:'
1249 - version: 2.0.0(effect@4.1.1)
1249 + version: 2.0.1(effect@4.1.1)
1250 '@composio/core':
1251 specifier: workspace:*
1252 version: link:../core
@@ -1355,7 +1355,7 @@ importers:
1355 dependencies:
1356 '@composio/client':
1357 specifier: 'catalog:'
1358 - version: 2.0.0(effect@4.1.1)
1358 + version: 2.0.1(effect@4.1.1)
1359 '@composio/json-schema-to-zod':
1360 specifier: workspace:*
1361 version: link:../json-schema-to-zod
@@ -1772,7 +1772,7 @@ importers:
1772 dependencies:
1773 '@composio/client':
1774 specifier: 'catalog:'
1775 - version: 2.0.0(effect@4.1.1)
1775 + version: 2.0.1(effect@4.1.1)
1776 '@composio/json-schema-to-zod':
1777 specifier: workspace:*
1778 version: link:../json-schema-to-zod
@@ -2324,8 +2324,8 @@ packages:
2324 resolution: {integrity: sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==}
2325 engines: {node: '>=0.1.90'}
2326
2327 - '@composio/client@2.0.0':
2328 - resolution: {integrity: sha512-6NK+TNvpsencFPMLJSm3gaVLl0rwYh+8N8pfRywuK9YcjxsP8H0zunO8h/1xg3rq1iV5/KUxKMGwNWookQLbMQ==}
2327 + '@composio/client@2.0.1':
2328 + resolution: {integrity: sha512-1+Azl8W/grinmXVt6KhDKy5UlvTiv7MCMgjqBDxd8TqndjM92/HotxLabnB63A285bvo5Lcu4kbOz413uaPmEQ==}
2329 engines: {node: '>=22'}
2330 peerDependencies:
2331 effect: '*'
@@ -7541,7 +7541,7 @@ snapshots:
7541 '@colors/colors@1.5.0':
7542 optional: true
7543
7544 - '@composio/client@2.0.0(effect@4.1.1)':
7544 + '@composio/client@2.0.1(effect@4.1.1)':
7545 optionalDependencies:
7546 effect: 4.1.1
7547
pnpm-workspace.yaml
+1 -1
@@ -33,7 +33,7 @@ catalog:
33 '@clack/prompts': '^1.8.1'
34 '@cloudflare/vitest-pool-workers': 0.23.0
35 '@cloudflare/workers-types': ^5.20261019.1
36 - '@composio/client': 2.0.0
36 + '@composio/client': 2.0.1
37 '@effect/language-service': ^0.87.5
38 '@effect/platform-bun': ^4.1.0
39 '@effect/vitest': ^4.1.0
python/composio/client/types.py
+8
@@ -27,8 +27,12 @@ from composio_client.types import (
27 connected_account_retrieve_response,
28 connected_account_revoke_response,
29 connected_account_update_status_response,
30 + custom_create_toolkit_params,
31 + custom_create_toolkit_response,
32 custom_delete_toolkit_response,
33 custom_sync_response,
34 + custom_update_toolkits_params,
35 + custom_update_toolkits_response,
36 custom_upsert_params,
37 custom_upsert_response,
38 keyring_list_transfer_keys_response,
@@ -137,8 +141,12 @@ __all__ = (
141 "connected_account_retrieve_response",
142 "connected_account_revoke_response",
143 "connected_account_update_status_response",
144 + "custom_create_toolkit_params",
145 + "custom_create_toolkit_response",
146 "custom_delete_toolkit_response",
147 "custom_sync_response",
148 + "custom_update_toolkits_params",
149 + "custom_update_toolkits_response",
150 "custom_upsert_params",
151 "custom_upsert_response",
152 "keyring_list_transfer_keys_response",
python/composio/core/models/experimental.py
+98 -1
@@ -17,6 +17,7 @@ not on the underlying model modules.
17 from __future__ import annotations
18
19 import typing as t
20 +import warnings
21
22 import typing_extensions as te
23 from pydantic import BaseModel
@@ -25,8 +26,12 @@ from composio.client import HttpClient
26 from composio.utils.pydantic import none_to_omit
27 from composio.client.types import (
28 connected_account_patch_response,
29 + custom_create_toolkit_params,
30 + custom_create_toolkit_response,
31 custom_delete_toolkit_response,
32 custom_sync_response,
33 + custom_update_toolkits_params,
34 + custom_update_toolkits_response,
35 custom_upsert_params,
36 custom_upsert_response,
37 usage_retrieve_params,
@@ -129,6 +134,15 @@ class ExperimentalUsage:
134 return self._require_client().project.usage.retrieve(entity_type, **params)
135
136
137 +_UPSERT_DEPRECATION = (
138 + "experimental.custom_toolkits.upsert() is deprecated. Use create() for a "
139 + "new toolkit and update(slug, ...) to change its name, logo or API key field."
140 +)
141 +
142 +# Warn once per process so services that upsert on every deploy aren't spammed.
143 +_upsert_warning_emitted = False
144 +
145 +
146 class ExperimentalCustomToolkits:
147 """Project-owned custom toolkits, accessed via
148 ``composio.experimental.custom_toolkits``.
@@ -149,10 +163,78 @@ class ExperimentalCustomToolkits:
163 if self._client is None:
164 raise exceptions.ValidationError(
165 "experimental.custom_toolkits requires a Composio client. Access "
152 - "it via composio.experimental.custom_toolkits.upsert(...)."
166 + "it via composio.experimental.custom_toolkits.create(...)."
167 )
168 return self._client
169
170 + def create(
171 + self,
172 + **params: te.Unpack[custom_create_toolkit_params.CustomCreateToolkitParams],
173 + ) -> custom_create_toolkit_response.CustomCreateToolkitResponse:
174 + """
175 + Create a custom MCP toolkit and return its generated slug.
176 + Experimental — shape may change.
177 +
178 + Set ``user_id`` to ``"all"`` to share the toolkit with every user in
179 + the project, or to a user ID to make it private to that user.
180 + ``app_url``, ``auth_schemes`` and ``user_id`` cannot change later:
181 + delete and re-create the toolkit instead.
182 +
183 + :param name: Display name of the toolkit.
184 + :param app_url: The MCP server URL. Must use https.
185 + :param auth_schemes: How users authenticate to the MCP server.
186 + :param user_id: ``"all"``, or the user ID the toolkit is private to.
187 + :param logo_file: Optional base64 PNG or JPEG logo.
188 + :param callback_url: Where to send the user after they connect. Used
189 + only for ``connect_link``.
190 + :return: The toolkit ``slug`` and, for a private toolkit, a
191 + ``connect_link`` to send that user to (else ``None``).
192 +
193 + Example:
194 + toolkit = composio.experimental.custom_toolkits.create(
195 + name="Internal API",
196 + app_url="https://mcp.internal.example.com/mcp",
197 + auth_schemes=[
198 + {
199 + "mode": "API_KEY",
200 + "headers": {"Authorization": "Bearer {{generic_api_key}}"},
201 + }
202 + ],
203 + user_id="user_123",
204 + )
205 + """
206 + return self._require_client().custom.create_toolkit(**params)
207 +
208 + def update(
209 + self,
210 + slug: str,
211 + **params: te.Unpack[custom_update_toolkits_params.CustomUpdateToolkitsParams],
212 + ) -> custom_update_toolkits_response.CustomUpdateToolkitsResponse:
213 + """
214 + Update a custom toolkit's name, logo or API key field copy. Omitted
215 + fields keep their current value. Experimental — shape may change.
216 +
217 + On a project with 2FA enabled, updating a private toolkit requires the
218 + ``user_id`` it is private to.
219 +
220 + :param slug: The custom toolkit slug returned by :meth:`create`.
221 + :param name: New display name.
222 + :param logo_file: New base64 PNG or JPEG logo.
223 + :param api_key_field: Label and help text for the API key input on
224 + the connect page. API_KEY toolkits only.
225 + :param user_id: The user the toolkit is private to.
226 + :return: ``success``.
227 +
228 + Example:
229 + composio.experimental.custom_toolkits.update(
230 + "CUSTOM_INTERNAL_API_K7F2Q",
231 + name="Internal API (prod)",
232 + user_id="user_123",
233 + )
234 + """
235 + return self._require_client().custom.update_toolkits(slug, **params)
236 +
237 + @te.deprecated(_UPSERT_DEPRECATION, category=None)
238 def upsert(
239 self,
240 **params: te.Unpack[custom_upsert_params.CustomUpsertParams],
@@ -162,6 +244,11 @@ class ExperimentalCustomToolkits:
244 field copy) when the project already owns one with this slug.
245 Experimental — shape may change.
246
247 + .. deprecated::
248 + Use :meth:`create` for a new toolkit and :meth:`update` to change
249 + its name, logo or API key field. ``create`` generates the slug,
250 + so store the slug it returns.
251 +
252 ``app_url`` and ``auth_schemes`` cannot change on an existing
253 toolkit: re-sending them unchanged is a no-op, and changing them fails
254 with a 409. Delete and re-register the toolkit instead, which revokes
@@ -188,6 +275,16 @@ class ExperimentalCustomToolkits:
275 },
276 )
277 """
278 + global _upsert_warning_emitted
279 + if not _upsert_warning_emitted:
280 + from composio import exceptions
281 +
282 + _upsert_warning_emitted = True
283 + warnings.warn(
284 + _UPSERT_DEPRECATION,
285 + exceptions.ComposioDeprecationWarning,
286 + stacklevel=2,
287 + )
288 return self._require_client().custom.upsert(**params)
289
290 def sync(
python/pyproject.toml
+1 -1
@@ -14,7 +14,7 @@ dependencies = [
14 "pysher==1.0.8",
15 "websocket-client<2",
16 "pydantic>=2.11.9,<3",
17 - "composio-client==2.0.0",
17 + "composio-client==2.0.1",
18 "typing-extensions>=4.16.0,<5",
19 "openai>=2.48.0,<4",
20 "json-schema-to-pydantic>=0.4.11,<1",
python/setup.py
+1 -1
@@ -28,7 +28,7 @@ setup(
28 "pysher==1.0.8",
29 "websocket-client<2",
30 "pydantic>=2.11.9,<3",
31 - "composio-client==2.0.0",
31 + "composio-client==2.0.1",
32 "typing-extensions>=4.16.0,<5",
33 "openai>=2.48.0,<4",
34 "json-schema-to-pydantic>=0.4.11,<1",
python/tests/test_experimental_custom_toolkits.py
+45 -1
@@ -1,5 +1,6 @@
1 """Tests for ``composio.experimental.custom_toolkits``."""
2
3 +import warnings
4 from unittest.mock import Mock
5
6 import pytest
@@ -7,6 +8,7 @@ from composio_client import omit
8
9 from composio import exceptions
10 from composio.client.types import custom_upsert_params
11 +from composio.core.models import experimental as experimental_module
12 from composio.core.models.experimental import (
13 ExperimentalAPI,
14 ExperimentalCustomToolkits,
@@ -43,6 +45,46 @@ class TestExperimentalCustomToolkits:
45 assert isinstance(experimental.custom_toolkits, ExperimentalCustomToolkits)
46 assert experimental.custom_toolkits._client is mock_client
47
48 + def test_create_passes_params_through(self, custom_toolkits, mock_client):
49 + mock_client.custom.create_toolkit.return_value = "created"
50 +
51 + result = custom_toolkits.create(**TOOLKIT_CONFIG, user_id="user_123")
52 +
53 + assert result == "created"
54 + mock_client.custom.create_toolkit.assert_called_once_with(
55 + **TOOLKIT_CONFIG, user_id="user_123"
56 + )
57 +
58 + def test_update_passes_slug_and_params_through(self, custom_toolkits, mock_client):
59 + mock_client.custom.update_toolkits.return_value = "updated"
60 +
61 + result = custom_toolkits.update(
62 + "CUSTOM_MY_TOOLKIT_K7F2Q", name="Renamed", user_id="user_123"
63 + )
64 +
65 + assert result == "updated"
66 + mock_client.custom.update_toolkits.assert_called_once_with(
67 + "CUSTOM_MY_TOOLKIT_K7F2Q", name="Renamed", user_id="user_123"
68 + )
69 +
70 + def test_upsert_warns_once_per_process(
71 + self, custom_toolkits, mock_client, monkeypatch
72 + ):
73 + monkeypatch.setattr(experimental_module, "_upsert_warning_emitted", False)
74 +
75 + with warnings.catch_warnings(record=True) as caught:
76 + warnings.simplefilter("always")
77 + custom_toolkits.upsert(slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG)
78 + custom_toolkits.upsert(slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG)
79 +
80 + deprecations = [
81 + w
82 + for w in caught
83 + if issubclass(w.category, exceptions.ComposioDeprecationWarning)
84 + ]
85 + assert len(deprecations) == 1
86 + assert "create()" in str(deprecations[0].message)
87 +
88 def test_upsert_passes_params_through(self, custom_toolkits, mock_client):
89 mock_client.custom.upsert.return_value = "upserted"
90
@@ -84,7 +126,9 @@ class TestExperimentalCustomToolkits:
126 custom_toolkits = ExperimentalCustomToolkits(client=None)
127
128 with pytest.raises(exceptions.ValidationError):
87 - custom_toolkits.upsert(slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG)
129 + custom_toolkits.create(**TOOLKIT_CONFIG, user_id="all")
130 + with pytest.raises(exceptions.ValidationError):
131 + custom_toolkits.update("CUSTOM_MY_TOOLKIT", name="Renamed")
132 with pytest.raises(exceptions.ValidationError):
133 custom_toolkits.sync("CUSTOM_MY_TOOLKIT")
134 with pytest.raises(exceptions.ValidationError):
ts/packages/core/src/models/CustomToolkits.ts
+114 -8
@@ -7,10 +7,16 @@
7 */
8 import ComposioClient from '@composio/client';
9 import {
10 + CustomToolkitCreateParams,
11 + CustomToolkitCreateParamsSchema,
12 + CustomToolkitCreateResponse,
13 CustomToolkitDeleteResponse,
14 CustomToolkitSyncParams,
15 CustomToolkitSyncParamsSchema,
16 CustomToolkitSyncResponse,
17 + CustomToolkitUpdateParams,
18 + CustomToolkitUpdateParamsSchema,
19 + CustomToolkitUpdateResponse,
20 CustomToolkitUpsertParams,
21 CustomToolkitUpsertParamsSchema,
22 CustomToolkitUpsertResponse,
@@ -19,14 +25,24 @@ import { ComposioRequestOptions } from '../types/requestOptions.types';
25 import { ValidationError } from '../errors/ValidationErrors';
26 import { telemetry } from '../telemetry/Telemetry';
27 import { withCancellation } from '../utils/cancellation';
28 +import logger from '../utils/logger';
29 import {
30 + transformCustomToolkitCreateParams,
31 + transformCustomToolkitCreateResponse,
32 transformCustomToolkitDeleteResponse,
33 transformCustomToolkitSyncParams,
34 transformCustomToolkitSyncResponse,
35 + transformCustomToolkitUpdateParams,
36 + transformCustomToolkitUpdateResponse,
37 transformCustomToolkitUpsertParams,
38 transformCustomToolkitUpsertResponse,
39 } from '../utils/transformers/customToolkits';
40
41 +const UPSERT_DEPRECATION =
42 + '[Deprecation] composio.experimental.customToolkits.upsert() is deprecated. ' +
43 + 'Use create() for a new toolkit and update(slug, ...) to change its name, logo or API key field.';
44 +let _upsertDeprecationWarned = false;
45 +
46 /**
47 * `composio.experimental.customToolkits` — toolkits your project registers
48 * from its own app or MCP server, with their own auth configs and connected
@@ -38,15 +54,13 @@ import {
54 *
55 * @example
56 * ```typescript
41 - * const { slug } = await composio.experimental.customToolkits.upsert({
42 - * slug: 'MY_TOOLKIT',
43 - * toolkitConfig: {
44 - * name: 'My Toolkit',
45 - * appUrl: 'https://mcp.example.com/mcp',
46 - * authSchemes: [{ mode: 'DCR_OAUTH', discoveryUrl: 'https://mcp.example.com/.well-known/oauth-authorization-server' }],
47 - * },
57 + * const { slug } = await composio.experimental.customToolkits.create({
58 + * name: 'My Toolkit',
59 + * appUrl: 'https://mcp.example.com/mcp',
60 + * authSchemes: [{ mode: 'DCR_OAUTH', discoveryUrl: 'https://mcp.example.com/.well-known/oauth-authorization-server' }],
61 + * userId: 'all',
62 * });
49 - * await composio.experimental.customToolkits.sync(slug);
63 + * await composio.experimental.customToolkits.update(slug, { name: 'My Renamed Toolkit' });
64 * ```
65 */
66 export class CustomToolkits {
@@ -57,6 +71,90 @@ export class CustomToolkits {
71 telemetry.instrument(this, 'CustomToolkits');
72 }
73
74 + /**
75 + * Creates a custom MCP toolkit and returns its generated slug.
76 + * **Experimental — custom toolkits are in pilot; shape may change.**
77 + *
78 + * Set `userId` to `'all'` to share the toolkit with every user in the
79 + * project, or to a user ID to make it private to that user. `appUrl`,
80 + * `authSchemes` and `userId` cannot change later: delete and re-create the
81 + * toolkit instead. For a private toolkit, `connectLink` is where to send
82 + * that user to connect.
83 + *
84 + * @param {CustomToolkitCreateParams} params - The toolkit to create
85 + * @returns {Promise<CustomToolkitCreateResponse>} The toolkit's slug and, for a private toolkit, a connect link
86 + * @throws {ValidationError} If the params fail validation
87 + *
88 + * @example
89 + * ```typescript
90 + * const { slug, connectLink } = await composio.experimental.customToolkits.create({
91 + * name: 'Internal API',
92 + * appUrl: 'https://mcp.internal.example.com/mcp',
93 + * authSchemes: [
94 + * { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
95 + * ],
96 + * userId: 'user_123',
97 + * });
98 + * ```
99 + */
100 + async create(
101 + params: CustomToolkitCreateParams,
102 + requestOptions?: ComposioRequestOptions
103 + ): Promise<CustomToolkitCreateResponse> {
104 + const parsedParams = CustomToolkitCreateParamsSchema.safeParse(params);
105 + if (!parsedParams.success) {
106 + throw new ValidationError('Failed to parse custom toolkit create params', {
107 + cause: parsedParams.error,
108 + });
109 + }
110 + const body = transformCustomToolkitCreateParams(parsedParams.data);
111 + const result = await withCancellation(
112 + () => this.client.custom.createToolkit(body, requestOptions),
113 + requestOptions?.signal
114 + );
115 + return transformCustomToolkitCreateResponse(result);
116 + }
117 +
118 + /**
119 + * Updates a custom toolkit's name, logo or API key field copy. Omitted
120 + * fields keep their current value.
121 + * **Experimental — custom toolkits are in pilot; shape may change.**
122 + *
123 + * On a project with 2FA enabled, updating a private toolkit requires the
124 + * `userId` it is private to.
125 + *
126 + * @param {string} slug - The custom toolkit slug returned by `create()`
127 + * @param {CustomToolkitUpdateParams} params - At least one of `name`, `logoFile`, `apiKeyField`
128 + * @returns {Promise<CustomToolkitUpdateResponse>} `{ success: true }`
129 + * @throws {ValidationError} If the params fail validation
130 + *
131 + * @example
132 + * ```typescript
133 + * await composio.experimental.customToolkits.update('CUSTOM_INTERNAL_API_K7F2Q', {
134 + * name: 'Internal API (prod)',
135 + * userId: 'user_123',
136 + * });
137 + * ```
138 + */
139 + async update(
140 + slug: string,
141 + params: CustomToolkitUpdateParams,
142 + requestOptions?: ComposioRequestOptions
143 + ): Promise<CustomToolkitUpdateResponse> {
144 + const parsedParams = CustomToolkitUpdateParamsSchema.safeParse(params);
145 + if (!parsedParams.success) {
146 + throw new ValidationError('Failed to parse custom toolkit update params', {
147 + cause: parsedParams.error,
148 + });
149 + }
150 + const body = transformCustomToolkitUpdateParams(parsedParams.data);
151 + const result = await withCancellation(
152 + () => this.client.custom.updateToolkits(slug, body, requestOptions),
153 + requestOptions?.signal
154 + );
155 + return transformCustomToolkitUpdateResponse(result);
156 + }
157 +
158 /**
159 * Creates a custom toolkit, or updates its display metadata (name, API key
160 * field copy) when the project already owns a toolkit with this slug.
@@ -83,11 +181,19 @@ export class CustomToolkits {
181 * },
182 * });
183 * ```
184 + *
185 + * @deprecated Use `create()` for a new toolkit and `update(slug, ...)` to change
186 + * its name, logo or API key field. `create()` generates the slug, so store the
187 + * slug it returns.
188 */
189 async upsert(
190 params: CustomToolkitUpsertParams,
191 requestOptions?: ComposioRequestOptions
192 ): Promise<CustomToolkitUpsertResponse> {
193 + if (!_upsertDeprecationWarned) {
194 + _upsertDeprecationWarned = true;
195 + logger.warn(UPSERT_DEPRECATION);
196 + }
197 const parsedParams = CustomToolkitUpsertParamsSchema.safeParse(params);
198 if (!parsedParams.success) {
199 throw new ValidationError('Failed to parse custom toolkit upsert params', {
ts/packages/core/src/models/Experimental.ts
+1 -1
@@ -144,7 +144,7 @@ export class Experimental {
144 usage: Usage;
145
146 /**
147 - * Register and manage project-owned custom toolkits (`upsert()` / `sync()` / `delete()`).
147 + * Register and manage project-owned custom toolkits (`create()` / `update()` / `sync()` / `delete()`).
148 * **Experimental — custom toolkits are in pilot; shape may change.**
149 *
150 * @example
ts/packages/core/src/types/customToolkits.types.ts
+83 -12
@@ -1,5 +1,11 @@
1 import { z } from 'zod/v3';
2
3 +const CustomToolkitApiKeyFieldSchema = z.object({
4 + displayName: z.string().min(1).max(100).optional(),
5 + description: z.string().min(1).max(500).optional(),
6 +});
7 +export type CustomToolkitApiKeyField = z.infer<typeof CustomToolkitApiKeyFieldSchema>;
8 +
9 /**
10 * How end users authenticate to a custom toolkit.
11 * **Experimental — custom toolkits are in pilot; shape may change.**
@@ -15,12 +21,7 @@ export const CustomToolkitAuthSchemeSchema = z.discriminatedUnion('mode', [
21 */
22 headers: z.record(z.string(), z.string()),
23 /** End-user copy for the API key input on the connect page. */
18 - apiKeyField: z
19 - .object({
20 - displayName: z.string().min(1).max(100).optional(),
21 - description: z.string().min(1).max(500).optional(),
22 - })
23 - .optional(),
24 + apiKeyField: CustomToolkitApiKeyFieldSchema.optional(),
25 }),
26 z.object({
27 mode: z.literal('DCR_OAUTH'),
@@ -33,9 +34,84 @@ export const CustomToolkitAuthSchemeSchema = z.discriminatedUnion('mode', [
34 ]);
35 export type CustomToolkitAuthScheme = z.infer<typeof CustomToolkitAuthSchemeSchema>;
36
37 +const CustomToolkitLogoFileSchema = z.object({
38 + content: z.string().min(1),
39 + mimeType: z.enum(['image/png', 'image/jpeg']),
40 +});
41 +export type CustomToolkitLogoFile = z.infer<typeof CustomToolkitLogoFileSchema>;
42 +
43 +/**
44 + * Params for `composio.experimental.customToolkits.create()`.
45 + * **Experimental — custom toolkits are in pilot; shape may change.**
46 + */
47 +export const CustomToolkitCreateParamsSchema = z.object({
48 + /** Human-readable toolkit name. */
49 + name: z.string().min(1).max(200),
50 + /** The MCP server URL. Must use https. */
51 + appUrl: z.string().url(),
52 + /** Square PNG or JPEG logo (256-1024px, max 3MB), base64-encoded. Defaults to the MCP logo. */
53 + logoFile: CustomToolkitLogoFileSchema.optional(),
54 + /** At least one scheme. Cannot be changed after create. */
55 + authSchemes: z.array(CustomToolkitAuthSchemeSchema).min(1),
56 + /**
57 + * `'all'` to share the toolkit with every user in the project, or a user ID
58 + * to make it private to that user. Cannot be changed after create.
59 + */
60 + userId: z.string().min(1),
61 + /** Where to send the user after they connect. Used only for `connectLink`. */
62 + callbackUrl: z.string().url().optional(),
63 +});
64 +export type CustomToolkitCreateParams = z.infer<typeof CustomToolkitCreateParamsSchema>;
65 +
66 +export const CustomToolkitCreateResponseSchema = z.object({
67 + /** Slug of the created toolkit. Store it to update, sync or delete the toolkit later. */
68 + slug: z.string(),
69 + /**
70 + * Hosted connect page for a private toolkit's user. `null` for shared or
71 + * no-auth toolkits, or if the link could not be created.
72 + */
73 + connectLink: z
74 + .object({
75 + redirectUrl: z.string(),
76 + expiresAt: z.string(),
77 + connectedAccountId: z.string(),
78 + })
79 + .nullable(),
80 +});
81 +export type CustomToolkitCreateResponse = z.infer<typeof CustomToolkitCreateResponseSchema>;
82 +
83 +/**
84 + * Params for `composio.experimental.customToolkits.update()`.
85 + * **Experimental — custom toolkits are in pilot; shape may change.**
86 + */
87 +export const CustomToolkitUpdateParamsSchema = z
88 + .object({
89 + name: z.string().min(1).max(200).optional(),
90 + logoFile: CustomToolkitLogoFileSchema.optional(),
91 + /** End-user copy for the API key input on the connect page. API_KEY toolkits only. */
92 + apiKeyField: CustomToolkitApiKeyFieldSchema.optional(),
93 + /**
94 + * The user the toolkit is private to. Required to update a private toolkit
95 + * when the project has 2FA enabled.
96 + */
97 + userId: z.string().min(1).optional(),
98 + })
99 + .refine(
100 + params => [params.name, params.logoFile, params.apiKeyField].some(value => value !== undefined),
101 + { message: 'Provide at least one of name, logoFile, apiKeyField' }
102 + );
103 +export type CustomToolkitUpdateParams = z.infer<typeof CustomToolkitUpdateParamsSchema>;
104 +
105 +export const CustomToolkitUpdateResponseSchema = z.object({
106 + success: z.literal(true),
107 +});
108 +export type CustomToolkitUpdateResponse = z.infer<typeof CustomToolkitUpdateResponseSchema>;
109 +
110 /**
111 * Params for `composio.experimental.customToolkits.upsert()`.
112 * **Experimental — custom toolkits are in pilot; shape may change.**
113 + *
114 + * @deprecated Use `CustomToolkitCreateParams` with `create()`.
115 */
116 export const CustomToolkitUpsertParamsSchema = z.object({
117 /**
@@ -53,12 +129,7 @@ export const CustomToolkitUpsertParamsSchema = z.object({
129 /** The app URL. For an MCP app, the MCP server URL. */
130 appUrl: z.string().url(),
131 /** Square PNG or JPEG logo (256-1024px, max 3MB), base64-encoded. Defaults to the Composio logo. */
56 - logoFile: z
57 - .object({
58 - content: z.string().min(1),
59 - mimeType: z.enum(['image/png', 'image/jpeg']),
60 - })
61 - .optional(),
132 + logoFile: CustomToolkitLogoFileSchema.optional(),
133 /** At least one scheme. The schemes cannot change once the toolkit exists. */
134 authSchemes: z.array(CustomToolkitAuthSchemeSchema).min(1),
135 }),
ts/packages/core/src/utils/transformers/customToolkits.ts
+70 -9
@@ -1,24 +1,48 @@
1 import type {
2 + CustomCreateToolkitParams as RawCustomCreateToolkitParams,
3 + CustomCreateToolkitResponse as RawCustomCreateToolkitResponse,
4 CustomDeleteToolkitResponse as RawCustomDeleteToolkitResponse,
5 CustomSyncParams as RawCustomSyncParams,
6 CustomSyncResponse as RawCustomSyncResponse,
7 + CustomUpdateToolkitsParams as RawCustomUpdateToolkitsParams,
8 + CustomUpdateToolkitsResponse as RawCustomUpdateToolkitsResponse,
9 CustomUpsertParams as RawCustomUpsertParams,
10 CustomUpsertResponse as RawCustomUpsertResponse,
11 } from '@composio/client/resources/custom';
12 import {
13 + CustomToolkitApiKeyField,
14 CustomToolkitAuthScheme,
15 + CustomToolkitCreateParams,
16 + CustomToolkitCreateResponse,
17 + CustomToolkitCreateResponseSchema,
18 CustomToolkitDeleteResponse,
19 CustomToolkitDeleteResponseSchema,
20 + CustomToolkitLogoFile,
21 CustomToolkitSyncParams,
22 CustomToolkitSyncResponse,
23 CustomToolkitSyncResponseSchema,
24 + CustomToolkitUpdateParams,
25 + CustomToolkitUpdateResponse,
26 + CustomToolkitUpdateResponseSchema,
27 CustomToolkitUpsertParams,
28 CustomToolkitUpsertResponse,
29 CustomToolkitUpsertResponseSchema,
30 } from '../../types/customToolkits.types';
31 import { transform } from '../transform';
32
21 -type RawCustomToolkitAuthScheme = RawCustomUpsertParams['toolkit_config']['auth_schemes'][number];
33 +type RawCustomToolkitAuthScheme = RawCustomCreateToolkitParams['auth_schemes'][number];
34 +type RawCustomToolkitLogoFile = NonNullable<RawCustomCreateToolkitParams['logo_file']>;
35 +
36 +const transformCustomToolkitLogoFile = (
37 + logoFile: CustomToolkitLogoFile | undefined
38 +): RawCustomToolkitLogoFile | undefined =>
39 + logoFile && { content: logoFile.content, mime_type: logoFile.mimeType };
40 +
41 +const transformCustomToolkitApiKeyField = (apiKeyField: CustomToolkitApiKeyField | undefined) =>
42 + apiKeyField && {
43 + display_name: apiKeyField.displayName,
44 + description: apiKeyField.description,
45 + };
46
47 const transformCustomToolkitAuthScheme = (
48 scheme: CustomToolkitAuthScheme
@@ -30,16 +54,56 @@ const transformCustomToolkitAuthScheme = (
54 return {
55 mode: 'API_KEY',
56 headers: scheme.headers,
33 - api_key_field: scheme.apiKeyField && {
34 - display_name: scheme.apiKeyField.displayName,
35 - description: scheme.apiKeyField.description,
36 - },
57 + api_key_field: transformCustomToolkitApiKeyField(scheme.apiKeyField),
58 };
59 case 'DCR_OAUTH':
60 return { mode: 'DCR_OAUTH', discovery_url: scheme.discoveryUrl };
61 }
62 };
63
64 +export const transformCustomToolkitCreateParams = (
65 + params: CustomToolkitCreateParams
66 +): RawCustomCreateToolkitParams => ({
67 + name: params.name,
68 + app_url: params.appUrl,
69 + logo_file: transformCustomToolkitLogoFile(params.logoFile),
70 + auth_schemes: params.authSchemes.map(transformCustomToolkitAuthScheme),
71 + user_id: params.userId,
72 + callback_url: params.callbackUrl,
73 +});
74 +
75 +export const transformCustomToolkitCreateResponse = (
76 + response: RawCustomCreateToolkitResponse
77 +): CustomToolkitCreateResponse => {
78 + return transform(response)
79 + .with(CustomToolkitCreateResponseSchema)
80 + .using(response => ({
81 + slug: response.slug,
82 + connectLink: response.connect_link && {
83 + redirectUrl: response.connect_link.redirect_url,
84 + expiresAt: response.connect_link.expires_at,
85 + connectedAccountId: response.connect_link.connected_account_id,
86 + },
87 + }));
88 +};
89 +
90 +export const transformCustomToolkitUpdateParams = (
91 + params: CustomToolkitUpdateParams
92 +): RawCustomUpdateToolkitsParams => ({
93 + name: params.name,
94 + logo_file: transformCustomToolkitLogoFile(params.logoFile),
95 + api_key_field: transformCustomToolkitApiKeyField(params.apiKeyField),
96 + user_id: params.userId,
97 +});
98 +
99 +export const transformCustomToolkitUpdateResponse = (
100 + response: RawCustomUpdateToolkitsResponse
101 +): CustomToolkitUpdateResponse => {
102 + return transform(response)
103 + .with(CustomToolkitUpdateResponseSchema)
104 + .using(response => ({ success: response.success }));
105 +};
106 +
107 export const transformCustomToolkitUpsertParams = (
108 params: CustomToolkitUpsertParams
109 ): RawCustomUpsertParams => ({
@@ -47,10 +111,7 @@ export const transformCustomToolkitUpsertParams = (
111 toolkit_config: {
112 name: params.toolkitConfig.name,
113 app_url: params.toolkitConfig.appUrl,
50 - logo_file: params.toolkitConfig.logoFile && {
51 - content: params.toolkitConfig.logoFile.content,
52 - mime_type: params.toolkitConfig.logoFile.mimeType,
53 - },
114 + logo_file: transformCustomToolkitLogoFile(params.toolkitConfig.logoFile),
115 auth_schemes: params.toolkitConfig.authSchemes.map(transformCustomToolkitAuthScheme),
116 },
117 });
ts/packages/core/test/models/customToolkits.test.ts
+144
@@ -13,6 +13,8 @@ vi.mock('../../src/telemetry/Telemetry', () => ({
13
14 const createMockClient = () => ({
15 custom: {
16 + createToolkit: vi.fn(),
17 + updateToolkits: vi.fn(),
18 upsert: vi.fn(),
19 sync: vi.fn(),
20 deleteToolkit: vi.fn(),
@@ -34,7 +36,149 @@ describe('Experimental.customToolkits', () => {
36 expect(telemetry.instrument).toHaveBeenCalledWith(customToolkits, 'CustomToolkits');
37 });
38
39 + describe('create', () => {
40 + it('maps the toolkit to the wire and transforms the connect link', async () => {
41 + mockClient.custom.createToolkit.mockResolvedValue({
42 + slug: 'CUSTOM_MY_TOOLKIT_K7F2Q',
43 + connect_link: {
44 + redirect_url: 'https://connect.composio.dev/link/lk_1',
45 + expires_at: '2026-11-03T12:00:00Z',
46 + connected_account_id: 'ca_abc123',
47 + },
48 + });
49 + const signal = new AbortController().signal;
50 +
51 + const result = await customToolkits.create(
52 + {
53 + name: 'My Toolkit',
54 + appUrl: 'https://mcp.example.com/mcp',
55 + logoFile: { content: 'aGVsbG8=', mimeType: 'image/png' },
56 + authSchemes: [
57 + {
58 + mode: 'API_KEY',
59 + headers: { Authorization: 'Bearer {{generic_api_key}}' },
60 + apiKeyField: { displayName: 'API key' },
61 + },
62 + ],
63 + userId: 'user_123',
64 + callbackUrl: 'https://app.example.com/connected',
65 + },
66 + { signal }
67 + );
68 +
69 + const [body, options] = mockClient.custom.createToolkit.mock.calls[0];
70 + expect(JSON.parse(JSON.stringify(body))).toEqual({
71 + name: 'My Toolkit',
72 + app_url: 'https://mcp.example.com/mcp',
73 + logo_file: { content: 'aGVsbG8=', mime_type: 'image/png' },
74 + auth_schemes: [
75 + {
76 + mode: 'API_KEY',
77 + headers: { Authorization: 'Bearer {{generic_api_key}}' },
78 + api_key_field: { display_name: 'API key' },
79 + },
80 + ],
81 + user_id: 'user_123',
82 + callback_url: 'https://app.example.com/connected',
83 + });
84 + expect(options).toEqual({ signal });
85 + expect(result).toEqual({
86 + slug: 'CUSTOM_MY_TOOLKIT_K7F2Q',
87 + connectLink: {
88 + redirectUrl: 'https://connect.composio.dev/link/lk_1',
89 + expiresAt: '2026-11-03T12:00:00Z',
90 + connectedAccountId: 'ca_abc123',
91 + },
92 + });
93 + });
94 +
95 + it('returns a null connect link for a shared toolkit', async () => {
96 + mockClient.custom.createToolkit.mockResolvedValue({
97 + slug: 'CUSTOM_MY_TOOLKIT_K7F2Q',
98 + connect_link: null,
99 + });
100 +
101 + const result = await customToolkits.create({
102 + name: 'My Toolkit',
103 + appUrl: 'https://mcp.example.com/mcp',
104 + authSchemes: [{ mode: 'NO_AUTH' }],
105 + userId: 'all',
106 + });
107 +
108 + expect(result).toEqual({ slug: 'CUSTOM_MY_TOOLKIT_K7F2Q', connectLink: null });
109 + });
110 +
111 + it.each([
112 + ['no user ID', { userId: undefined }],
113 + ['no auth schemes', { authSchemes: [] }],
114 + ['an app URL that is not a URL', { appUrl: 'not a url' }],
115 + ])('rejects %s before calling the API', async (_label, override) => {
116 + await expect(
117 + customToolkits.create({
118 + name: 'My Toolkit',
119 + appUrl: 'https://mcp.example.com/mcp',
120 + authSchemes: [{ mode: 'NO_AUTH' }],
121 + userId: 'all',
122 + ...(override as object),
123 + })
124 + ).rejects.toThrow(ValidationError);
125 + expect(mockClient.custom.createToolkit).not.toHaveBeenCalled();
126 + });
127 + });
128 +
129 + describe('update', () => {
130 + it('sends only the given fields and transforms the response', async () => {
131 + mockClient.custom.updateToolkits.mockResolvedValue({ success: true });
132 +
133 + const result = await customToolkits.update('CUSTOM_MY_TOOLKIT_K7F2Q', {
134 + apiKeyField: { displayName: 'Token', description: 'From your settings page' },
135 + userId: 'user_123',
136 + });
137 +
138 + const [slug, body] = mockClient.custom.updateToolkits.mock.calls[0];
139 + expect(slug).toBe('CUSTOM_MY_TOOLKIT_K7F2Q');
140 + expect(JSON.parse(JSON.stringify(body))).toEqual({
141 + api_key_field: { display_name: 'Token', description: 'From your settings page' },
142 + user_id: 'user_123',
143 + });
144 + expect(result).toEqual({ success: true });
145 + });
146 +
147 + it('rejects an update with nothing to change before calling the API', async () => {
148 + await expect(
149 + customToolkits.update('CUSTOM_MY_TOOLKIT_K7F2Q', { userId: 'user_123' })
150 + ).rejects.toThrow(ValidationError);
151 + expect(mockClient.custom.updateToolkits).not.toHaveBeenCalled();
152 + });
153 + });
154 +
155 describe('upsert', () => {
156 + it('warns once per process that it is deprecated', async () => {
157 + vi.resetModules();
158 + const { CustomToolkits: FreshCustomToolkits } =
159 + await import('../../src/models/CustomToolkits');
160 + const { default: freshLogger } = await import('../../src/utils/logger');
161 + const warn = vi.spyOn(freshLogger, 'warn').mockImplementation(() => {});
162 + mockClient.custom.upsert.mockResolvedValue({ slug: 'CUSTOM_MY_TOOLKIT' });
163 + const fresh = new FreshCustomToolkits(mockClient as unknown as ComposioClient);
164 + const params = {
165 + slug: 'MY_TOOLKIT',
166 + toolkitConfig: {
167 + name: 'My Toolkit',
168 + appUrl: 'https://mcp.example.com/mcp',
169 + authSchemes: [{ mode: 'NO_AUTH' as const }],
170 + },
171 + };
172 +
173 + await fresh.upsert(params);
174 + await fresh.upsert(params);
175 +
176 + const deprecationWarnings = warn.mock.calls.filter(([message]) =>
177 + String(message).includes('upsert() is deprecated')
178 + );
179 + expect(deprecationWarnings).toHaveLength(1);
180 + });
181 +
182 it('maps every auth scheme and the logo to the wire', async () => {
183 mockClient.custom.upsert.mockResolvedValue({ slug: 'CUSTOM_MY_TOOLKIT' });
184
uv.lock
+4 -4
@@ -534,7 +534,7 @@ release = [
534 [package.metadata]
535 requires-dist = [
536 { name = "certifi", specifier = ">=2026.10.19" },
537 - { name = "composio-client", specifier = "==2.0.0" },
537 + { name = "composio-client", specifier = "==2.0.1" },
538 { name = "json-schema-to-pydantic", specifier = ">=0.4.11,<1" },
539 { name = "jsonschema", specifier = ">=4.23.0,<5" },
540 { name = "openai", specifier = ">=2.48.0,<4" },
@@ -586,16 +586,16 @@ requires-dist = [
586
587 [[package]]
588 name = "composio-client"
589 -version = "2.0.0"
589 +version = "2.0.1"
590 source = { registry = "https://pypi.org/simple" }
591 dependencies = [
592 { name = "httpx" },
593 { name = "pydantic" },
594 { name = "typing-extensions" },
595 ]
596 -sdist = { url = "https://files.pythonhosted.org/packages/c8/7b/be475ecbab35280d6f565b689724d350c06491d3412d65b7f69b4b48c76a/composio_client-2.0.0.tar.gz", hash = "sha256:78d852ace33f6c330bf66628f2e794e8f6a333eeed20f740d162160ec0466944", size = 588293, upload-time = "2026-11-03T08:31:56.577Z" }
596 +sdist = { url = "https://files.pythonhosted.org/packages/11/69/0e6e74fcd32748c9c2f58604e92e1a9fd293033231250d61b35d6a7a93e4/composio_client-2.0.1.tar.gz", hash = "sha256:d23d185b5a45f6628263a37db56567bd8dab6b1dabc0de899ea8ce389b29517b", size = 591542, upload-time = "2026-11-03T11:21:56.274Z" }
597 wheels = [
598 - { url = "https://files.pythonhosted.org/packages/5e/be/2ce8fe148ffaa6ad343a8eea6a4f8558c740fca2308970980e7874f6dbf5/composio_client-2.0.0-py3-none-any.whl", hash = "sha256:4de6ef10ae4b731857dd70b6edbf0fd62c4fd41169e5f8d3f21655637c53cfe6", size = 471648, upload-time = "2026-11-03T08:31:54.624Z" },
598 + { url = "https://files.pythonhosted.org/packages/2e/d7/d4ca7bbbbf4c8b3b2e232e029313a8d59a4dd2f9396683806218f0eefaae/composio_client-2.0.1-py3-none-any.whl", hash = "sha256:e9a24a0883dfa67e19c3d70e0cfe1034cf427411c70edf5e5f4925e4e4d73845", size = 477792, upload-time = "2026-11-03T11:21:54.465Z" },
599 ]
600
601 [[package]]