@getanyapi/sdk 0.9.2 → 0.9.5

package/dist/index.d.cts

@@ -65,6 +65,8 @@ interface RequestOptions {
     signal?: AbortSignal;
     /** Override the client maxRetries for this call. */
     maxRetries?: number;
+    /** Override the generated Idempotency-Key for this billed POST. */
+    idempotencyKey?: string;
 }
 /**
  * Client construction options. See SPEC 2.1.
@@ -76,10 +78,12 @@ interface ClientOptions {
     baseUrl?: string;
     /** Custom fetch implementation. Defaults to globalThis.fetch. */
     fetch?: typeof fetch;
-    /** Max retry attempts for retryable failures (429 + network). Default 2. */
+    /** Max retry attempts for retryable failures (429 + retry-safe network). Default 2. */
     maxRetries?: number;
     /** Per-request timeout in milliseconds. Default 60000. */
     timeoutMs?: number;
+    /** Send Idempotency-Key on billed POSTs. Default "auto"; use "off" as a kill switch. */
+    idempotency?: "auto" | "off";
 }
 /**
  * Account profile returned by /v1/me (internal-only fields dropped). See SPEC 2.7.
@@ -209,6 +213,7 @@ declare class AnyAPI$1 implements ClientCore {
     private readonly fetchImpl;
     private readonly maxRetries;
     private readonly timeoutMs;
+    private readonly 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
@@ -245,6 +250,7 @@ declare class AnyAPI$1 implements ClientCore {
         timeoutMs: number;
         maxRetries: number;
         signal?: AbortSignal;
+        idempotencyKey?: string;
     }): Promise<T>;
     /** Internal accessor for GET helpers in account.ts (same base URL / machinery). */
     protected get gatewayBaseUrl(): string;
@@ -290,7 +296,9 @@ declare class AnyAPIError extends Error {
     readonly status: number;
     /** The x-request-id response header when present, else undefined. */
     readonly requestId?: string;
-    constructor(message: string, status: number, requestId?: string);
+    /** Stable gateway error code when the JSON body includes one, else undefined. */
+    readonly code?: string;
+    constructor(message: string, status: number, requestId?: string, code?: string);
 }
 /** HTTP 400. */
 declare class BadRequestError extends AnyAPIError {
@@ -3982,7 +3990,7 @@ interface EmailFindData {
  */
 interface EmailVerifyInput {
     /**
-     * The email address to verify (e.g. jane.doe@acme.com).
+     * The email address to verify (e.g. jane.doe@acme.com). Exactly one @, a dotted domain, no whitespace or angle brackets. Addresses on reserved, never-deliverable TLDs (.invalid, .test, .example, .localhost, .local, .internal, .blink) and HTML/JSON escape artifacts (a u003e prefix) are rejected locally with no charge.
      */
     email: string;
 }
@@ -4021,7 +4029,7 @@ interface EmailVerifyItem {
  */
 interface EmailVerifyData {
     /**
-     * Verification records: the email address with its deliverability verdict and syntax, domain, and mailbox check details. Populated whenever the provider has data for the entity.
+     * Verification records: the email address with its deliverability verdict and the domain, mailbox, and reputation signals behind it. A record is returned for every syntactically valid address, including ones the verdict marks undeliverable. Populated whenever the provider has data for the entity.
      */
     items: EmailVerifyItem[];
 }
@@ -4046,7 +4054,7 @@ declare class EmailNamespace {
     /**
      * 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).
      *
@@ -4364,7 +4372,7 @@ interface FacebookCommentRepliesData {
  */
 interface FacebookCompanyAdsInput {
     /**
-     * Company name to search (e.g. "nike"). Provide either pageId or companyName.
+     * Company name to search (e.g. "nike"). Exact-match and case-sensitive against the Meta Ad Library index; an advertiser with no indexed page returns found:false.
      */
     companyName?: string;
     /**
@@ -24764,7 +24772,7 @@ declare class AnyAPI extends AnyAPI$1 {
      * result type from the SkuMap; any other string returns RunResult<unknown>.
      */
     run<K extends keyof SkuMap>(slug: K, input: SkuMap[K]["input"], options?: RequestOptions): Promise<SkuMap[K]["result"]>;
-    run<S extends string, T = unknown>(slug: S extends keyof SkuMap ? never : S, input: unknown, options?: RequestOptions): Promise<RunResult<T>>;
+    run<T = unknown, S extends string = string>(slug: S extends keyof SkuMap ? never : S, input: unknown, options?: RequestOptions): Promise<RunResult<T>>;
     /**
      * Typed methods for the ahrefs platform.
      */

package/dist/index.d.ts

@@ -65,6 +65,8 @@ interface RequestOptions {
     signal?: AbortSignal;
     /** Override the client maxRetries for this call. */
     maxRetries?: number;
+    /** Override the generated Idempotency-Key for this billed POST. */
+    idempotencyKey?: string;
 }
 /**
  * Client construction options. See SPEC 2.1.
@@ -76,10 +78,12 @@ interface ClientOptions {
     baseUrl?: string;
     /** Custom fetch implementation. Defaults to globalThis.fetch. */
     fetch?: typeof fetch;
-    /** Max retry attempts for retryable failures (429 + network). Default 2. */
+    /** Max retry attempts for retryable failures (429 + retry-safe network). Default 2. */
     maxRetries?: number;
     /** Per-request timeout in milliseconds. Default 60000. */
     timeoutMs?: number;
+    /** Send Idempotency-Key on billed POSTs. Default "auto"; use "off" as a kill switch. */
+    idempotency?: "auto" | "off";
 }
 /**
  * Account profile returned by /v1/me (internal-only fields dropped). See SPEC 2.7.
@@ -209,6 +213,7 @@ declare class AnyAPI$1 implements ClientCore {
     private readonly fetchImpl;
     private readonly maxRetries;
     private readonly timeoutMs;
+    private readonly 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
@@ -245,6 +250,7 @@ declare class AnyAPI$1 implements ClientCore {
         timeoutMs: number;
         maxRetries: number;
         signal?: AbortSignal;
+        idempotencyKey?: string;
     }): Promise<T>;
     /** Internal accessor for GET helpers in account.ts (same base URL / machinery). */
     protected get gatewayBaseUrl(): string;
@@ -290,7 +296,9 @@ declare class AnyAPIError extends Error {
     readonly status: number;
     /** The x-request-id response header when present, else undefined. */
     readonly requestId?: string;
-    constructor(message: string, status: number, requestId?: string);
+    /** Stable gateway error code when the JSON body includes one, else undefined. */
+    readonly code?: string;
+    constructor(message: string, status: number, requestId?: string, code?: string);
 }
 /** HTTP 400. */
 declare class BadRequestError extends AnyAPIError {
@@ -3982,7 +3990,7 @@ interface EmailFindData {
  */
 interface EmailVerifyInput {
     /**
-     * The email address to verify (e.g. jane.doe@acme.com).
+     * The email address to verify (e.g. jane.doe@acme.com). Exactly one @, a dotted domain, no whitespace or angle brackets. Addresses on reserved, never-deliverable TLDs (.invalid, .test, .example, .localhost, .local, .internal, .blink) and HTML/JSON escape artifacts (a u003e prefix) are rejected locally with no charge.
      */
     email: string;
 }
@@ -4021,7 +4029,7 @@ interface EmailVerifyItem {
  */
 interface EmailVerifyData {
     /**
-     * Verification records: the email address with its deliverability verdict and syntax, domain, and mailbox check details. Populated whenever the provider has data for the entity.
+     * Verification records: the email address with its deliverability verdict and the domain, mailbox, and reputation signals behind it. A record is returned for every syntactically valid address, including ones the verdict marks undeliverable. Populated whenever the provider has data for the entity.
      */
     items: EmailVerifyItem[];
 }
@@ -4046,7 +4054,7 @@ declare class EmailNamespace {
     /**
      * 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).
      *
@@ -4364,7 +4372,7 @@ interface FacebookCommentRepliesData {
  */
 interface FacebookCompanyAdsInput {
     /**
-     * Company name to search (e.g. "nike"). Provide either pageId or companyName.
+     * Company name to search (e.g. "nike"). Exact-match and case-sensitive against the Meta Ad Library index; an advertiser with no indexed page returns found:false.
      */
     companyName?: string;
     /**
@@ -24764,7 +24772,7 @@ declare class AnyAPI extends AnyAPI$1 {
      * result type from the SkuMap; any other string returns RunResult<unknown>.
      */
     run<K extends keyof SkuMap>(slug: K, input: SkuMap[K]["input"], options?: RequestOptions): Promise<SkuMap[K]["result"]>;
-    run<S extends string, T = unknown>(slug: S extends keyof SkuMap ? never : S, input: unknown, options?: RequestOptions): Promise<RunResult<T>>;
+    run<T = unknown, S extends string = string>(slug: S extends keyof SkuMap ? never : S, input: unknown, options?: RequestOptions): Promise<RunResult<T>>;
     /**
      * Typed methods for the ahrefs platform.
      */

package/dist/index.js

@@ -4,13 +4,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);
   }
 };
@@ -32,25 +37,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) {
@@ -359,14 +411,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 {
@@ -383,6 +439,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) {
@@ -467,6 +535,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}`);
@@ -485,13 +580,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;
@@ -499,6 +602,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
@@ -521,6 +625,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
@@ -528,13 +637,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 } : {}
       }
     );
@@ -599,6 +710,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(
@@ -624,7 +741,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;
@@ -645,7 +764,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);
@@ -653,7 +772,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). */
@@ -698,12 +817,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) {
@@ -714,6 +835,7 @@ function paginate(core, slug, input, itemsField, bare, options) {
         return;
       }
       cursor = next;
+      pageNumber += 1;
     }
   }
   async function* walkItems() {
@@ -745,6 +867,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;
@@ -1322,7 +1453,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).
    *