@curviate/sdk 0.24.3 → 0.26.0

package/dist/index.js

@@ -12,6 +12,14 @@ var ERROR_CODES = [
   // linking again. Not retryable.
   "ACCOUNT_ALREADY_LINKED",
   "RESOURCE_NOT_FOUND",
+  // A read found nothing in Curviate's store and its mode may not fetch, so it
+  // refused rather than reaching LinkedIn. 422, and NOT RESOURCE_NOT_FOUND: the
+  // resource may be perfectly real, so the fix is another mode, not another id.
+  // Absent from RETRYABLE_CODES on purpose, nothing about the answer changes
+  // until the caller picks one.
+  //
+  // `cache_only` is the mode that raises it; re-read with `refill` or `auto`.
+  "NOT_STORED",
   "RESOURCE_ACCESS_RESTRICTED",
   // Search filter resolution: a plain-string filter value matched several
   // LinkedIn taxonomy options and one has to be picked (422). The body carries
@@ -31,6 +39,14 @@ var ERROR_CODES = [
   // response headers). Distinct from the account/tenant/platform trio above.
   // Always retry-safe (retry_likely_to_succeed: true); see RETRYABLE_CODES.
   "RATE_LIMITED",
+  // Curviate's OWN account-safety ceiling, not a request-rate limit and not
+  // LinkedIn refusing. A 429 that never reached LinkedIn and spent nothing:
+  // the budget row named by `budgetRow` is at the ceiling configured on
+  // `PATCH /v1/{account_id}/safety-policy`, or the account is outside its
+  // activity window. Deliberately absent from RETRYABLE_CODES: a monthly
+  // row's reset can be weeks out, so backing off is the wrong recovery.
+  // Read `resetAt`, `safetyReason` and `safetyHint` instead.
+  "BUDGET_EXHAUSTED",
   // Platform errors
   "PLATFORM_ERROR",
   "PLATFORM_NOT_IMPLEMENTED",
@@ -60,6 +76,14 @@ var ERROR_CODES = [
   "REAUTH_REQUIRED",
   // LinkedIn-specific connect errors
   "LINKEDIN_AUTH_FAILED",
+  // LinkedIn allows only one session at a time for some accounts, so a person
+  // signing in elsewhere breaks this one. A 401 like LINKEDIN_AUTH_FAILED and a
+  // separate code because the remedy differs and the auth one prescribes the
+  // wrong remedy: reconnecting does nothing while the other session is open.
+  // user_fixable, never retryable: a person has to close the other session.
+  // While it lasts, `account_states` on the account resource carries
+  // `recruiter_session_evicted`.
+  "LINKEDIN_SESSION_EVICTED",
   "LINKEDIN_RATE_LIMITED",
   "LINKEDIN_COOKIE_INVALID",
   "LINKEDIN_SERVICE_UNAVAILABLE",
@@ -94,6 +118,12 @@ var CurviateError = class _CurviateError extends Error {
     this.retryLikelyToSucceed = init.retryLikelyToSucceed;
     this.requiredTier = init.requiredTier;
     this.retryAfterMs = init.retryAfterMs;
+    this.budgetRow = init.budgetRow;
+    this.retryAfterSeconds = init.retryAfterSeconds;
+    this.resetAt = init.resetAt;
+    this.safetyHint = init.safetyHint;
+    this.safetyReason = init.safetyReason;
+    this.blocked = init.blocked;
     Object.setPrototypeOf(this, _CurviateError.prototype);
   }
   /**
@@ -113,6 +143,12 @@ var CurviateError = class _CurviateError extends Error {
     if (this.httpStatus !== void 0) json.httpStatus = this.httpStatus;
     if (this.requiredTier !== void 0) json.requiredTier = this.requiredTier;
     if (this.retryAfterMs !== void 0) json.retryAfterMs = this.retryAfterMs;
+    if (this.budgetRow !== void 0) json.budgetRow = this.budgetRow;
+    if (this.retryAfterSeconds !== void 0) json.retryAfterSeconds = this.retryAfterSeconds;
+    if (this.resetAt !== void 0) json.resetAt = this.resetAt;
+    if (this.safetyHint !== void 0) json.safetyHint = this.safetyHint;
+    if (this.safetyReason !== void 0) json.safetyReason = this.safetyReason;
+    if (this.blocked !== void 0) json.blocked = this.blocked;
     return json;
   }
 };
@@ -152,6 +188,11 @@ var RETRYABLE_CODES = /* @__PURE__ */ new Set([
   "RATE_LIMIT_ACCOUNT",
   "RATE_LIMIT_TENANT",
   "RATE_LIMITED"
+  // BUDGET_EXHAUSTED is deliberately NOT here, even though it is a 429. It is
+  // Curviate's own account-safety ceiling rather than a request-rate limit:
+  // nothing reached LinkedIn, nothing was spent, and a monthly row's reset can
+  // be weeks out, so a backoff loop burns retries against a wall that will not
+  // move. The recovery is `resetAt` / `safetyHint`, not a sleep.
 ]);
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PATCH", "PUT", "DELETE"]);
 function defaultSleep(ms) {
@@ -170,6 +211,15 @@ function backoffDelay(n, jitter) {
 function toErrorCode(code) {
   return code && KNOWN_ERROR_CODES.has(code) ? code : "INTERNAL";
 }
+function toSafetyHint(hint) {
+  if (!hint || typeof hint !== "object") return void 0;
+  const { parameter, message } = hint;
+  if (typeof parameter !== "string" || typeof message !== "string") return void 0;
+  return { parameter, message };
+}
+function toSafetyReason(reason) {
+  return reason === "ceiling" || reason === "activity_window" ? reason : void 0;
+}
 function toRetryHint(hint) {
   if (!hint || typeof hint !== "object") return null;
   const kind = hint.kind;
@@ -187,6 +237,8 @@ async function errorFromResponse(res) {
     env = void 0;
   }
   const requiredTier = env?.required_tier && KNOWN_REQUIRED_TIERS.has(env.required_tier) ? env.required_tier : void 0;
+  const safetyHint = toSafetyHint(env?.hint);
+  const safetyReason = toSafetyReason(env?.reason);
   return new CurviateError({
     code: toErrorCode(env?.code),
     message: env?.message ?? `Request failed with status ${res.status}.`,
@@ -195,7 +247,23 @@ async function errorFromResponse(res) {
     userFixable: env?.user_fixable ?? false,
     retryLikelyToSucceed: env?.retry_likely_to_succeed ?? false,
     ...requiredTier !== void 0 ? { requiredTier } : {},
-    ...retryAfterMs !== void 0 ? { retryAfterMs } : {}
+    ...retryAfterMs !== void 0 ? { retryAfterMs } : {},
+    ...typeof env?.row === "string" ? { budgetRow: env.row } : {},
+    // `retry_after` is DELIBERATELY NOT folded into `retryAfterMs`. Everything
+    // that reads `retryAfterMs` SLEEPS it, on reads and on writes; a paused
+    // budget row can be paused for an hour, and turning that into an hour-long
+    // sleep inside a client call would be a hang, not a backoff. It stays on
+    // `retryAfterSeconds` for the caller to decide about, next to `budgetRow`,
+    // which is the field that says what to do instead: switch work.
+    ...typeof env?.retry_after === "number" && Number.isFinite(env.retry_after) ? { retryAfterSeconds: env.retry_after } : {},
+    // `reset_at` is null-BEARING: null means "no clock frees this" (the
+    // pending_invites gauge, or an InMail credit exhaustion), which is a
+    // different fact from the field being absent, so both survive the round
+    // trip.
+    ...typeof env?.reset_at === "string" || env?.reset_at === null ? { resetAt: env.reset_at } : {},
+    ...safetyHint !== void 0 ? { safetyHint } : {},
+    ...safetyReason !== void 0 ? { safetyReason } : {},
+    ...typeof env?.blocked === "boolean" ? { blocked: env.blocked } : {}
   });
 }
 function retryDelay(err, attempt, jitter) {
@@ -278,7 +346,8 @@ async function execute(method, path, opts) {
       return parseSuccess(res);
     }
     const err = await errorFromResponse(res);
-    const retryable = !isWrite && RETRYABLE_CODES.has(err.code) && attempt < opts.maxRetries;
+    const namesBudgetRow = err.budgetRow !== void 0;
+    const retryable = !isWrite && !namesBudgetRow && RETRYABLE_CODES.has(err.code) && attempt < opts.maxRetries;
     if (retryable) {
       await sleep(retryDelay(err, attempt + 1, jitterFn()));
       attempt += 1;
@@ -388,8 +457,31 @@ var AccountsResource = class {
   }
   /**
    * Return metadata and current state for one connected account, including the
-   * central `quotas[]` view for all tracked quota families and `seat_id` (the
-   * seat this account occupies, `null` for an admin seatless account).
+   * central `quotas[]` account-safety view, `account_states[]` and `seat_id`
+   * (the seat this account occupies, `null` for an admin seatless account).
+   *
+   * `quotas[]` REPLACED its earlier `quota_name` / `remaining` / `total` /
+   * `reset_time` / `recommended_throttle_hint` shape. Each row now reports
+   * `budget_row`, `kind`, `used`, `ceiling`, `effective_ceiling`, `band`,
+   * `posture`, `over_default`, `halt` and the window fields. **Compare `used`
+   * against `effective_ceiling`, not `ceiling`**: the effective one is the
+   * ceiling with the account's warm-up ramp applied, and on a new account the
+   * two differ by roughly a factor of seven. `posture` says what happens at the
+   * ceiling and defaults to `warn`, so nothing here refuses until it is
+   * configured to. Two rows are not counters and say so in `kind`:
+   * `total_actions` (`tally`) and `pending_invites` (`gauge`, whose `used` is
+   * `null` until something has observed it).
+   *
+   * The per-minute REQUEST ceiling is a different thing and is deliberately
+   * NOT in this array: it protects Curviate's own servers rather than the
+   * LinkedIn account, and it is always enforced with `429` whatever the
+   * posture.
+   *
+   * `account_states[]` lists platform conditions the account is in right now,
+   * additive to `status` and independent of it: `recruiter_session_evicted`,
+   * `commercial_use_limited`, `profile_view_limited`. The last two are read on
+   * calls that SUCCEEDED, so check them before concluding thin results are
+   * wrong. Empty for an unaffected account.
    *
    * This is a stale-while-revalidate read; it always returns immediately
    * from the cached row (never blocks on a live substrate call). The cached
@@ -569,11 +661,19 @@ var MessagingResource = class {
       body
     });
   }
-  /** Get details of a single chat. `GET /v1/{account_id}/chats/{chat_id}` */
-  getChat(chatId) {
+  /**
+   * Get details of a single chat. `GET /v1/{account_id}/chats/{chat_id}`
+   *
+   * A store-servable read: `{ mode, max_age }` says how willing it is to reach
+   * LinkedIn, and the response's `source` says which way the answer came. See
+   * "Retrieval modes" in the README for the four modes and what `max_age`
+   * overrides.
+   */
+  getChat(chatId, params) {
     return this.ctx.request({
       method: "GET",
-      path: apiPath`/v1/{account_id}/chats/${chatId}`
+      path: apiPath`/v1/{account_id}/chats/${chatId}`,
+      ...params ? { query: params } : {}
     });
   }
   /**
@@ -698,6 +798,16 @@ var MessagingResource = class {
    * Free-text search the account's own inbox; matches participant names
    * and message content. `GET /v1/{account_id}/chats/search`
    *
+   * SERVED FROM CURVIATE'S STORE, not from LinkedIn: it costs no platform call
+   * and draws down no account-safety budget, and a chat that has never been
+   * retrieved for this account cannot match. Read `coverage` on the response to
+   * see how complete the searched corpus is before treating an empty result as
+   * "no such conversation".
+   *
+   * A result's `type` is `1to1`, `group` or `channel`. It used to be documented
+   * as never a channel; that is no longer true, so a caller switching on `type`
+   * needs the third arm.
+   *
    * @param params - `query` (required free-text term) plus `limit` and an
    *   opaque `cursor` for pagination.
    */
@@ -2769,6 +2879,7 @@ async function constructEvent(rawBody, signatureHeader, secret, opts) {
 export {
   Curviate,
   CurviateError,
+  ERROR_CODES,
   WebhookSignatureError,
   constructEvent,
   isCurviateError

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curviate/sdk",
-  "version": "0.24.3",
+  "version": "0.26.0",
   "private": false,
   "description": "TypeScript SDK for the Curviate API.",
   "license": "MIT",
@@ -38,6 +38,7 @@
   "scripts": {
     "build": "tsup",
     "prepack": "node scripts/check-clean.mjs && node scripts/check-copy.mjs && tsup && node scripts/check-clean.mjs --dist",
+    "check:cli-notice": "node scripts/check-cli-notice.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
@@ -58,6 +59,7 @@
     "@types/node": "^22.15.21",
     "msw": "^2.7.0",
     "openapi-typescript": "7.6.1",
+    "semver": "^7.8.5",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^3.2.2"