@curviate/sdk 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,191 @@ Versioning: semantic — minor for additive changes, patch for bug fixes; no sta
 
 ---
 
+## [Unreleased]
+
+## [0.16.0] — 2026-07-17
+
+Mostly additive, plus one breaking removal on the connect/reconnect body.
+
+### Breaking
+
+- **`disabled_features` is removed from `auth.intent()`'s request body**
+  (`AuthIntentBody`). The negative-list model could not express the `company`
+  product or the one-Premium-per-profile XOR. Connection scope (which
+  LinkedIn products get synced) is now **seat-derived**: there is no products
+  input on connect/reconnect at all. Drop any `disabled_features` you were
+  passing: a body still carrying it is now rejected 400 by the server. The
+  scope actually recorded for an account reads back as the new
+  `requested_products` field (see Added, below). A reconnect that changes
+  scope must use `auth_method: "credentials"`, since a cookie replay cannot
+  change scope and now throws `CurviateError(code: "REAUTH_REQUIRED")`.
+
+### Added
+
+- **New account-scoped `inboxes` namespace (2 methods, Beta), the reply-as-a-page
+  surface.** `inboxes.list(query?)` discovers the account's personal inbox
+  plus, when the company product is attached, one entry per company page (id
+  like `"COMPANY_83734124_PRIMARY"`). `inboxes.listChats(inboxId, query?)`
+  lists a single inbox's conversations, cursor-paginated. Every returned chat
+  `id` is send-ready: pass it straight to the existing `messaging.sendMessage()`
+  to reply, no separate start/send endpoint. Company pages are reply-only
+  (`reply_only: true`) and cannot start a new conversation. **Beta:**
+  single-page listing is verified; deep pagination against a busier inbox is
+  still being validated.
+- **`sendMessage()` echoes the acting identity as `sent_as`,** additive on
+  the existing send-message response. A `COMPANY_` chat id (from
+  `inboxes.listChats()`) sends AS THE PAGE and echoes
+  `sent_as: { kind: "company", company_id, name }` (`company_id` is `null`
+  when the page could not be correlated to a managed page). Any other chat id
+  sends as the connected member and echoes `sent_as: { kind: "personal" }`.
+  Never infer the acting identity from a message's `sender` field, only from
+  `sent_as`.
+- **`accounts.list()` / `accounts.get()` gain `requested_products`,** the
+  seat-derived connection scope (e.g. `["classic", "company",
+  "sales_navigator"]`) the account was last connected with. `null` for
+  accounts connected before this was recorded, and not attachment truth for
+  Company Pages (that is decidable only via `inboxes.list()`).
+- **Two new error codes:** `PREMIUM_CONFLICT` (a seat resolving to both
+  individual-Premium tiers at once, since LinkedIn permits only one per
+  profile; `user_fixable`, never retryable) and `REAUTH_REQUIRED` (a
+  scope-changing reconnect attempted with a cookie instead of credentials;
+  `user_fixable`, never retryable).
+- **New account-scoped `profile` namespace (4 methods)** — the connected
+  account's own insight surface: `profile.subscription()`, `profile.analytics()`,
+  `profile.visitors(query?)`, `profile.ssi()`. Distinct from the retired
+  `profiles` namespace (renamed to `users` in 0.15.0).
+- **New account-scoped `groups` namespace (3 methods)** — `groups.list(query?)`
+  (own groups by default, or another member's via `{ profile }`),
+  `groups.get(group)`, and `groups.members(group, query?)` (with the folded-in
+  `{ name }` member search).
+- **New account-scoped `feed` namespace (1 method)** — `feed.home(query?)` reads
+  the connected account's home feed as agent-actionable posts, with `relevant`
+  or `recent` sort orders.
+- **`companies` gains 3 company-insights methods** — `companies.managed(query?)`
+  lists the pages the connected account administers; `companies.followers(identifier,
+  query?)` lists a page's followers (**re-added** under a different item shape —
+  `company_follower`, carrying `degree`/`followed_at` — than the pre-0.15.0
+  method of the same name); `companies.invitableFollowers(identifier, query?)`
+  lists connections invitable to follow the page. All three require the
+  connected account to administer the target page.
+- **`companies` gains 5 Beta company-inbox methods** — `companies.chats(identifier,
+  query?)`, `companies.chat(identifier, chatId)`, `companies.messages(identifier,
+  chatId, query?)`, `companies.message(identifier, chatId, messageId)`, and
+  `companies.searchChats(identifier, query?)` (exactly one of `query`/`topic`/
+  `unread` per call). A distinct conversation surface from the account's own
+  `messaging` namespace, scoped to one administered company page. **Beta:**
+  single-page listing and termination are verified; deep pagination (many
+  pages / large cursor round-trips) is still being validated against a busier
+  inbox. `companies` is now 12 methods (was 4).
+- **`search` gains 3 methods** — `search.groups(query)` searches LinkedIn
+  groups by keyword; `search.services(body & query)` searches Services
+  Marketplace providers with structured filters; `search.getServiceParameters(query)`
+  resolves human-readable service-category/location terms into the opaque
+  filter ids `services()` accepts. `search` is now 9 methods (was 6).
+- **`messaging` gains 1 method** — `messaging.searchChats(params)` free-text
+  searches the account's own inbox (participant names and message content).
+  `messaging` is now 13 methods (was 12).
+- **`posts` gains 3 saved-posts methods** — `posts.listSaved(query?)` lists the
+  connected account's own saved posts (a self resource — previews only,
+  `snippet` capped at ≤140 chars, never the full body); `posts.save(postId)`
+  and `posts.unsave(postId)` add/remove a bookmark, both idempotent and
+  accepting either `urn:li:activity:<id>` or a bare numeric id. `posts` is now
+  12 methods (was 9).
+- **New account-scoped `notifications` namespace (3 methods)** — the connected
+  account's own notification centre: `notifications.list(query?)` (cards +
+  the account-level `unread_count`/`latest_published_at`);
+  `notifications.delete(cardUrn)` and `notifications.showLess(cardUrn)`, two
+  self-action writes on the account's own cards. Both writes are idempotent
+  and take effect within a few seconds — a list read immediately after may
+  still show the card for a moment, which is not a failure signal. The SDK
+  percent-encodes `cardUrn` (which embeds `(`, `)`, `:`, `,`) into the path.
+- **Parity pin: 143 methods across 18 namespaces** (was 135 / 16 at the start
+  of this release cycle). The `inboxes` namespace is the final addition.
+
+## [0.15.0] — 2026-07-11
+
+Full v2 parity. The SDK is re-aligned 1:1 to the served API surface: every
+operation is now exactly one method at the exact wire encoding, the entire
+account-scoped surface moves to the account-first path grammar, and three
+namespaces are reorganized. This is a **breaking** release touching nearly
+every namespace. The five breaking categories below — removals, namespace
+reorganization, method renames/relocations, request/response shape changes, and
+the account-first path-grammar migration — are the complete set of breaks a
+`0.14.1` → `0.15.0` upgrade must reconcile, gathered here so a consumer finds
+every break in one place.
+
+### Removed (BREAKING)
+
+- **14 methods that map to no served operation are removed, with no alias:**
+  - `accounts.createConnectLink()`, `accounts.createReconnectLink()`, `accounts.reconnect()` — hosted connect/reconnect link minting and in-place reconnect are no longer part of the API surface.
+  - `messaging.syncChat()`, `messaging.syncMessages()`, `recruiter.syncMessages()`, `salesNavigator.syncMessages()` — explicit sync operations are gone; accounts sync continuously and deliver via webhooks.
+  - `posts.list()` — the standalone feed list has no served operation (use `posts.listUserPosts(userId)` for a member's posts).
+  - `companies.followers()` — no served operation.
+  - `recruiter.addApplicant()`, `recruiter.rejectApplicant()`, `recruiter.solveJobCheckpoint()` — superseded by the project-centric pipeline surface.
+  - `webhooks.getStateDiff()` — no served operation.
+- **`invites.respond()` is removed** — split into two dedicated bodyless methods, `invites.accept(invitationId)` and `invites.decline(invitationId)` (see below).
+- **`profiles.getCompany()` stays removed** — dropped ahead of this release with no return; company reads live on the `companies` namespace.
+
+### Changed (BREAKING) — namespaces reorganized
+
+- **`profiles` namespace renamed to `users`.** Every `curviate.account(id).profiles.*` call becomes `…users.*`; the served group is "Users" and every path is `/users/{user_id}`.
+- **New root-scoped `auth` namespace, split out of `accounts`.** The connect/checkpoint operations move off `accounts`: `accounts.link` → `auth.intent`, `accounts.solveCheckpoint` → `auth.solveCheckpoint`, plus `auth.requestCheckpoint`, `auth.pollCheckpoint`, and `accounts.getConnectSession` → `auth.getSession(sessionId)`. `accounts` now carries only `list` / `get` / `update` / `disconnect`.
+- **New account-scoped `comments` namespace.** The comment-thread surface (create / edit / delete / reply / list replies / reactions) plus the relocated `listUserComments` live here rather than on `posts`.
+- **Root and account surfaces are now strictly disjoint.** The root client exposes only `accounts`, `auth`, `webhooks`. Every other namespace is reachable exclusively through `curviate.account(id)` — the account-scoped namespaces are no longer mounted on the root client (they cannot build a valid path without a bound `account_id`).
+
+### Changed (BREAKING) — methods renamed / relocated
+
+- `profiles.endorse(userId, { skill_endorsement_id })` → **`users.endorseSkill(userId, { endorsement_id })`** — renamed, and the body key changed from `skill_endorsement_id` to `endorsement_id`.
+- `profiles.listConnections()` → **`users.listRelations()`**.
+- `messaging.getInMailBalance()` → **`users.getInMailCredits()`** (relocated onto `users`).
+- `posts.comment(postId, …)` → **`comments.create(postId, …)`**.
+- `profiles.listComments(userId)` → **`comments.listUserComments(userId)`**.
+- `profiles.listPosts(userId)` → **`posts.listUserPosts(userId)`**.
+- `profiles.listReactions(userId)` → **`posts.listUserReactions(userId)`**.
+- `invites.respond(...)` → **`invites.accept(invitationId)` / `invites.decline(invitationId)`** (split; both bodyless).
+- `recruiter.addCandidate(...)` → **`recruiter.saveCandidate(projectId, { stage_id, candidate_id })`**.
+- `recruiter.getParameters(...)` (GET) → **`recruiter.searchParameters(body)` (POST)** — the HTTP verb changed GET→POST, with a `source`-discriminated body.
+- `recruiter.listProjectJobs(projectId)` → **`recruiter.getProjectJob(projectId)`** — the operation returns the single attached job posting, not a list.
+
+### Changed (BREAKING) — request / response shapes
+
+- **`users.update(userId, body)`** never sends `description`; accepted keys are `{ first_name, last_name, headline, bio, skills, picture, background_picture }`.
+- **`users.endorseSkill`** body key is `endorsement_id` (was `skill_endorsement_id`).
+- **`jobs.publish` / `recruiter.publishJob`** take a `mode`-discriminated body (`FREE` | `PROMOTED` | `PROMOTED_PLUS`; the `PROMOTED*` modes require a `budget { currency, amount, scope }`) and respond `{ object, job_state }`.
+- **`jobs.close` / `recruiter.closeJob`** are bodyless POSTs responding `{ object }`.
+- **`invites.cancel`** withdrawal now discriminates on `invitation_withdrawn`.
+- **Message operations are re-homed under the chat.** `getMessage` / `editMessage` / `deleteMessage` / `addReaction` / `getAttachment` now path under `/chats/{chat_id}/messages/…` and take `chatId` as the leading argument.
+- **`messaging.sendInMail`** body drops the `surface` field.
+- **Media-bearing writes moved from multipart to JSON + base64** where the surface retired multipart (recruiter, sales-navigator, posts, messaging); read each operation's declared content-type — some remain multipart.
+- **Sales Navigator `saveAccount` / `saveLead` bodies shrank** to the minimal saved-entity shape.
+- **`recruiter.startChat`** now requires a `signature` (alongside `attendees_ids`, `text`, `subject`).
+- **`recruiter.createJob`** now requires `project_name` and responds `{ job_id, object, project_id }` (was a full job object).
+- **`recruiter.saveCandidate`** body is `{ stage_id, candidate_id }`.
+
+### Changed (BREAKING) — account-first path grammar
+
+- **Every account-scoped method now carries `account_id` as the leading path segment** (`/v1/{account_id}/…`), never as a query parameter, body field, or omitted. Bind it once with `curviate.account(id)` and it is injected on every call. Companies and relations, which previously carried `account_id` as a query argument, drop it entirely.
+
+### Added
+
+- **`comments` namespace (9 methods):** `listUserComments`, `create`, `edit`, `delete`, `reply`, `listReplies`, `listReactions`, `addReaction`, `removeReaction` — `removeReaction` is a DELETE that carries a `{ reaction }` body.
+- **`jobs` write surface (9 new methods):** `list`, `create`, `update`, `getBudget`, `publish`, `close`, `listApplicants`, `getApplicant`, `downloadResume` (binary `ArrayBuffer`). `jobs.create` takes object-shaped `job_title` / `company` and a `method`-discriminated `apply_method`.
+- **Project-centric `recruiter` surface (9 new methods):** `searchTalentPool`, `searchFromUrl`, `updateProject`, `listPipeline`, `getProjectJob`, `createProjectJob`, `getProjectJobBudget`, `updateProjectJob`, `closeJob`, with `getApplicant` / `downloadResume` re-homed under the project scope.
+- **`users.follow` / `users.unfollow`** (bodyless POST / DELETE), **`users.listFollowing`**, **`users.update`**.
+- **`messaging.markChatRead(chatId, { read })`**.
+- **`search.fromUrl({ url })`** and **`salesNavigator.searchFromUrl({ url })`** — resolve a LinkedIn search-results URL into a search.
+- **`posts.delete`** (bodyless, 204) and **`posts.unreact(postId, { reaction })`** (DELETE with body).
+- **`users.get(userId)` accepts `'me'`** — `users.get('me')` reads the caller's own profile (folds in the old `getMe`).
+- **New `ErrorCode` value: `LINKEDIN_OPERATION_NOT_SUPPORTED`.** The `422` a permanent LinkedIn platform limitation for the attempted operation returns (e.g. listing a non-self user's following list) — `user_fixable: true`, `retry_likely_to_succeed: false` (not a transient failure; retrying will not help). Added to the `ErrorCode` union and the transport's known-code set — previously this narrowed to `INTERNAL`, which is retryable.
+
+### Fixed
+
+- **`CONNECTION_REQUEST_CONFLICT` was silently downgraded to `INTERNAL`.** The `409` the API returns when a connect-request to a member already exists (or you are already a first-degree connection) is a real, documented error code, but the transport's runtime known-code set omitted it — so callers received `code: "INTERNAL"` with the wrong semantics (`INTERNAL` is retryable, whereas this conflict is `user_fixable: true`, `retry_likely_to_succeed: false` and must never be re-sent). The transport now decodes `CONNECTION_REQUEST_CONFLICT` to itself. To eliminate the class of bug: the `ErrorCode` type and the transport's runtime known-code set are now both **derived from one source array**, so the code a caller narrows on and the code the transport recognizes can never drift apart again.
+- **`RATE_LIMITED` was silently downgraded to `INTERNAL`.** The `429` the Recruiter and Sales Navigator read surface returns under LinkedIn-platform throttling (dedicated `RateLimit-Policy` / `RateLimit` / `Retry-After` response headers, `retry_likely_to_succeed: true`) is a real, documented error code, but the transport's runtime known-code set omitted it — so callers received `code: "INTERNAL"`, which happened to auto-retry on `GET`/`HEAD` by accident but with the wrong (generic backoff) delay instead of honoring `Retry-After`. The transport now decodes `RATE_LIMITED` to itself and retries it on `GET`/`HEAD` like the other rate-limit codes, honoring `Retry-After`.
+- **`users.update` forwarded an unsupported `description` key if a caller smuggled one in.** The `UserUpdateBody` type never declared `description`, so a typed caller was already rejected at compile time — but an untyped/JS caller (or an `as`-cast) could still put it on the object, and `update()` forwarded the body verbatim with no runtime check. `update()` now strips `description` from the outgoing payload before the request is sent, regardless of caller strictness.
+
+---
+
 ## [0.14.1] — 2026-07-07
 
 ### Fixed

package/README.md

@@ -3,7 +3,7 @@
 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.
+> **Status:** `0.16.0` — pre-1.0. Full v2 API parity; the surface is public but not yet stability-promised.
 
 ---
 
@@ -37,10 +37,10 @@ const curviate = new Curviate({
 
 ## 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:
+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()`). 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
+// Root-level: tenant-wide operations (accounts, auth, webhooks)
 const { items: accounts } = await curviate.accounts.list();
 
 // Account-scoped: all LinkedIn ops under a specific account
@@ -48,7 +48,8 @@ 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");
+const me = await acc.users.get("me");           // your own profile
+const profile = await acc.users.get("some-user-id"); // someone else's
 ```
 
 ---
@@ -131,7 +132,7 @@ Resources that return lists support cursor pagination. `curviate.paginate()` is
 ```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);
+  console.log(chat.id);
 }
 
 // With initial params