@traceten/sdk-node 1.0.0

package/dist/validate.js

@@ -0,0 +1,323 @@
+/**
+ * Client-side validation for the Traceten Node SDK.
+ *
+ * Philosophy (see DESIGN.md §5): programmer errors surface *loudly and
+ * synchronously* at call time — a mis-shaped call is a bug you want to find in
+ * development, not a silent server-side 422 buried in logs. Delivery failures,
+ * by contrast, never throw (they go through `onError`).
+ *
+ * Every regex here is copied verbatim from the ingestion Worker
+ * (`apps/workers/src/index.ts`) so the client rejects exactly what the server
+ * would reject — never more, never less.
+ */
+/** `siteId` / `sessionId` charset on `/v1/events` (URL/Redis-safe). */
+const ID_RE = /^[A-Za-z0-9_-]+$/;
+/** `eventName` on `/v1/events` — hyphen allowed. */
+const EVENT_NAME_RE = /^[a-z][a-z0-9_-]*$/;
+/** `event_name` on `/v1/conversions` — stricter, NO hyphen. */
+const CONVERSION_NAME_RE = /^[a-z][a-z0-9_]*$/;
+/** Visitor id: a canonical UUID or the identify-hash form `h:<64-hex>`. */
+const VISITOR_ID_RE = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|h:[0-9a-f]{64})$/;
+/** ISO-4217 currency code, lowercased. */
+const CURRENCY_RE = /^[a-z]{3}$/;
+/**
+ * API key shape: "tk_live_" followed by 64 lowercase hex characters.
+ *
+ * Matches the server's own pre-database filter, so an obviously wrong value
+ * (a snippet key pasted into the wrong field, a truncated copy/paste) fails at
+ * construction instead of turning into a 401 per batch at runtime.
+ */
+const API_KEY_RE = /^tk_live_[0-9a-f]{64}$/;
+function fail(message) {
+    throw new TypeError(`Traceten: ${message}`);
+}
+/**
+ * Validate the constructor `siteId`. Throws synchronously on a bad value —
+ * a wrong site id means every event silently 422s server-side.
+ */
+export function validateSiteId(siteId) {
+    if (typeof siteId !== "string" || siteId.length < 1 || siteId.length > 64) {
+        fail("siteId must be a string of 1–64 characters");
+    }
+    if (!ID_RE.test(siteId)) {
+        fail("siteId must contain only A-Z, a-z, 0-9, _ or -");
+    }
+    return siteId;
+}
+/**
+ * Validate the constructor `apiKey`.
+ *
+ * REQUIRED since the SDK moved to `/v1/server/*` — that endpoint rejects an
+ * unauthenticated request with 401, so a missing key means every event is
+ * silently dropped server-side. Failing loudly in the constructor is the whole
+ * point: the alternative is a production integration that looks healthy and
+ * records nothing.
+ *
+ * Only the SHAPE is checked here. Whether the key is live, unrevoked and
+ * scoped to `siteId` is a server-side question, answered per request.
+ */
+export function validateApiKey(apiKey) {
+    if (typeof apiKey !== "string" || apiKey.length === 0) {
+        fail("apiKey is required. Create one in the dashboard under Settings -> API keys, " +
+            "and keep it server-side — it is a secret.");
+    }
+    if (!API_KEY_RE.test(apiKey)) {
+        fail('apiKey must look like "tk_live_" followed by 64 hexadecimal characters');
+    }
+    return apiKey;
+}
+/**
+ * Validate + normalize the constructor `host`: absolute http(s) URL, trailing
+ * slash stripped. Throws on anything else.
+ */
+export function normalizeHost(host) {
+    if (typeof host !== "string" || host.length === 0) {
+        fail("host is required and must be an absolute http(s) URL");
+    }
+    let url;
+    try {
+        url = new URL(host);
+    }
+    catch {
+        fail(`host "${host}" is not a valid URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        fail(`host must use http or https, got "${url.protocol}"`);
+    }
+    // Plaintext http is refused off-loopback. The SDK now attaches a live
+    // `Authorization: Bearer <apiKey>` to EVERY request, so an http host puts a
+    // secret on the wire in cleartext for anything between the caller and the
+    // ingest endpoint — a footgun that did not exist while the key was optional
+    // and unused. Loopback stays allowed so local development and the test stub
+    // keep working, where there is no network to intercept.
+    if (url.protocol === "http:" && !isLoopbackHostname(url.hostname)) {
+        fail(`host must use https (got "${host}"). The API key is sent as a Bearer ` +
+            `token on every request and http would transmit it in cleartext.`);
+    }
+    // Reject a userinfo component: "https://ingest.traceten.com@evil.com" parses
+    // with authority "evil.com", which would send the Bearer apiKey to the wrong
+    // host. host is trusted config, so this is a copy-paste footgun guard.
+    if (url.username !== "" || url.password !== "") {
+        fail("host must not contain a username/password (userinfo) component");
+    }
+    return host.replace(/\/+$/, "");
+}
+/**
+ * Is this hostname a loopback address?
+ *
+ * `localhost`, any `*.localhost` name (RFC 6761 reserves the whole TLD), the
+ * entire `127.0.0.0/8` block, and IPv6 `::1` — which `URL` reports bracketed.
+ */
+function isLoopbackHostname(hostname) {
+    const h = hostname.toLowerCase();
+    if (h === "localhost" || h.endsWith(".localhost"))
+        return true;
+    if (h === "[::1]" || h === "::1")
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+/** Validate the `page()` url: valid URL, ≤2048 chars. */
+export function validateUrl(url) {
+    if (typeof url !== "string") {
+        fail("page() requires a `url` string");
+    }
+    if (url.length > 2048) {
+        fail("url exceeds the 2048-character limit");
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        fail(`url "${url}" is not a valid URL`);
+    }
+    // Enforce http(s) for parity with the Python/Go SDKs (reject javascript:,
+    // data:, file:, etc.). A pageview url is always http(s).
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        fail(`url must use http or https, got "${parsed.protocol}"`);
+    }
+    return url;
+}
+/** Validate a `/v1/events` `eventName`. */
+export function validateEventName(name) {
+    if (typeof name !== "string" || name.length < 1 || name.length > 64) {
+        fail("eventName must be a string of 1–64 characters");
+    }
+    if (!EVENT_NAME_RE.test(name)) {
+        fail(`eventName "${name}" must match ^[a-z][a-z0-9_-]*$`);
+    }
+    return name;
+}
+/** Validate a `/v1/conversions` `event_name` (stricter — no hyphen). */
+export function validateConversionName(name) {
+    if (typeof name !== "string" || name.length < 1 || name.length > 64) {
+        fail("track() name must be a string of 1–64 characters");
+    }
+    if (!CONVERSION_NAME_RE.test(name)) {
+        fail(`track() name "${String(name)}" must match ^[a-z][a-z0-9_]*$ (no hyphen)`);
+    }
+    return name;
+}
+/**
+ * Goal names the Stripe/Shopify pipeline emits. `goal()` refuses them because a
+ * collision silently corrupts the site's revenue funnel; `track()` still accepts
+ * them, since that is how those events are legitimately sent.
+ *
+ * Mirrors RESERVED_GOAL_NAMES in Traceten's shared contract.
+ */
+export const RESERVED_GOAL_NAMES = [
+    "payment",
+    "free_trial",
+    "trial_started",
+    "trial_converted",
+    "subscription_started",
+    "subscription_upgraded",
+    "subscription_downgraded",
+    "subscription_renewed",
+    "subscription_cancel_scheduled",
+    "subscription_reactivated",
+    "subscription_ended",
+];
+/** Validate a `goal()` name: a conversion name that is not reserved. */
+export function validateGoalName(name) {
+    const validated = validateConversionName(name);
+    if (RESERVED_GOAL_NAMES.includes(validated)) {
+        fail(`goal() name "${validated}" is reserved for the Stripe/Shopify integrations. ` +
+            "Pick another name, or use track() if you really mean that event.");
+    }
+    return validated;
+}
+/** Validate a visitor id against the shared UUID | `h:<hash>` format. */
+export function validateVisitorId(vid) {
+    if (typeof vid !== "string" || !VISITOR_ID_RE.test(vid)) {
+        fail("visitorId must be a UUID or an `h:<64-hex>` identify hash");
+    }
+    return vid;
+}
+/** Validate an `/v1/events` `sessionId` (charset-restricted, ≤128). */
+export function validateEventSessionId(sessionId) {
+    if (typeof sessionId !== "string" || sessionId.length > 128) {
+        fail("sessionId must be a string of at most 128 characters");
+    }
+    if (!ID_RE.test(sessionId)) {
+        fail("sessionId must contain only A-Z, a-z, 0-9, _ or -");
+    }
+    return sessionId;
+}
+/** Validate a `/v1/conversions` `session_id` (length only, ≤128). */
+export function validateConversionSessionId(sessionId) {
+    if (typeof sessionId !== "string" || sessionId.length > 128) {
+        fail("sessionId must be a string of at most 128 characters");
+    }
+    return sessionId;
+}
+/** Validate a User-Agent string (≤512). */
+export function validateUserAgent(ua) {
+    if (typeof ua !== "string" || ua.length > 512) {
+        fail("userAgent must be a string of at most 512 characters");
+    }
+    return ua;
+}
+/** Validate a referrer string (≤2048). */
+export function validateReferrer(referrer) {
+    if (typeof referrer !== "string" || referrer.length > 2048) {
+        fail("referrer must be a string of at most 2048 characters");
+    }
+    return referrer;
+}
+/** Validate `valueCents`: a non-negative integer (minor units). */
+export function validateValueCents(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        fail("valueCents must be a non-negative integer in minor units (cents)");
+    }
+    return value;
+}
+/**
+ * Lowercase + validate an ISO-4217 currency code.
+ *
+ * The lowercasing is a CLIENT-SIDE normalisation only, and deliberately kept
+ * (#793): Traceten uppercases at every server boundary, so the case sent here
+ * does not reach storage. Do not read this as the wire format — stored and
+ * returned codes are uppercase.
+ */
+export function normalizeCurrency(currency) {
+    if (typeof currency !== "string") {
+        fail("currency must be a 3-letter ISO-4217 string");
+    }
+    const lowered = currency.toLowerCase();
+    if (!CURRENCY_RE.test(lowered)) {
+        fail(`currency "${currency}" must be a 3-letter ISO-4217 code`);
+    }
+    return lowered;
+}
+/** Lowercase provider slug, 1-32 chars. Mirrors `PAYMENT_PROVIDER_RE` (#794). */
+const PROVIDER_RE = /^[a-z][a-z0-9_-]{0,31}$/;
+/** Validate the processor's transaction id — the Payment API idempotency key. */
+export function validateTransactionId(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 255) {
+        fail("transactionId must be a non-empty string of at most 255 characters");
+    }
+    return value;
+}
+/**
+ * Validate a payment amount: a finite, non-negative DECIMAL in the major unit.
+ *
+ * Not integer cents, unlike `valueCents` — see {@link PaymentProps.amount}. A
+ * negative is rejected outright because a refund is the `refunded` flag; the
+ * server stores revenue as an unsigned integer and could not hold one anyway.
+ */
+export function validateAmount(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        fail("amount must be a finite, non-negative number in the currency's major unit");
+    }
+    return value;
+}
+/** Validate the optional Payment API `provider` label. */
+export function validateProvider(value) {
+    if (typeof value !== "string" || !PROVIDER_RE.test(value)) {
+        fail("provider must be 1-32 lowercase characters starting with a letter (a-z, 0-9, _, -)");
+    }
+    return value;
+}
+/**
+ * Uppercase + validate an ISO-4217 code for the Payment API.
+ *
+ * Uppercase, unlike {@link normalizeCurrency}: this endpoint is newer than the
+ * conversions one and there is no legacy lowercase behaviour to preserve, so it
+ * sends the case the server actually stores.
+ */
+export function normalizePaymentCurrency(currency) {
+    if (typeof currency !== "string") {
+        fail("currency must be a 3-letter ISO-4217 string");
+    }
+    const upper = currency.toUpperCase();
+    if (!/^[A-Z]{3}$/.test(upper)) {
+        fail(`currency "${currency}" must be a 3-letter ISO-4217 code`);
+    }
+    return upper;
+}
+/**
+ * Normalize a caller-supplied timestamp to an ISO-8601 UTC string (the format
+ * the ingest Worker's `z.string().datetime()` accepts). An invalid `Date` or
+ * unparseable string is a programmer error and throws.
+ */
+export function toIsoTimestamp(value) {
+    if (value === undefined) {
+        return new Date().toISOString();
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            fail("timestamp is an invalid Date");
+        }
+        return value.toISOString();
+    }
+    if (typeof value === "string") {
+        const parsed = new Date(value);
+        if (Number.isNaN(parsed.getTime())) {
+            fail(`timestamp "${value}" is not a valid ISO-8601 date`);
+        }
+        return parsed.toISOString();
+    }
+    fail("timestamp must be a Date or an ISO-8601 string");
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

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

package/dist/webhook.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Verification for Traceten's client-facing OUTBOUND webhooks.
+ *
+ * Traceten signs every webhook delivery so your endpoint can prove the request
+ * really came from us and was not tampered with or replayed. {@link verifyWebhook}
+ * does the three things a hand-rolled verifier most often gets wrong:
+ *
+ *   1. Recomputes `hmac-sha256(secret, `${timestamp}.${rawBody}`)` over the RAW
+ *      body bytes — never a re-serialized object.
+ *   2. Compares in **constant time** (`crypto.timingSafeEqual`), length-guarded
+ *      so a mismatched-length signature can never throw.
+ *   3. Rejects deliveries whose timestamp is outside the replay window.
+ *
+ * On success it returns the parsed, typed {@link WebhookEvent}. On ANY failure
+ * it throws {@link WebhookVerificationError} — and it never parses the body
+ * before the signature checks out.
+ *
+ * The constants below are vendored (not imported from `@traceten/shared`) so
+ * this SDK stays a self-contained, publishable package. They mirror the frozen
+ * signing spec exactly; the known-answer vector in the test suite proves this
+ * implementation is byte-identical to Traceten's signer.
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhook, WebhookVerificationError } from "@traceten/sdk-node";
+ *
+ * // Express — note `express.raw`, so `req.body` is the exact bytes we signed.
+ * app.post("/traceten-webhooks", express.raw({ type: "application/json" }), (req, res) => {
+ *   try {
+ *     const event = verifyWebhook(
+ *       req.body, // Buffer or string of the RAW body
+ *       req.header("X-Traceten-Signature") ?? "",
+ *       req.header("X-Traceten-Signature-Timestamp") ?? "",
+ *       process.env.TRACETEN_WEBHOOK_SECRET!,
+ *     );
+ *     if (event.type === "ai_session.classified") {
+ *       // event.data is fully typed here
+ *     }
+ *     res.status(200).end(); // ack fast; do heavy work on a queue
+ *   } catch (err) {
+ *     if (err instanceof WebhookVerificationError) res.status(401).end();
+ *     else res.status(400).end();
+ *   }
+ * });
+ * ```
+ */
+/** Header carrying the hex HMAC-SHA256 signature. */
+export declare const WEBHOOK_SIGNATURE_HEADER: "X-Traceten-Signature";
+/** Header carrying the unix-SECONDS timestamp that was signed over. */
+export declare const WEBHOOK_TIMESTAMP_HEADER: "X-Traceten-Signature-Timestamp";
+/** Default replay tolerance for verification, in seconds (5 minutes). */
+export declare const WEBHOOK_REPLAY_TOLERANCE_SECONDS = 300;
+/**
+ * The exhaustive allow-list of outbound webhook event types (frozen contract).
+ * Adding a type is additive-only.
+ */
+export declare const WEBHOOK_EVENT_TYPES: readonly ["ai_session.classified", "conversion.attributed", "webhook.ping"];
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+/** Attribution model names carried in `conversion.attributed`. */
+export declare const ATTRIBUTION_MODELS: readonly ["first_touch", "last_touch", "linear", "time_decay"];
+export type AttributionModel = (typeof ATTRIBUTION_MODELS)[number];
+/**
+ * `ai_session.classified` `data` — a stable projection of an AI-classified
+ * session. Actual PII (`ip_hash`, `user_agent`, `referrer`, `asn`) is never
+ * sent; `url` is reduced to origin + path so query-string PII cannot ride along.
+ */
+export interface AiSessionClassifiedData {
+    /** Edge-assigned event ID. */
+    event_id: string;
+    /** Customer site key (the public `ttid_…` snippet key). */
+    site_id: string;
+    /** Browser-session identifier. */
+    session_id: string;
+    /** Persistent visitor identifier. */
+    visitor_id: string;
+    /** Page URL, reduced to origin + path (no query string or fragment). */
+    url: string;
+    /** Canonical AI source name, e.g. `"ChatGPT"`. */
+    ai_source: string;
+    /** Confidence in `[0.0, 1.0]`. */
+    ai_confidence: number;
+    /** Detection method that produced the classification. */
+    detection_method: string;
+    /** ISO 3166-1 alpha-2 country code; `null` when unavailable. */
+    country: string | null;
+    /** ISO-8601 UTC timestamp of the event. */
+    timestamp: string;
+}
+/** One entry in `conversion.attributed`'s `data.models[]`. */
+export interface AttributionModelBreakdown {
+    /** Attribution model this slice belongs to. */
+    model: AttributionModel;
+    /** Fraction of conversion credit assigned to the AI source, `[0.0, 1.0]`. */
+    credit_fraction: number;
+    /**
+     * Revenue attributed under this model, in integer minor units of the
+     * conversion currency. `null` when the conversion carries no money.
+     */
+    revenue_cents_attributed: number | null;
+}
+/**
+ * `conversion.attributed` `data` — a stable projection of an AI-attributed
+ * conversion, for any goal (not purchases only). The optional revenue block
+ * (`revenue_cents_attributed` + `currency`) is present ONLY for money-carrying
+ * conversions; for a non-purchase goal both are absent (never a fake `$0`).
+ * Excludes all PII (no email, no `ip_hash`).
+ */
+export interface ConversionAttributedData {
+    /** Unique conversion event ID. */
+    conversion_id: string;
+    /** Customer site key (the public `ttid_…` snippet key). */
+    site_id: string;
+    /** Browser-session token credited under the canonical (last-touch) model. */
+    session_id: string;
+    /** Canonical AI source name for the credited session. */
+    ai_source: string;
+    /** Custom goal / event name, e.g. `"purchase"`, `"signup"`. */
+    event_name: string;
+    /** Canonical attribution model for the top-level fields (last-touch in v1). */
+    attribution_model: AttributionModel;
+    /** Canonical-model credit fraction for the AI source, `[0.0, 1.0]`. */
+    credit_fraction: number;
+    /** Revenue under the canonical model, minor units. Present only with money. */
+    revenue_cents_attributed?: number;
+    /** ISO 4217 currency code, UPPERCASE. Present only with revenue. */
+    currency?: string;
+    /** Full four-model attribution breakdown. */
+    models: AttributionModelBreakdown[];
+    /** ISO-8601 UTC timestamp of the conversion. */
+    timestamp: string;
+}
+/** `webhook.ping` `data` — the test/verification event. */
+export interface WebhookPingData {
+    /** Site the ping was triggered for. */
+    site_id: string;
+    /** Human-readable confirmation message. */
+    message: string;
+}
+/** Fields common to every webhook envelope. */
+interface WebhookEnvelopeBase {
+    /** Delivery id — unique per attempt-group (stable across retries). */
+    id: string;
+    /** Date-stamped contract version, e.g. `"2026-07-01"`. */
+    api_version: string;
+    /** Envelope creation time, unix MILLISECONDS. */
+    created: number;
+}
+/**
+ * A verified outbound webhook, discriminated on `type` so `data` narrows to the
+ * matching projection.
+ */
+export type WebhookEvent = (WebhookEnvelopeBase & {
+    type: "ai_session.classified";
+    data: AiSessionClassifiedData;
+}) | (WebhookEnvelopeBase & {
+    type: "conversion.attributed";
+    data: ConversionAttributedData;
+}) | (WebhookEnvelopeBase & {
+    type: "webhook.ping";
+    data: WebhookPingData;
+});
+/** Options for {@link verifyWebhook}. */
+export interface VerifyWebhookOptions {
+    /**
+     * Replay tolerance in seconds — the signature timestamp must be within
+     * `± toleranceSeconds` of `now`. Pass `Infinity` to skip the freshness check
+     * (do this only when testing against the fixed conformance vector). Defaults
+     * to {@link WEBHOOK_REPLAY_TOLERANCE_SECONDS}.
+     */
+    toleranceSeconds?: number;
+    /** Current unix SECONDS. Injectable for tests. Defaults to `Date.now()/1000`. */
+    nowSeconds?: number;
+}
+/**
+ * Thrown by {@link verifyWebhook} when a delivery cannot be trusted: a bad or
+ * missing signature, a stale/invalid timestamp, or a body that is not the JSON
+ * envelope we signed. Never thrown for a valid, fresh delivery.
+ */
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify an outbound Traceten webhook and return its typed envelope.
+ *
+ * @param rawBody          The EXACT raw request body — a `Buffer` (preferred)
+ *                         or the raw UTF-8 string. Never a re-serialized object;
+ *                         re-serializing changes the bytes and the signature
+ *                         will not match.
+ * @param signatureHeader  The `X-Traceten-Signature` header value.
+ * @param timestampHeader  The `X-Traceten-Signature-Timestamp` header value
+ *                         (unix seconds).
+ * @param secret           The endpoint's signing secret (raw UTF-8 string).
+ * @param options          {@link VerifyWebhookOptions}.
+ * @returns The verified, parsed {@link WebhookEvent}.
+ * @throws {WebhookVerificationError} on any verification or parse failure.
+ * @throws {TypeError} if `secret` is empty or blank — a misconfiguration (e.g.
+ *   an unset `TRACETEN_WEBHOOK_SECRET`), surfaced loudly rather than silently
+ *   weakening verification. This is a config bug, not a bad delivery, so it is
+ *   deliberately NOT a {@link WebhookVerificationError}.
+ */
+export declare function verifyWebhook(rawBody: Buffer | string, signatureHeader: string, timestampHeader: string, secret: string, options?: VerifyWebhookOptions): WebhookEvent;
+export {};
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

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