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

next
ts 391 lines 14.8 KB
Raw
1 import { Context, Data, Duration, Effect, Layer, Option, Schema, Stream } from 'effect';
2 import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from 'effect/http';
3 import { ensure } from './runtime';
4
5 export const SDK_RELEASE_REPOSITORY = 'ComposioHQ/composio';
6 export const REPOSITORY_PATH = `/repos/${SDK_RELEASE_REPOSITORY}`;
7 export const runUrl = (id: string | number) =>
8 `https://github.com/${SDK_RELEASE_REPOSITORY}/actions/runs/${id}`;
9 const PAGE_SIZE = 100;
10 /** The REST API version every release request pins. */
11 const GITHUB_API_VERSION = '2026-03-10';
12 /** Bounded so large release diffs stay under GitHub's secondary rate limit. */
13 export const CONTENT_CONCURRENCY = 8;
14
15 export const RunId = Schema.String.check(Schema.isPattern(/^[1-9][0-9]*$/));
16 export const Sha = Schema.String.check(Schema.isPattern(/^[a-f0-9]{40}$/));
17 export const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
18 export const PositiveIntFromString = Schema.NumberFromString.check(
19 Schema.isInt(),
20 Schema.isGreaterThan(0)
21 );
22 export const TagRef = Schema.Struct({ object: Schema.Struct({ type: Schema.String, sha: Sha }) });
23 export const CreatedSha = Schema.Struct({ sha: Sha });
24 const Login = Schema.String.check(Schema.isPattern(/^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,38})$/));
25
26 export const ReleaseRun = Schema.Struct({
27 id: PositiveInt,
28 path: Schema.String,
29 head_sha: Schema.optionalKey(Sha),
30 event: Schema.optionalKey(Schema.String),
31 repository: Schema.Struct({ full_name: Schema.String }),
32 conclusion: Schema.NullOr(Schema.String),
33 html_url: Schema.String.check(Schema.isPattern(/^https:\/\//)),
34 });
35 export type ReleaseRun = typeof ReleaseRun.Type;
36
37 const ReleaseJob = Schema.Struct({
38 name: Schema.String,
39 status: Schema.optionalKey(Schema.String),
40 conclusion: Schema.optionalKey(Schema.NullOr(Schema.String)),
41 started_at: Schema.optionalKey(Schema.NullOr(Schema.String)),
42 completed_at: Schema.optionalKey(Schema.NullOr(Schema.String)),
43 steps: Schema.Array(
44 Schema.Struct({
45 name: Schema.String,
46 conclusion: Schema.NullOr(Schema.String),
47 started_at: Schema.optionalKey(Schema.NullOr(Schema.String)),
48 completed_at: Schema.optionalKey(Schema.NullOr(Schema.String)),
49 })
50 ).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
51 });
52
53 const JobsPage = Schema.Struct({ jobs: Schema.Array(ReleaseJob) });
54
55 export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
56
57 /** GitHub refused or failed a request; `message` carries GitHub's own reason and request ID. */
58 export class GitHubApiError extends Data.TaggedError('GitHubApiError')<{
59 readonly status: number;
60 readonly method: HttpMethod;
61 readonly path: string;
62 readonly message: string;
63 }> {}
64
65 /**
66 * GitHub answered, but not in the shape the release workflow reads. Retrying cannot help: the
67 * schemas need updating for the API version GitHub now serves.
68 */
69 export class GitHubContractError extends Data.TaggedError('GitHubContractError')<{
70 readonly method: HttpMethod;
71 readonly path: string;
72 readonly message: string;
73 }> {}
74
75 const decodeBody = <S extends Schema.Top>(
76 schema: S,
77 text: string,
78 method: HttpMethod,
79 path: string
80 ) =>
81 (text === ''
82 ? Schema.decodeUnknownEffect(schema)(undefined)
83 : Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(text)
84 ).pipe(
85 Effect.mapError(
86 error =>
87 new GitHubContractError({
88 method,
89 path,
90 message: `GitHub ${method} ${path} returned a response the release workflow cannot read under API version ${GITHUB_API_VERSION}: ${error.message}`,
91 })
92 )
93 );
94
95 /** How long one request may take, and how often and how long a failed one is retried. */
96 export interface RetryPolicy {
97 /** Attempts per request, the first one included. */
98 readonly attempts: number;
99 /** The first backoff; each later one doubles it. */
100 readonly baseDelayMs: number;
101 /** The longest single wait, including one GitHub asks for; a longer request gives up instead. */
102 readonly maxDelayMs: number;
103 /** Per-attempt timeout. */
104 readonly timeout: Duration.Input;
105 }
106
107 const DEFAULT_RETRY: RetryPolicy = {
108 attempts: 5,
109 baseDelayMs: 1_000,
110 maxDelayMs: 60_000,
111 timeout: '30 seconds',
112 };
113
114 const ErrorBody = Schema.Struct({
115 message: Schema.optionalKey(Schema.String),
116 errors: Schema.optionalKey(
117 Schema.Array(
118 Schema.Struct({
119 message: Schema.optionalKey(Schema.String),
120 code: Schema.optionalKey(Schema.String),
121 })
122 )
123 ),
124 });
125
126 /** GitHub's own explanation from an error body, such as "Validation Failed (already_exists)". */
127 const githubReason = (text: string) => {
128 const parsed = Schema.decodeUnknownOption(Schema.fromJsonString(ErrorBody))(text);
129 if (Option.isNone(parsed)) return text.trim().slice(0, 300);
130 const details = (parsed.value.errors ?? []).flatMap(error => error.message ?? error.code ?? []);
131 return [parsed.value.message, details.length ? `(${details.join('; ')})` : '']
132 .filter(Boolean)
133 .join(' ');
134 };
135
136 const failure = (
137 method: HttpMethod,
138 path: string,
139 response: HttpClientResponse.HttpClientResponse,
140 text: string
141 ) => {
142 const reason = githubReason(text);
143 return new GitHubApiError({
144 status: response.status,
145 method,
146 path,
147 message: `GitHub ${method} ${path} failed (${response.status})${reason ? `: ${reason}` : ''} [request ${response.headers['x-github-request-id'] ?? 'unknown'}, API ${GITHUB_API_VERSION}]`,
148 });
149 };
150
151 /**
152 * A rate limit, which GitHub did not process. Secondary limits answer 403 or 429 with
153 * `retry-after`, an exhausted primary limit `x-ratelimit-remaining: 0`.
154 */
155 const isRateLimited = (response: HttpClientResponse.HttpClientResponse, text: string) =>
156 response.status === 429 ||
157 (response.status === 403 &&
158 (response.headers['retry-after'] !== undefined ||
159 response.headers['x-ratelimit-remaining'] === '0' ||
160 /rate limit/i.test(text)));
161
162 /** The wait GitHub asked for, from `retry-after` or the primary limit's reset time. */
163 const requestedDelayMs = (response: HttpClientResponse.HttpClientResponse, now: number) => {
164 const retryAfter = Number(response.headers['retry-after']);
165 if (Number.isFinite(retryAfter) && retryAfter >= 0) return retryAfter * 1_000;
166 const reset = Number(response.headers['x-ratelimit-reset']);
167 if (response.headers['x-ratelimit-remaining'] === '0' && Number.isFinite(reset))
168 return Math.max(0, reset * 1_000 - now);
169 return undefined;
170 };
171
172 /** A response and its whole body, read within the same attempt timeout. */
173 interface Answer {
174 readonly response: HttpClientResponse.HttpClientResponse;
175 readonly text: string;
176 }
177
178 type Attempt =
179 | ({ readonly _tag: 'Done' } & Answer)
180 | { readonly _tag: 'Retry'; readonly error: GitHubApiError; readonly delayMs?: number };
181
182 const makeGitHub = (token: string, policy: RetryPolicy) =>
183 Effect.gen(function* () {
184 const client = yield* HttpClient.HttpClient;
185 const sendOnce = (
186 method: HttpMethod,
187 path: string,
188 body: unknown,
189 redirect: RequestRedirect,
190 accept: string
191 ) =>
192 Effect.gen(function* () {
193 const base = HttpClientRequest.make(method)(`https://api.github.com${path}`, {
194 headers: {
195 accept,
196 authorization: `Bearer ${token}`,
197 'x-github-api-version': GITHUB_API_VERSION,
198 },
199 });
200 const response = yield* client.execute(
201 body === undefined ? base : HttpClientRequest.bodyJsonUnsafe(base, body)
202 );
203 // The body is read here, so a response that stalls after its headers also times out.
204 return { response, text: yield* response.text } satisfies Answer;
205 }).pipe(
206 Effect.provideService(FetchHttpClient.RequestInit, { redirect }),
207 Effect.timeout(policy.timeout)
208 );
209 /**
210 * One attempt, classified. Rate limits are retried for every method. Server errors and
211 * timeouts are retried only for GET: GitHub sometimes applies a write before answering 502,
212 * and repeating it would duplicate an issue or comment, or fail on a ref that now exists.
213 */
214 const attempt = (
215 method: HttpMethod,
216 path: string,
217 body: unknown,
218 redirect: RequestRedirect,
219 accept: string
220 ) =>
221 sendOnce(method, path, body, redirect, accept).pipe(
222 Effect.matchEffect({
223 onFailure: (cause): Effect.Effect<Attempt, GitHubApiError> => {
224 const error = new GitHubApiError({
225 status: 0,
226 method,
227 path,
228 message: `GitHub ${method} ${path} did not answer: ${cause.message}`,
229 });
230 return method === 'GET' ? Effect.succeed({ _tag: 'Retry', error }) : Effect.fail(error);
231 },
232 onSuccess: ({ response, text }) =>
233 Effect.gen(function* () {
234 const retryable =
235 response.status === 429 ||
236 response.status === 403 ||
237 (response.status >= 500 && method === 'GET');
238 if (!retryable) return { _tag: 'Done', response, text } satisfies Attempt;
239 if (response.status === 403 && !isRateLimited(response, text))
240 return yield* failure(method, path, response, text);
241 return {
242 _tag: 'Retry',
243 error: failure(method, path, response, text),
244 delayMs: requestedDelayMs(response, Date.now()),
245 } satisfies Attempt;
246 }),
247 })
248 );
249 const send = (
250 method: HttpMethod,
251 path: string,
252 body: unknown,
253 redirect: RequestRedirect,
254 accept = 'application/vnd.github+json'
255 ) =>
256 Effect.gen(function* () {
257 yield* ensure(path.startsWith('/') && !path.startsWith('//'), 'Expected a GitHub API path');
258 for (let tries = 1; ; tries++) {
259 const outcome = yield* attempt(method, path, body, redirect, accept);
260 if (outcome._tag === 'Done') return { response: outcome.response, text: outcome.text };
261 const delayMs = outcome.delayMs ?? policy.baseDelayMs * 2 ** (tries - 1);
262 if (tries >= policy.attempts || delayMs > policy.maxDelayMs)
263 return yield* new GitHubApiError({
264 ...outcome.error,
265 message: `${outcome.error.message}; gave up after ${tries} attempt${tries === 1 ? '' : 's'}`,
266 });
267 yield* Effect.sleep(delayMs);
268 }
269 });
270 const failResponse = (method: HttpMethod, path: string, { response, text }: Answer) =>
271 Effect.fail(failure(method, path, response, text));
272 return {
273 request: <S extends Schema.Top>(
274 method: HttpMethod,
275 path: string,
276 schema: S,
277 body?: unknown
278 ) =>
279 Effect.gen(function* () {
280 const answer = yield* send(method, path, body, 'error');
281 if (answer.response.status < 200 || answer.response.status >= 300)
282 return yield* failResponse(method, path, answer);
283 return yield* decodeBody(schema, answer.text, method, path);
284 }),
285 /** A file's raw contents, or `None` on 404. Raw media works for files over 1 MB. */
286 raw: (path: string) =>
287 Effect.gen(function* () {
288 const answer = yield* send('GET', path, undefined, 'error', 'application/vnd.github.raw');
289 if (answer.response.status === 404) return Option.none<string>();
290 if (answer.response.status < 200 || answer.response.status >= 300)
291 return yield* failResponse('GET', path, answer);
292 return Option.some(answer.text);
293 }),
294 /** Resolves an endpoint that answers with a 302 to short-lived storage, such as an artifact archive. */
295 redirectLocation: (path: string) =>
296 Effect.gen(function* () {
297 const answer = yield* send('GET', path, undefined, 'manual');
298 if (answer.response.status !== 302) return yield* failResponse('GET', path, answer);
299 return Option.fromNullishOr(answer.response.headers.location);
300 }),
301 };
302 });
303
304 /** The controller's GitHub App installation client. Only trusted controller entry points provide it. */
305 export class GitHub extends Context.Service<
306 GitHub,
307 Effect.Success<ReturnType<typeof makeGitHub>>
308 >()('sdk-release/GitHub') {
309 static readonly layer = (token: string, retry: Partial<RetryPolicy> = {}) =>
310 Layer.effect(GitHub, makeGitHub(token, { ...DEFAULT_RETRY, ...retry }));
311 }
312
313 export const request = <S extends Schema.Top>(
314 method: HttpMethod,
315 path: string,
316 schema: S,
317 body?: unknown
318 ) =>
319 Effect.gen(function* () {
320 const github = yield* GitHub;
321 return yield* github.request(method, path, schema, body);
322 });
323
324 /** Optional lookup: a 404 becomes `None`; every other failure still fails. */
325 export const requestOptional = <S extends Schema.Top>(path: string, schema: S) =>
326 request('GET', path, schema).pipe(
327 Effect.map(Option.some),
328 Effect.catchTag('GitHubApiError', error =>
329 error.status === 404 ? Effect.succeedNone : Effect.fail(error)
330 )
331 );
332
333 /** Streams a paginated list endpoint until GitHub returns a short page. */
334 export const paginate = <S extends Schema.Top, A>(
335 path: string,
336 page: S,
337 items: (body: S['Type']) => ReadonlyArray<A>
338 ) =>
339 Stream.paginate(1, (index: number) =>
340 request(
341 'GET',
342 `${path}${path.includes('?') ? '&' : '?'}per_page=${PAGE_SIZE}&page=${index}`,
343 page
344 ).pipe(
345 Effect.map(body => {
346 const found = items(body);
347 return [found, found.length < PAGE_SIZE ? Option.none() : Option.some(index + 1)] as const;
348 })
349 )
350 );
351
352 export const paginateArray = <S extends Schema.Top>(path: string, item: S) =>
353 paginate(path, Schema.Array(item), body => body);
354
355 export const requireActiveMember = (login: string) =>
356 Effect.gen(function* () {
357 const user = yield* Schema.decodeUnknownEffect(Login)(login);
358 const membership = yield* request(
359 'GET',
360 `/orgs/ComposioHQ/memberships/${encodeURIComponent(user)}`,
361 Schema.Struct({ state: Schema.Literals(['active', 'pending']) })
362 );
363 yield* ensure(membership.state === 'active', 'An active ComposioHQ membership is required');
364 });
365
366 export const commentIssue = (issueNumber: number, body: string) =>
367 Effect.gen(function* () {
368 const issue = yield* Schema.decodeUnknownEffect(PositiveInt)(issueNumber);
369 yield* request(
370 'POST',
371 `${REPOSITORY_PATH}/issues/${issue}/comments`,
372 Schema.Struct({ id: Schema.Number }),
373 { body }
374 );
375 });
376
377 /** A file's UTF-8 contents at `sha`, or `None` when it does not exist there. */
378 export const fileAt = (path: string, sha: string) =>
379 Effect.flatMap(GitHub, github => github.raw(`${REPOSITORY_PATH}/contents/${path}?ref=${sha}`));
380 export const fileAtOrNull = (path: string, sha: string) =>
381 Effect.map(fileAt(path, sha), Option.getOrNull);
382
383 /** A run's jobs across pages: from every attempt, or only from the latest one. */
384 export const jobs = (id: string, filter: 'all' | 'latest' = 'all') =>
385 Stream.runCollect(
386 paginate(
387 `${REPOSITORY_PATH}/actions/runs/${id}/jobs?filter=${filter}`,
388 JobsPage,
389 body => body.jobs
390 )
391 );