{"id":15046005,"url":"https://github.com/denoland/subhosting-js","last_synced_at":"2025-10-19T21:32:25.744Z","repository":{"id":222378840,"uuid":"757133628","full_name":"denoland/subhosting-js","owner":"denoland","description":"The JavaScript client library for Subhosting API.","archived":false,"fork":false,"pushed_at":"2024-05-06T11:33:32.000Z","size":181,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-01-30T06:11:14.712Z","etag":null,"topics":["deno","javascript","node","npm","subhosting","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/subhosting","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denoland.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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}},"created_at":"2024-02-13T21:41:50.000Z","updated_at":"2024-12-20T16:06:12.000Z","dependencies_parsed_at":"2024-04-17T19:09:50.266Z","dependency_job_id":null,"html_url":"https://github.com/denoland/subhosting-js","commit_stats":null,"previous_names":["denoland/subhosting-js"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fsubhosting-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fsubhosting-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fsubhosting-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fsubhosting-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denoland","download_url":"https://codeload.github.com/denoland/subhosting-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237221176,"owners_count":19274447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["deno","javascript","node","npm","subhosting","typescript"],"created_at":"2024-09-24T20:52:34.767Z","updated_at":"2025-10-19T21:32:25.373Z","avatar_url":"https://github.com/denoland.png","language":"TypeScript","readme":"# Deno Deploy Subhosting REST API client for JavaScript\n\n[![NPM version](https://img.shields.io/npm/v/subhosting.svg)](https://npmjs.org/package/subhosting)\n\nThis library provides convenient access to the\n[Deno Deploy Subhosting](https://deno.com/subhosting) REST API, which allows you\nto programmatically deploy untrusted, third-party code into the cloud, from\nserver-side JavaScript/TypeScript.\n\nThe REST API documentation can be found\n[on apidocs.deno.com](https://apidocs.deno.com/). The full API of this library\ncan be found in [api.md](api.md).\n\nTo learn more about Subhosting,\n[check out our documentation](https://docs.deno.com/subhosting/manual).\n\n## Installation for Node\n\nNode requires dependencies to be preinstalled before executing your scripts.\nInstall the Subhosting client library from npm using one of the following\ncommands:\n\n```sh\nnpm i --save subhosting\n# or\npnpm add subhosting\n# or\nyarn add subhosting\n```\n\n## Usage\n\nBefore you begin, you'll need to have a Deno Deploy access token and an ID for\nthe Deno Deploy organization you're using for Subhosting.\n\n- You can find or create a personal access token\n  [in the dashboard here](https://dash.deno.com/account#access-tokens)\n- Your org ID can be found near the top of the page on your Deno Deploy\n  dashboard [as described here](https://docs.deno.com/subhosting/api)\n\nThe code examples below assume your access token is stored in a\n`DEPLOY_ACCESS_TOKEN` environment variable and your Deno Deploy org ID is stored\nin a `DEPLOY_ORG_ID` environment variable.\n\n### Deno\n\nThe following example shows client initialization and usage in Deno:\n\n```js\nimport Subhosting from \"npm:subhosting\";\n\nconst subhosting = new Subhosting({\n  bearerToken: Deno.env.get(\"DEPLOY_ACCESS_TOKEN\"),\n});\n\nconst organization = await subhosting.organizations.get(\n  Deno.env.get(\"DEPLOY_ORG_ID\"),\n);\n\nconsole.log(organization);\n```\n\n### Node\n\nThe following example shows client initialization and usage in Node:\n\n\u003c!-- prettier-ignore --\u003e\n\n```js\nimport Subhosting from \"subhosting\";\n\nconst subhosting = new Subhosting({\n  bearerToken: process.env[\"DEPLOY_ACCESS_TOKEN\"], // This is the default and can be omitted\n});\n\nasync function main() {\n  const organization = await subhosting.organizations.get(\"DEPLOY_ORG_ID\");\n\n  console.log(organization.id);\n}\n\nmain();\n```\n\n### Request \u0026 Response types\n\nThis library includes TypeScript definitions for all request params and response\nfields. You may import and use them like so:\n\n\u003c!-- prettier-ignore --\u003e\n\n```ts\nimport Subhosting from \"subhosting\";\n\nconst subhosting = new Subhosting({\n  bearerToken: process.env[\"DEPLOY_ACCESS_TOKEN\"], // This is the default and can be omitted\n});\n\nasync function main() {\n  const organization: Subhosting.Organization = await subhosting.organizations\n    .get(\"DEPLOY_ORG_ID\");\n}\n\nmain();\n```\n\nDocumentation for each method, request param, and response field are available\nin docstrings and will appear on hover in most modern editors.\n\n## Handling errors\n\nWhen the library is unable to connect to the API, or if the API returns a\nnon-success status code (i.e., 4xx or 5xx response), a subclass of `APIError`\nwill be thrown:\n\n\u003c!-- prettier-ignore --\u003e\n\n```ts\nasync function main() {\n  const organization = await subhosting.organizations.get(\"DEPLOY_ORG_ID\")\n    .catch((err) =\u003e {\n      if (err instanceof Subhosting.APIError) {\n        console.log(err.status); // 400\n        console.log(err.name); // BadRequestError\n        console.log(err.headers); // {server: 'nginx', ...}\n      } else {\n        throw err;\n      }\n    });\n}\n\nmain();\n```\n\nError codes are as followed:\n\n| Status Code | Error Type                 |\n| ----------- | -------------------------- |\n| 400         | `BadRequestError`          |\n| 401         | `AuthenticationError`      |\n| 403         | `PermissionDeniedError`    |\n| 404         | `NotFoundError`            |\n| 422         | `UnprocessableEntityError` |\n| 429         | `RateLimitError`           |\n| \u003e=500       | `InternalServerError`      |\n| N/A         | `APIConnectionError`       |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short\nexponential backoff. Connection errors (for example, due to a network\nconnectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and\n\u003e=500 Internal errors will all be retried by default.\n\nYou can use the `maxRetries` option to configure or disable this:\n\n\u003c!-- prettier-ignore --\u003e\n\n```js\n// Configure the default for all requests:\nconst subhosting = new Subhosting({\n  maxRetries: 0, // default is 2\n});\n\n// Or, configure per-request:\nawait subhosting.organizations.get(\"DEPLOY_ORG_ID\", {\n  maxRetries: 5,\n});\n```\n\n### Timeouts\n\nRequests time out after 1 minute by default. You can configure this with a\n`timeout` option:\n\n\u003c!-- prettier-ignore --\u003e\n\n```ts\n// Configure the default for all requests:\nconst subhosting = new Subhosting({\n  timeout: 20 * 1000, // 20 seconds (default is 1 minute)\n});\n\n// Override per-request:\nawait subhosting.organizations.get(\"DEPLOY_ORG_ID\", {\n  timeout: 5 * 1000,\n});\n```\n\nOn timeout, an `APIConnectionTimeoutError` is thrown.\n\nNote that requests which time out will be [retried twice by default](#retries).\n\n## Advanced Usage\n\n### Accessing raw Response data (e.g., headers)\n\nThe \"raw\" `Response` returned by `fetch()` can be accessed through the\n`.asResponse()` method on the `APIPromise` type that all methods return.\n\nYou can also use the `.withResponse()` method to get the raw `Response` along\nwith the parsed data.\n\n\u003c!-- prettier-ignore --\u003e\n\n```ts\nconst subhosting = new Subhosting();\n\nconst response = await subhosting.organizations.get(\"DEPLOY_ORG_ID\")\n  .asResponse();\nconsole.log(response.headers.get(\"X-My-Header\"));\nconsole.log(response.statusText); // access the underlying Response object\n\nconst { data: organization, response: raw } = await subhosting.organizations\n  .get(\"DEPLOY_ORG_ID\")\n  .withResponse();\nconsole.log(raw.headers.get(\"X-My-Header\"));\nconsole.log(organization.id);\n```\n\n## Customizing the fetch client\n\nBy default, this library uses `node-fetch` in Node, and expects a global `fetch`\nfunction in other environments.\n\nIf you would prefer to use a global, web-standards-compliant `fetch` function\neven in a Node environment, (for example, if you are running Node with\n`--experimental-fetch` or using NextJS which polyfills with `undici`), add the\nfollowing import before your first import `from \"Subhosting\"`:\n\n```ts\n// Tell TypeScript and the package to use the global web fetch instead of node-fetch.\n// Note, despite the name, this does not add any polyfills, but expects them to be provided if needed.\nimport \"subhosting/shims/web\";\nimport Subhosting from \"subhosting\";\n```\n\nTo do the inverse, add `import \"subhosting/shims/node\"` (which does import\npolyfills). This can also be useful if you are getting the wrong TypeScript\ntypes for `Response` - more details\n[here](https://github.com/denoland/subhosting-js/tree/main/src/_shims#readme).\n\nYou may also provide a custom `fetch` function when instantiating the client,\nwhich can be used to inspect or alter the `Request` or `Response` before/after\neach request:\n\n```ts\nimport { fetch } from \"undici\"; // as one example\nimport Subhosting from \"subhosting\";\n\nconst client = new Subhosting({\n  fetch: async (url: RequestInfo, init?: RequestInfo): Promise\u003cResponse\u003e =\u003e {\n    console.log(\"About to make a request\", url, init);\n    const response = await fetch(url, init);\n    console.log(\"Got response\", response);\n    return response;\n  },\n});\n```\n\nNote that if given a `DEBUG=true` environment variable, this library will log\nall requests and responses automatically. This is intended for debugging\npurposes only and may change in the future without notice.\n\n## Configuring an HTTP(S) Agent (e.g., for proxies)\n\nBy default, this library uses a stable agent for all http/https requests to\nreuse TCP connections, eliminating many TCP \u0026 TLS handshakes and shaving around\n100ms off most requests.\n\nIf you would like to disable or customize this behavior, for example to use the\nAPI behind a proxy, you can pass an `httpAgent` which is used for all requests\n(be they http or https), for example:\n\n\u003c!-- prettier-ignore --\u003e\n\n```ts\nimport http from \"http\";\nimport HttpsProxyAgent from \"https-proxy-agent\";\n\n// Configure the default for all requests:\nconst subhosting = new Subhosting({\n  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),\n});\n\n// Override per-request:\nawait subhosting.organizations.get(\"DEPLOY_ORG_ID\", {\n  baseURL: \"http://localhost:8080/test-api\",\n  httpAgent: new http.Agent({ keepAlive: false }),\n});\n```\n\n## Semantic Versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html)\nconventions, though certain backwards-incompatible changes may be released as\nminor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. Changes to library internals which are technically public but not intended or\n   documented for external use. _(Please open a GitHub issue to let us know if\n   you are relying on such internals)_.\n3. Changes that we do not expect to impact the vast majority of users in\n   practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely\non a smooth upgrade experience.\n\nWe are keen for your feedback; please open an\n[issue](https://www.github.com/denoland/subhosting-js/issues) with questions,\nbugs, or suggestions.\n\n## Requirements\n\nTypeScript \u003e= 4.5 is supported.\n\nThe following runtimes are supported:\n\n- Node.js 18 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.\n- Deno v1.28.0 or higher, using `import Subhosting from \"npm:subhosting\"`.\n- Bun 1.0 or later.\n- Cloudflare Workers.\n- Vercel Edge Runtime.\n- Jest 28 or greater with the `\"node\"` environment (`\"jsdom\"` is not supported\n  at this time).\n- Nitro v2.6 or greater.\n\nNote that React Native is not supported at this time.\n\nIf you are interested in other runtime environments, please open or upvote an\nissue on GitHub.\n\n## Contributing\n\nThis library is auto-generated with\n[Stainless API](https://www.stainlessapi.com/) based on our\n[OpenAPI spec](https://apidocs.deno.com/). If you’re interested in contributing\nto the readme/documentation, feel free to submit a PR. However, since our\nOpenAPI spec is generated from our private Deno Deploy repository, if you’re\ninterested in contributing code, please provide feedback in the\n[issues](https://github.com/denoland/subhosting-js/issues) and we’ll review it.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoland%2Fsubhosting-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenoland%2Fsubhosting-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoland%2Fsubhosting-js/lists"}