@curviate/sdk 0.24.3 → 0.26.0

package/CHANGELOG.md

@@ -7,7 +7,180 @@ Versioning: semantic. Minor for additive changes, patch for bug fixes; no stabil
 
 ---
 
-## [Unreleased]
+## [0.26.0] - 2026-09-06
+
+Fixture regenerated against the deployed production document
+(`https://api.curviate.com`, `server_git_sha bd795601...`, 125 paths).
+**BREAKING at the type level** for a consumer that reads `row` off an error
+or a safety warning as a `string`: it is now `string | null` on both. Three
+response enums also widen, which reds an exhaustive `switch` with a `never`
+default. Everything else in this release is additive.
+
+### Added
+
+- **`NOT_STORED` in the error taxonomy.** The `422` a read gets when
+  `mode=cache_only` (or `refill` on a resource that cannot be filled) finds
+  nothing in Curviate's store, so the API refuses rather than reaching
+  LinkedIn. It was missing from `ERROR_CODES`, so it decoded to `INTERNAL`:
+  a caller could not branch on it, and, the harmful half, `INTERNAL` is
+  retryable, so a `cache_only` miss was retried on a GET against an answer
+  that cannot change until the caller picks another mode. It is now decoded to
+  itself and is deliberately absent from the retryable set. Not the same as
+  `RESOURCE_NOT_FOUND`: the resource may exist and this API simply holds no
+  copy, so the fix is another mode, not another id. `cache_only` is the mode
+  that raises it on these reads, and `refill` or `auto` is the remedy.
+
+  **This reds `@curviate/cli`'s exit-code exhaustiveness guard, by design.**
+  That guard iterates the exported `ERROR_CODES` array rather than a copy of
+  it, which is the whole reason the array is exported, so a code added here
+  with no exit-code mapping is supposed to fail it. Map `NOT_STORED` there when
+  bumping the pin.
+- **`messaging.getChat(chatId, params?)` takes the retrieval query.**
+  `GET /v1/{account_id}/chats/{chat_id}` declares `expand`, `mode` and
+  `max_age`; the method sent no query at all, so a chat read was the one
+  store-servable read with no retrieval ladder. `ChatGetQuery` is derived from
+  the generated `paths` types, like every other query type here.
+  `users.get()` and `messaging.listMessages()` already carried the pair and
+  are unchanged; the README now documents all three.
+
+### Regenerated types
+
+- **BREAKING - `row` is nullable on both `Error` and `SafetyWarning`.**
+  `Error.row` goes `string | undefined` to `string | null | undefined`, and
+  `SafetyWarning.row` - which is REQUIRED, so it is the one that will actually
+  break a build - goes `string` to `string | null`. `null` says the breach
+  names no row: an `activity_window` refusal on an action that spends no
+  budget of its own has an hour to answer for and no counter. Read
+  `hint.parameter` in that case; it names `posture`. A consumer that assigned
+  `.row` to a `string` or passed it somewhere non-null now has a type error,
+  and that error is correct - the runtime value was always going to be `null`
+  once the server started sending it. The SDK's own `CurviateError.budgetRow`
+  is UNCHANGED (`string | undefined`): `transport.ts` maps the wire field with
+  a `typeof === "string"` guard, so a `null` row arrives as an absent
+  `budgetRow`, which is what "no row to name" already meant on that surface.
+- **BREAKING for an exhaustive `switch` - three response enums widen.** Each
+  gains a member, so a `switch` with a `never`-typed default arm stops
+  compiling. None of them removes a member, so a `switch` with a real default
+  keeps working:
+  - `GET /v1/{account_id}/safety-events` `items[].reason` gains
+    `activity_window` alongside `budget_exhausted` and `rate_limited`.
+  - `GET /v1/{account_id}/safety-events` `items[].budget_row` gains `"*"`, the
+    wildcard for an event that is not scoped to one row.
+  - `notices[].code` on the ten chat and message reads that accept
+    `expand=public_identifier` gains `EXPANSION_WITHHELD_ACTIVITY_WINDOW`
+    alongside `EXPANSION_LIMIT_REACHED`: the expansion was refused because the
+    account is outside its activity window, not because the page ran out of
+    lookup budget. Same consequence for the reader either way -
+    `public_identifier` is `null` for reasons that are not "no public profile"
+    - but a different fix, so it is a separate code. The `notices` key itself
+    is not new.
+- **Additive - `interface_ceiling` and `effective_interface_ceiling` on every
+  budget row.** Optional, `number | null`. They appear on `quotas[]` from
+  `GET /v1/accounts/{account_id}` and on the policy rows from
+  `GET`/`PATCH /v1/{account_id}/safety-policy`. What a call through the
+  matching ELEVATED interface (`/sales-navigator/...`, `/recruiter/...`) is
+  held to on that row; `null` wherever the row and limit profile have no such
+  figure, which is every row on `basic` and `premium`. `ceiling`,
+  `effective_ceiling`, `band` and `over_default` all remain the STANDARD
+  figure, so a row can report `band: "over"` while an elevated call still
+  succeeds. Read `effective_interface_ceiling`, not `interface_ceiling`, for
+  the same reason `effective_ceiling` and not `ceiling` answers that on the
+  standard side. On the `PATCH` request body both are typed `unknown` and
+  documented READ-ONLY: sent back they are accepted and ignored, so a read can
+  round-trip unedited.
+- **Additive - `activity_window` on the `PATCH /v1/{account_id}/safety-policy`
+  request body**, typed `unknown` and documented NOT ACCEPTED. Send the
+  settable subfields instead: top-level `timezone`, and per row
+  `activity_window_start`, `activity_window_end`, `activity_window_timezone`,
+  `activity_window_applies_to`.
+- Description-only, no type change: `reset_at` on `Error` and `SafetyWarning`
+  now states that it is the window roll on a `ceiling` refusal and the next
+  window open on an `activity_window` one, and restates the two cases where no
+  clock frees the account (the `pending_invites` gauge, and InMail credits).
+  The chat-search `q` parameter documents that a 1-2 character term is slower.
+
+## [0.25.0] - 2026-09-05
+
+**BREAKING** for a consumer that pinned the old type declarations: `quotas[]`
+on `GET /v1/accounts/{account_id}` is a different array, and `message_id` on
+`startChat`, `sendMessage`, `sendInMail` and the company chat reply is now
+`string | string[] | null` where it was `string`. Both are detailed under
+"Regenerated types" below. Pre-1.0 a breaking change ships as a minor, so a
+caret range on `0.24.x` will not pick this up.
+
+### Added
+
+- **`BUDGET_EXHAUSTED`, the account-safety refusal, and its payload.** A `429`
+  that is Curviate's own ceiling rather than a request-rate limit: nothing
+  reached LinkedIn and nothing was spent. `CurviateError` gains `budgetRow`
+  (wire `row`), `resetAt` (`reset_at`, and `null` in the two cases no clock
+  frees: the `pending_invites` gauge and an InMail credit exhaustion),
+  `safetyHint` (`hint`, the settable parameter
+  on `PATCH /v1/{account_id}/safety-policy`), `safetyReason` (`reason`:
+  `ceiling` or `activity_window`) and `blocked`. All six ride `toJSON()`.
+  The code is deliberately NOT retryable: a monthly row's reset can be weeks
+  out, so a backoff loop burns retries against a wall that will not move.
+  On a successful response the same payload arrives under `safety_warning`
+  with `blocked: false`, typed on the generated response types.
+- **`budgetRow` and `retryAfterSeconds` on a paused-row `PLATFORM_RATE_LIMIT`.**
+  Same wire `row`, different meaning: LinkedIn refused a recent call on that
+  row, so the next one is refused locally until the pause lifts. The pause is
+  scoped to `(account, row)`, so the recovery is to switch work rather than
+  back off across the account. `retry_after` is deliberately NOT folded into
+  `retryAfterMs`, which everything sleeps.
+- **A response carrying `row` is never auto-retried, on any method.**
+- **`LINKEDIN_SESSION_EVICTED`.** A 401 split from `LINKEDIN_AUTH_FAILED`
+  because the remedies differ: reconnecting does nothing while the other
+  session is open. Not retryable.
+
+### Changed
+
+- **Fixture regenerated against the deployed production document**
+  (`https://api.curviate.com`, `git_sha 33b42521...`), and the generated
+  types with it. Two shape changes are BREAKING for a consumer that pinned
+  the old declarations, and one enum widened. See "Regenerated types" below.
+
+### Regenerated types
+
+- **BREAKING - `quotas[]` on `GET /v1/accounts/{account_id}` is a different
+  array.** `quota_name`, `remaining`, `total`, `reset_time` and
+  `recommended_throttle_hint` are gone. Each row now carries `budget_row`,
+  `kind` (`debit` / `tally` / `gauge`), `window`, `window_start`, `resets_at`,
+  `used`, `ceiling`, `effective_ceiling`, `band`, `posture`, `over_default`,
+  `halt` and, on the gauge, `observed_at`. **Compare `used` against
+  `effective_ceiling`**, which is `ceiling` with the account's warm-up ramp
+  applied; on a new account the two differ by roughly a factor of seven.
+  `used` is `null` only on the gauge, and only before anything has observed
+  it. The per-minute REQUEST ceiling is deliberately not in this array.
+- **BREAKING - `message_id` is `string | string[] | null`** on `startChat`,
+  `sendMessage`, `sendInMail` and the company chat reply, where it was
+  `string`. `null` when no message was actually sent, an array when the
+  message was delivered as several, one per attachment. Confirm a send with
+  `chat_id`, which is always present.
+- Chat-search results: `type` gains `channel`. The generated comment used to
+  say search results are never channels; that is no longer true, so an
+  exhaustive `switch` over `type` needs a third arm.
+- Additive: `GET`/`PATCH /v1/{account_id}/safety-policy`,
+  `GET /v1/{account_id}/safety-events`, the four retained-event operations
+  under `/v1/{account_id}/events`, a `SafetyWarning` component reachable as
+  `safety_warning` on 149 success responses, six new optional fields on the
+  shared `Error` component, `coverage` on chat search, `mode` and `max_age`
+  query params on the store-served reads, `account_states[]` on the account
+  resource, and `observed_at` / `source` / `withdrawn` becoming REQUIRED on
+  four entity reads (a response gaining guarantees, not losing them).
+
+- **`postpublish` now notices a stale CLI pin.** After every `npm publish`,
+  `scripts/check-cli-notice.mjs` compares the version just published
+  against what `@curviate/cli` actually declares for `@curviate/sdk` on the
+  registry (never a dist-tag lookup, since `npm view @curviate/sdk version`
+  returns `latest` and this package's own RC/0.x releases route to `--tag
+  next`). Exits non-zero, loudly, when the CLI has not picked up the
+  release yet. It cannot undo the publish and does not try to; it replaces
+  the prior manual runbook step, which could not fail by construction
+  (the SDK-CLI drift-notice defect).
+- `check:clean` now flags a committed npm auth token (`npm_`-prefixed
+  shape), and `.npmrc`/`*.tgz` are gitignored. Same gap as the sibling
+  `cli` package's copy of this scanner (security-auditor F3).
 
 ## [0.24.3] - 2026-08-27
 

package/README.md

@@ -109,9 +109,26 @@ try {
       // err.retryAfterMs tells you exactly how long to wait
       await sleep(err.retryAfterMs ?? 5_000);
       break;
+    case "BUDGET_EXHAUSTED":
+      // Curviate's OWN account-safety ceiling, not a request-rate limit:
+      // nothing reached LinkedIn and nothing was spent, so backing off is the
+      // wrong move. Wait until err.resetAt, or raise the setting the hint
+      // names on PATCH /v1/{account_id}/safety-policy.
+      // resetAt is null in the two cases no clock frees: the pending_invites
+      // backlog, and an InMail credit pool LinkedIn regrants on its own schedule.
+      console.warn(`${err.budgetRow} is spent until ${err.resetAt ?? "no fixed time"}`);
+      console.warn(`change ${err.safetyHint?.parameter} to lift it`);
+      break;
     case "ACCOUNT_NOT_FOUND":
       console.error("Account does not exist for this tenant.");
       break;
+    case "NOT_STORED":
+      // A cache_only read the store could not answer, so nothing was fetched.
+      // The id may be perfectly good, so do not go looking for it again:
+      // re-read with mode "refill" or "auto", and on a narrowed listing drop
+      // the narrowing parameters. See "Retrieval modes" below.
+      console.warn("Nothing stored for that resource under this mode.");
+      break;
     default:
       if (err.retryLikelyToSucceed) {
         // Safe to retry: server-side transient error
@@ -127,6 +144,67 @@ exported `ErrorCode` type is the complete set, so `tsc` tells you when a `switch
 
 ---
 
+## Retrieval modes
+
+Some reads can be answered from Curviate's own store instead of a live LinkedIn
+fetch. Those reads take the same two query parameters, `mode` and `max_age`:
+
+- `users.get()`, including `users.get("me")` (`GET /v1/{account_id}/users/{user_id}`)
+- `messaging.getChat()` (`GET /v1/{account_id}/chats/{chat_id}`)
+- `messaging.listMessages()` (`GET /v1/{account_id}/chats/{chat_id}/messages`)
+
+No other read accepts them, so do not pass them elsewhere. These two keys are
+refused rather than ignored: sending either to a read that does not declare it
+is a `400`, and so is sending either one twice. A read that accepted
+`mode=cache_only` and then called LinkedIn anyway would break the one guarantee
+that parameter makes, so neither case is resolved quietly.
+
+| `mode` | What the read does |
+| --- | --- |
+| `auto` (default) | serves a stored copy while it is inside the resource's freshness threshold, otherwise fetches |
+| `live` | always fetches |
+| `refill` | serves a stored copy at any age, and fetches once when this read has none |
+| `cache_only` | never fetches, and throws `NOT_STORED` when the store cannot answer |
+
+`max_age` is the mechanism the first three are presets over: the oldest stored
+copy, in seconds, the read will accept. It overrides them in both directions,
+and `max_age: 0` is the same as `mode: "live"`. It cannot be combined with
+`cache_only`, whose guarantee is not a freshness threshold; that pair is
+rejected with `INVALID_REQUEST` rather than one of the two being quietly
+dropped.
+
+```ts
+// Serve whatever is stored, at any age; reach LinkedIn only if nothing is.
+const chat = await acc.messaging.getChat("chat_1", { mode: "refill" });
+
+// Never reach LinkedIn. Throws NOT_STORED when the store holds nothing.
+const profile = await acc.users.get("me", { mode: "cache_only" });
+
+// Accept a stored copy up to five minutes old, fetch otherwise.
+const page = await acc.messaging.listMessages("chat_1", { max_age: 300 });
+```
+
+Every one of these responses carries fields that say what you are holding:
+
+- `source` is `"store"` or `"live"`, and `observed_at` is when the data was seen
+  on LinkedIn. A stored answer can carry less than a live one, because some
+  fields are dropped before anything is written, so `source: "store"` is how you
+  know to ask again with `mode: "live"` when a field you need is missing.
+- `withdrawn` is always present, never inferred from a missing field. `true`
+  means LinkedIn has said the resource is gone, such as a removed profile, and
+  the answer you are holding is the copy Curviate still has: do not act on it.
+  `withdrawn_at` rides along when it is `true`. This is the field to branch on
+  before messaging or acting on anything served from the store, and `refill`,
+  which serves a copy at any age, is the mode most likely to hand you one.
+
+`NOT_STORED` under `cache_only` does not always mean the resource is unknown.
+On `listMessages` it also fires when the request narrows the page in a way the
+stored copy cannot reproduce, so a fully stored chat can refuse a narrowed
+`cache_only` read. Re-read without the narrowing parameters, or with a mode that
+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: