@curviate/sdk 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -9,6 +9,82 @@ Versioning: semantic. Minor for additive changes, patch for bug fixes; no stabil
 
 ## [Unreleased]
 
+## [0.40.0] - 2026-10-01
+
+Fixture and types regenerated against the deployed production document
+(`https://api.curviate.com`, 130 paths, server
+`66421dcfa43949f2fd60b2872ef7fe3b16a79660`).
+
+### Changed
+
+- **A blank search filter or keyword is now refused with a `400`.** The
+  served document marks every free-text search filter and keyword
+  `minLength: 1`, and the server enforces it. A caller that sends an empty
+  string (`""`) for a filter or `keywords` used to get a search that ignored
+  it, and now gets `INVALID_REQUEST`. Omit the field instead of sending it
+  empty. The SDK does not validate this client-side, so the refusal comes from
+  the server. This is the one behaviour change in the release: callers that
+  pass `""` through from user input need to drop the key first.
+- **`POST /v1/auth/checkpoint/poll` and `POST /v1/auth/checkpoint/solve` now
+  return `409 ACCOUNT_ALREADY_LINKED` when the approved LinkedIn identity is
+  already connected.** On solve, the body carries `account_id` when the
+  existing account is yours, so you can reuse it. When the identity is held by
+  another workspace, poll and solve name no account and the error is not
+  retryable. The
+  `CHECKPOINT_EXPIRED`, `CHECKPOINT_ALREADY_RESOLVED` and
+  `CONNECTION_IN_PROGRESS` 409s are unchanged. The generated 409 descriptions
+  and the `ACCOUNT_ALREADY_LINKED` note in `errors.ts` say so.
+
+### Fixed
+
+- **`TOOLSET_DISABLED` and `AMBIGUOUS_IDENTIFIER` are now in the error
+  taxonomy.** The served `Error` type documents an extra field for each
+  (`toolset`, `candidates`), but the SDK did not carry either code, so a
+  response with one decoded to `INTERNAL`, which is retryable and reads as a
+  server fault. They now decode to themselves and are not retried. A new guard
+  reads the codes named in the `Error` extras descriptions from the fixture and
+  fails if the taxonomy lacks one.
+
+### Added
+
+- **The generated `Error` type documents the per-code extra fields**, each
+  optional and present only on its code: `portal_url` (`PAYMENT_REQUIRED`,
+  `ACCOUNT_DISPUTED`; `null` when no portal session could be opened),
+  `attempts_remaining` (`CHECKPOINT_INVALID_CODE`), `challenge_type`
+  (`CHECKPOINT_UNSUPPORTED`), `account_id` (`ACCOUNT_ALREADY_LINKED`), `quota`
+  (`RATE_LIMIT_ACCOUNT`), `toolset` (`TOOLSET_DISABLED`) and `candidates`
+  (`AMBIGUOUS_IDENTIFIER`, each `{ id, name }`). These are types only:
+  `CurviateError` does not surface them as properties yet, so read them from
+  the response body if you need them.
+
+## [0.39.0] - 2026-09-28
+
+Fixture and types regenerated against the deployed production document
+(`https://api.curviate.com`, 130 paths, server
+`006f3739c93ff758085dc0ad13ae423bafab4631`).
+
+### Changed
+
+- **The retry decision now honours an explicit `retry_likely_to_succeed:
+  false`.** A GET on a retryable code (`INTERNAL`, `PLATFORM_ERROR`,
+  `PLATFORM_RATE_LIMIT`, `RATE_LIMIT_ACCOUNT`, `RATE_LIMIT_TENANT`) whose
+  envelope says `retry_likely_to_succeed: false` is no longer retried, with or
+  without a `retry_hint`. The server now sends `false` only as a verdict that
+  an unchanged retry fails the same way, and `true` for a failure whose cause
+  it cannot see, so this closes the half of the 0.37.1 fix that was deferred.
+  A response with no JSON envelope, or no such field, still retries on the
+  code table alone. Requires a server that includes the change; against an
+  older server, unexpected `INTERNAL` and `PLATFORM_ERROR` failures would stop
+  being retried.
+- **`accounts.addSeats()` documents its new failure shapes.** A `502` means
+  the purchase failed after today's charge was taken; the charge was refunded
+  in full and the seat count was confirmed unchanged, so no seats were added
+  and it is safe to retry. A `503 STRIPE_DRIFT_DETECTED` means the seat price
+  is misconfigured on our side: nothing was charged, this is not something you
+  can fix, and retrying fails the same way until the price is corrected.
+  Contact support. Both are generated-type/description additions; no
+  resource-method shape changed.
+
 ## [0.38.0] - 2026-09-26
 
 Fixture and types regenerated against the deployed production document

package/dist/index.d.ts

@@ -2878,6 +2878,25 @@ interface components {
                     name?: string;
                 }[];
             }[];
+            /** @description Present on PAYMENT_REQUIRED and ACCOUNT_DISPUTED: the self-service page where the tenant resolves the payment problem, so an agent can hand a human one link. Null when no portal session could be opened; fall back to the dashboard. */
+            portal_url?: string | null;
+            /** @description Present on CHECKPOINT_INVALID_CODE: how many more verification codes the checkpoint accepts before it locks. Stop and ask the account owner for a fresh code when it reaches zero, rather than guessing. */
+            attempts_remaining?: number;
+            /** @description Present on CHECKPOINT_UNSUPPORTED: the kind of verification challenge LinkedIn raised that cannot be solved through this API. A human has to complete it in LinkedIn, then the account reconnects. */
+            challenge_type?: string;
+            /** @description Present on ACCOUNT_ALREADY_LINKED: the id of your own existing account for this LinkedIn profile, so you can reuse it instead of linking again. Only ever an account of the calling tenant. */
+            account_id?: string;
+            /** @description Present on RATE_LIMIT_ACCOUNT: the per-account request ceiling that was breached, with its name, the units remaining and total, and the absolute reset_time. Wait until reset_time before retrying. */
+            quota?: Record<string, never>;
+            /** @description Present on TOOLSET_DISABLED: the name of the toolset that is switched off for this tenant, so you can enable it or use another tool. */
+            toolset?: string;
+            /** @description Present on AMBIGUOUS_IDENTIFIER: the entries the identifier matched. Pick one and re-send its id. */
+            candidates?: {
+                /** @description The id to send instead of the ambiguous identifier. */
+                id?: string;
+                /** @description Human-readable label for this entry. */
+                name?: string;
+            }[];
             /** @description Present on errors that can be recovered programmatically, a plain sentence describing the next call to make. */
             next_action?: string;
             /** @description Present when something about this response is true but not visible in it. On a search, an entry names a filter value we could not check before sending it, or reports that some of the people on the page were not disclosed to the connected account, so an unexpected result count is explicable rather than silent. Branch on each entry's code, never on its message. */
@@ -28960,7 +28979,7 @@ interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description The checkpoint has expired. */
+            /** @description CHECKPOINT_EXPIRED or CHECKPOINT_ALREADY_RESOLVED: restart the connection. ACCOUNT_ALREADY_LINKED: the LinkedIn identity is already connected; it names your own account_id when you own it, otherwise it is not one you can manage here. CONNECTION_IN_PROGRESS: another connection attempt for this identity is open; wait for it to finish or expire. */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -29310,7 +29329,7 @@ interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description The approved LinkedIn identity is already linked to another account. Reconnect or disconnect the existing account instead of linking it again. */
+            /** @description ACCOUNT_ALREADY_LINKED. The approved LinkedIn identity is already connected and is not one you can manage here; not retryable. CONNECTION_IN_PROGRESS. Another connection attempt for this identity is open; wait for it to finish or expire. */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -31778,7 +31797,16 @@ interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description The purchase could not be confirmed while another change was in progress. Check the seat count before retrying. */
+            /** @description The purchase failed after today's charge was taken; the charge was refunded in full and the seat count was confirmed unchanged, so no seats were added. Safe to retry. */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description The purchase could not be confirmed while another change was in progress (check the seat count before retrying), or the seat price is misconfigured on our side (nothing charged; contact support, retrying fails the same way). */
             503: {
                 headers: {
                     [name: string]: unknown;
@@ -31956,7 +31984,7 @@ interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Another change to this subscription is in progress. Retry shortly. */
+            /** @description Another change to this subscription is in progress (retry shortly), or the seat price is misconfigured on our side (nothing charged; contact support, retrying fails the same way). */
             503: {
                 headers: {
                     [name: string]: unknown;
@@ -34472,7 +34500,7 @@ declare class Curviate {
  * A code the API NEVER emitted is a different case and goes immediately, since
  * no deployment can be sending it: `RATE_LIMITED` went that way in 0.30.0.
  */
-declare const ERROR_CODES: readonly ["UNAUTHORIZED", "INVALID_REQUEST", "UNSUPPORTED_MEDIA_TYPE", "PAYLOAD_TOO_LARGE", "ACCOUNT_NOT_FOUND", "ACCOUNT_RESTRICTED", "ACCOUNT_ALREADY_LINKED", "RESOURCE_NOT_FOUND", "NOT_STORED", "RESOURCE_ACCESS_RESTRICTED", "FILTER_CANDIDATES_REQUIRED", "NO_ACTIVE_SEAT", "LINKEDIN_FEATURE_NOT_SUBSCRIBED", "BETA_NOT_ENABLED", "RATE_LIMIT_ACCOUNT", "RATE_LIMIT_TENANT", "PLATFORM_RATE_LIMIT", "BUDGET_EXHAUSTED", "PLATFORM_ERROR", "PLATFORM_NOT_IMPLEMENTED", "LINKEDIN_OPERATION_NOT_SUPPORTED", "CHECKPOINT_NOT_FOUND", "CHECKPOINT_EXPIRED", "CHECKPOINT_INVALID_CODE", "CHECKPOINT_MAX_ATTEMPTS", "CHECKPOINT_ALREADY_RESOLVED", "CHECKPOINT_UNSUPPORTED", "CONNECTION_IN_PROGRESS", "REAUTH_REQUIRED", "LINKEDIN_AUTH_FAILED", "LINKEDIN_SESSION_EVICTED", "LINKEDIN_RATE_LIMITED", "LINKEDIN_COOKIE_INVALID", "LINKEDIN_SERVICE_UNAVAILABLE", "MESSAGE_WINDOW_EXPIRED", "RECIPIENT_UNREACHABLE", "CONNECTION_REQUEST_CONFLICT", "PAYMENT_REQUIRED", "PAYMENT_FAILED", "SUBSCRIPTION_BUSY", "SUBSCRIPTION_NOT_FOUND", "SEAT_NOT_FOUND", "SEAT_CANCELLED", "NOT_FOUND", "REACTION_NOT_FOUND", "SUBSTRATE_LINK_FAILED", "SUBSTRATE_CAP_REACHED", "BILLING_CHECKOUT_FAILED", "BILLING_PORTAL_UNAVAILABLE", "ACCOUNT_DISPUTED", "ACCOUNT_LINKING_DISABLED", "PERIOD_LOCKED", "SEAT_NOT_EMPTY", "SEAT_PROVISIONAL", "SUBSCRIPTION_ALREADY_EXISTS", "ALREADY_CANCELLED", "CANCELLATION_ALREADY_EFFECTIVE", "INVALID_CANCELLATION_SOURCE", "TRIAL_EXPIRED", "TRIAL_SEAT_LIMIT", "TRIAL_ACTIVE_SEAT_LIMIT", "TRIAL_IDENTITY_ALREADY_USED", "TRIAL_IDENTITY_UNRESOLVED", "ADMIN_BYPASS", "STRIPE_DRIFT_DETECTED", "INTERNAL"];
+declare const ERROR_CODES: readonly ["UNAUTHORIZED", "INVALID_REQUEST", "UNSUPPORTED_MEDIA_TYPE", "PAYLOAD_TOO_LARGE", "ACCOUNT_NOT_FOUND", "ACCOUNT_RESTRICTED", "ACCOUNT_ALREADY_LINKED", "RESOURCE_NOT_FOUND", "NOT_STORED", "RESOURCE_ACCESS_RESTRICTED", "FILTER_CANDIDATES_REQUIRED", "NO_ACTIVE_SEAT", "LINKEDIN_FEATURE_NOT_SUBSCRIBED", "BETA_NOT_ENABLED", "RATE_LIMIT_ACCOUNT", "RATE_LIMIT_TENANT", "PLATFORM_RATE_LIMIT", "BUDGET_EXHAUSTED", "PLATFORM_ERROR", "PLATFORM_NOT_IMPLEMENTED", "LINKEDIN_OPERATION_NOT_SUPPORTED", "CHECKPOINT_NOT_FOUND", "CHECKPOINT_EXPIRED", "CHECKPOINT_INVALID_CODE", "CHECKPOINT_MAX_ATTEMPTS", "CHECKPOINT_ALREADY_RESOLVED", "CHECKPOINT_UNSUPPORTED", "CONNECTION_IN_PROGRESS", "REAUTH_REQUIRED", "LINKEDIN_AUTH_FAILED", "LINKEDIN_SESSION_EVICTED", "LINKEDIN_RATE_LIMITED", "LINKEDIN_COOKIE_INVALID", "LINKEDIN_SERVICE_UNAVAILABLE", "MESSAGE_WINDOW_EXPIRED", "RECIPIENT_UNREACHABLE", "CONNECTION_REQUEST_CONFLICT", "PAYMENT_REQUIRED", "PAYMENT_FAILED", "SUBSCRIPTION_BUSY", "SUBSCRIPTION_NOT_FOUND", "SEAT_NOT_FOUND", "SEAT_CANCELLED", "NOT_FOUND", "REACTION_NOT_FOUND", "SUBSTRATE_LINK_FAILED", "SUBSTRATE_CAP_REACHED", "BILLING_CHECKOUT_FAILED", "BILLING_PORTAL_UNAVAILABLE", "ACCOUNT_DISPUTED", "ACCOUNT_LINKING_DISABLED", "PERIOD_LOCKED", "SEAT_NOT_EMPTY", "SEAT_PROVISIONAL", "SUBSCRIPTION_ALREADY_EXISTS", "ALREADY_CANCELLED", "CANCELLATION_ALREADY_EFFECTIVE", "INVALID_CANCELLATION_SOURCE", "TRIAL_EXPIRED", "TRIAL_SEAT_LIMIT", "TRIAL_ACTIVE_SEAT_LIMIT", "TRIAL_IDENTITY_ALREADY_USED", "TRIAL_IDENTITY_UNRESOLVED", "ADMIN_BYPASS", "STRIPE_DRIFT_DETECTED", "TOOLSET_DISABLED", "AMBIGUOUS_IDENTIFIER", "INTERNAL"];
 /**
  * The complete set of error codes observable by API callers.
  *

package/dist/index.js

@@ -8,8 +8,10 @@ var ERROR_CODES = [
   // Account state
   "ACCOUNT_NOT_FOUND",
   "ACCOUNT_RESTRICTED",
-  // Duplicate connect: reconnect or adopt the existing account instead of
-  // linking again. Not retryable.
+  // Duplicate connect (409): the LinkedIn identity is already connected. When
+  // your own tenant holds it the body carries `account_id`, so reuse that
+  // account instead of linking again; when another tenant holds it the body
+  // names no account and there is nothing you can manage here. Not retryable.
   "ACCOUNT_ALREADY_LINKED",
   "RESOURCE_NOT_FOUND",
   // A read found nothing in Curviate's store and its mode may not fetch, so it
@@ -165,6 +167,16 @@ var ERROR_CODES = [
   // was charged. Stop and surface it to a human (or support) rather than
   // backing off.
   "STRIPE_DRIFT_DETECTED",
+  // Agent-surface refusals the served Error component documents (their extras
+  // are `toolset` and `candidates`). Both are user_fixable and never
+  // retryable as sent.
+  //
+  // - `TOOLSET_DISABLED`: the toolset the call needs is switched off for this
+  //   tenant. Enable it or use another tool.
+  // - `AMBIGUOUS_IDENTIFIER`: a name matched several entries. Pick one from
+  //   `candidates` and re-send its id.
+  "TOOLSET_DISABLED",
+  "AMBIGUOUS_IDENTIFIER",
   // Generic
   "INTERNAL"
 ];
@@ -300,7 +312,7 @@ async function errorFromResponse(res) {
   }
   const safetyHint = toSafetyHint(env?.hint);
   const safetyReason = toSafetyReason(env?.reason);
-  return new CurviateError({
+  const err = new CurviateError({
     code: toErrorCode(env?.code),
     message: env?.message ?? `Request failed with status ${res.status}.`,
     httpStatus: res.status,
@@ -325,6 +337,7 @@ async function errorFromResponse(res) {
     ...safetyReason !== void 0 ? { safetyReason } : {},
     ...typeof env?.blocked === "boolean" ? { blocked: env.blocked } : {}
   });
+  return { err, refusesRetry: env?.retry_likely_to_succeed === false };
 }
 function retryDelay(err, attempt, jitter) {
   if (err.retryAfterMs !== void 0) return err.retryAfterMs;
@@ -405,9 +418,9 @@ async function execute(method, path, opts) {
     if (res.ok) {
       return parseSuccess(res);
     }
-    const err = await errorFromResponse(res);
+    const { err, refusesRetry } = await errorFromResponse(res);
     const namesBudgetRow = err.budgetRow !== void 0;
-    const neverRetry = err.retryHint?.kind === "never";
+    const neverRetry = err.retryHint?.kind === "never" || refusesRetry;
     const retryable = !isWrite && !namesBudgetRow && !neverRetry && RETRYABLE_CODES.has(err.code) && attempt < opts.maxRetries;
     if (retryable) {
       await sleep(retryDelay(err, attempt + 1, jitterFn()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curviate/sdk",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "private": false,
   "description": "TypeScript SDK for the Curviate API.",
   "license": "MIT",

package/src/generated/types.ts

@@ -2781,6 +2781,25 @@ export interface components {
                     name?: string;
                 }[];
             }[];
+            /** @description Present on PAYMENT_REQUIRED and ACCOUNT_DISPUTED: the self-service page where the tenant resolves the payment problem, so an agent can hand a human one link. Null when no portal session could be opened; fall back to the dashboard. */
+            portal_url?: string | null;
+            /** @description Present on CHECKPOINT_INVALID_CODE: how many more verification codes the checkpoint accepts before it locks. Stop and ask the account owner for a fresh code when it reaches zero, rather than guessing. */
+            attempts_remaining?: number;
+            /** @description Present on CHECKPOINT_UNSUPPORTED: the kind of verification challenge LinkedIn raised that cannot be solved through this API. A human has to complete it in LinkedIn, then the account reconnects. */
+            challenge_type?: string;
+            /** @description Present on ACCOUNT_ALREADY_LINKED: the id of your own existing account for this LinkedIn profile, so you can reuse it instead of linking again. Only ever an account of the calling tenant. */
+            account_id?: string;
+            /** @description Present on RATE_LIMIT_ACCOUNT: the per-account request ceiling that was breached, with its name, the units remaining and total, and the absolute reset_time. Wait until reset_time before retrying. */
+            quota?: Record<string, never>;
+            /** @description Present on TOOLSET_DISABLED: the name of the toolset that is switched off for this tenant, so you can enable it or use another tool. */
+            toolset?: string;
+            /** @description Present on AMBIGUOUS_IDENTIFIER: the entries the identifier matched. Pick one and re-send its id. */
+            candidates?: {
+                /** @description The id to send instead of the ambiguous identifier. */
+                id?: string;
+                /** @description Human-readable label for this entry. */
+                name?: string;
+            }[];
             /** @description Present on errors that can be recovered programmatically, a plain sentence describing the next call to make. */
             next_action?: string;
             /** @description Present when something about this response is true but not visible in it. On a search, an entry names a filter value we could not check before sending it, or reports that some of the people on the page were not disclosed to the connected account, so an unexpected result count is explicable rather than silent. Branch on each entry's code, never on its message. */
@@ -28864,7 +28883,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description The checkpoint has expired. */
+            /** @description CHECKPOINT_EXPIRED or CHECKPOINT_ALREADY_RESOLVED: restart the connection. ACCOUNT_ALREADY_LINKED: the LinkedIn identity is already connected; it names your own account_id when you own it, otherwise it is not one you can manage here. CONNECTION_IN_PROGRESS: another connection attempt for this identity is open; wait for it to finish or expire. */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -29214,7 +29233,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description The approved LinkedIn identity is already linked to another account. Reconnect or disconnect the existing account instead of linking it again. */
+            /** @description ACCOUNT_ALREADY_LINKED. The approved LinkedIn identity is already connected and is not one you can manage here; not retryable. CONNECTION_IN_PROGRESS. Another connection attempt for this identity is open; wait for it to finish or expire. */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -31682,7 +31701,16 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description The purchase could not be confirmed while another change was in progress. Check the seat count before retrying. */
+            /** @description The purchase failed after today's charge was taken; the charge was refunded in full and the seat count was confirmed unchanged, so no seats were added. Safe to retry. */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description The purchase could not be confirmed while another change was in progress (check the seat count before retrying), or the seat price is misconfigured on our side (nothing charged; contact support, retrying fails the same way). */
             503: {
                 headers: {
                     [name: string]: unknown;
@@ -31860,7 +31888,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Another change to this subscription is in progress. Retry shortly. */
+            /** @description Another change to this subscription is in progress (retry shortly), or the seat price is misconfigured on our side (nothing charged; contact support, retrying fails the same way). */
             503: {
                 headers: {
                     [name: string]: unknown;