SDKsJavaScript
JavaScript and TypeScript SDK
Install @useorbits/sdk, create a client, deploy and follow a build, manage variables and domains, and handle errors, pages and retries.
import { Orbits } from "@useorbits/sdk";
const orbits = new Orbits();
for await (const project of orbits.projects.listAll("my-team")) {
console.log(project.slug, project.status, project.production_url);
}@useorbits/sdk is the official JavaScript library, with TypeScript types generated from the API's OpenAPI contract. It has no runtime dependencies and uses the global fetch, so it runs on Node.js 20 or later, Bun and Deno. It ships as ESM and CommonJS.
Request and response fields are exactly as the API sends them (source_kind, next_cursor); method names are camelCase. team is a team's slug or team_ id, and project a project's slug or prj_ id.
Install
$ npm install @useorbits/sdkAuthenticate
Make an API token under Team › Settings › API tokens and put it in ORBITS_TOKEN. The client reads it.
$ export ORBITS_TOKEN=orb_live_…Without a token, new Orbits() throws. Or pass options:
const orbits = new Orbits({
token: process.env.MY_ORBITS_TOKEN,
baseUrl: "https://stagingapi.theorbits.app/v1", // or ORBITS_API_URL; default https://api.theorbits.app/v1
maxRetries: 3, // the default
timeout: 60_000, // per attempt, in milliseconds (the default)
userAgent: "my-deployer/1.0", // default orbits-js/<version>
});fetch sets your own fetch. Every method also takes per-call options last: { signal, timeout, maxRetries, idempotencyKey, headers }.
Deploy and follow the build
For a Git project, deployments.create builds a branch's newest commit, by default the production branch:
import { Orbits } from "@useorbits/sdk";
const orbits = new Orbits();
const deployment = await orbits.deployments.create("my-team", "my-app");
// or a preview: orbits.deployments.create("my-team", "my-app", { branch: "feature/checkout" })
for await (const event of orbits.deployments.streamLogs("my-team", "my-app", deployment)) {
if (event.type === "line") console.log(event.line.text);
if (event.type === "done") console.log(`Build ${event.state} in ${event.duration_seconds}s`);
}
const ready = await orbits.waitForDeployment("my-team", "my-app", deployment);
console.log(ready.url);streamLogs follows the build log as it is written, reconnects where it left off if the connection drops, and ends after done. Breaking out of the loop, or aborting signal, closes the stream. For a finished build, deployments.listAllLogs(team, project, deployment) pages through the whole log. deployments.get(team, project, deployment) reads one deployment.
Deploy a folder
Projects created with source_kind: "upload" deploy from files instead of a repository. uploadDir, from @useorbits/sdk/node, zips a folder and deploys it to production:
import { Orbits } from "@useorbits/sdk";
import { uploadDir } from "@useorbits/sdk/node";
const orbits = new Orbits();
await orbits.projects.create("my-team", { name: "my-site", source_kind: "upload" });
const { deployment } = await uploadDir(orbits, "my-team", "my-site", "./dist");
await orbits.waitForDeployment("my-team", "my-site", deployment);It leaves out node_modules, .git, .next and __MACOSX, and whatever the folder's .orbitsignore lists (.gitignore syntax). Everything else is uploaded, .env files included, so list those in .orbitsignore unless the build needs them. Symbolic links are left out and reported in skipped. An upload may be up to 100 MB zipped and 20,000 files.
@useorbits/sdk/node uses Node.js built-ins (Node.js, Bun, and Deno with node: modules). Anywhere else, zip the files yourself and call orbits.deployments.upload(team, project, zipBytes, { filename }).
Promote, roll back, redeploy
await orbits.deployments.promote("my-team", "my-app", "dpl_…"); // a preview to production, as a new build
await orbits.deployments.redeploy("my-team", "my-app", "dpl_…", { use_cache: false });
await orbits.deployments.cancel("my-team", "my-app", "dpl_…");
const change = await orbits.deployments.rollback("my-team", "my-app", "dpl_…"); // at once, no build
console.log(change.undo); // pass to deployments.setProduction to undo itA rollback pauses automatic production deploys. See Deployments.
Environment variables
await orbits.env.create("my-team", "my-app", {
variables: [
{ key: "STRIPE_SECRET_KEY", value: process.env.STRIPE_SECRET_KEY ?? "" }, // sensitive by default
{ key: "API_URL", value: "https://api.example.com", sensitive: false, environments: ["production"] },
],
});
for await (const v of orbits.env.listAll("my-team", "my-app")) {
console.log(v.key, v.environments, v.sensitive);
}Variables are sensitive (write-only) unless sensitive: false, and apply to production and preview unless you set environments. A key that exists already fails with a ConflictError; pass on_conflict: "replace" to replace it. New values apply to deployments built afterwards, so redeploy to use them. Values are never listed; env.reveal reads one non-sensitive value and env.pull an environment's readable values, both with a full-access token. See Environment variables.
Domains
const domain = await orbits.domains.add("my-team", { domain: "shop.example.com", project: "my-app" });
console.log(domain.state, domain.required_record);
const checked = await orbits.domains.check("my-team", "shop.example.com"); // look the DNS up again nowbranch serves a branch's newest preview instead of production, and to redirects to another hostname. Records on Orbits DNS are under domains.records (list, add, replace, delete). See Custom domains.
Resources
| Area | Methods |
|---|---|
| Me | me.get() |
| Teams | teams.list/listAll/get/update/overview, teams.notifications.list/listAll/markRead |
| Projects | projects.list/listAll/create/get/update/delete/deletionImpact/pause/resume/branchAddresses |
| Deployments | deployments.list/listAll/listForTeam/listAllForTeam/create/get/redeploy/promote/rollback/cancel/setProduction, deployments.logs/listAllLogs/streamLogs/screenshot, deployments.upload, deployments.uploads.start/complete/cancel, deployments.wait |
| Environment variables | env.list/listAll/create/update/delete/restore/reveal/pull |
| Domains | domains.list/preview/add/get/update/remove/check/importZone, domains.records.list/add/replace/delete, domains.email.get/set |
| Flags | flags.list/create/get/update/delete/keys/setEnvironment, flags.rules.add/update/remove |
| Workflows | workflows.list/run, workflows.runs.get/cancel/retry |
| Alerts | alerts.list/create/preview/update/delete, alerts.events.list/listAll, alerts.channels.get/setWebhook/deleteWebhook/testWebhook |
| Observability | observability.get, observability.runtimeLogs.list/listAll/get, observability.analytics.get/event/set, observability.speedInsights.get/set |
| Usage, activity | usage.get(team, { month }), activity.list/listAll |
| Billing (reads) | billing.listPlans, billing.get, billing.invoices.list/get |
| Templates, integrations | templates.list(), integrations.list(team) |
| Operations | operations.get/wait, waitForOperation, waitForDeployment |
There are sandboxes methods too, but sandboxes are not available yet.
Errors
Every error is an OrbitsError with the API's problem document: status, title, detail, code, requestId, errors (the fields of a 422) and problem. Show detail to people; branch on the class or the code:
import { ForbiddenError, isOrbitsError, ValidationError } from "@useorbits/sdk";
try {
await orbits.projects.create("my-team", { name: "my-app", source_kind: "upload" });
} catch (err) {
if (err instanceof ValidationError) for (const e of err.errors) console.log(e.field, e.message);
else if (err instanceof ForbiddenError) console.log(err.reason); // e.g. "This API token is read-only"
else if (isOrbitsError(err, "plan_required")) console.log("Needs Pro");
else throw err;
}| Class | When |
|---|---|
BadRequestError | 400 |
AuthenticationError | 401: the token is wrong, revoked or expired |
PlanRequiredError | 402: the team's plan doesn't include this (requiredPlan, feature) |
ForbiddenError | 403, with the API's reason |
NotFoundError | 404: not there, or not in the token's team. The API answers the same for both |
ConflictError | 409 |
ValidationError | 422, with errors[{ field, message }] |
RateLimitedError | 429 after the retries, with retryAfterSeconds and scope |
ServerError | 5xx after the retries |
ConnectionError, TimeoutError | No answer |
A response that isn't the API's own error (a proxy's error page, say) is never shown: the message says what the status means and gives the request id. Errors.
Pages
list() returns one page ({ items, next_cursor }). listAll() follows the cursor for you, fetching each page only when the loop gets there:
for await (const d of orbits.deployments.listAll("my-team", "my-app", { environment: "production" })) {
console.log(d.id, d.state);
}Waiting
Slow changes answer 202 with an operation or the new deployment:
const op = await orbits.projects.delete("my-team", "old-site");
await orbits.waitForOperation(op); // rejects with OperationFailedError if it failed
const d = await orbits.deployments.redeploy("my-team", "my-app", "dpl_…");
await orbits.waitForDeployment("my-team", "my-app", d, { timeoutMs: 15 * 60_000, onUpdate: (x) => console.log(x.state) });Both poll every 2 seconds and give up after 30 minutes with a WaitTimeoutError; the change may still finish. Options: { timeoutMs, pollIntervalMs, signal, onUpdate }. waitForDeployment resolves when the deployment is ready, and rejects with DeploymentFailedError (with the build's failure in the message) when it ends failed or canceled; pass throwOnFailure: false to get the deployment back instead.
Idempotency and retries
Every POST carries an Idempotency-Key, a random UUID or yours via idempotencyKey, and every retry of that call reuses it, so a change can't happen twice. Connection errors, timeouts, 429, 502, 503 and 504 are retried up to maxRetries times with a growing, random wait, or after Retry-After when the API sends it (at most a minute).
The token is sent only to the API, never to the storage address an upload goes to, and is kept out of the client's printed form. The SDK never logs anything.
Calling any endpoint
request calls a path directly, with the same auth, retries and errors:
const page = await orbits.request({ method: "GET", path: "/teams/my-team/projects", query: { q: "shop" } });