@iann29/rastro 0.5.0 → 0.7.0

package/src/component/reports.ts

@@ -56,7 +56,7 @@ import {
 } from "./eventStore.js";
 import { isPlainRecord } from "./guards.js";
 import { classifyOrigin } from "./origin.js";
-import { externalReferrer } from "./sanitize.js";
+import { externalReferrer, normalizeRoute } from "./sanitize.js";
 import {
   affiliateFieldsValidator,
   eventFieldsValidator,
@@ -64,8 +64,9 @@ import {
   goalFieldsValidator,
   sessionFieldsValidator,
   vitalMetricValidator,
+  visitorProfileValidator,
 } from "./validators.js";
-import { resolveVisitorIdentities } from "./visitors.js";
+import { resolveVisitorIdentities, withVisitorProfiles } from "./visitors.js";
 import {
   mergeVitalHistograms,
   VITAL_ALL,
@@ -76,6 +77,7 @@ import {
 } from "./vitals.js";
 
 const sessionDocumentValidator = sessionFieldsValidator.extend({
+  profile: v.optional(visitorProfileValidator),
   _id: v.id("sessions"),
   _creationTime: v.number(),
 });
@@ -84,6 +86,7 @@ const eventDocumentValidator = eventFieldsValidator.extend({
   _creationTime: v.number(),
 });
 const liveSessionDocumentValidator = v.object({
+  profile: v.optional(visitorProfileValidator),
   _id: v.id("liveSessions"),
   _creationTime: v.number(),
   siteId: v.id("sites"),
@@ -628,7 +631,7 @@ export const liveVisitors = query({
           .take(limit)),
       );
     }
-    return rows
+    const visible = rows
       .sort((left, right) => right.lastSeenAt - left.lastSeenAt)
       .slice(0, limit)
       .map((row) => ({
@@ -662,6 +665,7 @@ export const liveVisitors = query({
           : {}),
         ...(row.funnel ? { funnel: row.funnel } : {}),
       }));
+    return withVisitorProfiles(ctx, visible);
   },
 });
 
@@ -707,6 +711,7 @@ export const siteMap = query({
     window: v.union(v.object({ from: v.number(), to: v.number() }), v.null()),
     routes: v.array(siteMapRouteValidator),
     transitions: v.array(siteMapTransitionValidator),
+    routePatterns: v.optional(v.record(v.string(), v.array(v.string()))),
     truncated: v.object({ routes: v.boolean(), transitions: v.boolean() }),
     metadata: reportMetadataValidator.extend({
       visitors: v.object({
@@ -724,6 +729,17 @@ export const siteMap = query({
     const siteIds = validateSiteIds(args.siteIds);
     validateRange(args.from, args.to, MAX_FEATURE_ROLLUP_DAYS);
     requireAlignedRange(args.from, args.to, DAY_MS, "site map");
+    const routePatterns = Object.fromEntries(
+      await Promise.all(
+        siteIds.map(
+          async (siteId) =>
+            [
+              siteId,
+              (await ctx.db.get("sites", siteId))?.routePatterns ?? [],
+            ] as const,
+        ),
+      ),
+    );
     const controls = await Promise.all(
       siteIds.map((siteId) =>
         ctx.db
@@ -771,6 +787,7 @@ export const siteMap = query({
         window: null,
         routes: [],
         transitions: [],
+        routePatterns,
         truncated: { routes: false, transitions: false },
         metadata: metadata("unavailable"),
       };
@@ -838,7 +855,10 @@ export const siteMap = query({
     >();
     for (const row of rows) {
       if (row.bucketStart < completeFrom) continue;
-      const current = totalsFor(row.route);
+      // Apply current patterns to retained rollups too, before merging sketches.
+      const patterns = routePatterns[row.siteId];
+      const route = normalizeRoute(row.route, patterns);
+      const current = totalsFor(route);
       current.pageviews += row.pageviews;
       current.entries += row.entries;
       current.continued += row.continued;
@@ -850,10 +870,11 @@ export const siteMap = query({
         (current.daily.get(row.bucketStart) ?? 0) + row.pageviews,
       );
       for (const target of row.outgoing) {
-        const key = `${row.route}\u0000${target.route}`;
+        const to = normalizeRoute(target.route, patterns);
+        const key = `${route}\u0000${to}`;
         const edge = edges.get(key) ?? {
-          from: row.route,
-          to: target.route,
+          from: route,
+          to,
           count: 0,
         };
         edge.count += target.count;
@@ -909,6 +930,7 @@ export const siteMap = query({
       from: args.from,
       to: args.to,
       window: completeFrom > args.to ? null : { from: windowFrom, to: args.to },
+      routePatterns,
       routes: routeRows,
       transitions: transitionRows,
       truncated: {
@@ -1003,7 +1025,9 @@ export const getSession = query({
       ...result
     } = session;
     const site = await ctx.db.get("sites", args.siteId);
-    return withOrigin(result, site?.domains ?? []);
+    return (
+      await withVisitorProfiles(ctx, [withOrigin(result, site?.domains ?? [])])
+    )[0];
   },
 });
 
@@ -1150,10 +1174,11 @@ export const listSessions = query({
         ...row
       }) => withOrigin(row, site?.domains ?? []),
     );
-    return keysetPaginationResult(publicRows, pagination, (row) => ({
+    const result = keysetPaginationResult(publicRows, pagination, (row) => ({
       timestamp: row.lastSeenAt,
       creationTime: row._creationTime,
     }));
+    return { ...result, page: await withVisitorProfiles(ctx, result.page) };
   },
 });
 

package/src/component/sanitize.ts

@@ -82,6 +82,36 @@ const NUMERIC_SEGMENT = /^\d+$/;
 const UUID_SEGMENT =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const HEX_SEGMENT = /^[0-9a-f]{16,}$/i;
+const ROUTE_PARAMETER = /^:[A-Za-z][A-Za-z0-9_]*$/;
+
+/** Ordered, full-path patterns; no regex or wildcard execution from settings. */
+export function validateRoutePatterns(patterns: readonly string[]): string[] {
+  if (patterns.length > 32)
+    throw new Error("At most 32 route patterns are allowed");
+  return [
+    ...new Set(
+      patterns.map((value) => {
+        const pattern = value.trim().replace(/\/$/, "");
+        const segments = pattern.slice(1).split("/");
+        if (
+          !pattern.startsWith("/") ||
+          pattern.length > 256 ||
+          /[\s?#*\\]/.test(pattern) ||
+          !segments.some((segment) => ROUTE_PARAMETER.test(segment)) ||
+          segments.some(
+            (segment) =>
+              !segment ||
+              segment === "." ||
+              segment === ".." ||
+              (segment.includes(":") && !ROUTE_PARAMETER.test(segment)),
+          )
+        )
+          throw new Error("Use full route patterns such as /pedido/:codigo");
+        return pattern;
+      }),
+    ),
+  ];
+}
 
 /**
  * Collapses the identifiers that unmistakably vary per record — numbers,
@@ -91,10 +121,25 @@ const HEX_SEGMENT = /^[0-9a-f]{16,}$/i;
  * spellings serve the same page. Only the map uses this; every other report
  * keeps the sanitized path exactly as the tracker sent it.
  */
-export function normalizeRoute(path: string): string {
+export function normalizeRoute(
+  path: string,
+  patterns: readonly string[] = [],
+): string {
   const trimmed =
     path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
   const segments = trimmed.split("/");
+  for (const pattern of patterns) {
+    const parts = pattern.split("/");
+    if (
+      parts.length === segments.length &&
+      parts.every(
+        (part, index) =>
+          part === segments[index] ||
+          (ROUTE_PARAMETER.test(part) && Boolean(segments[index])),
+      )
+    )
+      return pattern;
+  }
   for (let index = 1; index < segments.length; index += 1) {
     const segment = segments[index] ?? "";
     if (

package/src/component/schema.ts

@@ -10,6 +10,8 @@ import {
   siteFieldsValidator,
   trackedLinkFieldsValidator,
   visitorSketchValidator,
+  visitorProfileValidator,
+  personAttributeValueValidator,
   vitalMetricValidator,
 } from "./validators.js";
 import {
@@ -395,6 +397,39 @@ export default defineSchema({
     createdAt: v.number(),
   }).index("by_key", ["key"]),
 
+  visitorProfiles: defineTable(
+    visitorProfileValidator.extend({
+      siteId: v.id("sites"),
+      searchName: v.optional(v.string()),
+      searchEmail: v.optional(v.string()),
+    }),
+  )
+    .index("by_siteId_and_visitorId", ["siteId", "visitorId"])
+    .index("by_siteId_and_searchName_and_visitorId", [
+      "siteId",
+      "searchName",
+      "visitorId",
+    ])
+    .index("by_siteId_and_searchEmail_and_visitorId", [
+      "siteId",
+      "searchEmail",
+      "visitorId",
+    ]),
+
+  visitorAttributes: defineTable({
+    siteId: v.id("sites"),
+    visitorId: v.string(),
+    key: v.string(),
+    value: personAttributeValueValidator,
+  })
+    .index("by_siteId_and_key_and_value_and_visitorId", [
+      "siteId",
+      "key",
+      "value",
+      "visitorId",
+    ])
+    .index("by_siteId_and_visitorId", ["siteId", "visitorId"]),
+
   visitorAliases: defineTable({
     siteId: v.id("sites"),
     visitorId: v.string(),

package/src/component/sites.ts

@@ -12,6 +12,7 @@ import {
   sanitizeCurrency,
   sanitizeOpaqueId,
   validateTimezone,
+  validateRoutePatterns,
 } from "./sanitize.js";
 import { siteFieldsValidator } from "./validators.js";
 
@@ -29,6 +30,7 @@ export const create = mutation({
     timezone: v.optional(v.string()),
     currency: v.optional(v.string()),
     cookieless: v.optional(v.boolean()),
+    routePatterns: v.optional(v.array(v.string())),
   },
   returns: v.id("sites"),
   handler: async (ctx, args) => {
@@ -41,6 +43,7 @@ export const create = mutation({
     let timezone: string | undefined;
     let networkId: string | undefined;
     let currency: string;
+    let routePatterns: string[];
     try {
       domains = normalizeDomains(args.domains);
       timezone = validateTimezone(args.timezone);
@@ -48,6 +51,7 @@ export const create = mutation({
         ? sanitizeOpaqueId(args.networkId, "networkId")
         : undefined;
       currency = sanitizeCurrency(args.currency ?? "USD");
+      routePatterns = validateRoutePatterns(args.routePatterns ?? []);
     } catch (error) {
       fail(
         "INVALID_SITE",
@@ -69,7 +73,10 @@ export const create = mutation({
         existing.networkId !== networkId ||
         existing.timezone !== timezone ||
         (existing.currency ?? "USD") !== currency ||
-        existing.cookieless !== cookieless
+        existing.cookieless !== cookieless ||
+        (args.routePatterns !== undefined &&
+          JSON.stringify(existing.routePatterns ?? []) !==
+            JSON.stringify(routePatterns))
       ) {
         fail(
           "CONFLICT",
@@ -99,6 +106,7 @@ export const create = mutation({
       timezone,
       currency,
       cookieless,
+      routePatterns,
       createdAt: now,
       updatedAt: now,
     });
@@ -116,6 +124,7 @@ export const update = mutation({
     timezone: v.optional(v.union(v.string(), v.null())),
     currency: v.optional(v.string()),
     cookieless: v.optional(v.boolean()),
+    routePatterns: v.optional(v.array(v.string())),
   },
   returns: v.null(),
   handler: async (ctx, args) => {
@@ -129,6 +138,7 @@ export const update = mutation({
       timezone?: string | undefined;
       currency?: string;
       cookieless?: boolean;
+      routePatterns?: string[];
       updatedAt: number;
     } = { updatedAt: Date.now() };
     if (args.name !== undefined) {
@@ -161,6 +171,9 @@ export const update = mutation({
       if (args.currency !== undefined) {
         patch.currency = sanitizeCurrency(args.currency);
       }
+      if (args.routePatterns !== undefined) {
+        patch.routePatterns = validateRoutePatterns(args.routePatterns);
+      }
     } catch (error) {
       fail(
         "INVALID_SITE",

package/src/component/validators.ts

@@ -1,5 +1,54 @@
 import { v, type Infer } from "convex/values";
 
+export const personAttributeValueValidator = v.union(
+  v.string(),
+  v.number(),
+  v.boolean(),
+);
+export const personAttributesValidator = v.record(
+  v.string(),
+  personAttributeValueValidator,
+);
+export type PersonAttributes = Infer<typeof personAttributesValidator>;
+export const personFilterValidator = v.union(
+  v.object({
+    field: v.union(
+      v.literal("name"),
+      v.literal("email"),
+      v.literal("visitorId"),
+    ),
+    prefix: v.string(),
+  }),
+  v.object({
+    field: v.literal("attribute"),
+    key: v.string(),
+    value: personAttributeValueValidator,
+  }),
+);
+export type PersonFilter = Infer<typeof personFilterValidator>;
+
+/** A profile supplied by the product's trusted backend, shared by its visits. */
+export const visitorProfileValidator = v.object({
+  visitorId: v.string(),
+  name: v.optional(v.string()),
+  email: v.optional(v.string()),
+  attributes: v.optional(personAttributesValidator),
+  identifiedAt: v.number(),
+  updatedAt: v.number(),
+});
+export type VisitorProfile = Infer<typeof visitorProfileValidator>;
+
+export const identifyVisitorFields = {
+  visitorId: v.string(),
+  previousVisitorId: v.optional(v.string()),
+  // Omission preserves the value; null explicitly removes it.
+  name: v.optional(v.union(v.string(), v.null())),
+  email: v.optional(v.union(v.string(), v.null())),
+  attributes: v.optional(
+    v.record(v.string(), v.union(personAttributeValueValidator, v.null())),
+  ),
+};
+
 export const eventTypeValidator = v.union(
   v.literal("pageview"),
   v.literal("click"),
@@ -112,6 +161,7 @@ export const siteFieldsValidator = v.object({
   timezone: v.optional(v.string()),
   currency: v.optional(v.string()),
   cookieless: v.boolean(),
+  routePatterns: v.optional(v.array(v.string())),
   createdAt: v.number(),
   updatedAt: v.number(),
 });