@curviate/sdk 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -7,6 +7,167 @@ Versioning: semantic. Minor for additive changes, patch for bug fixes; no stabil
 
 ---
 
+## [0.27.0] - 2026-09-06
+
+Fixture regenerated against the deployed production document
+(`https://api.curviate.com`, `server_git_sha 2a86542f...`, 125 paths).
+**BREAKING**: the `message.delivered` webhook event is gone from the catalogue,
+from `CurviateEvent`, and from the events a subscription can be created with.
+Everything else here is additive or description-only. Pre-1.0 a breaking change
+ships as a minor, so a caret range on `0.26.x` will not pick this up.
+
+### BREAKING
+
+- **`message.delivered` is removed from the webhook event catalogue.** The
+  platform never emitted it, so no `event.event === 'message.delivered'` branch
+  has ever run: the event was subscribable and undeliverable. Two surfaces lose
+  the member.
+  - `CurviateEvent` (hand-written, `src/webhooks.ts`) drops its
+    `{ event: "message.delivered"; data: MessagePayload }` arm, going from 25
+    arms to 24. A `switch` on `event.event` that still lists it stops
+    compiling, and that arm was dead code in every build it ever shipped in.
+  - The generated create-events enum, `events` on the `messaging` variant of
+    the `POST /v1/webhooks` request body
+    (`operations["postV1Webhooks"]["requestBody"]`), goes from 8 members to 7.
+    Passing `"message.delivered"` to a create call is now a type error, and the
+    server rejects the value.
+
+  The two are pinned to each other by an exact two-way type equality in
+  `test/webhooks.constructEvent.test.ts`, so they cannot drift apart: that pin
+  is what failed first on this regeneration.
+
+  `GET /v1/webhooks/events` now reports 27 events, messaging 7, where it
+  reported 28 and 8.
+
+  **The read path is untyped and deliberately unaffected.** `events` on a
+  webhook returned by `GET /v1/webhooks` or `GET /v1/webhooks/{id}` is
+  `string[]`, not the create enum. A subscription created before 2026-09-06 may
+  still echo `message.delivered` in its stored `events` until the server-side
+  cleanup migration lands; it was never delivered. Reading such a subscription
+  back therefore neither breaks a build nor throws, and no migration is
+  required of a consumer that only lists webhooks.
+
+  **The replacement is a read, not an event**: `is_delivered` on the message
+  resource.
+
+### Regenerated types
+
+- **BREAKING for an exhaustive `switch` - `notices[].code` gains
+  `EXPANSION_WITHHELD_CEILING`.** On the same ten chat and message reads that
+  accept `expand=public_identifier`, alongside `EXPANSION_LIMIT_REACHED` and
+  `EXPANSION_WITHHELD_ACTIVITY_WINDOW`. The expansion was withheld because the
+  account is at an account-safety ceiling, not because the page ran out of
+  lookup budget and not because the account is outside its activity window.
+  Same consequence for the reader as its two siblings, `public_identifier` is
+  `null` for a reason that is not "no public profile", and a different remedy,
+  which is why it is a separate code rather than a reuse. Additive on the wire:
+  only a `switch` with a `never`-typed default arm stops compiling.
+- Description-only, no type change:
+  - `SafetyWarning` now states that `hint.message` is the one field whose text
+    differs from the `BUDGET_EXHAUSTED` refusal. On a warn-posture ceiling
+    breach it says the action went through and how far past the ceiling the row
+    now stands, rather than telling the caller what was refused. The shape is
+    unchanged, so no branch moves; the string is longer and more specific.
+  - The `502` response documents that `retry_likely_to_succeed` is what
+    separates its two cases: a temporary upstream error is worth retrying, an
+    upstream response that could not be interpreted is not, and the latter
+    carries `retry_hint: {"kind": "never"}`. No new field, and the SDK's own
+    retry set is unchanged in this release.
+  - The `notices` description on the ten expansion reads now lists the ceiling
+    case as a third reason a person can go unresolved.
+
+## [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[]`

package/README.md

@@ -122,6 +122,13 @@ try {
     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
@@ -137,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: