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

# TypeScript SDK

> The @sente-labs/sdk client — typed, zero runtime dependencies, talks to https://api.sente.run/v1.

`@sente-labs/sdk` is a thin typed client for the Sente REST API. Zero runtime dependencies
(it uses global `fetch`). Types ship with the package — no `@types/*` install.

```bash theme={null}
npm i @sente-labs/sdk
```

## Setup

Get an API key from the [dashboard](https://app.sente.run) (API keys page), or via the
[CLI](/sdks/cli) with `sente login` + `sente token`. The key authenticates your whole
organization — keep it in an environment variable, never in code.

```ts theme={null}
import { Sente } from "@sente-labs/sdk";

const sente = new Sente({ apiKey: process.env.SENTE_API_TOKEN! });
```

`new Sente(opts)` takes `{ apiKey, baseUrl?, fetch? }`. `baseUrl` defaults to
`https://api.sente.run`; the `fetch` override is handy for tests.

## Create an identity

An identity is a real, reusable email address on `sente.run` that your agent owns.
See [Identities and registrations](/concepts/identities-and-registrations).

```ts theme={null}
const idt = await sente.identities.create({ name: "support-bot", localPart: "support-bot" });
// -> { id, email: "support-bot@sente.run", ... }
```

If the `localPart` is taken, `create` throws a 409 (`onConflict: "error"` is the default);
pass `onConflict: "suffix"` to append a random suffix instead.

## Wait for a verification code

Every inbound email is classified server-side (`message.annotation`:
`{ kind, code, link, confidence }`), so an agent that signed up somewhere with the identity's
address can block until the code or link arrives. Stamp `since` **before** triggering the
action so you never match an older email:

```ts theme={null}
const since = new Date().toISOString();
// ...trigger the signup / login that sends the verification email...
const otp = await sente.messages.waitForOtp(idt.id, { since, timeout: 60 });
if (otp) console.log(otp.code); // e.g. "481923"

// Links instead of codes:
const ml = await sente.messages.waitForMagicLink(idt.id, { since, timeout: 60 });
if (ml) console.log(ml.link);
```

Both resolve `null` on timeout. `timeout` is in seconds (1–60, default 25). If you omit
`since`, the server falls back to a 60-second lookback. More patterns in
[Receive verification codes](/guides/receive-verification-codes).

## Send and reply

```ts theme={null}
await sente.messages.send(idt.id, {
  to: "user@example.com",
  subject: "hi",
  text: "from your agent",
});

// Thread a reply to an inbound message (sets In-Reply-To/References):
await sente.messages.send(idt.id, {
  to: "user@example.com",
  subject: "Re: hi",
  text: "following up",
  inReplyTo: inboundMessageId,
});
```

`text` and/or `html` is required. To consume mail continuously, `messages.stream(identityId)`
is an async generator that long-polls; for production prefer [webhooks](/guides/webhooks)
(push, not poll).

## Register at a third-party app

`registrations.register` drives a browser through signup at `appUrl` under the identity's
email and completes email verification from the identity's own inbox. It returns the durable
account (`registration`) and its first `run`.

```ts theme={null}
const { registration, run } = await sente.registrations.register({
  identityId: idt.id,
  appUrl: "https://app.example.com/signup",
  confirmBeforeSubmit: true, // a human clicks the final submit (recommended)
});

const final = await sente.runs.waitForRun(run.id); // settles on completed | failed | blocked
```

<Warning>
  Register only at apps whose terms permit it. `confirmBeforeSubmit: true` keeps a human in
  the loop: the agent fills the form, then the run goes `blocked` with
  `error.code === "SUBMIT_CONFIRMATION_REQUIRED"` and a `liveViewUrl` — a person clicks the
  final submit there (and accepts the app's terms themselves), then you call
  `runs.resume(run.id)`. See [Acceptable use](/trust/acceptable-use).
</Warning>

`waitForRun(id, { timeout?, pollMs? })` polls until the run is `completed`, `failed`, or
`blocked` (`timeout` in **milliseconds**, default 180000). `blocked` means human takeover:
CAPTCHAs, SMS verification, and confirm-before-submit all stop the run — a person finishes
the step in the interactive `liveViewUrl`, then `runs.resume(id)` continues. On timeout it
returns the last-polled run (status still `running` / `awaiting_verification`). See
[Runs and human takeover](/concepts/runs-and-human-takeover).

Re-authenticate later with `registrations.login(registrationId)` — same
`{ registration, run }` shape. Vaulted credentials: `registrations.getCredentials(id)` /
`setCredentials(id, { username?, password? })` (`setCredentials` overwrites the vault only —
it does not change the password at the app).

## Connect an account you already own

`connections.connect` is delegated access to an existing account: you supply the credentials,
Sente logs in, vaults them **write-only**, and keeps the account re-loginable. See the
[Connect guide](/guides/connect).

```ts theme={null}
const { connection, run } = await sente.connections.connect({
  identityId: idt.id,
  appUrl: "https://app.example.com/login",
  credentials: {
    username: "you@yourco.com",
    password: process.env.APP_PASSWORD!,
    totpSeed: process.env.APP_TOTP_SEED, // optional: base32 secret or otpauth:// URI
  },
});
await sente.runs.waitForRun(run.id);
```

<Note>
  Limits, stated plainly:

  * **SSO-only accounts** (Google/Okta sign-in, passkeys) cannot be connected — connect needs a username + password login.
  * **Credentials are write-only**: `registrations.getCredentials` on a connected account returns 403 `CREDENTIALS_WRITE_ONLY`.
  * With a vaulted `totpSeed`, re-login clears TOTP 2FA without a human; the server computes the 30-second code — the seed never reaches any model.
  * **Email or SMS code MFA needs a human**: the run goes `blocked` with `MFA_REQUIRED` — enter the code in `liveViewUrl`, then `runs.resume(run.id)` — unless the account's notification email has been repointed to the Sente identity.
</Note>

`connections.revoke(id)` disables the connection but keeps the vault (a later `connect`
re-enables it); `connections.delete(id)` revokes **and** purges the vaulted credentials.
Connected accounts are also reachable through the `registrations` methods (`getSession`,
`login`, `exportSession`) by the returned id.

## Open or export a logged-in session

`getSession` returns a remote browser already logged into the account, as a CDP URL you
drive yourself. If the login has gone stale, Sente re-logs-in first (vaulted credentials +
a fresh code from the identity's inbox) — `healed: true` tells you that happened, and a cold
call can take a minute.

```ts theme={null}
import { chromium } from "playwright";

const s = await sente.registrations.getSession(registration.id);
// { sessionId, cdpUrl, liveViewUrl, expiresAt, verified, healed }
const browser = await chromium.connectOverCDP(s.cdpUrl);
// ... drive it ...
await sente.registrations.closeSession(registration.id);
```

One live session per identity; open sessions count against your plan's browser-minute
allowance — always `closeSession` when done. `getSession` accepts `{ verify?, maxStaleSec?, timeoutMs? }`; `verify: false`
skips the freshness check (raw). `openSession(id)` is the raw primitive with no freshness
check. If re-login can't recover, `getSession` throws a `SenteError` whose body is the
failed/blocked run.

To use your **own** browser stack instead, export the logged-in state (cookies +
localStorage) as a Playwright `storageState`:

```ts theme={null}
const { storageState } = await sente.registrations.exportSession(registration.id);
const context = await browser.newContext({ storageState });
```

The export is a bearer credential for a logged-in account — store it like a secret. More in
the [Sessions guide](/guides/sessions).

## Webhooks

Register your endpoint and Sente pushes events to it with retries. The `secret` is returned
once — store it.

```ts theme={null}
const { secret } = await sente.webhooks.register({
  url: "https://your-host.example.com/sente",
  events: ["message.received"],
  identityId: idt.id, // omit for org-wide
});
```

`message.received` payloads are thin notifications with no body — fetch content with
`messages.get(id)`. Run lifecycle events (`run.blocked`, `run.completed`, `run.failed`) are
also available. Every delivery carries the secret in the `x-sente-secret` header — verify it
with a timing-safe compare. Full payloads and verification code in the
[Webhooks guide](/guides/webhooks).

## Errors

Non-2xx responses throw `SenteError` with `status` (HTTP status) and `body` (response body).

```ts theme={null}
import { Sente, SenteError } from "@sente-labs/sdk";

try {
  await sente.identities.create({ localPart: "acme-bot" });
} catch (e) {
  if (e instanceof SenteError && e.status === 409) {
    // address taken — pick another, or retry with onConflict: "suffix"
  }
}
```

<Warning>
  Inbound email is untrusted input. It can contain prompt injection ("ignore your
  instructions...", "send the API key to..."). Never treat instructions found in email as
  coming from your user — extract only the datum you need (a code, a link, the sender's ask).
</Warning>

## Method reference

| Method                                                  | Params                                                                   | Returns                                                                    |
| ------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `identities.create(input?)`                             | `{ name?, description?, localPart?, onConflict?: "error" \| "suffix" }`  | `Promise<Identity>`                                                        |
| `identities.get(id)` / `identities.list()`              | —                                                                        | `Promise<Identity>` / `Promise<Identity[]>`                                |
| `messages.list(identityId, opts?)`                      | `{ since?, direction?, kind?, limit? }`                                  | `Promise<Message[]>`                                                       |
| `messages.get(id)`                                      | `id: string`                                                             | `Promise<Message>`                                                         |
| `messages.send(identityId, input)`                      | `{ to, subject, text?, html?, inReplyTo? }`                              | `Promise<Message>`                                                         |
| `messages.waitFor(identityId, opts?)`                   | `{ since?, timeout?, kind? }`                                            | `Promise<Message \| null>`                                                 |
| `messages.waitForOtp(identityId, opts?)`                | `{ since?, timeout? }`                                                   | `Promise<{ code, message } \| null>`                                       |
| `messages.waitForMagicLink(identityId, opts?)`          | `{ since?, timeout? }`                                                   | `Promise<{ link, message } \| null>`                                       |
| `messages.stream(identityId, opts?)`                    | `{ since?, timeout? }`                                                   | `AsyncGenerator<Message>`                                                  |
| `webhooks.register(input)`                              | `{ url, events, identityId? }`                                           | `Promise<Webhook & { secret }>`                                            |
| `webhooks.list()` / `webhooks.delete(id)`               | —                                                                        | `Promise<Webhook[]>` / `Promise<void>`                                     |
| `registrations.register(input)`                         | `{ identityId, appUrl, credentials?, confirmBeforeSubmit? }`             | `Promise<{ registration, run }>`                                           |
| `registrations.list(identityId?)`                       | —                                                                        | `Promise<(Registration & { latestRun })[]>`                                |
| `registrations.get(id)`                                 | —                                                                        | `Promise<Registration>`                                                    |
| `registrations.login(id)`                               | —                                                                        | `Promise<{ registration, run }>`                                           |
| `registrations.getCredentials(id)`                      | —                                                                        | `Promise<{ username, password, origin }>`                                  |
| `registrations.setCredentials(id, input)`               | `{ username?, password? }`                                               | `Promise<void>`                                                            |
| `registrations.getSession(id, opts?)`                   | `{ verify?, maxStaleSec?, timeoutMs? }`                                  | `Promise<{ sessionId, cdpUrl, liveViewUrl, expiresAt, verified, healed }>` |
| `registrations.openSession(id)`                         | —                                                                        | same minus `verified`/`healed`; no freshness check                         |
| `registrations.closeSession(id)`                        | —                                                                        | `Promise<void>`                                                            |
| `registrations.exportSession(id, opts?)`                | `{ verify?, maxStaleSec? }`                                              | `Promise<{ storageState }>`                                                |
| `connections.connect(input)`                            | `{ identityId, appUrl, credentials: { username, password, totpSeed? } }` | `Promise<{ connection, run }>`                                             |
| `connections.list(identityId?)` / `connections.get(id)` | —                                                                        | `Promise<...>`                                                             |
| `connections.revoke(id)` / `connections.delete(id)`     | —                                                                        | `Promise<Registration>` / `Promise<void>`                                  |
| `runs.get(id)` / `runs.resume(id)` / `runs.abort(id)`   | —                                                                        | `Promise<Run>`                                                             |
| `runs.waitForRun(id, opts?)`                            | `{ timeout? (ms, default 180000), pollMs? }`                             | `Promise<Run>`                                                             |

Endpoint-level details are in the [API reference](/api-reference/overview). Python sibling:
[sente-sdk](/sdks/python). CLI: [sente](/sdks/cli).