@iann29/rastro 0.1.0-alpha.4 → 0.1.0-alpha.6

package/src/component/visitors.ts

@@ -0,0 +1,116 @@
+import { v } from "convex/values";
+import { MAX_VISITOR_ALIASES } from "./constants.js";
+import { fail } from "./errors.js";
+import { sanitizeOpaqueId } from "./sanitize.js";
+import type { Id } from "./_generated/dataModel.js";
+import { mutation, type QueryCtx } from "./_generated/server.js";
+
+/**
+ * Folds an anonymous visitor id into the pseudonymous identity the host
+ * supplies after signup or sign-in. Links are one level deep: an alias can
+ * belong to one identity, an identity can never become an alias, and an
+ * alias can never own aliases, so journeys stay bounded and unambiguous.
+ */
+export const link = mutation({
+  args: {
+    siteId: v.id("sites"),
+    visitorId: v.string(),
+    previousVisitorId: v.string(),
+  },
+  returns: v.object({ linked: v.boolean(), aliasCount: v.number() }),
+  handler: async (ctx, args) => {
+    const site = await ctx.db.get("sites", args.siteId);
+    if (!site) fail("NOT_FOUND", "site not found");
+    let visitorId: string;
+    let previousVisitorId: string;
+    try {
+      visitorId = sanitizeOpaqueId(args.visitorId, "visitorId");
+      previousVisitorId = sanitizeOpaqueId(
+        args.previousVisitorId,
+        "previousVisitorId",
+      );
+    } catch (error) {
+      fail(
+        "INVALID_ARGUMENT",
+        error instanceof Error ? error.message : "invalid visitor id",
+      );
+    }
+    if (visitorId === previousVisitorId) {
+      fail("INVALID_ARGUMENT", "previousVisitorId must differ from visitorId");
+    }
+    if (await findAlias(ctx, args.siteId, visitorId)) {
+      fail("CONFLICT", "visitorId is already linked to another visitor");
+    }
+    const previousOwnsAliases = await ctx.db
+      .query("visitorAliases")
+      .withIndex("by_siteId_and_visitorId", (range) =>
+        range.eq("siteId", args.siteId).eq("visitorId", previousVisitorId),
+      )
+      .first();
+    if (previousOwnsAliases) {
+      fail("CONFLICT", "previousVisitorId already owns linked visitors");
+    }
+    const aliases = await ctx.db
+      .query("visitorAliases")
+      .withIndex("by_siteId_and_visitorId", (range) =>
+        range.eq("siteId", args.siteId).eq("visitorId", visitorId),
+      )
+      .take(MAX_VISITOR_ALIASES);
+    const existing = await findAlias(ctx, args.siteId, previousVisitorId);
+    if (existing) {
+      if (existing.visitorId !== visitorId) {
+        fail(
+          "CONFLICT",
+          "previousVisitorId is already linked to a different visitor",
+        );
+      }
+      return { linked: false, aliasCount: aliases.length };
+    }
+    if (aliases.length >= MAX_VISITOR_ALIASES) {
+      fail(
+        "LIMIT_EXCEEDED",
+        `a visitor can hold at most ${MAX_VISITOR_ALIASES} aliases`,
+        {
+          limit: MAX_VISITOR_ALIASES,
+        },
+      );
+    }
+    await ctx.db.insert("visitorAliases", {
+      siteId: args.siteId,
+      visitorId,
+      previousVisitorId,
+      linkedAt: Date.now(),
+    });
+    return { linked: true, aliasCount: aliases.length + 1 };
+  },
+});
+
+/** The identity a visitor id resolves to, followed by every alias it owns. */
+export async function resolveVisitorIdentities(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  visitorId: string,
+): Promise<string[]> {
+  const alias = await findAlias(ctx, siteId, visitorId);
+  const identity = alias?.visitorId ?? visitorId;
+  const aliases = await ctx.db
+    .query("visitorAliases")
+    .withIndex("by_siteId_and_visitorId", (range) =>
+      range.eq("siteId", siteId).eq("visitorId", identity),
+    )
+    .take(MAX_VISITOR_ALIASES);
+  return [identity, ...aliases.map((row) => row.previousVisitorId)];
+}
+
+function findAlias(
+  ctx: QueryCtx,
+  siteId: Id<"sites">,
+  previousVisitorId: string,
+) {
+  return ctx.db
+    .query("visitorAliases")
+    .withIndex("by_siteId_and_previousVisitorId", (range) =>
+      range.eq("siteId", siteId).eq("previousVisitorId", previousVisitorId),
+    )
+    .unique();
+}

package/src/component/vitals.ts

@@ -0,0 +1,146 @@
+import { VITAL_HISTOGRAM_EDGES, MAX_VITAL_VALUE } from "./constants.js";
+
+/**
+ * Field-measured Web Vitals. Values are integers: milliseconds for the time
+ * metrics, and CLS scaled by 1000 so one shared histogram covers every metric.
+ */
+export const VITAL_METRICS = ["LCP", "CLS", "INP", "FCP", "TTFB"] as const;
+
+export type VitalMetric = (typeof VITAL_METRICS)[number];
+
+/**
+ * The Google-published rating thresholds. Every threshold is also a histogram
+ * edge, so good/needs-improvement/poor counts are exact, never interpolated.
+ */
+export const VITAL_THRESHOLDS: Record<
+  VitalMetric,
+  { good: number; poor: number }
+> = {
+  LCP: { good: 2_500, poor: 4_000 },
+  CLS: { good: 100, poor: 250 },
+  INP: { good: 200, poor: 500 },
+  FCP: { good: 1_800, poor: 3_000 },
+  TTFB: { good: 800, poor: 1_800 },
+};
+
+/** Sentinel row keys; sanitized paths always start with "/" so neither collides. */
+export const VITAL_ALL = "(all)";
+export const VITAL_OTHER_PAGES = "(other)";
+
+/** Bounded device classes; anything else folds into "unknown". */
+export const VITAL_DEVICES = ["desktop", "mobile", "tablet"] as const;
+
+export function vitalDevice(device: string | undefined): string {
+  return device && (VITAL_DEVICES as readonly string[]).includes(device)
+    ? device
+    : "unknown";
+}
+
+export const VITAL_HISTOGRAM_BUCKETS = VITAL_HISTOGRAM_EDGES.length + 1;
+
+export function isVitalMetric(value: string): value is VitalMetric {
+  return (VITAL_METRICS as readonly string[]).includes(value);
+}
+
+export function isValidVitalValue(value: number): boolean {
+  return Number.isFinite(value) && value >= 0 && value <= MAX_VITAL_VALUE;
+}
+
+export function emptyVitalHistogram(): number[] {
+  return Array.from({ length: VITAL_HISTOGRAM_BUCKETS }, () => 0);
+}
+
+/** Bucket i holds values in (edge[i-1], edge[i]]; the last bucket is open. */
+export function vitalHistogramBucket(value: number): number {
+  for (let index = 0; index < VITAL_HISTOGRAM_EDGES.length; index += 1) {
+    if (value <= VITAL_HISTOGRAM_EDGES[index]) return index;
+  }
+  return VITAL_HISTOGRAM_EDGES.length;
+}
+
+export function addToVitalHistogram(
+  histogram: number[],
+  value: number,
+): number[] {
+  const next = normalizedVitalHistogram(histogram);
+  next[vitalHistogramBucket(value)] += 1;
+  return next;
+}
+
+export function mergeVitalHistograms(
+  left: number[],
+  right: number[],
+): number[] {
+  const result = normalizedVitalHistogram(left);
+  const addition = normalizedVitalHistogram(right);
+  for (let index = 0; index < result.length; index += 1) {
+    result[index] += addition[index];
+  }
+  return result;
+}
+
+/**
+ * Percentile estimated by linear interpolation inside the winning bucket. The
+ * top bucket is open-ended, so estimates saturate at the highest edge; a
+ * reported p75 equal to that edge means "at least this much".
+ */
+export function vitalHistogramPercentile(
+  histogram: number[],
+  fraction: number,
+): number {
+  const buckets = normalizedVitalHistogram(histogram);
+  const total = buckets.reduce((sum, count) => sum + count, 0);
+  if (total === 0) return 0;
+  const target = Math.ceil(total * fraction);
+  let cumulative = 0;
+  for (let index = 0; index < buckets.length; index += 1) {
+    const count = buckets[index];
+    if (count === 0) continue;
+    if (cumulative + count >= target) {
+      const lower = index === 0 ? 0 : VITAL_HISTOGRAM_EDGES[index - 1];
+      const upper =
+        index < VITAL_HISTOGRAM_EDGES.length
+          ? VITAL_HISTOGRAM_EDGES[index]
+          : VITAL_HISTOGRAM_EDGES[VITAL_HISTOGRAM_EDGES.length - 1];
+      const position = (target - cumulative) / count;
+      return Math.round(Math.min(upper, lower + position * (upper - lower)));
+    }
+    cumulative += count;
+  }
+  return VITAL_HISTOGRAM_EDGES[VITAL_HISTOGRAM_EDGES.length - 1];
+}
+
+/** Exact rating counts; every threshold is a bucket edge by construction. */
+export function vitalRatingCounts(
+  histogram: number[],
+  metric: VitalMetric,
+): { good: number; needsImprovement: number; poor: number } {
+  const buckets = normalizedVitalHistogram(histogram);
+  const thresholds = VITAL_THRESHOLDS[metric];
+  let good = 0;
+  let needsImprovement = 0;
+  let poor = 0;
+  for (let index = 0; index < buckets.length; index += 1) {
+    const upper =
+      index < VITAL_HISTOGRAM_EDGES.length
+        ? VITAL_HISTOGRAM_EDGES[index]
+        : Number.POSITIVE_INFINITY;
+    if (upper <= thresholds.good) good += buckets[index];
+    else if (upper <= thresholds.poor) needsImprovement += buckets[index];
+    else poor += buckets[index];
+  }
+  return { good, needsImprovement, poor };
+}
+
+function normalizedVitalHistogram(histogram: number[]): number[] {
+  const result = Array.from({ length: VITAL_HISTOGRAM_BUCKETS }, () => 0);
+  for (
+    let index = 0;
+    index < Math.min(histogram.length, result.length);
+    index += 1
+  ) {
+    const count = histogram[index];
+    result[index] = Number.isSafeInteger(count) && count > 0 ? count : 0;
+  }
+  return result;
+}