{"id":51419669,"url":"https://github.com/cycleplatform/internal-api-client-typescript","last_synced_at":"2026-07-04T23:01:20.738Z","repository":{"id":365729159,"uuid":"1273303294","full_name":"cycleplatform/internal-api-client-typescript","owner":"cycleplatform","description":"Cycle internal API client for use in containers on the Cycle Platform","archived":false,"fork":false,"pushed_at":"2026-07-02T20:13:00.000Z","size":142,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T22:14:25.039Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cycleplatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-18T11:48:44.000Z","updated_at":"2026-07-02T20:13:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cycleplatform/internal-api-client-typescript","commit_stats":null,"previous_names":["cycleplatform/internal-api-client-typescript"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cycleplatform/internal-api-client-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Finternal-api-client-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Finternal-api-client-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Finternal-api-client-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Finternal-api-client-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cycleplatform","download_url":"https://codeload.github.com/cycleplatform/internal-api-client-typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Finternal-api-client-typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35138078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-04T23:01:19.976Z","updated_at":"2026-07-04T23:01:20.674Z","avatar_url":"https://github.com/cycleplatform.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cycle Internal API Client - NodeJS\n\nA Cycle API client for the internal API located within every container running on the Cycle platform.\n\nThis client communicates over the Unix socket mounted at `/var/run/cycle/api/api.sock` inside every Cycle container instance. It is intended to run inside a container on the Cycle platform and is not usable from a browser.\n\n_This is an auto-generated API client based on the [OpenAPI Spec for Cycle](https://github.com/cycleplatform/api-spec). Please do not open any PRs for the generated code under /src/generated. If you have any questions on what changes are made in the latest version, please refer to the spec above._\n\n## Basics\n\nThis client utilizes [openapi-typescript](https://github.com/drwpow/openapi-typescript) to generate the type definitions for our client. The client itself is a pre-built [openapi-fetch](https://github.com/drwpow/openapi-typescript/tree/main/packages/openapi-fetch) client for convenience.\n\nEvery request should be typesafe, and only endpoints described in the spec will be valid in Typescript as the first parameter to `GET`, `POST`, `PATCH`, or `DELETE`.\n\n## Usage\n\n### Installation\n\n```bash\nnpm i @cycleplatform/internal-api-client\n```\n\n### Making a Request\n\nThe internal API authenticates using the token provided to the instance through the `CYCLE_API_TOKEN` environment variable. Pass it to `getClient` along with an optional socket path.\n\n```ts\nimport { getClient } from \"@cycleplatform/internal-api-client\";\n\nconst client = getClient();\n\nconst resp = await client.GET(\"/v1/container/instances\", {\n    params: {\n        query: {\n            // ...\n        },\n    },\n});\n\nconsole.log(resp.data, resp.error);\n```\n\nBy default the client connects to the socket at `/var/run/cycle/api/api.sock`. You can override this with the `socketPath` option:\n\n```ts\nconst client = getClient({\n    token: process.env.CYCLE_API_TOKEN,\n    socketPath: \"/custom/path/api.sock\",\n});\n```\n\n### Streaming Notifications\n\nBeyond REST requests, the internal API exposes a **notification pipeline**: a one-way streaming WebSocket over the same Unix socket that pushes real-time notifications as things happen on the hub. Each message identifies a single event: its `topic`, the `object` it concerns, and a `context` of related resource IDs. Use the REST client to fetch fuller detail when a notification warrants it.\n\nIt authenticates with the `CYCLE_API_TOKEN` environment variable by default, just like `getClient`.\n\n```ts\nimport { NotificationSocket } from \"@cycleplatform/internal-api-client\";\n\nconst socket = new NotificationSocket();\n\nsocket.on(\"open\", () =\u003e console.log(\"OPEN\"));\nsocket.on(\"notification\", (n) =\u003e console.log(\"NOTIFICATION:\", n));\nsocket.on(\"error\", (err) =\u003e console.error(\"ERROR:\", err.message));\nsocket.on(\"close\", (code, reason) =\u003e console.log(\"CLOSE:\", code, reason));\n\nsocket.connect();\n```\n\nAttach your listeners _before_ calling `connect()`. `NotificationSocket` is a Node `EventEmitter`, and an emitted `error` with no listener attached will throw.\n\nA received notification looks like this:\n\n```json\n{\n    \"topic\": \"environment.deployments.reconfigured\",\n    \"object\": { \"id\": \"68518ade194b15be6bfd0a1e\" },\n    \"context\": {\n        \"label\": null,\n        \"hub_id\": \"5a14ddd8b6393d0001976f44\",\n        \"account_id\": null,\n        \"environments\": [\n            \"68518ade194b15be6bfd0a1e\",\n            \"6813cd199cb8434cb64067c9\"\n        ],\n        \"dns_zones\": null,\n        \"clusters\": [\"production\"],\n        \"containers\": null,\n        \"virtual_machines\": null\n    }\n}\n```\n\nCall `socket.close()` to disconnect and stop reconnecting. The `socket.connected` getter reports whether the underlying socket is currently open.\n\nIf you just want to connect with the defaults, `connectNotifications(options)` constructs and connects in a single call, returning the socket:\n\n```ts\nimport { connectNotifications } from \"@cycleplatform/internal-api-client\";\n\nconst socket = connectNotifications();\nsocket.on(\"notification\", (n) =\u003e console.log(n));\n```\n\n### Reading Environment Metadata\n\nCycle mounts a metadata file inside every instance describing its environment: the environment ID, deployment tags, private network, and active services. `getEnvironmentMetadata()` reads and parses that file for you.\n\nIt returns a `Result` (`{ data, error }`) so check `error` before using `data`:\n\n```ts\nimport { getEnvironmentMetadata } from \"@cycleplatform/internal-api-client\";\n\nconst { data, error } = await getEnvironmentMetadata();\nif (error) {\n    console.error(\"failed to read environment metadata:\", error.message);\n} else {\n    console.log(data.id, data.services);\n}\n```\n\nSee [Environment Metadata File](https://cycle.io/docs/platform/container-environment-variables#environment-metadata-file) for the full field reference.\n\n## Development\n\n### Cloning submodules\n\n`git submodule update --recursive --remote`\n\n### Building\n\nTo build a local copy of this client, run `npm run build:lib` to create a `./dist` folder with the necessary files.\n\n### Testing\n\n`npm run test:ts \u0026\u0026 npm run test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcycleplatform%2Finternal-api-client-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcycleplatform%2Finternal-api-client-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcycleplatform%2Finternal-api-client-typescript/lists"}