Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | ); |