@noirtrack/sdk 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared types for every NoirTrack SDK entry. Kept platform-neutral so the web, React Native,
+ * and server clients all speak the same shapes.
+ */
+/** Event/identify metadata. Flat record of primitives, like the ingest API accepts. */
+export type Props = Record<string, string | number | boolean>;
+/** A firewall verdict from the decision engine. */
+export interface Verdict {
+    action: 'allow' | 'block' | 'challenge';
+    reason: string | null;
+    blocked_page: string | null;
+    ttl: number;
+}
+/** Input to a hard firewall decision (server, secret key). */
+export interface DecideInput {
+    ip?: string;
+    ua?: string;
+    path?: string;
+    /** The page's host (for the analytics pageview), when recording. */
+    host?: string;
+    /** Referrer header, when recording. */
+    referrer?: string | null;
+    /** Visitor id from the `noir_vid` cookie, when recording. */
+    visitorId?: string;
+    /**
+     * Also record this hit as an analytics pageview (stamped with the verdict), so a hard-block
+     * install needs no separate snippet. Bypasses the verdict cache (one call per hit). Default off
+     * on `decide()`; the framework guards turn it on unless `analytics: false`.
+     */
+    record?: boolean;
+}
+/** A server-side goal (secret key). */
+export interface GoalInput {
+    /** Goal name: lowercase `a-z 0-9 _ - :`, up to 64 chars (the server lowercases it). */
+    name: string;
+    /** The visitor's id, read from your `noir_vid` cookie on the server. Anonymous if omitted. */
+    visitorId?: string;
+    /** Path the goal happened on. Defaults to `/` server-side. */
+    path?: string;
+    /** Optional context, up to 10 keys. */
+    metadata?: Props;
+}
+/**
+ * Revenue. Two safe shapes, auto-routed by the client:
+ *  - `{ checkoutId, provider }` captures by checkout id; the server reads the amount from the
+ *    provider, so it works with the public key and can't be forged from the browser.
+ *  - `{ amount, currency? }` records an explicit amount; the server can't verify it, so it
+ *    requires the secret key (server only). `refund: true` subtracts from revenue.
+ */
+export type RevenueInput = {
+    checkoutId: string;
+    provider?: 'stripe' | 'polar' | 'lemonsqueezy';
+    visitorId?: string;
+} | {
+    /** Required for `paid`/`refunded`; omit for `cancelled`/`subscription_ended` (no money moves). */
+    amount?: number;
+    currency?: string;
+    visitorId?: string;
+    event?: string;
+    /** Lifecycle status. Default `paid`. */
+    status?: 'paid' | 'refunded' | 'cancelled' | 'subscription_ended';
+    /** @deprecated Legacy alias for `status: 'refunded'`. */
+    refund?: boolean;
+};
+/** Attach customer info to a visitor: your user id, name, email, and any custom attributes. */
+export interface IdentifyInput {
+    visitorId?: string;
+    /** Your app's user id — stored as a `userId` attribute, the same field the snippet/browser send. */
+    userId?: string;
+    name?: string;
+    email?: string;
+    /** Any extra custom fields to attach to the visitor's profile. */
+    attributes?: Props;
+}
+/** A form-shield check. */
+export interface ShieldInput {
+    /** Submitted email (for the disposable-domain check). */
+    email?: string;
+    /** Value of the hidden `_noir_hp` honeypot field; any value means bot. */
+    honeypot?: string;
+    /** The submitter's IP. Pass it so checks run on the visitor, not your server. */
+    ip?: string;
+    /** The submitter's user-agent. */
+    ua?: string;
+    /** The form's path, for the report. */
+    path?: string;
+}
+export interface ShieldResult {
+    ok: boolean;
+    reason: string | null;
+}
+/** Block-handling shared by the firewall adapters. */
+export interface BlockOptions {
+    /** What to do on a block verdict. Default 'block' (return an HTTP error). */
+    onBlock?: 'redirect' | 'rewrite' | 'block';
+    /** Page to redirect/rewrite to (falls back to the verdict's blocked_page). */
+    blockedPage?: string;
+    /** HTTP status for the 'block' action. Default 403. */
+    blockStatus?: number;
+    /**
+     * Record each request as an analytics pageview (stamped with the verdict) in the same call —
+     * so a hard-block install populates the dashboard with no separate snippet. Default true. Set
+     * false for a pure firewall (cached decisions, no analytics) when you track analytics elsewhere.
+     */
+    analytics?: boolean;
+}
+/** Tuning shared by every client. */
+export interface ClientTuning {
+    /** NoirTrack base URL. Self-hosted only; defaults to the hosted service. */
+    endpoint?: string;
+    /** Abort a network call after this many ms, then fail open. Default 800. */
+    timeoutMs?: number;
+}

package/dist/core/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for every NoirTrack SDK entry. Kept platform-neutral so the web, React Native,
+ * and server clients all speak the same shapes.
+ */
+export {};

package/dist/express.d.ts

@@ -0,0 +1,15 @@
+/** @noirtrack/sdk/express — firewall middleware for Express / Connect-style apps. */
+import type { RequestHandler } from 'express';
+import type { BlockOptions } from './core/types.js';
+import { type GuardTarget } from './index.js';
+/**
+ *   import { createClient } from '@noirtrack/sdk';
+ *   import { guard } from '@noirtrack/sdk/express';
+ *
+ *   const noir = createClient({ publicKey: '...', secretKey: process.env.NOIRTRACK_SECRET! });
+ *   app.use(guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' }));
+ *
+ * Or pass options: `guard({ publicKey, secretKey, onBlock: 'block' })`.
+ * Fails open: a NoirTrack error/timeout calls next() and never breaks your app.
+ */
+export declare function guard(target: GuardTarget, blockOptions?: BlockOptions): RequestHandler;

package/dist/express.js

@@ -0,0 +1,52 @@
+import { clientIp } from './core/client-ip.js';
+import { isBlockedPagePath } from './core/endpoint.js';
+import { resolveGuard } from './index.js';
+/**
+ *   import { createClient } from '@noirtrack/sdk';
+ *   import { guard } from '@noirtrack/sdk/express';
+ *
+ *   const noir = createClient({ publicKey: '...', secretKey: process.env.NOIRTRACK_SECRET! });
+ *   app.use(guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' }));
+ *
+ * Or pass options: `guard({ publicKey, secretKey, onBlock: 'block' })`.
+ * Fails open: a NoirTrack error/timeout calls next() and never breaks your app.
+ */
+export function guard(target, blockOptions) {
+    const { client, block } = resolveGuard(target, blockOptions);
+    return async function (request, response, next) {
+        const ip = clientIp((name) => {
+            const value = request.headers[name];
+            return Array.isArray(value) ? value[0] : value;
+        }, request.socket.remoteAddress);
+        const ua = request.headers['user-agent'] ?? '';
+        const path = request.path;
+        // Record the hit as an analytics pageview in the same call (default), so the firewall
+        // doubles as analytics with no separate snippet. Set `analytics: false` for a pure filter.
+        const record = block.analytics !== false;
+        const cookie = (name) => request.headers.cookie?.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`))?.[1];
+        const verdict = await client.decide({
+            ip,
+            ua,
+            path: record ? (request.originalUrl ?? path) : path,
+            host: record ? request.headers.host : undefined,
+            referrer: record ? (request.headers.referer ?? null) : undefined,
+            visitorId: record ? cookie('noir_vid') : undefined,
+            record,
+        });
+        if (verdict?.action !== 'block') {
+            next();
+            return;
+        }
+        const page = verdict.blocked_page ?? block.blockedPage;
+        if ((block.onBlock ?? 'block') === 'redirect' && page) {
+            // Don't redirect the blocked page to itself — that loops forever.
+            if (isBlockedPagePath(path, page)) {
+                next();
+                return;
+            }
+            response.redirect(page);
+            return;
+        }
+        response.status(block.blockStatus ?? 403).send('Forbidden');
+    };
+}

package/dist/fetch.d.ts

@@ -0,0 +1,16 @@
+import type { BlockOptions } from './core/types.js';
+import { type GuardTarget } from './index.js';
+/**
+ * Returns a guard that, given a standard Request, resolves to a blocking Response, or null when
+ * the request should continue.
+ *
+ *   import { createClient } from '@noirtrack/sdk';
+ *   import { createGuard } from '@noirtrack/sdk/fetch';
+ *
+ *   const noir = createClient({ publicKey: '...', secretKey: env.NOIRTRACK_SECRET });
+ *   const guard = createGuard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
+ *   export default { async fetch(req) { return (await guard(req)) ?? fetch(req); } };
+ *
+ * Fails open: a NoirTrack error/timeout returns null (let the request through).
+ */
+export declare function createGuard(target: GuardTarget, blockOptions?: BlockOptions): (request: Request) => Promise<Response | null>;

package/dist/fetch.js

@@ -0,0 +1,48 @@
+/** @noirtrack/sdk/fetch — guard for standard Request/Response runtimes (Hono, Cloudflare Workers, Deno). */
+import { clientIp } from './core/client-ip.js';
+import { isBlockedPagePath } from './core/endpoint.js';
+import { resolveGuard } from './index.js';
+/**
+ * Returns a guard that, given a standard Request, resolves to a blocking Response, or null when
+ * the request should continue.
+ *
+ *   import { createClient } from '@noirtrack/sdk';
+ *   import { createGuard } from '@noirtrack/sdk/fetch';
+ *
+ *   const noir = createClient({ publicKey: '...', secretKey: env.NOIRTRACK_SECRET });
+ *   const guard = createGuard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
+ *   export default { async fetch(req) { return (await guard(req)) ?? fetch(req); } };
+ *
+ * Fails open: a NoirTrack error/timeout returns null (let the request through).
+ */
+export function createGuard(target, blockOptions) {
+    const { client, block } = resolveGuard(target, blockOptions);
+    return async function guard(request) {
+        const url = new URL(request.url);
+        const ip = clientIp((name) => request.headers.get(name));
+        const ua = request.headers.get('user-agent') ?? '';
+        const path = url.pathname;
+        // Record the hit as an analytics pageview in the same call (default), so the firewall
+        // doubles as analytics with no separate snippet. Set `analytics: false` for a pure filter.
+        const record = block.analytics !== false;
+        const verdict = await client.decide({
+            ip,
+            ua,
+            path: record ? path + url.search : path,
+            host: record ? (request.headers.get('host') ?? url.host) : undefined,
+            referrer: record ? request.headers.get('referer') : undefined,
+            visitorId: record ? request.headers.get('cookie')?.match(/(?:^|;\s*)noir_vid=([^;]+)/)?.[1] : undefined,
+            record,
+        });
+        if (verdict?.action !== 'block')
+            return null;
+        const page = verdict.blocked_page ?? block.blockedPage;
+        if ((block.onBlock ?? 'block') === 'redirect' && page) {
+            // Already on the blocked page → let it through, don't loop.
+            if (isBlockedPagePath(path, page))
+                return null;
+            return Response.redirect(new URL(page, request.url), 302);
+        }
+        return new Response('Forbidden', { status: block.blockStatus ?? 403 });
+    };
+}

package/dist/form-shield.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @noirtrack/sdk/form-shield — spam/bot check for form submissions.
+ *
+ * Authenticated by your SECRET key (sk_live_…), like the rest of the SDK. Call it from your
+ * form's POST handler and reject when `ok` is false. Email/phone are checked in-request on
+ * NoirTrack's side and never stored.
+ *
+ *   import { createFormShield } from '@noirtrack/sdk/form-shield';
+ *   const formShield = createFormShield({ apiKey: process.env.NOIRTRACK_API_KEY! });
+ *   const { ok, reason } = await formShield.check({ email, honeypot, ip, ua });
+ *   if (!ok) return res.status(422).json({ error: 'blocked', reason });
+ */
+export interface FormShieldOptions {
+    /** Secret API key (sk_live_…). Keep it server-side. */
+    apiKey: string;
+    /** NoirTrack base URL. Defaults to the NOIRTRACK_ENDPOINT env var, then DEFAULT_ENDPOINT. */
+    endpoint?: string;
+    /** Abort the check after this many ms, then fail open. Default 1500. */
+    timeoutMs?: number;
+}
+export interface FormShieldInput {
+    /** Submitted email (for the disposable-domain check). */
+    email?: string;
+    /** Value of the hidden honeypot field (`_noir_hp`); any value = bot. */
+    honeypot?: string;
+    /** The submitter's IP — pass it server-side so checks run on the visitor, not your server. */
+    ip?: string;
+    /** The submitter's user-agent. */
+    ua?: string;
+    /** The form's path, for the report. */
+    path?: string;
+}
+export interface FormShieldResult {
+    ok: boolean;
+    reason: string | null;
+}
+export declare function createFormShield(options: FormShieldOptions): {
+    check: (input: FormShieldInput) => Promise<FormShieldResult>;
+};

package/dist/form-shield.js

@@ -0,0 +1,41 @@
+/**
+ * @noirtrack/sdk/form-shield — spam/bot check for form submissions.
+ *
+ * Authenticated by your SECRET key (sk_live_…), like the rest of the SDK. Call it from your
+ * form's POST handler and reject when `ok` is false. Email/phone are checked in-request on
+ * NoirTrack's side and never stored.
+ *
+ *   import { createFormShield } from '@noirtrack/sdk/form-shield';
+ *   const formShield = createFormShield({ apiKey: process.env.NOIRTRACK_API_KEY! });
+ *   const { ok, reason } = await formShield.check({ email, honeypot, ip, ua });
+ *   if (!ok) return res.status(422).json({ error: 'blocked', reason });
+ */
+import { resolveEndpoint } from './index.js';
+export function createFormShield(options) {
+    const endpoint = resolveEndpoint(options.endpoint);
+    const timeoutMs = options.timeoutMs ?? 1500;
+    /** Returns { ok }; fails open (ok:true) on timeout/error so a NoirTrack outage never blocks real users. */
+    async function check(input) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(`${endpoint}/api/v1/form-shield`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${options.apiKey}` },
+                body: JSON.stringify(input),
+                signal: controller.signal,
+            });
+            if (!res.ok)
+                return { ok: true, reason: null }; // fail open
+            const data = (await res.json());
+            return { ok: data.ok !== false, reason: data.reason ?? null };
+        }
+        catch {
+            return { ok: true, reason: null };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return { check };
+}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import type { BlockOptions, DecideInput, GoalInput, IdentifyInput, Props, RevenueInput, ShieldInput, ShieldResult, Verdict } from './core/types.js';
+export { DEFAULT_ENDPOINT, isBlockedPagePath, resolveEndpoint } from './core/endpoint.js';
+export type { BlockOptions, ClientTuning, DecideInput, GoalInput, IdentifyInput, Props, RevenueInput, ShieldInput, ShieldResult, Verdict, } from './core/types.js';
+export interface ServerClientOptions {
+    /**
+     * Public key (`pk_live_...`). Only needed for analytics ingest from this client — `view`,
+     * `event`, and `revenue` by checkout id. The firewall guard and every secret-key method
+     * (`decide`, `goal`, amount-based `revenue`, `identify`, `shield`) don't use it, so a guard-only
+     * setup can leave it out.
+     */
+    publicKey?: string;
+    /** Secret key (`sk_live_...`). Used for firewall, goals, revenue, and identify. Server-side only. */
+    secretKey: string;
+    /** NoirTrack base URL. Self-hosted only; defaults to the hosted service. */
+    endpoint?: string;
+    /** Abort a network call after this many ms, then fail open. Default 800. */
+    timeoutMs?: number;
+    /** Cap how long a per-IP verdict is cached, ms. Default 60000. */
+    cacheTtlMs?: number;
+}
+export interface ServerClient {
+    /** Record a pageview (rarely used server-side). */
+    view(path?: string, opts?: {
+        visitorId?: string;
+    }): Promise<boolean>;
+    /** Record a custom event. */
+    event(name: string, props?: Props, opts?: {
+        visitorId?: string;
+        path?: string;
+    }): Promise<boolean>;
+    /** Record revenue. `{ amount }` uses the secret key; `{ checkoutId }` captures via the provider. */
+    revenue(input: RevenueInput): Promise<boolean>;
+    /** Attach a name + attributes to a visitor. */
+    identify(input: IdentifyInput & {
+        visitorId: string;
+    }): Promise<boolean>;
+    /** A hard firewall decision. Returns the verdict, or null on timeout/error (fail open). */
+    decide(input: DecideInput): Promise<Verdict | null>;
+    /** Fire a server-side goal. */
+    goal(name: string, options?: Omit<GoalInput, 'name'>): Promise<boolean>;
+    /** Check a form submission for spam and bots. */
+    shield(input: ShieldInput): Promise<ShieldResult>;
+}
+export declare function createClient(options: ServerClientOptions): ServerClient;
+/** What a firewall adapter accepts: an existing client, or options to build one. */
+export type GuardTarget = ServerClient | (ServerClientOptions & BlockOptions);
+/**
+ * Resolve a guard's `(target, block?)` arguments into a client plus its block options, so every
+ * adapter supports both `guard(noir, { onBlock })` and `guard({ publicKey, secretKey, onBlock })`.
+ */
+export declare function resolveGuard(target: GuardTarget, block?: BlockOptions): {
+    client: ServerClient;
+    block: BlockOptions;
+};

package/dist/index.js

@@ -0,0 +1,56 @@
+/**
+ * @noirtrack/sdk — server entry (Node, edge, Deno, Bun).
+ *
+ * `createClient({ secretKey, publicKey? })` returns one client for everything your backend does.
+ * The secret key powers trusted operations (firewall, server goals, amount-based revenue, identify)
+ * and is all the firewall guard needs. The public key is optional — add it only to also send
+ * analytics ingest (view/event/checkout-id revenue) from this client. The client routes each call
+ * to the right key. Browser and React Native have their own entries (`@noirtrack/sdk/web`,
+ * `@noirtrack/sdk/react-native`) that take the public key only.
+ */
+import { resolveEndpoint } from './core/endpoint.js';
+import { postOk } from './core/http.js';
+import { createSecretApi } from './core/secret.js';
+export { DEFAULT_ENDPOINT, isBlockedPagePath, resolveEndpoint } from './core/endpoint.js';
+export function createClient(options) {
+    const endpoint = resolveEndpoint(options.endpoint);
+    const timeoutMs = options.timeoutMs ?? 800;
+    const secret = createSecretApi({ secretKey: options.secretKey, endpoint, timeoutMs, cacheTtlMs: options.cacheTtlMs });
+    function eventBody(name, meta, opts) {
+        return { site_key: options.publicKey, path: opts?.path ?? '/', event: name, meta, visitor_id: opts?.visitorId };
+    }
+    function view(path, opts) {
+        return postOk(`${endpoint}/api/v1/event`, eventBody('pageview', undefined, { visitorId: opts?.visitorId, path }), {}, timeoutMs);
+    }
+    function event(name, props, opts) {
+        return postOk(`${endpoint}/api/v1/event`, eventBody(name, props, opts), {}, timeoutMs);
+    }
+    function revenue(input) {
+        // Only a bare `{ checkoutId }` uses the public capture path (the server reads the amount from
+        // the provider). Everything else — amount, status, or refund, including an amount-less
+        // cancellation — goes through the secret-key payment endpoint.
+        if (!('checkoutId' in input))
+            return secret.payment(input);
+        const provider = input.provider ?? 'stripe';
+        return postOk(`${endpoint}/api/v1/payment/capture`, { site_key: options.publicKey, provider, external_id: input.checkoutId, visitor_id: input.visitorId }, {}, timeoutMs);
+    }
+    return {
+        view,
+        event,
+        revenue,
+        identify: secret.identify,
+        decide: secret.decide,
+        goal: secret.goal,
+        shield: secret.shield,
+    };
+}
+/**
+ * Resolve a guard's `(target, block?)` arguments into a client plus its block options, so every
+ * adapter supports both `guard(noir, { onBlock })` and `guard({ publicKey, secretKey, onBlock })`.
+ */
+export function resolveGuard(target, block = {}) {
+    if (typeof target.decide === 'function') {
+        return { client: target, block };
+    }
+    return { client: createClient(target), block: target };
+}

package/dist/next.d.ts

@@ -0,0 +1,16 @@
+/** @noirtrack/sdk/next — firewall middleware for Next.js (Edge runtime). */
+import { NextRequest, NextResponse } from 'next/server';
+import { type GuardTarget } from './index.js';
+/**
+ *   // middleware.ts
+ *   import { createClient } from '@noirtrack/sdk';
+ *   import { guard } from '@noirtrack/sdk/next';
+ *
+ *   const noir = createClient({ publicKey: '...', secretKey: process.env.NOIRTRACK_SECRET! });
+ *   export const middleware = guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
+ *   export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };
+ *
+ * You can also pass options directly: `guard({ publicKey, secretKey, onBlock: 'redirect' })`.
+ * Fails open: a NoirTrack error/timeout never blocks or breaks your site.
+ */
+export declare function guard(target: GuardTarget, blockOptions?: import('./core/types.js').BlockOptions): (request: NextRequest) => Promise<NextResponse>;

package/dist/next.js

@@ -0,0 +1,49 @@
+/** @noirtrack/sdk/next — firewall middleware for Next.js (Edge runtime). */
+import { NextResponse } from 'next/server';
+import { clientIp } from './core/client-ip.js';
+import { isBlockedPagePath } from './core/endpoint.js';
+import { resolveGuard } from './index.js';
+/**
+ *   // middleware.ts
+ *   import { createClient } from '@noirtrack/sdk';
+ *   import { guard } from '@noirtrack/sdk/next';
+ *
+ *   const noir = createClient({ publicKey: '...', secretKey: process.env.NOIRTRACK_SECRET! });
+ *   export const middleware = guard(noir, { onBlock: 'redirect', blockedPage: '/blocked' });
+ *   export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };
+ *
+ * You can also pass options directly: `guard({ publicKey, secretKey, onBlock: 'redirect' })`.
+ * Fails open: a NoirTrack error/timeout never blocks or breaks your site.
+ */
+export function guard(target, blockOptions) {
+    const { client, block } = resolveGuard(target, blockOptions);
+    return async function middleware(request) {
+        const ip = clientIp((name) => request.headers.get(name));
+        const ua = request.headers.get('user-agent') ?? '';
+        const path = request.nextUrl.pathname;
+        // Record the hit as an analytics pageview in the same call (default), so the firewall
+        // doubles as analytics with no separate snippet. Set `analytics: false` for a pure filter.
+        const record = block.analytics !== false;
+        const verdict = await client.decide({
+            ip,
+            ua,
+            path: record ? path + request.nextUrl.search : path,
+            host: record ? (request.headers.get('host') ?? request.nextUrl.host) : undefined,
+            referrer: record ? request.headers.get('referer') : undefined,
+            visitorId: record ? request.cookies.get('noir_vid')?.value : undefined,
+            record,
+        });
+        if (verdict?.action !== 'block')
+            return NextResponse.next();
+        const mode = block.onBlock ?? 'block';
+        const page = verdict.blocked_page ?? block.blockedPage;
+        // The blocked page must stay reachable, or a still-blocked visitor loops forever
+        // when that page also runs this middleware.
+        if ((mode === 'redirect' || mode === 'rewrite') && page) {
+            if (isBlockedPagePath(path, page))
+                return NextResponse.next();
+            return mode === 'redirect' ? NextResponse.redirect(new URL(page, request.url)) : NextResponse.rewrite(new URL(page, request.url));
+        }
+        return new NextResponse('Forbidden', { status: block.blockStatus ?? 403 });
+    };
+}

package/dist/react-native.d.ts

@@ -0,0 +1,24 @@
+import { type Ingest } from './core/ingest.js';
+/** Minimal async key/value store. `@react-native-async-storage/async-storage` satisfies it. */
+export interface RNStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface RNClientOptions {
+    /** Public key (`pk_live_...`). */
+    publicKey: string;
+    /** Persistent store (pass AsyncStorage). Omit for an in-memory, session-only id. */
+    storage?: RNStorage;
+    /** App identifier reported as the event host (for example your bundle id). */
+    app?: string;
+    /** Send the initial view on init. Default false (RN screens are tracked manually). */
+    autoView?: boolean;
+    /** Self-hosted base URL. Defaults to the hosted service. */
+    endpoint?: string;
+    timeoutMs?: number;
+    flushIntervalMs?: number;
+    maxQueueSize?: number;
+}
+export type RNClient = Ingest;
+export declare function createClient(options: RNClientOptions): Promise<RNClient>;

package/dist/react-native.js

@@ -0,0 +1,78 @@
+/**
+ * @noirtrack/sdk/react-native — analytics for React Native and Expo apps.
+ *
+ *   import AsyncStorage from '@react-native-async-storage/async-storage';
+ *   import { createClient } from '@noirtrack/sdk/react-native';
+ *
+ *   const noir = await createClient({ publicKey: 'pk_live_...', storage: AsyncStorage });
+ *   noir.view('Home');                 // a screen view
+ *   noir.event('signup', { plan: 'pro' });
+ *
+ * Same API as the web client (public key only), with two differences: storage is async so
+ * `createClient` returns a Promise, and screen views are manual (call `view(screenName)` from
+ * your navigation listener, since RN has no shared router).
+ */
+import { resolveEndpoint } from './core/endpoint.js';
+import { uuid } from './core/ids.js';
+import { createIngest } from './core/ingest.js';
+export async function createClient(options) {
+    const endpoint = resolveEndpoint(options.endpoint);
+    const store = options.storage;
+    async function loadId(key) {
+        if (store) {
+            try {
+                const existing = await store.getItem(key);
+                if (existing)
+                    return existing;
+            }
+            catch {
+                /* fall through to a fresh id */
+            }
+        }
+        const fresh = uuid();
+        if (store)
+            await store.setItem(key, fresh).catch(() => { });
+        return fresh;
+    }
+    let visitorId = await loadId('noir_vid');
+    let sessionId = await loadId('noir_sid');
+    function context(pathOverride) {
+        return {
+            host: options.app ?? null,
+            path: pathOverride ?? '/',
+            referrer: null,
+            screen: null,
+            utm: { source: null, medium: null, campaign: null },
+        };
+    }
+    const platform = {
+        publicKey: options.publicKey,
+        endpoint,
+        timeoutMs: options.timeoutMs ?? 800,
+        batch: true,
+        flushIntervalMs: options.flushIntervalMs ?? 5000,
+        maxQueueSize: options.maxQueueSize ?? 10,
+        visitorId: () => visitorId,
+        sessionId: () => sessionId,
+        resetIds() {
+            visitorId = uuid();
+            sessionId = uuid();
+            if (store) {
+                void store.setItem('noir_vid', visitorId).catch(() => { });
+                void store.setItem('noir_sid', sessionId).catch(() => { });
+            }
+        },
+        context,
+        disabled: () => false,
+        deliver(url, body) {
+            void fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }).catch(() => { });
+        },
+        scheduleFlush(flush) {
+            setInterval(flush, options.flushIntervalMs ?? 5000);
+        },
+    };
+    const ingest = createIngest(platform);
+    if (options.autoView)
+        ingest.view();
+    return ingest;
+}

package/dist/web.d.ts

@@ -0,0 +1,30 @@
+import { type Ingest } from './core/ingest.js';
+export interface WebClientOptions {
+    /** Public key (`pk_live_...`). */
+    publicKey: string;
+    /** Capture the initial pageview and SPA route changes. Default true. */
+    autoPageviews?: boolean;
+    /** Fire goals from `data-noir-goal` (click) and `data-noir-scroll` (view) attributes, like the
+     *  hosted snippet. Re-scans as a framework renders new sections. Default true. */
+    autoGoals?: boolean;
+    /** Privacy mode: no cookies, ids live in sessionStorage. No consent banner needed. */
+    cookieless?: boolean;
+    /** Track on localhost too (off by default, like the hosted script). */
+    allowLocalhost?: boolean;
+    /** Soft, client-side firewall on the first view. Off by default. */
+    block?: 'redirect' | 'overlay';
+    /** Where to send blocked visitors when `block` is `redirect`. */
+    blockedPage?: string;
+    /** Self-hosted base URL. Defaults to the hosted service. */
+    endpoint?: string;
+    timeoutMs?: number;
+    /** Ms between batch flushes. Default 5000. */
+    flushIntervalMs?: number;
+    /** Max queued events before an early flush. Default 10. */
+    maxQueueSize?: number;
+}
+export interface WebClient extends Ingest {
+    /** Whether the client was initialised in cookieless mode. */
+    readonly cookieless: boolean;
+}
+export declare function createClient(options: WebClientOptions): WebClient;