@heedeo/sdk 0.0.0-stage → 0.1.0-pilot.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Heedeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# Heedeo package quickstart
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pilot package for Node.js 20.18+, Next.js App Router, and Cloudflare Workers with `nodejs_compat`. It handles browser loading, same-domain forwarding, event requests, timeouts and one retry. Heedeo returns signals; your app still owns signup and authentication.
+
+## 1. Install
+
+```sh
+npm install @heedeo/sdk
+```
+
+The package is published on npm as `@heedeo/sdk`. It has no runtime dependencies.
+
+Get your keys at https://app.heedeo.com/review/sign-up. Save the secret in your server's environment settings, including your deployed environment. Never put it in a `NEXT_PUBLIC_` variable.
+
+```sh
+HEEDEO_SECRET_KEY=sk_your_secret_key
+NEXT_PUBLIC_HEEDEO_KEY=pk_your_publishable_key
+```
+
+## 2. Configure the server once
+
+```ts
+// lib/heedeo.ts: import only from server files
+import { Heedeo } from '@heedeo/sdk';
+import { trustedClientIp } from './trusted-client-ip';
+
+export const heedeo = new Heedeo({
+  secretKey: process.env.HEEDEO_SECRET_KEY,
+  clientIp: trustedClientIp,
+});
+```
+
+`trustedClientIp(request)` is the one hosting-specific piece. It must return the real visitor's IP from a source your server trusts, or `null` when unavailable. Use the same function for the proxy and signup. The package deliberately does not guess whether an incoming forwarded header is trustworthy.
+
+For local testing only:
+
+```ts
+// lib/trusted-client-ip.ts
+export function trustedClientIp(_request: Request): string | null {
+  if (process.env.NODE_ENV === 'development') return '127.0.0.1';
+  return null; // Configure your host's trusted IP source before deploying.
+}
+```
+
+For a Cloudflare-proxied app, `cf-connecting-ip` is an option only when your origin rejects requests that bypass that trusted proxy. Do not assume that a public Railway origin is protected just because the custom domain uses Cloudflare. Have your coding assistant inspect the actual deployment and configure this function. A missing IP returns a setup error; it does not silently group all production visitors under localhost.
+
+## 3. Add one route, or use your endpoint
+
+Your app forwards Heedeo's two paths itself. If the Domains page (https://app.heedeo.com/review/domains) already serves Heedeo from your domain, skip this step and pass its endpoint instead (step 4).
+
+```ts
+// app/hd/[...path]/route.ts
+import { heedeo } from '../../../lib/heedeo';
+
+export const runtime = 'nodejs';
+export const GET = heedeo.proxy;
+export const POST = heedeo.proxy;
+```
+
+This assumes `lib` is at the project root, as in the runnable example. Keep `/hd/i.js` and `/hd/v1/identify` reachable before sign-in. Existing authentication middleware must allow those two paths. Only these endpoints are forwarded; this route cannot forward event submissions or arbitrary URLs. Cookies and request headers unrelated to Heedeo are not sent upstream.
+
+## 4. Identify just before signup
+
+```ts
+// lib/heedeo-browser.ts: safe to import in a client component
+import { createHeedeo } from '@heedeo/sdk/browser';
+
+export const heedeo = createHeedeo({
+  publishableKey: process.env.NEXT_PUBLIC_HEEDEO_KEY,
+});
+```
+
+In your existing submit handler:
+
+```ts
+const { data } = await heedeo.identify();
+await signup({ email, heedeoToken: data?.token });
+```
+
+Keep your existing `signup` function and its validation, loading state and error handling. The package loads the script once, waits for it, and returns a new receipt for each call. No script tag or global type declaration is needed. Identification happens at the action, not on every page load. If identification fails, `data` is `null` and `error` explains the problem; continue signup without signals. Do not mix the package with an existing Heedeo script tag.
+
+With an endpoint from the Domains page, pass it as `endpoint` in place of `path` and add no route, for example `createHeedeo({ publishableKey, endpoint: 'https://www.customer.com/k9m2x' })`. `endpoint` needs 0.1.0-pilot.12 or later (`npm install @heedeo/sdk@latest`). It is an HTTPS origin with at most one path segment and no trailing slash; the script loads from `${endpoint}/i.js`. Passing both `path` and `endpoint` throws. Installed with the route before the domain was live? Change only this call; the server's `event` call stays the same, with its `clientIp`, and the route can go once the endpoint answers.
+
+## 5. Record the event on your server
+
+In the existing signup route, after validating the submitted fields:
+
+```ts
+const { data, error } = await heedeo.event({
+  request,
+  token: input.heedeoToken,
+  action: 'signup',
+  email: input.email,
+});
+
+if (data) console.info('Heedeo event', data.event_id);
+if (error) console.warn('Heedeo setup', error.code);
+// Continue your existing signup. Observe only during the pilot.
+```
+
+`request` is the original Web Request received by a Next.js route handler; it preserves the actual URL, method and headers. The call does not read or consume its body. Route handlers are the supported Next.js path for this first package release. Keep an existing server-action integration on the manual guide until an adapter has been tested; do not invent a request URL or replace authentication to use the package.
+
+What your backend knows about the person goes in `evidence`, every field optional: a verified email, the phone and its line type, the sign-in provider's claims, your account's age and plan, the card from Stripe, a check you ran. The phone number and card fingerprint are hashed on arrival and never stored raw. The integration guide has the one-liner for Stripe, Twilio Lookup, Google, Apple and GitHub.
+
+```ts
+await heedeo.event({
+  request, token, action: 'signup', email, userId,
+  evidence: {
+    phone: { number: '+14155550123', verified: true, line_type: 'mobile' },
+    account: { created_at: user.createdAt, plan: 'paid', paid_since: user.paidSince },
+  },
+});
+```
+
+`data.suggested` is `allow`, `verify`, `review`, or `block` once you set Block at score in Settings. Trust reasons in `data.reasons` carry a negative weight.
+
+The SDK generates a request ID once and reuses the same body on its one retry. If your application retries the entire action, provide its stable ID as `requestId`. A new user action needs a new identification and ID. Do not send two events with the same receipt to attach a user ID later.
+
+## 6. Report what you learn
+
+When you find out what a signup really was, say so. An outcome changes no flag and no label; it is the labelled set Heedeo uses to tune your weights later, and the more you report, the sooner your own numbers replace the defaults.
+
+```ts
+await heedeo.outcome({ eventId: data.event_id, outcome: 'abuse', label: 'trial_abuse' });
+// or { visitorId }, or { userId } once the account exists. outcome is 'abuse' or 'legit'.
+```
+
+A paid conversion is a cheap `legit`; a refund, a chargeback or a third free trial is `abuse`. `label` is your own short word, `note` one line for your reviewers; both are optional. One outcome per event, visitor or account: a later report replaces the earlier one. The same `{ data, error }` shape comes back, with `kind`, `event_id` or `visitor_id`, `outcome`, `label`, `source`, `note` and `created_at`. Reviewers can report the same thing on the flags page by resolving a flag as Abuse or Legit.
+
+## 7. Ask about a visitor
+
+Between events, read a browser's standing score, after trust, in your bands:
+
+```ts
+const { data } = await heedeo.visitor(visitorId);
+if (data?.suggested === 'review') holdPayout();
+```
+
+## Check that it works
+
+Run a test signup and check the server result: an `event_id` and a non-null `visitor` confirm a usable identification. `flag: false` is normal; an empty flags screen is not evidence of failure. Check that signup still completes with the script blocked or Heedeo unavailable. Never expose the full signals response or internal reasons to an end user.
+
+Use HTTPS for deployed testing, including Safari's secure-cookie behavior. Review the privacy wording in https://app.heedeo.com/docs#for-your-privacy-policy before going live.
+
+## Options and errors
+
+Server options: `secretKey`, required `clientIp(request)`, optional `path` (default `/hd`), `timeoutMs` (default 3000 total across event retries), `baseUrl` (default `https://app.heedeo.com`), and `fetch` for testing. Custom origins require HTTPS, except localhost. Browser options: `publishableKey`, matching `path` or an `endpoint` on your domain, and `timeoutMs` (default 3000 total for script loading and identification).
+
+Configuration mistakes throw when you construct the client, so missing keys are caught at setup. Operational failures return `{ data: null, error: { code, message, status? } }`; checking `error` narrows `data` to the success value. `code` is a `HeedeoErrorCode`, so a `switch` over it is checked by TypeScript:
+
+- Server: `missing_token`, `missing_client_ip`, `invalid_key`, `api_error`, `invalid_response`, `network_error`, `timeout_or_aborted`, `configuration_error`.
+- Browser: `browser_required`, `timeout`, `invalid_response`, `identification_unavailable`.
+
+Neither entry point logs credentials, request bodies or upstream error bodies.
+
+Browser timeouts stop waiting, but cannot cancel an already-running collector call in this pilot version. Always pass the returned token explicitly; never fall back to an older cookie token after a timeout. Browser results are not security decisions. Secret keys and event signals stay on your server.
+
+## Pilot boundaries
+
+This package is an ESM package (use `import`) for Node.js servers. The browser entry is separate and imports no server code. The server entry supports Node.js and Cloudflare Workers with `nodejs_compat`. Other edge runtimes have not been verified. No change to your hosting, database or sign-in provider is required. React hooks, server-action adapters, Express-specific wrappers and an automatic installer are not included in this release.
+
+## Cloudflare Workers
+
+Enable `nodejs_compat` in Wrangler. Create the client inside the request handler so keys come from Worker secrets:
+
+```ts
+import { Heedeo } from '@heedeo/sdk';
+
+export default {
+  async fetch(request, env) {
+    const heedeo = new Heedeo({
+      secretKey: env.HEEDEO_SECRET_KEY,
+      clientIp: request => request.headers.get('cf-connecting-ip'),
+    });
+    if (new URL(request.url).pathname.startsWith('/hd/')) {
+      return heedeo.proxy(request);
+    }
+    // In your signup handler, use heedeo.event() as above.
+    return env.ASSETS.fetch(request);
+  },
+};
+```
+
+This IP resolver is for a Worker receiving requests through Cloudflare, not an unprotected origin. If you use static assets, set `assets.run_worker_first` for `/hd/*` and your signup route. Store `HEEDEO_SECRET_KEY` with `wrangler secret put`; only the publishable key belongs in the browser.

package/dist/browser.d.ts

@@ -0,0 +1,13 @@
+import { type Identification, type Result } from "./shared.js";
+export type { HeedeoError, HeedeoErrorCode, Identification, Result } from "./shared.js";
+/** Create once per app. Calling this function alone makes no identification request. */
+export declare function createHeedeo(options: {
+    publishableKey: string | undefined;
+    /** Your own proxy route on this origin. Default: /hd. */
+    path?: string;
+    /** A host on your domain that serves Heedeo, instead of path. */
+    endpoint?: string;
+    timeoutMs?: number;
+}): {
+    identify(): Promise<Result<Identification>>;
+};

package/dist/browser.js

@@ -0,0 +1,85 @@
+import { failure, isIdentification, pathPrefix, timeout, } from "./shared.js";
+let loading;
+function load(url, timeoutMs) {
+    if (loading) {
+        return loading.url === url
+            ? loading.promise
+            : Promise.reject(new Error("conflicting_configuration"));
+    }
+    const promise = new Promise((resolve, reject) => {
+        if (window.heedeo) {
+            reject(new Error("existing_collector"));
+            return;
+        }
+        const script = document.createElement("script");
+        script.src = url;
+        script.async = true;
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        function finish(ok) {
+            clearTimeout(timer);
+            script.onload = null;
+            script.onerror = null;
+            if (ok && window.heedeo)
+                resolve();
+            else {
+                script.remove();
+                reject(new Error("script_unavailable"));
+            }
+        }
+        script.onload = () => finish(true);
+        script.onerror = () => finish(false);
+        document.head.append(script);
+    });
+    loading = { url, promise };
+    void promise.catch(() => {
+        if (loading?.promise === promise)
+            loading = undefined;
+    });
+    return promise;
+}
+/** Create once per app. Calling this function alone makes no identification request. */
+export function createHeedeo(options) {
+    if (!options.publishableKey?.startsWith("pk_"))
+        throw new Error("Use a Heedeo publishable key in the browser.");
+    if (options.path !== undefined && options.endpoint !== undefined)
+        throw new Error("Give Heedeo either path or endpoint, not both.");
+    const publishableKey = options.publishableKey;
+    // A host on your domain that serves Heedeo, such as https://www.customer.com/k9m2x: an HTTPS
+    // origin and at most one path segment, which the script and identify sit under.
+    const endpoint = options.endpoint ?? null;
+    if (endpoint !== null &&
+        (!/^https:\/\/[^/?#]+(\/[a-zA-Z0-9_-]+)?$/.test(endpoint) || !URL.canParse(endpoint)))
+        throw new Error("Heedeo endpoint must be an HTTPS origin with one optional path segment.");
+    const path = pathPrefix(options.path ?? "/hd");
+    const budget = timeout(options.timeoutMs ?? 3000);
+    return {
+        async identify() {
+            if (typeof window === "undefined")
+                return failure("browser_required", "Call identify in a browser action handler.");
+            let timer;
+            const deadline = new Promise((resolve) => {
+                timer = setTimeout(() => resolve(failure("timeout", "Identification timed out. Continue without signals.")), budget);
+            });
+            const identify = async () => {
+                try {
+                    const url = new URL(`${endpoint ?? window.location.origin + path}/i.js`);
+                    url.searchParams.set("key", publishableKey);
+                    await load(url.href, budget);
+                    const data = await window.heedeo?.identify();
+                    return isIdentification(data)
+                        ? { data, error: null }
+                        : failure("invalid_response", "Identification returned an unexpected response.");
+                }
+                catch {
+                    return failure("identification_unavailable", "Check the public key and proxy route. Continue signup without signals.");
+                }
+            };
+            try {
+                return await Promise.race([identify(), deadline]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}

package/dist/response.d.ts

@@ -0,0 +1,160 @@
+type Counts = {
+    "24h": number;
+    "7d": number;
+    all: number;
+};
+declare const LINKS: readonly ["shared_account", "shared_email", "shared_principal", "shared_phone", "shared_card", "probable", "ip"];
+declare const BANDS: readonly ["allow", "verify", "review", "block"];
+/** How two browsers are related. */
+export type Link = (typeof LINKS)[number];
+export type EventData = {
+    event_id: string;
+    flag: boolean;
+    score: number;
+    threshold: number;
+    /** The thresholds that applied under Settings: verify, review (the flag) and block (null without a block band; absent on answers stored before it), and the action whose own thresholds applied (null: the workspace's; absent before it). Absent on answers stored before bands. */
+    thresholds?: Thresholds & {
+        action?: string | null;
+    };
+    /** The band the score falls in, from those numbers alone: allow below verify, verify from there, review from the flag threshold, block from the block threshold. Heedeo enforces nothing. */
+    suggested?: Band;
+    /** When the customer's weights last changed (ISO 8601), null while the defaults are in use: the weight table that scored this answer. Absent on answers stored before it existed. */
+    version?: string | null;
+    /** Each reason with the weight your table gave it and base, its weight at the defaults (absent on answers stored before it existed). A trust reason (verified_phone, card_on_file, wallet_card, real_user, tenure, paid_history, verified_id, legit_outcome, email_tenure) lowers the score: its weight and base are negative. */
+    reasons: {
+        code: string;
+        text: string;
+        weight: number;
+        base?: number;
+    }[];
+    /** Browsers related to this one, one entry per edge, the strongest first: a shared account, email, principal, phone or card (weight 1), a probable match (its score), or an address shared in the last 7 days (`ip`: exact for IPv4, the /64 for IPv6; 0.5 a home line, 0.2 hosting). weight is how much the link proves; identities the other browser's own. Absent on answers stored before it existed. */
+    related?: {
+        visitor_id: string;
+        link: Link;
+        weight: number;
+        identities: number;
+    }[];
+    /** The account-side read, when the event sent a user_id: the browsers that presented this account in each window, this one included, and whether this browser is new to it; null without a user_id. Absent on answers stored before it existed. */
+    account?: {
+        visitors: Counts;
+        new_browser: boolean;
+    } | null;
+    visitor: {
+        id: string;
+        confidence: number;
+        first_seen: string;
+        last_seen: string;
+        emails: Counts;
+        accounts: Counts;
+    } | null;
+    counts: {
+        "24h": number;
+        "7d": number;
+    };
+    listed: "allow" | "block" | null;
+    activity: {
+        last_hour: number;
+        hourly_norm: number;
+        burst: boolean;
+    };
+    email: {
+        disposable: boolean;
+        alias_of_existing: boolean;
+        pattern: boolean;
+        /** The domain is a free mail provider's (Gmail, Outlook, Yahoo, iCloud, Proton and the like). Absent on answers stored before it existed. */
+        free_provider?: boolean;
+        /** The local part names a role (admin@, info@, billing@), not a person. Absent before it existed. */
+        role_address?: boolean;
+        /** The young_domain reason fired: the domain was registered under 30 days ago. Absent before it existed. */
+        young_domain?: boolean;
+        /** When the email's registrable domain was registered (ISO 8601), by RDAP; null when not asked (a free provider's) or the registry could not say. Absent before it existed. */
+        domain_registered?: string | null;
+        /** The registry was asked and could not say how old the domain is: no RDAP server for its TLD, no answer in time, or no registration date. Never a reason. Absent before it existed. */
+        domain_age_unknown?: boolean;
+        /** Have I Been Pwned's earliest breach holding the address (`first`, YYYY-MM-DD; null in none); null when breach history is off. Absent before it existed. */
+        breach?: {
+            first: string | null;
+        } | null;
+    } | null;
+    network: {
+        /** What a shared address proves: 0.5 a home or office line, 0.2 hosting, 0 a carrier, Private Relay or Tor. Absent on answers stored before it existed. */
+        link_weight?: number;
+        datacenter: boolean;
+        vpn: boolean | null;
+        proxy: boolean | null;
+        tor: boolean;
+        private_relay: boolean;
+        anonymous: boolean | null;
+        network_type: string | null;
+        asn: string | null;
+    };
+    agent: {
+        operator: string | null;
+        verified: boolean;
+        declared: string | null;
+        operator_network: string | null;
+        automation: string | null;
+    } | null;
+    /** What the identification's browser showed of itself (collector 1.2.0), null without an identification: `tampered` its own readings disagree (`tamper` names the checks that failed; null when the collector made none), `virtual_machine` a virtual or software GPU with two supporting tells (`vm` names the renderer and the tells), `private_mode` a private window (null when unknown). Absent on answers stored before it existed. */
+    environment?: Environment | null;
+};
+export type Environment = {
+    tampered: boolean | null;
+    tamper: string[];
+    virtual_machine: boolean;
+    vm: string[];
+    private_mode: boolean | null;
+};
+/** The four bands: allow, verify, review and block. */
+export type Band = (typeof BANDS)[number];
+type Thresholds = {
+    verify: number;
+    review: number;
+    block?: number | null;
+};
+/** What GET /v1/visitors/:id answers: the browser's standing score now, after trust, in your bands. */
+export type VisitorData = {
+    visitor: {
+        id: string;
+        first_seen: string;
+        last_seen: string;
+        emails: Counts;
+        accounts: Counts;
+    };
+    listed: "allow" | "block" | null;
+    score: number;
+    thresholds: Thresholds;
+    suggested: Band;
+    related: {
+        visitor_id: string;
+        link: Link;
+        weight: number;
+        identities: number;
+    }[];
+    /** The trust the visitor's evidence earns, each with a negative weight; only the strongest counts. Absent before trust existed. */
+    trust?: {
+        code: string;
+        text: string;
+        weight: number;
+    }[];
+    outcomes: {
+        kind: string;
+        outcome: string;
+        label: string | null;
+        created_at: string;
+    }[];
+};
+export type OutcomeData = {
+    kind: "event" | "visitor" | "account";
+    event_id?: string;
+    visitor_id: string | null;
+    outcome: "abuse" | "legit";
+    label: string | null;
+    source: string;
+    note: string | null;
+    created_at: string;
+};
+export declare function isVisitorData(value: unknown): value is VisitorData;
+export declare function isOutcomeData(value: unknown): value is OutcomeData;
+export declare function isEventData(value: unknown): value is EventData;
+export {};

package/dist/response.js

@@ -0,0 +1,150 @@
+const LINKS = [
+    "shared_account",
+    "shared_email",
+    "shared_principal",
+    "shared_phone",
+    "shared_card",
+    "probable",
+    "ip",
+];
+const BANDS = ["allow", "verify", "review", "block"];
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const number = (value) => typeof value === "number" && Number.isFinite(value);
+const string = (value) => typeof value === "string";
+const boolean = (value) => typeof value === "boolean";
+const nullable = (check) => (value) => value === null || check(value);
+// A field added after answers were first stored: absent, or as checked.
+const optional = (check) => (value) => value === undefined || check(value);
+const counts = (value) => object(value) && number(value["24h"]) && number(value["7d"]);
+const windows = (value) => counts(value) && number(value.all);
+const related = (value) => Array.isArray(value) &&
+    value.every((r) => object(r) &&
+        string(r.visitor_id) &&
+        LINKS.includes(r.link) &&
+        number(r.weight) &&
+        number(r.identities));
+const thresholds = (value) => object(value) &&
+    number(value.verify) &&
+    number(value.review) &&
+    (value.block === undefined || nullable(number)(value.block)) &&
+    (value.action === undefined || nullable(string)(value.action));
+const band = (value) => BANDS.includes(value);
+const strings = (value) => Array.isArray(value) && value.every(string);
+const environment = (value) => object(value) &&
+    nullable(boolean)(value.tampered) &&
+    strings(value.tamper) &&
+    boolean(value.virtual_machine) &&
+    strings(value.vm) &&
+    nullable(boolean)(value.private_mode);
+export function isVisitorData(value) {
+    if (!object(value) || !object(value.visitor))
+        return false;
+    const v = value.visitor;
+    return (string(v.id) &&
+        string(v.first_seen) &&
+        string(v.last_seen) &&
+        windows(v.emails) &&
+        windows(v.accounts) &&
+        (value.listed === null || value.listed === "allow" || value.listed === "block") &&
+        number(value.score) &&
+        thresholds(value.thresholds) &&
+        band(value.suggested) &&
+        related(value.related) &&
+        (value.trust === undefined ||
+            (Array.isArray(value.trust) &&
+                value.trust.every((t) => object(t) && string(t.code) && number(t.weight)))) &&
+        Array.isArray(value.outcomes) &&
+        value.outcomes.every((o) => object(o) && string(o.kind) && string(o.outcome)));
+}
+export function isOutcomeData(value) {
+    return (object(value) &&
+        ["event", "visitor", "account"].includes(value.kind) &&
+        (value.event_id === undefined || string(value.event_id)) &&
+        nullable(string)(value.visitor_id) &&
+        (value.outcome === "abuse" || value.outcome === "legit") &&
+        nullable(string)(value.label) &&
+        string(value.source) &&
+        nullable(string)(value.note) &&
+        string(value.created_at));
+}
+export function isEventData(value) {
+    if (!object(value) ||
+        !string(value.event_id) ||
+        !boolean(value.flag) ||
+        !number(value.score) ||
+        !number(value.threshold) ||
+        !counts(value.counts) ||
+        (value.listed !== null && value.listed !== "allow" && value.listed !== "block") ||
+        !Array.isArray(value.reasons) ||
+        !value.reasons.every((reason) => object(reason) &&
+            string(reason.code) &&
+            string(reason.text) &&
+            number(reason.weight) &&
+            (reason.base === undefined || number(reason.base))) ||
+        (value.thresholds !== undefined && !thresholds(value.thresholds)) ||
+        (value.suggested !== undefined && !band(value.suggested)) ||
+        (value.version !== undefined && !nullable(string)(value.version)) ||
+        (value.related !== undefined && !related(value.related)) ||
+        (value.account !== undefined &&
+            value.account !== null &&
+            (!object(value.account) ||
+                !counts(value.account.visitors) ||
+                !number(value.account.visitors.all) ||
+                !boolean(value.account.new_browser))))
+        return false;
+    if (value.visitor !== null) {
+        const visitor = value.visitor;
+        if (!object(visitor) ||
+            !string(visitor.id) ||
+            !number(visitor.confidence) ||
+            !string(visitor.first_seen) ||
+            !string(visitor.last_seen) ||
+            !object(visitor.emails) ||
+            !counts(visitor.emails) ||
+            !number(visitor.emails.all) ||
+            !object(visitor.accounts) ||
+            !counts(visitor.accounts) ||
+            !number(visitor.accounts.all))
+            return false;
+    }
+    const activity = value.activity;
+    const network = value.network;
+    if (!object(activity) ||
+        !number(activity.last_hour) ||
+        !number(activity.hourly_norm) ||
+        !boolean(activity.burst) ||
+        !object(network) ||
+        (network.link_weight !== undefined && !number(network.link_weight)) ||
+        !boolean(network.datacenter) ||
+        !boolean(network.tor) ||
+        !boolean(network.private_relay) ||
+        ![network.vpn, network.proxy, network.anonymous].every(nullable(boolean)) ||
+        ![network.network_type, network.asn].every(nullable(string)))
+        return false;
+    const email = value.email;
+    if (email !== null &&
+        (!object(email) ||
+            ![email.disposable, email.alias_of_existing, email.pattern].every(boolean) ||
+            ![
+                email.free_provider,
+                email.role_address,
+                email.young_domain,
+                email.domain_age_unknown,
+            ].every(optional(boolean)) ||
+            !optional(nullable(string))(email.domain_registered) ||
+            !optional(nullable((b) => object(b) && nullable(string)(b.first)))(email.breach)))
+        return false;
+    if (value.agent !== null &&
+        (!object(value.agent) ||
+            !boolean(value.agent.verified) ||
+            ![
+                value.agent.operator,
+                value.agent.declared,
+                value.agent.operator_network,
+                value.agent.automation,
+            ].every(nullable(string))))
+        return false;
+    if (value.environment !== undefined && !nullable(environment)(value.environment))
+        return false;
+    return true;
+}

package/dist/server.d.ts

@@ -0,0 +1,101 @@
+import { type EventData, type OutcomeData, type VisitorData } from "./response.js";
+export type { Band, EventData, Link, OutcomeData, VisitorData } from "./response.js";
+import { type Result } from "./shared.js";
+export type { HeedeoError, HeedeoErrorCode, Result } from "./shared.js";
+export type HeedeoOptions = {
+    secretKey: string | undefined;
+    /** Resolve only an IP supplied by your trusted hosting layer. Used for BOTH requests. */
+    clientIp: (request: Request) => string | null;
+    baseUrl?: string;
+    path?: string;
+    /** Total event budget, including the retry. Default: 3000 ms. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+};
+export type EventInput = {
+    request: Request;
+    token?: string | null;
+    action: string;
+    email?: string;
+    userId?: string;
+    /** For an agent acting for one of your users: that user's account id (the principal). Hashed on arrival. */
+    actingFor?: string;
+    /** Reuse across application-level retries of the same logical action. */
+    requestId?: string;
+    /** What your platform knows about the person, server to server. Every field is optional; the phone number and the card fingerprint are hashed on arrival and never stored raw. */
+    evidence?: Evidence;
+};
+/** ISO 8601, such as new Date(seconds * 1000).toISOString(). */
+type Timestamp = string;
+/** Ownership evidence: see the integration guide for the one-liner from each source. */
+export type Evidence = {
+    email?: {
+        verified?: boolean;
+        verified_at?: Timestamp;
+    };
+    /** number in E.164 (+14155550123), or your own hash of it as hash: one of the two. line_type from Twilio Lookup's line type intelligence. */
+    phone?: {
+        number?: string;
+        hash?: string;
+        verified?: boolean;
+        line_type?: "mobile" | "landline" | "fixed_voip" | "non_fixed_voip" | "toll_free" | "prepaid" | "unknown";
+        country?: string;
+    };
+    /** From the provider's ID token or user endpoint. real_user_status is Apple's (0, 1, 2). */
+    oauth?: {
+        provider?: "google" | "apple" | "github" | "microsoft" | "other";
+        email_verified?: boolean;
+        hosted_domain?: string;
+        real_user_status?: 0 | 1 | 2;
+        private_relay?: boolean;
+        account_created_at?: Timestamp;
+        two_factor?: boolean;
+    };
+    /** Your own account record. */
+    account?: {
+        created_at?: Timestamp;
+        plan?: "free" | "trial" | "paid";
+        paid_since?: Timestamp;
+    };
+    /** From Stripe's PaymentMethod (card.funding, card.fingerprint, card.checks.cvc_check, card.wallet, card.country) and its charge. */
+    payment?: {
+        funding?: "credit" | "debit" | "prepaid";
+        card_fingerprint?: string;
+        cvc_check?: "pass" | "fail";
+        wallet?: "apple_pay" | "google_pay" | "link" | "none";
+        three_ds?: "authenticated" | "failed" | "not_attempted";
+        country?: string;
+        radar_risk_level?: Risk;
+        free_trial_abuse_risk?: Risk;
+    };
+    /** A check you ran on the person. */
+    verification?: {
+        kind?: "otp" | "email_link" | "3ds" | "id_document" | "liveness" | "captcha";
+        result?: "passed" | "failed";
+        at?: Timestamp;
+    };
+};
+type Risk = "normal" | "elevated" | "highest" | "not_assessed" | "unknown";
+/** What you learned about one event, visitor or account: exactly one id, abuse or legit. */
+export type OutcomeInput = {
+    eventId?: string;
+    visitorId?: string;
+    userId?: string;
+    outcome: "abuse" | "legit";
+    /** Your own short word for it: trial_abuse, chargeback, paid. */
+    label?: string;
+    /** One line for your reviewers. */
+    note?: string;
+};
+export declare class Heedeo {
+    #private;
+    constructor(options: HeedeoOptions);
+    /** Signals only. Errors are values; this method never decides whether signup is allowed. */
+    event: (input: EventInput) => Promise<Result<EventData>>;
+    /** Report what you learned about an event, visitor or account. Ground truth for tuning weights, never policy. */
+    outcome: (input: OutcomeInput) => Promise<Result<OutcomeData>>;
+    /** A browser's standing score now, after trust, in your bands: GET /v1/visitors/:id. Errors are values; an unknown visitor is a 404 api_error. */
+    visitor: (visitorId: string) => Promise<Result<VisitorData>>;
+    /** Mount at /hd/[...path]. Only the public script and identification endpoint are forwarded. */
+    proxy: (request: Request) => Promise<Response>;
+}

package/dist/server.js

@@ -0,0 +1,265 @@
+// Node's built-in import also prevents accidentally bundling this entry into browser code.
+import { isIP } from "node:net";
+import { isEventData, isOutcomeData, isVisitorData, } from "./response.js";
+import { failure, pathPrefix, timeout } from "./shared.js";
+function origin(value) {
+    const url = new URL(value);
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/") {
+        throw new Error("Heedeo baseUrl must be an HTTPS origin (HTTP is allowed only on localhost).");
+    }
+    return url.origin;
+}
+// Send just the request context used for signals and signed-agent verification, never app secrets.
+const EVENT_HEADERS = [
+    "user-agent",
+    "accept-language",
+    "signature",
+    "signature-input",
+    "signature-agent",
+    "content-digest",
+    "sec-ch-ua",
+    "sec-ch-ua-platform",
+    "sec-ch-ua-mobile",
+    // The end user's country as your edge saw it, which card_mismatch reads without an IPinfo answer.
+    "cf-ipcountry",
+    "x-vercel-ip-country",
+];
+// What the identify proxy forwards: the browser's own description of itself, its languages and its
+// client hints, low and high entropy, which the matcher reads beside the bundle; and origin, since a
+// workspace with allowed origins checks the page's. Never a cookie but Heedeo's own (below), never
+// an app secret.
+const IDENTIFY_HEADERS = [
+    "user-agent",
+    "accept-language",
+    "content-type",
+    "origin",
+    "sec-ch-ua",
+    "sec-ch-ua-platform",
+    "sec-ch-ua-mobile",
+    "sec-ch-ua-platform-version",
+    "sec-ch-ua-model",
+    "sec-ch-ua-arch",
+    "sec-ch-ua-bitness",
+    "sec-ch-ua-full-version-list",
+];
+class PayloadTooLarge extends Error {
+}
+async function limitedBody(request, signal) {
+    const reader = request.body?.getReader();
+    if (!reader)
+        return new Uint8Array();
+    const chunks = [];
+    let size = 0;
+    const abort = () => {
+        void reader.cancel().catch(() => { });
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const { done, value } = await reader.read();
+            signal.throwIfAborted();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 65536)
+                throw new PayloadTooLarge();
+            chunks.push(value);
+        }
+        const body = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return body;
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+export class Heedeo {
+    #key;
+    #origin;
+    #path;
+    #timeout;
+    #fetch;
+    #clientIp;
+    constructor(options) {
+        if (!options.secretKey?.startsWith("sk_")) {
+            throw new Error("Set HEEDEO_SECRET_KEY on your server. Never use a publishable key here.");
+        }
+        this.#key = options.secretKey;
+        this.#origin = origin(options.baseUrl ?? "https://app.heedeo.com");
+        this.#path = pathPrefix(options.path ?? "/hd");
+        this.#timeout = timeout(options.timeoutMs ?? 3000);
+        // Workers requires the global receiver; do not call native fetch as a class method.
+        const send = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#fetch = (input, init) => send(input, init);
+        this.#clientIp = options.clientIp;
+    }
+    #ip(request) {
+        const value = this.#clientIp(request);
+        const normalized = value?.replace(/^::ffff:/, "").trim();
+        return normalized && isIP(normalized) ? normalized : null;
+    }
+    /** Signals only. Errors are values; this method never decides whether signup is allowed. */
+    event = async (input) => {
+        if (!input.token)
+            return failure("missing_token", "Identification was unavailable. Continue without signals.");
+        try {
+            const ip = this.#ip(input.request);
+            if (!ip)
+                return failure("missing_client_ip", "Configure clientIp for your trusted hosting layer.");
+            const url = new URL(input.request.url);
+            const headers = {
+                host: url.host,
+                ":method": input.request.method,
+                ":path": url.pathname + url.search,
+            };
+            for (const name of EVENT_HEADERS) {
+                const value = input.request.headers.get(name);
+                if (value !== null)
+                    headers[name] = value;
+            }
+            const body = JSON.stringify({
+                token: input.token,
+                action: input.action,
+                email: input.email,
+                user_id: input.userId,
+                acting_for: input.actingFor,
+                evidence: input.evidence,
+                client_ip: ip,
+                headers,
+                request_id: input.requestId ?? crypto.randomUUID(),
+            });
+            const signal = AbortSignal.any([AbortSignal.timeout(this.#timeout), input.request.signal]);
+            return await this.#send("/v1/events", body, signal, isEventData, "event");
+        }
+        catch {
+            return failure("configuration_error", "Check the Heedeo request and clientIp configuration.");
+        }
+    };
+    /** Report what you learned about an event, visitor or account. Ground truth for tuning weights, never policy. */
+    outcome = async (input) => {
+        const body = JSON.stringify({
+            event_id: input.eventId,
+            visitor_id: input.visitorId,
+            user_id: input.userId,
+            outcome: input.outcome,
+            label: input.label,
+            note: input.note,
+        });
+        return this.#send("/v1/outcomes", body, AbortSignal.timeout(this.#timeout), isOutcomeData, "outcome");
+    };
+    /** A browser's standing score now, after trust, in your bands: GET /v1/visitors/:id. Errors are values; an unknown visitor is a 404 api_error. */
+    visitor = async (visitorId) => this.#send(`/v1/visitors/${encodeURIComponent(visitorId)}`, null, AbortSignal.timeout(this.#timeout), isVisitorData, "visitor lookup");
+    // One POST (a GET without a body) with one retry on a 5xx or a network error. Errors are
+    // values, never thrown.
+    async #send(path, body, signal, valid, what) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                const response = await this.#fetch(`${this.#origin}${path}`, {
+                    method: body === null ? "GET" : "POST",
+                    redirect: "manual",
+                    signal,
+                    headers: {
+                        authorization: `Bearer ${this.#key}`,
+                        ...(body === null ? {} : { "content-type": "application/json" }),
+                    },
+                    ...(body === null ? {} : { body }),
+                });
+                if (response.status >= 500 && attempt === 0 && !signal.aborted) {
+                    await response.body?.cancel();
+                    continue;
+                }
+                if (!response.ok) {
+                    // Do not reflect response bodies: upstream errors can contain sensitive input.
+                    const code = response.status === 401 || response.status === 403 ? "invalid_key" : "api_error";
+                    return failure(code, `Heedeo could not record this ${what}. Check the server configuration.`, response.status);
+                }
+                const data = await response.json();
+                if (!valid(data)) {
+                    return failure("invalid_response", "Heedeo returned an unexpected response.");
+                }
+                return { data, error: null };
+            }
+            catch {
+                if (signal.aborted)
+                    return failure("timeout_or_aborted", "Heedeo did not finish within the request budget.");
+                if (attempt === 1)
+                    return failure("network_error", "Heedeo is unavailable. Continue without signals.");
+            }
+        }
+        return failure("network_error", "Heedeo is unavailable. Continue without signals.");
+    }
+    /** Mount at /hd/[...path]. Only the public script and identification endpoint are forwarded. */
+    proxy = async (request) => {
+        const url = new URL(request.url);
+        const script = url.pathname === `${this.#path}/i.js` && request.method === "GET";
+        const identify = url.pathname === `${this.#path}/v1/identify` && request.method === "POST";
+        if (!script && !identify)
+            return new Response("Not found", { status: 404 });
+        try {
+            const ip = this.#ip(request);
+            if (!ip)
+                return new Response("Heedeo clientIp is not configured", { status: 503 });
+            const target = new URL(script ? "/i.js" : "/v1/identify", this.#origin);
+            const key = url.searchParams.get("key");
+            if (!key?.startsWith("pk_"))
+                return new Response("A publishable key is required", { status: 400 });
+            target.searchParams.set("key", key);
+            const headers = new Headers({ "x-heedeo-client-ip": ip });
+            for (const name of IDENTIFY_HEADERS) {
+                const value = request.headers.get(name);
+                if (value)
+                    headers.set(name, value);
+            }
+            const cookie = request.headers
+                .get("cookie")
+                ?.split(";")
+                .map((v) => v.trim())
+                .find((v) => v.startsWith("_idd="));
+            if (cookie)
+                headers.set("cookie", cookie);
+            const signal = AbortSignal.any([AbortSignal.timeout(this.#timeout), request.signal]);
+            const body = identify ? await limitedBody(request, signal) : undefined;
+            const response = await this.#fetch(target, {
+                method: request.method,
+                headers,
+                body,
+                signal,
+                redirect: "manual",
+            });
+            if (response.status >= 300 && response.status < 400) {
+                await response.body?.cancel();
+                throw new Error("Unexpected upstream redirect");
+            }
+            const outgoing = new Headers({ "cache-control": "no-store" });
+            for (const name of ["content-type", "accept-ch"]) {
+                const value = response.headers.get(name);
+                if (value)
+                    outgoing.set(name, value);
+            }
+            for (const value of response.headers.getSetCookie())
+                outgoing.append("set-cookie", value);
+            return new Response(response.body, { status: response.status, headers: outgoing });
+        }
+        catch (error) {
+            if (error instanceof PayloadTooLarge)
+                return new Response("Payload too large", { status: 413 });
+            return new Response("Heedeo is unavailable", {
+                status: 502,
+                headers: { "cache-control": "no-store" },
+            });
+        }
+    };
+}

package/dist/shared.d.ts

@@ -0,0 +1,22 @@
+export type HeedeoErrorCode = "missing_token" | "missing_client_ip" | "invalid_key" | "api_error" | "invalid_response" | "network_error" | "timeout_or_aborted" | "configuration_error" | "browser_required" | "timeout" | "identification_unavailable";
+export type HeedeoError = {
+    code: HeedeoErrorCode;
+    message: string;
+    status?: number;
+};
+export type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: HeedeoError;
+};
+export declare function failure(code: HeedeoErrorCode, message: string, status?: number): Result<never>;
+export declare function timeout(value: number): number;
+export declare function pathPrefix(value: string): string;
+export type Identification = {
+    token: string;
+    visitor_id: string;
+    confidence: number;
+};
+export declare function isIdentification(value: unknown): value is Identification;

package/dist/shared.js

@@ -0,0 +1,24 @@
+export function failure(code, message, status) {
+    return { data: null, error: { code, message, ...(status === undefined ? {} : { status }) } };
+}
+export function timeout(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 30_000) {
+        throw new Error("Heedeo timeoutMs must be an integer between 1 and 30000.");
+    }
+    return value;
+}
+export function pathPrefix(value) {
+    if (!/^\/[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*$/.test(value)) {
+        throw new Error("Heedeo path must be a local prefix such as /hd.");
+    }
+    return value;
+}
+export function isIdentification(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const id = value;
+    return (typeof id.token === "string" &&
+        id.token.length > 0 &&
+        typeof id.visitor_id === "string" &&
+        typeof id.confidence === "number");
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@heedeo/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-pilot.12",
+  "description": "Browser identification and server-side signup signals for Heedeo",
+  "type": "module",
+  "engines": {
+    "node": ">=20.18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "lint": "biome check ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "homepage": "https://app.heedeo.com/docs/sdk",
+  "license": "MIT"
+}