@curviate/sdk 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -7,7 +7,256 @@ Versioning: semantic. Minor for additive changes, patch for bug fixes; no stabil
 
 ---
 
-## [Unreleased]
+## [0.43.0] - Unreleased
+
+Fixture and types regenerated from deployed staging (server
+`7359b1b1be0584f7f368f1367d39261f2de8f079`, 193 paths; earlier regens at
+`16b2eaf1473e4fb2a7b7b4a0308b9e248b30a93e`, 193 paths,
+`091f53a69decbc55c53336bbbbfa1dc5fd56e859`, 193 paths,
+`13d5357a7f74772782872c791ec8a5835060e9fe`, 191 paths, and
+`3b0b7503a516f6a1f39622bd40ec6fec9c217c38`, 176 paths). The previous fixture
+was older, so this regen also carries earlier, unrelated server changes (see
+Changed). Regenerate from production and confirm an empty diff before publishing.
+
+### Added
+
+- **`network`** (root, 2 methods plus **`network.connections`**, 1 method):
+  `connections.list`, `syncStatus`, `resync`. The stored LinkedIn Connections
+  of your accounts, read with no LinkedIn call and no limit used; `account_id`
+  takes several accounts. `resync` re-reads one account's Connections, once
+  per account per 24 hours.
+- **`unibox`** (root, 6 methods plus **`unibox.accounts`**, 2 methods):
+  `list`, `get`, `unreadCount`, `refresh`, `tagContact`, `enroll`,
+  `accounts.list`, `accounts.update`. One inbox over every account you can
+  operate, from what Curviate stores; `accounts.update` turns full-inbox sync
+  on or off for an account. Messages and chat actions stay on `messaging`.
+- **`analytics`** (root, 1 method plus **`analytics.motions`**, 2 methods,
+  and **`analytics.events`**, 1 method): `activity`, `motions.list`,
+  `motions.get`, `events.list`. Read-only, any Tier.
+- **List iterators**: `network.connections.list`, `unibox.list` and
+  `analytics.events.list` resolve to their first page when awaited and yield
+  every item across pages under `for await` (type `Pageable`).
+- **`BudgetRow`** type: the budget rows, `connections_sync` and `inbox_sync`
+  included.
+- **Needs Automate** in the JSDoc of `network.resync`, `unibox.refresh`,
+  `unibox.tagContact`, `unibox.enroll` and `unibox.accounts.update` (turning
+  full-inbox sync on; off passes on any Tier).
+- **Error code** `CLIENT_TIMEOUT`: no response within the client's `timeout`.
+  Before, it was `INTERNAL` ("Request timed out."), which read like a server
+  fault. A read is retried first; a write is not, may still have reached the
+  API, and carries `retryLikelyToSucceed: false` so a generic retry loop
+  does not resend it. A network failure with no response stays `INTERNAL`.
+
+- **Offline Sequence module** (no network, key or file system; TypeScript 5.0
+  or later): `Sequence` (an immutable builder: `create`, `add`,
+  `insertBefore`, `replace`, `remove`, `onReply`, `validate`, `toDocument`,
+  `fromDocument`), `step` (one constructor per step kind: `do`, `wait`,
+  `until`, `if`, `emit`, `tag`), `validateSequence` and the published JSON
+  Schema `SEQUENCE_SCHEMA_V1` with `SEQUENCE_SCHEMA_URL`. The builder emits
+  exactly the Sequence document a Motion runs, keys in one canonical order, so
+  diffs show only real changes; `fromDocument` loads a fetched document and
+  re-emits it unchanged. With literal arguments a typo'd action, event,
+  reaction or predicate, a `{{...}}` that is not a v1 variable, a text with a
+  variable and no fallback, a malformed duration and a jump to a step you never
+  added fail to compile. `validateSequence` and `toDocument()` give the API's
+  own verdict offline: every error as `{path, rule}`, in step order, and the
+  warnings (`W1`, `W5` to `W9`). A document using an action or event added to
+  the API after this release is refused offline while the API accepts it:
+  upgrade the SDK. Not on the client: no request is ever sent. Like the API,
+  the first 100 errors are listed (the message counts all), an oversized
+  document gets the size error alone, and a NUL or lone surrogate in any
+  string is refused (`toDocument()` throws `INVALID_REQUEST`, as the API's 400).
+- **`CurviateError.errors`**: every failure as `{path, rule}` on a refusal that
+  lists them (`SEQUENCE_INVALID`, `MOTION_NOT_STARTABLE`), decoded from the
+  response's `errors[]` and emitted by `toJSON()`. The offline `SEQUENCE_INVALID`
+  a builder throws carries the same list.
+- **Error code** `SEQUENCE_INVALID` (422): the Sequence document breaks one or
+  more rules; nothing is saved.
+
+- **`contacts`** (root, 9 methods): `list`, `get`, `upsert`, `update`,
+  `delete`, `deleteMany`, `updateMany`, `enrich`, `export`, plus
+  **`contacts.imports`** (4 methods): `create`, `get`, `list`, `rows`. Your
+  team's Contacts: a LinkedIn URL plus your own fields, Tags and list
+  memberships; any spelling of one person's URL resolves to one Contact, so
+  `upsert` creates or updates and reports `outcome`. `updateMany` adds or
+  removes Tags and list memberships on up to 1,000 Contacts. `enrich` fills
+  profile fields from what Curviate stores, else queues paced live profile
+  views (a real view the person may see). `export` returns the whole matching
+  set in one download: `format: "json"` resolves with the Contact array, `csv`
+  and `ndjson` (default) with the raw bytes. Imports take `rows` or a `csv`
+  string, up to 10,000 rows; up to 500 run inline, larger ones in the
+  background (poll `imports.get`, read the report with `imports.rows`).
+  `list` and `export` send an `enrollment_status` array as the one comma
+  list the API reads.
+- **`contactLists`** (root, 5 methods): `create`, `list`, `get`, `update`,
+  `delete`. Static lists; membership changes go through
+  `contacts.updateMany` (`add_list_id`, `remove_list_id`).
+- **`tags`** (root, 3 methods): `list`, `update` (rename), `delete`. No create
+  call: a write that names a new Tag creates it.
+- **Error codes** for Contacts, lists and Tags: `NAME_TAKEN` (409),
+  `RESOURCE_IN_USE` (409, a live Motion or running import uses the list or
+  Tag), `CONTACT_LIMIT_REACHED` (422), `IMPORT_QUEUE_FULL` (429).
+- **`motions`** (root, 13 methods): `create`, `list`, `get`, `update`,
+  `delete`, `start`, `pause`, `resume`, `archive`, `preview`,
+  `getSequenceVersion`, `addContacts`, `removeContacts`. `sequence` in
+  `create` and `update` takes a `Sequence` builder besides a document: the
+  builder is converted with `toDocument()` first, so an invalid one rejects
+  with `SEQUENCE_INVALID` and nothing is sent, and one with a jump to a step
+  never added does not compile. A plain object is sent as is (the API
+  validates it); `null` clears a draft's Sequence. `preview` is a read: it
+  never reaches LinkedIn.
+- **`enrollments`** (root, 5 methods): `list`, `get` (with the Step
+  history), `stop`, `resume` (`at` a Step), `signal`.
+- **Error codes** for Motions: `MOTION_NOT_STARTABLE` (422, every gap in
+  `errors`), `MOTION_STATUS_CONFLICT` (409), `ENROLLMENT_NOT_ACTIVE` (409),
+  `CONTACT_NOT_ENROLLABLE` (422).
+
+- **`tier`** (root, 1 method): `get` reads `GET /v1/billing/tier`: the Tier the
+  team has now (`null` for none), the bought Tier, `period`, the free `trial`,
+  a granted `override`, a downgrade `pending` for the next renewal, the
+  `features` it includes and `early_access` per announced Tier. No prices.
+- **`TIER_REQUIRED` details** on `CurviateError`: `feature`, `requiredTier`,
+  `currentTier` (both `null` when no Tier has the feature / the team has none)
+  and `upgradeUrl` (team Owners only), decoded from the 403 and emitted by
+  `toJSON()`. Writes in Drafts, Contacts, Motions (and later Network and
+  Unibox) on a team below Automate are refused with it; reads, exports,
+  deletes and stopping running work pass. The "Needs Automate" note is now in
+  the JSDoc of the 19 gated write methods: `drafts.create`, `update`,
+  `publish`, `uploadAttachment`; `contacts.upsert`, `update`, `updateMany`,
+  `enrich`, `imports.create`; `contactLists.create`, `update`; `tags.update`;
+  `motions.create`, `update`, `start`, `resume`, `addContacts`;
+  `enrollments.resume`, `signal`.
+- **`tier_required`** is a member of the Motion `pause_reason`, the sync
+  `paused_reason` and the Contact enrichment `failure_code` types, and the
+  reason a `motion.status_changed` event carries when the team loses the Tier.
+
+- **Unibox types** (no SDK method yet): `POST
+  /v1/unibox/chats/{account_id}/{chat_id}/contact` and `.../enrollments`, and
+  the typed `motion_context` on Unibox chats (was an empty object type).
+
+- **`notifications` at the root** (4 methods): `list`, `unreadCount`,
+  `update`, `markAllRead`. Curviate's own Notifications for you in this team
+  (an account needs reconnecting, a Motion paused, an import finished, a
+  teammate joined or left), with per-person read and archived state. Check
+  `unreadCount()` at session start. `curviate.account(id).notifications` is
+  unchanged and still means the account's LinkedIn notifications: the same key
+  now carries a different class at each scope.
+- **`connectRequests`** (root, 3 methods): `create`, `get`, `cancel`
+  (`/v1/auth/connect-requests`). The credential-free way for an agent to get an
+  account connected or reconnected: create one, relay its `url` to the person,
+  poll `get` until `status` leaves `pending`. Your code never handles a
+  LinkedIn password, cookie or code. `create` is not retry-safe: a retry makes
+  a second request.
+- **`teams`** (root, 10 methods): `list`, `getCurrent`, `updateCurrent`,
+  `listMembers`, `updateMember`, `removeMember` (`"me"` leaves the team),
+  `createInvites`, `listInvites`, `resendInvite`, `revokeInvite`.
+- **`accounts.setTeamAccess(accountId, teamAccess)`**
+  (`PUT /v1/accounts/{account_id}/team-access`): opt an account you connected
+  out of team use, or share it again.
+- **`team` client option**, sent as `X-Curviate-Team`: the team a dashboard
+  session token acts in. An API key acts only in the team it was created in;
+  leave `team` unset with one. An empty `team` throws `INVALID_REQUEST` at
+  construction.
+- **Error codes** that decoded to `INTERNAL` until now: `TEAM_ACCESS_DENIED`,
+  `ACCOUNT_NOT_SHARED`, `ACCOUNT_OWNER_ONLY`, `LAST_OWNER`,
+  `BILLING_OWNER_REQUIRED`, `DEFAULT_TEAM_PROTECTED`, `ALREADY_MEMBER`,
+  `INVITE_ALREADY_PENDING`, `INVITE_NOT_PENDING`, `INVITE_LIMIT_REACHED`,
+  `CONNECT_REQUEST_NOT_PENDING`, `CONNECT_REQUEST_IN_USE`,
+  `LINKEDIN_ACCOUNT_MISMATCH`.
+
+- **`activity_window.effective_timezone` and `activity_window.source`** on the
+  account object (`accounts.get`, `accounts.update`) and on the per-account
+  safety policy (`GET`/`PATCH /v1/{account_id}/safety-policy`, types only: the
+  SDK has no safety-policy method). `effective_timezone` is the IANA zone the activity window is
+  read in; `source` is `account`, `browser`, `location` or `default`.
+
+### Changed
+
+- **Connect request types**: every field of the object `connectRequests`
+  returns is required (`id`, `url`, `status`, ...), so `req.id` needs no `!`.
+- **Contacts export types**: the `csv` and `json` response media types are
+  typed beside `ndjson`.
+
+- **`SequenceDocument` type**: `post`, `newer_than` and `reaction` in a
+  `post.react` or `post.comment` step's `with` are optional (the API applies
+  their defaults), and a `contact.extra.<key>` predicate compiles. Before, a
+  valid document omitting them, or using one, did not type-check.
+
+- **The activity window applies to every account, with or without a
+  `timezone`.** It is no longer switched off when no zone is set: the zone is
+  the one you set, else the one the user's browser reported, else one inferred
+  from the LinkedIn profile location when it maps to one zone, else
+  `Europe/Berlin`. `timezone` and `timezone_unset` keep their meaning: what you
+  set. Behavior change on the server: under `enforce` an account with no
+  `timezone` is now refused outside 07:00 to 22:00 in its effective zone
+  (`BUDGET_EXHAUSTED`, `safetyReason: "activity_window"`), where before nothing
+  was refused. Description changes only on the generated types.
+- Types regenerated from the staging document also include server changes that
+  were not in the previous fixture: the contacts, tags, contact lists, Motions,
+  enrollments, unibox, notifications, network sync and billing tier paths; new
+  `Error` fields and `reason` values; `owner_user_id` and `team_access` on the
+  account object. Types only, except notifications, teams and team access
+  (Added above).
+- **An API key is one person's key in one team**, no longer one key per
+  workspace: it acts as the person who created it, with their role in that
+  team. `owner_user_id` on the account object is the person who connected it;
+  `team_access: false` means only they can use it.
+- **`auth_method` on the account object** is the method of the last successful
+  connect or reconnect (`credentials`, `cookie` or `hosted`), not the method
+  of the first connect.
+- **Two drift fixes the regen forced** (the SDK's own pins went red against the
+  new document): the seven `motion` webhook events (`motion.status_changed`,
+  `enrollment.started`, `enrollment.skipped`, `enrollment.finished`,
+  `step.executed`, `step.failed`, `motion.signal`) join `CurviateEvent` with a
+  loose `MotionPayload` (`motion_id`, `account_id` nullable), and the error
+  codes `INSUFFICIENT_ROLE` and `TIER_REQUIRED` join `ERROR_CODES` instead of
+  decoding to `INTERNAL`.
+
+### Fixed
+
+- **`jobs.get` `with_sections`** goes as one comma value. Several sections
+  were sent as a repeated key, of which the API keeps only the last.
+- **Package size**: the tarball no longer ships `src/generated/types.ts`. The
+  same types are in `dist/index.d.ts`, and `paths`, `components` and
+  `operations` are exported from the package root; the file was not
+  importable through the package's `exports` anyway.
+- **`motions.preview` `sample` and `motions.getSequenceVersion` `version`**
+  are typed as numbers, as the API reads them.
+- **An empty array in a comma-list filter is no filter.** `status: []`
+  (`drafts.list`, `motions.list`, `enrollments.list`), `enrollment_status: []`
+  (`contacts.list`, `contacts.export`) and `contact_ids: []`
+  (`motions.preview`) leave the parameter out instead of sending it empty,
+  which the API refused.
+
+## [0.42.0] - 2026-10-07
+
+Fixture and types regenerated from the server integration branch (134 paths,
+server `b1c443c6a3a0e1c2a09944be39f01c6921fca46c`), **not** from a deployed
+document: regenerate from deployed staging and confirm an empty diff before
+publishing.
+
+### Added
+
+- **`drafts` resource** (root-scoped, 7 methods): `create`, `list`, `get`,
+  `update`, `delete`, `publish`, `uploadAttachment`. A Draft is a stored,
+  editable post that Curviate publishes at `scheduled_at` (ISO 8601 with
+  offset, passed through unchanged). `list` takes `status` as an array and
+  sends it as the API's comma list; `status: ["published"]` returns publish
+  records. `uploadAttachment(id, data, { filename, contentType })` sends a
+  file (an MP4 video or PDF up to 50 MiB; an image is capped at 5 MiB) as the raw request body.
+  `delete` resolves with `undefined` (204). (`posts.delete` and `comments.delete`
+  still hand back the transport's empty buffer under a `void` type; unchanged here.)
+- **Six new error codes** decode to themselves instead of `INTERNAL`:
+  `DRAFT_LIMIT_REACHED`, `MEDIA_QUOTA_EXCEEDED`, `ACCOUNT_REQUIRED`,
+  `DRAFT_NOT_PUBLISHABLE`, `SCHEDULE_CONFLICT`, `DRAFT_PUBLISHING`.
+- **`post.published` and `post.publish_failed` webhook events** join
+  `CurviateEvent` (`PostPublishedPayload`, `PostPublishFailedPayload`).
+  Payloads carry ids and times, never post text or media.
+- `Draft*` request and result types are exported.
+
+### Changed
+
+- The webhook `source` enum includes `post`, from the regenerated types.
 
 ## [0.41.0] - 2026-10-03
 

package/README.md

@@ -33,20 +33,40 @@ const curviate = new Curviate({
 });
 ```
 
+An API key belongs to one person in one team and acts with that person's role there. `curviate.teams.getCurrent()` says which team and role. A dashboard session token may act in any team you belong to: pick one with `team: "tnt_..."` (sent as `X-Curviate-Team`). Leave `team` unset with an API key; naming another team is refused with `TEAM_ACCESS_DENIED`.
+
 ---
 
-## Account-scoped accessor
+## Connecting an account
+
+Every LinkedIn operation (messages, member profiles, invites, posts) is tied to a **managed account**, a LinkedIn session connected to Curviate.
 
-Every LinkedIn operation (messages, member profiles, invites, posts) is tied to a **managed account**, a LinkedIn session you have connected via the connect flow (`curviate.auth.intent()`). A new connect names where LinkedIn sees the account connecting from, with exactly one of `country` (e.g. `"US"`), `ip` or your own `proxy`:
+**Agents: use a connect request.** Your code never handles a LinkedIn password, cookie or verification code, so never ask for one. Create a request, give its `url` to the person, and they connect in their own Curviate dashboard:
+
+```ts
+const req = await curviate.connectRequests.create();             // new account
+// const req = await curviate.connectRequests.create({ account_id: "acc_123" }); // reconnect
+console.log(`Connect your LinkedIn account here: ${req.url}`);
+
+// Poll until it leaves `pending`: completed, expired (15 minutes), failed or cancelled.
+const done = await curviate.connectRequests.get(req.id);
+if (done.status === "completed") console.log(done.account_id);
+```
+
+`create` is not retry-safe: a retry makes a second request. A pending request can be withdrawn with `connectRequests.cancel(id)`.
+
+**Your own app, with the person's credentials in hand:** `curviate.auth.intent()`. A new connect names where LinkedIn sees the account connecting from, with exactly one of `country` (e.g. `"US"`), `ip` or your own `proxy`:
 
 ```ts
 await curviate.auth.intent({ seat_id, auth_method: "credentials", credentials: { email, password }, country: "US" });
 ```
 
+## Account-scoped accessor
+
 The `curviate.account(id)` accessor fixes the `account_id` on every call so you do not have to thread it manually:
 
 ```ts
-// Root-level: tenant-wide operations (accounts, auth, webhooks)
+// Root-level: team-wide operations (accounts, auth, connectRequests, webhooks, drafts, teams, notifications)
 const { items: accounts } = await curviate.accounts.list();
 
 // Account-scoped: all LinkedIn ops under a specific account
@@ -58,6 +78,186 @@ const me = await acc.users.get("me");           // your own profile
 const profile = await acc.users.get("some-user-id"); // someone else's
 ```
 
+## Notifications
+
+`curviate.notifications` is Curviate telling you something needs attention: an account needs reconnecting, a Motion paused, an import finished, a teammate joined or left. Each person has their own list and read state. Check it at session start:
+
+```ts
+const { unread_count } = await curviate.notifications.unreadCount();
+if (unread_count > 0) {
+  const { items } = await curviate.notifications.list({ filter: "unread" });
+  for (const n of items) console.log(n.type, n.title);
+  // Mark only what you saw: one that arrived since the list stays unread.
+  await curviate.notifications.markAllRead({ before: items[0]!.created_at });
+}
+```
+
+`type` is an open list: tolerate values you do not know. `curviate.account(id).notifications` is something else: that account's LinkedIn notifications.
+
+## Teams
+
+`curviate.teams` manages the team the credential acts in: `getCurrent`, `updateCurrent`, `listMembers`, `updateMember` (role), `removeMember` (`"me"` leaves), `createInvites`, `listInvites`, `resendInvite`, `revokeInvite`, plus `list` for every team you belong to. Member and invite writes are for Owners (`INSUFFICIENT_ROLE` otherwise). `curviate.accounts.setTeamAccess(accountId, false)` keeps an account you connected to yourself.
+
+## Tiers
+
+A Team's Tier decides which features it has. Drafts, Contacts, Motions (and Network and Unibox) need Automate: a write in one of those groups on a Team below it is refused with `TIER_REQUIRED`, before the request is even validated. Reads, exports, deletes and stopping running work (`motions.pause`, `motions.archive`, `enrollments.stop`) pass on any Tier. The refusal names what is missing:
+
+```ts
+try {
+  await curviate.motions.start("mot_123");
+} catch (err) {
+  if (isCurviateError(err) && err.code === "TIER_REQUIRED") {
+    console.warn(`${err.feature} needs ${err.requiredTier}; this team has ${err.currentTier ?? "no Tier"}.`);
+    // A team Owner also gets err.upgradeUrl; any other role has none and should ask an Owner.
+  }
+}
+
+const { tier, features } = await curviate.tier.get(); // check first: no write is sent
+```
+
+`curviate.tier.get()` returns the Tier now (`null` for none), the bought Tier, the free trial or granted Tier that raises it, a downgrade due at the next renewal (`pending`), and the `features` it includes. It reports no prices. A Motion or a sync that stopped for the Tier reads `pause_reason` / `paused_reason: "tier_required"`.
+
+## Contacts, lists and Tags
+
+`curviate.contacts` keeps the people your team works with: a LinkedIn URL plus your own fields, Tags and Contact lists. Any spelling of one person's URL resolves to one Contact, so `upsert` is safe to repeat:
+
+```ts
+const { id, outcome } = await curviate.contacts.upsert({
+  linkedin_url: "https://www.linkedin.com/in/ana/",
+  job_title: "CTO",
+  tags: ["warm"],
+  list_name: "Q4 webinar", // created if new
+});
+
+// Bulk: rows or a CSV string, up to 10,000 rows. Over 500 runs in the background.
+const csv = await readFile("leads.csv", "utf8"); // node:fs/promises
+const imp = await curviate.contacts.imports.create({ csv, list_name: "Q4 webinar" });
+// Once `status` is `completed` (poll `imports.get` for a background import):
+const { items: skipped } = await curviate.contacts.imports.rows(imp.id, { outcome: "skipped" });
+
+await curviate.contacts.updateMany({ contact_ids: [id], add_tags: ["vip"] });
+const all = await curviate.contacts.export({ format: "json", tag: "vip" });
+```
+
+`contacts.enrich` fills profile fields from what Curviate already stores, else queues paced live profile views from an account you name: a live view is a real profile view the person may see. `curviate.contactLists` and `curviate.tags` rename and delete; a Tag has no create call, the first write naming it creates it. Refusals: `NAME_TAKEN`, `RESOURCE_IN_USE` (a live Motion or a running import uses it), `CONTACT_LIMIT_REACHED`, `IMPORT_QUEUE_FULL`. Deletes are for Owners and Managers.
+
+## Sequences
+
+A Motion runs one Sequence: a JSON document of steps (`do`, `wait`, `until`, `if`, `emit`, `tag`), run from the first step and ended explicitly with `"end"`. The SDK has an offline module for it: a typed builder that emits exactly that document, and `validateSequence`, which gives the verdict the API gives. Nothing in it touches the network, a key or the file system, so it runs in CI, browsers and edge functions. It needs TypeScript 5.0 or later.
+
+```ts
+import { Sequence, step } from "@curviate/sdk";
+
+const seq = Sequence.create({ on_reply: "end" }).add(
+  step.do("invite", "invite.send", { with: { note: null, withdraw_after: "21d" } }),
+  step.until("accepted", "invite.accepted", { timeout: "21d", then: "opener", else: "end" }),
+  step.do("opener", "message.send", {
+    with: { text: "Hi {{contact.first_name}}, thanks for connecting.", fallback: "Hi, thanks for connecting." },
+    next: "end",
+  }),
+);
+
+const document = seq.toDocument(); // the Sequence document, keys in canonical order
+```
+
+Field names are the document's keys (`on_reply`, `note_fallback`, `withdraw_after`). With literal arguments, the type checker refuses what the API would: a typo'd action, event, reaction or predicate, a `{{...}}` that is not a v1 variable (`{{firstName}}`, a `| default:` filter), a text with a variable and no fallback, a duration like `"1w"`, the reserved id `"end"`, and a jump to a step you never added (at `toDocument()`). Text the type checker cannot see (a `string` variable) is checked when you call `validate()` or `toDocument()`.
+
+Every builder operation (`add`, `insertBefore`, `replace`, `remove`, `onReply`) returns a new builder. `toDocument()` throws `SEQUENCE_INVALID` with every error in `err.errors` as `{path, rule}`, the same list the API returns; warnings never block, read them with `validate()`. `JSON.stringify(seq)` equals `JSON.stringify(seq.toDocument())`.
+
+Raw JSON stays first class. Validate a document you wrote by hand, or load one (a Motion's `sequence`) to edit it:
+
+```ts
+import { Sequence, step, validateSequence } from "@curviate/sdk";
+
+const { errors, warnings } = validateSequence(JSON.parse(text));
+for (const e of errors) console.error(`${e.path}: ${e.rule}`);
+
+const edited = Sequence.fromDocument(motion.sequence) // throws SEQUENCE_INVALID when invalid
+  .insertBefore("opener", step.wait("settle", "1d"))
+  .toDocument();
+```
+
+`{{motion.<key>}}` is warning `W9` offline: only the API knows the Motion's `settings.variables`. Warnings that need the Motion's sending accounts or settings come from the API only. `SEQUENCE_SCHEMA_V1` is the published JSON Schema (`SEQUENCE_SCHEMA_URL`) for editors and tooling. The validator knows the vocabulary of the schema it ships with: a document using an action or event added to the API later is refused offline while the API accepts it; upgrade the SDK.
+
+## Motions and Enrollments
+
+A Motion runs one Sequence for the Contacts of its Contact lists, on its sending accounts, inside its schedule. `sequence` in `motions.create` and `motions.update` takes a builder or a document:
+
+```ts
+import { Sequence, step } from "@curviate/sdk";
+
+const motion = await curviate.motions.create({
+  name: "Q4 webinar follow-up",
+  contact_list_ids: ["cl_123"],
+  account_ids: ["acc_123"],
+  schedule: { timezone: "Europe/Berlin" },
+  sequence: seq, // a builder: converted with toDocument(); an invalid one throws SEQUENCE_INVALID, nothing is sent
+});
+
+const { paths, samples, projection } = await curviate.motions.preview(motion.id); // a read: nothing is sent to LinkedIn
+await curviate.motions.start(motion.id);
+
+// Edit later: load the stored document into a builder.
+const current = await curviate.motions.get(motion.id);
+await curviate.motions.update(motion.id, {
+  sequence: Sequence.fromDocument(current.sequence).insertBefore("opener", step.wait("settle", "1d")),
+});
+```
+
+A plain object goes as is and the API validates it; wrap hand-written JSON in `Sequence.fromDocument(json)` to have it checked offline first. `sequence: null` clears a draft's. Status operations: `start`, `pause`, `resume`, `archive` (irreversible), `delete` (drafts only); `addContacts` / `removeContacts` enroll or take out Contacts directly; `getSequenceVersion` reads a past version. `curviate.enrollments` lists one Contact's run per account (`list`, `get` with its Step history) and acts on it: `stop`, `resume({ at })`, `signal({ name })`. Refusals: `MOTION_NOT_STARTABLE` (every gap in `err.errors`), `MOTION_STATUS_CONFLICT`, `ENROLLMENT_NOT_ACTIVE`, `SEQUENCE_INVALID`.
+
+## Network, Unibox and Analytics
+
+Reads here come from what Curviate has stored: no LinkedIn call, no limit used. Lists with a cursor resolve to their first page when awaited and yield every item across pages under `for await`:
+
+```ts
+// Stored Connections of several accounts; read coverage before trusting an empty page.
+const { items, coverage } = await curviate.network.connections.list({ account_id: ["acc_1", "acc_2"] });
+for await (const c of curviate.network.connections.list({ q: "founder" })) console.log(c.public_profile_url);
+const { items: sync } = await curviate.network.syncStatus();
+await curviate.network.resync({ account_id: "acc_1" }); // once per account per 24 h
+
+// One inbox over every account you can operate.
+for await (const chat of curviate.unibox.list({ unread: true })) console.log(chat.chat_id);
+const { unread_chats } = await curviate.unibox.unreadCount();
+await curviate.unibox.accounts.update("acc_1", { sync_full_inbox: true }); // by the person who connected it
+await curviate.unibox.refresh();
+await curviate.unibox.tagContact("acc_1", "chat_1", { tags: ["warm"] });
+await curviate.unibox.enroll("acc_1", "chat_1", { motion_id: "mot_1" });
+
+// Motion results, activity in budget units, the events feed.
+const overview = await curviate.analytics.motions.list({ from: "2026-10-01", to: "2026-10-31" });
+const detail = await curviate.analytics.motions.get("mot_1");
+const { types } = await curviate.analytics.activity(); // per BudgetRow; never add rows together
+for await (const event of curviate.analytics.events.list({ kind: ["message.replied"] })) console.log(event.motion_name);
+```
+
+Needs Automate: `network.resync`, `unibox.refresh`, `unibox.tagContact`, `unibox.enroll` and turning full-inbox sync on (off passes on any Tier). Messages and actions on a chat stay on `curviate.account(id).messaging`.
+
+## Drafts and scheduled posts
+
+A Draft is a stored, editable, unpublished post. Give it an account and a `scheduled_at` and Curviate publishes it at that time. Drafts are tenant-wide, so `drafts` hangs off the root client (a Draft's `account_id` is a field, and optional). `acc.posts.create()` still publishes immediately and does not schedule.
+
+```ts
+const draft = await curviate.drafts.create({
+  account_id: "acc_...",
+  text: "Three things we learned shipping our first agent integration.",
+  scheduled_at: "2026-10-12T09:00:00+02:00", // ISO 8601 with offset; 5 min to 365 days ahead
+});
+
+// A video or PDF (up to 50 MiB) goes up as the raw body; images (up to 5 MiB) can ride inline as base64.
+await curviate.drafts.uploadAttachment(draft.id, await readFile("clip.mp4"), {
+  filename: "clip.mp4",
+  contentType: "video/mp4",
+});
+
+await curviate.drafts.update(draft.id, { scheduled_at: null }); // unschedule
+const { id: postId } = await curviate.drafts.publish(draft.id); // or publish now
+const { items } = await curviate.drafts.list({ status: ["scheduled", "published"] });
+```
+
+Refusals carry their own codes: `DRAFT_LIMIT_REACHED`, `MEDIA_QUOTA_EXCEEDED`, `ACCOUNT_REQUIRED`, `DRAFT_NOT_PUBLISHABLE`, `SCHEDULE_CONFLICT` and `DRAFT_PUBLISHING`. A scheduled publish that fails raises the `post.publish_failed` webhook (`post.published` on success); a `failure_code` of `outcome_unknown` means the post may be live, so check the account's posts before retrying.
+
 ---
 
 ## First end-to-end call
@@ -126,6 +326,11 @@ try {
       console.warn(`${err.budgetRow} is spent until ${err.resetAt ?? "no fixed time"}`);
       console.warn(`change ${err.safetyHint?.parameter} to lift it`);
       break;
+    case "TIER_REQUIRED":
+      // The team's Tier lacks err.feature; err.requiredTier has it. A team
+      // Owner also gets err.upgradeUrl. See "Tiers" above.
+      console.warn(`${err.feature} needs ${err.requiredTier}`);
+      break;
     case "ACCOUNT_NOT_FOUND":
       console.error("Account does not exist for this tenant.");
       break;
@@ -145,6 +350,8 @@ try {
 }
 ```
 
+No response within the client's `timeout` throws `CLIENT_TIMEOUT` (not `INTERNAL`): a read is retried first and carries `retryLikelyToSucceed: true`; a write is not retried, carries `false`, and may still have reached the API, so read back before resending. A network failure with no response is `INTERNAL` with no `httpStatus`.
+
 Every error code is documented in the [API reference](https://docs.curviate.com). The
 exported `ErrorCode` type is the complete set, so `tsc` tells you when a `switch` over
 `err.code` has missed one.
@@ -284,7 +491,7 @@ may fetch.
 
 ## Cursor pagination
 
-Resources that return lists support cursor pagination. `curviate.paginate()` is an async iterator that follows the `cursor` field automatically, so you pull items one at a time without managing cursors:
+`network.connections.list`, `unibox.list` and `analytics.events.list` iterate themselves (`for await (const x of curviate.unibox.list())`). For the other lists, `curviate.paginate()` is an async iterator that follows the `cursor` field automatically, so you pull items one at a time without managing cursors:
 
 ```ts
 // Iterate over every chat across all pages