# SDKs

> Official zero-dependency TypeScript and Python clients for the Ody REST API, with auto-pagination, typed errors, idempotency and webhook verification.

Source: https://dev.ody.co/sdks/overview

> **Availability:**
The SDKs are **in preview**: the packages are release-ready at v0.3.0 and the first registry release is being set up. Until `npm install @ody/sdk` / `pip install ody-sdk` work, install from the [source tree](https://github.com/CosmicHero2/ody-platform/tree/main/sdks) (each README has the one-line install), call the REST API directly (every example in these docs has a cURL tab), or generate a client from the [OpenAPI spec](https://api.ody.co/v1/api/openapi.json). Want to be told when they land on npm and PyPI? Email [support@ody.co](mailto:support@ody.co).

| | TypeScript | Python |
|---|---|---|
| Package | `@ody/sdk` | `ody-sdk` (imported as `ody`) |
| Version | 0.3.0 | 0.3.0 |
| Runtime | Node.js 18+, Deno, Bun, browsers (any `fetch`) | Python 3.9+ |
| Dependencies | None | None (standard library only) |
| Webhook verification | `verifyWebhookSignature()` (server-side) | `verify_webhook_signature()` |
| Webhook parsing | `parseWebhookEvent()` → typed `WebhookEvent` | `parse_webhook_event()` → envelope dict |
| Event catalog | `WEBHOOK_EVENT_TYPES`, `WebhookEventType`, a `data` type per event | `WEBHOOK_EVENT_TYPES` |

## What they give you over raw HTTP

| Feature | TypeScript | Python |
|---|---|---|
| Auto-pagination | `for await (const c of ody.contacts.listAll())` | `for c in client.contacts.list_all():` |
| Typed errors | `OdyError` with `code`, `status`, `requestId`, `retryAfter` | `OdyError` with `code`, `status`, `request_id`, `retry_after` |
| Idempotency | `idempotencyKey` option on `messages.send`, `numbers.buy` | `idempotency_key=` |
| Types | Full TypeScript types for every resource | Docstrings and type hints; responses are dicts |
| Webhook signatures | Constant-time HMAC, 5-minute replay window | Same |
| Webhook events | `parseWebhookEvent()` verifies + parses; `event.data` typed per `event.type` | `parse_webhook_event()` verifies + parses |

The SDKs **don't retry automatically**. Wrap calls in your own backoff using `retryAfter` / `retry_after` (see [Rate limits](https://dev.ody.co/api/rate-limits)).

## Resource map

Both SDKs mirror the REST API one-to-one:

| Namespace | TypeScript methods | REST |
|---|---|---|
| `contacts` | `list`, `listAll`, `create`, `get`, `update`, `delete` | [Contacts](https://dev.ody.co/api/contacts) |
| `conversations` | `list`, `listAll`, `get`, `setStatus` | [Conversations](https://dev.ody.co/api/conversations) |
| `messages` | `send`, `search` | [Messages](https://dev.ody.co/api/messages) |
| `calls` | `list`, `place` | [Calls](https://dev.ody.co/api/calls) |
| `numbers` | `list`, `searchAvailable`, `buy`, `connectAgent`, `disconnectAgent` | [Numbers](https://dev.ody.co/api/numbers) |
| `messaging` | `status`, `register`, `refresh`, `verifyOtp`, `resendOtp` | [Messaging](https://dev.ody.co/api/messaging) |
| `agent` | `get`, `update`, `publish` | [Agent](https://dev.ody.co/api/agent) |
| `webhooks` | `list`, `create`, `get`, `update`, `delete`, `rotate`, `test`, `deliveries`, `eventTypes` | [Webhook endpoints](https://dev.ody.co/api/webhook-endpoints) |

Python uses the same names in `snake_case` (`list_all`, `set_status`, `search_available`, `connect_agent`, `verify_otp`, `event_types`, …).

- [**TypeScript SDK**](https://dev.ody.co/sdks/typescript) — Setup, usage, errors, webhook verification.
- [**Python SDK**](https://dev.ody.co/sdks/python) — Setup, usage, errors, webhook verification.