@getanyapi/sdk 0.9.1 → 0.9.5

package/README.md

@@ -126,13 +126,30 @@ Per-call transport overrides: `timeoutMs`, `maxRetries`, and an `AbortSignal` vi
 | `ResultNotFoundError`      | -    | `unwrap` on an empty found-data result     |
 | `RateLimitedError`         | 429  | Too many requests (retried automatically)  |
 | `UpstreamError`            | 502  | An upstream backend failed                 |
-| `ConnectionError`          | 0    | Network or transport failure (retried)     |
+| `ConnectionError`          | 0    | Network or transport failure               |
 | `TimeoutError`             | 0    | Request exceeded its timeout (not retried) |
 
 All extend `AnyAPIError` (with `status` and `requestId`). Retries cover only 429 and network
-failures, with jittered exponential backoff honoring `Retry-After`. Default `maxRetries` is 2
-(up to 3 attempts); set it on the client or per request. Timeouts are never retried. Configure
-with `new AnyAPI({ timeoutMs, maxRetries })`.
+failures proven to happen before a request was sent, with jittered exponential backoff honoring
+`Retry-After`. Default `maxRetries` is 2 (up to 3 attempts); set it on the client or per request.
+Timeouts are never retried. Connection failures during or after a billed `POST /v1/run` are not
+retried because the call may already have been charged. When the send phase is unknown, the SDK
+does not retry. Configure with `new AnyAPI({ timeoutMs, maxRetries })`.
+
+Automatic network retry of a billed `run()` requires structured runtime evidence that the
+request body was not sent:
+
+| Runtime | Automatic billed-run network retry | Evidence available to the SDK |
+| ------- | ---------------------------------- | ----------------------------- |
+| Node 18+ with built-in undici `fetch` | Yes | DNS and connect codes, connect-phase timeouts, or an undici socket reporting zero bytes written |
+| Bun 1.3.11 | Yes | `ConnectionRefused`, which Bun 1.3.11 emits only while establishing the origin or proxy connection |
+| Cloudflare Workers | No | `retryable: true` means transient, not undelivered; it can appear after the origin received the full body |
+| Deno | No | Fetch exposes only prose without a structured connection code |
+| Browsers | No | Fetch generally exposes an opaque `TypeError` |
+
+On a runtime without strict non-delivery evidence, the SDK makes no automatic network retry for a
+billed `run()`. HTTP 429 retry is unchanged. Handle other retries explicitly only when your
+application can establish non-delivery.
 
 ## Agent signup
 

package/dist/index.cjs

@@ -103,13 +103,18 @@ var AnyAPIError = class extends Error {
   status;
   /** The x-request-id response header when present, else undefined. */
   requestId;
-  constructor(message, status, requestId) {
+  /** Stable gateway error code when the JSON body includes one, else undefined. */
+  code;
+  constructor(message, status, requestId, code) {
     super(message);
     this.name = new.target.name;
     this.status = status;
     if (requestId !== void 0) {
       this.requestId = requestId;
     }
+    if (code !== void 0) {
+      this.code = code;
+    }
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
@@ -131,25 +136,72 @@ var ConnectionError = class extends AnyAPIError {
 };
 var TimeoutError = class extends AnyAPIError {
 };
-function errorFromStatus(status, message, requestId) {
+function errorFromStatus(status, message, requestId, code) {
   switch (status) {
     case 400:
-      return new BadRequestError(message, status, requestId);
+      return new BadRequestError(message, status, requestId, code);
     case 401:
-      return new AuthenticationError(message, status, requestId);
+      return new AuthenticationError(message, status, requestId, code);
     case 402:
-      return new InsufficientBalanceError(message, status, requestId);
+      return new InsufficientBalanceError(message, status, requestId, code);
     case 404:
-      return new NotFoundError(message, status, requestId);
+      return new NotFoundError(message, status, requestId, code);
     case 429:
-      return new RateLimitedError(message, status, requestId);
+      return new RateLimitedError(message, status, requestId, code);
     case 502:
-      return new UpstreamError(message, status, requestId);
+      return new UpstreamError(message, status, requestId, code);
     default:
-      return new AnyAPIError(message, status, requestId);
+      return new AnyAPIError(message, status, requestId, code);
   }
 }
 
+// src/core/idempotency.ts
+var MAX_IDEMPOTENCY_KEY_BYTES = 255;
+function generateIdempotencyKey() {
+  let runtimeCrypto;
+  try {
+    runtimeCrypto = globalThis.crypto;
+  } catch {
+    runtimeCrypto = void 0;
+  }
+  if (typeof runtimeCrypto?.randomUUID === "function") {
+    try {
+      return runtimeCrypto.randomUUID();
+    } catch {
+    }
+  }
+  if (typeof runtimeCrypto?.getRandomValues === "function") {
+    try {
+      const bytes = runtimeCrypto.getRandomValues(new Uint8Array(16));
+      return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    } catch {
+    }
+  }
+  return Array.from(
+    { length: 4 },
+    () => Math.floor(Math.random() * 4294967296).toString(16).padStart(8, "0")
+  ).join("");
+}
+function validateIdempotencyKey(key) {
+  if (key.length === 0 || key.length > MAX_IDEMPOTENCY_KEY_BYTES || [...key].some((char) => {
+    const code = char.charCodeAt(0);
+    return code < 33 || code > 126;
+  })) {
+    throw new TypeError(
+      "idempotencyKey must be 1-255 bytes of visible ASCII (0x21-0x7e)"
+    );
+  }
+}
+function pageIdempotencyKey(key, pageNumber) {
+  validateIdempotencyKey(key);
+  const suffix = `-p${pageNumber}`;
+  const prefixLength = MAX_IDEMPOTENCY_KEY_BYTES - suffix.length;
+  if (prefixLength < 1) {
+    throw new TypeError("pagination page number is too large for an idempotency key");
+  }
+  return `${key.slice(0, prefixLength)}${suffix}`;
+}
+
 // src/core/account.ts
 var DEFAULT_BASE_URL = "https://api.getanyapi.com";
 function malformed(path) {
@@ -458,14 +510,18 @@ async function agentSignup(options = {}) {
   const text = await response.text().catch(() => "");
   if (response.status !== 200) {
     let message = `request failed with status ${response.status}`;
+    let code;
     try {
       const parsed2 = JSON.parse(text);
       if (typeof parsed2.error === "string" && parsed2.error !== "") {
         message = parsed2.error;
       }
+      if (typeof parsed2.code === "string" && parsed2.code !== "") {
+        code = parsed2.code;
+      }
     } catch {
     }
-    throw errorFromStatus(response.status, message, requestId);
+    throw errorFromStatus(response.status, message, requestId, code);
   }
   const parsed = JSON.parse(text);
   return {
@@ -482,6 +538,18 @@ var DEFAULT_TIMEOUT_MS = 6e4;
 var DEFAULT_MAX_RETRIES = 2;
 var RETRY_BASE_DELAY_MS = 500;
 var RETRY_MAX_DELAY_MS = 8e3;
+var PRE_SEND_NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "EADDRNOTAVAIL",
+  "EAI_AGAIN",
+  "EAI_NODATA",
+  "EAI_NONAME",
+  "ECONNREFUSED",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "ConnectionRefused"
+]);
 function envApiKey() {
   try {
     if (typeof process !== "undefined" && process?.env) {
@@ -566,6 +634,33 @@ function isTimeoutSignal(timeoutSignal, callerSignal) {
   }
   return callerSignal?.aborted !== true || timeoutSignal.aborted;
 }
+function isDefinitelyPreSendConnectionError(error) {
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (value) => {
+    if (typeof value !== "object" && typeof value !== "function" || value === null) {
+      return false;
+    }
+    if (seen.has(value)) {
+      return false;
+    }
+    seen.add(value);
+    const candidate = value;
+    if (typeof candidate.code === "string" && PRE_SEND_NETWORK_ERROR_CODES.has(candidate.code)) {
+      return true;
+    }
+    if (candidate.code === "ETIMEDOUT" && candidate.syscall === "connect") {
+      return true;
+    }
+    if (candidate.code === "UND_ERR_SOCKET" && candidate.socket?.bytesWritten === 0) {
+      return true;
+    }
+    if (Array.isArray(candidate.errors) && candidate.errors.length > 0) {
+      return candidate.errors.some((item) => visit(item)) || visit(candidate.cause);
+    }
+    return visit(candidate.cause);
+  };
+  return visit(error);
+}
 function buildUrl(baseUrl, slug, options) {
   const base = baseUrl.replace(/\/+$/, "");
   const url = new URL(`${base}/v1/run/${slug}`);
@@ -584,13 +679,21 @@ function messageFromBody(body, status) {
   if (body) {
     try {
       const parsed = JSON.parse(body);
+      const code = typeof parsed.code === "string" && parsed.code !== "" ? parsed.code : void 0;
       if (typeof parsed.error === "string" && parsed.error !== "") {
-        return parsed.error;
+        return {
+          message: parsed.error,
+          ...code !== void 0 ? { code } : {}
+        };
       }
+      return {
+        message: `request failed with status ${status}`,
+        ...code !== void 0 ? { code } : {}
+      };
     } catch {
     }
   }
-  return `request failed with status ${status}`;
+  return { message: `request failed with status ${status}` };
 }
 var AnyAPI = class {
   apiKey;
@@ -598,6 +701,7 @@ var AnyAPI = class {
   fetchImpl;
   maxRetries;
   timeoutMs;
+  idempotency;
   /**
    * The network seam the generated per-platform namespaces target. The base client IS a
    * ClientCore (it implements `run`), so the generated subclass hands `this._core` to each
@@ -620,6 +724,11 @@ var AnyAPI = class {
     this.fetchImpl = resolvedFetch;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const idempotency = options.idempotency ?? "auto";
+    if (idempotency !== "auto" && idempotency !== "off") {
+      throw new TypeError('idempotency must be "auto" or "off"');
+    }
+    this.idempotency = idempotency;
   }
   /**
    * Generic run for any SKU by slug (the untyped network seam + the string fallback). The
@@ -627,13 +736,15 @@ var AnyAPI = class {
    * base signature is the fallback that returns RunResult<unknown> for an unknown slug.
    */
   run(slug, input, options) {
+    const body = JSON.stringify(input ?? {});
     return this.request(
       "POST",
       buildUrl(this.baseUrl, slug, options),
       {
-        body: JSON.stringify(input ?? {}),
+        body,
         timeoutMs: options?.timeoutMs ?? this.timeoutMs,
         maxRetries: options?.maxRetries ?? this.maxRetries,
+        ...options?.idempotencyKey !== void 0 ? { idempotencyKey: options.idempotencyKey } : {},
         ...options?.signal ? { signal: options.signal } : {}
       }
     );
@@ -698,6 +809,12 @@ var AnyAPI = class {
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
     }
+    const billedPost = method === "POST" && opts.body !== void 0;
+    if (billedPost && this.idempotency === "auto") {
+      const key = opts.idempotencyKey ?? generateIdempotencyKey();
+      validateIdempotencyKey(key);
+      headers["Idempotency-Key"] = key;
+    }
     let attempt = 0;
     for (; ; ) {
       const { signal, timeoutSignal } = composeSignal(
@@ -723,7 +840,9 @@ var AnyAPI = class {
           err instanceof Error ? err.message : "connection failed",
           0
         );
-        if (attempt < opts.maxRetries) {
+        const requestMayBeBilled = method === "POST" && opts.body !== void 0;
+        const safeToRetry = !requestMayBeBilled || isDefinitelyPreSendConnectionError(err);
+        if (safeToRetry && attempt < opts.maxRetries) {
           await sleep(backoffDelay(attempt), opts.signal);
           attempt += 1;
           continue;
@@ -744,7 +863,7 @@ var AnyAPI = class {
         }
       }
       const body = await response.text().catch(() => "");
-      const message = messageFromBody(body, response.status);
+      const { message, code } = messageFromBody(body, response.status);
       if (response.status === 429 && attempt < opts.maxRetries) {
         const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
         const delay = retryAfter ?? backoffDelay(attempt);
@@ -752,7 +871,7 @@ var AnyAPI = class {
         attempt += 1;
         continue;
       }
-      throw errorFromStatus(response.status, message, requestId);
+      throw errorFromStatus(response.status, message, requestId, code);
     }
   }
   /** Internal accessor for GET helpers in account.ts (same base URL / machinery). */
@@ -797,12 +916,14 @@ function paginate(core, slug, input, itemsField, bare, options) {
   const maxItems = options?.maxItems;
   async function* walkPages() {
     let cursor;
+    let pageNumber = 1;
     for (; ; ) {
       const pageInput = { ...input };
       if (cursor !== void 0) {
         pageInput["cursor"] = cursor;
       }
-      const result = await core.run(slug, pageInput, wireOptions);
+      const pageOptions = optionsForPage(wireOptions, pageNumber);
+      const result = await core.run(slug, pageInput, pageOptions);
       yield result;
       const data = pageData(result, bare);
       if (data === null) {
@@ -813,6 +934,7 @@ function paginate(core, slug, input, itemsField, bare, options) {
         return;
       }
       cursor = next;
+      pageNumber += 1;
     }
   }
   async function* walkItems() {
@@ -844,6 +966,15 @@ function paginate(core, slug, input, itemsField, bare, options) {
   };
   return paginator;
 }
+function optionsForPage(options, pageNumber) {
+  if (options?.idempotencyKey === void 0) {
+    return options;
+  }
+  return {
+    ...options,
+    idempotencyKey: pageIdempotencyKey(options.idempotencyKey, pageNumber)
+  };
+}
 function stripMaxItems(options) {
   if (!options) {
     return void 0;
@@ -1421,7 +1552,7 @@ var EmailNamespace = class {
   /**
    * Email Verifier
    *
-   * Verify any email address for deliverability: syntax, domain, and mailbox checks in one normalized response.
+   * Verify an email address for deliverability: a status verdict (valid, risky, or invalid) with domain, mailbox, catch-all, disposable, and role signals plus a confidence score. Malformed addresses are rejected by the input schema with no charge; every syntactically valid address returns a billed verdict, including undeliverable ones.
    *
    * Price: $0 per request plus $0.0008 per result (maximum $0.0008).
    *
@@ -1668,7 +1799,7 @@ var FacebookNamespace = class {
   /**
    * Facebook Marketplace
    *
-   * Search Facebook Marketplace listings by keyword near a location, with price, condition, delivery, recency, and availability filters (title, price, location, and image) as normalized JSON.
+   * Search Facebook Marketplace listings by keyword near a location, filter by price, condition, delivery, recency, and availability, and get title, price, location, and image as normalized JSON.
    *
    * Price: $0.002 per request.
    *