> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Orbit by Devotel SDKs — 2 in active development (Node, Web), 6 on roadmap.

# SDKs

Orbit ships two SDKs in active development today (Node.js, Web). The
remaining six (Python, Go, PHP, Ruby, Java, .NET) are on the roadmap
but have not been published to any package registry. When they ship,
every SDK will share the same auth model (`X-API-Key`), retry policy
(3 attempts on 429/5xx with exponential backoff), idempotency contract
(auto-generated `Idempotency-Key` on every non-GET), and webhook
verification format (`t=<unix_ts>,v1=<hex_hmac>` HMAC-SHA256, 5-minute
replay window).

<Note>
  **Pre-launch — no SDK is currently published to a public registry.**
  Until first publish, the Node + Web SDK source lives in the monorepo
  under `packages/sdk-node/` and `packages/sdk-web/`. Install commands
  here describe the *future* registry shapes — not the *current* reach
  (every public registry probe today returns 404). The remaining six
  languages are roadmap.
</Note>

## Available today (workspace source)

<CardGroup cols={2}>
  <Card title="Node.js / TypeScript" icon="js" href="/sdks/node">
    Source: `packages/sdk-node/` — package name `@devotel/orbit-sdk`.
    Hand-written, fully typed. Node 18+.
    Status: **GA (workspace, pre-publish)**.
  </Card>

  <Card title="Web (browser)" icon="globe" href="/sdks/web">
    Source: `packages/sdk-web/` — package name `@devotel/orbit-web-sdk`.
    Embeddable chat widget + inbound APIs.
    Status: **GA (workspace, pre-publish)**.
  </Card>
</CardGroup>

## On the roadmap

The six languages below are tracked targets — no public registry entry
exists for any of them today. Do not attempt to install; the cited
package names describe the *future* coordinates and may change before
first publish.

| Language  | Future package name           | Future registry | Status  |
| --------- | ----------------------------- | --------------- | ------- |
| Python    | `devotel-orbit-sdk`           | PyPI            | Roadmap |
| Go        | `github.com/devotel/orbit-go` | pkg.go.dev      | Roadmap |
| PHP       | `devotel/orbit-sdk`           | Packagist       | Roadmap |
| Ruby      | `orbit_sdk`                   | RubyGems        | Roadmap |
| Java      | `io.devotel:orbit-sdk`        | Maven Central   | Roadmap |
| .NET / C# | `Orbit.Sdk`                   | NuGet           | Roadmap |

Once each lands on its registry, the per-language Mintlify subpage
(`/sdks/node`, `/sdks/web`, …) will carry the production install
command, version pin, and per-language quickstart. The codegen pipeline
that drives this lives at `tools/sdk-codegen/README.md`.

## Common patterns across languages

### Authentication

Every SDK authenticates with an `X-API-Key`. The GA Node SDK exposes a
single constructor — `new Orbit({ apiKey })` (alias `new Devotel({ apiKey })`)
— and you pass your own env var (e.g. `process.env.ORBIT_API_KEY`); the Web
surfaces take a `publicKey` instead. There is **no** `fromApiKey()` static
or `from_env()` helper on the GA SDKs today — those are roadmap-language for
the codegen'd clients, so the **From env** column below is marked *Roadmap*
on every row that lists one.

| Language | Direct                                      | From env (Roadmap)                      | Status  |
| -------- | ------------------------------------------- | --------------------------------------- | ------- |
| Node     | `new Orbit({ apiKey: 'dv_live_sk_...'})`    | — (use `process.env.ORBIT_API_KEY`)     | GA      |
| Web      | `OrbitVoiceAgent.init({ publicKey: '...'})` | — (use bundler-injected env)            | GA      |
| Python   | `OrbitClient.from_api_key('...')`           | `OrbitClient.from_env()` *(Roadmap)*    | Roadmap |
| Go       | `orbit.NewClient('...')`                    | — (use `os.Getenv("ORBIT_API_KEY")`)    | Roadmap |
| PHP      | `OrbitClient::fromApiKey('...')`            | `OrbitClient::fromEnv()` *(Roadmap)*    | Roadmap |
| Ruby     | `OrbitSdk::Client.from_api_key('...')`      | `OrbitSdk::Client.from_env` *(Roadmap)* | Roadmap |
| Java     | `OrbitClient.fromApiKey("...")`             | `OrbitClient.fromEnv()` *(Roadmap)*     | Roadmap |
| C#       | `OrbitClient.FromApiKey("...")`             | `OrbitClient.FromEnv()` *(Roadmap)*     | Roadmap |

The GA Node and Web rows have **no** `fromApiKey`/env-reading helper — only
the constructor shown in the **Direct** column.

### Webhook verification

Webhook verification is server-side only — the Web SDK does not expose a
verifier (browser surfaces never receive inbound webhooks). Each server-side
SDK exposes a one-call verifier that returns the decoded event on success or
throws `OrbitWebhookSignatureError` on any failure (malformed header, expired
timestamp, signature mismatch, invalid JSON):

* **Node** *(GA)*: `Orbit.webhooks.constructEvent(body, signature, secret)`
* **Python** *(Roadmap)*: `verify_webhook(payload=..., signature=..., secret=...)`
* **Go** *(Roadmap)*: `orbit.VerifyWebhook(body, header, secret, 0, time.Time{})`
* **PHP** *(Roadmap)*: `Webhooks::verify(payload: ..., signature: ..., secret: ...)`
* **Ruby** *(Roadmap)*: `OrbitSdk::Webhooks.verify(payload:, signature:, secret:)`
* **Java** *(Roadmap)*: `Webhooks.verify(body, signature, secret)`
* **C#** *(Roadmap)*: `Webhooks.Verify(payload, signature, secret)`

### Error hierarchy

Every SDK exposes the same error tree:

* `OrbitApiError` (base) → catch this to handle any non-2xx API response.
  Carries `code`, `statusCode` (aliased as `status`), `details`, `docsUrl`,
  and `requestId`, plus `isRateLimited` / `isClientError` / `isServerError`
  getters.
* `OrbitAuthError` — 401/403 (bad API key or missing scope).
* `OrbitNotFoundError` — 404 (resource doesn't exist or isn't visible).
* `OrbitRateLimitError` — 429. Check the `Retry-After` header (also surfaced
  in `details`) to decide when to retry.
* `OrbitValidationError` — 400/422 (request body failed server-side validation).
* `OrbitServerError` — 5xx after retries exhausted, or persistent network failure.
* `OrbitWebhookSignatureError` — webhook verification failed. Carries a
  `code` of `'bad_signature' | 'expired' | 'malformed'`. Extends `Error`,
  **not** `OrbitApiError`, so a broad `catch (OrbitApiError)` block can't
  accidentally swallow + retry forgeries.

## Operator: publishing checklist

See `tools/sdk-codegen/README.md` for the per-registry publish commands.
Pre-launch, the SDKs are committed source-only; first publish to each
registry is an operator action.