@vectoral-labs/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,572 @@
+/** Categorizes why a call failed, so callers can branch without string-matching. */
+type VectoralErrorCode = "http_error" | "network_error" | "timeout" | "invalid_response";
+/** Thrown for any non-2xx response, network failure, or timeout. */
+declare class VectoralError extends Error {
+    /** HTTP status code, or 0 for network/timeout errors. */
+    readonly status: number;
+    readonly code: VectoralErrorCode;
+    /** Raw response body, when there was one. */
+    readonly responseBody: string | undefined;
+    constructor(message: string, opts: {
+        code: VectoralErrorCode;
+        status: number;
+        responseBody?: string;
+        cause?: unknown;
+    });
+    /**
+     * 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(): boolean;
+}
+/** Thrown at construction time for a misconfigured client. Never at call time. */
+declare class VectoralConfigError extends Error {
+    constructor(message: string);
+}
+
+/** Minimal fetch signature so this runs on Node 18+, Deno, Bun, and edge runtimes. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface TransportOptions {
+    baseUrl: string;
+    authHeader: Record<string, string>;
+    headers: Record<string, string>;
+    timeoutMs: number;
+    fetch: FetchLike;
+    /**
+     * Attempts after the first, for transient failures. Only applied to requests
+     * the caller marked idempotent — see `post()`.
+     */
+    retries: number;
+}
+interface PostOptions {
+    /**
+     * Whether a retry is safe. Every Vectoral write endpoint mints a new row per
+     * call unless the body carries an `event_id`, so the transport refuses to
+     * retry anything without one: a blind retry after a response lost in transit
+     * would double-write.
+     */
+    idempotent: boolean;
+    /**
+     * A per-call timeout FLOOR, used by `deadline_ms`. It can only raise the
+     * effective timeout, never lower it: a caller who configured `timeoutMs`
+     * explicitly must not have it silently reduced by asking the server for a
+     * tight budget, or a slow link turns every good verdict into a fail-open
+     * zero — the failure mode `httpTimeoutFor` exists to prevent.
+     */
+    timeoutMs?: number;
+}
+declare class Transport {
+    private readonly opts;
+    constructor(opts: TransportOptions);
+    post<T>(path: string, body: unknown, po: PostOptions): Promise<T>;
+    private doPost;
+    private send;
+}
+
+/** Minimum salt length we will accept. 32 hex chars = 128 bits. */
+declare const MIN_SALT_LENGTH = 32;
+interface FingerprintOptions$1 {
+    /**
+     * Master switch. When false or absent, prompt text is never read and never
+     * hashed — the SDK does not touch it.
+     */
+    enabled: boolean;
+    /**
+     * Secret tenant salt. Defaults to `process.env.VECTORAL_FINGERPRINT_SALT`.
+     * Treat it like a signing key: 128+ bits, out of source control, rotated
+     * deliberately.
+     */
+    salt?: string;
+    /**
+     * Generation id for `salt`, e.g. `s_2026_09`. Sent alongside every
+     * fingerprint so the server knows which generation a value belongs to and
+     * never compares across a rotation. Defaults to
+     * `process.env.VECTORAL_FINGERPRINT_SALT_ID`.
+     */
+    saltId?: string;
+    /**
+     * Additionally compute an UNSALTED fingerprint, comparable across all
+     * Vectoral customers who opted in. Requires `enabled`. Opting in
+     * acknowledges the reduced confidentiality of that tier.
+     */
+    shareGlobal?: boolean;
+}
+/** Resolved config. `null` means fingerprinting is inert for this client. */
+interface ResolvedFingerprintConfig {
+    salt: string;
+    saltId: string;
+    shareGlobal: boolean;
+}
+/**
+ * Generate a fresh tenant salt: 32 random bytes, hex-encoded.
+ *
+ * For bootstrapping and rotation. Store the output in your secret manager and
+ * pair it with a new `saltId`; do not call this at process start, which would
+ * mint a new salt per deploy and make every stored fingerprint incomparable.
+ */
+declare function generateSalt(): string;
+/**
+ * A conventional salt id for the current month, e.g. `s_2026_09`. Any stable
+ * string works; the convention just makes rotations self-documenting in logs.
+ */
+declare function suggestSaltId(now?: Date): string;
+
+/** Browser-environment tells, as collected by `@vectoral-labs/browser`. */
+interface RegistrationClientBlock {
+    /** `navigator.webdriver`. Cheap, and a strong tell when true. */
+    webdriver?: boolean;
+    /** Your own [0,1] canvas/WebGL/capability-consistency score. */
+    fingerprint_anomaly?: number;
+    /** Milliseconds from page load to submit. */
+    load_to_submit_ms?: number;
+    /** IANA zone, compared against the observed origin. */
+    timezone?: string;
+}
+/** Per-field fill behaviour. `pasted` is the highest-value bit. */
+interface RegistrationFormField {
+    pasted?: boolean;
+    keystrokes?: number;
+    corrections?: number;
+    focus_ms?: number;
+}
+interface RegistrationFormBlock {
+    load_to_submit_ms?: number;
+    fields?: Record<string, RegistrationFormField>;
+}
+/**
+ * Body of POST /v1/registrations/score.
+ *
+ * Every optional field you omit produces an **absent** signal, never a
+ * favourable one: no `device_fingerprint` does not mean "no device reuse", and
+ * no `form` does not mean "a human typed it".
+ */
+interface RegistrationRequest {
+    /** The submitted address. The only required field. */
+    email: string;
+    /**
+     * Idempotency key. A repeat of the same `(customer, event_id)` returns the
+     * original verdict with `duplicate: true` and writes nothing.
+     *
+     * Strongly recommended, and the SDK only retries transient failures when it
+     * is present. Derive it from your own pending-signup record, not from a
+     * transport message id.
+     */
+    event_id?: string;
+    /** The user's browser IP at submit — the one your server observed. */
+    ip?: string;
+    /** Your own keyed token instead of `ip`. Disables per-subnet velocity. */
+    ip_hash?: string;
+    asn?: number;
+    ip_country?: string;
+    /** The country the user claimed, if your form collects one. */
+    declared_country?: string;
+    user_agent?: string;
+    /**
+     * Client-side device identifier. **The single highest-value optional field** —
+     * one device across many registrations is the strongest farm signal there is.
+     * `@vectoral-labs/browser`'s `deviceFingerprint()` produces one.
+     */
+    device_fingerprint?: string;
+    /** A token from the browser sensor, if deployed. */
+    sensor_token?: string;
+    client?: RegistrationClientBlock;
+    form?: RegistrationFormBlock;
+    phone?: string;
+    username?: string;
+    referrer?: string;
+    /**
+     * Whole-call budget in ms for the server's external lookups. Defaults to 400
+     * server-side and is clamped to [250, 2000] rather than rejected. The SDK
+     * raises its own HTTP timeout to sit above whatever you set here.
+     */
+    deadline_ms?: number;
+}
+/**
+ * What to do with the signup. An **open, ordered scale** — higher means more
+ * friction. Compare (`tier >= Tier.StepUp`); never switch exhaustively, because
+ * new tiers can be added without a new API version.
+ */
+declare const RegistrationTier: {
+    readonly Allow: 0;
+    readonly Challenge: 1;
+    readonly StepUp: 2;
+};
+interface RegistrationVerdict {
+    /**
+     * Opaque handle to pass back on `identity.record()` when the account is
+     * created. `null` only when the call failed open — there is nothing to link.
+     */
+    registration_id: string | null;
+    /** See `RegistrationTier`. Compare, do not switch. */
+    tier: number;
+    /** The underlying risk score in [0,1], for your own tuning. */
+    score: number;
+    /** Up to three contributing facts, most significant first. Do not branch on these. */
+    reasons: string[];
+    /** True on an idempotent replay of a previous `event_id`. */
+    duplicate?: boolean;
+    /** True during the warm-up window, when `tier` is pinned to 0. */
+    shadow_mode?: boolean;
+    /**
+     * True when this verdict is the SDK's fail-open default rather than a real
+     * answer — the call errored and `failOpen` was on. Log it: a flow silently
+     * running at `tier: 0` because Vectoral is unreachable looks identical to one
+     * where every signup is clean.
+     */
+    degraded: boolean;
+    /** The underlying failure, when `degraded`. */
+    error?: VectoralError;
+}
+interface RegistrationsOptions {
+    failOpen: boolean;
+    onError: ((err: VectoralError, context: string) => void) | undefined;
+}
+declare class Registrations {
+    private readonly transport;
+    private readonly opts;
+    constructor(transport: Transport, opts: RegistrationsOptions);
+    /**
+     * 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.
+     */
+    score(req: RegistrationRequest): Promise<RegistrationVerdict>;
+}
+
+/** Risk banding returned alongside the numeric score. */
+type Tier = "low" | "medium" | "high";
+/**
+ * Reason codes that can appear in a score response, as a hint for autocomplete.
+ *
+ * **This list is not exhaustive and cannot be made exhaustive.** Reasons are
+ * produced by the scoring algorithm running server-side, which ships
+ * independently of this package — a new one can appear in a response without an
+ * SDK release. The `(string & {})` member is what makes that safe: an unlisted
+ * code type-checks. It is also why you must not write an exhaustive `switch`
+ * over this type, and why `reasons` is for your logs and support conversations
+ * rather than for branching. `tier` is the field to act on.
+ *
+ * The server returns at most three, ordered by contribution.
+ *
+ * Listed below by where the code comes from, because the three groups behave
+ * differently — an operational code means the verdict was overridden and the
+ * algorithm's opinion is not what you are looking at. See
+ * `docs/concepts/inference-scoring.md` for what each one means.
+ */
+type ReasonCode = "machine_paced" | "hidden_telemetry" | "birth_cohort" | "probing" | "resource_shape" | "value_extraction" | "resource_extraction" | "datacenter_origin" | "account_risk" | "synthetic_noop" | "account_blocked" | "spend_cap_exceeded:account" | "spend_cap_exceeded:org" | "scoring_unavailable" | "reputation_discount" | "webdriver_present" | "automation_signature" | "headless_browser" | "no_accept_languages" | "missing_chrome_object" | "no_human_interaction" | "no_pointer_activity" | "cursor_teleport" | "thin_fingerprint" | (string & {});
+/**
+ * Account-context block. All fields optional but recommended.
+ *
+ * Both fields are sent verbatim in the request body — this block is context you
+ * supply, not something derived from the prompt. Worth knowing if anything on
+ * your egress path inspects outgoing bodies: a label you chose will appear in
+ * them as plain text. See `docs/concepts/inference-scoring.md`.
+ */
+interface AccountBlock {
+    /** RFC 3339 timestamp of when the account first existed in your system. */
+    first_seen?: string;
+    /**
+     * Free-form tier label, e.g. "free" | "pro" | "enterprise". Sent as given;
+     * use a stable internal label rather than anything user-supplied.
+     */
+    subscription_tier?: string;
+}
+/**
+ * Per-session behavioral signals.
+ *
+ * Semantics matter: OMITTING this block entirely differs from sending it with
+ * zero values. If absent, session-derived signals are skipped. If present (even
+ * as `{}`), they participate — and `interaction_events_count: 0` is a
+ * meaningful "scripted-shaped" signal.
+ */
+interface SessionSignals {
+    ms_since_last_request?: number;
+    ms_since_page_load?: number;
+    interaction_events_count?: number;
+    is_first_request_in_session?: boolean;
+    ms_since_signup?: number;
+}
+/**
+ * Wire form of the prompt fingerprint. 64-bit values are strings (hex for
+ * hashes, decimal for band keys) because JSON cannot carry 64-bit integers
+ * safely through every runtime.
+ */
+interface PromptFingerprintBlock {
+    v: 1;
+    salt_id: string;
+    simhash: string;
+    exact_hash: string;
+    conversation_key?: string;
+    minhash?: string;
+    band_keys?: string[];
+    simhash_global?: string;
+}
+/** Per-request context. */
+interface RequestBlock {
+    /**
+     * End-user IP. Drives datacenter / IP-rotation / sybil signals. Use the IP
+     * your SERVER observed, not one reported by the browser.
+     */
+    ip?: string;
+    ip_hash?: string;
+    user_agent?: string;
+    /** The model you're about to invoke, e.g. "claude-opus-5". */
+    model_requested?: string;
+    estimated_prompt_tokens?: number;
+    /** Pass `null` or omit to skip session signals entirely. */
+    session_signals?: SessionSignals | null;
+    /** Only used by Deep Mode. Never leaves the customer VPC. */
+    prompt_text?: string;
+    /** Customer-precomputed embedding (alternative to `prompt_text`). */
+    prompt_embedding?: number[];
+    /**
+     * LOCAL-ONLY input for prompt fingerprinting. When fingerprinting is
+     * configured, the SDK hashes this in-process and attaches
+     * `prompt_fingerprint`. **This field is always stripped before the request
+     * leaves the process** — enabled or not — and is independent of
+     * `prompt_text`/Deep Mode.
+     */
+    prompt_text_to_fingerprint?: string;
+    /** Normally set by the SDK; pass it yourself only if you precompute. */
+    prompt_fingerprint?: PromptFingerprintBlock;
+}
+/** Body of POST /v1/score. */
+interface ScoreRequest {
+    /** Stable end-user identifier; the primary join key for scoring history. */
+    account_id: string;
+    /** Your own session token; stored for forensic correlation. */
+    session_id?: string;
+    account?: AccountBlock;
+    request: RequestBlock;
+}
+interface ScoreResponse {
+    /** Calibrated [0,1] score. 0 = clean, 1 = certain fraud. */
+    score: number;
+    /** low (<0.4) | medium (<0.7) | high (>=0.7). */
+    tier: Tier;
+    /** Up to 3 reason codes. */
+    reasons: ReasonCode[];
+    deep_mode_active: boolean;
+    /**
+     * False while the per-account baseline is still forming: the score is
+     * provisional — advisory, not enforcement-grade.
+     */
+    baseline_ready: boolean;
+    /** True during the customer's warm-up window. The score is still real. */
+    shadow_mode: boolean;
+    /** Diagnostic only; treat as an opaque string. */
+    algorithm?: string;
+    algorithm_version?: string;
+    /** The Vectoral release that answered, e.g. `0.1.7`. */
+    service_version?: string;
+    /**
+     * True when this is the SDK's fail-open default rather than a real verdict.
+     * See `RegistrationVerdict.degraded`.
+     */
+    degraded?: boolean;
+    /** The underlying failure, when `degraded`. */
+    error?: VectoralError;
+}
+/** Body of POST /v1/events/post-call. */
+interface PostCallEvent {
+    /** Must match the `account_id` from the preceding score call. */
+    account_id: string;
+    session_id?: string;
+    /** Recommended; omitting it loses model-mix features. */
+    model?: string;
+    /** Required if `inference_cost_usd` is not supplied. */
+    prompt_tokens?: number;
+    /** Required if `inference_cost_usd` is not supplied. */
+    completion_tokens?: number;
+    latency_ms?: number;
+    /** If omitted, the server computes cost from its bundled rate table. */
+    inference_cost_usd?: number;
+    /** Idempotency key. Also what makes an SDK-level retry safe. */
+    event_id?: string;
+}
+interface OkResponse {
+    ok: boolean;
+    duplicate?: boolean;
+}
+interface InferenceOptions {
+    failOpen: boolean;
+    fingerprint: ResolvedFingerprintConfig | null;
+    onError: ((err: VectoralError, context: string) => void) | undefined;
+    onWarning: ((message: string) => void) | undefined;
+}
+declare class Inference {
+    private readonly transport;
+    private readonly opts;
+    private warnedMissingFingerprintInput;
+    constructor(transport: Transport, opts: InferenceOptions);
+    /** Pre-call risk score. Call before invoking the LLM. */
+    score(req: ScoreRequest): Promise<ScoreResponse>;
+    /**
+     * 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: PostCallEvent): Promise<OkResponse>;
+    /**
+     * 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.
+     */
+    private prepare;
+}
+
+type IdentityEventType = "signup" | "login" | "dashboard";
+interface IdentityEvent {
+    /** Created if not already present, so identity-only accounts still surface. */
+    account_id: string;
+    /** Defaults to `login` server-side. */
+    event_type?: IdentityEventType;
+    /** The user's real browser IP at that moment. */
+    ip?: string;
+    /** Your own keyed token instead of `ip`. */
+    ip_hash?: string;
+    asn?: number;
+    ip_country?: string;
+    user_agent?: string;
+    /** Idempotency key. Also what makes an SDK-level retry safe. */
+    event_id?: string;
+    /**
+     * The handle from `registrations.score()`. Send it once, on the `signup`
+     * event, and the fraud labels you later report reach back to the registration
+     * that produced the account. That is the feedback loop.
+     *
+     * It can arrive late — if you gate account creation on email verification,
+     * store the id with your pending-signup record and send it whenever the
+     * account is finally created. An unknown or already-linked id is ignored,
+     * never rejected.
+     */
+    registration_id?: string;
+}
+declare class Identity {
+    private readonly transport;
+    constructor(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: IdentityEvent): Promise<OkResponse>;
+    /**
+     * Convenience for the common signup case: record the event and link the
+     * registration in one call.
+     */
+    linkRegistration(accountId: string, registrationId: string, extra?: Omit<IdentityEvent, "account_id" | "registration_id" | "event_type">): Promise<OkResponse>;
+}
+
+type Label = "fraud" | "legitimate";
+interface LabelRequest {
+    account_id: string;
+    label: Label;
+    notes?: string;
+}
+declare class Labels {
+    private readonly transport;
+    constructor(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: LabelRequest): Promise<OkResponse>;
+    fraud(accountId: string, notes?: string): Promise<OkResponse>;
+    legitimate(accountId: string, notes?: string): Promise<OkResponse>;
+}
+
+interface VectoralOptions {
+    /**
+     * API key (`vg_live_…`), sent as `Authorization: Bearer`. Defaults to
+     * `process.env.VECTORAL_API_KEY`. Provide exactly one of `apiKey` or
+     * `customerId`.
+     */
+    apiKey?: string;
+    /**
+     * Customer identifier, sent as `X-Customer-ID`. Only for a self-hosted or
+     * in-VPC deployment running in header auth mode.
+     */
+    customerId?: string;
+    /** API base URL. Defaults to `VECTORAL_BASE_URL`, then the hosted endpoint. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation. Defaults to global fetch. */
+    fetch?: FetchLike;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /**
+     * Retry attempts for transient failures. Default 2.
+     *
+     * **Only applied to calls that carry an `event_id`.** Every write endpoint
+     * mints a new row per call, so retrying a request without an idempotency key
+     * would double-write after a response lost in transit. Supplying `event_id`
+     * is what buys you retries.
+     */
+    retries?: number;
+    /**
+     * Return a safe default instead of throwing when a scoring call fails.
+     * Default true. Applies to `registrations.score()` and `inference.score()`;
+     * results carry `degraded: true`. Telemetry and label calls always throw —
+     * you want to know when those are being dropped.
+     */
+    failOpen?: boolean;
+    /** Privacy-preserving prompt fingerprinting. Off unless `enabled`. */
+    fingerprint?: FingerprintOptions$1;
+    /** Called for every fail-open failure. Default: none (silent). Wire this up. */
+    onError?: (err: VectoralError, context: string) => void;
+    /** Called for non-fatal configuration problems. Defaults to `console.warn`. */
+    onWarning?: (message: string) => void;
+}
+/**
+ * Server-side Vectoral client.
+ *
+ * Use this on your backend only. It holds a secret API key, and the signals it
+ * sends — above all the client IP — are only trustworthy when your own server
+ * observed them.
+ */
+declare class Vectoral {
+    readonly registrations: Registrations;
+    readonly inference: Inference;
+    readonly identity: Identity;
+    readonly labels: Labels;
+    /** True when prompt fingerprinting resolved to a usable salt. */
+    readonly fingerprintingActive: boolean;
+    constructor(opts?: VectoralOptions);
+}
+/** Convenience factory equivalent to `new Vectoral(opts)`. */
+declare const createClient: (opts?: VectoralOptions) => Vectoral;
+
+interface FingerprintOptions {
+    /** Also compute the MinHash signature + band keys. */
+    minHash: boolean;
+    /** Also compute the unsalted global SimHash (cross-customer opt-in). */
+    global: boolean;
+}
+interface ComputedFingerprint {
+    /** True when the prompt is under the 8-token floor; no other field is set. */
+    tooShort: boolean;
+    simhash?: string;
+    exactHash?: string;
+    minhashB64?: string;
+    bandKeys?: string[];
+    simhashGlobal?: string;
+}
+/** Run the full normative pipeline over text with the tenant salt. */
+declare function computeFingerprint(text: string, salt: string, opts: FingerprintOptions): ComputedFingerprint;
+/**
+ * Fallback conversation key derived from the first user message:
+ * "c_" + hex64(XXH64(normalized text, tenant seed)).
+ */
+declare function conversationKey(firstUserMessage: string, salt: string): string;
+
+export { type AccountBlock, type ComputedFingerprint, type FetchLike, type FingerprintOptions$1 as FingerprintOptions, Identity, type IdentityEvent, type IdentityEventType, Inference, type Label, type LabelRequest, Labels, MIN_SALT_LENGTH, type OkResponse, type PostCallEvent, type PromptFingerprintBlock, type ReasonCode, type RegistrationClientBlock, type RegistrationFormBlock, type RegistrationFormField, type RegistrationRequest, RegistrationTier, type RegistrationVerdict, Registrations, type RequestBlock, type ScoreRequest, type ScoreResponse, type SessionSignals, type Tier, Vectoral, VectoralConfigError, VectoralError, type VectoralErrorCode, type VectoralOptions, computeFingerprint, conversationKey, createClient, generateSalt, suggestSaltId };