@graph8/sdk 0.245.0 → 0.260.0

package/docs/agents.md

@@ -0,0 +1,748 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from sdk/js/agent-docs/guide.md, the recipes and the contract. Regenerated on every build. -->
+
+# `@graph8/sdk`: guide for AI coding agents
+
+You are probably an AI coding agent (Claude Code, Codex, Cursor, Copilot) asked to build something on graph8.
+This file is the fastest way to use this SDK correctly. It ships inside the package, so it matches the
+version installed in `node_modules/@graph8/sdk`. Trust it over anything you remember about graph8: the API
+grows every week and your training data is older than this file.
+
+graph8 is a B2B go-to-market platform: CRM (contacts, companies, deals, custom objects), a 700M-person
+data index with enrichment, intent signals, sequences and campaigns across email/SMS/LinkedIn/voice, a unified
+inbox, meetings, workflows and more. This SDK reaches all of it: **3252 Developer API
+operations** in 141 areas.
+
+## 1. The short version
+
+1. **Server-side code uses an API key, browser code uses a write key.** `g8.init({ apiKey })` on a server,
+   `g8.init({ writeKey })` in a browser. Never put an API key in front-end code.
+2. **Use a hand-written client when one exists** (`g8.contacts`, `g8.deals`, `g8.sequences`, ...). They
+   unwrap the response envelope and take friendly arguments. 289 methods, listed in
+   [sdk-clients.md](sdk-clients.md).
+3. **Everything else is `g8.api.<namespace>.<member>(input)`**, generated from the API contract, so every
+   operation exists there. Find it in [api/README.md](api/README.md) (by area) or
+   [api/by-path.md](api/by-path.md) (by REST path). `g8.api` returns the raw `{ data, ... }` envelope.
+4. **Do not guess.** Method names, field names and ids come from these docs, the TypeScript types, or a
+   previous API response. If the docs do not list it, it does not exist. Search again (section 5) before
+   telling the user graph8 cannot do something.
+5. **Ask a human before anything `external`, `billable` or `destructive`** (sends messages, spends credits,
+   deletes data). Every operation's tier is in its reference entry and in `g8.api.operation(id).tier`.
+6. **Let the SDK retry.** It already retries rate limits, 5xx and network errors, with idempotency keys on
+   writes. Do not add your own retry loop around it.
+
+**Setting up a project for agents?** `npx @graph8/sdk init-agent` writes a Claude Code skill
+(`.claude/skills/graph8-sdk/SKILL.md`), an `AGENTS.md` section (Codex, Cursor, Copilot) and a Cursor rule that
+point future sessions at this guide. It is idempotent and never touches the user's own `AGENTS.md` text.
+
+## 2. What is in this package
+
+```
+node_modules/@graph8/sdk/
+  README.md              human overview and quick start
+  docs/agents.md         this guide
+  docs/sdk-clients.md    every hand-written method: signature, JSDoc, and the REST call behind it
+  docs/api/README.md     index of the g8.api namespaces, with operation counts
+  docs/api/by-path.md    "POST /api/v1/contacts" -> the SDK call, for every route
+  docs/api/<ns>.md       one page per area: every operation's input, output and an example
+  docs/api/<ns>.d.ts     that area's exact TypeScript types, self-contained (small: read it)
+  dist/types/<module>.d.ts  one hand-written client's types, e.g. dist/types/contacts.d.ts
+  dist/index.d.ts        the bundled types the compiler uses (large: search it, do not read it whole)
+```
+
+Search the docs directly. Some good searches:
+
+```bash
+grep -n "upsert" node_modules/@graph8/sdk/docs/sdk-clients.md
+grep -n "/sequences/" node_modules/@graph8/sdk/docs/api/by-path.md
+grep -rn "Enroll\|enroll" node_modules/@graph8/sdk/docs/api/ | head
+ls node_modules/@graph8/sdk/docs/api/
+```
+
+## 3. Setup and credentials
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+// Server: API key from app.graph8.com, Settings > MCP & API > API.
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+| Credential | Where | Unlocks |
+|---|---|---|
+| **Write key** | browser, safe to expose | `g8.track/identify/page/reset`, `g8.visitors`, `g8.forms`, `g8.copilot`, `g8.chat`, `g8.calendar`, `g8.signals` |
+| **API key** | server only, secret | everything else, including all of `g8.api` |
+| **Both** | `g8.init({ writeKey, apiKey })` | full access (server-rendered apps) |
+
+- Accessing an API-key module without an API key throws immediately, naming the module.
+- API keys start `g8_live_` (real data) or `g8_test_` (tagged test mode; until the sandbox ships, treat test
+  keys as touching real data too).
+- **Scopes.** A key with no scopes has full access. A restricted key carries scopes like `contacts:read` or
+  `contacts:*`. Each operation's required scope is in its reference entry and in
+  `g8.api.operation(id).scope`. A missing scope returns `403`.
+- **Another environment.** `g8.init({ apiKey, apiUrl: "https://be.qa.graph8.com" })`. The default is
+  `https://be.graph8.com`.
+- **Agency keys** manage several client orgs. Send the header `X-Target-Org-Id: <org_id>` (every
+  `g8.api` input accepts `headers`) to act on one. Any other kind of key silently ignores the header and acts
+  on its own org. See the agency recipe below.
+- **Hosted graph8 apps** do not use API keys: `createGraph8AppClient` (browser) and
+  `createGraph8ServiceClient` (backend) exchange a short-lived app token. See the README's "App Platform".
+
+## 4. The two layers
+
+| | Hand-written clients | `g8.api` (generated) |
+|---|---|---|
+| Example | `g8.contacts.upsert({ list_id, work_email })` | `g8.api.assertUpsert.assertContact({ body: { list_id, work_email } })` |
+| Coverage | 289 methods, reaching 258 operations | all 3252 operations |
+| Returns | the unwrapped value (usually `data`) | the full envelope; read `result.data` |
+| Arguments | positional / friendly names | `{ path?, query?, headers?, body? }`, exactly as the contract names them |
+| Reference | [sdk-clients.md](sdk-clients.md) | [api/README.md](api/README.md) |
+
+Every entry in the `g8.api` reference marks the hand-written method that covers the same operation (★), so
+you can start from either side.
+
+Hand-written modules:
+
+| Module | Methods | Key |
+|---|---|---|
+| [`g8.agency`](sdk-clients.md#g8-agency) | 2 | API key |
+| [`g8.appPlatform`](sdk-clients.md#g8-appplatform) | 19 | API key |
+| [`g8.apps`](sdk-clients.md#g8-apps) | 7 | API key |
+| [`g8.audiences`](sdk-clients.md#g8-audiences) | 8 | API key |
+| [`g8.calendar`](sdk-clients.md#g8-calendar) | 5 | write key |
+| [`g8.campaigns`](sdk-clients.md#g8-campaigns) | 4 | API key |
+| [`g8.chat`](sdk-clients.md#g8-chat) | 5 | write key |
+| [`g8.companies`](sdk-clients.md#g8-companies) | 8 | API key |
+| [`g8.contacts`](sdk-clients.md#g8-contacts) | 10 | API key |
+| [`g8.copilot`](sdk-clients.md#g8-copilot) | 5 | write key |
+| [`g8.deals`](sdk-clients.md#g8-deals) | 8 | API key |
+| [`g8.enrich`](sdk-clients.md#g8-enrich) | 4 | API key |
+| [`g8.fields`](sdk-clients.md#g8-fields) | 5 | API key |
+| [`g8.forms`](sdk-clients.md#g8-forms) | 1 | write key |
+| [`g8.inbox`](sdk-clients.md#g8-inbox) | 6 | API key |
+| [`g8.intent`](sdk-clients.md#g8-intent) | 13 | API key |
+| [`g8.lists`](sdk-clients.md#g8-lists) | 6 | API key |
+| [`g8.mailboxes`](sdk-clients.md#g8-mailboxes) | 7 | API key |
+| [`g8.marketplace`](sdk-clients.md#g8-marketplace) | 5 | API key |
+| [`g8.meetings`](sdk-clients.md#g8-meetings) | 2 | API key |
+| [`g8.newsletter`](sdk-clients.md#g8-newsletter) | 15 | API key |
+| [`g8.notes`](sdk-clients.md#g8-notes) | 8 | API key |
+| [`g8.objects`](sdk-clients.md#g8-objects) | 18 | API key |
+| [`g8.pipelines`](sdk-clients.md#g8-pipelines) | 12 | API key |
+| [`g8.quotes`](sdk-clients.md#g8-quotes) | 12 | API key |
+| [`g8.search`](sdk-clients.md#g8-search) | 4 | API key |
+| [`g8.sequences`](sdk-clients.md#g8-sequences) | 13 | API key |
+| [`g8.signals`](sdk-clients.md#g8-signals) | 2 | write key |
+| [`g8.skills`](sdk-clients.md#g8-skills) | 14 | API key |
+| [`g8.snippet`](sdk-clients.md#g8-snippet) | 1 | API key |
+| [`g8.studio`](sdk-clients.md#g8-studio) | 11 | API key |
+| [`g8.tasks`](sdk-clients.md#g8-tasks) | 5 | API key |
+| [`g8.visitors`](sdk-clients.md#g8-visitors) | 3 | write key |
+| [`g8.voice`](sdk-clients.md#g8-voice) | 14 | API key |
+| [`g8.webhooks`](sdk-clients.md#g8-webhooks) | 1 | API key |
+| [`g8.workflows`](sdk-clients.md#g8-workflows) | 21 | API key |
+
+`g8.api` namespaces (operation counts): `accounts` (16), `adCampaigns` (19), `adCreatives` (40), `agency` (24), `agent` (8), `agents` (65), `aiInbox` (79), `analytics` (51), `apiKeys` (6), `appDeployments` (7), `appDomains` (5), `appLogs` (2), `appObjects` (10), `appPages` (16), `appPlatformTokens` (3), `appointments` (92), `apps` (22), `assertUpsert` (6), `audienceSyncs` (8), `brandKit` (30), `bugReports` (7), `calendarInvites` (3), `campaignWorkflows` (5), `campaigns` (29), `channels` (5), `cliCampaigns` (6), `cliPipelines` (12), `clickHouse` (2), `companies` (50), `companyIntelligence` (14), `contacts` (70), `content` (41), `contentGridSkills` (6), `copilot` (39), `crmSyncs` (6), `customerSuccess` (19), `deals` (48), `deliverability` (17), `desk` (71), `dialer` (46), `dialerAnalytics` (6), `documents` (35), `duplicates` (7), `eSign` (1), `eSignature` (7), `enrichment` (114), `events` (1), `fields` (8), `forms` (35), `gtmCampaigns` (22), `gtmContext` (51), `gtmDeliverability` (1), `gtmKnowledgeBase` (2), `gtmLaunchHelpers` (2), `gtmLibrary` (20), `health` (1), `imageLibrary` (14), `imports` (3), `inbox` (22), `install` (6), `installedApps` (4), `integrationStatus` (6), `integrations` (83), `intent` (16), `knowledge` (21), `knowledgeBase` (2), `landingPages` (59), `leads` (4), `library` (9), `linkedIn` (5), `linkedInOutreach` (20), `lists` (36), `logs` (1), `mailboxes` (38), `marketingIntelligence` (10), `marketplace` (142), `mcp` (1), `me` (1), `meetings` (17), `newsletter` (61), `notes` (19), `notifications` (2), `objects` (18), `openSearch` (4), `ops` (5), `orgGovernance` (17), `orgVideos` (6), `organizationSettings` (22), `phoneNumbers` (16), `profile` (14), `programmaticPages` (15), `providerDomains` (34), `providerUsage` (5), `public` (1), `publicCopilot` (1), `publicSignals` (1), `publicVisitors` (2), `quotes` (56), `radar` (42), `radarReports` (8), `recordRoles` (4), `repos` (4), `research` (13), `revenue` (14), `revenueAnalytics` (6), `revenueLifecycle` (5), `revenueRecords` (15), `roles` (20), `salesCoach` (37), `sandbox` (9), `scans` (2), `scheduleBuy` (9), `scraping` (10), `sdrAnalytics` (5), `search` (19), `seo` (11), `sequenceLifecycle` (8), `sequences` (71), `settings` (18), `signals` (56), `signatures` (24), `skills` (12), `snippet` (2), `socialPublishing` (22), `studioDocuments` (9), `support` (1), `suppressions` (6), `surveys` (21), `tasks` (25), `teamMembers` (21), `teams` (35), `usage` (9), `visitors` (26), `voice` (187), `webAnalytics` (38), `webChat` (46), `webhooks` (8), `websiteEditor` (12), `work` (59), `workbench` (107), `workflows` (59).
+
+## 5. How to find the right call
+
+1. **Know the area?** Open `docs/api/<namespace>.md`. Its table lists every operation with HTTP route, tier,
+   scope and summary.
+2. **Have a REST path** from a curl example, the web docs or an error? Look it up in
+   [api/by-path.md](api/by-path.md).
+3. **Have a task?** Grep for its verb and noun across `docs/api/` and `docs/sdk-clients.md` (`enroll`,
+   `transcript`, `booking`, `enrich`). Summaries and descriptions are included in full.
+4. **At runtime**, `g8.api.operations()` returns the whole catalogue: `{ id, method, path, tag, member,
+   tier, scope }` for every operation.
+5. **Types.** Open `docs/api/<namespace>.d.ts` for one area's exact types, or `dist/types/<module>.d.ts`
+   for a hand-written client. Inputs and outputs are fully typed. `ApiInput<"operation_id">` and `ApiOutput<"operation_id">`
+   name them, and contract schemas are under `import type { G8Contract } from "@graph8/sdk"`.
+
+If none of that finds it, graph8 does not publish it through the Developer API. Say so plainly, name the
+closest operation you did find, and do not invent an endpoint.
+
+## 6. Calling `g8.api`
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// Input is split by where each value goes on the wire. Each part is typed.
+const result = await g8.api.contacts.getContact({ path: { contact_id: 101 } });
+console.log(result.data);
+
+// Same operation by its frozen operationId.
+const same = await g8.api.call("get_contact_contacts__contact_id__get", { path: { contact_id: 101 } });
+void same;
+
+// Every item across every page (follows pagination.next_cursor).
+for await (const contact of g8.api.paginate("list_contacts_contacts_get", { query: { limit: 200 } })) {
+  console.log(contact);
+}
+
+// Per-call transport options go in the second argument.
+await g8.api.contacts.listContacts({ query: { limit: 10 } }, { maxRetries: 0 });
+```
+
+- `path`: every `{param}` in the route. A missing one throws before any request is sent.
+- `query`: filters, paging (`limit`, `cursor`, `page`, and sometimes `take`; the types say which).
+- `headers`: rarely needed (`X-Target-Org-Id` for agency keys).
+- `body`: the JSON request body.
+- The input argument is optional exactly when nothing in it is required.
+
+## 7. Safety: tiers, retries and idempotency
+
+Every operation carries a tier:
+
+| Tier | What it means | Count |
+|---|---|---|
+| `read` | reads data; safe to call and to retry | 1508 |
+| `write` | creates or changes records; the SDK sends an Idempotency-Key and retries transient failures | 811 |
+| `destructive` | deletes or archives data; confirm with a human before calling | 300 |
+| `billable` | spends credits; the SDK never blindly retries it; confirm cost before bulk use | 383 |
+| `external` | reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first | 250 |
+
+What the SDK does for you:
+
+- **Retries** 429, 5xx and network errors up to 2 more times (3 tries in total) with exponential backoff,
+  honouring `Retry-After`. Change it with `{ maxRetries }` in the call options.
+- **Idempotency.** Every write (POST/PUT/PATCH/DELETE) gets an auto-generated `Idempotency-Key` header
+  (unless `maxRetries` is 0), so the SDK's own retries cannot create duplicates. Pass `{ idempotencyKey }`
+  yourself (or the `idempotencyKey` argument some hand-written methods take) when YOUR code may repeat a
+  call, for example after a crash: on endpoints that support it, the server replays the first response for
+  24 hours instead of acting twice. Support is rolling out endpoint by endpoint; sending the header to one
+  that does not support it yet is harmless.
+- **Billable and external operations are never blindly retried.** They are retried only on 429, or when the
+  request provably never left the machine, because a retry could charge twice or message someone twice.
+
+What you must do:
+
+- Get a human's confirmation before calling an `external`, `billable` or `destructive` operation, and say
+  what it will do ("this sends the email to 240 contacts").
+- Keep bulk billable jobs small until the user confirms the cost (enrichment is 1 credit per lookup).
+
+## 8. Errors
+
+Every failure throws `G8Error` (exported from `@graph8/sdk`):
+
+| Field | Meaning |
+|---|---|
+| `status` | HTTP status (0 for a network error) |
+| `code` | machine code, for example `api_key_expired`; the status as a string when the API sends none |
+| `detail` | **the explanation.** Usually a string; on `422` a list of `{ loc, msg, type }` field errors |
+| `message` | the API's `message` when present, otherwise just `Request failed with status N` |
+| `requestId` | quote it to graph8 support |
+| `retryable` | the failure was transient and the SDK's own retries were exhausted |
+
+Most graph8 errors are FastAPI-style `{ "detail": ... }` with no `message`, so **always log
+`err.detail`**, not only `err.message`.
+
+| Status | Usual cause | Fix |
+|---|---|---|
+| 400 | missing or invalid field | read `detail`; fix the input |
+| 401 | key missing, invalid (`api_key_invalid`) or expired (`api_key_expired`) | rotate the key; do not retry |
+| 403 | key lacks the operation's scope | use a key with `g8.api.operation(id).scope` |
+| 404 | the id does not exist in this org | re-read the id from an API response |
+| 409 | duplicate (`contacts.create`), or a stale `expected_revision` | upsert instead, or reload and retry |
+| 422 | validation failed | `detail` lists each bad field |
+| 429 | rate limit | the SDK waits and retries; slow down bulk loops |
+
+## 9. Limits
+
+- **50 requests per second and 1,000 per minute, per org**, across the data API. Responses carry
+  `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
+- Use the largest page size an endpoint allows (commonly 100 to 200). One request, one rate-limit slot.
+- For per-contact lookups, prefer batch operations (for example `POST /api/v1/contacts/related`, up to 100
+  contact ids) over a request per contact.
+
+## 10. Recipes
+
+Complete, runnable programs for common tasks. Each one is type-checked against the SDK in CI, so the method
+names and fields are real.
+
+1. [Set up the client and check the key works](#recipe-setup-and-verify-key)
+2. [Create or update a contact](#recipe-upsert-contact)
+3. [Find and read contacts in the CRM](#recipe-find-contacts)
+4. [Prospect in the graph8 index, then save the people you want](#recipe-prospect-and-import)
+5. [Enrich one person or company](#recipe-enrich)
+6. [Create a list and manage its members](#recipe-lists)
+7. [Enroll contacts in a sequence](#recipe-add-to-sequence)
+8. [Create and launch a campaign](#recipe-campaign)
+9. [Create a deal and move it through the pipeline](#recipe-deals)
+10. [Log a note and create a follow-up task on a contact](#recipe-tasks-and-notes)
+11. [Triage the unified inbox and send a reply](#recipe-inbox-reply)
+12. [Call any endpoint, including ones with no hand-written client](#recipe-any-endpoint)
+13. [Read every page of a list endpoint](#recipe-paginate)
+14. [Handle errors](#recipe-errors)
+15. [Receive and verify webhooks](#recipe-webhooks)
+16. [Upsert a record in a custom object](#recipe-custom-objects)
+17. [Act on a client org with an agency key](#recipe-agency)
+18. [Track visitors and identify companies in the browser](#recipe-browser-tracking)
+
+<a id="recipe-setup-and-verify-key"></a>
+
+### Set up the client and check the key works
+
+Start of every server-side integration. `describeCurrentKey` is free, read-only, and tells you which org the key acts on and what it may reach, so a wrong or unscoped key fails here instead of halfway through a job.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+// Server-side only. Never ship an API key to a browser; use a write key there (see "Track visitors").
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const me = await g8.api.me.describeCurrentKey();
+console.log(me.data); // the key's org, mode (live/test) and scopes
+```
+
+<a id="recipe-upsert-contact"></a>
+
+### Create or update a contact
+
+Writing a person into graph8 when they may already exist. `upsert` matches on `work_email`, then `linkedin_url`, is idempotent and safe to retry. `create` is create-only and throws a 409 on a duplicate. Every contact lives in a list, so `list_id` is required.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const { action } = await g8.contacts.upsert({
+  list_id: 42,
+  work_email: "jane@acme.com",
+  first_name: "Jane",
+  last_name: "Doe",
+  job_title: "VP Sales",
+  company_domain: "acme.com",
+});
+console.log(action); // "created" or "updated"
+```
+
+<a id="recipe-find-contacts"></a>
+
+### Find and read contacts in the CRM
+
+Looking up people already in the workspace. `g8.contacts.list` filters the CRM; it does not search the 700M-person graph8 index (that is `g8.enrich.search`, which costs credits).
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const { data: contacts } = await g8.contacts.list({ company_name: "Acme", seniority_level: "VP", limit: 25 });
+for (const c of contacts) console.log(c.id, c.first_name, c.last_name, c.work_email);
+
+if (contacts.length > 0) {
+  const contact = await g8.contacts.get(contacts[0].id);
+  console.log(contact.job_title, contact.company_domain);
+}
+```
+
+<a id="recipe-prospect-and-import"></a>
+
+### Prospect in the graph8 index, then save the people you want
+
+Building a list of new prospects. `enrich.search` queries graph8's contact index (not your CRM) and can spend credits depending on the plan, so keep pages small and confirm the cost with a human before bulk runs. Results are plain records: write the ones you keep into a list with `contacts.upsert`.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const results = await g8.enrich.search(
+  [
+    { field: "seniority_level", operator: "any_of", value: ["VP", "Director"] },
+    { field: "company_industry", operator: "contains", value: ["SaaS"] },
+  ],
+  1, // page
+  25, // page size
+);
+console.log(`${results.total} matches; showing ${results.contacts.length}`);
+
+const list = await g8.lists.create("Q4 SaaS VPs", "contacts");
+for (const person of results.contacts) {
+  const email = typeof person.work_email === "string" ? person.work_email : undefined;
+  if (!email) continue;
+  await g8.contacts.upsert({
+    list_id: list.id,
+    work_email: email,
+    first_name: typeof person.first_name === "string" ? person.first_name : undefined,
+    last_name: typeof person.last_name === "string" ? person.last_name : undefined,
+  });
+}
+```
+
+<a id="recipe-enrich"></a>
+
+### Enrich one person or company
+
+You have an email, LinkedIn URL, name + company, or a domain and need the full profile. Each call costs 1 credit (tier `billable`), so the SDK will not blindly retry it on a 5xx.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const person = await g8.enrich.person({ email: "jane@acme.com" });
+const company = await g8.enrich.company({ domain: "acme.com" });
+const email = await g8.enrich.verifyEmail("jane@acme.com");
+console.log(person, company, email);
+```
+
+<a id="recipe-lists"></a>
+
+### Create a list and manage its members
+
+Grouping contacts for a sequence, campaign or export. List `type` is `contacts` or `companies`.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const list = await g8.lists.create("Webinar attendees", "contacts");
+await g8.lists.addContacts(list.id, [101, 102, 103]);
+
+const { data: members, total } = await g8.lists.contacts(list.id, 1, 100);
+console.log(`${total} contacts`, members.map((m) => m.id));
+
+await g8.lists.removeContacts(list.id, [103]);
+```
+
+<a id="recipe-add-to-sequence"></a>
+
+### Enroll contacts in a sequence
+
+Starting outreach for contacts that are already in a list. This reaches real people (tier `external`): confirm with a human first. Pass an idempotency key so a retry after a timeout cannot enroll anyone twice.
+
+```ts
+import { randomUUID } from "node:crypto";
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const sequences = await g8.sequences.list();
+const target = sequences.find((s) => s.name === "Q4 outbound");
+if (!target) throw new Error("No sequence named 'Q4 outbound'");
+
+const result = await g8.sequences.add(
+  { sequenceId: target.id, contactIds: [101, 102], listId: 42 },
+  randomUUID(), // reuse this same key if you retry this exact call
+);
+console.log(result);
+```
+
+<a id="recipe-campaign"></a>
+
+### Create and launch a campaign
+
+Running a multi-step graph8 campaign. `create` is safe; `launch` starts sending (tier `external`), so confirm with a human before calling it.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const campaign = await g8.campaigns.create({
+  name: "Q4 Push",
+  category: "Outbound",
+  target_persona: "VP Sales at 200-1000 person SaaS companies",
+  goal: "Book discovery calls",
+});
+
+// Only after a human has reviewed the campaign in graph8:
+const launched = await g8.campaigns.launch(campaign.id);
+console.log(launched);
+```
+
+<a id="recipe-deals"></a>
+
+### Create a deal and move it through the pipeline
+
+Tracking revenue. Stage ids come from `deals.pipelines()`; never guess them. `owner_id` is a graph8 user id.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const { data: pipelines } = await g8.deals.pipelines();
+const pipeline = pipelines.find((p) => p.is_default) ?? pipelines[0];
+const [firstStage, secondStage] = pipeline.stages;
+
+const deal = await g8.deals.create({
+  name: "Acme - annual plan",
+  owner_id: "user_123",
+  contact_ids: [101],
+  amount: 24000,
+  currency: "USD",
+  pipeline_id: pipeline.id,
+  stage_id: firstStage.id,
+});
+
+// `id` is typed nullable on the response; a created deal always has one.
+if (!deal.id) throw new Error("graph8 returned a deal without an id");
+await g8.deals.update(deal.id, { stage_id: secondStage.id, amount: 30000 });
+```
+
+<a id="recipe-tasks-and-notes"></a>
+
+### Log a note and create a follow-up task on a contact
+
+Recording activity against a contact, company or deal.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const contactId = 101;
+await g8.notes.create(contactId, "Spoke on the phone: evaluating vendors in Q1.");
+
+const task = await g8.tasks.create(contactId, {
+  title: "Send pricing",
+  due_date: "2026-10-15",
+  priority: 1,
+});
+await g8.tasks.update(task.id, { title: "Send pricing + case study" });
+
+const { data: open } = await g8.tasks.listForContact(contactId, "open");
+console.log(open.length);
+```
+
+<a id="recipe-inbox-reply"></a>
+
+### Triage the unified inbox and send a reply
+
+Handling replies across email, SMS and LinkedIn. `draft` asks graph8's AI for a suggested reply; `send` delivers a real message (tier `external`), so confirm with a human first.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const { data: threads } = await g8.inbox.list({ status: "open", page_size: 20 });
+const thread = threads[0];
+if (thread) {
+  const draft = await g8.inbox.draft(thread.id);
+  console.log(draft);
+
+  await g8.inbox.send(thread.id, {
+    channel: "email",
+    body: "Thanks Jane, Tuesday at 10am works. Invite on its way.",
+  });
+}
+```
+
+<a id="recipe-any-endpoint"></a>
+
+### Call any endpoint, including ones with no hand-written client
+
+The task is not covered by `g8.contacts`, `g8.deals` and the other hand-written clients. `g8.api` covers every Developer API operation, grouped by area, with typed `path` / `query` / `headers` / `body` input. Look the operation up in `docs/api/<namespace>.md` or `docs/api/by-path.md`. It returns the raw `{ data, ... }` envelope.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// By namespace and member (autocompletes). Appointments has no hand-written client.
+const bookings = await g8.api.appointments.listBookings({ query: { take: 50 } }); // `take`, not `limit`: the types say so
+console.log(bookings);
+
+// By the stable operationId, when you already know it.
+const contact = await g8.api.call("get_contact_contacts__contact_id__get", { path: { contact_id: 101 } });
+console.log(contact.data);
+
+// Check what an operation does before calling it: tier and required scope.
+const op = g8.api.operation("add_contacts_to_sequence_sequences__sequence_id__contacts_post");
+if (op.tier === "external" || op.tier === "billable" || op.tier === "destructive") {
+  console.log(`${op.method} ${op.path} is ${op.tier}: ask a human before calling it (scope ${op.scope})`);
+}
+```
+
+<a id="recipe-paginate"></a>
+
+### Read every page of a list endpoint
+
+Exporting or syncing more records than one page holds. `g8.api.paginate` follows `pagination.next_cursor` until it runs out. Use the largest page size the endpoint allows: the rate limit is per request, not per record.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+let count = 0;
+for await (const contact of g8.api.paginate("list_contacts_contacts_get", { query: { limit: 200 } })) {
+  count += 1;
+  if (count <= 3) console.log(contact);
+}
+console.log(`${count} contacts`);
+```
+
+<a id="recipe-errors"></a>
+
+### Handle errors
+
+Every integration. Failures throw `G8Error`. Read `status`, `code` and `detail`: FastAPI errors put the explanation in `detail` (a string, or a list of field errors on 422), and when the body has no `message` the error's `message` is only "Request failed with status N". The SDK already retries 429 / 5xx / network errors (`retryable` tells you it gave up on a transient one); do not wrap it in a second retry loop.
+
+```ts
+import { g8, G8Error } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+try {
+  await g8.contacts.create({ work_email: "jane@acme.com", list_id: 42 });
+} catch (err) {
+  if (!(err instanceof G8Error)) throw err;
+  switch (err.status) {
+    case 401: // bad or expired key: code is "api_key_expired" or "api_key_invalid"; rotate, do not retry
+      throw new Error(`graph8 key rejected (${err.code})`);
+    case 403: // key lacks the scope for this operation: g8.api.operation(id).scope names it
+      throw new Error(`graph8 key is missing a scope: ${JSON.stringify(err.detail)}`);
+    case 409: // duplicate: create() is create-only; upsert() updates the existing contact instead
+      await g8.contacts.upsert({ work_email: "jane@acme.com", list_id: 42 });
+      break;
+    case 422: // validation: detail is [{ loc, msg, type }]
+      console.error("invalid input", err.detail);
+      break;
+    default:
+      console.error(err.status, err.code, err.detail, `request id ${err.requestId}`, `retryable ${err.retryable}`);
+      throw err;
+  }
+}
+```
+
+<a id="recipe-webhooks"></a>
+
+### Receive and verify webhooks
+
+Reacting to graph8 events (replies, campaign status, CRM changes). Verify the signature on the RAW body before parsing it. Delivery is at least once, so deduplicate on the event id.
+
+```ts
+import http from "node:http";
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+const seen = new Set<string>();
+
+http
+  .createServer((req, res) => {
+    let raw = "";
+    req.on("data", (chunk) => (raw += chunk));
+    req.on("end", () => {
+      try {
+        const event = g8.webhooks.constructEvent(
+          raw,
+          String(req.headers["x-studio-signature"] ?? ""),
+          String(req.headers["x-studio-timestamp"] ?? ""),
+          process.env.G8_WEBHOOK_SECRET!,
+          { toleranceSeconds: 300 },
+        );
+        const id = String((event as { id?: unknown }).id ?? "");
+        if (id && seen.has(id)) return void res.writeHead(200).end();
+        if (id) seen.add(id);
+        console.log(event.event, event.data);
+        res.writeHead(200).end();
+      } catch {
+        res.writeHead(400).end(); // bad signature or stale timestamp
+      }
+    });
+  })
+  .listen(3000);
+```
+
+<a id="recipe-custom-objects"></a>
+
+### Upsert a record in a custom object
+
+The workspace defines its own objects (invoices, projects, ...). Match on a unique attribute so re-running the sync updates instead of duplicating. Needs an API key with `objects:write`.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const { data: attributes } = await g8.objects.listAttributes("invoices");
+console.log(attributes.map((a) => a.slug));
+
+const invoice = await g8.objects.upsertRecord("invoices", "reference", { reference: "INV-1042", amount: 1200 });
+
+// A conditional update: fails with 409 if someone changed the record since you read it.
+await g8.objects.updateRecord("invoices", invoice.id, { amount: 1250 }, { expectedRevision: invoice.revision });
+```
+
+<a id="recipe-agency"></a>
+
+### Act on a client org with an agency key
+
+An agency key (minted with `is_agency: true`) manages several client orgs. Send `X-Target-Org-Id` per call to pick one. Any other key silently ignores the header and acts on its own org, so check `agency.me()` first.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_AGENCY_KEY! });
+
+const { data: clients } = await g8.agency.clients();
+const clientOrg = clients[0]?.org_id;
+if (clientOrg) {
+  const contacts = await g8.api.contacts.listContacts({
+    query: { limit: 10 },
+    headers: { "X-Target-Org-Id": clientOrg },
+  });
+  console.log(contacts.data);
+}
+```
+
+<a id="recipe-browser-tracking"></a>
+
+### Track visitors and identify companies in the browser
+
+Front-end code. Use a WRITE key (safe to expose), never an API key. Write-key features: tracking, identity, visitor company lookup, forms, copilot, chat and calendar widgets. For React, wrap the app in `G8Provider` from `@graph8/sdk/react` and call `useG8()`.
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ writeKey: "YOUR_WRITE_KEY" });
+
+g8.page();
+g8.track("pricing_viewed", { plan: "pro" });
+g8.identify("jane@acme.com", { first_name: "Jane", company: "Acme" });
+
+const visitor = await g8.visitors.identify();
+console.log(visitor.company_name);
+
+const stop = g8.visitors.onIntent("high", (v) => console.log(`${v.company_name} is showing high intent`));
+setTimeout(stop, 60_000);
+```
+
+## 11. Pitfalls
+
+- **`g8.api` returns the envelope.** Write `const { data } = await g8.api.contacts.listContacts()`, then use
+  `data`; the result itself is not the record. Hand-written methods have already unwrapped it.
+- **`contacts.create` is create-only.** A duplicate throws `409`. Use `contacts.upsert` when the person may
+  exist.
+- **Contacts live in lists.** Creating or upserting a contact needs a `list_id`.
+- **`contacts.list()` returns a lean record** (17 fields). For full records (`created_at`, `updated_at`,
+  `full_name`, `personal_emails`, `company`, ...) in bulk, use `g8.contacts.listDetailed(filters)` or
+  `g8.contacts.getMany(ids)` (100 per request), not a `get()` per contact.
+- **The CRM and the data index are different things.** `g8.contacts.*` reads YOUR workspace;
+  `g8.enrich.search` searches graph8's 700M-person index, which can spend credits depending on the plan.
+- **Ids have types.** Contact and list ids are numbers; deal, task, note, sequence and campaign ids are
+  strings. The types enforce this, so read them.
+- **Parameter names differ per endpoint** (`limit` vs `take` vs `page_size`). Take them from the types or
+  the reference, not from a neighbouring endpoint.
+- **Never guess stage, pipeline, sequence, owner or list ids.** List them first (`deals.pipelines()`,
+  `sequences.list()`, `lists.list()`).
+- **Signals with an API key need `intent:read`.** Without it `g8.signals.company()` throws a `403`.
+- **Webhooks must be verified on the raw body**, before `JSON.parse`, and deduplicated by event id.
+- **An agency header on a non-agency key does nothing.** The call silently acts on the key's own org.
+- **Preview operations** (marked `preview` in the reference) may not be enabled for every org yet. A `403` or
+  `404` there can mean "not enabled", not "wrong input".
+
+## 12. Other ways in
+
+- **MCP server** (for agents that talk to graph8 directly rather than write code): `https://be.graph8.com/mcp/`,
+  OAuth, no install. Same capabilities as this SDK.
+- **CLI**: `pip install g8-mcp-server` installs `g8` (`g8 login`, `g8 whoami`).
+- **REST**: `https://be.graph8.com/api/v1/...` with `Authorization: Bearer <api key>`. Every route is in
+  [api/by-path.md](api/by-path.md).
+- **Web docs**: https://docs.graph8.com (index for agents: https://docs.graph8.com/llms.txt).