@curviate/sdk 0.40.1 → 0.41.0

package/dist/index.js

@@ -79,6 +79,19 @@ var ERROR_CODES = [
   "CHECKPOINT_ALREADY_RESOLVED",
   "CHECKPOINT_UNSUPPORTED",
   "CONNECTION_IN_PROGRESS",
+  // Connection location (where LinkedIn sees the account connecting from).
+  // `CONNECTION_LOCATION_REQUIRED` (400): a new connect named no location, or
+  // a PATCH cleared your own proxy (`proxy: null`) without a `country`. Send
+  // exactly one of `country`, `ip` or `proxy`. user_fixable, never retryable
+  // as sent.
+  // `CONNECTION_LOCATION_UNAVAILABLE` (422): no connection is free in that
+  // country right now (strict), or the change landed elsewhere. When a change
+  // was applied, {@link CurviateError.connectionLocation} says where the
+  // account connects from now, which may mean your own proxy is already gone.
+  // Try a nearby country, or allow fallback. user_fixable, never retryable as
+  // sent.
+  "CONNECTION_LOCATION_REQUIRED",
+  "CONNECTION_LOCATION_UNAVAILABLE",
   // A reconnect whose seat-derived scope differs from the account's recorded
   // scope was attempted with cookie auth; a cookie replay cannot change
   // scope, so a full credentials re-authentication is required. user_fixable,
@@ -187,6 +200,7 @@ var CurviateError = class _CurviateError extends Error {
     this.safetyHint = init.safetyHint;
     this.safetyReason = init.safetyReason;
     this.blocked = init.blocked;
+    this.connectionLocation = init.connectionLocation;
     Object.setPrototypeOf(this, _CurviateError.prototype);
   }
   /**
@@ -211,6 +225,7 @@ var CurviateError = class _CurviateError extends Error {
     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;
+    if (this.connectionLocation !== void 0) json.connectionLocation = this.connectionLocation;
     return json;
   }
 };
@@ -325,7 +340,8 @@ async function errorFromResponse(res) {
     ...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 } : {}
+    ...typeof env?.blocked === "boolean" ? { blocked: env.blocked } : {},
+    ...env?.connection_location !== null && typeof env?.connection_location === "object" ? { connectionLocation: env.connection_location } : {}
   });
   return { err, refusesRetry: env?.retry_likely_to_succeed === false };
 }
@@ -543,7 +559,7 @@ var AccountsResource = class {
    * const { items } = await curviate.accounts.listSeats();
    * const free = items.find((seat) => !seat.occupied);
    * if (!free) throw new Error("No seat is free to connect to right now (add a seat, or check billing).");
-   * await curviate.auth.intent({ seat_id: free.seat_id, auth_method: "cookie", cookie: { li_at }, user_agent });
+   * await curviate.auth.intent({ seat_id: free.seat_id, auth_method: "cookie", cookie: { li_at }, user_agent, country: "US" });
    */
   listSeats() {
     return this.ctx.request({ method: "GET", path: "/v1/accounts/seats" });
@@ -597,13 +613,30 @@ var AccountsResource = class {
    * `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.
+   * carrying only them makes no LinkedIn call.
+   *
+   * `country` moves the account's connection location to that supported ISO
+   * country. LinkedIn sees a new IP there and may ask the owner to verify, so
+   * change it only when the current location is wrong. Strict unless
+   * `allow_country_fallback: true`; `allow_country_fallback` alone changes the
+   * strictness of the configured country. `proxy` sets your own proxy; `null`
+   * returns to a managed location and **requires** a `country` in the same
+   * call (else `CONNECTION_LOCATION_REQUIRED`), and an account on your own
+   * proxy can only take a `country` together with `proxy: null`. The
+   * `proxy.password`, if given, is never returned.
+   *
+   * Returns the account (as `get` returns it, without `quotas` and
+   * `event_log`). After a location change its `connection_location` is re-read,
+   * so it shows where the account really connects from now. A change that did
+   * not land where asked throws `CONNECTION_LOCATION_UNAVAILABLE`, whose
+   * `connectionLocation` carries the actual location.
    *
    * @example
    * await curviate.accounts.update("acc_123", { external_id: "usr_42", metadata: { plan: "pro" } });
+   *
+   * @example
+   * const account = await curviate.accounts.update("acc_123", { country: "DE" });
+   * console.log(account.connection_location?.country); // "DE"
    */
   update(accountId, body) {
     return this.ctx.request({
@@ -623,7 +656,7 @@ var AccountsResource = class {
   }
   /**
    * Buy seats on the workspace's active subscription. Returns the new
-   * `seat_ids`; connect an account into one with `auth.intent({ seat_id })`.
+   * `seat_ids`; connect an account into one with `auth.intent({ seat_id, country, ... })`.
    *
    * Every call buys the `qty` it asks for, so a repeated call buys again.
    * The SDK never retries it for you. A
@@ -728,8 +761,30 @@ var AuthResource = class {
    * LinkedIn account does not hold throws
    * `CurviateError(code: "LINKEDIN_FEATURE_NOT_SUBSCRIBED")` (403); the remedy
    * is to activate the subscription on LinkedIn or to point `linkedin_premium`
-   * at the premium the account really has. Pin a managed proxy with the
-   * optional `country`/`ip`, or supply `proxy` to override it entirely.
+   * at the premium the account really has.
+   *
+   * **Connection location.** A NEW connect must say where LinkedIn sees the
+   * account connecting from, with exactly one of: `country` (a supported ISO
+   * code such as `"US"`; pick the one the owner normally signs in from), `ip`
+   * (a public IPv4 whose country is used) or your own `proxy`. Without one the
+   * API throws `CurviateError(code: "CONNECTION_LOCATION_REQUIRED")`, and the
+   * {@link AuthIntentBody} type refuses it at compile time. `country` and `ip`
+   * are strict by default: the connect fails with
+   * `CONNECTION_LOCATION_UNAVAILABLE` rather than use another country, unless
+   * you send `allow_country_fallback: true`. A reconnect may omit the location
+   * to keep the account's configured one. The account's `connection_location`
+   * says where it connects from; when a connect re-attached an account you
+   * already had and moved it, `connection_location.previous_country` names
+   * where it was.
+   *
+   * @example
+   * const result = await curviate.auth.intent({
+   *   seat_id: "YOUR_SEAT_ID",
+   *   auth_method: "credentials",
+   *   credentials: { email: "YOUR_EMAIL", password: "YOUR_PASSWORD" },
+   *   country: "US",
+   * });
+   * console.log(result.account_id);
    */
   intent(body) {
     return this.ctx.request({
@@ -777,7 +832,7 @@ var AuthResource = class {
    * @param body - optional `{ challenge }` for a `challenge_selection` checkpoint.
    *
    * @example
-   * const cp = await curviate.auth.intent({ seat_id, auth_method: "credentials", credentials });
+   * const cp = await curviate.auth.intent({ seat_id, auth_method: "credentials", credentials, country: "US" });
    * if (cp.object === "checkpoint" && cp.challenge_type === "challenge_selection") {
    *   const next = await curviate.auth.requestCheckpoint(cp.account_id!, { challenge: cp.challenges![0]!.id });
    * }
@@ -1387,15 +1442,15 @@ var PostsResource = class {
    * Get a single post. `GET /v1/{account_id}/posts/{post_id}`
    *
    * @param postId - the post's `id` as returned by {@link listUserPosts} or
-   *   {@link create}. A bare numeric id (`7332661864792854528`), a URN
-   *   (`urn:li:activity:N`, `urn:li:ugcPost:N`, `urn:li:share:N`), and a full
-   *   share URL (`https://www.linkedin.com/posts/...` or
+   *   {@link create}, or a post search result's `id`. A bare numeric id
+   *   (`7332661864792854528`), a URN (`urn:li:activity:N`, `urn:li:ugcPost:N`,
+   *   `urn:li:share:N`), and a full post URL (`https://www.linkedin.com/posts/...`
+   *   with an `activity-`, `ugcPost-` or `share-` slug, or
    *   `https://www.linkedin.com/feed/update/urn:li:activity:N`) all resolve to
    *   the same post. Pass the value as-is; it is percent-encoded into the path
    *   for you, so do not encode it yourself.
    *
-   *   {@link listComments} and the reaction operations are stricter: they take
-   *   the opaque `id` form only.
+   *   {@link listComments} and the reaction operations accept the same forms.
    */
   get(postId) {
     return this.ctx.request({

package/package.json

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