# SDKs (https://dodomain.io/docs/sdks)

The four published DoDomain SDKs (@dodomain/node, @dodomain/connect and @dodomain/react on npm, dodomain-sdk on PyPI), and how to pick one.

DoDomain publishes four SDKs. Each is a convenience over the same REST surface: raw HTTP against `/api/v1` stays fully supported, and nothing the SDKs do is unavailable to a plain `curl`.

| Package                         | Registry | Runs on               | What it's for                                                                   |
| ------------------------------- | -------- | --------------------- | ------------------------------------------------------------------------------- |
| [`@dodomain/node`](https://dodomain.io/docs/node-sdk)   | npm      | Node 20+ (server)     | Mint sessions, manage connections, webhook endpoints and keys; verify webhooks. |
| [`@dodomain/connect`](https://dodomain.io/docs/widget)  | npm      | Browsers              | Open the hosted connect flow in a modal iframe on your own page.                |
| [`@dodomain/react`](https://dodomain.io/docs/react-sdk) | npm      | React 18+ (browsers)  | The widget as a React hook: lifecycle, stale-closure and unmount safety.        |
| [`dodomain-sdk`](https://dodomain.io/docs/python-sdk)   | PyPI     | Python 3.10+ (server) | The same server surface as `@dodomain/node`, in sync and async twins.           |

```bash
npm install @dodomain/node      # your server (TypeScript / JavaScript)
npm install @dodomain/connect   # your frontend
npm install @dodomain/react     # your frontend, if it's React
pip install dodomain-sdk        # your server (Python)
```

All four are MIT-licensed. `@dodomain/node` and `@dodomain/connect` ship **zero runtime dependencies** (dual ESM + CJS builds with self-contained type declarations; the schemas they validate against are inlined); `@dodomain/react` is ~1 KB of glue whose only runtime dependency is `@dodomain/connect` itself, so the widget is never bundled twice. The Python SDK depends only on [httpx](https://www.python-httpx.org/).

## Which ones you need [#which-ones-you-need]

A complete integration usually takes **one server SDK plus nothing else**: your backend mints the session, and you hand the user `session.connectUrl`. That is a working custom-domain flow with no frontend code at all.

Add `@dodomain/connect` when you want the flow to happen inside your own page rather than on `app.dodomain.io`. It never touches the API itself: it opens the hosted flow in an iframe and relays what that flow reports, so it needs no credential beyond the session token your server already minted. In a React app, reach for [`@dodomain/react`](https://dodomain.io/docs/react-sdk) instead of calling the widget directly: same widget, plus the hook-shaped lifecycle handling (latest-props callbacks, one-modal-at-a-time, unmount cleanup).

## Two rules that hold for every SDK [#two-rules-that-hold-for-every-sdk]

**The secret key is server-side only.** `dd_sk_...` authenticates every server SDK call. It must never reach a browser bundle, and the browser widget never needs one: only the `dd_sess_...` session token, which is a capability scoped to that one session.

**The webhook is the source of truth.** A browser callback (`onVerified`) fires where anything can be spoofed; a `connection.verified` webhook is HMAC-signed by DoDomain. Use the callback to refresh your UI and the webhook to change your data. Both server SDKs ship the verifier: `verifyWebhook` in `@dodomain/node`, `verify_webhook` in `dodomain-sdk`. See [Webhooks](https://dodomain.io/docs/webhooks).

## Source and issues [#source-and-issues]

The npm packages are developed in the DoDomain monorepo and mirrored read-only at [DevinoSolutions/dodomain-sdk](https://github.com/DevinoSolutions/dodomain-sdk), which also hosts their external issues. The Python SDK is developed in the open at [DevinoSolutions/dodomain-python](https://github.com/DevinoSolutions/dodomain-python).