npm - @kismet-tech/telemetry-node - Versions diffs - 1.0.0 - Mend

@kismet-tech/telemetry-node 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,15 @@
+# Changelog
+All notable changes to `@kismet-tech/telemetry-node`. Each entry names the tracking contract version the package conforms to.
+## 1.0.0 (unreleased)
+Conforms to contract 1.0, on `@kismet-tech/telemetry` ^1.0.0.
+- `kismetTelemetry(config)`: Express and Connect middleware doing the whole contract on every page request, with local mint plus after-response reconcile as the default, dotted-domain cookies, `private, no-store`, and the seed left on `req.kismet` and `res.locals.kismet` for the template. Works on the raw `node:http` request and response, so Fastify, Koa and a plain server use it too. A middleware error serves the page without telemetry.
+- `createKismetResolver(config)`: the same decision as a function of a web `Request`, for frameworks that apply headers themselves. `applyKismetDecision` and `toWebRequest` are the two halves the middleware is made of.
+- `kismetSeedHtml`: one inline script (seed, then the k.js tag appended by the script) for any template engine.
+- `readKismetState`, `bookingBridge`, `quoteCapture`.
+- `./client`: the browser helpers, re-exported from the core.
+- ESM and CommonJS builds.
+- Tests: the conformance suite through a real Express app on a real HTTP server behind forwarded headers, plus unit tests on the raw request and response.

package/README.md ADDED Viewed

@@ -0,0 +1,103 @@
+# @kismet-tech/telemetry-node
+Kismet Telemetry for Node servers. A thin adapter over [`@kismet-tech/telemetry`](../telemetry): the contract (version 1.0) is the core's; this package wires it to the `node:http` request and response, which is what Express, Connect, Fastify and Koa hand you.
+Docs: https://developers.kismet.travel/telemetry/node/
+## Install
+```bash
+npm install @kismet-tech/telemetry-node
+```
+Node 20 or later. ESM and CommonJS.
+Environment: `KISMET_COLLECTION_SLUG` and `KISMET_TRACKING_KEY` (the collection's `ctk_` key, server-side only).
+## Express
+```js
+import express from 'express';
+import { kismetTelemetry, consentFromCookie } from '@kismet-tech/telemetry-node';
+const app = express();
+app.use(
+  kismetTelemetry({
+    collectionSlug: process.env.KISMET_COLLECTION_SLUG,
+    trackingKey: process.env.KISMET_TRACKING_KEY,
+    consent: consentFromCookie('CookieConsent', /statistics:true/),
+    profile: {
+      property: { pattern: /^\/stays\/[^/]+\/([^/]+)\/?$/, as: 'externalListingId' },
+      searchPaths: ['/stays', /^\/stays\/in\//],
+      intent: { path: '/stays/checkout', checkinParam: 'checkin', checkoutParam: 'checkout', guestsParam: 'guests' },
+    },
+  })
+);
+app.get('/stays/:town/:house', (req, res) => {
+  res.render('property', { kismetSeed: res.locals.kismet?.seed ?? '' });
+});
+```
+In the template, print the seed first thing in `<head>`, unescaped:
+```html
+<head>
+  <%- kismetSeed %>
+  <title>...</title>
+</head>
+```
+Mount it before your routes and before any static middleware you want excluded (assets are excluded by the route profile anyway). Behind a reverse proxy, make sure it forwards `X-Forwarded-Host`, `X-Forwarded-Proto` and `X-Forwarded-For`; the adapter reads them to rebuild the public URL, decide `Secure`, and take the visitor's IP.
+## The checkout call
+```js
+import { bookingBridge } from '@kismet-tech/telemetry-node';
+await bookingBridge(config, { kidSid, confirmationCode, bookingEngine: 'custom', domain: 'example.co.uk' });
+```
+`kidSid` is the `_kid_sid` cookie on the checkout request (`req.kismet.kidSid` on any page request); carry it through your booking pipeline to wherever the confirmation code is known. Bounded, never throws, must not affect the booking.
+## Fastify, Koa, plain node:http
+The middleware only needs the raw request and response.
+```js
+// Fastify
+fastify.addHook('onRequest', (request, reply, done) => middleware(request.raw, reply.raw, done));
+// then request.raw.kismet.seed in the handler
+// Koa
+app.use((ctx, next) => new Promise((r) => middleware(ctx.req, ctx.res, r)).then(next));
+// then ctx.req.kismet.seed
+// node:http
+createServer((req, res) => middleware(req, res, () => render(req, res)));
+```
+## Frameworks that speak Request and Response
+`createKismetResolver(config).resolve(request)` returns the decision (state, headers, Set-Cookie lines) without applying it, for Hono, Cloudflare Workers, Deno and similar. The core's reference adapter is the worked example for the same shape.
+## Browser signals
+```js
+import { createTracker } from '@kismet-tech/telemetry-node/client';
+const track = createTracker({ collectionSlug: 'your-collection' });
+track.propertyView({ externalListingId: listing.id, checkIn, checkOut, guests, stayTotalCents });
+track.save({ externalListingId: listing.id });
+track.bookIntent({ externalListingId: listing.id, checkIn, checkOut, guests, stayTotalCents });
+```
+## What the middleware does on every page request
+Resolves the visitor (threaded id, cookie, suppressed for bots and visitors without consent, else a locally minted id reconciled with Kismet after the response), emits one server-plane event (agent surfaces as `fetch` with no identity), sets `_kid_sid` and `_kid_vid` on the dotted serving domain, marks the response `private, no-store`, and leaves `{ kidSid, suppressed, tier, classification, seed }` on `req.kismet` and `res.locals.kismet`. The page never waits on Kismet, and a middleware error serves the page without telemetry rather than failing it.
+Caching: a page that prints the seed is per visitor and is marked `private, no-store` for that reason. If you serve HTML from a shared cache, do not print the seed into it; use the cache-safe bootstrap pattern in the contract (section 7) instead.
+## Conformance
+`npm test` builds the package and runs it through the contract's conformance suite as a real Express app on a real HTTP server behind forwarded headers, plus unit tests on the raw request and response.

package/dist/cjs/client.js ADDED Viewed

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postBookingBridgeFromBrowser = exports.emitVisitorEvent = exports.currentKidSid = exports.createTracker = void 0;
+// Browser helpers, re-exported from the core so a Node app imports one package.
+//   import { createTracker } from '@kismet-tech/telemetry-node/client';
+var client_1 = require("@kismet-tech/telemetry/client");
+Object.defineProperty(exports, "createTracker", { enumerable: true, get: function () { return client_1.createTracker; } });
+Object.defineProperty(exports, "currentKidSid", { enumerable: true, get: function () { return client_1.currentKidSid; } });
+Object.defineProperty(exports, "emitVisitorEvent", { enumerable: true, get: function () { return client_1.emitVisitorEvent; } });
+Object.defineProperty(exports, "postBookingBridgeFromBrowser", { enumerable: true, get: function () { return client_1.postBookingBridgeFromBrowser; } });

package/dist/cjs/index.js ADDED Viewed

@@ -0,0 +1,252 @@
+"use strict";
+// @kismet-tech/telemetry-node: the Node server adapter over @kismet-tech/telemetry.
+//
+// kismetTelemetry(config) returns an Express or Connect middleware (req, res, next)
+// that does the whole contract on every page request: resolve the visitor
+// (threaded, cookie, suppressed, cold with a local mint and an after-response
+// reconcile), emit the server-plane event, set the first-party cookies on the
+// dotted serving domain, mark the response private, and leave the seed on
+// `req.kismet` and `res.locals.kismet` for the template. It works on the raw
+// node:http request and response, so Fastify (`req.raw`, `reply.raw`), Koa
+// (`ctx.req`, `ctx.res`) and a plain `createServer` handler use it too.
+//
+// resolveKismetRequest(config) is the same decision as a function of a web
+// `Request`, for frameworks that speak Request and Response (Hono, Workers,
+// Deno) and want to apply the headers themselves.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEED_HEADERS = exports.countryAllowsCookies = exports.consentFromCookie = exports.CONTRACT_VERSION = void 0;
+exports.kismetSeedHtml = kismetSeedHtml;
+exports.createKismetResolver = createKismetResolver;
+exports.toWebRequest = toWebRequest;
+exports.applyKismetDecision = applyKismetDecision;
+exports.kismetTelemetry = kismetTelemetry;
+exports.readKismetState = readKismetState;
+exports.bookingBridge = bookingBridge;
+exports.quoteCapture = quoteCapture;
+const telemetry_1 = require("@kismet-tech/telemetry");
+exports.CONTRACT_VERSION = '1.0';
+function eventEnv(cfg) {
+    return {
+        COLLECTION_KEY: cfg.trackingKey,
+        ...(cfg.endpoints?.track ? { TRACKING_ENDPOINT: cfg.endpoints.track } : {}),
+    };
+}
+function apiEnv(cfg) {
+    return {
+        COLLECTION_KEY: cfg.trackingKey,
+        ...(cfg.endpoints?.apiOrigin ? { KISMET_API_ORIGIN: cfg.endpoints.apiOrigin } : {}),
+    };
+}
+/**
+ * The seed as one inline script: the assignment, then the k.js tag appended by
+ * the script itself, so no template engine or renderer can reorder them
+ * (contract section 7). Empty when there is neither an id nor a suppression.
+ */
+function kismetSeedHtml(input, collectionSlug, kjsUrl) {
+    const seed = (0, telemetry_1.renderSeedScript)({ kidSid: input.kidSid, suppressed: input.suppressed });
+    if (!seed)
+        return '';
+    const assignment = seed.replace(/^<script>/, '').replace(/<\/script>$/, '');
+    const src = `${kjsUrl || telemetry_1.DEFAULT_KJS_URL}?c=${encodeURIComponent(collectionSlug)}`;
+    return ('<script>' +
+        assignment +
+        `(function(){var s=document.createElement('script');s.async=true;s.src=${JSON.stringify(src)};` +
+        `(document.head||document.documentElement).appendChild(s);})();` +
+        '</script>');
+}
+/**
+ * The contract as a function of a web `Request`. Returns what to do with the
+ * response; applies nothing itself. `flush()` awaits the background work
+ * (reconcile, events), for tests and for graceful shutdown.
+ */
+function createKismetResolver(cfg) {
+    if (!cfg.collectionSlug)
+        throw new Error('@kismet-tech/telemetry-node: collectionSlug is required');
+    if (!cfg.trackingKey) {
+        console.warn('[kismet-telemetry] trackingKey is empty: sessions resolve locally, nothing is sent to Kismet');
+    }
+    let pending = [];
+    const ctx = {
+        waitUntil(p) {
+            const tracked = Promise.resolve(p).catch(() => undefined);
+            pending.push(tracked);
+            void tracked.then(() => {
+                pending = pending.filter((x) => x !== tracked);
+            });
+        },
+    };
+    const env = eventEnv(cfg);
+    async function resolve(request) {
+        const headers = request.headers;
+        const url = (0, telemetry_1.publicUrl)(headers, new URL(request.url));
+        const classification = (0, telemetry_1.classifyRequest)(url, cfg.profile, {
+            accept: headers.get('accept'),
+            method: request.method,
+        });
+        if (classification.kind === 'excluded')
+            return { kind: 'excluded' };
+        const country = cfg.country ? (cfg.country(headers) ?? null) : (0, telemetry_1.readCountry)(headers);
+        const common = {
+            pageUrl: url.toString(),
+            domain: (0, telemetry_1.normalizeServingDomain)(url.host),
+            collectionSlug: cfg.collectionSlug,
+            userAgent: headers.get('user-agent'),
+            clientIp: (0, telemetry_1.visitorIp)(headers),
+            country,
+            referrer: headers.get('referer'),
+        };
+        if (classification.kind === 'agent') {
+            (0, telemetry_1.fireContentEvent)(ctx, env, {
+                ...common,
+                vrSlug: null,
+                clientSessionId: null,
+                agentFetch: true,
+            });
+            return { kind: 'agent' };
+        }
+        const resolved = await (0, telemetry_1.resolveVisitor)({
+            url,
+            headers,
+            collectionSlug: cfg.collectionSlug,
+            trackingKey: cfg.trackingKey,
+            consent: cfg.consent ?? null,
+            country,
+            authorityFirst: cfg.authorityFirst,
+            suppressGenericClients: cfg.suppressGenericClients,
+            resolveEndpoint: cfg.endpoints?.resolveAnchor ?? null,
+            apiOrigin: cfg.endpoints?.apiOrigin ?? null,
+            waitUntil: ctx.waitUntil,
+        });
+        const visitor = { ...resolved, classification };
+        (0, telemetry_1.fireContentEvent)(ctx, env, {
+            ...common,
+            vrSlug: classification.vrSlug,
+            ...(classification.externalListingId
+                ? { externalListingId: classification.externalListingId }
+                : {}),
+            clientSessionId: visitor.isBot ? null : visitor.kidSid,
+            ctaIntent: classification.kind === 'intent',
+            stayCheckIn: classification.stayCheckIn,
+            stayCheckOut: classification.stayCheckOut,
+            guestCount: classification.guestCount,
+            promoCode: classification.promoCode,
+        });
+        const state = {
+            kidSid: visitor.kidSid,
+            kidVid: visitor.kidVid,
+            suppressed: visitor.suppressed,
+            isBot: visitor.isBot,
+            tier: visitor.tier,
+            classification,
+            seed: kismetSeedHtml(visitor, cfg.collectionSlug, cfg.endpoints?.kjs),
+        };
+        // A response that carries a per-visitor seed must never be cached by a shared cache.
+        const outHeaders = {
+            'cache-control': 'private, no-store',
+            [telemetry_1.SEED_HEADERS.tier]: visitor.tier,
+        };
+        const domain = (0, telemetry_1.cookieDomainFor)(url.host, cfg.cookieDomain ?? null);
+        const secure = (0, telemetry_1.isHttps)(headers, url);
+        const setCookies = [];
+        if (visitor.kidSid && visitor.setSid) {
+            setCookies.push((0, telemetry_1.buildCookie)(telemetry_1.SID_COOKIE, visitor.kidSid, { maxAge: telemetry_1.SID_MAX_AGE, domain, secure }));
+        }
+        if (visitor.kidVid && visitor.setVid) {
+            setCookies.push((0, telemetry_1.buildCookie)(telemetry_1.VID_COOKIE, visitor.kidVid, { maxAge: telemetry_1.VID_MAX_AGE, domain, secure }));
+        }
+        return { kind: 'page', visitor, state, headers: outHeaders, setCookies };
+    }
+    async function flush() {
+        while (pending.length) {
+            const p = pending;
+            pending = [];
+            await Promise.allSettled(p);
+        }
+    }
+    return { resolve, flush };
+}
+/** Build a web `Request` from a Node request, with the public URL rebuilt from forwarded headers. */
+function toWebRequest(req) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+    }
+    const socket = req.socket;
+    const scheme = socket?.encrypted ? 'https' : 'http';
+    const host = headers.get('host') || 'localhost';
+    const path = req.originalUrl || req.url || '/';
+    return new Request(new URL(path, `${scheme}://${host}`), {
+        method: req.method || 'GET',
+        headers,
+    });
+}
+/** Apply a page decision to a Node response and stash the state on the request. */
+function applyKismetDecision(req, res, decision) {
+    if (decision.kind !== 'page')
+        return;
+    req.kismet = decision.state;
+    if (res.locals && typeof res.locals === 'object')
+        res.locals.kismet = decision.state;
+    for (const [name, value] of Object.entries(decision.headers))
+        res.setHeader(name, value);
+    if (decision.setCookies.length) {
+        const prev = res.getHeader('set-cookie');
+        const existing = Array.isArray(prev) ? prev : typeof prev === 'string' ? [prev] : [];
+        res.setHeader('Set-Cookie', [...existing, ...decision.setCookies]);
+    }
+}
+/**
+ * Build the middleware. `app.use(kismetTelemetry(config))` before your routes;
+ * then print `res.locals.kismet.seed` (or `req.kismet.seed`) in `<head>`.
+ */
+function kismetTelemetry(cfg) {
+    const resolver = createKismetResolver(cfg);
+    const middleware = function kismetTelemetryMiddleware(req, res, next) {
+        let request;
+        try {
+            request = toWebRequest(req);
+        }
+        catch (err) {
+            warn(err);
+            next();
+            return;
+        }
+        resolver.resolve(request).then((decision) => {
+            try {
+                applyKismetDecision(req, res, decision);
+            }
+            catch (err) {
+                warn(err);
+            }
+            next();
+        }, (err) => {
+            // The page is always served. Telemetry degrades to "nothing on this request".
+            warn(err);
+            next();
+        });
+    };
+    middleware.flush = resolver.flush;
+    middleware.resolve = resolver.resolve;
+    return middleware;
+}
+function warn(err) {
+    console.warn('[kismet-telemetry] middleware error, serving without telemetry:', err instanceof Error ? err.message : err);
+}
+/** Read the state the middleware attached, from a route handler or template helper. */
+function readKismetState(req) {
+    return req.kismet ?? null;
+}
+/** The conversion join, from the server code that knows the booking succeeded. */
+function bookingBridge(cfg, body) {
+    return (0, telemetry_1.postBookingBridge)(apiEnv(cfg), body);
+}
+/** A quote the guest saw, for the fallback match on property and dates. */
+function quoteCapture(cfg, body) {
+    return (0, telemetry_1.postQuoteCapture)(apiEnv(cfg), { collectionSlug: cfg.collectionSlug, ...body });
+}
+var telemetry_2 = require("@kismet-tech/telemetry");
+Object.defineProperty(exports, "consentFromCookie", { enumerable: true, get: function () { return telemetry_2.consentFromCookie; } });
+Object.defineProperty(exports, "countryAllowsCookies", { enumerable: true, get: function () { return telemetry_2.countryAllowsCookies; } });
+Object.defineProperty(exports, "SEED_HEADERS", { enumerable: true, get: function () { return telemetry_2.SEED_HEADERS; } });

package/dist/cjs/package.json ADDED Viewed

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/esm/client.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export { createTracker, currentKidSid, emitVisitorEvent, postBookingBridgeFromBrowser, } from '@kismet-tech/telemetry/client';

package/dist/esm/client.js ADDED Viewed

@@ -0,0 +1,3 @@
+// Browser helpers, re-exported from the core so a Node app imports one package.
+//   import { createTracker } from '@kismet-tech/telemetry-node/client';
+export { createTracker, currentKidSid, emitVisitorEvent, postBookingBridgeFromBrowser, } from '@kismet-tech/telemetry/client';

package/dist/esm/index.d.ts ADDED Viewed

@@ -0,0 +1,120 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { BookingBridgeBody, Classification, ConsentHook, ConversionResult, QuoteCaptureBody, ResolveResult, RouteProfile } from '@kismet-tech/telemetry';
+export declare const CONTRACT_VERSION = "1.0";
+export interface KismetTelemetryConfig {
+    /** The collection this site's pages belong to. */
+    collectionSlug: string;
+    /** The collection's `ctk_` tracking key. Server-side only; read it from the environment. */
+    trackingKey: string;
+    /** Which URLs are properties, search, the checkout path, agent surfaces. */
+    profile?: RouteProfile;
+    /**
+     * The site's consent decision. Without it the country default applies, which
+     * reads a Cloudflare or Vercel country header; a Node server behind Apache or
+     * nginx has neither, so the default would set cookies for everyone. Wire your
+     * consent manager here (`consentFromCookie` covers the common case).
+     */
+    consent?: ConsentHook | null;
+    /** Override the dotted-domain rule, e.g. '.example.com' for a deeper serving host. */
+    cookieDomain?: string | null;
+    /** Ask the authority before responding on a cold visit (1.5 s cap). Off by default. */
+    authorityFirst?: boolean;
+    /** Suppress generic clients (curl, headless browsers) as well as the bot vocabulary. Default true. */
+    suppressGenericClients?: boolean;
+    /**
+     * Your own country source when the platform sets one under a different header
+     * (a GeoIP module, a load balancer). Return null when unknown. Default reads
+     * `cf-ipcountry` then `x-vercel-ip-country`.
+     */
+    country?: (headers: Headers) => string | null | undefined;
+    /** Overrides for lab and staging. */
+    endpoints?: {
+        resolveAnchor?: string;
+        track?: string;
+        apiOrigin?: string;
+        kjs?: string;
+    };
+}
+export interface KismetVisitor extends ResolveResult {
+    /** What the request was classified as by the route profile. */
+    classification: Classification;
+}
+/** What the middleware leaves on `req.kismet` and `res.locals.kismet`. */
+export interface KismetRequestState {
+    kidSid: string | null;
+    kidVid: string | null;
+    suppressed: boolean;
+    isBot: boolean;
+    tier: string;
+    classification: Classification;
+    /**
+     * One inline `<script>` for `<head>`: the seed assignment, then the k.js tag
+     * appended by the script itself. Empty when there is nothing to seed. Print it
+     * verbatim before any other script in the head.
+     */
+    seed: string;
+}
+export type KismetDecision = {
+    kind: 'excluded';
+} | {
+    kind: 'agent';
+} | {
+    kind: 'page';
+    visitor: KismetVisitor;
+    state: KismetRequestState;
+    /** Response headers to set: cache-control, the tier header. */
+    headers: Record<string, string>;
+    /** Set-Cookie lines to append, zero to two. */
+    setCookies: string[];
+};
+/**
+ * The seed as one inline script: the assignment, then the k.js tag appended by
+ * the script itself, so no template engine or renderer can reorder them
+ * (contract section 7). Empty when there is neither an id nor a suppression.
+ */
+export declare function kismetSeedHtml(input: {
+    kidSid: string | null;
+    suppressed: boolean;
+}, collectionSlug: string, kjsUrl?: string): string;
+/**
+ * The contract as a function of a web `Request`. Returns what to do with the
+ * response; applies nothing itself. `flush()` awaits the background work
+ * (reconcile, events), for tests and for graceful shutdown.
+ */
+export declare function createKismetResolver(cfg: KismetTelemetryConfig): {
+    resolve: (request: Request) => Promise<KismetDecision>;
+    flush: () => Promise<void>;
+};
+/** The request the middleware accepts: node:http, Express, Connect, Fastify raw, Koa raw. */
+export type NodeRequest = IncomingMessage & {
+    originalUrl?: string;
+    kismet?: KismetRequestState;
+};
+export type NodeResponse = ServerResponse & {
+    locals?: Record<string, unknown>;
+};
+export type NextFunction = (err?: unknown) => void;
+/** Build a web `Request` from a Node request, with the public URL rebuilt from forwarded headers. */
+export declare function toWebRequest(req: NodeRequest): Request;
+/** Apply a page decision to a Node response and stash the state on the request. */
+export declare function applyKismetDecision(req: NodeRequest, res: NodeResponse, decision: KismetDecision): void;
+export interface KismetMiddleware {
+    (req: NodeRequest, res: NodeResponse, next: NextFunction): void;
+    /** Await background work (reconcile, events). For tests and graceful shutdown. */
+    flush(): Promise<void>;
+    /** The decision as a function of a web Request, for frameworks that apply headers themselves. */
+    resolve(request: Request): Promise<KismetDecision>;
+}
+/**
+ * Build the middleware. `app.use(kismetTelemetry(config))` before your routes;
+ * then print `res.locals.kismet.seed` (or `req.kismet.seed`) in `<head>`.
+ */
+export declare function kismetTelemetry(cfg: KismetTelemetryConfig): KismetMiddleware;
+/** Read the state the middleware attached, from a route handler or template helper. */
+export declare function readKismetState(req: NodeRequest): KismetRequestState | null;
+/** The conversion join, from the server code that knows the booking succeeded. */
+export declare function bookingBridge(cfg: KismetTelemetryConfig, body: BookingBridgeBody): Promise<ConversionResult>;
+/** A quote the guest saw, for the fallback match on property and dates. */
+export declare function quoteCapture(cfg: KismetTelemetryConfig, body: QuoteCaptureBody): Promise<ConversionResult>;
+export { consentFromCookie, countryAllowsCookies, SEED_HEADERS } from '@kismet-tech/telemetry';
+export type { RouteProfile, ConsentHook, Classification, BookingBridgeBody, QuoteCaptureBody, ConversionResult, } from '@kismet-tech/telemetry';

package/dist/esm/index.js ADDED Viewed

@@ -0,0 +1,238 @@
+// @kismet-tech/telemetry-node: the Node server adapter over @kismet-tech/telemetry.
+//
+// kismetTelemetry(config) returns an Express or Connect middleware (req, res, next)
+// that does the whole contract on every page request: resolve the visitor
+// (threaded, cookie, suppressed, cold with a local mint and an after-response
+// reconcile), emit the server-plane event, set the first-party cookies on the
+// dotted serving domain, mark the response private, and leave the seed on
+// `req.kismet` and `res.locals.kismet` for the template. It works on the raw
+// node:http request and response, so Fastify (`req.raw`, `reply.raw`), Koa
+// (`ctx.req`, `ctx.res`) and a plain `createServer` handler use it too.
+//
+// resolveKismetRequest(config) is the same decision as a function of a web
+// `Request`, for frameworks that speak Request and Response (Hono, Workers,
+// Deno) and want to apply the headers themselves.
+import { buildCookie, classifyRequest, cookieDomainFor, DEFAULT_KJS_URL, fireContentEvent, isHttps, normalizeServingDomain, postBookingBridge, postQuoteCapture, publicUrl, readCountry, renderSeedScript, resolveVisitor, SEED_HEADERS, SID_COOKIE, SID_MAX_AGE, VID_COOKIE, VID_MAX_AGE, visitorIp, } from '@kismet-tech/telemetry';
+export const CONTRACT_VERSION = '1.0';
+function eventEnv(cfg) {
+    return {
+        COLLECTION_KEY: cfg.trackingKey,
+        ...(cfg.endpoints?.track ? { TRACKING_ENDPOINT: cfg.endpoints.track } : {}),
+    };
+}
+function apiEnv(cfg) {
+    return {
+        COLLECTION_KEY: cfg.trackingKey,
+        ...(cfg.endpoints?.apiOrigin ? { KISMET_API_ORIGIN: cfg.endpoints.apiOrigin } : {}),
+    };
+}
+/**
+ * The seed as one inline script: the assignment, then the k.js tag appended by
+ * the script itself, so no template engine or renderer can reorder them
+ * (contract section 7). Empty when there is neither an id nor a suppression.
+ */
+export function kismetSeedHtml(input, collectionSlug, kjsUrl) {
+    const seed = renderSeedScript({ kidSid: input.kidSid, suppressed: input.suppressed });
+    if (!seed)
+        return '';
+    const assignment = seed.replace(/^<script>/, '').replace(/<\/script>$/, '');
+    const src = `${kjsUrl || DEFAULT_KJS_URL}?c=${encodeURIComponent(collectionSlug)}`;
+    return ('<script>' +
+        assignment +
+        `(function(){var s=document.createElement('script');s.async=true;s.src=${JSON.stringify(src)};` +
+        `(document.head||document.documentElement).appendChild(s);})();` +
+        '</script>');
+}
+/**
+ * The contract as a function of a web `Request`. Returns what to do with the
+ * response; applies nothing itself. `flush()` awaits the background work
+ * (reconcile, events), for tests and for graceful shutdown.
+ */
+export function createKismetResolver(cfg) {
+    if (!cfg.collectionSlug)
+        throw new Error('@kismet-tech/telemetry-node: collectionSlug is required');
+    if (!cfg.trackingKey) {
+        console.warn('[kismet-telemetry] trackingKey is empty: sessions resolve locally, nothing is sent to Kismet');
+    }
+    let pending = [];
+    const ctx = {
+        waitUntil(p) {
+            const tracked = Promise.resolve(p).catch(() => undefined);
+            pending.push(tracked);
+            void tracked.then(() => {
+                pending = pending.filter((x) => x !== tracked);
+            });
+        },
+    };
+    const env = eventEnv(cfg);
+    async function resolve(request) {
+        const headers = request.headers;
+        const url = publicUrl(headers, new URL(request.url));
+        const classification = classifyRequest(url, cfg.profile, {
+            accept: headers.get('accept'),
+            method: request.method,
+        });
+        if (classification.kind === 'excluded')
+            return { kind: 'excluded' };
+        const country = cfg.country ? (cfg.country(headers) ?? null) : readCountry(headers);
+        const common = {
+            pageUrl: url.toString(),
+            domain: normalizeServingDomain(url.host),
+            collectionSlug: cfg.collectionSlug,
+            userAgent: headers.get('user-agent'),
+            clientIp: visitorIp(headers),
+            country,
+            referrer: headers.get('referer'),
+        };
+        if (classification.kind === 'agent') {
+            fireContentEvent(ctx, env, {
+                ...common,
+                vrSlug: null,
+                clientSessionId: null,
+                agentFetch: true,
+            });
+            return { kind: 'agent' };
+        }
+        const resolved = await resolveVisitor({
+            url,
+            headers,
+            collectionSlug: cfg.collectionSlug,
+            trackingKey: cfg.trackingKey,
+            consent: cfg.consent ?? null,
+            country,
+            authorityFirst: cfg.authorityFirst,
+            suppressGenericClients: cfg.suppressGenericClients,
+            resolveEndpoint: cfg.endpoints?.resolveAnchor ?? null,
+            apiOrigin: cfg.endpoints?.apiOrigin ?? null,
+            waitUntil: ctx.waitUntil,
+        });
+        const visitor = { ...resolved, classification };
+        fireContentEvent(ctx, env, {
+            ...common,
+            vrSlug: classification.vrSlug,
+            ...(classification.externalListingId
+                ? { externalListingId: classification.externalListingId }
+                : {}),
+            clientSessionId: visitor.isBot ? null : visitor.kidSid,
+            ctaIntent: classification.kind === 'intent',
+            stayCheckIn: classification.stayCheckIn,
+            stayCheckOut: classification.stayCheckOut,
+            guestCount: classification.guestCount,
+            promoCode: classification.promoCode,
+        });
+        const state = {
+            kidSid: visitor.kidSid,
+            kidVid: visitor.kidVid,
+            suppressed: visitor.suppressed,
+            isBot: visitor.isBot,
+            tier: visitor.tier,
+            classification,
+            seed: kismetSeedHtml(visitor, cfg.collectionSlug, cfg.endpoints?.kjs),
+        };
+        // A response that carries a per-visitor seed must never be cached by a shared cache.
+        const outHeaders = {
+            'cache-control': 'private, no-store',
+            [SEED_HEADERS.tier]: visitor.tier,
+        };
+        const domain = cookieDomainFor(url.host, cfg.cookieDomain ?? null);
+        const secure = isHttps(headers, url);
+        const setCookies = [];
+        if (visitor.kidSid && visitor.setSid) {
+            setCookies.push(buildCookie(SID_COOKIE, visitor.kidSid, { maxAge: SID_MAX_AGE, domain, secure }));
+        }
+        if (visitor.kidVid && visitor.setVid) {
+            setCookies.push(buildCookie(VID_COOKIE, visitor.kidVid, { maxAge: VID_MAX_AGE, domain, secure }));
+        }
+        return { kind: 'page', visitor, state, headers: outHeaders, setCookies };
+    }
+    async function flush() {
+        while (pending.length) {
+            const p = pending;
+            pending = [];
+            await Promise.allSettled(p);
+        }
+    }
+    return { resolve, flush };
+}
+/** Build a web `Request` from a Node request, with the public URL rebuilt from forwarded headers. */
+export function toWebRequest(req) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+    }
+    const socket = req.socket;
+    const scheme = socket?.encrypted ? 'https' : 'http';
+    const host = headers.get('host') || 'localhost';
+    const path = req.originalUrl || req.url || '/';
+    return new Request(new URL(path, `${scheme}://${host}`), {
+        method: req.method || 'GET',
+        headers,
+    });
+}
+/** Apply a page decision to a Node response and stash the state on the request. */
+export function applyKismetDecision(req, res, decision) {
+    if (decision.kind !== 'page')
+        return;
+    req.kismet = decision.state;
+    if (res.locals && typeof res.locals === 'object')
+        res.locals.kismet = decision.state;
+    for (const [name, value] of Object.entries(decision.headers))
+        res.setHeader(name, value);
+    if (decision.setCookies.length) {
+        const prev = res.getHeader('set-cookie');
+        const existing = Array.isArray(prev) ? prev : typeof prev === 'string' ? [prev] : [];
+        res.setHeader('Set-Cookie', [...existing, ...decision.setCookies]);
+    }
+}
+/**
+ * Build the middleware. `app.use(kismetTelemetry(config))` before your routes;
+ * then print `res.locals.kismet.seed` (or `req.kismet.seed`) in `<head>`.
+ */
+export function kismetTelemetry(cfg) {
+    const resolver = createKismetResolver(cfg);
+    const middleware = function kismetTelemetryMiddleware(req, res, next) {
+        let request;
+        try {
+            request = toWebRequest(req);
+        }
+        catch (err) {
+            warn(err);
+            next();
+            return;
+        }
+        resolver.resolve(request).then((decision) => {
+            try {
+                applyKismetDecision(req, res, decision);
+            }
+            catch (err) {
+                warn(err);
+            }
+            next();
+        }, (err) => {
+            // The page is always served. Telemetry degrades to "nothing on this request".
+            warn(err);
+            next();
+        });
+    };
+    middleware.flush = resolver.flush;
+    middleware.resolve = resolver.resolve;
+    return middleware;
+}
+function warn(err) {
+    console.warn('[kismet-telemetry] middleware error, serving without telemetry:', err instanceof Error ? err.message : err);
+}
+/** Read the state the middleware attached, from a route handler or template helper. */
+export function readKismetState(req) {
+    return req.kismet ?? null;
+}
+/** The conversion join, from the server code that knows the booking succeeded. */
+export function bookingBridge(cfg, body) {
+    return postBookingBridge(apiEnv(cfg), body);
+}
+/** A quote the guest saw, for the fallback match on property and dates. */
+export function quoteCapture(cfg, body) {
+    return postQuoteCapture(apiEnv(cfg), { collectionSlug: cfg.collectionSlug, ...body });
+}
+export { consentFromCookie, countryAllowsCookies, SEED_HEADERS } from '@kismet-tech/telemetry';

package/package.json ADDED Viewed

@@ -0,0 +1,72 @@
+{
+  "name": "@kismet-tech/telemetry-node",
+  "version": "1.0.0",
+  "description": "Kismet Telemetry for Node servers: kismetTelemetry() Express and Connect middleware on the @kismet-tech/telemetry core (contract 1.0), the page seed for your template, booking-bridge and quote-capture helpers, and the browser helpers. Works with Express, Connect, Fastify (raw request and reply), Koa and plain node:http. Ships with the contract conformance suite.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./client": {
+      "types": "./dist/esm/client.d.ts",
+      "import": "./dist/esm/client.js",
+      "require": "./dist/cjs/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/write-cjs-package.mjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.mjs\" \"scripts/**/*.mjs\"",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.mjs\" \"scripts/**/*.mjs\"",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kismet-tech/kismet-telemetry.git",
+    "directory": "packages/telemetry-node"
+  },
+  "homepage": "https://developers.kismet.travel/telemetry/node/",
+  "keywords": [
+    "kismet",
+    "telemetry",
+    "tracking",
+    "express",
+    "connect",
+    "fastify",
+    "middleware",
+    "attribution",
+    "ai-visibility"
+  ],
+  "author": "Kismet Technologies",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@kismet-tech/telemetry": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "express": "^5.1.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.8.3"
+  }
+}

package/src/client.ts ADDED Viewed

@@ -0,0 +1,8 @@
+// Browser helpers, re-exported from the core so a Node app imports one package.
+//   import { createTracker } from '@kismet-tech/telemetry-node/client';
+export {
+    createTracker,
+    currentKidSid,
+    emitVisitorEvent,
+    postBookingBridgeFromBrowser,
+} from '@kismet-tech/telemetry/client';

package/src/index.ts ADDED Viewed

@@ -0,0 +1,403 @@
+// @kismet-tech/telemetry-node: the Node server adapter over @kismet-tech/telemetry.
+//
+// kismetTelemetry(config) returns an Express or Connect middleware (req, res, next)
+// that does the whole contract on every page request: resolve the visitor
+// (threaded, cookie, suppressed, cold with a local mint and an after-response
+// reconcile), emit the server-plane event, set the first-party cookies on the
+// dotted serving domain, mark the response private, and leave the seed on
+// `req.kismet` and `res.locals.kismet` for the template. It works on the raw
+// node:http request and response, so Fastify (`req.raw`, `reply.raw`), Koa
+// (`ctx.req`, `ctx.res`) and a plain `createServer` handler use it too.
+//
+// resolveKismetRequest(config) is the same decision as a function of a web
+// `Request`, for frameworks that speak Request and Response (Hono, Workers,
+// Deno) and want to apply the headers themselves.
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+    buildCookie,
+    classifyRequest,
+    cookieDomainFor,
+    DEFAULT_KJS_URL,
+    fireContentEvent,
+    isHttps,
+    normalizeServingDomain,
+    postBookingBridge,
+    postQuoteCapture,
+    publicUrl,
+    readCountry,
+    renderSeedScript,
+    resolveVisitor,
+    SEED_HEADERS,
+    SID_COOKIE,
+    SID_MAX_AGE,
+    VID_COOKIE,
+    VID_MAX_AGE,
+    visitorIp,
+} from '@kismet-tech/telemetry';
+import type {
+    BookingBridgeBody,
+    Classification,
+    ConsentHook,
+    ConversionResult,
+    QuoteCaptureBody,
+    ResolveResult,
+    RouteProfile,
+} from '@kismet-tech/telemetry';
+export const CONTRACT_VERSION = '1.0';
+export interface KismetTelemetryConfig {
+    /** The collection this site's pages belong to. */
+    collectionSlug: string;
+    /** The collection's `ctk_` tracking key. Server-side only; read it from the environment. */
+    trackingKey: string;
+    /** Which URLs are properties, search, the checkout path, agent surfaces. */
+    profile?: RouteProfile;
+    /**
+     * The site's consent decision. Without it the country default applies, which
+     * reads a Cloudflare or Vercel country header; a Node server behind Apache or
+     * nginx has neither, so the default would set cookies for everyone. Wire your
+     * consent manager here (`consentFromCookie` covers the common case).
+     */
+    consent?: ConsentHook | null;
+    /** Override the dotted-domain rule, e.g. '.example.com' for a deeper serving host. */
+    cookieDomain?: string | null;
+    /** Ask the authority before responding on a cold visit (1.5 s cap). Off by default. */
+    authorityFirst?: boolean;
+    /** Suppress generic clients (curl, headless browsers) as well as the bot vocabulary. Default true. */
+    suppressGenericClients?: boolean;
+    /**
+     * Your own country source when the platform sets one under a different header
+     * (a GeoIP module, a load balancer). Return null when unknown. Default reads
+     * `cf-ipcountry` then `x-vercel-ip-country`.
+     */
+    country?: (headers: Headers) => string | null | undefined;
+    /** Overrides for lab and staging. */
+    endpoints?: { resolveAnchor?: string; track?: string; apiOrigin?: string; kjs?: string };
+}
+export interface KismetVisitor extends ResolveResult {
+    /** What the request was classified as by the route profile. */
+    classification: Classification;
+}
+/** What the middleware leaves on `req.kismet` and `res.locals.kismet`. */
+export interface KismetRequestState {
+    kidSid: string | null;
+    kidVid: string | null;
+    suppressed: boolean;
+    isBot: boolean;
+    tier: string;
+    classification: Classification;
+    /**
+     * One inline `<script>` for `<head>`: the seed assignment, then the k.js tag
+     * appended by the script itself. Empty when there is nothing to seed. Print it
+     * verbatim before any other script in the head.
+     */
+    seed: string;
+}
+export type KismetDecision =
+    | { kind: 'excluded' }
+    | { kind: 'agent' }
+    | {
+          kind: 'page';
+          visitor: KismetVisitor;
+          state: KismetRequestState;
+          /** Response headers to set: cache-control, the tier header. */
+          headers: Record<string, string>;
+          /** Set-Cookie lines to append, zero to two. */
+          setCookies: string[];
+      };
+function eventEnv(cfg: KismetTelemetryConfig) {
+    return {
+        COLLECTION_KEY: cfg.trackingKey,
+        ...(cfg.endpoints?.track ? { TRACKING_ENDPOINT: cfg.endpoints.track } : {}),
+    };
+}
+function apiEnv(cfg: KismetTelemetryConfig) {
+    return {
+        COLLECTION_KEY: cfg.trackingKey,
+        ...(cfg.endpoints?.apiOrigin ? { KISMET_API_ORIGIN: cfg.endpoints.apiOrigin } : {}),
+    };
+}
+/**
+ * The seed as one inline script: the assignment, then the k.js tag appended by
+ * the script itself, so no template engine or renderer can reorder them
+ * (contract section 7). Empty when there is neither an id nor a suppression.
+ */
+export function kismetSeedHtml(
+    input: { kidSid: string | null; suppressed: boolean },
+    collectionSlug: string,
+    kjsUrl?: string
+): string {
+    const seed = renderSeedScript({ kidSid: input.kidSid, suppressed: input.suppressed });
+    if (!seed) return '';
+    const assignment = seed.replace(/^<script>/, '').replace(/<\/script>$/, '');
+    const src = `${kjsUrl || DEFAULT_KJS_URL}?c=${encodeURIComponent(collectionSlug)}`;
+    return (
+        '<script>' +
+        assignment +
+        `(function(){var s=document.createElement('script');s.async=true;s.src=${JSON.stringify(src)};` +
+        `(document.head||document.documentElement).appendChild(s);})();` +
+        '</script>'
+    );
+}
+/**
+ * The contract as a function of a web `Request`. Returns what to do with the
+ * response; applies nothing itself. `flush()` awaits the background work
+ * (reconcile, events), for tests and for graceful shutdown.
+ */
+export function createKismetResolver(cfg: KismetTelemetryConfig) {
+    if (!cfg.collectionSlug)
+        throw new Error('@kismet-tech/telemetry-node: collectionSlug is required');
+    if (!cfg.trackingKey) {
+        console.warn(
+            '[kismet-telemetry] trackingKey is empty: sessions resolve locally, nothing is sent to Kismet'
+        );
+    }
+    let pending: Promise<unknown>[] = [];
+    const ctx = {
+        waitUntil(p: Promise<unknown>) {
+            const tracked = Promise.resolve(p).catch(() => undefined);
+            pending.push(tracked);
+            void tracked.then(() => {
+                pending = pending.filter((x) => x !== tracked);
+            });
+        },
+    };
+    const env = eventEnv(cfg);
+    async function resolve(request: Request): Promise<KismetDecision> {
+        const headers = request.headers;
+        const url = publicUrl(headers, new URL(request.url));
+        const classification = classifyRequest(url, cfg.profile, {
+            accept: headers.get('accept'),
+            method: request.method,
+        });
+        if (classification.kind === 'excluded') return { kind: 'excluded' };
+        const country = cfg.country ? (cfg.country(headers) ?? null) : readCountry(headers);
+        const common = {
+            pageUrl: url.toString(),
+            domain: normalizeServingDomain(url.host),
+            collectionSlug: cfg.collectionSlug,
+            userAgent: headers.get('user-agent'),
+            clientIp: visitorIp(headers),
+            country,
+            referrer: headers.get('referer'),
+        };
+        if (classification.kind === 'agent') {
+            fireContentEvent(ctx, env, {
+                ...common,
+                vrSlug: null,
+                clientSessionId: null,
+                agentFetch: true,
+            });
+            return { kind: 'agent' };
+        }
+        const resolved = await resolveVisitor({
+            url,
+            headers,
+            collectionSlug: cfg.collectionSlug,
+            trackingKey: cfg.trackingKey,
+            consent: cfg.consent ?? null,
+            country,
+            authorityFirst: cfg.authorityFirst,
+            suppressGenericClients: cfg.suppressGenericClients,
+            resolveEndpoint: cfg.endpoints?.resolveAnchor ?? null,
+            apiOrigin: cfg.endpoints?.apiOrigin ?? null,
+            waitUntil: ctx.waitUntil,
+        });
+        const visitor: KismetVisitor = { ...resolved, classification };
+        fireContentEvent(ctx, env, {
+            ...common,
+            vrSlug: classification.vrSlug,
+            ...(classification.externalListingId
+                ? { externalListingId: classification.externalListingId }
+                : {}),
+            clientSessionId: visitor.isBot ? null : visitor.kidSid,
+            ctaIntent: classification.kind === 'intent',
+            stayCheckIn: classification.stayCheckIn,
+            stayCheckOut: classification.stayCheckOut,
+            guestCount: classification.guestCount,
+            promoCode: classification.promoCode,
+        });
+        const state: KismetRequestState = {
+            kidSid: visitor.kidSid,
+            kidVid: visitor.kidVid,
+            suppressed: visitor.suppressed,
+            isBot: visitor.isBot,
+            tier: visitor.tier,
+            classification,
+            seed: kismetSeedHtml(visitor, cfg.collectionSlug, cfg.endpoints?.kjs),
+        };
+        // A response that carries a per-visitor seed must never be cached by a shared cache.
+        const outHeaders: Record<string, string> = {
+            'cache-control': 'private, no-store',
+            [SEED_HEADERS.tier]: visitor.tier,
+        };
+        const domain = cookieDomainFor(url.host, cfg.cookieDomain ?? null);
+        const secure = isHttps(headers, url);
+        const setCookies: string[] = [];
+        if (visitor.kidSid && visitor.setSid) {
+            setCookies.push(
+                buildCookie(SID_COOKIE, visitor.kidSid, { maxAge: SID_MAX_AGE, domain, secure })
+            );
+        }
+        if (visitor.kidVid && visitor.setVid) {
+            setCookies.push(
+                buildCookie(VID_COOKIE, visitor.kidVid, { maxAge: VID_MAX_AGE, domain, secure })
+            );
+        }
+        return { kind: 'page', visitor, state, headers: outHeaders, setCookies };
+    }
+    async function flush(): Promise<void> {
+        while (pending.length) {
+            const p = pending;
+            pending = [];
+            await Promise.allSettled(p);
+        }
+    }
+    return { resolve, flush };
+}
+/** The request the middleware accepts: node:http, Express, Connect, Fastify raw, Koa raw. */
+export type NodeRequest = IncomingMessage & {
+    originalUrl?: string;
+    kismet?: KismetRequestState;
+};
+export type NodeResponse = ServerResponse & { locals?: Record<string, unknown> };
+export type NextFunction = (err?: unknown) => void;
+/** Build a web `Request` from a Node request, with the public URL rebuilt from forwarded headers. */
+export function toWebRequest(req: NodeRequest): Request {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined) continue;
+        headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+    }
+    const socket = req.socket as { encrypted?: boolean } | undefined;
+    const scheme = socket?.encrypted ? 'https' : 'http';
+    const host = headers.get('host') || 'localhost';
+    const path = req.originalUrl || req.url || '/';
+    return new Request(new URL(path, `${scheme}://${host}`), {
+        method: req.method || 'GET',
+        headers,
+    });
+}
+/** Apply a page decision to a Node response and stash the state on the request. */
+export function applyKismetDecision(
+    req: NodeRequest,
+    res: NodeResponse,
+    decision: KismetDecision
+): void {
+    if (decision.kind !== 'page') return;
+    req.kismet = decision.state;
+    if (res.locals && typeof res.locals === 'object') res.locals.kismet = decision.state;
+    for (const [name, value] of Object.entries(decision.headers)) res.setHeader(name, value);
+    if (decision.setCookies.length) {
+        const prev = res.getHeader('set-cookie');
+        const existing = Array.isArray(prev) ? prev : typeof prev === 'string' ? [prev] : [];
+        res.setHeader('Set-Cookie', [...existing, ...decision.setCookies]);
+    }
+}
+export interface KismetMiddleware {
+    (req: NodeRequest, res: NodeResponse, next: NextFunction): void;
+    /** Await background work (reconcile, events). For tests and graceful shutdown. */
+    flush(): Promise<void>;
+    /** The decision as a function of a web Request, for frameworks that apply headers themselves. */
+    resolve(request: Request): Promise<KismetDecision>;
+}
+/**
+ * Build the middleware. `app.use(kismetTelemetry(config))` before your routes;
+ * then print `res.locals.kismet.seed` (or `req.kismet.seed`) in `<head>`.
+ */
+export function kismetTelemetry(cfg: KismetTelemetryConfig): KismetMiddleware {
+    const resolver = createKismetResolver(cfg);
+    const middleware = function kismetTelemetryMiddleware(
+        req: NodeRequest,
+        res: NodeResponse,
+        next: NextFunction
+    ): void {
+        let request: Request;
+        try {
+            request = toWebRequest(req);
+        } catch (err) {
+            warn(err);
+            next();
+            return;
+        }
+        resolver.resolve(request).then(
+            (decision) => {
+                try {
+                    applyKismetDecision(req, res, decision);
+                } catch (err) {
+                    warn(err);
+                }
+                next();
+            },
+            (err) => {
+                // The page is always served. Telemetry degrades to "nothing on this request".
+                warn(err);
+                next();
+            }
+        );
+    } as KismetMiddleware;
+    middleware.flush = resolver.flush;
+    middleware.resolve = resolver.resolve;
+    return middleware;
+}
+function warn(err: unknown): void {
+    console.warn(
+        '[kismet-telemetry] middleware error, serving without telemetry:',
+        err instanceof Error ? err.message : err
+    );
+}
+/** Read the state the middleware attached, from a route handler or template helper. */
+export function readKismetState(req: NodeRequest): KismetRequestState | null {
+    return req.kismet ?? null;
+}
+/** The conversion join, from the server code that knows the booking succeeded. */
+export function bookingBridge(
+    cfg: KismetTelemetryConfig,
+    body: BookingBridgeBody
+): Promise<ConversionResult> {
+    return postBookingBridge(apiEnv(cfg), body);
+}
+/** A quote the guest saw, for the fallback match on property and dates. */
+export function quoteCapture(
+    cfg: KismetTelemetryConfig,
+    body: QuoteCaptureBody
+): Promise<ConversionResult> {
+    return postQuoteCapture(apiEnv(cfg), { collectionSlug: cfg.collectionSlug, ...body });
+}
+export { consentFromCookie, countryAllowsCookies, SEED_HEADERS } from '@kismet-tech/telemetry';
+export type {
+    RouteProfile,
+    ConsentHook,
+    Classification,
+    BookingBridgeBody,
+    QuoteCaptureBody,
+    ConversionResult,
+} from '@kismet-tech/telemetry';