@shieldlabs-ai/node 0.0.0-stage → 1.0.1

package/dist/index.js

@@ -0,0 +1,1559 @@
+import { timingSafeEqual, createHmac } from 'node:crypto';
+
+// src/index.ts
+
+// src/constants.ts
+var NIL_UUID = "00000000-0000-0000-0000-000000000000";
+var SIGNALS = Object.freeze({
+  TOR: "tor",
+  JAVASCRIPT_DISABLED: "javascript_disabled",
+  OS_MISMATCH: "os_mismatch",
+  ANTIDETECT_BROWSER: "antidetect_browser",
+  PROXY_ROUTED_ANTIDETECT: "proxy_routed_antidetect",
+  PORT_SCAN_ROUTED_VIA_PROXY: "port_scan_routed_via_proxy",
+  BROWSER_AUTOMATION: "browser_automation",
+  STUN_NOT_CHECKED: "stun_not_checked",
+  STUN_LATE_CORRECTION: "stun_late_correction",
+  OS_NOT_DETECTED: "os_not_detected",
+  BROWSER_VPN_PROXY: "browser_vpn_proxy",
+  VPN: "vpn",
+  PRIVACY_RELAY: "privacy_relay",
+  PROXY: "proxy",
+  DATACENTER_IP: "datacenter_ip",
+  ABUSER: "abuser",
+  TIMEZONE_MISMATCH: "timezone_mismatch",
+  RATE_LIMITED: "rate_limited"
+});
+var RISK_BANDS = Object.freeze({
+  trusted: Object.freeze({ min: 0, max: 29 }),
+  suspicious: Object.freeze({ min: 30, max: 59 }),
+  dangerous: Object.freeze({ min: 60, max: 100 })
+});
+var RISK_BAND_NAMES = ["trusted", "suspicious", "dangerous"];
+var LOOKUP_TYPES = [
+  "ip",
+  "user_hid",
+  "visitor_id",
+  "request_id",
+  "device_id",
+  "session_id",
+  "cookie_id"
+];
+var FLAG_KEYS = [
+  "vpn",
+  "privacy_relay",
+  "browser_vpn_proxy",
+  "tor",
+  "proxy",
+  "datacenter_ip",
+  "abuser",
+  "os_mismatch",
+  "os_not_detected",
+  "timezone_mismatch",
+  "anti_detect_browser",
+  "browser_automation",
+  "ip_mismatch",
+  "incognito",
+  "search_bot",
+  "suspicious_paid_click",
+  "javascript_disabled",
+  "stun_not_checked",
+  "check_incomplete"
+];
+var KNOWN_SCHEMA_VERSION = "2026-06-01";
+var DEFAULT_HISTORY_BASE_URL = "https://account.shieldlabs.ai";
+var DEFAULT_MANAGEMENT_BASE_URL = "https://api.shieldlabs.ai";
+
+// src/errors.ts
+var ShieldLabsError = class extends Error {
+  name = "ShieldLabsError";
+  constructor(message, options) {
+    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+  }
+};
+var EMPTY_HEADERS = { get: () => null };
+var ApiError = class extends ShieldLabsError {
+  name = "ApiError";
+  /** HTTP status code. */
+  status;
+  /** Parsed response body: JSON value, raw text, or null when the body was empty. */
+  body;
+  /** Response headers. */
+  headers;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.status = options.status;
+    this.body = options.body === void 0 ? null : options.body;
+    this.headers = options.headers ?? EMPTY_HEADERS;
+  }
+};
+var BadRequestError = class extends ApiError {
+  name = "BadRequestError";
+};
+var AuthenticationError = class extends ApiError {
+  name = "AuthenticationError";
+};
+var QuotaExceededError = class extends ApiError {
+  name = "QuotaExceededError";
+};
+var NotFoundError = class extends ApiError {
+  name = "NotFoundError";
+};
+var RateLimitError = class extends ApiError {
+  name = "RateLimitError";
+  /** Seconds to wait, from the Retry-After header, when the server sent one. */
+  retryAfter;
+  constructor(message, options) {
+    super(message, options);
+    this.retryAfter = options.retryAfter;
+  }
+};
+var ServerError = class extends ApiError {
+  name = "ServerError";
+};
+var ConnectionError = class extends ShieldLabsError {
+  name = "ConnectionError";
+};
+var TimeoutError = class extends ShieldLabsError {
+  name = "TimeoutError";
+};
+var SignatureVerificationError = class extends ShieldLabsError {
+  name = "SignatureVerificationError";
+};
+var WebhookParseError = class extends ShieldLabsError {
+  name = "WebhookParseError";
+};
+var ValidationError = class extends ShieldLabsError {
+  name = "ValidationError";
+};
+
+// src/normalize.ts
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function own(obj, key) {
+  return hasOwn(obj, key) ? obj[key] : void 0;
+}
+function stringField(obj, key) {
+  const value = own(obj, key);
+  return typeof value === "string" ? value : "";
+}
+function isTruthy(value) {
+  if (value === void 0 || value === null) return false;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") return value.length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.keys(value).length > 0;
+  return true;
+}
+var WHITESPACE = /* @__PURE__ */ new Set([
+  9,
+  10,
+  11,
+  12,
+  13,
+  28,
+  29,
+  30,
+  31,
+  32,
+  133,
+  160,
+  5760,
+  8192,
+  8193,
+  8194,
+  8195,
+  8196,
+  8197,
+  8198,
+  8199,
+  8200,
+  8201,
+  8202,
+  8232,
+  8233,
+  8239,
+  8287,
+  12288
+]);
+function stripWhitespace(text) {
+  let start = 0;
+  let end = text.length;
+  while (start < end && WHITESPACE.has(text.charCodeAt(start))) start++;
+  while (end > start && WHITESPACE.has(text.charCodeAt(end - 1))) end--;
+  return text.slice(start, end);
+}
+function stripUnderscores(text) {
+  let start = 0;
+  let end = text.length;
+  while (start < end && text[start] === "_") start++;
+  while (end > start && text[end - 1] === "_") end--;
+  return text.slice(start, end);
+}
+var EXACT_SLUGS = /* @__PURE__ */ new Map([
+  ["Is tor", "tor"],
+  ["Is VPN", "vpn"],
+  ["Is privacy relay", "privacy_relay"],
+  ["Is proxy", "proxy"],
+  ["Is datacenter", "datacenter_ip"],
+  ["Is abuser", "abuser"],
+  ["Stun is not checked", "stun_not_checked"],
+  ["Stun passed (late arrival, corrected)", "stun_late_correction"],
+  ["UA OS is not detected", "os_not_detected"],
+  ["Network OS is not detected", "os_not_detected"],
+  ["Browser timezone \u2260 IP-timezone", "timezone_mismatch"],
+  ["Browser VPN/Proxy", "browser_vpn_proxy"],
+  ["Browser Automation", "browser_automation"],
+  ["Port scan routed via proxy (antidetect browser pattern)", "proxy_routed_antidetect"],
+  ["User has been banned 1H, to many requests", "rate_limited"]
+]);
+var PREFIX_SLUGS = [
+  ["Antidetect browser", "antidetect_browser"],
+  ["Os_mismatch", "os_mismatch"],
+  ["OS mismatch2", "os_mismatch2"],
+  ["TCP handshake", "tcp_handshake_v2"],
+  ["Latency test", "ws_tcp_latency"],
+  ["JavaScript disabled", "javascript_disabled"]
+];
+var STICKY_PREFIX = "Sticky verdict: ";
+var LETTER_OR_DIGIT = /^[\p{L}\p{Nd}]$/u;
+function fallbackSlug(description) {
+  let text = stripWhitespace(description);
+  const paren = text.indexOf("(");
+  if (paren >= 0) text = stripWhitespace(text.slice(0, paren));
+  let out = "";
+  let previousWasSeparator = false;
+  for (const ch of text) {
+    if (ch === " " || ch === "-" || ch === "/") {
+      if (!previousWasSeparator && out.length > 0) {
+        out += "_";
+        previousWasSeparator = true;
+      }
+    } else if (ch === "\u2260") {
+      out += "_neq_";
+      previousWasSeparator = false;
+    } else if (LETTER_OR_DIGIT.test(ch)) {
+      out += ch.toLowerCase();
+      previousWasSeparator = false;
+    }
+  }
+  const slug = stripUnderscores(out);
+  return slug === "" ? "unknown" : slug;
+}
+function signalSlug(description) {
+  const exact = EXACT_SLUGS.get(description);
+  if (exact !== void 0) return exact;
+  for (const [prefix, slug] of PREFIX_SLUGS) {
+    if (description.startsWith(prefix)) return slug;
+  }
+  if (description.startsWith(STICKY_PREFIX)) {
+    const colon = description.indexOf(":");
+    const rest = colon >= 0 && colon + 1 < description.length ? stripWhitespace(description.slice(colon + 1)) : description;
+    return fallbackSlug(rest);
+  }
+  return fallbackSlug(description);
+}
+var HISTORY_TIME = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(?:Z|[+-]\d{2}:?\d{2})?$/;
+var RFC3339 = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})\n?$/;
+function isLeapYear(year) {
+  return year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+}
+function daysInMonth(year, month) {
+  if (month === 2) return isLeapYear(year) ? 29 : 28;
+  return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+function pad(value, width) {
+  return String(value).padStart(width, "0");
+}
+function formatUtc(match, offsetMinutes) {
+  const [year, month, day, hour, minute, second] = [1, 2, 3, 4, 5, 6].map(
+    (i) => Number(match[i])
+  );
+  if (year < 1 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month) || hour > 23 || minute > 59 || second > 59) {
+    return null;
+  }
+  const local = /* @__PURE__ */ new Date(0);
+  local.setUTCFullYear(year, month - 1, day);
+  local.setUTCHours(hour, minute, second, 0);
+  const utc = new Date(local.getTime() - offsetMinutes * 6e4);
+  const utcYear = utc.getUTCFullYear();
+  if (utcYear < 1 || utcYear > 9999) return null;
+  const millis = (match[7] ?? "0").slice(0, 3).padEnd(3, "0");
+  return `${pad(utcYear, 4)}-${pad(utc.getUTCMonth() + 1, 2)}-${pad(utc.getUTCDate(), 2)}T${pad(utc.getUTCHours(), 2)}:${pad(utc.getUTCMinutes(), 2)}:${pad(utc.getUTCSeconds(), 2)}.${millis}Z`;
+}
+function parseHistoryTime(value) {
+  if (typeof value !== "string") return null;
+  const text = stripWhitespace(value);
+  if (text === "") return null;
+  const match = text.match(HISTORY_TIME);
+  return match ? formatUtc(match, 0) : null;
+}
+function parseRfc3339(value) {
+  if (typeof value !== "string") return null;
+  const match = value.match(RFC3339);
+  if (!match) return null;
+  const zone = match[8] ?? "Z";
+  let offsetMinutes = 0;
+  if (zone !== "Z") {
+    const sign = zone.startsWith("+") ? 1 : -1;
+    offsetMinutes = sign * (Number(zone.slice(1, 3)) * 60 + Number(zone.slice(4, 6)));
+  }
+  return formatUtc(match, offsetMinutes);
+}
+var HISTORY_FLAG_COLUMNS = {
+  vpn: "is_vpn",
+  privacy_relay: "is_privacy_relay",
+  tor: "is_tor",
+  proxy: "is_proxy",
+  datacenter_ip: "is_datacenter",
+  abuser: "is_abuser",
+  os_mismatch: "is_os_mismatch",
+  os_not_detected: "is_os_not_detected",
+  timezone_mismatch: "is_timezone_mismatch",
+  anti_detect_browser: "is_antidetect",
+  browser_automation: "is_browser_automation",
+  incognito: "is_incognito",
+  search_bot: "is_search_bot",
+  suspicious_paid_click: "is_suspicious_paid_click",
+  javascript_disabled: "is_js_disabled",
+  stun_not_checked: "is_stun_not_checked",
+  check_incomplete: "check_incomplete"
+};
+function normalizeIp(value) {
+  if (typeof value !== "string") return "";
+  const ip = stripWhitespace(value);
+  return ip === "0.0.0.0" ? "" : ip;
+}
+function normalizeUserHid(value) {
+  if (value === void 0 || value === null || value === "") return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return null;
+}
+function normalizeScore(obj, key) {
+  if (!hasOwn(obj, key)) return 0;
+  const value = obj[key];
+  return typeof value === "number" ? value : Number.NaN;
+}
+function parseScoreDetails(value) {
+  const text = isTruthy(value) ? value : "[]";
+  if (typeof text !== "string") return [];
+  try {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function ipInfo(value) {
+  const obj = isPlainObject(value) ? value : {};
+  return { ip: normalizeIp(own(obj, "ip")), country: stringField(obj, "country") };
+}
+var TRAFFIC_KEYS = [
+  "channel",
+  "referrer_domain",
+  "landing_url",
+  "click_id_type",
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term"
+];
+function fromHistoryRow(row) {
+  const leakSource = stripWhitespace(stringField(row, "webrtc_leak_source"));
+  let localIp;
+  let localCountry;
+  if (leakSource !== "" && leakSource !== "none") {
+    localIp = normalizeIp(own(row, "webrtc_leak_ip"));
+    localCountry = stringField(row, "webrtc_leak_country");
+  } else {
+    localIp = normalizeIp(own(row, "web_rtc_ip"));
+    localCountry = stringField(row, "web_rtc_country");
+  }
+  const publicIp = normalizeIp(own(row, "ip"));
+  const signals = [];
+  let ipLeakDetail = false;
+  for (const entry of parseScoreDetails(own(row, "score_details"))) {
+    if (!isPlainObject(entry)) continue;
+    const description = stringField(entry, "Description");
+    if (description.startsWith("IP \u2260 leakIP")) ipLeakDetail = true;
+    const value = own(entry, "Value");
+    if (typeof value !== "number" || !Number.isInteger(value) || value === 0) continue;
+    signals.push({ name: signalSlug(description), weight: value, description });
+  }
+  const searchBot = isTruthy(own(row, "is_search_bot"));
+  const flags = {};
+  for (const key of FLAG_KEYS) {
+    if (key === "browser_vpn_proxy") {
+      flags[key] = own(row, "connection_type") === "browser_vpn_proxy";
+    } else if (key === "ip_mismatch") {
+      flags[key] = !searchBot && (ipLeakDetail || publicIp !== "" && localIp !== "" && publicIp !== localIp);
+    } else {
+      flags[key] = isTruthy(own(row, HISTORY_FLAG_COLUMNS[key]));
+    }
+  }
+  const siteDomain = own(row, "site_domain");
+  let domain;
+  if (isTruthy(siteDomain)) {
+    domain = typeof siteDomain === "string" ? siteDomain : "";
+  } else {
+    domain = stringField(row, "domain");
+  }
+  return {
+    request_id: stringField(row, "request_id"),
+    visitor_id: stringField(row, "visitor_id"),
+    device_id: stringField(row, "device_id"),
+    session_id: stringField(row, "session_id"),
+    cookie_id: stringField(row, "cookie_id"),
+    user_hid: normalizeUserHid(own(row, "user_hid")),
+    domain,
+    public_ip: { ip: publicIp, country: stringField(row, "country") },
+    local_ip: { ip: localIp, country: localCountry },
+    connection_type: stringField(row, "connection_type"),
+    os: stringField(row, "os"),
+    browser: stringField(row, "browser"),
+    device_type: stringField(row, "device_type"),
+    traffic_source: {
+      channel: stringField(row, "traffic_channel"),
+      referrer_domain: stringField(row, "referrer_domain"),
+      landing_url: stringField(row, "entry_url"),
+      click_id_type: stringField(row, "click_id_type"),
+      utm_source: stringField(row, "utm_source"),
+      utm_medium: stringField(row, "utm_medium"),
+      utm_campaign: stringField(row, "utm_campaign"),
+      utm_content: stringField(row, "utm_content"),
+      utm_term: stringField(row, "utm_term")
+    },
+    risk_score: normalizeScore(row, "score"),
+    signals,
+    detection_flags: flags,
+    observed_at: parseHistoryTime(own(row, "created_at")),
+    source: "history",
+    raw: row
+  };
+}
+function fromWebhookData(data) {
+  const rawFlags = own(data, "detection_flags");
+  const flagSource = isPlainObject(rawFlags) ? rawFlags : {};
+  const flags = {};
+  for (const key of FLAG_KEYS) flags[key] = isTruthy(own(flagSource, key));
+  const rawTraffic = own(data, "traffic_source");
+  const trafficSource = isPlainObject(rawTraffic) ? rawTraffic : {};
+  const traffic = {};
+  for (const key of TRAFFIC_KEYS) traffic[key] = stringField(trafficSource, key);
+  const rawSignals = own(data, "signals");
+  const signals = Array.isArray(rawSignals) ? rawSignals.filter(isPlainObject).map((signal) => {
+    const weight = own(signal, "weight");
+    return {
+      name: stringField(signal, "name"),
+      weight: typeof weight === "number" ? weight : 0,
+      description: null
+    };
+  }) : [];
+  return {
+    request_id: stringField(data, "request_id"),
+    visitor_id: stringField(data, "visitor_id"),
+    device_id: stringField(data, "device_id"),
+    session_id: stringField(data, "session_id"),
+    cookie_id: stringField(data, "cookie_id"),
+    user_hid: normalizeUserHid(own(data, "user_hid")),
+    domain: stringField(data, "domain"),
+    public_ip: ipInfo(own(data, "public_ip")),
+    local_ip: ipInfo(own(data, "local_ip")),
+    connection_type: stringField(data, "connection_type"),
+    os: stringField(data, "os"),
+    browser: stringField(data, "browser"),
+    device_type: stringField(data, "device_type"),
+    traffic_source: traffic,
+    risk_score: normalizeScore(data, "risk_score"),
+    signals,
+    detection_flags: flags,
+    observed_at: parseRfc3339(own(data, "observed_at")),
+    source: "webhook",
+    raw: data
+  };
+}
+function profileFromResponse(body) {
+  const weight = own(body, "Weight");
+  return {
+    domain: stringField(body, "Domain"),
+    remaining_identifications: typeof weight === "number" && Number.isFinite(weight) ? weight : 0,
+    public_key_masked: stringField(body, "PublicKey"),
+    secret_key_masked: stringField(body, "Secret"),
+    created_at: parseRfc3339(own(body, "CreatedAt")),
+    raw: body
+  };
+}
+
+// src/version.ts
+var VERSION = "1.0.0";
+
+// src/runtime.ts
+function detectRuntime() {
+  const g = globalThis;
+  if (typeof g.Bun?.version === "string") return `bun/${g.Bun.version}`;
+  if (typeof g.Deno?.version?.deno === "string") return `deno/${g.Deno.version.deno}`;
+  if (typeof g.EdgeRuntime === "string") return "edge-runtime";
+  if (g.navigator?.userAgent === "Cloudflare-Workers") return "workerd";
+  if (typeof g.process?.versions?.node === "string") return `node/${g.process.versions.node}`;
+  return null;
+}
+var cachedUserAgent;
+function userAgent() {
+  if (cachedUserAgent === void 0) {
+    const runtime = detectRuntime();
+    cachedUserAgent = runtime ? `shieldlabs-node/${VERSION} ${runtime}` : `shieldlabs-node/${VERSION}`;
+  }
+  return cachedUserAgent;
+}
+function abortReason(signal) {
+  if (signal.reason !== void 0) return signal.reason;
+  const error = new Error("The operation was aborted.");
+  error.name = "AbortError";
+  return error;
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortReason(signal);
+}
+var MAX_TIMER_DELAY_MS = 2147483647;
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    let timer;
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    const wait = (left) => {
+      timer = setTimeout(
+        () => {
+          if (left > MAX_TIMER_DELAY_MS) {
+            wait(left - MAX_TIMER_DELAY_MS);
+            return;
+          }
+          signal?.removeEventListener("abort", onAbort);
+          resolve();
+        },
+        Math.min(left, MAX_TIMER_DELAY_MS)
+      );
+    };
+    wait(ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var warned = /* @__PURE__ */ new Set();
+var MAX_WARNINGS = 32;
+function warnOnce(key, message) {
+  if (warned.has(key) || warned.size >= MAX_WARNINGS) return;
+  warned.add(key);
+  console.warn(`[shieldlabs] ${message}`);
+}
+function warnIfBrowserPage(client, key) {
+  const g = globalThis;
+  if (g.window !== void 0 && g.document !== void 0) {
+    warnOnce(
+      `browser-page:${client}`,
+      `${client} was created in a web page, where its ${key} is visible to every visitor. Use @shieldlabs-ai/node on your server only; in the page, use the browser SDK (@shieldlabs-ai/js).`
+    );
+  }
+}
+
+// src/webhooks.ts
+var SIGNATURE_PREFIX = "sha256=";
+var HEX_DIGEST = /^[0-9a-fA-F]{64}$/;
+var MISMATCH = "The webhook signature does not match the payload. Check the endpoint signing secret (including its whsec_ prefix) and verify the raw body bytes, not re-serialized JSON.";
+var encoder = new TextEncoder();
+function parseSignatureHeader(header) {
+  let value = header;
+  if (Array.isArray(value)) {
+    if (value.length !== 1) return null;
+    value = value[0];
+  }
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith(SIGNATURE_PREFIX)) return null;
+  const digest = trimmed.slice(SIGNATURE_PREFIX.length);
+  return HEX_DIGEST.test(digest) ? digest.toLowerCase() : null;
+}
+function secretList(secret) {
+  const list = Array.isArray(secret) ? secret : [secret];
+  return list.filter((item) => typeof item === "string" && item !== "");
+}
+function isArrayBuffer(value) {
+  return value instanceof ArrayBuffer || Object.prototype.toString.call(value) === "[object ArrayBuffer]";
+}
+function payloadBytes(payload) {
+  if (typeof payload === "string") return encoder.encode(payload);
+  if (payload instanceof Uint8Array) return payload;
+  if (ArrayBuffer.isView(payload)) {
+    return new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
+  }
+  if (isArrayBuffer(payload)) return new Uint8Array(payload);
+  return null;
+}
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  let hex = "";
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+function prepare(payload, header, secret) {
+  const bytes = payloadBytes(payload);
+  if (bytes === null) {
+    return {
+      ok: false,
+      reason: "The payload must be the raw request body (a string, Uint8Array or ArrayBuffer). A parsed object cannot be verified because re-serializing changes the bytes."
+    };
+  }
+  const digest = parseSignatureHeader(header);
+  if (digest === null) {
+    return {
+      ok: false,
+      reason: "The X-Shield-Signature header is missing or malformed (expected sha256=<64 hex characters>)."
+    };
+  }
+  const secrets = secretList(secret);
+  if (secrets.length === 0) {
+    return { ok: false, reason: "No webhook signing secret was provided." };
+  }
+  return { ok: true, bytes, expected: hexToBytes(digest), secrets };
+}
+var decoder = new TextDecoder("utf-8");
+function preview(text) {
+  return text.length > 40 ? `${text.slice(0, 37)}...` : text;
+}
+function parseEvent(bytes) {
+  const text = decoder.decode(bytes);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new WebhookParseError("The webhook body is not valid JSON.", { cause: error });
+  }
+  if (!isPlainObject(parsed)) {
+    throw new WebhookParseError("The webhook body is not a JSON object.");
+  }
+  const eventType = parsed.event_type;
+  if (typeof eventType !== "string" || eventType === "") {
+    throw new WebhookParseError("The webhook body has no event_type.");
+  }
+  const schemaVersion = typeof parsed.schema_version === "string" ? parsed.schema_version : "";
+  const createdAt = typeof parsed.created_at === "string" ? parsed.created_at : "";
+  if (schemaVersion !== KNOWN_SCHEMA_VERSION) {
+    warnOnce(
+      `schema-version:${schemaVersion}`,
+      `Received a webhook with schema_version "${preview(schemaVersion)}" while this SDK version targets "${KNOWN_SCHEMA_VERSION}". The event was parsed; update @shieldlabs-ai/node for typed support of newer fields.`
+    );
+  }
+  if (eventType === "identification.scored") {
+    if (!isPlainObject(parsed.data)) {
+      throw new WebhookParseError("The identification.scored event has no data object.");
+    }
+    return {
+      event_type: "identification.scored",
+      schema_version: schemaVersion,
+      created_at: createdAt,
+      data: fromWebhookData(parsed.data),
+      raw: parsed
+    };
+  }
+  if (eventType === "webhook.ping") {
+    return {
+      event_type: "webhook.ping",
+      schema_version: schemaVersion,
+      created_at: createdAt,
+      raw: parsed
+    };
+  }
+  return {
+    event_type: eventType,
+    schema_version: schemaVersion,
+    created_at: createdAt,
+    raw: parsed
+  };
+}
+function syncUnavailable(fn, alternative) {
+  return new ShieldLabsError(
+    `${fn}() is synchronous and needs node:crypto, which the edge build of @shieldlabs-ai/node does not load. Use await ${alternative}() instead.`
+  );
+}
+function createWebhooks(backend2) {
+  const equal = backend2.equal ?? constantTimeEqual;
+  function verifySync(payload, header, secret, hmac) {
+    const prepared = prepare(payload, header, secret);
+    if (!prepared.ok) return prepared;
+    for (const key of prepared.secrets) {
+      if (equal(hmac(key, prepared.bytes), prepared.expected)) return prepared;
+    }
+    return { ok: false, reason: MISMATCH };
+  }
+  async function verifyAsync(payload, header, secret) {
+    const prepared = prepare(payload, header, secret);
+    if (!prepared.ok) return prepared;
+    for (const key of prepared.secrets) {
+      if (equal(await backend2.hmacAsync(key, prepared.bytes), prepared.expected)) return prepared;
+    }
+    return { ok: false, reason: MISMATCH };
+  }
+  function requireSync(fn, alternative) {
+    if (backend2.hmacSync === null) throw syncUnavailable(fn, alternative);
+    return backend2.hmacSync;
+  }
+  return Object.freeze({
+    verifySignature(payload, signatureHeader, secret) {
+      const hmac = requireSync("webhooks.verifySignature", "webhooks.verifySignatureAsync");
+      return verifySync(payload, signatureHeader, secret, hmac).ok;
+    },
+    constructEvent(payload, signatureHeader, secret) {
+      const hmac = requireSync("webhooks.constructEvent", "webhooks.constructEventAsync");
+      const result = verifySync(payload, signatureHeader, secret, hmac);
+      if (!result.ok) throw new SignatureVerificationError(result.reason);
+      return parseEvent(result.bytes);
+    },
+    async verifySignatureAsync(payload, signatureHeader, secret) {
+      return (await verifyAsync(payload, signatureHeader, secret)).ok;
+    },
+    async constructEventAsync(payload, signatureHeader, secret) {
+      const result = await verifyAsync(payload, signatureHeader, secret);
+      if (!result.ok) throw new SignatureVerificationError(result.reason);
+      return parseEvent(result.bytes);
+    }
+  });
+}
+function validateUserHidInput(userId, secret) {
+  if (typeof userId !== "string" || userId === "") {
+    throw new ValidationError("userId must be a non-empty string.");
+  }
+  if (typeof secret !== "string" || secret === "") {
+    throw new ValidationError("secret must be a non-empty string.");
+  }
+}
+function computeUserHid(backend2, userId, secret) {
+  if (backend2.hmacSync === null) throw syncUnavailable("userHid", "userHidAsync");
+  validateUserHidInput(userId, secret);
+  return bytesToHex(backend2.hmacSync(secret, encoder.encode(userId)));
+}
+async function computeUserHidAsync(backend2, userId, secret) {
+  validateUserHidInput(userId, secret);
+  return bytesToHex(await backend2.hmacAsync(secret, encoder.encode(userId)));
+}
+
+// src/http.ts
+var BACKOFF_BASE_MS = 500;
+var BACKOFF_CAP_MS = 8e3;
+var RETRY_AFTER_CAP_MS = 1e4;
+var RATE_LIMIT_FLOOR_MS = 1e3;
+var MAX_DETAIL_LENGTH = 200;
+function isLoopbackHost(hostname) {
+  return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "[::1]" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname);
+}
+function normalizeBaseUrl(input, name, stripApiSuffix, allowInsecureHttp = false) {
+  if (typeof input !== "string" || input.trim() === "") {
+    throw new ValidationError(`${name} must be a non-empty URL.`);
+  }
+  let url;
+  try {
+    url = new URL(input.trim());
+  } catch {
+    throw new ValidationError(`${name} is not a valid URL.`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new ValidationError(`${name} must be an https URL.`);
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw new ValidationError(`${name} must not contain credentials.`);
+  }
+  if (url.search !== "" || url.hash !== "") {
+    throw new ValidationError(`${name} must not contain a query string or a fragment.`);
+  }
+  if (url.protocol === "http:" && !isLoopbackHost(url.hostname)) {
+    if (!allowInsecureHttp) {
+      throw new ValidationError(
+        `${name} must be an https URL: with plain http the key would travel unencrypted. Plain http is accepted for localhost, 127.0.0.1 and [::1]; for a test server on another host, pass allowInsecureHttp: true.`
+      );
+    }
+    warnOnce(
+      `insecure-base-url:${url.origin}`,
+      `${name} uses plain http, so credentials travel unencrypted. Use https outside local testing.`
+    );
+  }
+  let path = url.pathname.replace(/\/+$/, "");
+  if (stripApiSuffix && /\/api$/i.test(path)) path = path.slice(0, -4).replace(/\/+$/, "");
+  return `${url.origin}${path}`;
+}
+function parseRetryAfter(value, nowMs = Date.now()) {
+  if (value === null || value === void 0) return void 0;
+  const text = value.trim();
+  if (/^\d+(?:\.\d+)?$/.test(text)) return Number(text);
+  if (!/[a-z]{3}/i.test(text)) return void 0;
+  const date = Date.parse(text);
+  if (Number.isNaN(date)) return void 0;
+  return Math.max(0, Math.ceil((date - nowMs) / 1e3));
+}
+function truncate(text) {
+  return text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH - 3)}...` : text;
+}
+function errorDetail(body, parsedJson, text) {
+  if (parsedJson) {
+    if (isPlainObject(body) && typeof body.error === "string" && body.error !== "") {
+      return truncate(body.error);
+    }
+    if (typeof body === "string" && body !== "") return truncate(body);
+    return void 0;
+  }
+  const trimmed = text.trim();
+  if (trimmed === "" || trimmed.startsWith("<")) return void 0;
+  return truncate(trimmed);
+}
+function hintFor(apiName, status) {
+  if (status === 401 || status === 403) {
+    return apiName === "History API" ? " Check that apiKey is the Private API Key (sec_...) of this domain." : " Check the Secret Key and that domain matches the registered domain exactly.";
+  }
+  if (status === 404) return " Check the base URL.";
+  if (status === 429 && apiName === "Management API") {
+    return " The Management API allows about 15 requests per minute per IP, then blocks the IP for 10 minutes.";
+  }
+  return "";
+}
+function createApiError(apiName, status, text, headers) {
+  let body = null;
+  let parsedJson = false;
+  if (text !== "") {
+    try {
+      body = JSON.parse(text);
+      parsedJson = true;
+    } catch {
+      body = text;
+    }
+  }
+  const detail = errorDetail(body, parsedJson, text);
+  const message = `${apiName} request failed with HTTP ${status}${detail ? ` (${detail})` : ""}.${hintFor(apiName, status)}`;
+  const options = { status, body, headers };
+  if (status === 400) return new BadRequestError(message, options);
+  if (status === 401 || status === 403) return new AuthenticationError(message, options);
+  if (status === 402) return new QuotaExceededError(message, options);
+  if (status === 404) return new NotFoundError(message, options);
+  if (status === 429) {
+    let retryAfter;
+    try {
+      retryAfter = parseRetryAfter(headers.get("retry-after"));
+    } catch {
+      retryAfter = void 0;
+    }
+    return new RateLimitError(message, { ...options, retryAfter });
+  }
+  if (status >= 500 && status <= 599) return new ServerError(message, options);
+  return new ApiError(message, options);
+}
+function messageOf(error) {
+  return error instanceof Error && error.message ? error.message : String(error);
+}
+function causeDetail(error) {
+  const cause = error instanceof Error ? error.cause : void 0;
+  if (typeof cause !== "object" || cause === null) return "";
+  const { code, message } = cause;
+  const codeText = typeof code === "string" ? code : "";
+  const text = typeof message === "string" ? message.trim() : "";
+  if (text !== "" && codeText !== "" && !text.includes(codeText)) {
+    return ` (${codeText}: ${truncate(text)})`;
+  }
+  if (text !== "") return ` (${truncate(text)})`;
+  return codeText === "" ? "" : ` (${codeText})`;
+}
+function printableTexts(error) {
+  const texts = [];
+  let current = error;
+  for (let depth = 0; depth < 5 && current !== void 0 && current !== null; depth++) {
+    if (typeof current !== "object") {
+      if (typeof current === "string") texts.push(current);
+      break;
+    }
+    const { message, stack } = current;
+    if (typeof message === "string") texts.push(message);
+    if (typeof stack === "string") texts.push(stack);
+    try {
+      texts.push(JSON.stringify(current) ?? "");
+    } catch {
+    }
+    current = current.cause;
+  }
+  return texts;
+}
+function mentionsSecret(texts, secrets) {
+  return secrets.some((secret) => secret !== "" && texts.some((text) => text.includes(secret)));
+}
+function raceWithAbort(promise, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const onAbort = () => reject(abortReason(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    );
+  });
+}
+function globalFetch() {
+  const candidate = globalThis.fetch;
+  if (typeof candidate !== "function") {
+    throw new ValidationError(
+      "No fetch implementation is available. Use Node.js 18 or later, or pass the fetch option."
+    );
+  }
+  const fetchFn = candidate;
+  return (url, init) => fetchFn.call(globalThis, url, init);
+}
+var Transport = class {
+  #options;
+  constructor(options) {
+    this.#options = options;
+  }
+  /** The client's per-attempt timeout in milliseconds. */
+  get timeout() {
+    return this.#options.timeout;
+  }
+  async getJson(path, options = {}) {
+    const maxRetries = options.maxRetries ?? this.#options.maxRetries;
+    let url = `${this.#options.baseUrl}${path}`;
+    if (options.query) url += `?${new URLSearchParams(options.query).toString()}`;
+    for (let attempt = 0; ; attempt++) {
+      throwIfAborted(options.signal);
+      try {
+        return await this.#attempt(url, options.signal, options.timeout);
+      } catch (error) {
+        if (attempt >= maxRetries || !this.#isRetryable(error)) throw error;
+        await sleep(this.#retryDelay(error, attempt), options.signal);
+      }
+    }
+  }
+  #isRetryable(error) {
+    if (error instanceof ConnectionError || error instanceof TimeoutError) return true;
+    if (error instanceof RateLimitError) return this.#options.retryRateLimited;
+    return error instanceof ServerError;
+  }
+  #retryDelay(error, attempt) {
+    if (error instanceof ApiError) {
+      const retryAfter = error instanceof RateLimitError ? error.retryAfter : parseRetryAfter(error.headers.get("retry-after"));
+      if (retryAfter !== void 0) return Math.min(retryAfter * 1e3, RETRY_AFTER_CAP_MS);
+    }
+    const nominal = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
+    const delay = nominal / 2 + Math.random() * (nominal / 2);
+    return error instanceof RateLimitError ? Math.max(delay, RATE_LIMIT_FLOOR_MS) : delay;
+  }
+  #connectionError(error) {
+    const { apiName, secrets } = this.#options;
+    const message = `${apiName} request failed: ${messageOf(error)}${causeDetail(error)}`;
+    if (mentionsSecret([message, ...printableTexts(error)], secrets)) {
+      return new ConnectionError(
+        `${apiName} request failed before a response was received. The underlying error was withheld because it contained a credential.`
+      );
+    }
+    return new ConnectionError(message, { cause: error });
+  }
+  async #attempt(url, signal, timeoutCap) {
+    const { apiName } = this.#options;
+    const timeout = Math.min(this.#options.timeout, timeoutCap ?? Number.POSITIVE_INFINITY);
+    const fetchImpl = this.#options.fetch ?? globalFetch();
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeout);
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    let response;
+    let text;
+    try {
+      const init = {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          "User-Agent": userAgent(),
+          ...this.#options.headers
+        },
+        signal: controller.signal
+      };
+      response = await raceWithAbort(
+        Promise.resolve().then(() => fetchImpl(url, init)),
+        controller.signal
+      );
+      text = await raceWithAbort(
+        Promise.resolve().then(() => response.text()),
+        controller.signal
+      );
+    } catch (error) {
+      if (signal?.aborted) throw abortReason(signal);
+      if (timedOut) {
+        throw new TimeoutError(`${apiName} request timed out after ${timeout} ms.`, {
+          cause: error
+        });
+      }
+      if (error instanceof ShieldLabsError) throw error;
+      throw this.#connectionError(error);
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+    const { status, headers } = response;
+    if (status >= 200 && status < 300) {
+      try {
+        return { body: JSON.parse(text), status, headers };
+      } catch (error) {
+        throw new ApiError(
+          `${apiName} returned a response that is not valid JSON (HTTP ${status}).`,
+          {
+            status,
+            body: text,
+            headers,
+            cause: error
+          }
+        );
+      }
+    }
+    throw createApiError(apiName, status, text, headers);
+  }
+};
+
+// src/validation.ts
+var UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+var IPV4_OCTET = "(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)";
+var IPV4 = new RegExp(`^${IPV4_OCTET}(?:\\.${IPV4_OCTET}){3}$`);
+function describe(value) {
+  const text = typeof value === "string" ? JSON.stringify(value) : String(value);
+  return text.length > 40 ? `${text.slice(0, 37)}...` : text;
+}
+var PLAIN_IN_PATH = /%(?:24|26|2B|2C|3A|3B|3D|40)/g;
+var ESCAPED_IN_PATH = /[!'()*]/g;
+function encodePathSegment(value) {
+  let escaped;
+  try {
+    escaped = encodeURIComponent(value);
+  } catch {
+    throw new ValidationError(
+      "user_hid must be valid Unicode text (it has an unpaired surrogate)."
+    );
+  }
+  return escaped.replace(PLAIN_IN_PATH, (match) => decodeURIComponent(match)).replace(ESCAPED_IN_PATH, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function validateLookup(type, value) {
+  if (typeof type !== "string" || !LOOKUP_TYPES.includes(type)) {
+    throw new ValidationError(
+      `Unknown lookup type ${describe(type)}. Use one of: ${LOOKUP_TYPES.join(", ")}.`
+    );
+  }
+  const lookupType = type;
+  if (typeof value !== "string") {
+    throw new ValidationError(`The ${lookupType} value must be a string.`);
+  }
+  if (lookupType === "user_hid") {
+    if (value === "") throw new ValidationError("user_hid must be a non-empty string.");
+    if (value === "." || value === "..") {
+      throw new ValidationError(
+        'user_hid cannot be "." or "..": a URL path segment cannot carry it.'
+      );
+    }
+    if (value.includes("/")) {
+      throw new ValidationError(
+        'user_hid cannot contain "/": the History API cannot search a value with a slash. Use URL-safe User HIDs, such as the 64 hex characters of userHid().'
+      );
+    }
+    return { type: lookupType, value, segment: encodePathSegment(value) };
+  }
+  if (lookupType === "ip") {
+    if (value.includes(":")) {
+      throw new ValidationError(
+        "IPv6 addresses cannot be searched: the History API stores IPv4 addresses only."
+      );
+    }
+    if (!IPV4.test(value)) {
+      throw new ValidationError("ip must be a dotted IPv4 address such as 203.0.113.24.");
+    }
+    return { type: lookupType, value, segment: value };
+  }
+  if (!UUID.test(value)) {
+    throw new ValidationError(`${lookupType} must be a UUID (8-4-4-4-12 hexadecimal digits).`);
+  }
+  const uuid = value.toLowerCase();
+  return { type: lookupType, value: uuid, segment: uuid };
+}
+function validateRequestId(requestId) {
+  if (typeof requestId !== "string" || !UUID.test(requestId)) {
+    throw new ValidationError("requestId must be a UUID (8-4-4-4-12 hexadecimal digits).");
+  }
+  return requestId.toLowerCase();
+}
+function validateBoolean(value, name) {
+  if (typeof value !== "boolean") throw new ValidationError(`${name} must be a boolean.`);
+  return value;
+}
+function validatePageSize(value, name) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 100) {
+    throw new ValidationError(`${name} must be an integer from 1 to 100.`);
+  }
+  return value;
+}
+function validateNonNegativeInteger(value, name) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new ValidationError(`${name} must be an integer greater than or equal to 0.`);
+  }
+  return value;
+}
+function validateMilliseconds(value, name, allowZero = false) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || !allowZero && value === 0) {
+    const bound = allowZero ? "greater than or equal to 0" : "greater than 0";
+    throw new ValidationError(`${name} must be a number of milliseconds ${bound}.`);
+  }
+  return value;
+}
+var HEADER_SAFE = /^[\x21-\x7E]+$/;
+function requireHeaderSafe(text, name) {
+  if (!HEADER_SAFE.test(text)) {
+    throw new ValidationError(
+      `${name} contains characters that cannot be sent in an HTTP header (only visible ASCII characters are allowed).`
+    );
+  }
+}
+function isAscii(text) {
+  for (let index = 0; index < text.length; index++) {
+    if (text.charCodeAt(index) > 127) return false;
+  }
+  return true;
+}
+function validateCredential(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new ValidationError(`${name} is required and must be a non-empty string.`);
+  }
+  const credential = value.trim();
+  requireHeaderSafe(credential, name);
+  return credential;
+}
+
+// src/history.ts
+var API_KEY_FORMAT = /^sec_[a-z0-9]{8}-[a-z0-9]{8}-[a-z0-9]{8}$/;
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_LIMIT = 20;
+var DEFAULT_PAGE_SIZE = 100;
+var DEFAULT_WAIT_TIMEOUT_MS = 1e4;
+var DEFAULT_POLL_INTERVAL_MS = 250;
+var POLL_WAIT_CAP_MS = 2e3;
+var POLL_WAIT_FACTORS = [1, 2, 4, 6];
+var LAST_POLL_WAIT_FACTOR = 8;
+var MIN_POLL_ATTEMPT_MS = 1e3;
+function pollWait(index, pollInterval) {
+  const factor = POLL_WAIT_FACTORS[index] ?? LAST_POLL_WAIT_FACTOR;
+  return Math.min(Math.max(POLL_WAIT_CAP_MS, pollInterval), pollInterval * factor);
+}
+function parsePage(body, status, headers) {
+  if (!isPlainObject(body) || !Array.isArray(body.data)) {
+    throw new ApiError("History API returned an unexpected response body.", {
+      status,
+      body,
+      headers
+    });
+  }
+  const data = body.data.filter(isPlainObject).map(fromHistoryRow);
+  const total = typeof body.total === "number" && Number.isFinite(body.total) ? body.total : data.length;
+  return { data, total };
+}
+async function fetchPage(transport, lookup, limit, offset, signal, maxRetries, attemptTimeout) {
+  const path = `/api/v1/history/${lookup.type}/${lookup.segment}`;
+  const response = await transport.getJson(path, {
+    query: { limit: String(limit), offset: String(offset) },
+    signal,
+    maxRetries,
+    timeout: attemptTimeout
+  });
+  return parsePage(response.body, response.status, response.headers);
+}
+function isTransientPollError(error) {
+  return error instanceof RateLimitError || error instanceof ServerError || error instanceof ConnectionError || error instanceof TimeoutError;
+}
+var HistoryResource = class {
+  #transport;
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  /**
+   * One page of identifications for one identifier, newest first.
+   * `GET /api/v1/history/{type}/{value}`.
+   */
+  async search(type, value, options = {}) {
+    const lookup = validateLookup(type, value);
+    const limit = validatePageSize(options.limit ?? DEFAULT_LIMIT, "limit");
+    const offset = validateNonNegativeInteger(options.offset ?? 0, "offset");
+    return fetchPage(this.#transport, lookup, limit, offset, options.signal);
+  }
+  /**
+   * Every identification for one identifier, newest first, fetched page by page. Rows repeated
+   * across pages (new rows can shift offsets) are skipped by request ID. Stops at `total`, at an
+   * empty page or after `maxItems`.
+   */
+  iterate(type, value, options = {}) {
+    const lookup = validateLookup(type, value);
+    const pageSize = validatePageSize(options.pageSize ?? DEFAULT_PAGE_SIZE, "pageSize");
+    const maxItems = options.maxItems === void 0 ? void 0 : validateNonNegativeInteger(options.maxItems, "maxItems");
+    return this.#iterate(lookup, pageSize, maxItems, options.signal);
+  }
+  async *#iterate(lookup, pageSize, maxItems, signal) {
+    const seen = /* @__PURE__ */ new Set();
+    let offset = 0;
+    let yielded = 0;
+    for (; ; ) {
+      if (maxItems !== void 0 && yielded >= maxItems) return;
+      const page = await fetchPage(this.#transport, lookup, pageSize, offset, signal);
+      if (page.data.length === 0) return;
+      for (const identification of page.data) {
+        const key = identification.request_id;
+        if (key !== "") {
+          if (seen.has(key)) continue;
+          seen.add(key);
+        }
+        yield identification;
+        yielded++;
+        if (maxItems !== void 0 && yielded >= maxItems) return;
+      }
+      offset += page.data.length;
+      if (offset >= page.total) return;
+    }
+  }
+};
+var IdentificationsResource = class {
+  #transport;
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  /**
+   * The identification with this request ID, or null when none is found.
+   *
+   * Scoring is asynchronous: the row appears about 1 to 3 seconds after the browser call and can
+   * be refined for up to about 10 seconds while follow-up checks finish; this returns the first
+   * version it sees. With `wait` (the default), `timeout` is the total budget of the call:
+   *
+   * - The first poll runs at once. The waits between polls are `pollInterval` times 1, 2, 4 and 6,
+   *   then 8 times it for every later wait, each capped at max(2 s, `pollInterval`): 250 ms,
+   *   500 ms, 1 s, 1.5 s and then every 2 s by default, and every 3 s for a `pollInterval` of
+   *   3 s. A wait that would pass the deadline is cut short, so the last poll runs at the
+   *   deadline.
+   * - Each poll is one HTTP attempt without retries, with the timeout
+   *   min(client timeout, max(time left, 1 s)).
+   * - 429, 5xx, connection errors and timeouts do not end the wait. After a 429 the next wait is
+   *   the longest of the scheduled wait, 1 s and the Retry-After capped at 10 s (a missing
+   *   Retry-After, 0 or a past date counts as 0), cut short at the deadline like any other wait.
+   *   When the capped Retry-After is longer than the time left, that RateLimitError is thrown at
+   *   once.
+   * - At the deadline, the error of the last poll is thrown if it failed; otherwise the result
+   *   is null.
+   * - 400, 401, 403 and 404 (and any other error that another poll cannot fix) are thrown at once.
+   */
+  async get(requestId, options = {}) {
+    const id = validateRequestId(requestId);
+    const wait = validateBoolean(options.wait ?? true, "wait");
+    const timeout = validateMilliseconds(
+      options.timeout ?? DEFAULT_WAIT_TIMEOUT_MS,
+      "timeout",
+      true
+    );
+    const pollInterval = validateMilliseconds(
+      options.pollInterval ?? DEFAULT_POLL_INTERVAL_MS,
+      "pollInterval"
+    );
+    const { signal } = options;
+    throwIfAborted(signal);
+    const lookup = { type: "request_id", value: id, segment: id };
+    if (!wait) {
+      const page = await fetchPage(this.#transport, lookup, 1, 0, signal);
+      return page.data[0] ?? null;
+    }
+    return this.#poll(lookup, Date.now() + timeout, pollInterval, signal);
+  }
+  async #poll(lookup, deadline, pollInterval, signal) {
+    let atDeadline = false;
+    for (let index = 0; ; index++) {
+      const attemptTimeout = Math.min(
+        this.#transport.timeout,
+        Math.max(deadline - Date.now(), MIN_POLL_ATTEMPT_MS)
+      );
+      let failure;
+      try {
+        const page = await fetchPage(this.#transport, lookup, 1, 0, signal, 0, attemptTimeout);
+        const found = page.data[0];
+        if (found) return found;
+      } catch (error) {
+        throwIfAborted(signal);
+        if (!isTransientPollError(error)) throw error;
+        failure = error;
+      }
+      const remaining = deadline - Date.now();
+      if (atDeadline || remaining <= 0) {
+        if (failure !== void 0) throw failure;
+        return null;
+      }
+      let delay = pollWait(index, pollInterval);
+      if (failure instanceof RateLimitError) {
+        const retryAfter = Math.min((failure.retryAfter ?? 0) * 1e3, RETRY_AFTER_CAP_MS);
+        if (retryAfter > remaining) throw failure;
+        delay = Math.max(delay, RATE_LIMIT_FLOOR_MS, retryAfter);
+      }
+      if (delay >= remaining) {
+        delay = remaining;
+        atDeadline = true;
+      }
+      await sleep(delay, signal);
+    }
+  }
+};
+var ShieldLabs = class {
+  /** Single identifications by request ID, with wait-for-verdict polling. */
+  identifications;
+  /** History lookups by identifier. */
+  history;
+  constructor(options) {
+    if (!isPlainObject(options)) {
+      throw new ValidationError("new ShieldLabs() needs an options object with apiKey.");
+    }
+    const apiKey = validateCredential(options.apiKey, "apiKey");
+    warnIfBrowserPage("ShieldLabs", "Private API Key");
+    if (!API_KEY_FORMAT.test(apiKey)) {
+      warnOnce(
+        "api-key-format",
+        "apiKey does not look like a Private API Key (sec_xxxxxxxx-xxxxxxxx-xxxxxxxx). The History API needs the Private API Key, not the Public Key or the Secret Key."
+      );
+    }
+    const baseUrl = normalizeBaseUrl(
+      options.baseUrl ?? DEFAULT_HISTORY_BASE_URL,
+      "baseUrl",
+      true,
+      validateBoolean(options.allowInsecureHttp ?? false, "allowInsecureHttp")
+    );
+    const timeout = validateMilliseconds(options.timeout ?? DEFAULT_TIMEOUT_MS, "timeout");
+    const maxRetries = validateNonNegativeInteger(
+      options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      "maxRetries"
+    );
+    if (options.fetch !== void 0 && typeof options.fetch !== "function") {
+      throw new ValidationError("fetch must be a function.");
+    }
+    const transport = new Transport({
+      apiName: "History API",
+      baseUrl,
+      headers: { Authorization: `Bearer ${apiKey}` },
+      secrets: [apiKey],
+      timeout,
+      maxRetries,
+      retryRateLimited: true,
+      fetch: options.fetch
+    });
+    this.history = new HistoryResource(transport);
+    this.identifications = new IdentificationsResource(transport);
+  }
+};
+
+// src/management.ts
+var DEFAULT_TIMEOUT_MS2 = 1e4;
+var DEFAULT_MAX_RETRIES2 = 2;
+function normalizeDomain(input) {
+  let domain = input.trim().toLowerCase();
+  domain = domain.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+  domain = domain.split(/[/?#]/, 1)[0] ?? "";
+  return domain.replace(/^www\./, "");
+}
+var ShieldLabsManagement = class {
+  /** The normalized domain sent in X-Shield-Domain. */
+  domain;
+  #transport;
+  constructor(options) {
+    if (!isPlainObject(options)) {
+      throw new ValidationError(
+        "new ShieldLabsManagement() needs an options object with secretKey and domain."
+      );
+    }
+    const secretKey = validateCredential(options.secretKey, "secretKey");
+    warnIfBrowserPage("ShieldLabsManagement", "Secret Key");
+    if (typeof options.domain !== "string") {
+      throw new ValidationError('domain is required and must be a string such as "example.com".');
+    }
+    const domain = normalizeDomain(options.domain);
+    if (domain === "") {
+      throw new ValidationError('domain is required and must be a string such as "example.com".');
+    }
+    if (!isAscii(domain)) {
+      throw new ValidationError("domain must be ASCII: pass the punycode form (xn--...).");
+    }
+    requireHeaderSafe(domain, "domain");
+    const baseUrl = normalizeBaseUrl(
+      options.baseUrl ?? DEFAULT_MANAGEMENT_BASE_URL,
+      "baseUrl",
+      false,
+      validateBoolean(options.allowInsecureHttp ?? false, "allowInsecureHttp")
+    );
+    const timeout = validateMilliseconds(options.timeout ?? DEFAULT_TIMEOUT_MS2, "timeout");
+    const maxRetries = validateNonNegativeInteger(
+      options.maxRetries ?? DEFAULT_MAX_RETRIES2,
+      "maxRetries"
+    );
+    if (options.fetch !== void 0 && typeof options.fetch !== "function") {
+      throw new ValidationError("fetch must be a function.");
+    }
+    this.domain = domain;
+    this.#transport = new Transport({
+      apiName: "Management API",
+      baseUrl,
+      headers: { "X-Shield-Domain": domain, Authorization: `Bearer ${secretKey}` },
+      secrets: [secretKey],
+      timeout,
+      maxRetries,
+      retryRateLimited: false,
+      fetch: options.fetch
+    });
+  }
+  /** The domain profile: remaining identifications and masked keys. `GET /v1/profile`. */
+  async getProfile(options = {}) {
+    const response = await this.#transport.getJson("/v1/profile", { signal: options.signal });
+    if (!isPlainObject(response.body)) {
+      throw new ApiError("Management API returned an unexpected response body.", {
+        status: response.status,
+        body: response.body,
+        headers: response.headers
+      });
+    }
+    return profileFromResponse(response.body);
+  }
+};
+
+// src/risk.ts
+function riskBand(score) {
+  if (typeof score !== "number" || Number.isNaN(score)) {
+    throw new ValidationError("riskBand() needs a numeric Risk Score.");
+  }
+  if (score > 100) return "rate_limited";
+  if (score >= 60) return "dangerous";
+  if (score >= 30) return "suspicious";
+  return "trusted";
+}
+function isRateLimited(score) {
+  return typeof score === "number" && score > 100;
+}
+var DEFAULT_MAX_AGE_MS = 3e5;
+var DEFAULT_BLOCK_BANDS = ["dangerous"];
+var DEFAULT_BLOCK_FLAGS = ["browser_automation", "javascript_disabled"];
+function resolveNow(now) {
+  if (now === void 0) return Date.now();
+  const value = now instanceof Date ? now.getTime() : now;
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new ValidationError("now must be a valid Date or a number of epoch milliseconds.");
+  }
+  return value;
+}
+function isThenable(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+function evaluateIdentification(identification, options = {}) {
+  const maxAge = options.maxAge ?? DEFAULT_MAX_AGE_MS;
+  if (typeof maxAge !== "number" || Number.isNaN(maxAge) || maxAge < 0) {
+    throw new ValidationError(
+      "maxAge must be a number of milliseconds greater than or equal to 0, or Infinity to skip the freshness check."
+    );
+  }
+  const nowMs = resolveNow(options.now);
+  const blockBands = options.blockBands ?? DEFAULT_BLOCK_BANDS;
+  for (const band2 of blockBands) {
+    if (!RISK_BAND_NAMES.includes(band2)) {
+      throw new ValidationError(
+        `Unknown risk band in blockBands. Use one of: ${RISK_BAND_NAMES.join(", ")}.`
+      );
+    }
+  }
+  const blockFlags = options.blockFlags ?? DEFAULT_BLOCK_FLAGS;
+  for (const flag of blockFlags) {
+    if (!FLAG_KEYS.includes(flag)) {
+      throw new ValidationError(
+        `Unknown detection flag in blockFlags. Use one of: ${FLAG_KEYS.join(", ")}.`
+      );
+    }
+  }
+  if (identification === null || identification === void 0) {
+    return { ok: false, reason: "missing", band: null };
+  }
+  const band = riskBand(identification.risk_score);
+  if (options.isReplay) {
+    const replayed = options.isReplay(identification.request_id);
+    if (isThenable(replayed)) {
+      throw new ValidationError(
+        "isReplay must return a boolean synchronously. Claim the request ID in your store first (an atomic insert-if-absent), then pass the result, for example isReplay: () => !claimed."
+      );
+    }
+    if (replayed) return { ok: false, reason: "replayed", band };
+  }
+  if (maxAge !== Number.POSITIVE_INFINITY) {
+    const observedMs = identification.observed_at === null ? Number.NaN : Date.parse(identification.observed_at);
+    if (Number.isNaN(observedMs) || nowMs - observedMs > maxAge) {
+      return { ok: false, reason: "stale", band };
+    }
+  }
+  if (isRateLimited(identification.risk_score)) {
+    return { ok: false, reason: "rate_limited", band };
+  }
+  if (!identification.device_id || identification.device_id === NIL_UUID) {
+    return { ok: false, reason: "no_device_signals", band };
+  }
+  for (const flag of blockFlags) {
+    if (identification.detection_flags[flag]) {
+      return { ok: false, reason: "blocked_flag", band, flag };
+    }
+  }
+  if (band !== "rate_limited" && blockBands.includes(band)) {
+    return { ok: false, reason: "blocked_band", band };
+  }
+  return { ok: true, reason: null, band };
+}
+
+// src/index.ts
+var hmacSync = (key, message) => createHmac("sha256", key).update(message).digest();
+var backend = {
+  hmacSync,
+  hmacAsync: (key, message) => Promise.resolve().then(() => hmacSync(key, message)),
+  equal: (a, b) => a.length === b.length && timingSafeEqual(a, b)
+};
+var webhooks = createWebhooks(backend);
+function userHid(userId, secret) {
+  return computeUserHid(backend, userId, secret);
+}
+function userHidAsync(userId, secret) {
+  return computeUserHidAsync(backend, userId, secret);
+}
+
+export { ApiError, AuthenticationError, BadRequestError, ConnectionError, NIL_UUID, NotFoundError, QuotaExceededError, RISK_BANDS, RateLimitError, SIGNALS, ServerError, ShieldLabs, ShieldLabsError, ShieldLabsManagement, SignatureVerificationError, TimeoutError, VERSION, ValidationError, WebhookParseError, evaluateIdentification, isRateLimited, riskBand, userHid, userHidAsync, webhooks };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map