@vectoral-labs/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,855 @@
+// src/errors.ts
+var VectoralError = class extends Error {
+  /** HTTP status code, or 0 for network/timeout errors. */
+  status;
+  code;
+  /** Raw response body, when there was one. */
+  responseBody;
+  constructor(message, opts) {
+    super(message, opts.cause !== void 0 ? { cause: opts.cause } : void 0);
+    this.name = "VectoralError";
+    this.code = opts.code;
+    this.status = opts.status;
+    this.responseBody = opts.responseBody;
+  }
+  /**
+   * True for failures where the request provably did not reach a decision:
+   * network errors, timeouts, and 5xx. A retry is safe only if the call also
+   * carried an `event_id` — see `docs/concepts/reliability.md`.
+   */
+  get transient() {
+    return this.code === "network_error" || this.code === "timeout" || this.code === "http_error" && this.status >= 500;
+  }
+};
+function notifyError(cb, err, context) {
+  try {
+    cb?.(err, context);
+  } catch {
+  }
+}
+var VectoralConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VectoralConfigError";
+  }
+};
+
+// src/http.ts
+function assertAck(body) {
+  if (body?.ok !== true) {
+    throw new VectoralError(
+      "vectoral: write was not acknowledged (expected `ok: true`)",
+      { code: "invalid_response", status: 200, responseBody: JSON.stringify(body) }
+    );
+  }
+  return body;
+}
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var backoffMs = (attempt) => Math.min(200 * 2 ** attempt, 5e3);
+var Transport = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  async post(path, body, po) {
+    const url = `${this.opts.baseUrl}${path}`;
+    const maxAttempts = po.idempotent ? this.opts.retries : 0;
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        return await this.doPost(
+          url,
+          body,
+          Math.max(po.timeoutMs ?? 0, this.opts.timeoutMs)
+        );
+      } catch (err) {
+        const retryable = err instanceof VectoralError && err.transient;
+        if (retryable && attempt < maxAttempts) {
+          attempt += 1;
+          await delay(backoffMs(attempt));
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+  async doPost(url, body, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await this.send(url, body, controller, timeoutMs);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async send(url, body, controller, timeoutMs) {
+    const failed = (err) => controller.signal.aborted ? new VectoralError(`request timed out after ${timeoutMs}ms`, {
+      code: "timeout",
+      status: 0,
+      cause: err
+    }) : new VectoralError(
+      `network error: ${err instanceof Error ? err.message : String(err)}`,
+      { code: "network_error", status: 0, cause: err }
+    );
+    let res;
+    try {
+      res = await this.opts.fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.opts.authHeader,
+          ...this.opts.headers
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      throw failed(err);
+    }
+    let text;
+    try {
+      text = await res.text();
+    } catch (err) {
+      throw failed(err);
+    }
+    if (!res.ok) {
+      let message = res.statusText;
+      try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.error === "string") message = parsed.error;
+      } catch {
+      }
+      throw new VectoralError(`vectoral ${res.status}: ${message}`, {
+        code: "http_error",
+        status: res.status,
+        responseBody: text
+      });
+    }
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new VectoralError("vectoral: invalid JSON in response body", {
+        code: "invalid_response",
+        status: res.status,
+        responseBody: text,
+        cause: err
+      });
+    }
+  }
+};
+
+// src/salt.ts
+var MIN_SALT_LENGTH = 32;
+var env = (name) => {
+  const p = globalThis.process;
+  return p?.env?.[name];
+};
+var PLACEHOLDER_SALTS = /* @__PURE__ */ new Set([
+  "changeme",
+  "your-salt-here",
+  "test",
+  "secret",
+  "vectoral"
+]);
+function resolveFingerprintConfig(opts) {
+  const warnings = [];
+  if (!opts?.enabled) {
+    if (opts?.shareGlobal) {
+      throw new VectoralConfigError(
+        "fingerprint.shareGlobal requires fingerprint.enabled: true"
+      );
+    }
+    return { config: null, warnings };
+  }
+  const salt = opts.salt ?? env("VECTORAL_FINGERPRINT_SALT");
+  const saltId = opts.saltId ?? env("VECTORAL_FINGERPRINT_SALT_ID");
+  if (!salt || !saltId) {
+    warnings.push(
+      "fingerprint.enabled is set but salt/saltId are missing (pass them, or set VECTORAL_FINGERPRINT_SALT and VECTORAL_FINGERPRINT_SALT_ID) \u2014 prompt fingerprinting is disabled"
+    );
+    return { config: null, warnings };
+  }
+  if (PLACEHOLDER_SALTS.has(salt.toLowerCase())) {
+    warnings.push(
+      "fingerprint.salt is a well-known placeholder value \u2014 prompt fingerprinting is disabled. Generate one with generateSalt()."
+    );
+    return { config: null, warnings };
+  }
+  if (salt.length < MIN_SALT_LENGTH) {
+    warnings.push(
+      `fingerprint.salt is only ${salt.length} characters; at least ${MIN_SALT_LENGTH} are required for a meaningful search space \u2014 prompt fingerprinting is disabled`
+    );
+    return { config: null, warnings };
+  }
+  return {
+    config: { salt, saltId, shareGlobal: opts.shareGlobal ?? false },
+    warnings
+  };
+}
+function generateSalt() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function suggestSaltId(now = /* @__PURE__ */ new Date()) {
+  const yyyy = now.getUTCFullYear();
+  const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
+  return `s_${yyyy}_${mm}`;
+}
+
+// src/resources/registrations.ts
+var RegistrationTier = {
+  Allow: 0,
+  Challenge: 1,
+  StepUp: 2
+};
+var DEADLINE_MIN_MS = 250;
+var DEADLINE_MAX_MS = 2e3;
+var DEADLINE_OVERHEAD_MS = 300;
+var Registrations = class {
+  constructor(transport, opts) {
+    this.transport = transport;
+    this.opts = opts;
+  }
+  transport;
+  opts;
+  /**
+   * Score a registration at form submit.
+   *
+   * With `failOpen` (the default) this never throws: any network failure,
+   * timeout, or HTTP error yields `tier: 0, degraded: true`. A screening check
+   * that can take your signup page down is worse than no screening check.
+   */
+  async score(req) {
+    try {
+      const body = await this.transport.post(
+        "/v1/registrations/score",
+        req,
+        {
+          idempotent: req.event_id !== void 0,
+          ...req.deadline_ms !== void 0 ? { timeoutMs: httpTimeoutFor(req.deadline_ms) } : {}
+        }
+      );
+      if (typeof body?.tier !== "number" || typeof body?.score !== "number") {
+        throw new VectoralError(
+          "vectoral: response is not a registration verdict (missing numeric `tier`/`score`)",
+          { code: "invalid_response", status: 200, responseBody: JSON.stringify(body) }
+        );
+      }
+      return {
+        registration_id: body.registration_id,
+        tier: body.tier,
+        score: body.score,
+        reasons: body.reasons ?? [],
+        ...body.duplicate !== void 0 ? { duplicate: body.duplicate } : {},
+        ...body.shadow_mode !== void 0 ? { shadow_mode: body.shadow_mode } : {},
+        degraded: false
+      };
+    } catch (err) {
+      if (!this.opts.failOpen || !(err instanceof VectoralError)) throw err;
+      notifyError(this.opts.onError, err, "registrations.score");
+      return {
+        registration_id: null,
+        tier: RegistrationTier.Allow,
+        score: 0,
+        reasons: [],
+        degraded: true,
+        error: err
+      };
+    }
+  }
+};
+function httpTimeoutFor(deadlineMs) {
+  const clamped = Math.min(Math.max(deadlineMs, DEADLINE_MIN_MS), DEADLINE_MAX_MS);
+  return clamped + DEADLINE_OVERHEAD_MS;
+}
+
+// src/fingerprint/encoding.ts
+var encoder = new TextEncoder();
+var utf8 = (s) => encoder.encode(s);
+var hex64 = (v) => v.toString(16).padStart(16, "0");
+var B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function bytesToBase64(b) {
+  let out = "";
+  let i = 0;
+  for (; i + 3 <= b.length; i += 3) {
+    const n = b[i] << 16 | b[i + 1] << 8 | b[i + 2];
+    out += B64[n >> 18 & 63] + B64[n >> 12 & 63] + B64[n >> 6 & 63] + B64[n & 63];
+  }
+  const rem = b.length - i;
+  if (rem === 1) {
+    const n = b[i] << 16;
+    out += B64[n >> 18 & 63] + B64[n >> 12 & 63] + "==";
+  } else if (rem === 2) {
+    const n = b[i] << 16 | b[i + 1] << 8;
+    out += B64[n >> 18 & 63] + B64[n >> 12 & 63] + B64[n >> 6 & 63] + "=";
+  }
+  return out;
+}
+
+// src/fingerprint/xxhash64.ts
+var MASK64 = (1n << 64n) - 1n;
+var PRIME64_1 = 0x9e3779b185ebca87n;
+var PRIME64_2 = 0xc2b2ae3d27d4eb4fn;
+var PRIME64_3 = 0x165667b19e3779f9n;
+var PRIME64_4 = 0x85ebca77c2b2ae63n;
+var PRIME64_5 = 0x27d4eb2f165667c5n;
+var rotl = (v, r) => (v << r | v >> 64n - r) & MASK64;
+var round = (acc, input) => rotl(acc + input * PRIME64_2 & MASK64, 31n) * PRIME64_1 & MASK64;
+var mergeRound = (acc, val) => (acc ^ round(0n, val)) * PRIME64_1 + PRIME64_4 & MASK64;
+var le64 = (b, i) => BigInt(b[i]) | BigInt(b[i + 1]) << 8n | BigInt(b[i + 2]) << 16n | BigInt(b[i + 3]) << 24n | BigInt(b[i + 4]) << 32n | BigInt(b[i + 5]) << 40n | BigInt(b[i + 6]) << 48n | BigInt(b[i + 7]) << 56n;
+var le32 = (b, i) => BigInt(b[i] | b[i + 1] << 8 | b[i + 2] << 16) | BigInt(b[i + 3]) << 24n;
+function xxh64(data, seed) {
+  const n = data.length;
+  let i = 0;
+  let h;
+  if (n >= 32) {
+    let v1 = seed + PRIME64_1 + PRIME64_2 & MASK64;
+    let v2 = seed + PRIME64_2 & MASK64;
+    let v3 = seed & MASK64;
+    let v4 = seed - PRIME64_1 & MASK64;
+    for (; i + 32 <= n; i += 32) {
+      v1 = round(v1, le64(data, i));
+      v2 = round(v2, le64(data, i + 8));
+      v3 = round(v3, le64(data, i + 16));
+      v4 = round(v4, le64(data, i + 24));
+    }
+    h = rotl(v1, 1n) + rotl(v2, 7n) + rotl(v3, 12n) + rotl(v4, 18n) & MASK64;
+    h = mergeRound(h, v1);
+    h = mergeRound(h, v2);
+    h = mergeRound(h, v3);
+    h = mergeRound(h, v4);
+  } else {
+    h = seed + PRIME64_5 & MASK64;
+  }
+  h = h + BigInt(n) & MASK64;
+  for (; i + 8 <= n; i += 8) {
+    h = rotl(h ^ round(0n, le64(data, i)), 27n) * PRIME64_1 + PRIME64_4 & MASK64;
+  }
+  if (i + 4 <= n) {
+    h = rotl(h ^ le32(data, i) * PRIME64_1 & MASK64, 23n) * PRIME64_2 + PRIME64_3 & MASK64;
+    i += 4;
+  }
+  for (; i < n; i++) {
+    h = rotl(h ^ BigInt(data[i]) * PRIME64_5 & MASK64, 11n) * PRIME64_1 & MASK64;
+  }
+  h ^= h >> 33n;
+  h = h * PRIME64_2 & MASK64;
+  h ^= h >> 29n;
+  h = h * PRIME64_3 & MASK64;
+  h ^= h >> 32n;
+  return h;
+}
+
+// src/fingerprint/normalize.ts
+var MAX_NORMALIZED_BYTES = 32 * 1024;
+var MIN_TOKENS = 8;
+var WHITESPACE_RE = /[\t\n\v\f\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/gu;
+var bucket = (run) => run.length === 1 ? "0" : run.length <= 3 ? "00" : "000";
+function normalizeTokens(text, collapseDigits) {
+  let s = text.normalize("NFKC").toLowerCase();
+  if (collapseDigits) s = s.replace(/[0-9]+/g, bucket);
+  const tokens = s.split(WHITESPACE_RE).filter((t) => t.length > 0);
+  return capTokens(tokens, MAX_NORMALIZED_BYTES);
+}
+var encoder2 = new TextEncoder();
+function capTokens(tokens, maxBytes) {
+  let total = 0;
+  for (let i = 0; i < tokens.length; i++) {
+    const n = encoder2.encode(tokens[i]).length + (i > 0 ? 1 : 0);
+    if (total + n > maxBytes) return tokens.slice(0, i);
+    total += n;
+  }
+  return tokens;
+}
+
+// src/fingerprint/minhash_constants.json
+var minhash_constants_default = {
+  a: [
+    "2021813335835409049",
+    "35211633415242073",
+    "1032286529175131953",
+    "2069131852558007211",
+    "1978694875717179127",
+    "92632024908598310",
+    "2227348836476178120",
+    "1241523794948756209",
+    "1281414715180458463",
+    "68168729981692814",
+    "1590120462813979606",
+    "1854116879905405569",
+    "1727992762099619348",
+    "2119624372221496183",
+    "1134157368671934749",
+    "1889971077583265806",
+    "1331960984677369123",
+    "424766757415873078",
+    "248769665290609414",
+    "379392552670680551",
+    "1071663163969004878",
+    "1088771757875541551",
+    "525798032415552240",
+    "1801279986719471057",
+    "2160440382124210661",
+    "542330089998054146",
+    "34780299756627497",
+    "864036708820350785",
+    "751227794015040822",
+    "1831265118418158537",
+    "204218925239092992",
+    "1011056663065980301",
+    "128115764264397803",
+    "1505159286259654375",
+    "1191262882168263883",
+    "740932194332428643",
+    "1593133303768919397",
+    "1618445643131025398",
+    "509860659052195117",
+    "1297874447217707170",
+    "1085228754310083322",
+    "119203851975622499",
+    "746088216632479645",
+    "259900005950983532",
+    "66551348091461166",
+    "1059503232844960577",
+    "255114382916886367",
+    "235744748558065614",
+    "2028861987517208555",
+    "360011178275786621",
+    "1854044834799956775",
+    "1374770026548661332",
+    "343207213113865673",
+    "679958157873282646",
+    "37240336268295500",
+    "1548562591492889568",
+    "1361800152292289303",
+    "1932288454007280877",
+    "1076765584066084170",
+    "177822684145201725",
+    "456689636495482067",
+    "486814351553121932",
+    "794790680498008333",
+    "1316082831976020478"
+  ],
+  b: [
+    "1610806161966735655",
+    "2047677487906336758",
+    "1275918690921527573",
+    "1189635637049945452",
+    "1281403506175249200",
+    "2081287680319054019",
+    "192492701049451181",
+    "1425310758080347673",
+    "2039895406543135671",
+    "1501410306195161698",
+    "1375342227526167841",
+    "308564847782375531",
+    "1049081053798665627",
+    "1584374554533213180",
+    "29377296984809279",
+    "455684791224639069",
+    "1701487829648668302",
+    "2052418598727637090",
+    "1782181777482596496",
+    "1405174944115920234",
+    "142697458214177465",
+    "2230201305625643893",
+    "1274214892560249329",
+    "108256409252165718",
+    "202993594240856655",
+    "1113572638037699701",
+    "293926112313331388",
+    "1266928255254575415",
+    "1378430457629976093",
+    "2279739612382497097",
+    "253506377110122931",
+    "2121229711337812063",
+    "1051445940000326502",
+    "1585510647031081366",
+    "513071450608671516",
+    "1692342139284161390",
+    "2099966457055163223",
+    "80748089313457135",
+    "915320896732073477",
+    "206016695116487206",
+    "313255738298670383",
+    "350087690804126655",
+    "566597602277147588",
+    "2286505508950253560",
+    "59749117790775024",
+    "1254224403872925255",
+    "62443264473934934",
+    "879402817051146288",
+    "579168338468101788",
+    "109843255863370304",
+    "2262200584042665321",
+    "2222280625931509317",
+    "1738258800373110427",
+    "208491563184516265",
+    "1409983652033055411",
+    "1950247065602176885",
+    "975504388282036391",
+    "804721776541171833",
+    "1241808411053857370",
+    "2092916582302830364",
+    "1783854280345651430",
+    "1299024548425035192",
+    "125336755862468958",
+    "646127779493447141"
+  ],
+  comment: "Canonical MinHash permutation constants. Decimal strings. p = 2^61 - 1. DO NOT REGENERATE (breaking algo_version change).",
+  p: "2305843009213693951"
+};
+
+// src/fingerprint/similarity.ts
+var saltSeed = (salt) => xxh64(utf8(salt), 0n);
+var GLOBAL_SEED = 0n;
+var P61 = (1n << 61n) - 1n;
+var A = minhash_constants_default.a.map(BigInt);
+var B = minhash_constants_default.b.map(BigInt);
+if (A.length !== 64 || B.length !== 64) {
+  throw new Error("fingerprint: minhash_constants.json must have 64 a and 64 b values");
+}
+function shingleSet(tokens, seed) {
+  const seen = /* @__PURE__ */ new Set();
+  const hashes = [];
+  for (let i = 0; i + 3 <= tokens.length; i++) {
+    const sh = `${tokens[i]} ${tokens[i + 1]} ${tokens[i + 2]}`;
+    if (seen.has(sh)) continue;
+    seen.add(sh);
+    hashes.push(xxh64(utf8(sh), seed));
+  }
+  return hashes;
+}
+function simHash64(hashes) {
+  const sums = new Int32Array(64);
+  for (const h of hashes) {
+    const lo = Number(h & 0xffffffffn);
+    const hi = Number(h >> 32n);
+    for (let i = 0; i < 32; i++) {
+      sums[i] += lo >>> i & 1 ? 1 : -1;
+      sums[i + 32] += hi >>> i & 1 ? 1 : -1;
+    }
+  }
+  let out = 0n;
+  for (let i = 0; i < 64; i++) {
+    if (sums[i] > 0) out |= 1n << BigInt(i);
+  }
+  return out;
+}
+var permute = (a, b, hp) => (a * hp + b) % P61;
+function minHash64x16(hashes) {
+  const sig = new Uint16Array(64);
+  const reduced = hashes.map((h) => h % P61);
+  for (let i = 0; i < 64; i++) {
+    let min = P61;
+    const a = A[i];
+    const b = B[i];
+    for (const hp of reduced) {
+      const v = permute(a, b, hp);
+      if (v < min) min = v;
+    }
+    sig[i] = Number(min & 0xffffn);
+  }
+  return sig;
+}
+function signatureBytes(sig) {
+  const out = new Uint8Array(128);
+  for (let i = 0; i < 64; i++) {
+    out[2 * i] = sig[i] & 255;
+    out[2 * i + 1] = sig[i] >> 8;
+  }
+  return out;
+}
+function bandKeys(sig, seed) {
+  const keys = [];
+  const buf = new Uint8Array(8);
+  for (let band = 0; band < 16; band++) {
+    for (let r = 0; r < 4; r++) {
+      const v = sig[band * 4 + r];
+      buf[2 * r] = v & 255;
+      buf[2 * r + 1] = v >> 8;
+    }
+    keys.push(BigInt.asIntN(64, xxh64(buf, seed)));
+  }
+  return keys;
+}
+function exactHash(text, seed) {
+  return xxh64(utf8(normalizeTokens(text, false).join(" ")), seed);
+}
+
+// src/fingerprint/index.ts
+function computeFingerprint(text, salt, opts) {
+  const seed = saltSeed(salt);
+  const tokens = normalizeTokens(text, true);
+  if (tokens.length < MIN_TOKENS) return { tooShort: true };
+  const hashes = shingleSet(tokens, seed);
+  const fp = {
+    tooShort: false,
+    simhash: hex64(simHash64(hashes)),
+    exactHash: hex64(exactHash(text, seed))
+  };
+  if (opts.minHash) {
+    const sig = minHash64x16(hashes);
+    fp.minhashB64 = bytesToBase64(signatureBytes(sig));
+    fp.bandKeys = bandKeys(sig, seed).map((k) => k.toString(10));
+  }
+  if (opts.global) {
+    fp.simhashGlobal = hex64(simHash64(shingleSet(tokens, GLOBAL_SEED)));
+  }
+  return fp;
+}
+function conversationKey(firstUserMessage, salt) {
+  const tokens = normalizeTokens(firstUserMessage, true);
+  return "c_" + hex64(xxh64(utf8(tokens.join(" ")), saltSeed(salt)));
+}
+
+// src/resources/inference.ts
+var FAIL_OPEN_SCORE = {
+  score: 0,
+  tier: "low",
+  reasons: [],
+  deep_mode_active: false,
+  baseline_ready: false,
+  shadow_mode: false,
+  degraded: true
+};
+var Inference = class {
+  constructor(transport, opts) {
+    this.transport = transport;
+    this.opts = opts;
+  }
+  transport;
+  opts;
+  warnedMissingFingerprintInput = false;
+  /** Pre-call risk score. Call before invoking the LLM. */
+  async score(req) {
+    try {
+      const body = await this.transport.post(
+        "/v1/score",
+        this.prepare(req),
+        { idempotent: false }
+      );
+      const raw = body;
+      if (typeof raw?.score !== "number" || typeof raw?.tier !== "string" || raw.tier === "" || typeof raw?.deep_mode_active !== "boolean" || typeof raw?.baseline_ready !== "boolean" || typeof raw?.shadow_mode !== "boolean" || !(Array.isArray(raw?.reasons) || raw?.reasons === null)) {
+        throw new VectoralError(
+          "vectoral: response is not a score verdict (missing or malformed required fields)",
+          { code: "invalid_response", status: 200, responseBody: JSON.stringify(body) }
+        );
+      }
+      return raw.reasons === null ? { ...body, reasons: [] } : body;
+    } catch (err) {
+      if (!this.opts.failOpen || !(err instanceof VectoralError)) throw err;
+      notifyError(this.opts.onError, err, "inference.score");
+      return { ...FAIL_OPEN_SCORE, error: err };
+    }
+  }
+  /**
+   * Post-call token/cost telemetry. Call after the LLM responds.
+   *
+   * This is the feedback that makes every later score meaningful — it is where
+   * token velocity and cost signals come from. It never fails open: telemetry
+   * you silently drop is telemetry you never notice missing.
+   */
+  postCall(event) {
+    return this.transport.post("/v1/events/post-call", event, {
+      idempotent: event.event_id !== void 0
+    }).then(assertAck);
+  }
+  /**
+   * Consume `prompt_text_to_fingerprint` (always stripped from the wire,
+   * enabled or not) and attach the computed block when fingerprinting is
+   * active. The caller's object is never mutated.
+   */
+  prepare(req) {
+    const { prompt_text_to_fingerprint: text, ...rest } = req.request;
+    const out = { ...req, request: rest };
+    const cfg = this.opts.fingerprint;
+    if (!cfg) {
+      if (text !== void 0 && text !== "" && !this.warnedMissingFingerprintInput) {
+        this.warnedMissingFingerprintInput = true;
+        this.opts.onWarning?.(
+          "request.prompt_text_to_fingerprint was supplied but prompt fingerprinting is not configured \u2014 the text was stripped and no fingerprint was sent. Set `fingerprint: { enabled: true, salt, saltId }`"
+        );
+      }
+      return out;
+    }
+    if (rest.prompt_fingerprint !== void 0) return out;
+    if (text === void 0 || text === "") {
+      if (!this.warnedMissingFingerprintInput) {
+        this.warnedMissingFingerprintInput = true;
+        this.opts.onWarning?.(
+          "prompt fingerprinting is configured but this score() call has no request.prompt_text_to_fingerprint \u2014 no fingerprint sent"
+        );
+      }
+      return out;
+    }
+    const fp = computeFingerprint(text, cfg.salt, {
+      minHash: true,
+      global: cfg.shareGlobal
+    });
+    if (fp.tooShort) return out;
+    const block = {
+      v: 1,
+      salt_id: cfg.saltId,
+      simhash: fp.simhash,
+      exact_hash: fp.exactHash,
+      conversation_key: req.session_id ?? conversationKey(text, cfg.salt),
+      minhash: fp.minhashB64,
+      band_keys: fp.bandKeys
+    };
+    if (cfg.shareGlobal) block.simhash_global = fp.simhashGlobal;
+    out.request = { ...rest, prompt_fingerprint: block };
+    return out;
+  }
+};
+
+// src/resources/identity.ts
+var Identity = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Record an authentication event.
+   *
+   * Use the same IP shape here as on `inference.score()`: the accounts-per-IP
+   * query unions both sources, so mixing raw addresses on one and tokens on the
+   * other splits your own sybil graph.
+   */
+  record(event) {
+    return this.transport.post("/v1/identity", event, {
+      idempotent: event.event_id !== void 0
+    }).then(assertAck);
+  }
+  /**
+   * Convenience for the common signup case: record the event and link the
+   * registration in one call.
+   */
+  linkRegistration(accountId, registrationId, extra = {}) {
+    return this.record({
+      ...extra,
+      account_id: accountId,
+      event_type: "signup",
+      registration_id: registrationId
+    });
+  }
+};
+
+// src/resources/labels.ts
+var Labels = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Report a verdict you reached yourself — a chargeback, a ban, a support
+   * resolution. Label legitimate accounts too: a corpus of only-fraud labels
+   * teaches a model nothing about the boundary.
+   */
+  submit(req) {
+    return this.transport.post("/v1/labels", req, { idempotent: false }).then(assertAck);
+  }
+  fraud(accountId, notes) {
+    return this.submit({
+      account_id: accountId,
+      label: "fraud",
+      ...notes !== void 0 ? { notes } : {}
+    });
+  }
+  legitimate(accountId, notes) {
+    return this.submit({
+      account_id: accountId,
+      label: "legitimate",
+      ...notes !== void 0 ? { notes } : {}
+    });
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.vectoral.cloud";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var DEFAULT_RETRIES = 2;
+var env2 = (name) => {
+  const p = globalThis.process;
+  return p?.env?.[name];
+};
+var Vectoral = class {
+  registrations;
+  inference;
+  identity;
+  labels;
+  /** True when prompt fingerprinting resolved to a usable salt. */
+  fingerprintingActive;
+  constructor(opts = {}) {
+    const customerId = opts.customerId;
+    const apiKey = opts.apiKey ?? (customerId ? void 0 : env2("VECTORAL_API_KEY"));
+    if (apiKey && customerId) {
+      throw new VectoralConfigError(
+        "provide either `apiKey` or `customerId`, not both"
+      );
+    }
+    let authHeader;
+    if (apiKey) {
+      authHeader = { Authorization: `Bearer ${apiKey}` };
+    } else if (customerId) {
+      authHeader = { "X-Customer-ID": customerId };
+    } else {
+      throw new VectoralConfigError(
+        "`apiKey` is required (pass it, or set VECTORAL_API_KEY)"
+      );
+    }
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new VectoralConfigError(
+        "no global fetch available \u2014 pass `fetch` (Node >=18 has it built in)"
+      );
+    }
+    const onWarning = opts.onWarning ?? ((m) => console.warn(`[vectoral] ${m}`));
+    const resolved = resolveFingerprintConfig(opts.fingerprint);
+    for (const w of resolved.warnings) onWarning(w);
+    this.fingerprintingActive = resolved.config !== null;
+    const transport = new Transport({
+      baseUrl: (opts.baseUrl ?? env2("VECTORAL_BASE_URL") ?? DEFAULT_BASE_URL).replace(
+        /\/+$/,
+        ""
+      ),
+      authHeader,
+      headers: opts.headers ?? {},
+      timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      fetch: fetchImpl,
+      retries: opts.retries ?? DEFAULT_RETRIES
+    });
+    const failOpen = opts.failOpen ?? true;
+    this.registrations = new Registrations(transport, {
+      failOpen,
+      onError: opts.onError
+    });
+    this.inference = new Inference(transport, {
+      failOpen,
+      fingerprint: resolved.config,
+      onError: opts.onError,
+      onWarning
+    });
+    this.identity = new Identity(transport);
+    this.labels = new Labels(transport);
+  }
+};
+var createClient = (opts = {}) => new Vectoral(opts);
+export {
+  Identity,
+  Inference,
+  Labels,
+  MIN_SALT_LENGTH,
+  RegistrationTier,
+  Registrations,
+  Vectoral,
+  VectoralConfigError,
+  VectoralError,
+  computeFingerprint,
+  conversationKey,
+  createClient,
+  generateSalt,
+  suggestSaltId
+};
+//# sourceMappingURL=index.js.map