@progressive-development/pd-provider-firebase-functions 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { requireAuth, requireClaims, requireOwnership } from './auth.js';
 export { success, created, handleError } from './response.js';
 export { getDb } from './firestore.js';
 export { getNextCounter } from './counter.js';
+export type { VisitInput, VisitDevice, VisitResult, CountVisitOptions, } from './visits.js';
+export { countVisit } from './visits.js';
 export type { TrashItem } from './trash.js';
 export { moveToTrash, restoreFromTrash, permanentDelete, listTrash, getTrashItem, } from './trash.js';
 export type { AuthTrashOptions } from './auth-trash.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EACL,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGzE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG9D,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACV,WAAW,EACX,YAAY,EACZ,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAGzE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,YAAY,EACV,OAAO,EACP,mBAAmB,EACnB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EACL,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGzE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG9D,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,YAAY,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACV,WAAW,EACX,YAAY,EACZ,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAGzE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,YAAY,EACV,OAAO,EACP,mBAAmB,EACnB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -4,6 +4,7 @@ export { requireAuth, requireClaims, requireOwnership } from './auth.js';
 export { created, handleError, success } from './response.js';
 export { getDb } from './firestore.js';
 export { getNextCounter } from './counter.js';
+export { countVisit } from './visits.js';
 export { getTrashItem, listTrash, moveToTrash, permanentDelete, restoreFromTrash } from './trash.js';
 export { moveToTrashWithAuth, permanentDeleteWithAuth, restoreFromTrashWithAuth } from './auth-trash.js';
 export { computeChanges } from './changes.js';

package/dist/visits.d.ts

@@ -0,0 +1,135 @@
+import { CallableRequest } from 'firebase-functions/v2/https';
+/**
+ * Reach measurement — one row per visitor and day.
+ *
+ * WHY ROWS AND NOT COUNTERS: a counter answers only the question you asked
+ * when you built it. Rows can still be grouped, filtered and exported later,
+ * and every value the client sends stays a field VALUE — never a field name,
+ * where a dot would silently create a nested field.
+ *
+ * HOW DEDUPLICATION WORKS: the document id is `<day>_<visitorKey>` and the row
+ * is written with `create()`. A second call on the same day hits ALREADY_EXISTS
+ * and is dropped. No read, no counter, no transaction — the storage IS the
+ * deduplication.
+ *
+ * THE DAY IS IN THE ID, NOT IN THE KEY. That is what makes returning visitors
+ * visible: same suffix on two days is the same visitor. How long that link
+ * survives is one option (`rotate`): "day" makes rows unlinkable across days,
+ * "month" lets you recognise a returning visitor within a month. Default is
+ * the private one; an app that wants recognition asks for it.
+ *
+ * WHAT THE KEY IS WORTH: it is derived from IP and user agent. A browser
+ * update changes the user agent, mobile networks rotate IPs, a household
+ * shares one — so a recognised visitor is real, but an unrecognised one may
+ * still be the same person. It is a lower bound, not a head count. With
+ * `rotate: "month"` the key is a pseudonymous identifier: two rows carrying it
+ * are the same person, which is the point and the price.
+ *
+ * `secret` is optional. Without it the key is a plain hash of values an
+ * attacker could guess, so anyone WHO ALREADY HAS THE ROWS could test whether
+ * a given IP and browser visited. Rows are readable through the Admin SDK
+ * only; adding a constant closes even that, without changing this signature.
+ */
+export type VisitDevice = "phone" | "tablet" | "desktop";
+/**
+ * What the client sends — coarse on purpose; every value is a field, not a key.
+ *
+ * Passed in SEPARATELY from the request, because an app usually wraps its calls
+ * in an envelope of its own (`{ object, type, details }`) and the payload then
+ * sits somewhere inside `request.data`. The helper reads headers from the
+ * request and takes the payload from the caller, so both shapes fit.
+ */
+export interface VisitInput {
+    /** Coarse device class, e.g. from a pointer/width media query. */
+    device?: VisitDevice;
+    /** Opened as an installed app (display-mode: standalone). */
+    standalone?: boolean;
+    /** Host of the referrer, reduced by the client. Never a full URL. */
+    referrer?: string;
+}
+export interface CountVisitOptions {
+    /**
+     * Count only calls from these origins — keeps dev servers out of the numbers.
+     * A site is usually reachable under more than one (hosting plus own domain).
+     */
+    origin?: string | string[];
+    /** IANA zone the day boundary follows. Functions run in UTC; default "UTC". */
+    timeZone?: string;
+    /** How long a visitor key stays the same. Default "day". */
+    rotate?: "day" | "month";
+    /** Optional salt; see the note above. */
+    secret?: string;
+    /**
+     * Days after which a row may be removed — written as `expires`.
+     *
+     * The FIELD is all this does. Deleting is a Firestore TTL policy on that
+     * field, switched on once per collection outside the code; without it the
+     * timestamp is documentation and nothing else. Say a retention period in a
+     * privacy notice only once the policy is on.
+     */
+    retentionDays?: number;
+    /** Default "visits". */
+    collection?: string;
+    /** Named Firestore database. */
+    databaseId?: string;
+}
+export interface VisitResult {
+    counted: boolean;
+    day: string;
+}
+/**
+ * The day as YYYY-MM-DD in the given zone.
+ *
+ * "sv-SE" is the shortest way to an ISO-shaped date: `toISOString()` would be
+ * UTC, and building it by hand from parts is where off-by-one bugs live.
+ */
+export declare function visitDay(now: Date, timeZone: string): string;
+/** The stretch of time a visitor key stays the same. */
+export declare function visitPeriod(day: string, rotate: "day" | "month"): string;
+/** The technical key — short enough to read, long enough not to collide. */
+export declare function visitorKey(period: string, ip: string, userAgent: string, secret?: string): string;
+/** Unknown values are dropped, never guessed and never stored raw. */
+export declare function cleanDevice(value: unknown): VisitDevice | undefined;
+/** A host, nothing else — no path, no query, no room for someone else's data. */
+export declare function cleanReferrer(value: unknown): string | undefined;
+export declare function isBot(userAgent: string): boolean;
+export interface BrowserInfo {
+    /** Family as the user would name it, or "other". */
+    browser: string;
+    /** MAJOR version only. The minor and patch parts identify, they do not inform. */
+    version?: string;
+}
+/**
+ * Browser family and major version.
+ *
+ * ORDER IS THE WHOLE TRICK, because these strings quote each other: Edge says
+ * Edg AND Chrome AND Safari, Chrome says Chrome AND Safari. So the most
+ * specific claim wins, and Safari is asked last. On iOS every engine is
+ * Safari's, but the browsers name themselves (CriOS, FxiOS) — reported as what
+ * the user sees, since that is what the question is about.
+ *
+ * Unclassified traffic becomes "other" rather than nothing: an unreadable
+ * agent is a fact worth seeing, missing data is a different fact.
+ */
+export declare function browserOf(userAgent: string): BrowserInfo;
+/**
+ * Operating system family, never a version.
+ *
+ * Android carries "Linux" in its agent and an iPad in desktop mode calls
+ * itself a Macintosh — so the order matters here too, and the iPad stays
+ * wrong. That is a limit of the source, not something to guess around.
+ */
+export declare function osOf(userAgent: string): string;
+/** No list means no restriction; an empty match means this call does not count. */
+export declare function originAllowed(origin: unknown, allowed?: string | string[]): boolean;
+/** First entry of x-forwarded-for; the rest are proxies. */
+export declare function clientIp(headers: Record<string, unknown>): string | undefined;
+/**
+ * Count one visit — or recognise that this visitor was already counted today.
+ *
+ * Never throws for the ordinary "does not count" cases (wrong origin, bot, no
+ * address, already seen): the caller is a fire-and-forget call from a page
+ * that must not care.
+ */
+export declare function countVisit(request: CallableRequest, visit?: VisitInput, options?: CountVisitOptions): Promise<VisitResult>;
+//# sourceMappingURL=visits.d.ts.map

package/dist/visits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visits.d.ts","sourceRoot":"","sources":["../src/visits.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAI9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACzB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAWD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wDAAwD;AACxD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAExE;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,SAAK,GACV,MAAM,CAKR;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAInE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIhE;AAED,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAgBxD;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ9C;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAC1B,OAAO,CAIT;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAM7E;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,eAAe,EACxB,KAAK,GAAE,UAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,WAAW,CAAC,CAqDtB"}

package/dist/visits.js

@@ -0,0 +1,105 @@
+import { createHash } from 'node:crypto';
+import { Timestamp, FieldValue } from 'firebase-admin/firestore';
+import { getDb } from './firestore.js';
+
+const DEVICES = ["phone", "tablet", "desktop"];
+const BOTS = /bot|crawl|spider|slurp|preview|monitor|headless|lighthouse|curl|wget/i;
+const ALREADY_EXISTS = 6;
+function visitDay(now, timeZone) {
+  return new Intl.DateTimeFormat("sv-SE", { timeZone }).format(now);
+}
+function visitPeriod(day, rotate) {
+  return rotate === "month" ? day.slice(0, 7) : day;
+}
+function visitorKey(period, ip, userAgent, secret = "") {
+  return createHash("sha256").update(`${secret}|${period}|${ip}|${userAgent}`).digest("hex").slice(0, 16);
+}
+function cleanDevice(value) {
+  return typeof value === "string" && DEVICES.includes(value) ? value : void 0;
+}
+function cleanReferrer(value) {
+  if (typeof value !== "string") return void 0;
+  const host = value.trim().toLowerCase();
+  return /^[a-z0-9.\-:]{1,60}$/.test(host) ? host : void 0;
+}
+function isBot(userAgent) {
+  return BOTS.test(userAgent);
+}
+function browserOf(userAgent) {
+  const rules = [
+    ["Edge", /Edg(?:iOS|A)?\/(\d+)/],
+    ["Opera", /OPR\/(\d+)/],
+    ["Samsung Internet", /SamsungBrowser\/(\d+)/],
+    ["Chrome", /CriOS\/(\d+)/],
+    ["Firefox", /FxiOS\/(\d+)/],
+    ["Firefox", /Firefox\/(\d+)/],
+    ["Chrome", /Chrome\/(\d+)/],
+    ["Safari", /Version\/(\d+)[\d.]*\s+(?:Mobile\/\S+\s+)?Safari/]
+  ];
+  for (const [browser, pattern] of rules) {
+    const hit = pattern.exec(userAgent);
+    if (hit) return { browser, version: hit[1] };
+  }
+  return { browser: "other" };
+}
+function osOf(userAgent) {
+  if (/iPhone|iPad|iPod/.test(userAgent)) return "iOS";
+  if (/Android/.test(userAgent)) return "Android";
+  if (/CrOS/.test(userAgent)) return "ChromeOS";
+  if (/Windows/.test(userAgent)) return "Windows";
+  if (/Macintosh|Mac OS X/.test(userAgent)) return "macOS";
+  if (/Linux/.test(userAgent)) return "Linux";
+  return "other";
+}
+function originAllowed(origin, allowed) {
+  if (!allowed) return true;
+  const list = Array.isArray(allowed) ? allowed : [allowed];
+  return typeof origin === "string" && list.includes(origin);
+}
+function clientIp(headers) {
+  const raw = headers["x-forwarded-for"];
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  if (typeof value !== "string") return void 0;
+  const first = value.split(",")[0]?.trim();
+  return first || void 0;
+}
+async function countVisit(request, visit = {}, options = {}) {
+  const headers = request.rawRequest?.headers ?? {};
+  const day = visitDay(/* @__PURE__ */ new Date(), options.timeZone ?? "UTC");
+  const skip = { counted: false, day };
+  if (!originAllowed(headers.origin, options.origin)) return skip;
+  const userAgent = typeof headers["user-agent"] === "string" ? headers["user-agent"] : "";
+  if (!userAgent || isBot(userAgent)) return skip;
+  const ip = clientIp(headers);
+  if (!ip) return skip;
+  const { browser, version } = browserOf(userAgent);
+  const period = visitPeriod(day, options.rotate ?? "day");
+  const visitor = visitorKey(period, ip, userAgent, options.secret);
+  try {
+    await getDb(options.databaseId).collection(options.collection ?? "visits").doc(`${day}_${visitor}`).create({
+      day,
+      visitor,
+      at: FieldValue.serverTimestamp(),
+      // Missing is missing: getDb ignores undefined, so an absent value
+      // leaves no empty field behind.
+      device: cleanDevice(visit.device),
+      standalone: visit.standalone === true,
+      referrer: cleanReferrer(visit.referrer),
+      // Read from the agent the server already has — the client sends
+      // nothing for these. Family and MAJOR version only; the full string
+      // stays where it cannot be read back, in the key.
+      browser,
+      browserVersion: version,
+      os: osOf(userAgent),
+      expires: options.retentionDays ? Timestamp.fromMillis(
+        Date.now() + options.retentionDays * 864e5
+      ) : void 0
+    });
+    return { counted: true, day };
+  } catch (e) {
+    if (e?.code === ALREADY_EXISTS) return skip;
+    throw e;
+  }
+}
+
+export { browserOf, cleanDevice, cleanReferrer, clientIp, countVisit, isBot, originAllowed, osOf, visitDay, visitPeriod, visitorKey };

package/dist/visits.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=visits.spec.d.ts.map

package/dist/visits.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visits.spec.d.ts","sourceRoot":"","sources":["../src/visits.spec.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progressive-development/pd-provider-firebase-functions",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Firebase Functions v2 utilities for pd-spa-helper backend",
   "author": "PD Progressive Development",
   "license": "SEE LICENSE IN LICENSE",