{"id":28424970,"url":"https://github.com/truefoundry/truefoundry-typescript-sdk","last_synced_at":"2026-01-30T20:09:15.353Z","repository":{"id":290376516,"uuid":"940095417","full_name":"truefoundry/truefoundry-typescript-sdk","owner":"truefoundry","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-10T13:53:05.000Z","size":2277,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-12-10T13:53:39.502Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/truefoundry-sdk","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/truefoundry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2025-02-27T15:55:53.000Z","updated_at":"2025-12-10T12:21:10.000Z","dependencies_parsed_at":"2025-06-18T19:23:28.549Z","dependency_job_id":"1e99f14e-8c21-4077-923c-9a40d93ad797","html_url":"https://github.com/truefoundry/truefoundry-typescript-sdk","commit_stats":null,"previous_names":["truefoundry/truefoundry-typescript-sdk"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/truefoundry/truefoundry-typescript-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truefoundry%2Ftruefoundry-typescript-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truefoundry%2Ftruefoundry-typescript-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truefoundry%2Ftruefoundry-typescript-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truefoundry%2Ftruefoundry-typescript-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/truefoundry","download_url":"https://codeload.github.com/truefoundry/truefoundry-typescript-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truefoundry%2Ftruefoundry-typescript-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28918235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T19:10:10.838Z","status":"ssl_error","status_checked_at":"2026-01-30T19:06:40.573Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2025-06-05T10:30:56.247Z","updated_at":"2026-01-30T20:09:15.347Z","avatar_url":"https://github.com/truefoundry.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Truefoundry TypeScript Library\n\n[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\u0026utm_medium=github\u0026utm_campaign=readme\u0026utm_source=https%3A%2F%2Fgithub.com%2Ftruefoundry%2Ftruefoundry-typescript-sdk)\n[![npm shield](https://img.shields.io/npm/v/truefoundry-sdk)](https://www.npmjs.com/package/truefoundry-sdk)\n\nThis library provides convenient access to the TrueFoundry API.\n\n\u003e [!tip]\n\u003e You can ask questions about this SDK using DeepWiki\n\u003e - Python: [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/truefoundry/truefoundry-python-sdk)\n\u003e - TypeScript: [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/truefoundry/truefoundry-typescript-sdk)\n\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Reference](#reference)\n- [Usage](#usage)\n- [Request and Response Types](#request-and-response-types)\n- [Exception Handling](#exception-handling)\n- [Pagination](#pagination)\n- [Advanced](#advanced)\n  - [Additional Headers](#additional-headers)\n  - [Additional Query String Parameters](#additional-query-string-parameters)\n  - [Retries](#retries)\n  - [Timeouts](#timeouts)\n  - [Aborting Requests](#aborting-requests)\n  - [Access Raw Response Data](#access-raw-response-data)\n  - [Logging](#logging)\n  - [Runtime Compatibility](#runtime-compatibility)\n- [Contributing](#contributing)\n\n## Installation\n\n```sh\nnpm i -s truefoundry-sdk\n```\n\n## Reference\n\nA full reference for this library is available [here](https://github.com/truefoundry/truefoundry-typescript-sdk/blob/HEAD/./reference.md).\n\n## Usage\n\nInstantiate and use the client with the following:\n\n```typescript\nimport { TrueFoundryClient } from \"truefoundry-sdk\";\n\nconst client = new TrueFoundryClient({ environment: \"YOUR_BASE_URL\", apiKey: \"YOUR_API_KEY\" });\nconst pageableResponse = await client.applications.list({\n    limit: 10,\n    offset: 0,\n    applicationId: \"applicationId\",\n    workspaceId: \"workspaceId\",\n    applicationName: \"applicationName\",\n    fqn: \"fqn\",\n    workspaceFqn: \"workspaceFqn\",\n    applicationType: \"applicationType\",\n    nameSearchQuery: \"nameSearchQuery\",\n    environmentId: \"environmentId\",\n    clusterId: \"clusterId\",\n    applicationSetId: \"applicationSetId\",\n    paused: true,\n    deviceTypeFilter: \"cpu\",\n    lastDeployedBySubjects: \"lastDeployedBySubjects\",\n    lifecycleStage: \"active\",\n    isRecommendationPresentAndVisible: true\n});\nfor await (const item of pageableResponse) {\n    console.log(item);\n}\n\n// Or you can manually iterate page-by-page\nlet page = await client.applications.list({\n    limit: 10,\n    offset: 0,\n    applicationId: \"applicationId\",\n    workspaceId: \"workspaceId\",\n    applicationName: \"applicationName\",\n    fqn: \"fqn\",\n    workspaceFqn: \"workspaceFqn\",\n    applicationType: \"applicationType\",\n    nameSearchQuery: \"nameSearchQuery\",\n    environmentId: \"environmentId\",\n    clusterId: \"clusterId\",\n    applicationSetId: \"applicationSetId\",\n    paused: true,\n    deviceTypeFilter: \"cpu\",\n    lastDeployedBySubjects: \"lastDeployedBySubjects\",\n    lifecycleStage: \"active\",\n    isRecommendationPresentAndVisible: true\n});\nwhile (page.hasNextPage()) {\n    page = page.getNextPage();\n}\n\n// You can also access the underlying response\nconst response = page.response;\n```\n\n## Request and Response Types\n\nThe SDK exports all request and response types as TypeScript interfaces. Simply import them with the\nfollowing namespace:\n\n```typescript\nimport { TrueFoundry } from \"truefoundry-sdk\";\n\nconst request: TrueFoundry.InternalGetIdFromFqnRequest = {\n    ...\n};\n```\n\n## Exception Handling\n\nWhen the API returns a non-success status code (4xx or 5xx response), a subclass of the following error\nwill be thrown.\n\n```typescript\nimport { TrueFoundryError } from \"truefoundry-sdk\";\n\ntry {\n    await client.applications.list(...);\n} catch (err) {\n    if (err instanceof TrueFoundryError) {\n        console.log(err.statusCode);\n        console.log(err.message);\n        console.log(err.body);\n        console.log(err.rawResponse);\n    }\n}\n```\n\n## Pagination\n\nList endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:\n\n```typescript\nimport { TrueFoundryClient } from \"truefoundry-sdk\";\n\nconst client = new TrueFoundryClient({ environment: \"YOUR_BASE_URL\", apiKey: \"YOUR_API_KEY\" });\nconst pageableResponse = await client.users.list({\n    limit: 10,\n    offset: 0,\n    query: \"query\",\n    showInvalidUsers: true,\n    includeVirtualAccounts: \"includeVirtualAccounts\"\n});\nfor await (const item of pageableResponse) {\n    console.log(item);\n}\n\n// Or you can manually iterate page-by-page\nlet page = await client.users.list({\n    limit: 10,\n    offset: 0,\n    query: \"query\",\n    showInvalidUsers: true,\n    includeVirtualAccounts: \"includeVirtualAccounts\"\n});\nwhile (page.hasNextPage()) {\n    page = page.getNextPage();\n}\n\n// You can also access the underlying response\nconst response = page.response;\n```\n\n## Advanced\n\n### Additional Headers\n\nIf you would like to send additional headers as part of the request, use the `headers` request option.\n\n```typescript\nimport { TrueFoundryClient } from \"truefoundry-sdk\";\n\nconst client = new TrueFoundryClient({\n    ...\n    headers: {\n        'X-Custom-Header': 'custom value'\n    }\n});\n\nconst response = await client.applications.list(..., {\n    headers: {\n        'X-Custom-Header': 'custom value'\n    }\n});\n```\n\n### Additional Query String Parameters\n\nIf you would like to send additional query string parameters as part of the request, use the `queryParams` request option.\n\n```typescript\nconst response = await client.applications.list(..., {\n    queryParams: {\n        'customQueryParamKey': 'custom query param value'\n    }\n});\n```\n\n### Retries\n\nThe SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long\nas the request is deemed retryable and the number of retry attempts has not grown larger than the configured\nretry limit (default: 2).\n\nA request is deemed retryable when any of the following HTTP status codes is returned:\n\n- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)\n- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)\n- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)\n\nUse the `maxRetries` request option to configure this behavior.\n\n```typescript\nconst response = await client.applications.list(..., {\n    maxRetries: 0 // override maxRetries at the request level\n});\n```\n\n### Timeouts\n\nThe SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.\n\n```typescript\nconst response = await client.applications.list(..., {\n    timeoutInSeconds: 30 // override timeout to 30s\n});\n```\n\n### Aborting Requests\n\nThe SDK allows users to abort requests at any point by passing in an abort signal.\n\n```typescript\nconst controller = new AbortController();\nconst response = await client.applications.list(..., {\n    abortSignal: controller.signal\n});\ncontroller.abort(); // aborts the request\n```\n\n### Access Raw Response Data\n\nThe SDK provides access to raw response data, including headers, through the `.withRawResponse()` method.\nThe `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property.\n\n```typescript\nconst { data, rawResponse } = await client.applications.list(...).withRawResponse();\n\nconsole.log(data);\nconsole.log(rawResponse.headers['X-My-Header']);\n```\n\n### Logging\n\nThe SDK supports logging. You can configure the logger by passing in a `logging` object to the client options.\n\n```typescript\nimport { TrueFoundryClient, logging } from \"truefoundry-sdk\";\n\nconst client = new TrueFoundryClient({\n    ...\n    logging: {\n        level: logging.LogLevel.Debug, // defaults to logging.LogLevel.Info\n        logger: new logging.ConsoleLogger(), // defaults to ConsoleLogger\n        silent: false, // defaults to true, set to false to enable logging\n    }\n});\n```\nThe `logging` object can have the following properties:\n- `level`: The log level to use. Defaults to `logging.LogLevel.Info`.\n- `logger`: The logger to use. Defaults to a `logging.ConsoleLogger`.\n- `silent`: Whether to silence the logger. Defaults to `true`.\n\nThe `level` property can be one of the following values:\n- `logging.LogLevel.Debug`\n- `logging.LogLevel.Info`\n- `logging.LogLevel.Warn`\n- `logging.LogLevel.Error`\n\nTo provide a custom logger, you can pass in an object that implements the `logging.ILogger` interface.\n\n\u003cdetails\u003e\n\u003csummary\u003eCustom logger examples\u003c/summary\u003e\n\nHere's an example using the popular `winston` logging library.\n```ts\nimport winston from 'winston';\n\nconst winstonLogger = winston.createLogger({...});\n\nconst logger: logging.ILogger = {\n    debug: (msg, ...args) =\u003e winstonLogger.debug(msg, ...args),\n    info: (msg, ...args) =\u003e winstonLogger.info(msg, ...args),\n    warn: (msg, ...args) =\u003e winstonLogger.warn(msg, ...args),\n    error: (msg, ...args) =\u003e winstonLogger.error(msg, ...args),\n};\n```\n\nHere's an example using the popular `pino` logging library.\n\n```ts\nimport pino from 'pino';\n\nconst pinoLogger = pino({...});\n\nconst logger: logging.ILogger = {\n  debug: (msg, ...args) =\u003e pinoLogger.debug(args, msg),\n  info: (msg, ...args) =\u003e pinoLogger.info(args, msg),\n  warn: (msg, ...args) =\u003e pinoLogger.warn(args, msg),\n  error: (msg, ...args) =\u003e pinoLogger.error(args, msg),\n};\n```\n\u003c/details\u003e\n\n\n### Runtime Compatibility\n\n\nThe SDK works in the following runtimes:\n\n\n\n- Node.js 18+\n- Vercel\n- Cloudflare Workers\n- Deno v1.25+\n- Bun 1.0+\n- React Native\n\n### Customizing Fetch Client\n\nThe SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an\nunsupported environment, this provides a way for you to break glass and ensure the SDK works.\n\n```typescript\nimport { TrueFoundryClient } from \"truefoundry-sdk\";\n\nconst client = new TrueFoundryClient({\n    ...\n    fetcher: // provide your implementation here\n});\n```\n\n## Contributing\n\nWhile we value open-source contributions to this SDK, this library is generated programmatically.\nAdditions made directly to this library would have to be moved over to our generation code,\notherwise they would be overwritten upon the next generated release. Feel free to open a PR as\na proof of concept, but know that we will not be able to merge it as-is. We suggest opening\nan issue first to discuss with us!\n\nOn the other hand, contributions to the README are always very welcome!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruefoundry%2Ftruefoundry-typescript-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftruefoundry%2Ftruefoundry-typescript-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruefoundry%2Ftruefoundry-typescript-sdk/lists"}