@traceten/sdk-node 1.0.0

package/dist/client.js

@@ -0,0 +1,320 @@
+/**
+ * The buffered Traceten client.
+ *
+ * `page()` and `track()` split at the API surface (two endpoints, two payload
+ * shapes) but unify in one buffered client with a single flush that drains both
+ * internal queues. See DESIGN.md §3–§4.
+ */
+import { Transport, chunk } from "./queue.js";
+import { normalizeCurrency, normalizeHost, toIsoTimestamp, validateConversionName, validateConversionSessionId, validateEventName, validateEventSessionId, validateGoalName, validateReferrer, validateAmount, validateApiKey, validateProvider, validateSiteId, validateTransactionId, normalizePaymentCurrency, validateUrl, validateUserAgent, validateValueCents, validateVisitorId, } from "./validate.js";
+const DEFAULT_FLUSH_AT = 50;
+const MAX_FLUSH_AT = 50;
+const MIN_FLUSH_AT = 1;
+const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_TIMEOUT_MS = 10000;
+/** Node process signals we install best-effort flush handlers for. */
+const EXIT_SIGNALS = ["SIGTERM", "SIGINT"];
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Validate an optional positive-number config field. */
+function positiveOr(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new TypeError(`Traceten: ${name} must be a positive number`);
+    }
+    return value;
+}
+export class Client {
+    siteId;
+    host;
+    flushAt;
+    transport;
+    onError;
+    events = [];
+    conversions = [];
+    timer;
+    inflight = new Set();
+    exitHooks = [];
+    closed = false;
+    constructor(options) {
+        if (options === null || typeof options !== "object") {
+            throw new TypeError("Traceten: Client requires an options object");
+        }
+        this.siteId = validateSiteId(options.siteId);
+        this.host = normalizeHost(options.host);
+        // Validated BEFORE anything else is set up: an integration missing its key
+        // would otherwise start, buffer, flush, and 401 every batch forever while
+        // looking perfectly healthy from the outside.
+        const apiKey = validateApiKey(options.apiKey);
+        this.flushAt = clamp(options.flushAt ?? DEFAULT_FLUSH_AT, MIN_FLUSH_AT, MAX_FLUSH_AT);
+        this.onError = options.onError ?? (() => undefined);
+        const flushInterval = positiveOr(options.flushInterval, DEFAULT_FLUSH_INTERVAL_MS, "flushInterval");
+        const maxRetries = options.maxRetries === undefined
+            ? DEFAULT_MAX_RETRIES
+            : (() => {
+                if (typeof options.maxRetries !== "number" ||
+                    !Number.isInteger(options.maxRetries) ||
+                    options.maxRetries < 0) {
+                    throw new TypeError("Traceten: maxRetries must be a non-negative integer");
+                }
+                return options.maxRetries;
+            })();
+        const timeoutMs = positiveOr(options.timeoutMs, DEFAULT_TIMEOUT_MS, "timeoutMs");
+        this.transport = new Transport({
+            host: this.host,
+            apiKey,
+            maxRetries,
+            timeoutMs,
+            onError: this.onError,
+        });
+        // Background flush timer — unref'd so it never keeps the process alive.
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, flushInterval);
+        this.timer.unref();
+        if (options.flushOnExit ?? true) {
+            this.registerExitHooks();
+        }
+    }
+    /**
+     * Enqueue a pageview (`/v1/server/events`). Returns immediately; never throws on
+     * network problems. Throws synchronously on programmer errors (bad url,
+     * bad eventName, bad visitorId).
+     */
+    page(props) {
+        this.assertOpen();
+        if (props === null || typeof props !== "object") {
+            throw new TypeError("Traceten: page() requires a props object");
+        }
+        const url = validateUrl(props.url);
+        const eventName = validateEventName(props.eventName ?? "pageview");
+        const referrer = validateReferrer(props.referrer ?? "");
+        const ts = toIsoTimestamp(props.timestamp);
+        const event = { siteId: this.siteId, ts, url, referrer, eventName };
+        if (props.sessionId !== undefined) {
+            event.sessionId = validateEventSessionId(props.sessionId);
+        }
+        if (props.visitorId !== undefined) {
+            event.vid = validateVisitorId(props.visitorId);
+        }
+        if (props.userAgent !== undefined) {
+            event.ua = validateUserAgent(props.userAgent);
+        }
+        this.events.push(event);
+        this.maybeFlush();
+    }
+    /**
+     * Enqueue a conversion (`/v1/server/conversions`). `opts.visitorId` is REQUIRED —
+     * omitting it is a programmer error and throws synchronously (a conversion
+     * cannot be attributed without it). Returns immediately otherwise.
+     */
+    track(name, opts) {
+        this.assertOpen();
+        const eventName = validateConversionName(name);
+        if (opts === null || typeof opts !== "object") {
+            throw new TypeError("Traceten: track() requires an options object with a visitorId");
+        }
+        if (opts.visitorId === undefined) {
+            throw new TypeError("Traceten: track() requires opts.visitorId — conversions cannot attribute without it");
+        }
+        const visitorId = validateVisitorId(opts.visitorId);
+        const timestamp = toIsoTimestamp(opts.timestamp);
+        const conversion = {
+            event_name: eventName,
+            site_id: this.siteId,
+            timestamp,
+            visitor_id: visitorId,
+            properties: opts.properties ?? {},
+        };
+        if (opts.sessionId !== undefined) {
+            conversion.session_id = validateConversionSessionId(opts.sessionId);
+        }
+        if (opts.valueCents !== undefined) {
+            conversion.value_cents = validateValueCents(opts.valueCents);
+        }
+        if (opts.currency !== undefined) {
+            conversion.currency = normalizeCurrency(opts.currency);
+        }
+        this.conversions.push(conversion);
+        this.maybeFlush();
+    }
+    /**
+     * Enqueue a goal completion. Identical to {@link Client.track} in every
+     * respect except the name check: the reserved Stripe/Shopify names are
+     * refused, because a goal that collides with one silently corrupts the site's
+     * revenue funnel.
+     *
+     * A goal IS a custom event — this is the same `/v1/server/conversions` call
+     * under a name that matches what the dashboard calls it.
+     *
+     * @example
+     * ```ts
+     * traceten.goal("demo_booked", { visitorId, properties: { plan: "pro" } });
+     * ```
+     */
+    goal(name, opts) {
+        this.track(validateGoalName(name), opts);
+    }
+    /**
+     * Record a payment from ANY payment processor (`POST /v1/server/payments`).
+     *
+     * ⚠️ The only method here that is AWAITED and that can reject. `page()` and
+     * `track()` are buffered and fire-and-forget because a lost pageview is a lost
+     * pageview; a lost payment is missing revenue, and the endpoint's whole point
+     * is the idempotency answer it returns — which a queue could not give back.
+     *
+     * Safe to call again with the same `transactionId`: the server deduplicates
+     * durably on `(site, provider, transactionId)` and answers `"duplicate"`
+     * rather than recording a second payment.
+     *
+     * `settlementAmount`/`settlementCurrency` are an optional fallback: your
+     * processor's own conversion of the payment into a currency Traceten can
+     * price, used only when `currency` itself isn't one Traceten prices
+     * natively. Set both or neither — one without the other is dropped.
+     *
+     * @example
+     * ```ts
+     * const res = await traceten.payment({
+     *   transactionId: charge.id,
+     *   amount: 49.99,
+     *   currency: "USD",
+     *   provider: "dodo",
+     *   email: customer.email,
+     * });
+     * // res.status === "recorded"
+     * ```
+     */
+    async payment(props) {
+        this.assertOpen();
+        if (props === null || typeof props !== "object") {
+            throw new TypeError("Traceten: payment() requires a props object");
+        }
+        const payment = {
+            site_id: this.siteId,
+            transaction_id: validateTransactionId(props.transactionId),
+            amount: validateAmount(props.amount),
+            currency: normalizePaymentCurrency(props.currency),
+        };
+        if (props.provider !== undefined)
+            payment.provider = validateProvider(props.provider);
+        if (props.visitorId !== undefined)
+            payment.visitor_id = validateVisitorId(props.visitorId);
+        if (props.email !== undefined)
+            payment.email = props.email;
+        if (props.customerId !== undefined)
+            payment.customer_id = props.customerId;
+        if (props.renewal !== undefined)
+            payment.renewal = props.renewal;
+        if (props.refunded !== undefined)
+            payment.refunded = props.refunded;
+        if (props.isFreeTrial !== undefined)
+            payment.is_free_trial = props.isFreeTrial;
+        if (props.timestamp !== undefined)
+            payment.timestamp = toIsoTimestamp(props.timestamp);
+        // Fallback fields — never sent unless BOTH are present. One without the
+        // other is not a valid settlement figure and the server would reject it.
+        if (props.settlementAmount !== undefined && props.settlementCurrency !== undefined) {
+            payment.settlement_amount = validateAmount(props.settlementAmount);
+            payment.settlement_currency = normalizePaymentCurrency(props.settlementCurrency);
+        }
+        return this.transport.sendPayment(payment);
+    }
+    /**
+     * Drain both queues now. Resolves once every in-flight request settles.
+     * Never rejects — delivery failures surface via `onError`.
+     */
+    async flush() {
+        // Snapshot + clear synchronously so concurrent enqueues aren't lost or
+        // double-sent. JS is single-threaded, so nothing runs between these lines.
+        const events = this.events;
+        this.events = [];
+        const conversions = this.conversions;
+        this.conversions = [];
+        // Send sequentially, not via Promise.all: firing one request per queued
+        // conversion concurrently would open N connections at once and, against the
+        // Worker's per-site / per-IP rate limits (100–200 req/min), trigger a 429
+        // storm that drops revenue events after retries. Matches the Go/Python SDKs.
+        for (const batch of chunk(events, this.flushAt)) {
+            await this.launch(this.transport.sendEvents(batch));
+        }
+        for (const conversion of conversions) {
+            await this.launch(this.transport.sendConversion(conversion));
+        }
+    }
+    /**
+     * Flush, stop the background timer, and remove exit hooks. Idempotent — safe
+     * to call more than once. After close, `page()`/`track()` throw.
+     */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        for (const { event, handler } of this.exitHooks) {
+            process.removeListener(event, handler);
+        }
+        this.exitHooks = [];
+        await this.flush();
+        // Await any batches launched by a prior auto-/timer-flush still in flight.
+        await Promise.all([...this.inflight]);
+    }
+    /** Alias for {@link Client.close} — matches the cross-language `shutdown()`. */
+    shutdown() {
+        return this.close();
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    assertOpen() {
+        if (this.closed) {
+            throw new Error("Traceten: client is closed; construct a new Client to send more events");
+        }
+    }
+    /** Trigger a flush when either queue has reached the flush threshold. */
+    maybeFlush() {
+        if (this.events.length >= this.flushAt || this.conversions.length >= this.flushAt) {
+            void this.flush();
+        }
+    }
+    /** Track an in-flight send so `close()` can await it, then self-remove. */
+    launch(promise) {
+        const tracked = promise.finally(() => {
+            this.inflight.delete(tracked);
+        });
+        this.inflight.add(tracked);
+        return tracked;
+    }
+    /**
+     * Register best-effort flush-on-exit hooks.
+     *
+     * `beforeExit` fires when the loop would otherwise empty — we flush and let
+     * the pending I/O keep the process alive until it settles. For `SIGTERM` /
+     * `SIGINT` we flush, then re-exit ONLY if we were the sole handler (otherwise
+     * the host app owns the shutdown decision and forcing `process.exit` would
+     * stomp its own handlers / exit code).
+     */
+    registerExitHooks() {
+        const beforeExit = () => {
+            void this.flush();
+        };
+        process.once("beforeExit", beforeExit);
+        this.exitHooks.push({ event: "beforeExit", handler: beforeExit });
+        for (const signal of EXIT_SIGNALS) {
+            const soleHandler = process.listenerCount(signal) === 0;
+            const handler = () => {
+                void this.flush().finally(() => {
+                    if (soleHandler) {
+                        process.exit(0);
+                    }
+                });
+            };
+            process.once(signal, handler);
+            this.exitHooks.push({ event: signal, handler });
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@traceten/sdk-node` — the Traceten server-side SDK for Node.js.
+ *
+ * Send AI-traffic pageviews (`page`) and revenue/conversion events (`track`)
+ * from your backend over authenticated, ad-blocker-resistant HTTP. See
+ * `API.md` for the quickstart and full reference.
+ *
+ * @example
+ * ```ts
+ * import { Client } from "@traceten/sdk-node";
+ *
+ * const traceten = new Client({ siteId: "ttid_7Rb4TrC1dTbnD8w3s1TS12", host: "https://ingest.traceten.com" });
+ * traceten.page({ url: "https://acme.com/pricing", visitorId });
+ * traceten.track("subscription_started", { visitorId, valueCents: 4900, currency: "usd" });
+ * await traceten.close(); // flush on shutdown
+ * ```
+ */
+export { Client } from "./client.js";
+export type { ClientOptions, PageProps, PaymentProps, PaymentResult, PaymentStatus, TrackOptions, OnError, EventWire, ConversionWire, PaymentWire, } from "./types.js";
+export { verifyWebhook, WebhookVerificationError, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_REPLAY_TOLERANCE_SECONDS, WEBHOOK_EVENT_TYPES, ATTRIBUTION_MODELS, } from "./webhook.js";
+export type { WebhookEvent, WebhookEventType, VerifyWebhookOptions, AiSessionClassifiedData, ConversionAttributedData, WebhookPingData, AttributionModel, AttributionModelBreakdown, } from "./webhook.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EACV,aAAa,EACb,SAAS,EACT,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,OAAO,EACP,SAAS,EACT,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,gCAAgC,EAChC,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@traceten/sdk-node` — the Traceten server-side SDK for Node.js.
+ *
+ * Send AI-traffic pageviews (`page`) and revenue/conversion events (`track`)
+ * from your backend over authenticated, ad-blocker-resistant HTTP. See
+ * `API.md` for the quickstart and full reference.
+ *
+ * @example
+ * ```ts
+ * import { Client } from "@traceten/sdk-node";
+ *
+ * const traceten = new Client({ siteId: "ttid_7Rb4TrC1dTbnD8w3s1TS12", host: "https://ingest.traceten.com" });
+ * traceten.page({ url: "https://acme.com/pricing", visitorId });
+ * traceten.track("subscription_started", { visitorId, valueCents: 4900, currency: "usd" });
+ * await traceten.close(); // flush on shutdown
+ * ```
+ */
+export { Client } from "./client.js";
+export { verifyWebhook, WebhookVerificationError, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_REPLAY_TOLERANCE_SECONDS, WEBHOOK_EVENT_TYPES, ATTRIBUTION_MODELS, } from "./webhook.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAcrC,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,gCAAgC,EAChC,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC"}

package/dist/queue.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Transport layer for the Traceten Node SDK.
+ *
+ * Owns the "one HTTP request, with retry" primitive that both queues share.
+ * Batching/chunking lives in the {@link Client}; this module only knows how to
+ * deliver a single already-shaped body to a single endpoint, retrying on
+ * transient failures per DESIGN.md §4.
+ *
+ * Retry policy:
+ *   - 2xx                       → success.
+ *   - 5xx or 429 or network/timeout → retryable; exponential backoff with full
+ *                                     jitter (`base 200ms * 2^attempt`), up to
+ *                                     `maxRetries` retries.
+ *   - other 4xx                 → the payload is malformed; DROP it and call
+ *                                 `onError`. Retrying a 400 forever is a
+ *                                 self-DoS.
+ */
+import type { ConversionWire, EventWire, OnError, PaymentResult, PaymentWire } from "./types.js";
+export interface TransportOptions {
+    host: string;
+    /** REQUIRED — `/v1/server/*` returns 401 without it. */
+    apiKey: string;
+    maxRetries: number;
+    timeoutMs: number;
+    onError: OnError;
+}
+/** Split `items` into contiguous chunks of at most `size`. */
+export declare function chunk<T>(items: readonly T[], size: number): T[][];
+export declare class Transport {
+    private readonly eventsUrl;
+    private readonly conversionsUrl;
+    private readonly paymentsUrl;
+    private readonly headers;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    private readonly onError;
+    constructor(opts: TransportOptions);
+    /** Send one `/v1/server/events` batch envelope. Never throws. */
+    sendEvents(events: EventWire[]): Promise<void>;
+    /** Send one `/v1/server/conversions` body (one event per request). Never throws. */
+    sendConversion(conversion: ConversionWire): Promise<void>;
+    /**
+     * Send one `/v1/server/payments` body and RETURN the outcome (#794).
+     *
+     * Unlike the two above, this one is awaited and its result surfaced: the
+     * endpoint's whole contract is the idempotency answer, so swallowing it would
+     * discard the one thing the caller asked for.
+     *
+     * Retrying is safe for the same reason — the server deduplicates on
+     * `(site, provider, transaction_id)` durably, so a retried 5xx cannot become a
+     * second payment.
+     *
+     * @throws when the payment was NOT accepted after every retry. `payment()` is
+     *   the only SDK call that rejects, because a silently dropped payment is
+     *   missing revenue rather than a missing pageview.
+     */
+    sendPayment(payment: PaymentWire): Promise<PaymentResult>;
+    /** One attempt that also reads the JSON body, for the payments endpoint. */
+    private attemptJson;
+    /**
+     * POST `body` to `url`, retrying transient failures. Resolves once the
+     * request either succeeds or is permanently given up on (after calling
+     * `onError`). Deliberately never rejects — `page()`/`track()`/`flush()` must
+     * not throw on network problems.
+     */
+    private deliver;
+    /** A single HTTP attempt, classified into an {@link Outcome}. */
+    private attempt;
+    /** Invoke the user `onError` hook, swallowing any error it throws. */
+    private reportError;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAKjG,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,8DAA8D;AAC9D,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAMjE;AAuBD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEtB,IAAI,EAAE,gBAAgB;IAoBlC,iEAAiE;IAC3D,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD,oFAAoF;IAC9E,cAAc,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/D;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAsB/D,4EAA4E;YAC9D,WAAW;IAgDzB;;;;;OAKG;YACW,OAAO;IAmBrB,iEAAiE;YACnD,OAAO;IAwCrB,sEAAsE;IACtE,OAAO,CAAC,WAAW;CAOpB"}