@intenque/network-sdk 0.0.0-stage → 2.2.0-beta.2

package/dist/server/index.d.cts

@@ -0,0 +1,350 @@
+export { a as SDK_VERSION } from '../constants-C_6Zxu_k.cjs';
+
+type SignInput = {
+    secret: string;
+    siteKey: string;
+    keyId: string;
+    method: string;
+    /** Path only (`/v1/conversions`, `/v1/conversions/ping`, `/v1/referrals/<clickId>`, `/v1/landings`). */
+    path: string;
+    /** The exact bytes sent (`''` for an empty body). */
+    body: string | Uint8Array;
+    /** Unix seconds; defaults to now. */
+    timestamp?: number;
+    /** uuid v4; defaults to a fresh one. Every attempt re-signs with a fresh nonce (§6.5). */
+    nonce?: string;
+};
+type SignedHeaders = {
+    'Content-Type': 'application/json';
+    'X-INR-Site': string;
+    'X-INR-Key-Id': string;
+    'X-INR-Timestamp': string;
+    'X-INR-Nonce': string;
+    'X-INR-Signature': string;
+};
+declare function sha256Hex(data: string | Uint8Array): string;
+/** The v1 HMAC base string: the identifiers are bound, so a signature never verifies under another site or key. */
+declare function hmacBase(timestamp: number, nonce: string, siteKey: string, keyId: string, method: string, path: string, body: string | Uint8Array): string;
+declare function signRequest(input: SignInput): {
+    headers: SignedHeaders;
+    timestamp: number;
+    nonce: string;
+    signature: string;
+};
+/** Constant-time check of a `v1=<hex>` signature (what the hub does; here for tests and ports). */
+declare function verifySignature(secret: string, input: {
+    timestamp: number;
+    nonce: string;
+    siteKey: string;
+    keyId: string;
+    method: string;
+    path: string;
+    body: string | Uint8Array;
+}, signature: string): boolean;
+
+type ReferralRef = {
+    clickId: string;
+    firstClickId: string | null;
+    tokenScope: 'session' | 'persistent';
+};
+type ReqLike = {
+    body?: unknown;
+    headers?: Record<string, unknown> | undefined;
+    get?: (name: string) => string | undefined;
+};
+declare function referralFromRequest(req: ReqLike): ReferralRef | null;
+/**
+ * Express middleware alternative: sets `req.inrRef` (`ReferralRef | null`), then removes an own `inrRef` from any
+ * object body (valid or not; plain objects, arrays and class instances alike), so `new Model(req.body)` and strict
+ * validators never see it (2.2 changelog). A body that cannot be changed (frozen, a throwing proxy) keeps it and never
+ * throws.
+ */
+declare function referralMiddleware(): (req: ReqLike & {
+    inrRef?: ReferralRef | null;
+}, _res: unknown, next: () => void) => void;
+
+/**
+ * Mongo outbox for conversion reports — spec §6.5: collection `inrConversionOutbox` (TTL 14 d, matching the hub's
+ * `occurredAt` lower bound), one row per `(eventType, eventId)`, storing the UNSIGNED body (every attempt re-signs
+ * with a fresh timestamp and nonce). `nextAttemptAt` is the lease (addendum "Claim and lease"); `unauthorizedSince`
+ * carries the 24 h rule of 401, missing config and misrouted answers (403, 404, a 3xx). The site passes its own `mongoose` (7 or 8; the model API used is identical on both); the
+ * SDK has no runtime dependency on it. The schema declares no index and has `autoIndex: false`: `ensureOutboxIndexes`
+ * creates the three helper indexes itself (addendum "Outbox row v2 and indexes"). The bounded in-memory spill holds
+ * reports whose enqueue failed or timed out (addendum "`report()`").
+ */
+declare const OUTBOX_DEFAULT_COLLECTION = "inrConversionOutbox";
+declare const OUTBOX_TTL_SECONDS: number;
+/** The last failed attempt: HTTP status (0 for transport failures and missing config) and the hub's error code. */
+type OutboxError = {
+    status: number;
+    code: string | null;
+};
+type OutboxEntry = {
+    eventType: string;
+    eventId: string;
+    body: Record<string, unknown>;
+    attempts: number;
+    nextAttemptAt: Date;
+    lastStatus: number | null;
+    lastError: OutboxError | null;
+    /** Set by the first 401, missing config or misrouted answer (403, 404, a 3xx); cleared by any other. */
+    unauthorizedSince: Date | null;
+    createdAt: Date;
+};
+type OutboxKey = Pick<OutboxEntry, 'eventType' | 'eventId'>;
+/** What a retried attempt writes back; `attempts` is the number of attempts this sender made. */
+type ReschedulePatch = {
+    nextAttemptAt: Date;
+    lastStatus: number;
+    lastError: OutboxError;
+    attempts: number;
+    /** The 401 / missing-config clock: kept at its earliest value; `null` clears it. */
+    unauthorizedAt: Date | null;
+};
+/** The subset of mongoose the outbox touches (so tests can pass a stub and the SDK stays dependency-free). */
+type MongooseLike = {
+    Schema: new (definition: Record<string, unknown>, options?: Record<string, unknown>) => unknown;
+    models: Record<string, unknown>;
+    model: (name: string, schema?: unknown, collection?: string) => unknown;
+};
+type Thenable<T> = Promise<T> | {
+    exec: () => Promise<T>;
+};
+type Filter = Record<string, unknown>;
+/** The model methods used (addendum "Mongoose 7 and 8"). */
+type OutboxModelLike = {
+    updateOne: (filter: Filter, update: Filter, options?: Filter) => Thenable<unknown>;
+    findOneAndUpdate?: (filter: Filter, update: Filter, options?: Filter) => Thenable<unknown>;
+    deleteOne?: (filter: Filter) => Thenable<unknown>;
+    deleteMany?: (filter: Filter) => Thenable<unknown>;
+    countDocuments: (filter?: Filter) => Thenable<number>;
+    collection?: {
+        createIndex: (keys: Filter, options?: Filter) => Promise<unknown>;
+    };
+};
+declare function outboxSchemaDefinition(): Record<string, unknown>;
+/** The three helper indexes (default names), created by `ensureOutboxIndexes`, never by `autoIndex`. */
+declare const OUTBOX_INDEXES: readonly [Filter, Filter][];
+/** Builds (or reuses) the outbox model on the given mongoose instance. */
+declare function outboxModel(mongoose: MongooseLike, collection?: string): OutboxModelLike;
+/**
+ * Creates the helper indexes (`collection.createIndex`, so `autoIndex: false` sites get them too): each one on its
+ * own, so a conflict on one leaves the others created. Called at construction and at every drain tick until all three
+ * succeed (a reporter built before `mongoose.connect()` times out its first try). Failures are one warn
+ * `INR_OUTBOX_INDEX_FAILED` per process and model; reporting goes on without them.
+ */
+declare function ensureOutboxIndexes(model: OutboxModelLike, warn: (message: string) => void): Promise<void>;
+type Outbox = {
+    /**
+     * Idempotent on `(eventType, eventId)`: inserts the entry's whole state once; a repeat leaves the existing row
+     * alone. Resolves `true` when this call inserted the row.
+     */
+    enqueue: (entry: OutboxEntry) => Promise<boolean>;
+    /** Success or a drop. */
+    remove: (key: OutboxKey) => Promise<void>;
+    /** A retried attempt. Never creates a row. */
+    reschedule: (key: OutboxKey, patch: ReschedulePatch) => Promise<void>;
+    /** An in-process chain renews its row's lease before each retry; false when no such row exists (purged). */
+    renew: (key: OutboxKey, until: Date) => Promise<boolean>;
+    /** The drain claim: the most overdue due row, its lease moved to `until` and `attempts + 1`; null when none. */
+    claim: (now: Date, until: Date) => Promise<OutboxEntry | null>;
+    /** `forget()`: deletes every row whose body names the click id (as `clickId` or `firstClickId`). */
+    purge: (clickId: string) => Promise<void>;
+    pending: () => Promise<number>;
+};
+declare function createOutbox(model: OutboxModelLike): Outbox;
+/** In-memory outbox for sites without Mongo (tests, `enabled: false`): lost on restart, by design. */
+declare function createMemoryOutbox(): Outbox & {
+    entries: OutboxEntry[];
+};
+/** Reports whose enqueue failed or timed out, oldest first, at most `max`. */
+type Spill = {
+    /** Adds the entry unless its key is already spilled; returns the oldest entry it evicted, if any. */
+    add: (entry: OutboxEntry) => OutboxEntry | null;
+    has: (key: OutboxKey) => boolean;
+    get: (key: OutboxKey) => OutboxEntry | undefined;
+    delete: (key: OutboxKey) => void;
+    entries: () => OutboxEntry[];
+    readonly size: number;
+};
+
+type Logger = {
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    info?: (message: string, meta?: Record<string, unknown>) => void;
+};
+type Classification = 'success' | 'terminal' | 'retryable' | 'skew' | 'unauthorized' | 'misrouted';
+/**
+ * The §6.5 matrix (status first, then code; a missing body is classified by status). Status 0 is a transport failure
+ * (network error, timeout). 403, 404 and any 3xx that reaches it are `misrouted` (a proxy, WAF or maintenance page in
+ * the way, a missing route prefix): retried in process, then every 10 min, dropped 24 h after the first like a 401.
+ * A real redirect never gets here: fetch with `redirect: 'error'` fails 301/302/303/307/308 (with or without
+ * `Location`) as a transport error (status 0, retryable), so only 300, 304 and the like are classified.
+ */
+declare function classifyResponse(status: number, code: string | null): Classification;
+
+/**
+ * The conversion wire contract as the SDK mirrors it — Phase 3 addendum "ConversionBodySchema home and SDK mirror",
+ * "EventId", "Link tables", "Per-type body rules", "`fee_charged`", "Site secret format", "`keyId`". packages/shared
+ * is the source; the server entry never imports it (zero runtime deps), and test/conversions-contract.test.ts fails
+ * when either side changes alone.
+ */
+/** §5.5 canonical conversion types plus `fee_charged` (R2(c)): 12 entries, in the hub's order. */
+declare const CONVERSION_TYPES: readonly ["booking_created", "booking_paid", "contact_submitted", "quote_requested", "call_clicked", "signup", "purchase", "booking_cancelled", "booking_refunded", "booking_no_show", "chargeback", "fee_charged"];
+type ConversionType = (typeof CONVERSION_TYPES)[number];
+/** Every type that carries `reverses`; a fee names the no-show or cancel it belongs to (it is not a reversal). */
+declare const LINK_TARGETS: {
+    readonly fee_charged: readonly ["booking_no_show", "booking_cancelled"];
+    readonly booking_cancelled: readonly ["booking_created"];
+    readonly booking_no_show: readonly ["booking_created"];
+    readonly booking_refunded: readonly ["booking_paid"];
+    readonly chargeback: readonly ["booking_paid", "purchase"];
+};
+declare const REVERSAL_TYPES: readonly ("booking_cancelled" | "booking_refunded" | "booking_no_show" | "chargeback")[];
+
+/**
+ * The outbox drainer — Phase 3 addendum "Drainer", "Claim and lease", "Drop logging". Each tick moves the spill into
+ * the outbox, then claims (lease now + 150 s, `attempts + 1`) and sends up to 50 due rows, one at a time; a 429 or 503
+ * ends the tick. Every attempt goes through `Delivery.attempt`, so it re-reads the config (a rotated `INR_KEY_ID` /
+ * `INR_SITE_SECRET` in `process.env` applies at the next row) and re-signs with a fresh timestamp and nonce. Ticks
+ * never overlap: the first at 10 s + U(0, 10 s), then 60 s ± 10 s after the previous one ends, unref'd.
+ */
+
+type DrainResult = {
+    sent: number;
+    retried: number;
+    dropped: number;
+};
+
+type RelayRequest = {
+    body?: unknown;
+    ip?: string | undefined;
+    headers?: Record<string, unknown> | undefined;
+    app?: {
+        get: (name: string) => unknown;
+    } | undefined;
+    readable?: boolean;
+    on?: (event: string, listener: (chunk?: unknown) => void) => unknown;
+};
+type RelayResponse = {
+    status: (code: number) => {
+        end: () => void;
+    };
+};
+type RelayOptions = {
+    /** The visitor's address when `req.ip` is not it (another proxy setup); Express `trust proxy` is still required. */
+    visitorIp?: ((req: RelayRequest) => string | null | undefined) | undefined;
+};
+
+/** `report()` resolves after at most this, whatever the outbox does. */
+declare const ENQUEUE_TIMEOUT_MS = 2000;
+type ConversionEvent = {
+    eventType: ConversionType;
+    eventId: string;
+    clickId: string;
+    firstClickId?: string | null | undefined;
+    tokenScope: 'session' | 'persistent';
+    occurredAt: Date | string;
+    valueCents?: number | null | undefined;
+    feeCents?: number | null | undefined;
+    currency?: string | null | undefined;
+    reverses?: {
+        eventType: ConversionType;
+        eventId: string;
+    } | null | undefined;
+};
+/** §5.4 v1 body (unknown keys → 400 on the hub, so nothing else is ever added here). */
+type ConversionBody = {
+    v: 1;
+    eventType: ConversionType;
+    eventId: string;
+    clickId: string;
+    firstClickId: string | null;
+    tokenScope: 'session' | 'persistent';
+    occurredAt: string;
+    valueCents: number | null;
+    feeCents: number | null;
+    currency: string | null;
+    reverses: {
+        eventType: ConversionType;
+        eventId: string;
+    } | null;
+    sdk: string;
+};
+type ReporterOptions = {
+    hubUrl?: string | undefined;
+    siteKey?: string | undefined;
+    /** `INR_KEY_ID` / `INR_SITE_SECRET` in `process.env` win at every attempt, so a redeploy after rotation applies. */
+    keyId?: string | undefined;
+    secret?: string | undefined;
+    /** `INR_ENABLED !== 'false'`; when false `report()` validates and drops. */
+    enabled?: boolean | undefined;
+    /** Per attempt; default `INR_TIMEOUT_MS` or 3000, clamped to [500, 30 000]. */
+    timeoutMs?: number | undefined;
+    /** `collection` defaults to `INR_OUTBOX_COLLECTION`, else `inrConversionOutbox` (the name `doctor` checks). */
+    outbox?: {
+        mongoose?: MongooseLike;
+        collection?: string;
+    } | undefined;
+    logger?: Logger | undefined;
+};
+type ReportResult = 
+/** Durable in the outbox. */
+{
+    status: 'queued';
+    body: ConversionBody;
+}
+/** The outbox write failed or timed out: held in memory (≤ 1000) until the next drain; attempts still run. */
+ | {
+    status: 'spilled';
+    body: ConversionBody;
+} | {
+    status: 'disabled';
+    body: ConversionBody;
+} | {
+    status: 'invalid';
+    error: string;
+};
+type ConversionReporter = {
+    /** Validates, builds the body, queues it and starts the in-process attempts. Never throws, never rejects. */
+    report: (event: ConversionEvent) => Promise<ReportResult>;
+    /**
+     * §5.9 erasure: purges queued reports naming the id, then the signed `DELETE /v1/referrals/:clickId` (up to 4
+     * attempts). True once the hub answered 2xx; keep the local referral until then. Ignores `enabled`.
+     */
+    forget: (clickId: string) => Promise<boolean>;
+    /** §5.3 first-party landing relay: an Express handler that always answers 204 (relay.ts). */
+    landingRelay: (opts?: RelayOptions) => (req: RelayRequest, res: RelayResponse) => Promise<void>;
+    /** The unsigned body an event produces (exposed for tests and for ports). */
+    bodyFor: (event: ConversionEvent) => ConversionBody | {
+        error: string;
+    };
+    /** One drain tick now (joins a running one). */
+    drainNow: () => Promise<DrainResult>;
+    /** Stops the drainer and waits ≤ 5 s for a running tick and the send chains (graceful shutdown). */
+    close: () => Promise<void>;
+    outbox: Outbox;
+    spill: Spill;
+    /** Resolves once every in-process attempt chain started so far has settled (tests, graceful shutdown). */
+    idle: () => Promise<void>;
+};
+/**
+ * The C.4 body, or the first rule it breaks (mirrors `ConversionBodySchema`): eventId per EVENT_ID_RE, clickId and
+ * tokenScope non-null, the per-type amount rules, currency required with any amount, `reverses` required on the
+ * linked types with `eventType ∈ LINK_TARGETS[type]` and null otherwise. Currency is upper-cased; a valid `Date` or an
+ * ISO datetime string with `Z` or an offset is sent as ISO UTC with milliseconds.
+ */
+declare function buildConversionBody(event: ConversionEvent): ConversionBody | {
+    error: string;
+};
+/**
+ * §6.5 `verifyEnv()`: returns the missing or invalid names (`INR_KEY_ID (invalid)`); never prints a value. Throws
+ * when `NODE_ENV !== 'production'` or `INR_STRICT_ENV === 'true'` (JCM staging runs NODE_ENV=production), warns
+ * otherwise so a misconfigured reporter never takes a production backend down. `opts.production` overrides NODE_ENV.
+ */
+declare function verifyEnv(env?: Record<string, string | undefined>, opts?: {
+    production?: boolean;
+    logger?: Logger;
+}): string[];
+declare function createConversionReporter(opts?: ReporterOptions): ConversionReporter;
+
+export { CONVERSION_TYPES, type Classification, type ConversionBody, type ConversionEvent, type ConversionReporter, type ConversionType, type DrainResult, ENQUEUE_TIMEOUT_MS, LINK_TARGETS, type Logger, type MongooseLike, OUTBOX_DEFAULT_COLLECTION, OUTBOX_INDEXES, OUTBOX_TTL_SECONDS, type Outbox, type OutboxEntry, type OutboxError, REVERSAL_TYPES, type ReferralRef, type RelayOptions, type ReportResult, type ReporterOptions, type SignInput, type SignedHeaders, type Spill, buildConversionBody, classifyResponse, createConversionReporter, createMemoryOutbox, createOutbox, ensureOutboxIndexes, hmacBase, outboxModel, outboxSchemaDefinition, referralFromRequest, referralMiddleware, sha256Hex, signRequest, verifyEnv, verifySignature };