OrbitsDocs
esc
    Open Orbits
    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.

    TypeScript
    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

    Terminal
    $ npm install @useorbits/sdk

    Authenticate

    Make an API token under Team › Settings › API tokens and put it in ORBITS_TOKEN. The client reads it.

    Terminal
    $ export ORBITS_TOKEN=orb_live_…

    Without a token, new Orbits() throws. Or pass options:

    TypeScript
    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:

    deploy.ts
    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:

    TypeScript
    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

    TypeScript
    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 it

    A rollback pauses automatic production deploys. See Deployments.

    Environment variables

    TypeScript
    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

    TypeScript
    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 now

    branch 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

    AreaMethods
    Meme.get()
    Teamsteams.list/listAll/get/update/overview, teams.notifications.list/listAll/markRead
    Projectsprojects.list/listAll/create/get/update/delete/deletionImpact/pause/resume/branchAddresses
    Deploymentsdeployments.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 variablesenv.list/listAll/create/update/delete/restore/reveal/pull
    Domainsdomains.list/preview/add/get/update/remove/check/importZone, domains.records.list/add/replace/delete, domains.email.get/set
    Flagsflags.list/create/get/update/delete/keys/setEnvironment, flags.rules.add/update/remove
    Workflowsworkflows.list/run, workflows.runs.get/cancel/retry
    Alertsalerts.list/create/preview/update/delete, alerts.events.list/listAll, alerts.channels.get/setWebhook/deleteWebhook/testWebhook
    Observabilityobservability.get, observability.runtimeLogs.list/listAll/get, observability.analytics.get/event/set, observability.speedInsights.get/set
    Usage, activityusage.get(team, { month }), activity.list/listAll
    Billing (reads)billing.listPlans, billing.get, billing.invoices.list/get
    Templates, integrationstemplates.list(), integrations.list(team)
    Operationsoperations.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:

    TypeScript
    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;
    }
    ClassWhen
    BadRequestError400
    AuthenticationError401: the token is wrong, revoked or expired
    PlanRequiredError402: the team's plan doesn't include this (requiredPlan, feature)
    ForbiddenError403, with the API's reason
    NotFoundError404: not there, or not in the token's team. The API answers the same for both
    ConflictError409
    ValidationError422, with errors[{ field, message }]
    RateLimitedError429 after the retries, with retryAfterSeconds and scope
    ServerError5xx after the retries
    ConnectionError, TimeoutErrorNo 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:

    TypeScript
    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:

    TypeScript
    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:

    TypeScript
    const page = await orbits.request({ method: "GET", path: "/teams/my-team/projects", query: { q: "shop" } });

    Was this page helpful?

    Updated