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, 04:45 UTC
| 1 | /** |
| 2 | * @fileoverview `composio.customToolkits`: register and manage |
| 3 | * project-owned custom toolkits. |
| 4 | * |
| 5 | * @module CustomToolkits |
| 6 | */ |
| 7 | import ComposioClient from '@composio/client'; |
| 8 | import { |
| 9 | CustomToolkitCreateParams, |
| 10 | CustomToolkitCreateParamsSchema, |
| 11 | CustomToolkitCreateResponse, |
| 12 | CustomToolkitDeleteResponse, |
| 13 | CustomToolkitSyncParams, |
| 14 | CustomToolkitSyncParamsSchema, |
| 15 | CustomToolkitSyncResponse, |
| 16 | CustomToolkitUpdateParams, |
| 17 | CustomToolkitUpdateParamsSchema, |
| 18 | CustomToolkitUpdateResponse, |
| 19 | CustomToolkitUpsertParams, |
| 20 | CustomToolkitUpsertParamsSchema, |
| 21 | CustomToolkitUpsertResponse, |
| 22 | } from '../types/customToolkits.types'; |
| 23 | import { ComposioRequestOptions } from '../types/requestOptions.types'; |
| 24 | import { ValidationError } from '../errors/ValidationErrors'; |
| 25 | import { telemetry } from '../telemetry/Telemetry'; |
| 26 | import { withCancellation } from '../utils/cancellation'; |
| 27 | import logger from '../utils/logger'; |
| 28 | import { |
| 29 | transformCustomToolkitCreateParams, |
| 30 | transformCustomToolkitCreateResponse, |
| 31 | transformCustomToolkitDeleteResponse, |
| 32 | transformCustomToolkitSyncParams, |
| 33 | transformCustomToolkitSyncResponse, |
| 34 | transformCustomToolkitUpdateParams, |
| 35 | transformCustomToolkitUpdateResponse, |
| 36 | transformCustomToolkitUpsertParams, |
| 37 | transformCustomToolkitUpsertResponse, |
| 38 | } from '../utils/transformers/customToolkits'; |
| 39 | |
| 40 | const UPSERT_DEPRECATION = |
| 41 | '[Deprecation] composio.customToolkits.upsert() is deprecated. ' + |
| 42 | 'Use create() for a new toolkit and update(slug, ...) to change its name, logo or API key field.'; |
| 43 | let _upsertDeprecationWarned = false; |
| 44 | |
| 45 | /** |
| 46 | * `composio.customToolkits` — toolkits your project registers |
| 47 | * from its own app or MCP server, with their own auth configs and connected |
| 48 | * accounts. |
| 49 | * |
| 50 | * These live on the Composio platform. They are unrelated to the in-process |
| 51 | * toolkits built with `experimental_createToolkit()`, which run inside your |
| 52 | * application. |
| 53 | * |
| 54 | * @example |
| 55 | * ```typescript |
| 56 | * const { slug } = await composio.customToolkits.create({ |
| 57 | * name: 'My Toolkit', |
| 58 | * mcpUrl: 'https://mcp.example.com/mcp', |
| 59 | * authSchemes: [{ mode: 'DCR_OAUTH', discoveryUrl: 'https://mcp.example.com/.well-known/oauth-authorization-server' }], |
| 60 | * userId: 'all', |
| 61 | * }); |
| 62 | * await composio.customToolkits.update(slug, { name: 'My Renamed Toolkit' }); |
| 63 | * ``` |
| 64 | */ |
| 65 | export class CustomToolkits { |
| 66 | private client: ComposioClient; |
| 67 | |
| 68 | constructor(client: ComposioClient) { |
| 69 | this.client = client; |
| 70 | telemetry.instrument(this, 'CustomToolkits'); |
| 71 | } |
| 72 | |
| 73 | /** |
| 74 | * Creates a custom MCP toolkit and returns its generated slug. |
| 75 | * |
| 76 | * Set `userId` to `'all'` to share the toolkit with every user in the |
| 77 | * project, or to a user ID to make it private to that user. `mcpUrl`, |
| 78 | * `authSchemes` and `userId` cannot change later: delete and re-create the |
| 79 | * toolkit instead. For a private toolkit, `connectLink` is where to send |
| 80 | * that user to connect. |
| 81 | * |
| 82 | * @param {CustomToolkitCreateParams} params - The toolkit to create |
| 83 | * @returns {Promise<CustomToolkitCreateResponse>} The toolkit's slug and, for a private toolkit, a connect link |
| 84 | * @throws {ValidationError} If the params fail validation |
| 85 | * |
| 86 | * @example |
| 87 | * ```typescript |
| 88 | * const { slug, connectLink } = await composio.customToolkits.create({ |
| 89 | * name: 'Internal API', |
| 90 | * mcpUrl: 'https://mcp.internal.example.com/mcp', |
| 91 | * authSchemes: [ |
| 92 | * { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } }, |
| 93 | * ], |
| 94 | * userId: 'user_123', |
| 95 | * }); |
| 96 | * ``` |
| 97 | */ |
| 98 | async create( |
| 99 | params: CustomToolkitCreateParams, |
| 100 | requestOptions?: ComposioRequestOptions |
| 101 | ): Promise<CustomToolkitCreateResponse> { |
| 102 | const parsedParams = CustomToolkitCreateParamsSchema.safeParse(params); |
| 103 | if (!parsedParams.success) { |
| 104 | throw new ValidationError('Failed to parse custom toolkit create params', { |
| 105 | cause: parsedParams.error, |
| 106 | }); |
| 107 | } |
| 108 | const body = transformCustomToolkitCreateParams(parsedParams.data); |
| 109 | const result = await withCancellation( |
| 110 | () => this.client.custom.createToolkit(body, requestOptions), |
| 111 | requestOptions?.signal |
| 112 | ); |
| 113 | return transformCustomToolkitCreateResponse(result); |
| 114 | } |
| 115 | |
| 116 | /** |
| 117 | * Updates a custom toolkit's name, logo or API key field copy. Omitted |
| 118 | * fields keep their current value. |
| 119 | * |
| 120 | * On a project with 2FA enabled, updating a private toolkit requires the |
| 121 | * `userId` it is private to. |
| 122 | * |
| 123 | * @param {string} slug - The custom toolkit slug returned by `create()` |
| 124 | * @param {CustomToolkitUpdateParams} params - At least one of `name`, `logoFile`, `apiKeyField` |
| 125 | * @returns {Promise<CustomToolkitUpdateResponse>} `{ success: true }` |
| 126 | * @throws {ValidationError} If the params fail validation |
| 127 | * |
| 128 | * @example |
| 129 | * ```typescript |
| 130 | * await composio.customToolkits.update('CUSTOM_INTERNAL_API_K7F2Q', { |
| 131 | * name: 'Internal API (prod)', |
| 132 | * userId: 'user_123', |
| 133 | * }); |
| 134 | * ``` |
| 135 | */ |
| 136 | async update( |
| 137 | slug: string, |
| 138 | params: CustomToolkitUpdateParams, |
| 139 | requestOptions?: ComposioRequestOptions |
| 140 | ): Promise<CustomToolkitUpdateResponse> { |
| 141 | const parsedParams = CustomToolkitUpdateParamsSchema.safeParse(params); |
| 142 | if (!parsedParams.success) { |
| 143 | throw new ValidationError('Failed to parse custom toolkit update params', { |
| 144 | cause: parsedParams.error, |
| 145 | }); |
| 146 | } |
| 147 | const body = transformCustomToolkitUpdateParams(parsedParams.data); |
| 148 | const result = await withCancellation( |
| 149 | () => this.client.custom.updateToolkits(slug, body, requestOptions), |
| 150 | requestOptions?.signal |
| 151 | ); |
| 152 | return transformCustomToolkitUpdateResponse(result); |
| 153 | } |
| 154 | |
| 155 | /** |
| 156 | * Creates a custom toolkit, or updates its display metadata (name, API key |
| 157 | * field copy) when the project already owns a toolkit with this slug. |
| 158 | * |
| 159 | * `mcpUrl` and `authSchemes` cannot change on an existing toolkit: |
| 160 | * re-sending them unchanged is a no-op, and changing them fails with a 409. |
| 161 | * Delete and re-register the toolkit instead, which revokes its connections. |
| 162 | * |
| 163 | * @param {CustomToolkitUpsertParams} params - The slug and toolkit configuration |
| 164 | * @returns {Promise<CustomToolkitUpsertResponse>} The toolkit's slug |
| 165 | * @throws {ValidationError} If the params fail validation |
| 166 | * |
| 167 | * @example |
| 168 | * ```typescript |
| 169 | * await composio.customToolkits.upsert({ |
| 170 | * slug: 'INTERNAL_API', |
| 171 | * toolkitConfig: { |
| 172 | * name: 'Internal API', |
| 173 | * mcpUrl: 'https://mcp.internal.example.com/mcp', |
| 174 | * authSchemes: [ |
| 175 | * { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } }, |
| 176 | * ], |
| 177 | * }, |
| 178 | * }); |
| 179 | * ``` |
| 180 | * |
| 181 | * @deprecated Use `create()` for a new toolkit and `update(slug, ...)` to change |
| 182 | * its name, logo or API key field. `create()` generates the slug, so store the |
| 183 | * slug it returns. |
| 184 | */ |
| 185 | async upsert( |
| 186 | params: CustomToolkitUpsertParams, |
| 187 | requestOptions?: ComposioRequestOptions |
| 188 | ): Promise<CustomToolkitUpsertResponse> { |
| 189 | if (!_upsertDeprecationWarned) { |
| 190 | _upsertDeprecationWarned = true; |
| 191 | logger.warn(UPSERT_DEPRECATION); |
| 192 | } |
| 193 | const parsedParams = CustomToolkitUpsertParamsSchema.safeParse(params); |
| 194 | if (!parsedParams.success) { |
| 195 | throw new ValidationError('Failed to parse custom toolkit upsert params', { |
| 196 | cause: parsedParams.error, |
| 197 | }); |
| 198 | } |
| 199 | const body = transformCustomToolkitUpsertParams(parsedParams.data); |
| 200 | const result = await withCancellation( |
| 201 | () => this.client.custom.upsert(body, requestOptions), |
| 202 | requestOptions?.signal |
| 203 | ); |
| 204 | return transformCustomToolkitUpsertResponse(result); |
| 205 | } |
| 206 | |
| 207 | /** |
| 208 | * Re-fetches the tool definitions of a custom toolkit from its remote MCP |
| 209 | * server. Call it when automatic sync fails or the remote tools change. |
| 210 | * |
| 211 | * @param {string} slug - The custom toolkit slug (`CUSTOM_...`) |
| 212 | * @param {CustomToolkitSyncParams} [params] - Optional connected account to fetch the definitions with |
| 213 | * @returns {Promise<CustomToolkitSyncResponse>} The toolkit version and number of tools synced |
| 214 | * @throws {ValidationError} If the params fail validation |
| 215 | * |
| 216 | * @example |
| 217 | * ```typescript |
| 218 | * const { version, syncedCount } = await composio.customToolkits.sync( |
| 219 | * 'CUSTOM_MY_TOOLKIT', |
| 220 | * { connectedAccountId: 'ca_abc123' } |
| 221 | * ); |
| 222 | * ``` |
| 223 | */ |
| 224 | async sync( |
| 225 | slug: string, |
| 226 | params?: CustomToolkitSyncParams, |
| 227 | requestOptions?: ComposioRequestOptions |
| 228 | ): Promise<CustomToolkitSyncResponse> { |
| 229 | const parsedParams = CustomToolkitSyncParamsSchema.safeParse(params ?? {}); |
| 230 | if (!parsedParams.success) { |
| 231 | throw new ValidationError('Failed to parse custom toolkit sync params', { |
| 232 | cause: parsedParams.error, |
| 233 | }); |
| 234 | } |
| 235 | const body = transformCustomToolkitSyncParams(slug, parsedParams.data); |
| 236 | const result = await withCancellation( |
| 237 | () => this.client.custom.sync(body, requestOptions), |
| 238 | requestOptions?.signal |
| 239 | ); |
| 240 | return transformCustomToolkitSyncResponse(result); |
| 241 | } |
| 242 | |
| 243 | /** |
| 244 | * Deletes a custom toolkit owned by the project, with its tools, auth |
| 245 | * configs and connected accounts. The credentials behind those connected |
| 246 | * accounts are revoked in background jobs (`revokeJobIds`). |
| 247 | * |
| 248 | * Composio-managed toolkits cannot be deleted; the API answers 403. |
| 249 | * |
| 250 | * @param {string} slug - The custom toolkit slug (`CUSTOM_...`) |
| 251 | * @returns {Promise<CustomToolkitDeleteResponse>} What was deleted |
| 252 | * |
| 253 | * @example |
| 254 | * ```typescript |
| 255 | * const result = await composio.customToolkits.delete('CUSTOM_MY_TOOLKIT'); |
| 256 | * console.log(result.connectedAccountsDeleted); |
| 257 | * ``` |
| 258 | */ |
| 259 | async delete( |
| 260 | slug: string, |
| 261 | requestOptions?: ComposioRequestOptions |
| 262 | ): Promise<CustomToolkitDeleteResponse> { |
| 263 | const result = await withCancellation( |
| 264 | () => this.client.custom.deleteToolkit(slug, {}, requestOptions), |
| 265 | requestOptions?.signal |
| 266 | ); |
| 267 | return transformCustomToolkitDeleteResponse(result); |
| 268 | } |
| 269 | } |