@devries-cameron20 / composio Mirror · read-only
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, 04:45 UTC

next
ts 527 lines 20.5 KB
Raw
1 import { Context, Effect, Layer, Option, Stream, Array, Order } from 'effect';
2 import * as Str from 'effect/String';
3 import type { Cause } from 'effect';
4 import { FetchHttpClient, HttpClient } from 'effect/http';
5 import {
6 // eslint-disable-next-line no-restricted-imports -- this module is the one place the client is built
7 make as makeComposioClient,
8 Auth,
9 type ComposioClientShape,
10 type ConfigurationError,
11 } from '@composio/client/effect';
12 // Types `client._internal`: the CLI-only operations the spec tags `x-internal`
13 // (login sessions, realtime credentials, logs, consumer projects).
14 import type {} from '@composio/client/effect/internal';
15 import { Toolkit, Toolkits, ToolkitDetailed } from 'src/models/toolkits';
16 import { ToolsAsEnums, Tools } from 'src/models/tools';
17 import {
18 groupByVersion,
19 type ToolkitVersionSpec,
20 type ToolkitVersionOverrides,
21 } from 'src/effects/toolkit-version-overrides';
22 import { Session, RetrievedSession } from 'src/models/session';
23 import { TriggerTypes, TriggerTypesAsEnums } from 'src/models/trigger-types';
24 import { cliClientIdentity } from './client-provenance';
25 import { sha256Hex } from 'src/utils/checksums';
26 import { getCurrentCwdSessionId } from 'src/analytics/dispatch';
27 import { ComposioUserContext, ComposioUserContextLive } from './user-context';
28 import { makeClientMetricsCollector, type ClientMetricsCollector } from './composio-client-metrics';
29 import { ComposioClientConfigurationError, type ClientError } from './composio-errors';
30 import { isClientConfigurationError } from 'src/utils/api-error-extraction';
31 import {
32 MAX_CONCURRENT_REQUESTS_PER_ENDPOINT,
33 decode,
34 idempotent,
35 validated,
36 } from './composio-request';
37 import { lookupOperations, resourceOperations } from './composio-resource-operations';
38 import { schemaLoaders } from '@composio/client/effect/schemas';
39 import {
40 InvalidToolkitsError,
41 invalidToolkitOn404,
42 validateToolkitVersionsImpl,
43 type InvalidToolkitVersionsError,
44 } from './toolkit-version-validation';
45
46 type NoSuchElementError = Cause.NoSuchElementError;
47
48 /**
49 * Request helpers
50 */
51
52 // Maximum items per page allowed by the server
53 const MAX_PAGE_SIZE = 1000;
54
55 /**
56 * Runs a paginated listing to exhaustion and returns every item. A page is
57 * requested only once the one before it arrived, so interrupting the listing
58 * sends no further request.
59 */
60 const collectAll = <A, E, E2>(
61 client: Effect.Effect<ComposioClientShape, E>,
62 list: (client: ComposioClientShape) => Stream.Stream<A, E2>
63 ): Effect.Effect<Array<A>, E | E2> =>
64 Effect.flatMap(client, resolved => Stream.runCollect(list(resolved)));
65
66 // Sort items by slug.
67 // TODO: make sure this happens on the server-side.
68 const sortBySlug = <T extends { readonly slug: string }>(
69 items: ReadonlyArray<T>
70 ): ReadonlyArray<T> =>
71 Array.sort(
72 items,
73 Order.mapInput(Order.String, (item: T) => item.slug)
74 );
75
76 /**
77 * Client singleton
78 */
79
80 const normalizeApiKey = (rawApiKey?: string): string | undefined =>
81 typeof rawApiKey === 'string' && rawApiKey.trim().length > 0 ? rawApiKey : undefined;
82
83 /**
84 * Which key a client sends: the user's (`userApiKey`, defaulting to the
85 * logged-in user's), or a project key in its place.
86 */
87 type ClientCredential =
88 | { readonly userApiKey?: string; readonly projectApiKey?: undefined }
89 | { readonly projectApiKey: string; readonly userApiKey?: undefined };
90
91 /**
92 * Whose requests a client sends. The org and project headers are only sent
93 * together, so a scope names both or neither.
94 */
95 export type ClientScope = ClientCredential &
96 (
97 | { readonly orgId: string; readonly projectId: string }
98 | { readonly orgId?: undefined; readonly projectId?: undefined }
99 );
100
101 /**
102 * Shape exposed by {@link ComposioClientSingleton}.
103 */
104 export interface ComposioClientSingletonShape {
105 /**
106 * The client for the user's key, with no org or project: the backend acts on
107 * the key's default project. A command that acts on a project it resolved
108 * (a developer project, the consumer project) asks `getFor` for that one.
109 */
110 readonly get: () => Effect.Effect<ComposioClientShape, ClientBuildError | NoSuchElementError>;
111 /**
112 * The client for an explicit scope. `userApiKey` defaults to the user's key;
113 * a `projectApiKey` is sent instead of any user key.
114 */
115 readonly getFor: (
116 params: ClientScope
117 ) => Effect.Effect<ComposioClientShape, ClientBuildError | NoSuchElementError>;
118 /**
119 * Returns a snapshot of the accumulated metrics (total bytes received and
120 * request count) across every client this singleton built.
121 */
122 readonly getMetrics: () => Effect.Effect<{
123 readonly byteSize: number;
124 readonly requests: number;
125 }>;
126 }
127
128 /**
129 * Why a client could not be built: the client's own `ConfigurationError`
130 * (a base URL it refuses, say) or a failure the CLI only knows as a thrown value.
131 */
132 export type ClientBuildError = ConfigurationError | ComposioClientConfigurationError;
133
134 // What each client built here addresses: its auth mode, a SHA-256 fingerprint
135 // of its credential (never the key itself), org, and project. `getFor` builds
136 // a new client on every call, so a memo over a client's reads keys on this
137 // rather than on the instance.
138 const clientScopeKeys = new WeakMap<ComposioClientShape, string>();
139 let nextUnscopedClient = 0;
140
141 /**
142 * A memo key for what `client` addresses. Two clients from
143 * {@link ComposioClientSingleton} with the same credential, org, and project
144 * share it; a client built anywhere else (a test double) gets one of its own.
145 */
146 export const clientScopeKey = (client: ComposioClientShape): string => {
147 let key = clientScopeKeys.get(client);
148 if (key === undefined) {
149 key = `instance:${nextUnscopedClient++}`;
150 clientScopeKeys.set(client, key);
151 }
152 return key;
153 };
154
155 /**
156 * Singleton service that lazily accesses `Config` only when needed, which is used to build and provide
157 * a Composio client instance from `@composio/client/effect`.
158 *
159 * Clients are built with `make`, which never consults the ambient process
160 * environment: every credential and the base URL come from the CLI's own
161 * configuration. Custom HTTP base URLs remain supported. A client
162 * authenticates with `Auth.user` and the user key, with `Auth.project` when a
163 * caller names a project key, and with `Auth.none()` before anyone has logged
164 * in; the org and project go in its `scope`. No credential or scope header is
165 * placed in `defaultHeaders`, which the client refuses while `auth` and
166 * `scope` own them.
167 *
168 * Every lookup builds a new client (`make` costs a few microseconds), so no
169 * credential is held anywhere but in the client a caller is using.
170 */
171 const makeComposioClientSingleton = (metrics: ClientMetricsCollector) =>
172 Effect.gen(function* () {
173 const ctx = yield* ComposioUserContext;
174 const httpClient = yield* HttpClient.HttpClient;
175
176 // Read from disk once per process, with the services captured here.
177 const sessionIdServices =
178 yield* Effect.context<Effect.Services<ReturnType<typeof getCurrentCwdSessionId>>>();
179 const currentCwdSessionId = yield* Effect.cached(
180 getCurrentCwdSessionId().pipe(Effect.provideContext(sessionIdServices))
181 );
182
183 // `ctx.data` is read per call: a login or logout changes the user key.
184 const getFor = (params?: ClientScope) =>
185 Effect.gen(function* () {
186 const cliSessionId = yield* currentCwdSessionId;
187 const userApiKey = normalizeApiKey(
188 params?.userApiKey ?? Option.getOrUndefined(ctx.data.apiKey)
189 );
190 const auth =
191 params?.projectApiKey !== undefined
192 ? Auth.project(params.projectApiKey)
193 : userApiKey !== undefined
194 ? Auth.user(userApiKey)
195 : Auth.none();
196 const orgId = params?.orgId;
197 const projectId = params?.projectId;
198 const credential = params?.projectApiKey ?? userApiKey;
199 const credentialFingerprint =
200 credential !== undefined
201 ? yield* Effect.promise(() => sha256Hex(new TextEncoder().encode(credential)))
202 : '';
203
204 const client = yield* Effect.try({
205 try: () =>
206 // A call that passes `decode: true` has its response validated
207 // against the client's schema for that operation.
208 makeComposioClient(
209 {
210 auth,
211 scope:
212 orgId !== undefined && projectId !== undefined
213 ? { organizationId: orgId, projectId }
214 : undefined,
215 baseURL: ctx.data.baseURL,
216 // Preserve support for explicitly configured HTTP backends.
217 allowInsecureHTTP: true,
218 // The identity headers come from here; the client refuses them
219 // in `defaultHeaders`.
220 identity: cliClientIdentity(),
221 defaultHeaders:
222 cliSessionId !== undefined ? { 'x-cli-session-id': cliSessionId } : undefined,
223 // Only a call that passes `idempotent` is retried.
224 maxRetries: 0,
225 schemas: schemaLoaders,
226 },
227 httpClient
228 ),
229 // The client's own error is kept as it is; anything else thrown is
230 // reported as the CLI's configuration error.
231 catch: (cause): ClientBuildError =>
232 isClientConfigurationError(cause)
233 ? cause
234 : new ComposioClientConfigurationError({
235 message: cause instanceof Error ? cause.message : String(cause),
236 cause,
237 }),
238 });
239 clientScopeKeys.set(
240 client,
241 `${auth.mode}\u0000${credentialFingerprint}\u0000${orgId ?? ''}\u0000${projectId ?? ''}`
242 );
243 return client;
244 });
245
246 return {
247 get: Effect.fn(function* () {
248 return yield* getFor();
249 }),
250 getFor: Effect.fn(function* (params: ClientScope) {
251 return yield* getFor(params);
252 }),
253 getMetrics: metrics.getMetrics,
254 } satisfies ComposioClientSingletonShape;
255 });
256
257 /**
258 * The org/project a project-scoped request is made for, as a command resolved it.
259 */
260 export interface ToolkitProjectScope {
261 readonly orgId: string;
262 readonly projectId: string;
263 }
264
265 export class ComposioClientSingleton extends Context.Service<
266 ComposioClientSingleton,
267 ComposioClientSingletonShape
268 >()('services/ComposioClientSingleton') {
269 // The singleton and its transport share one metrics collector, created
270 // when the layer is built. The transport is a fresh `FetchHttpClient.layer`
271 // rather than the memoized one an application may already have built
272 // (`InvocationLive` provides its own), because that one calls
273 // `globalThis.fetch` directly and counts nothing; this one is built over
274 // the counting `fetch`.
275 static readonly Default = Layer.unwrap(
276 Effect.sync(() => {
277 const metrics = makeClientMetricsCollector();
278 return Layer.effect(ComposioClientSingleton, makeComposioClientSingleton(metrics)).pipe(
279 Layer.provide(
280 Layer.fresh(FetchHttpClient.layer).pipe(
281 Layer.provide(Layer.succeed(FetchHttpClient.Fetch, metrics.fetch))
282 )
283 )
284 );
285 })
286 ).pipe(Layer.provide(ComposioUserContextLive));
287 }
288 /**
289 * Repositories
290 */
291
292 const makeComposioToolkitsRepository = Effect.gen(function* () {
293 const clientSingleton = yield* ComposioClientSingleton;
294 const client = clientSingleton.get();
295
296 const listToolkits = (managedBy?: 'project', scope?: ToolkitProjectScope) =>
297 collectAll(scope ? clientSingleton.getFor(scope) : client, c =>
298 c.toolkits.listStream({ limit: MAX_PAGE_SIZE, managed_by: managedBy }, idempotent)
299 ).pipe(Effect.flatMap(decode(Toolkits)), Effect.map(sortBySlug));
300
301 const getToolkitDetailed = (slug: string) =>
302 client.pipe(
303 Effect.flatMap(c => c.toolkits.retrieve(slug, undefined, idempotent)),
304 Effect.flatMap(decode(ToolkitDetailed))
305 );
306
307 // The retrieve endpoint omits `auth_schemes`; fill it so the result
308 // satisfies the catalog `Toolkit` contract.
309 const getToolkit = (slug: string): Effect.Effect<Toolkit, ClientError> =>
310 getToolkitDetailed(slug).pipe(
311 Effect.map(({ auth_config_details: _authConfigDetails, ...toolkit }) => ({
312 ...toolkit,
313 auth_schemes: [],
314 }))
315 );
316
317 const getToolkits = () => listToolkits();
318
319 /**
320 * Fetches the custom toolkits registered in the current project. They are
321 * project-scoped, so they are absent from the build-time catalog and from
322 * {@link getToolkits}, whose callers expect Composio-managed toolkits only.
323 * @param scope - The org/project the command resolved; without it, the
324 * backend picks the key's default project
325 */
326 const getProjectToolkits = (scope?: ToolkitProjectScope) => listToolkits('project', scope);
327
328 /**
329 * Fetches specific toolkits by their slugs.
330 * Makes parallel API calls to retrieve each toolkit.
331 * @param slugs - Array of toolkit slugs to fetch
332 */
333 const getToolkitsBySlugs = (slugs: ReadonlyArray<string>) =>
334 Effect.all(
335 slugs.map(slug => invalidToolkitOn404(slug, getToolkit(slug))),
336 { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
337 ).pipe(Effect.map(sortBySlug));
338
339 const listTools = (query: { toolkit_slug?: string; toolkit_versions: string }) =>
340 collectAll(client, c =>
341 c.tools.listStream({ ...query, limit: MAX_PAGE_SIZE }, idempotent)
342 ).pipe(Effect.flatMap(decode(Tools)));
343
344 return {
345 getToolkits,
346 getProjectToolkits,
347 getToolkitsBySlugs,
348 getMetrics: () => clientSingleton.getMetrics(),
349 /**
350 * Retrieve a list of all available tool enumeration values (tool slugs) for the project.
351 */
352 getToolsAsEnums: () =>
353 client.pipe(
354 Effect.flatMap(c => c.tools.retrieveEnum(idempotent)),
355 Effect.flatMap(decode(ToolsAsEnums))
356 ),
357 /**
358 * Fetches tools with optional toolkit filtering, always at the latest
359 * toolkit version. For per-toolkit versions use `getToolsByVersionSpecs`.
360 * @param toolkitSlugs - Optional array of toolkit slugs to filter by
361 */
362 getTools: (toolkitSlugs?: ReadonlyArray<string>) =>
363 listTools({
364 toolkit_slug: toolkitSlugs && toolkitSlugs.length > 0 ? toolkitSlugs.join(',') : undefined,
365 toolkit_versions: 'latest',
366 }).pipe(Effect.map(sortBySlug)),
367 /**
368 * Fetches tools with per-toolkit version support.
369 * Groups toolkits by version and makes separate API calls for each group.
370 * @param specs - Array of { toolkitSlug, toolkitVersion } specifications
371 */
372 getToolsByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
373 Effect.all(
374 [...groupByVersion(specs).entries()].map(([version, slugs]) =>
375 listTools({ toolkit_slug: slugs.join(','), toolkit_versions: version })
376 ),
377 { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
378 ).pipe(Effect.map(groups => sortBySlug(groups.flat()))),
379 /**
380 * Retrieves a list of all available trigger type enum values that can be used across the API.
381 */
382 getTriggerTypesAsEnums: () =>
383 client.pipe(
384 Effect.flatMap(c => c.triggersTypes.retrieveEnum(idempotent)),
385 Effect.flatMap(decode(TriggerTypesAsEnums))
386 ),
387 /**
388 * Fetches trigger types with optional toolkit filtering.
389 * When toolkitSlugs is provided, fetches all matching trigger types.
390 * @param toolkitSlugs - Optional array of toolkit slugs to filter by
391 */
392 getTriggerTypes: (toolkitSlugs?: ReadonlyArray<string>) =>
393 collectAll(client, c =>
394 c.triggersTypes.listStream(
395 {
396 limit: MAX_PAGE_SIZE,
397 toolkit_slugs: toolkitSlugs ? [...toolkitSlugs] : undefined,
398 },
399 idempotent
400 )
401 ).pipe(Effect.flatMap(decode(TriggerTypes)), Effect.map(sortBySlug)),
402 /**
403 * Validates that the given toolkit slugs are valid by comparing them against the list
404 * of available toolkits. Returns the list of valid toolkit slugs (normalized to lowercase).
405 * @param toolkitSlugs - Array of toolkit slugs to validate (case-insensitive)
406 */
407 validateToolkits: (
408 toolkitSlugs: ReadonlyArray<string>
409 ): Effect.Effect<ReadonlyArray<string>, InvalidToolkitsError | ClientError> =>
410 Effect.gen(function* () {
411 // Normalize input slugs to lowercase for comparison
412 const normalizedInputSlugs = toolkitSlugs.map(slug => Str.toLowerCase(slug));
413
414 // Fetch all available toolkits
415 const allToolkits = yield* getToolkits();
416 const availableSlugs = allToolkits.map(toolkit => Str.toLowerCase(toolkit.slug));
417
418 // Find invalid slugs
419 const invalidSlugs = normalizedInputSlugs.filter(slug => !availableSlugs.includes(slug));
420
421 if (invalidSlugs.length > 0) {
422 return yield* Effect.fail(
423 new InvalidToolkitsError({
424 invalidToolkits: invalidSlugs,
425 availableToolkits: availableSlugs,
426 })
427 );
428 }
429
430 return normalizedInputSlugs;
431 }),
432 /**
433 * Filters the given list of toolkits to only include those with the specified slugs.
434 * @param toolkits - Array of toolkits to filter
435 * @param toolkitSlugs - Array of toolkit slugs to filter by (case-insensitive)
436 */
437 filterToolkitsBySlugs: (
438 toolkits: ReadonlyArray<Toolkit>,
439 toolkitSlugs: ReadonlyArray<string>
440 ): ReadonlyArray<Toolkit> => {
441 const normalizedSlugs = new Set(toolkitSlugs.map(slug => Str.toLowerCase(slug)));
442 return toolkits.filter(toolkit => normalizedSlugs.has(Str.toLowerCase(toolkit.slug)));
443 },
444 /**
445 * Validates that the requested toolkit versions exist in the API's available_versions.
446 * Makes parallel API calls to fetch toolkit metadata for validation.
447 *
448 * @param overrides - Map of toolkit slug to requested version
449 * @param relevantToolkits - Optional array of toolkit slugs to validate (if --toolkits filter is used)
450 * @returns Effect that succeeds with the validated overrides and warnings, or fails with InvalidToolkitVersionsError
451 */
452 validateToolkitVersions: (
453 overrides: ToolkitVersionOverrides,
454 relevantToolkits?: ReadonlyArray<string>
455 ): Effect.Effect<
456 {
457 validatedOverrides: ToolkitVersionOverrides;
458 warnings: ReadonlyArray<string>;
459 },
460 InvalidToolkitVersionsError | InvalidToolkitsError | ClientError
461 > => validateToolkitVersionsImpl(getToolkit, overrides, relevantToolkits),
462 /**
463 * Retrieves detailed toolkit info including auth_config_details.
464 * @param slug - Toolkit slug
465 */
466 getToolkitDetailed,
467 ...lookupOperations(client),
468 ...resourceOperations(scope =>
469 clientSingleton.getFor({ orgId: scope.orgId, projectId: scope.projectId })
470 ),
471 };
472 });
473
474 export type ComposioToolkitsRepositoryShape = Effect.Success<typeof makeComposioToolkitsRepository>;
475
476 export class ComposioToolkitsRepository extends Context.Service<
477 ComposioToolkitsRepository,
478 ComposioToolkitsRepositoryShape
479 >()('services/ComposioToolkitsRepository') {
480 static readonly Default = Layer.effect(
481 ComposioToolkitsRepository,
482 makeComposioToolkitsRepository
483 ).pipe(Layer.provide(ComposioClientSingleton.Default));
484 }
485
486 const makeComposioSessionRepository = Effect.gen(function* () {
487 const clientSingleton = yield* ComposioClientSingleton;
488 const client = clientSingleton.get();
489
490 return {
491 /**
492 * Generates a new CLI session with a random 6-character code.
493 * @param params.scope - 'user' for login, 'project' for init (future)
494 */
495 createSession: (params?: { scope?: 'user' | 'project' }) =>
496 client.pipe(
497 Effect.flatMap(c => c._internal.cli.createSession({ scope: params?.scope ?? 'user' })),
498 Effect.flatMap(decode(Session))
499 ),
500 /**
501 * Retrieves the current state of a CLI session using either the session ID (UUID) or the 6-character code.
502 */
503 getSession: (session: { id: string }) =>
504 client.pipe(
505 Effect.flatMap(c => c._internal.cli.getSession({ id: session.id }, idempotent)),
506 Effect.flatMap(decode(RetrievedSession))
507 ),
508 getRealtimeCredentials: () =>
509 Effect.flatMap(client, c =>
510 c._internal.cli.realtime.credentials({ ...idempotent, ...validated })
511 ),
512 authRealtimeChannel: (params: { channel_name: string; socket_id: string }) =>
513 Effect.flatMap(client, c => c._internal.cli.realtime.auth(params, idempotent)),
514 };
515 });
516
517 export type ComposioSessionRepositoryShape = Effect.Success<typeof makeComposioSessionRepository>;
518
519 export class ComposioSessionRepository extends Context.Service<
520 ComposioSessionRepository,
521 ComposioSessionRepositoryShape
522 >()('services/ComposioSessionRepository') {
523 static readonly Default = Layer.effect(
524 ComposioSessionRepository,
525 makeComposioSessionRepository
526 ).pipe(Layer.provide(ComposioClientSingleton.Default));
527 }