@curviate/sdk 0.37.1 → 0.39.0

package/dist/index.js

@@ -300,7 +300,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 +325,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 +406,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()));
@@ -502,12 +503,19 @@ var AccountsResource = class {
    * `signatures`, `groups`) populated by an async background enrichment,
    * `null`/`[]` until the account's first enrichment pass completes.
    *
-   * @param params - optional `limit` (1-250) and `cursor` (from a prior page).
+   * Each item carries `external_id` (your own id for the account's end user,
+   * set on `auth.intent` or `update`) and `metadata`, both `null` when unset.
+   *
+   * @param params - optional `limit` (1-250), `cursor` (from a prior page), and
+   *   `external_id` (exact match: only that end user's accounts).
    * @returns a page of accounts and the next-page `cursor` (null when exhausted).
    *
    * @example
    * const page = await curviate.accounts.list({ limit: 50 });
    * for (const acc of page.items ?? []) console.log(acc.account_id);
+   *
+   * @example
+   * const { items } = await curviate.accounts.list({ external_id: "usr_42" });
    */
   list(params) {
     return this.ctx.request({
@@ -582,11 +590,18 @@ var AccountsResource = class {
   /**
    * Update an account's configuration.
    *
-   * `metadata` is a flat string->string map that **replaces** the account's
-   * custom-data store wholesale (keys not provided are removed). `proxy` sets a
-   * custom egress proxy, or clears it (reverting to automatic proxy protection)
-   * when passed as `null`. The `proxy.password`, if given, is stored securely
-   * and never returned.
+   * `external_id` is your own id for the account's end user (1-255 chars, not
+   * unique, `null` clears it); treat it as an opaque id, not an email.
+   * `metadata` is a flat string->string map (at most 16 keys, key 40 chars,
+   * value 500) that **replaces** the stored map wholesale; `null` clears it.
+   * Both are stored by Curviate, read back on `get`/`list`, and a PATCH
+   * carrying only them makes no LinkedIn call. `proxy` sets a custom egress
+   * proxy, or clears it (reverting to automatic proxy protection) when passed
+   * as `null`. The `proxy.password`, if given, is stored securely and never
+   * returned.
+   *
+   * @example
+   * await curviate.accounts.update("acc_123", { external_id: "usr_42", metadata: { plan: "pro" } });
    */
   update(accountId, body) {
     return this.ctx.request({
@@ -604,6 +619,63 @@ var AccountsResource = class {
       path: apiPath`/v1/accounts/${accountId}`
     });
   }
+  /**
+   * Buy seats on the workspace's active subscription. Returns the new
+   * `seat_ids`; connect an account into one with `auth.intent({ seat_id })`.
+   *
+   * Every call buys the `qty` it asks for, so a repeated call buys again.
+   * The SDK never retries it for you. A
+   * `CurviateError(code: "SUBSCRIPTION_BUSY")` (503) means the purchase could
+   * not be confirmed while another change was in progress: check the seat
+   * count with `listSeats()` before trying again. A trialing workspace
+   * throws `CurviateError(code: "TRIAL_ACTIVE_SEAT_LIMIT")`: buy a seat to
+   * convert first.
+   *
+   * @param body - `{ qty }`, 1-50.
+   *
+   * @example
+   * const { seat_ids } = await curviate.accounts.addSeats({ qty: 1 });
+   */
+  addSeats(body) {
+    return this.ctx.request({ method: "POST", path: "/v1/billing/seats/add", body });
+  }
+  /**
+   * Schedule a seat's cancellation at the end of the current period.
+   * `effective_at` is when access ends; until then the seat keeps working
+   * and `revertSeatCancellation()` can undo it. Repeating the call on an
+   * already-scheduled seat returns the same `effective_at`; a seat whose
+   * cancellation already took effect throws
+   * `CurviateError(code: "ALREADY_CANCELLED")`.
+   *
+   * @param seatId - a `seat_...` id from `listSeats()`.
+   *
+   * @example
+   * const { effective_at } = await curviate.accounts.cancelSeat("seat_123");
+   */
+  cancelSeat(seatId) {
+    return this.ctx.request({
+      method: "POST",
+      path: apiPath`/v1/billing/seats/${seatId}/cancel`
+    });
+  }
+  /**
+   * Undo a scheduled seat cancellation before it takes effect. A seat with
+   * nothing scheduled (never cancelled, already reverted, or already
+   * effective) throws `CurviateError(code: "CANCELLATION_ALREADY_EFFECTIVE")`;
+   * a seat covered by a whole-subscription cancellation throws
+   * `CurviateError(code: "INVALID_CANCELLATION_SOURCE")`.
+   *
+   * @param seatId - the `seat_...` id passed to `cancelSeat()`.
+   *
+   * @example
+   * await curviate.accounts.revertSeatCancellation("seat_123");
+   */
+  revertSeatCancellation(seatId) {
+    return this.ctx.request({
+      method: "POST",
+      path: apiPath`/v1/billing/seats/${seatId}/cancel/revert`
+    });
+  }
 };
 
 // src/resources/auth.ts
@@ -683,20 +755,36 @@ var AuthResource = class {
     });
   }
   /**
-   * Re-request the pending checkpoint notification (OTP / 2FA / mobile-app
-   * push). `resent` is honest: `true` once the notification was actually
-   * re-sent, `false` when there was nothing to re-send for that challenge
-   * type (e.g. an authenticator-app code); this call never throws just
+   * Re-send the pending checkpoint code, or switch its verification method.
+   *
+   * Without `body`: re-requests the pending notification (OTP / 2FA /
+   * mobile-app push) and returns 200 `{ resent }`. `resent` is honest: `true`
+   * once the notification was actually re-sent, `false` when there was
+   * nothing to re-send for that challenge type (e.g. an authenticator-app
+   * code, or a `challenge_selection` checkpoint); this call never throws just
    * because a re-send wasn't applicable. Does not reset the checkpoint's
    * expiry.
    *
+   * With `{ challenge }`: answers a `challenge_selection` checkpoint. Pass one
+   * `id` from its `challenges` list (`email`, `sms` or `whatsapp`); the
+   * response is the next checkpoint (202), which you then solve as usual. An
+   * id the checkpoint did not offer throws `CurviateError(code:
+   * "INVALID_REQUEST")`.
+   *
    * @param accountId - the (provisional) `account_id` from the 202 response.
+   * @param body - optional `{ challenge }` for a `challenge_selection` checkpoint.
+   *
+   * @example
+   * const cp = await curviate.auth.intent({ seat_id, auth_method: "credentials", credentials });
+   * if (cp.object === "checkpoint" && cp.challenge_type === "challenge_selection") {
+   *   const next = await curviate.auth.requestCheckpoint(cp.account_id!, { challenge: cp.challenges![0]!.id });
+   * }
    */
-  requestCheckpoint(accountId) {
+  requestCheckpoint(accountId, body) {
     return this.ctx.request({
       method: "POST",
       path: "/v1/auth/checkpoint/request",
-      body: { account_id: accountId }
+      body: { account_id: accountId, ...body }
     });
   }
   /**
@@ -2869,7 +2957,14 @@ var WebhooksResource = class {
    * Register a new webhook endpoint to receive real-time events.
    * `POST /v1/webhooks`
    * The HMAC signing secret is returned exactly once in the 201 response.
-   * `account_ids` is required (each webhook is scoped to specific accounts).
+   * `account_ids` scopes a webhook to specific accounts (`acc_` ids you own)
+   * and is required for `messaging` and `user`. For `account_status` it is
+   * optional: omit it to receive status events for every current and future
+   * account of the workspace (reads then return `account_ids: null`). An
+   * explicit `[]` is rejected.
+   *
+   * @example
+   * await curviate.webhooks.create({ source: "account_status", request_url: "https://example.com/hooks" });
    */
   create(body) {
     return this.ctx.request({
@@ -2915,6 +3010,8 @@ var WebhooksResource = class {
   /**
    * Update a webhook in place. `source` is immutable.
    * `PATCH /v1/webhooks/{id}`
+   * `account_ids: null` switches an `account_status` webhook to every current
+   * and future account.
    */
   update(id, body) {
     return this.ctx.request({

package/package.json

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