@curviate/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to `@curviate/sdk` are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning: semantic — minor for additive changes, patch for bug fixes; no stability promise before 1.0.
+
+---
+
+## [0.1.0] — 2026-06-21
+
+Initial public release.
+
+### Added
+
+**Client and auth**
+- `new Curviate({ apiKey })` — configures the SDK with a Bearer API key, base URL (`https://api.curviate.com`), timeout, and max retries.
+- `curviate.account(accountId)` — returns an account-scoped accessor; all LinkedIn operations are tied to a managed account.
+
+**Resource surface**
+
+- `curviate.accounts.*`:
+  - `list(params?)` — list managed accounts with optional `limit` and `cursor`.
+  - `get(accountId)` — fetch a single managed account.
+  - `link(body)` — connect a LinkedIn account via cookie or API key; returns an account or a checkpoint.
+  - `reconnect(accountId, body)` — reconnect a disconnected account.
+  - `refresh(accountId)` — force a session refresh.
+  - `update(accountId, body)` — update account settings.
+  - `disconnect(accountId)` — disconnect a managed account.
+  - `submitCheckpoint(body)` — submit a 2FA / CAPTCHA checkpoint challenge.
+  - `pollCheckpoint(body)` — poll for checkpoint resolution.
+  - `createConnectLink(body)` — generate a hosted connect link.
+
+- `curviate.account(id).messaging.*`:
+  - `listChats(params?)` — list conversation threads.
+  - `getChat(chatId)` — fetch a single chat.
+  - `startChat(body)` — start a new conversation.
+  - `listMessages(chatId, params?)` — list messages in a chat.
+  - `getMessage(messageId)` — fetch a single message.
+  - `sendMessage(chatId, body)` — send a message into a chat.
+  - `editMessage(messageId, body)` — edit a sent message.
+  - `deleteMessage(messageId)` — delete a sent message.
+  - `addReaction(messageId, body)` — add an emoji reaction.
+  - `getAttachment(messageId, attachmentId)` — download a message attachment.
+  - `syncChat(chatId)` — trigger a chat history sync.
+  - `syncMessages(params?)` — trigger a full message sync.
+  - `sendInMail(body)` — send an InMail.
+  - `getInMailBalance(params?)` — fetch InMail credit balance.
+
+- `curviate.account(id).profiles.*`:
+  - `get(profileId, params?)` — fetch a LinkedIn profile by id or handle.
+  - `getMe()` — fetch the profile for the managed account holder.
+  - `getCompany(companyId)` — fetch a company profile.
+  - `listConnections(params?)` — list the account's connections.
+  - `listFollowers(profileId, params?)` — list a profile's followers.
+  - `listPosts(profileId, params?)` — list a profile's posts.
+  - `listComments(profileId, params?)` — list a profile's post comments.
+  - `listReactions(profileId, params?)` — list a profile's post reactions.
+  - `endorse(profileId, body)` — endorse skills on a profile.
+
+- `curviate.account(id).invites.*`:
+  - `send(body)` — send a connection invitation.
+  - `listSent(params?)` — list sent invitations.
+  - `listReceived(params?)` — list received invitations.
+  - `respond(invitationId, body)` — accept or ignore a received invitation.
+  - `cancel(invitationId)` — cancel a sent invitation.
+
+- `curviate.account(id).posts.*`:
+  - `list(params?)` — list posts visible to the account.
+  - `get(postId)` — fetch a single post.
+  - `create(body)` — create a post.
+  - `listComments(postId, params?)` — list comments on a post.
+  - `comment(postId, body)` — comment on a post.
+  - `listReactions(postId, params?)` — list reactions on a post.
+  - `react(postId, body)` — react to a post.
+
+- `curviate.account(id).salesNavigator.*`:
+  - `searchPeople(body, params?)` — search people via Sales Navigator.
+  - `searchCompanies(body, params?)` — search companies via Sales Navigator.
+  - `getProfile(identifier, params?)` — fetch a Sales Navigator profile.
+  - `getParameters(params)` — fetch available search filter parameters.
+  - `saveLead(userId, body)` — save a lead.
+  - `startChat(body)` — start a Sales Navigator conversation.
+  - `syncMessages(params)` — sync Sales Navigator messages.
+
+- `curviate.account(id).recruiter.*`:
+  - `searchPeople(body, params?)` — search candidates via LinkedIn Recruiter.
+  - `getProfile(identifier, params?)` — fetch a Recruiter candidate profile.
+  - `getParameters(params)` — fetch available search filter parameters.
+  - `syncMessages(params)` — sync Recruiter messages.
+  - `startChat(body)` — start a Recruiter conversation.
+  - `listProjects(params?)` — list Recruiter projects.
+  - `getProject(projectId)` — fetch a single Recruiter project.
+  - `addCandidate(userId, body)` — add a candidate to a project.
+  - `addApplicant(userId, body)` — add an applicant to a job.
+  - `rejectApplicant(userId, body)` — reject an applicant.
+  - `listJobs(params?)` — list Recruiter job postings.
+  - `createJob(body)` — create a Recruiter job posting.
+  - `publishJob(jobId, body)` — publish a Recruiter job posting.
+  - `solveJobCheckpoint(jobId, body)` — solve a job-posting checkpoint.
+  - `listApplicants(jobId, params?)` — list applicants for a job.
+  - `getApplicant(applicantId)` — fetch a single applicant.
+  - `downloadResume(applicantId)` — download an applicant's resume.
+
+- `curviate.account(id).search.*` (classic LinkedIn search):
+  - `people(body)` — search people.
+  - `companies(body)` — search companies.
+  - `posts(body)` — search posts.
+  - `jobs(body)` — search jobs.
+  - `getParameters(query)` — fetch available search filter parameters.
+
+- `curviate.webhooks.*`:
+  - `create(body)` — register a new webhook endpoint.
+  - `list(params?)` — list registered webhooks.
+  - `update(id, body)` — update a webhook endpoint.
+  - `delete(id)` — delete a webhook endpoint.
+  - `listEvents()` — list available webhook event types.
+  - `getStateDiff(accountId, params?)` — fetch an account state diff.
+
+**Typed error model**
+- `CurviateError` — single thrown type for all API errors, carrying a stable `code`, `httpStatus`, `retryHint`, `userFixable`, `retryLikelyToSucceed`, and `requiredTier`.
+- `isCurviateError(err)` — type guard for narrowing in `catch` blocks.
+- 34-member `ErrorCode` union covering every observable API error code.
+
+**HTTP transport with retry and backoff**
+- Exponential backoff with jitter for retryable GET/HEAD errors (configurable `maxRetries`).
+- `Retry-After` header respected on 429 responses.
+- Per-attempt abort controller timeout.
+- JSON and binary (ArrayBuffer) response parsing.
+
+**Cursor pagination**
+- `curviate.paginate(method, params?)` — async iterator that follows the `cursor` field automatically.
+
+**Webhook signature verification**
+- `constructEvent(rawBody, signatureHeader, secret, opts?)` — verifies `HMAC-SHA256` webhook signatures using Web Crypto (`globalThis.crypto.subtle`); constant-time comparison prevents timing attacks; configurable replay window via `replayWindowSecs` (default 300 s). Always async — always `await` it.
+- `WebhookSignatureError` — thrown on malformed header, invalid signature, or replay; not a `CurviateError`.
+- `CurviateEvent` — 19-member discriminated union covering all canonical webhook event types.
+
+**TypeScript types**
+- Full OpenAPI-generated types at `src/generated/types.ts` — request bodies, responses, and path params.
+- ESM-only build targeting ES2020; works in Node 18+, Cloudflare Workers, Vercel Edge.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Redmer Holding GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# @curviate/sdk
+
+The official TypeScript SDK for the [Curviate API](https://docs.curviate.com) — agent-native
+LinkedIn infrastructure for AI engineers and agent builders.
+
+> **Status:** `0.1.0` — pre-GA. The surface is public but not yet stability-promised.
+
+---
+
+## Install
+
+```bash
+npm install @curviate/sdk
+```
+
+Requires Node 18+. Works in Cloudflare Workers and Vercel Edge.
+
+---
+
+## Auth — construct the client
+
+Get your API key from the Curviate dashboard. Store it as an environment variable.
+
+```ts
+import { Curviate } from "@curviate/sdk";
+
+const curviate = new Curviate({
+  apiKey: process.env.CURVIATE_API_KEY!,
+  // Optional:
+  // baseUrl: "https://api.curviate.com", // default
+  // timeout: 30_000,                     // per-attempt timeout, ms
+  // maxRetries: 3,                        // GET/HEAD retries with backoff
+});
+```
+
+---
+
+## Account-scoped accessor
+
+Every LinkedIn operation (messages, profiles, invites, posts) is tied to a **managed account** — a LinkedIn session you have connected via `curviate.accounts.link()`. 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
+const { items: accounts } = await curviate.accounts.list();
+
+// Account-scoped: all LinkedIn ops under a specific account
+const acc = curviate.account(accounts?.[0]?.account_id ?? "");
+
+// Now every resource call is scoped to that account:
+const { items: chats } = await acc.messaging.listChats();
+const profile = await acc.profiles.get("some-profile-id");
+```
+
+---
+
+## First end-to-end call
+
+This snippet lists your connected accounts, picks the first one, and sends a message — something an agent might do to automate outreach:
+
+```ts
+import { Curviate, isCurviateError } from "@curviate/sdk";
+
+const curviate = new Curviate({ apiKey: process.env.CURVIATE_API_KEY! });
+
+async function sendFirstMessage() {
+  // 1. List connected accounts
+  const { items: accounts } = await curviate.accounts.list();
+  if (!accounts || accounts.length === 0) throw new Error("No active accounts.");
+
+  const first = accounts[0]!;
+  const acc = curviate.account(first.account_id ?? "");
+
+  // 2. List recent chats
+  const { items: chats } = await acc.messaging.listChats({ limit: 5 });
+  if (!chats || chats.length === 0) return;
+
+  // 3. Send a message to the first chat
+  const chat = chats[0]!;
+  await acc.messaging.sendMessage(chat.id ?? "", {
+    text: "Hi — following up from our conversation.",
+  });
+
+  console.log("Message sent.");
+}
+
+sendFirstMessage().catch(console.error);
+```
+
+---
+
+## Typed error handling
+
+Every API error is a `CurviateError`. Use `isCurviateError` to narrow in `catch`, then switch on `err.code` for exhaustive handling:
+
+```ts
+import { isCurviateError } from "@curviate/sdk";
+
+try {
+  await acc.messaging.sendMessage("c_123", { text: "hello" });
+} catch (err) {
+  if (!isCurviateError(err)) throw err; // re-throw network errors etc.
+
+  switch (err.code) {
+    case "RECIPIENT_UNREACHABLE":
+      console.warn("Recipient can't receive messages.");
+      break;
+    case "RATE_LIMIT_ACCOUNT":
+      // err.retryAfterMs tells you exactly how long to wait
+      await sleep(err.retryAfterMs ?? 5_000);
+      break;
+    case "ACCOUNT_NOT_FOUND":
+      console.error("Account does not exist for this tenant.");
+      break;
+    default:
+      if (err.retryLikelyToSucceed) {
+        // Safe to retry — server-side transient error
+        await retry();
+      }
+  }
+}
+```
+
+All 34 error codes are documented in the [API reference](https://docs.curviate.com).
+
+---
+
+## Cursor pagination
+
+Resources that return lists support cursor pagination. `curviate.paginate()` is an async iterator that follows the `cursor` field automatically — pull items one at a time without managing cursors:
+
+```ts
+// Iterate over every chat across all pages
+for await (const chat of curviate.paginate(acc.messaging.listChats.bind(acc.messaging), {})) {
+  console.log(chat.id, chat.unread_count);
+}
+
+// With initial params
+for await (const account of curviate.paginate(
+  curviate.accounts.list.bind(curviate.accounts),
+  { limit: 50 },
+)) {
+  console.log(account.account_id);
+}
+```
+
+---
+
+## Webhook verification
+
+Register a webhook to receive real-time events, then verify each delivery with `constructEvent`:
+
+```ts
+import { constructEvent, WebhookSignatureError } from "@curviate/sdk";
+
+// Express (Node 18+)
+app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
+  const sig = req.headers["x-curviate-signature"] as string;
+  const secret = process.env.CURVIATE_WEBHOOK_SECRET!;
+
+  let event;
+  try {
+    event = await constructEvent(req.body, sig, secret);
+  } catch (err) {
+    if (err instanceof WebhookSignatureError) {
+      console.warn("Bad webhook:", err.reason); // 'invalid_signature' | 'replay_detected' | 'malformed_header'
+      return res.sendStatus(400);
+    }
+    throw err;
+  }
+
+  switch (event.type) {
+    case "message.received":
+      // event.data is MessagePayload — account_id, message_id, etc.
+      handleNewMessage(event.data);
+      break;
+    case "account.connected":
+      handleAccountConnected(event.data);
+      break;
+    // 17 more event types — all in the CurviateEvent union
+  }
+
+  res.sendStatus(200);
+});
+
+// Hono / Vercel Edge — always await (Web Crypto is async)
+app.post("/webhook", async (c) => {
+  const rawBody = await c.req.text();
+  const event = await constructEvent(rawBody, c.req.header("x-curviate-signature")!, secret);
+  return c.text("ok");
+});
+```
+
+`constructEvent` always returns a `Promise<CurviateEvent>` — always `await` it.
+
+`WebhookSignatureError` is NOT a `CurviateError` — narrow with `instanceof WebhookSignatureError`.
+
+---
+
+## Links
+
+- API reference: https://docs.curviate.com
+- Issues: https://github.com/curviate/sdk/issues
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)
+
+## License
+
+MIT © Redmer Holding GmbH