@traceten/sdk-node 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - Unreleased
+
+First stable release.
+
+### Added
+
+- `Client` with `page()`, `track()` and `payment()`, buffered delivery with batching and retry.
+- `flush()` / `close()` for explicit and shutdown-time delivery.
+- Webhook signature-verification helpers.
+- Required `apiKey`, sent as `Authorization: Bearer` on every request. It buys an
+  ingestion quota isolated from the shared per-site one.
+- `host` must use `https` off-loopback: the key rides every request, so plaintext
+  http would put a live credential on the wire.
+- `payment()` accepts optional `settlementAmount`/`settlementCurrency` — the
+  provider's own conversion, used by Traceten only as a fallback when `currency`
+  isn't one it can price on its own. Send both or neither.

package/LICENSE

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

package/README.md

@@ -0,0 +1,312 @@
+<img src="https://traceten.com/logos/traceten-wordmark-black.png" alt="Traceten" width="320" />
+
+# @traceten/sdk-node
+
+[![npm version](https://img.shields.io/npm/v/@traceten/sdk-node.svg)](https://www.npmjs.com/package/@traceten/sdk-node)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+The Traceten server-side SDK for Node.js. Send AI-traffic pageviews and revenue
+events from your backend over authenticated, ad-blocker-resistant HTTP.
+
+Use this when the browser snippet cannot run: server-rendered flows, webhooks,
+mobile/API backends, or when you want delivery that ad-blockers and privacy
+browsers cannot strip.
+
+## Install
+
+```bash
+npm install @traceten/sdk-node
+# or: pnpm add @traceten/sdk-node
+# or: yarn add @traceten/sdk-node
+```
+
+Node 18 or newer. The only runtime dependency is `undici`.
+
+## Quickstart
+
+```ts
+import { Client } from "@traceten/sdk-node";
+
+const traceten = new Client({
+  siteId: "ttid_7Rb4TrC1dTbnD8w3s1TS12", // your site key, from the dashboard's install page
+  host: "https://ingest.traceten.com",
+  // Required. A secret: load it from your environment, never hardcode it.
+  apiKey: process.env.TRACETEN_API_KEY!,
+});
+
+// A pageview. visitorId comes from your own request context (a cookie you set,
+// a user id, etc.) — the server has no Traceten cookie to read.
+traceten.page({
+  url: "https://acme.com/pricing",
+  referrer: "https://chat.openai.com/",
+  visitorId: "123e4567-e89b-42d3-a456-426614174000",
+});
+
+// A conversion. visitorId is required so the revenue can be attributed.
+traceten.track("subscription_started", {
+  visitorId: "123e4567-e89b-42d3-a456-426614174000",
+  valueCents: 4900,
+  currency: "usd",
+});
+
+// Flush and stop the background timer on shutdown.
+await traceten.close();
+```
+
+`page()` and `track()` return immediately. They buffer the event and send it in
+the background. They never throw on network problems, they throw only on
+programmer errors (a bad URL, a missing `visitorId`, a malformed event name).
+
+## The API key
+
+`apiKey` is required. Create a key in the dashboard under **Settings -> API
+keys**, or use the key shown once when you created the site.
+
+Keep it on your server. It is a secret: never put it in client-side code, a
+mobile app, or a public repository. It is not the same value as `siteId`, which
+is public and already embedded in your pages.
+
+The key does two things:
+
+- **Gets you in.** The SDK posts to the authenticated ingestion endpoints, which
+  return `401` without a valid key.
+- **Gets you your own quota.** Authenticated traffic is rate-limited on a bucket
+  tied to the key, separate from the shared per-site bucket. `siteId` is public,
+  so anyone who can read your page source can send events under it. With a key,
+  that traffic cannot exhaust your allowance and 429 your conversion calls.
+
+The client validates the key's shape when you construct it and throws if it is
+missing or malformed. An integration that silently drops every event is worse
+than one that fails on its first line.
+
+### Permissions
+
+A key carries a set of permissions that decide which endpoints it can reach.
+This SDK sends to `/v1/server/*`, which requires **`ingest:write`**. Tick that
+permission when you create the key.
+
+The client cannot check this for you. Permissions live on the server and the key
+looks identical either way, so a key without `ingest:write` is rejected with the
+same `401` as an invalid one.
+
+Grant only what you need. A key used solely for server-side ingestion does not
+need permission to read your analytics or erase visitor data, and if it leaks it
+cannot do either.
+
+To rotate a key: create the new one, deploy it, then revoke the old one.
+Revocation normally takes effect within about a minute. If our database is
+unreachable at that moment, an edge location that was already using the key may
+keep honouring it for up to about fifteen minutes more, so that a database blip
+cannot silently drop your events.
+
+## Identifiers
+
+Because it runs on your server, the SDK has no cookie and no DOM. You supply
+`visitorId` (and optionally `sessionId`) from your own request context. A
+`visitorId` is either a UUID or an `h:<64-hex>` identify hash. The SDK never
+fabricates one.
+
+The robust way to get this value is `window.traceten.getVisitorId()`, called
+client-side and forwarded to your backend (a form field, a fetch body, a
+header) — it always resolves the current cookie, so it keeps working if a
+customer turns cross-subdomain cookies on or off later. If you read the
+cookie by name instead, its name depends on the site's cookie scope:
+cross-subdomain cookies are off by default, giving plain `_traceten_vid`;
+once a customer enables it, the cookie becomes `_traceten_vid_` followed by
+eight characters of the site key. The install page shows the exact current
+name. Read that name exactly, never by prefix: two Traceten sites under one
+registered domain each set their own cookie, and a prefix match picks
+whichever the browser happens to list first, which merges two visitors the
+suffix exists to keep apart. If a request carries no such value, send the
+event without a `visitorId` rather than inventing one.
+
+## API
+
+### `new Client(options)`
+
+| Option          | Type                    | Default    | Notes                                                        |
+| --------------- | ----------------------- | ---------- | ------------------------------------------------------------ |
+| `siteId`        | `string`                | (required) | Your site key (`ttid_…`, case-sensitive) from the dashboard's install page. 1-64 chars, `A-Z a-z 0-9 _ -`. |
+| `host`          | `string`                | (required) | Ingest base URL. Absolute `https` (http on loopback only).    |
+| `apiKey`        | `string`                | (required) | Secret key, sent as `Authorization: Bearer`. See below.       |
+| `flushAt`       | `number`                | `50`       | Flush the events queue at this size. Clamped to `[1, 50]`.   |
+| `flushInterval` | `number`                | `5000`     | Background flush cadence in ms.                              |
+| `maxRetries`    | `number`                | `3`        | Retry attempts on 5xx / 429 / network error.                 |
+| `timeoutMs`     | `number`                | `10000`    | Per-request timeout in ms.                                   |
+| `onError`       | `(err: Error) => void`  | -          | Called when a batch is permanently dropped.                  |
+| `flushOnExit`   | `boolean`               | `true`     | Register best-effort flush on `beforeExit`/`SIGTERM`/`SIGINT`.|
+
+### `page(props)`
+
+| Prop        | Type             | Default      | Notes                                    |
+| ----------- | ---------------- | ------------ | ---------------------------------------- |
+| `url`       | `string`         | (required)   | Valid URL, up to 2048 chars.             |
+| `referrer`  | `string`         | `""`         |                                          |
+| `visitorId` | `string`         | -            | UUID or `h:<hash>`.                       |
+| `sessionId` | `string`         | -            |                                          |
+| `userAgent` | `string`         | -            | The end user's User-Agent, if you know it.|
+| `eventName` | `string`         | `"pageview"` | Must match `^[a-z][a-z0-9_-]*$`.         |
+| `timestamp` | `Date \| string` | now          |                                          |
+
+The `userAgent` you pass is what gets recorded as the visitor's user agent.
+Omit it and the event falls back to the `User-Agent` this SDK's HTTP client
+sent, which describes your server, not the visitor. User agent is an input to
+Traceten's traffic classification, so passing the real one materially improves
+your results.
+
+### `track(name, opts)`
+
+`name` must match `^[a-z][a-z0-9_]*$` (no hyphen).
+
+| Option       | Type             | Default    | Notes                                             |
+| ------------ | ---------------- | ---------- | ------------------------------------------------- |
+| `visitorId`  | `string`         | (required) | UUID or `h:<hash>`. Required to attribute revenue.|
+| `properties` | `object`         | `{}`       | Arbitrary JSON.                                   |
+| `valueCents` | `number`         | -          | Non-negative integer, minor units. -> `value_cents`.|
+| `currency`   | `string`         | -          | ISO-4217, lowercased on send.                     |
+| `sessionId`  | `string`         | -          |                                                   |
+| `timestamp`  | `Date \| string` | now        |                                                   |
+
+### `goal(name, opts)`
+
+Records a goal completion. Same arguments and same endpoint as `track()`, with
+one difference: the reserved names below are rejected.
+
+```ts
+traceten.goal("demo_booked", {
+  visitorId: "123e4567-e89b-42d3-a456-426614174000",
+  properties: { plan: "pro" },
+});
+```
+
+A goal is a custom event. `goal("demo_booked", ...)` and
+`track("demo_booked", ...)` send exactly the same payload, and the goal is
+listed by `GET /v1/goals` either way. Use `goal()` when the event is something
+you want to count and put in a funnel, and `track()` when you are recording
+revenue.
+
+**Reserved names.** These belong to the Stripe and Shopify integrations, which
+emit them for real subscription and payment events. `goal()` throws on them, so
+a name collision cannot quietly corrupt your revenue funnel:
+
+`payment`, `free_trial`, `trial_started`, `trial_converted`,
+`subscription_started`, `subscription_upgraded`, `subscription_downgraded`,
+`subscription_renewed`, `subscription_cancel_scheduled`,
+`subscription_reactivated`, `subscription_ended`.
+
+`track()` still accepts them, because that is how those events are legitimately
+sent.
+
+**Whitespace is not trimmed.** `goal(" signup ")` throws. The browser snippet
+trims a name read from an HTML attribute, because attribute values pick up
+whitespace from how the page is formatted; a name written in server code does
+not, so a stray space is a bug worth surfacing rather than quietly fixing.
+
+**Property keys and values are both stored, and both are readable back.**
+`GET /v1/goals/{name}/properties` returns every property key sent with a goal
+and that key's most common values. Do not put an email address, a person's name,
+or a postal address in either half of a property.
+
+Ingestion drops a property whose key is exactly `email`, `phone`, `name`,
+`password`, `token`, `ssn`, `credit_card` or `card_number`, and redacts email,
+phone, card and national-ID patterns inside string values. It has no pattern
+for a personal name or a street address, and it does not scan keys at all, so
+`{"full_name": "Alice Chen"}` is stored and returned exactly as sent.
+
+### `payment(props): Promise<PaymentResult>`
+
+Records a payment from ANY payment processor (`POST /v1/server/payments`). The
+only method here that sends immediately and reports a delivery failure to the
+caller: a dropped pageview is a dropped pageview, a dropped payment is missing
+revenue.
+
+```ts
+const res = await traceten.payment({
+  transactionId: "pay_9fK2mQ", // required — the processor's id. Idempotency key.
+  amount: 49.99, // required — MAJOR unit, not cents
+  currency: "USD", // required — ISO-4217, sent uppercase
+  provider: "dodo", // optional — your label. Defaults to "api".
+  email: "ada@example.com", // optional — hashed server-side, never stored
+  visitorId, // optional — a stronger match than the email
+  customerId: "cus_123", // optional
+  renewal: false, // optional
+  refunded: false, // optional — never send a negative amount
+  isFreeTrial: false, // optional — implied by amount: 0
+  settlementAmount: 45.50, // optional — your processor's own converted figure
+  settlementCurrency: "USD", // optional — must be set together with settlementAmount
+});
+
+res.status; // "recorded" | "trial" | "refunded" | "duplicate"
+```
+
+`amount` is the MAJOR unit, the opposite of `track()`'s `valueCents`: `49.99`
+for $49.99, `5000` for ¥5000.
+
+`settlementAmount`/`settlementCurrency` are a fallback for when `currency`
+isn't one Traceten can price natively (the ~30 ECB-published codes): your
+processor's own conversion of the payment into a currency it can price, so
+the payment isn't dropped. Set both or neither — sending one without the
+other causes the SDK to omit both.
+
+Re-posting the same `transactionId` returns `"duplicate"` and creates nothing,
+which is why a 5xx is retried here. It rejects on an invalid field and after
+every retry is exhausted.
+
+⚠️ Do NOT send payments here for a processor you have also connected natively.
+Traceten would record the payment twice and overstate your revenue.
+
+### `flush(): Promise<void>`
+
+Sends everything queued now. Resolves when every in-flight request settles.
+
+### `close(): Promise<void>` / `shutdown(): Promise<void>`
+
+Flushes, stops the background timer, and removes the exit hooks. Idempotent.
+After `close()`, `page()`, `track()` and `goal()` throw.
+
+## Delivery and retries
+
+- Pageviews go to `POST {host}/v1/server/events` in batch envelopes of up to 50.
+- Conversions go to `POST {host}/v1/server/conversions`, one body per event.
+- Every request carries `Authorization: Bearer <apiKey>`. Without a valid key
+  these endpoints return `401`.
+- On 5xx, 429, or a network/timeout error, the batch is retried with
+  exponential backoff and full jitter, up to `maxRetries`.
+- On any other 4xx the payload is malformed, so it is dropped and `onError` is
+  called. It is not retried.
+
+## Full docs
+
+See [API.md](./API.md) for the complete guide, or [docs.traceten.com/sdks/node](https://docs.traceten.com/sdks/node) for the hosted version.
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/). Before `1.0.0`,
+minor versions may include breaking changes — pin an exact version in production
+until then. See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## Contributing
+
+Issues and pull requests are welcome. For anything beyond a small fix, please
+open an issue first to discuss the change. Run the checks below before
+submitting a PR — CI enforces the same steps on every pull request:
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+```
+
+## License
+
+MIT © Traceten — see [LICENSE](./LICENSE).
+
+## Links
+
+- [Documentation](https://docs.traceten.com/sdks/node)
+- [Traceten](https://traceten.com) — AI traffic attribution for the AI search era
+- [Issues](https://github.com/traceten/sdk-node/issues)
+- [Changelog](./CHANGELOG.md)
+- [Python SDK](https://github.com/traceten/sdk-python) · [Go SDK](https://github.com/traceten/traceten-go) · [AI crawler tracking](https://github.com/traceten/ai-crawl)

package/dist/client.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 type { ClientOptions, PageProps, PaymentProps, PaymentResult, TrackOptions } from "./types.js";
+export declare class Client {
+    private readonly siteId;
+    private readonly host;
+    private readonly flushAt;
+    private readonly transport;
+    private readonly onError;
+    private events;
+    private conversions;
+    private timer;
+    private readonly inflight;
+    private exitHooks;
+    private closed;
+    constructor(options: ClientOptions);
+    /**
+     * 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: PageProps): void;
+    /**
+     * 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: string, opts: TrackOptions): void;
+    /**
+     * 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: string, opts: TrackOptions): void;
+    /**
+     * 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"
+     * ```
+     */
+    payment(props: PaymentProps): Promise<PaymentResult>;
+    /**
+     * Drain both queues now. Resolves once every in-flight request settles.
+     * Never rejects — delivery failures surface via `onError`.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush, stop the background timer, and remove exit hooks. Idempotent — safe
+     * to call more than once. After close, `page()`/`track()` throw.
+     */
+    close(): Promise<void>;
+    /** Alias for {@link Client.close} — matches the cross-language `shutdown()`. */
+    shutdown(): Promise<void>;
+    private assertOpen;
+    /** Trigger a flush when either queue has reached the flush threshold. */
+    private maybeFlush;
+    /** Track an in-flight send so `close()` can await it, then self-remove. */
+    private launch;
+    /**
+     * 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).
+     */
+    private registerExitHooks;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwBH,OAAO,KAAK,EACV,aAAa,EAIb,SAAS,EACT,YAAY,EACZ,aAAa,EAEb,YAAY,EACb,MAAM,YAAY,CAAC;AA8BpB,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,WAAW,CAAwB;IAE3C,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,aAAa;IAqDlC;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IA0B5B;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAoC7C;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAI5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IA8B1D;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB5B,gFAAgF;IAChF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMzB,OAAO,CAAC,UAAU;IAMlB,yEAAyE;IACzE,OAAO,CAAC,UAAU;IAMlB,2EAA2E;IAC3E,OAAO,CAAC,MAAM;IAQd;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;CAoB1B"}