@backendfree/webanalytics 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @backendfree/webanalytics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Report page views to BackendFree from your own server, for the visitors and
+crawlers a browser snippet never sees.
+
+The snippet on the Tracking screen covers people with JavaScript. This covers
+everything else: crawlers, which mostly do not run scripts at all, and any
+request you want measured before a page is rendered.
+
+```sh
+npm install @backendfree/webanalytics
+```
+
+## Using it
+
+Report a page view where your server answers a page load. In Next.js that is
+`proxy.ts` (`middleware.ts` before Next 16):
+
+```ts
+import { NextResponse, type NextFetchEvent, type NextRequest } from 'next/server';
+import { Reporter } from '@backendfree/webanalytics';
+
+const reporter = new Reporter({
+  origin: 'https://backendfree.com',
+  key: process.env.BACKENDFREE_SECRET_KEY!,
+});
+
+export function proxy(request: NextRequest, event: NextFetchEvent) {
+  // A page load, or a crawler, which sends no Sec-Fetch-Dest at all. Not the
+  // prefetches and data requests an app makes in the background.
+  const dest = request.headers.get('sec-fetch-dest');
+  if (request.method === 'GET' && (dest === null || dest === 'document')) {
+    reporter.pageview({
+      url: request.url,
+      referrer: request.headers.get('referer') ?? '',
+      ip: request.headers.get('cf-connecting-ip') ?? '',
+      userAgent: request.headers.get('user-agent') ?? '',
+      optedOut: request.headers.get('sec-gpc') === '1' || request.headers.get('dnt') === '1',
+    });
+    event.waitUntil(reporter.flush());
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  // Not the API routes, the framework's own files, or anything with an extension.
+  matcher: ['/((?!api/|_next/|.*\\.[a-zA-Z0-9]+$).*)'],
+};
+```
+
+`pageview` and `event` return immediately. Nothing is awaited, nothing throws,
+and a collector that is down or slow cannot delay or break the page.
+
+The proxy hands `flush()` to `waitUntil`, which keeps the function alive long
+enough for the report to leave without the page waiting for it. On any other
+serverless platform, do the same with whatever it calls that:
+
+```ts
+context.waitUntil(reporter.flush());
+```
+
+### Pages opened without a page load
+
+**A page reached by a link inside the site never reaches the proxy.** Next.js,
+and any app with a client-side router, fetches the next page in the background,
+often before the click, and shows it without a page load. Counting those
+background fetches would count pages nobody opened; ignoring them misses most of
+a visit. So the proxy counts page loads only, and the browser says when the path
+changes, through your own server, which reports it the same way:
+
+```ts
+// app/actions.ts
+'use server';
+import { headers } from 'next/headers';
+import { after } from 'next/server';
+
+export async function recordPageView(path: string) {
+  const asked = await headers();
+  reporter.pageview({
+    url: `https://salon.example${path}`,
+    ip: asked.get('cf-connecting-ip') ?? '',
+    userAgent: asked.get('user-agent') ?? '',
+    optedOut: asked.get('sec-gpc') === '1' || asked.get('dnt') === '1',
+  });
+  after(() => reporter.flush());
+}
+```
+
+Call it from a client component whenever `usePathname()` changes, skipping the
+first path, which was a page load the proxy has already counted. No key reaches
+the browser, and nothing is stored on the device.
+
+### Named events
+
+Something worth counting that is not a page, such as a booking made, is an
+event. Declare its name on the Tracking screen first: a name that is not
+declared is recorded as the page view it also was.
+
+```ts
+// in a server action, as above
+reporter.event('booking_made', {
+  url: 'https://salon.example/book',
+  ip: asked.get('cf-connecting-ip') ?? '',
+  userAgent: asked.get('user-agent') ?? '',
+});
+```
+
+## A secret key, and it refuses a publishable one
+
+Every report asserts who the visitor was, because your server is the only thing
+that saw them. A publishable key is public by design: it sits in the page source
+of every site using it. If this endpoint accepted one, anybody who read it could
+forge visitors and spend your events allowance while looking like real traffic.
+
+So this needs `sk_`, the platform refuses anything else with a 401, and the
+constructor refuses it earlier so the stack trace points at the line that is
+wrong.
+
+Keep the key on the server. It is the same key that can read your payments.
+
+## What we do with what you send
+
+The address and the User-Agent go into a hash with a salt that rotates at your
+project's local midnight and is never written down, and neither is ever stored.
+Same as what the browser snippet does with the address it arrives from, which is
+why sites using either need no cookie banner. The full list is on the Tracking
+screen.
+
+Send the **visitor's** address, not your server's: read it from whatever header
+your proxy sets (`cf-connecting-ip`, `x-real-ip`, or the entry your own proxy
+appended to `x-forwarded-for`, at its right-hand end, since the left is whatever
+the visitor sent). Your own address for everybody makes the whole site look
+like one person. A report with no address still records; it just counts fewer
+visitors than there were.
+
+Send the **visitor's** User-Agent too. It is what tells a crawler from a person,
+and without it a crawler is counted as a visitor and spends an event.
+
+Pass the **visitor's** opt-out. Somebody whose browser sends `Sec-GPC: 1` or
+`DNT: 1` is not measured by the snippet, and only your server saw those headers,
+so `optedOut` is how the same rule reaches this door. An opted-out hit is never
+sent. Writing your own client instead, send `"opted_out": true` on the event and
+the platform drops it before anything is derived from the address.
+
+## Options
+
+| option | default | |
+|---|---|---|
+| `origin` | required | Where the platform runs, no trailing path |
+| `key` | required | `sk_live_...` |
+| `batchSize` | `20` | Hits gathered before sending. Capped at 100 |
+| `interval` | `1000` | How long a partly full batch waits, in ms |
+| `timeout` | `10000` | Per-request, in ms. `0` disables it |
+| `fetch` | global | Your own: a test double, a Worker's fetcher |
+| `onError` | silence | The only place a failed report is visible |
+
+`onError` defaults to doing nothing on purpose. During an outage the alternative
+is a log line per page view, which fills your log budget with our problem.
+
+## What it does not do
+
+**It does not read anything.** There is no method here that returns figures: the
+Traffic screen in the dashboard is where those are read, and a key that could
+report and read would be a wider key than reporting needs.
+
+**It does not retry.** A page view that failed to send is a page view lost, and
+that is the right trade: a queue that grows during an outage is memory on
+somebody's web server, and the figure it protects is a count.
+
+**It does not trim your URLs.** The query string is dropped and `utm_*` kept on
+arrival, in the one place that rule lives. Doing it here as well would be a
+second implementation of it, and the day they disagreed your campaign tags would
+go missing with nothing failing.

package/dist/index.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @backendfree/webanalytics
+ *
+ * Reporting page views from your own server, for the visitors a browser snippet
+ * never sees.
+ *
+ *     import { Reporter } from '@backendfree/webanalytics';
+ *
+ *     const reporter = new Reporter({ origin, key: process.env.SECRET_KEY });
+ *
+ *     // where your server answers a page load: a Next.js proxy, an edge worker
+ *     reporter.pageview({
+ *       url: request.url,
+ *       referrer: request.headers.get('referer') ?? '',
+ *       ip: request.headers.get('cf-connecting-ip') ?? '',
+ *       userAgent: request.headers.get('user-agent') ?? '',
+ *       optedOut: request.headers.get('sec-gpc') === '1' || request.headers.get('dnt') === '1',
+ *     });
+ *     event.waitUntil(reporter.flush());
+ *
+ * Five things are worth knowing before using it.
+ *
+ * **This needs a secret key, and it throws on a publishable one.** Every report
+ * asserts who the visitor was, because your server is the only thing that saw
+ * them. A publishable key sits in the page source of every site using it, so
+ * accepting one here would let anybody who read it forge visitors and spend
+ * your month while looking like real traffic. The platform refuses it too; this
+ * refuses at construction, where the stack trace points at the line that is
+ * wrong.
+ *
+ * **It never throws while reporting, and never delays a response.** A page must
+ * not fail, or wait, because measuring it failed. `pageview` and `event` return
+ * immediately; sending happens in the background and a failure is dropped. Call
+ * `flush()` where you actually want to wait, which on a serverless platform
+ * means inside `waitUntil`.
+ *
+ * **It is not built on `Client`.** The collector is not `/v1`: no ETags, no
+ * idempotency keys, no error envelope, no pagination and no request allowance.
+ * Routing reports through a client built for a different API would attach four
+ * things the endpoint ignores.
+ *
+ * **What you send about a visitor does not survive the request.** The address
+ * and the agent go into a hash with a salt that rotates at your project's local
+ * midnight and is never written down, and neither is ever stored. That is the
+ * same thing the browser snippet does with the address it arrives from, which
+ * is why sites using either need no cookie banner. A visitor who sent GPC or
+ * DNT is not measured at all: pass `optedOut` and the hit is never sent.
+ *
+ * **Crawlers are why this exists.** Most never run JavaScript, so the snippet
+ * does not see them at all. Reported from your server they are classified,
+ * counted and capped, and they never spend your events allowance.
+ */
+/** Where the collector lives under an origin. */
+export declare const COLLECT_PATH = "/collect/s";
+/** What the platform takes in one report. Sending more is a 400. */
+export declare const MAX_BATCH = 100;
+/** Ten seconds, matching core's client: long enough for a cold start. */
+export declare const DEFAULT_TIMEOUT = 10000;
+/** How long a partly full batch waits for company before going anyway. */
+export declare const DEFAULT_INTERVAL = 1000;
+export interface ReporterOptions {
+    /** Where the platform runs, with no trailing path: `https://backendfree.com`. */
+    origin: string;
+    /** `sk_live_...`. A publishable key throws: see the note above. */
+    key: string;
+    /** Swap in your own `fetch`: a test double, or a Worker's bound fetcher. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout in milliseconds. `0` disables it. */
+    timeout?: number;
+    /**
+     * Hits to gather before sending. 1 sends every hit on its own, which is
+     * simplest and costs a request per page view. Capped at `MAX_BATCH`.
+     */
+    batchSize?: number;
+    /**
+     * How long a partly full batch waits, in milliseconds. `0` sends on the next
+     * turn of the event loop rather than never: a site with one visitor an hour
+     * would otherwise hold that visit until the next one arrived.
+     */
+    interval?: number;
+    /**
+     * Called when a batch could not be sent. Nothing is retried and nothing is
+     * thrown, so this is the only place a failure is visible. Default: silence,
+     * because the alternative is an unhandled rejection taking down a worker
+     * over an analytics call.
+     */
+    onError?: (error: unknown) => void;
+}
+/** One page view or named event to report. */
+export interface HitInput {
+    /** The full URL the visitor was on. The query is dropped except `utm_*`. */
+    url: string;
+    /** The referrer, reduced to a hostname on arrival. */
+    referrer?: string;
+    /**
+     * @deprecated Ignored. `pageview()` always reports a page view, and
+     * `event(name, hit)` takes the event's name as its first argument.
+     */
+    name?: string;
+    /**
+     * The visitor's address, hashed on arrival and never stored. Read it from
+     * whatever header your proxy sets: `cf-connecting-ip`, `x-real-ip`, or the
+     * far end of `x-forwarded-for`. Sending your own server's address instead
+     * makes every visitor look like one person.
+     */
+    ip?: string;
+    /**
+     * The visitor's User-Agent. Kept only as one of three device words, and it
+     * is what tells a crawler from a person, so a report without it counts a
+     * crawler as a visitor and spends an event on it.
+     */
+    userAgent?: string;
+    /**
+     * Whether the visitor asked not to be measured: `sec-gpc: 1` or `dnt: 1` on
+     * their request. Only your server saw those headers, so only you can pass
+     * them on. An opted-out hit is dropped here and never sent, the same as the
+     * browser snippet does.
+     */
+    optedOut?: boolean;
+}
+export declare class Reporter {
+    #private;
+    readonly origin: string;
+    constructor(options: ReporterOptions);
+    /** How many hits are waiting to be sent. */
+    get pending(): number;
+    /**
+     * Report one page view. Returns immediately and never throws.
+     *
+     * A hit with no `url` is dropped here rather than sent: the platform would
+     * drop it too, for having no hostname to match against the site list, and
+     * spending a request to find that out helps nobody.
+     */
+    pageview(hit: HitInput): void;
+    /**
+     * Report a named event. Same rules, plus the name has to be one the Tracking
+     * screen declares, or it is recorded as the page view it also was.
+     */
+    event(name: string, hit: HitInput): void;
+    /**
+     * Send everything queued and wait for it.
+     *
+     * Where a serverless platform needs this: `waitUntil(reporter.flush())` keeps
+     * the process alive long enough for the report to leave, and without it a
+     * function that returns immediately takes the queue with it.
+     */
+    flush(): Promise<void>;
+}
+export type { Hit, ReportResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAMH,iDAAiD;AACjD,eAAO,MAAM,YAAY,eAAe,CAAC;AAEzC,oEAAoE;AACpE,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B,yEAAyE;AACzE,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,QAAQ;;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAcZ,OAAO,EAAE,eAAe;IAiCpC,4CAA4C;IAC5C,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAI7B;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI;IAIxC;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmG7B;AAED,YAAY,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,220 @@
+/**
+ * @backendfree/webanalytics
+ *
+ * Reporting page views from your own server, for the visitors a browser snippet
+ * never sees.
+ *
+ *     import { Reporter } from '@backendfree/webanalytics';
+ *
+ *     const reporter = new Reporter({ origin, key: process.env.SECRET_KEY });
+ *
+ *     // where your server answers a page load: a Next.js proxy, an edge worker
+ *     reporter.pageview({
+ *       url: request.url,
+ *       referrer: request.headers.get('referer') ?? '',
+ *       ip: request.headers.get('cf-connecting-ip') ?? '',
+ *       userAgent: request.headers.get('user-agent') ?? '',
+ *       optedOut: request.headers.get('sec-gpc') === '1' || request.headers.get('dnt') === '1',
+ *     });
+ *     event.waitUntil(reporter.flush());
+ *
+ * Five things are worth knowing before using it.
+ *
+ * **This needs a secret key, and it throws on a publishable one.** Every report
+ * asserts who the visitor was, because your server is the only thing that saw
+ * them. A publishable key sits in the page source of every site using it, so
+ * accepting one here would let anybody who read it forge visitors and spend
+ * your month while looking like real traffic. The platform refuses it too; this
+ * refuses at construction, where the stack trace points at the line that is
+ * wrong.
+ *
+ * **It never throws while reporting, and never delays a response.** A page must
+ * not fail, or wait, because measuring it failed. `pageview` and `event` return
+ * immediately; sending happens in the background and a failure is dropped. Call
+ * `flush()` where you actually want to wait, which on a serverless platform
+ * means inside `waitUntil`.
+ *
+ * **It is not built on `Client`.** The collector is not `/v1`: no ETags, no
+ * idempotency keys, no error envelope, no pagination and no request allowance.
+ * Routing reports through a client built for a different API would attach four
+ * things the endpoint ignores.
+ *
+ * **What you send about a visitor does not survive the request.** The address
+ * and the agent go into a hash with a salt that rotates at your project's local
+ * midnight and is never written down, and neither is ever stored. That is the
+ * same thing the browser snippet does with the address it arrives from, which
+ * is why sites using either need no cookie banner. A visitor who sent GPC or
+ * DNT is not measured at all: pass `optedOut` and the hit is never sent.
+ *
+ * **Crawlers are why this exists.** Most never run JavaScript, so the snippet
+ * does not see them at all. Reported from your server they are classified,
+ * counted and capped, and they never spend your events allowance.
+ */
+import { ConfigError } from '@backendfree/core';
+/** Where the collector lives under an origin. */
+export const COLLECT_PATH = '/collect/s';
+/** What the platform takes in one report. Sending more is a 400. */
+export const MAX_BATCH = 100;
+/** Ten seconds, matching core's client: long enough for a cold start. */
+export const DEFAULT_TIMEOUT = 10_000;
+/** How long a partly full batch waits for company before going anyway. */
+export const DEFAULT_INTERVAL = 1_000;
+export class Reporter {
+    origin;
+    #key;
+    #fetch;
+    #timeout;
+    #batchSize;
+    #interval;
+    #onError;
+    #queue = [];
+    #timer = null;
+    /** The send in flight, so `flush()` can wait for it as well as for the queue. */
+    #sending = Promise.resolve();
+    constructor(options) {
+        const origin = (options.origin ?? '').trim().replace(/\/+$/, '');
+        if (!origin) {
+            throw new ConfigError('origin_required', 'Pass the origin the platform runs on.');
+        }
+        const key = (options.key ?? '').trim();
+        if (!key) {
+            throw new ConfigError('key_required', 'Pass a project API key.');
+        }
+        // The mistake this package exists to refuse. A publishable key is public by
+        // design, and this endpoint takes the visitor's identity on trust.
+        if (key.startsWith('pk_')) {
+            throw new ConfigError('secret_key_required', 'Reporting needs a secret key. Every report asserts who the visitor was, so a ' +
+                'publishable key here would let anybody who read it out of your page source forge ' +
+                'visitors and spend your events allowance.');
+        }
+        this.origin = origin;
+        this.#key = key;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.#batchSize = Math.min(Math.max(options.batchSize ?? 20, 1), MAX_BATCH);
+        this.#interval = Math.max(options.interval ?? DEFAULT_INTERVAL, 0);
+        this.#onError = options.onError ?? (() => { });
+        if (typeof this.#fetch !== 'function') {
+            throw new ConfigError('fetch_required', 'This runtime has no fetch. Pass one.');
+        }
+    }
+    /** How many hits are waiting to be sent. */
+    get pending() {
+        return this.#queue.length;
+    }
+    /**
+     * Report one page view. Returns immediately and never throws.
+     *
+     * A hit with no `url` is dropped here rather than sent: the platform would
+     * drop it too, for having no hostname to match against the site list, and
+     * spending a request to find that out helps nobody.
+     */
+    pageview(hit) {
+        this.#add(hit, '');
+    }
+    /**
+     * Report a named event. Same rules, plus the name has to be one the Tracking
+     * screen declares, or it is recorded as the page view it also was.
+     */
+    event(name, hit) {
+        this.#add(hit, name);
+    }
+    /**
+     * Send everything queued and wait for it.
+     *
+     * Where a serverless platform needs this: `waitUntil(reporter.flush())` keeps
+     * the process alive long enough for the report to leave, and without it a
+     * function that returns immediately takes the queue with it.
+     */
+    async flush() {
+        this.#cancelTimer();
+        while (this.#queue.length) {
+            await this.#send(this.#queue.splice(0, this.#batchSize));
+        }
+        await this.#sending;
+    }
+    // --- the queue ---------------------------------------------------------------
+    #add(hit, name) {
+        // Before anything else, so not even a url of theirs is queued.
+        if (hit?.optedOut) {
+            return;
+        }
+        const url = (hit?.url ?? '').trim();
+        if (!url) {
+            return;
+        }
+        this.#queue.push({
+            url,
+            referrer: hit.referrer ?? '',
+            name,
+            ip: hit.ip ?? '',
+            user_agent: hit.userAgent ?? '',
+        });
+        if (this.#queue.length >= this.#batchSize) {
+            this.#cancelTimer();
+            this.#launch(this.#queue.splice(0, this.#batchSize));
+            return;
+        }
+        this.#arm();
+    }
+    #arm() {
+        if (this.#timer !== null) {
+            return;
+        }
+        this.#timer = setTimeout(() => {
+            this.#timer = null;
+            this.#launch(this.#queue.splice(0, this.#batchSize));
+        }, this.#interval);
+        // Node keeps the process alive for a pending timer, so a script that has
+        // finished its work would hang for the interval waiting to report. The
+        // browser and Workers have no such method, hence the guard.
+        this.#timer?.unref?.();
+    }
+    #cancelTimer() {
+        if (this.#timer !== null) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+    }
+    /** Start a send without waiting for it, keeping it reachable for `flush()`. */
+    #launch(batch) {
+        this.#sending = this.#sending.then(() => this.#send(batch));
+    }
+    async #send(batch) {
+        if (!batch.length) {
+            return;
+        }
+        const controller = this.#timeout > 0 ? new AbortController() : null;
+        const timer = controller ? setTimeout(() => controller.abort(), this.#timeout) : null;
+        try {
+            const response = await this.#fetch(`${this.origin}${COLLECT_PATH}`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#key}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({ events: batch }),
+                signal: controller?.signal,
+            });
+            if (!response.ok) {
+                // Read, so the message says which of the four refusals it was rather
+                // than only the status. The platform answers a small JSON object.
+                const detail = await response.text().catch(() => '');
+                throw new Error(`The collector answered ${response.status}. ${detail}`.trim());
+            }
+        }
+        catch (error) {
+            // Swallowed on purpose, and this is the only place a failure surfaces. A
+            // rejected promise nobody is awaiting is an unhandled rejection, which on
+            // several runtimes takes the whole worker down: measuring a page must not
+            // be able to stop it being served.
+            this.#onError(error);
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What goes over the wire, in the collector's own spelling.
+ *
+ * Snake case here and camel case on `HitInput`, deliberately: the wire format
+ * is the platform's and changing it is a breaking change for every caller in
+ * every language, while the shape a TypeScript developer types is theirs. One
+ * conversion, in `#add`, rather than a wire format that reads as if it were
+ * designed for one language.
+ */
+/** One reported hit, as `POST /collect/s` takes it. */
+export interface Hit {
+    url: string;
+    referrer: string;
+    /** Empty for a page view. */
+    name: string;
+    /** Hashed on arrival with the day's salt, and never stored. */
+    ip: string;
+    /** Kept only as one of three device words, and used to spot a crawler. */
+    user_agent: string;
+    /**
+     * The visitor opted out. Never sent by this package, which drops an opted-out
+     * hit before anything leaves; a hand-written client sends it and the platform
+     * drops the event before anything is derived from the address.
+     */
+    opted_out?: boolean;
+}
+/** What the collector answers when it took the report. */
+export interface ReportResult {
+    /** Events in the request, including any it went on to drop. */
+    received: number;
+    /**
+     * Events that became a row. Lower than `received` when the month's allowance
+     * ran out, when a hostname is not on the site list, or when the module is off.
+     * A crawler counts as recorded and spends no allowance.
+     */
+    recorded: number;
+    /** False for a test key, whose hits are counted on the Tracking screen and kept nowhere. */
+    livemode: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uDAAuD;AACvD,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAC;CACnB"}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * What goes over the wire, in the collector's own spelling.
+ *
+ * Snake case here and camel case on `HitInput`, deliberately: the wire format
+ * is the platform's and changing it is a breaking change for every caller in
+ * every language, while the shape a TypeScript developer types is theirs. One
+ * conversion, in `#add`, rather than a wire format that reads as if it were
+ * designed for one language.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@backendfree/webanalytics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Report page views to BackendFree from your own server, for the visitors and crawlers a browser snippet never sees.",
+  "keywords": [
+    "backendfree",
+    "analytics",
+    "cookieless",
+    "privacy",
+    "sdk",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "BackendFree",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@backendfree/core": "^0.1.0"
+  },
+  "scripts": {
+    "clean": "tsc --build --clean && rm -rf dist",
+    "build": "tsc --build",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm run clean && npm run build",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,312 @@
+/**
+ * @backendfree/webanalytics
+ *
+ * Reporting page views from your own server, for the visitors a browser snippet
+ * never sees.
+ *
+ *     import { Reporter } from '@backendfree/webanalytics';
+ *
+ *     const reporter = new Reporter({ origin, key: process.env.SECRET_KEY });
+ *
+ *     // where your server answers a page load: a Next.js proxy, an edge worker
+ *     reporter.pageview({
+ *       url: request.url,
+ *       referrer: request.headers.get('referer') ?? '',
+ *       ip: request.headers.get('cf-connecting-ip') ?? '',
+ *       userAgent: request.headers.get('user-agent') ?? '',
+ *       optedOut: request.headers.get('sec-gpc') === '1' || request.headers.get('dnt') === '1',
+ *     });
+ *     event.waitUntil(reporter.flush());
+ *
+ * Five things are worth knowing before using it.
+ *
+ * **This needs a secret key, and it throws on a publishable one.** Every report
+ * asserts who the visitor was, because your server is the only thing that saw
+ * them. A publishable key sits in the page source of every site using it, so
+ * accepting one here would let anybody who read it forge visitors and spend
+ * your month while looking like real traffic. The platform refuses it too; this
+ * refuses at construction, where the stack trace points at the line that is
+ * wrong.
+ *
+ * **It never throws while reporting, and never delays a response.** A page must
+ * not fail, or wait, because measuring it failed. `pageview` and `event` return
+ * immediately; sending happens in the background and a failure is dropped. Call
+ * `flush()` where you actually want to wait, which on a serverless platform
+ * means inside `waitUntil`.
+ *
+ * **It is not built on `Client`.** The collector is not `/v1`: no ETags, no
+ * idempotency keys, no error envelope, no pagination and no request allowance.
+ * Routing reports through a client built for a different API would attach four
+ * things the endpoint ignores.
+ *
+ * **What you send about a visitor does not survive the request.** The address
+ * and the agent go into a hash with a salt that rotates at your project's local
+ * midnight and is never written down, and neither is ever stored. That is the
+ * same thing the browser snippet does with the address it arrives from, which
+ * is why sites using either need no cookie banner. A visitor who sent GPC or
+ * DNT is not measured at all: pass `optedOut` and the hit is never sent.
+ *
+ * **Crawlers are why this exists.** Most never run JavaScript, so the snippet
+ * does not see them at all. Reported from your server they are classified,
+ * counted and capped, and they never spend your events allowance.
+ */
+
+import { ConfigError } from '@backendfree/core';
+
+import type { Hit, ReportResult } from './types.js';
+
+/** Where the collector lives under an origin. */
+export const COLLECT_PATH = '/collect/s';
+
+/** What the platform takes in one report. Sending more is a 400. */
+export const MAX_BATCH = 100;
+
+/** Ten seconds, matching core's client: long enough for a cold start. */
+export const DEFAULT_TIMEOUT = 10_000;
+
+/** How long a partly full batch waits for company before going anyway. */
+export const DEFAULT_INTERVAL = 1_000;
+
+export interface ReporterOptions {
+  /** Where the platform runs, with no trailing path: `https://backendfree.com`. */
+  origin: string;
+  /** `sk_live_...`. A publishable key throws: see the note above. */
+  key: string;
+  /** Swap in your own `fetch`: a test double, or a Worker's bound fetcher. */
+  fetch?: typeof globalThis.fetch;
+  /** Per-request timeout in milliseconds. `0` disables it. */
+  timeout?: number;
+  /**
+   * Hits to gather before sending. 1 sends every hit on its own, which is
+   * simplest and costs a request per page view. Capped at `MAX_BATCH`.
+   */
+  batchSize?: number;
+  /**
+   * How long a partly full batch waits, in milliseconds. `0` sends on the next
+   * turn of the event loop rather than never: a site with one visitor an hour
+   * would otherwise hold that visit until the next one arrived.
+   */
+  interval?: number;
+  /**
+   * Called when a batch could not be sent. Nothing is retried and nothing is
+   * thrown, so this is the only place a failure is visible. Default: silence,
+   * because the alternative is an unhandled rejection taking down a worker
+   * over an analytics call.
+   */
+  onError?: (error: unknown) => void;
+}
+
+/** One page view or named event to report. */
+export interface HitInput {
+  /** The full URL the visitor was on. The query is dropped except `utm_*`. */
+  url: string;
+  /** The referrer, reduced to a hostname on arrival. */
+  referrer?: string;
+  /**
+   * @deprecated Ignored. `pageview()` always reports a page view, and
+   * `event(name, hit)` takes the event's name as its first argument.
+   */
+  name?: string;
+  /**
+   * The visitor's address, hashed on arrival and never stored. Read it from
+   * whatever header your proxy sets: `cf-connecting-ip`, `x-real-ip`, or the
+   * far end of `x-forwarded-for`. Sending your own server's address instead
+   * makes every visitor look like one person.
+   */
+  ip?: string;
+  /**
+   * The visitor's User-Agent. Kept only as one of three device words, and it
+   * is what tells a crawler from a person, so a report without it counts a
+   * crawler as a visitor and spends an event on it.
+   */
+  userAgent?: string;
+  /**
+   * Whether the visitor asked not to be measured: `sec-gpc: 1` or `dnt: 1` on
+   * their request. Only your server saw those headers, so only you can pass
+   * them on. An opted-out hit is dropped here and never sent, the same as the
+   * browser snippet does.
+   */
+  optedOut?: boolean;
+}
+
+export class Reporter {
+  readonly origin: string;
+
+  readonly #key: string;
+  readonly #fetch: typeof globalThis.fetch;
+  readonly #timeout: number;
+  readonly #batchSize: number;
+  readonly #interval: number;
+  readonly #onError: (error: unknown) => void;
+
+  #queue: Hit[] = [];
+  #timer: ReturnType<typeof setTimeout> | null = null;
+  /** The send in flight, so `flush()` can wait for it as well as for the queue. */
+  #sending: Promise<void> = Promise.resolve();
+
+  constructor(options: ReporterOptions) {
+    const origin = (options.origin ?? '').trim().replace(/\/+$/, '');
+    if (!origin) {
+      throw new ConfigError('origin_required', 'Pass the origin the platform runs on.');
+    }
+    const key = (options.key ?? '').trim();
+    if (!key) {
+      throw new ConfigError('key_required', 'Pass a project API key.');
+    }
+    // The mistake this package exists to refuse. A publishable key is public by
+    // design, and this endpoint takes the visitor's identity on trust.
+    if (key.startsWith('pk_')) {
+      throw new ConfigError(
+        'secret_key_required',
+        'Reporting needs a secret key. Every report asserts who the visitor was, so a ' +
+          'publishable key here would let anybody who read it out of your page source forge ' +
+          'visitors and spend your events allowance.',
+      );
+    }
+
+    this.origin = origin;
+    this.#key = key;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.#batchSize = Math.min(Math.max(options.batchSize ?? 20, 1), MAX_BATCH);
+    this.#interval = Math.max(options.interval ?? DEFAULT_INTERVAL, 0);
+    this.#onError = options.onError ?? (() => {});
+
+    if (typeof this.#fetch !== 'function') {
+      throw new ConfigError('fetch_required', 'This runtime has no fetch. Pass one.');
+    }
+  }
+
+  /** How many hits are waiting to be sent. */
+  get pending(): number {
+    return this.#queue.length;
+  }
+
+  /**
+   * Report one page view. Returns immediately and never throws.
+   *
+   * A hit with no `url` is dropped here rather than sent: the platform would
+   * drop it too, for having no hostname to match against the site list, and
+   * spending a request to find that out helps nobody.
+   */
+  pageview(hit: HitInput): void {
+    this.#add(hit, '');
+  }
+
+  /**
+   * Report a named event. Same rules, plus the name has to be one the Tracking
+   * screen declares, or it is recorded as the page view it also was.
+   */
+  event(name: string, hit: HitInput): void {
+    this.#add(hit, name);
+  }
+
+  /**
+   * Send everything queued and wait for it.
+   *
+   * Where a serverless platform needs this: `waitUntil(reporter.flush())` keeps
+   * the process alive long enough for the report to leave, and without it a
+   * function that returns immediately takes the queue with it.
+   */
+  async flush(): Promise<void> {
+    this.#cancelTimer();
+    while (this.#queue.length) {
+      await this.#send(this.#queue.splice(0, this.#batchSize));
+    }
+    await this.#sending;
+  }
+
+  // --- the queue ---------------------------------------------------------------
+
+  #add(hit: HitInput, name: string): void {
+    // Before anything else, so not even a url of theirs is queued.
+    if (hit?.optedOut) {
+      return;
+    }
+    const url = (hit?.url ?? '').trim();
+    if (!url) {
+      return;
+    }
+
+    this.#queue.push({
+      url,
+      referrer: hit.referrer ?? '',
+      name,
+      ip: hit.ip ?? '',
+      user_agent: hit.userAgent ?? '',
+    });
+
+    if (this.#queue.length >= this.#batchSize) {
+      this.#cancelTimer();
+      this.#launch(this.#queue.splice(0, this.#batchSize));
+      return;
+    }
+    this.#arm();
+  }
+
+  #arm(): void {
+    if (this.#timer !== null) {
+      return;
+    }
+    this.#timer = setTimeout(() => {
+      this.#timer = null;
+      this.#launch(this.#queue.splice(0, this.#batchSize));
+    }, this.#interval);
+    // Node keeps the process alive for a pending timer, so a script that has
+    // finished its work would hang for the interval waiting to report. The
+    // browser and Workers have no such method, hence the guard.
+    this.#timer?.unref?.();
+  }
+
+  #cancelTimer(): void {
+    if (this.#timer !== null) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+    }
+  }
+
+  /** Start a send without waiting for it, keeping it reachable for `flush()`. */
+  #launch(batch: Hit[]): void {
+    this.#sending = this.#sending.then(() => this.#send(batch));
+  }
+
+  async #send(batch: Hit[]): Promise<void> {
+    if (!batch.length) {
+      return;
+    }
+
+    const controller = this.#timeout > 0 ? new AbortController() : null;
+    const timer = controller ? setTimeout(() => controller.abort(), this.#timeout) : null;
+
+    try {
+      const response = await this.#fetch(`${this.origin}${COLLECT_PATH}`, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${this.#key}`,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({ events: batch }),
+        signal: controller?.signal,
+      });
+
+      if (!response.ok) {
+        // Read, so the message says which of the four refusals it was rather
+        // than only the status. The platform answers a small JSON object.
+        const detail = await response.text().catch(() => '');
+        throw new Error(`The collector answered ${response.status}. ${detail}`.trim());
+      }
+    } catch (error) {
+      // Swallowed on purpose, and this is the only place a failure surfaces. A
+      // rejected promise nobody is awaiting is an unhandled rejection, which on
+      // several runtimes takes the whole worker down: measuring a page must not
+      // be able to stop it being served.
+      this.#onError(error);
+    } finally {
+      if (timer) {
+        clearTimeout(timer);
+      }
+    }
+  }
+}
+
+export type { Hit, ReportResult } from './types.js';

package/src/types.ts

@@ -0,0 +1,41 @@
+/**
+ * What goes over the wire, in the collector's own spelling.
+ *
+ * Snake case here and camel case on `HitInput`, deliberately: the wire format
+ * is the platform's and changing it is a breaking change for every caller in
+ * every language, while the shape a TypeScript developer types is theirs. One
+ * conversion, in `#add`, rather than a wire format that reads as if it were
+ * designed for one language.
+ */
+
+/** One reported hit, as `POST /collect/s` takes it. */
+export interface Hit {
+  url: string;
+  referrer: string;
+  /** Empty for a page view. */
+  name: string;
+  /** Hashed on arrival with the day's salt, and never stored. */
+  ip: string;
+  /** Kept only as one of three device words, and used to spot a crawler. */
+  user_agent: string;
+  /**
+   * The visitor opted out. Never sent by this package, which drops an opted-out
+   * hit before anything leaves; a hand-written client sends it and the platform
+   * drops the event before anything is derived from the address.
+   */
+  opted_out?: boolean;
+}
+
+/** What the collector answers when it took the report. */
+export interface ReportResult {
+  /** Events in the request, including any it went on to drop. */
+  received: number;
+  /**
+   * Events that became a row. Lower than `received` when the month's allowance
+   * ran out, when a hostname is not on the site list, or when the module is off.
+   * A crawler counts as recorded and spends no allowance.
+   */
+  recorded: number;
+  /** False for a test key, whose hits are counted on the Tracking screen and kept nowhere. */
+  livemode: boolean;
+}