@iann29/rastro 0.1.0-alpha.0

package/src/component/sites.ts

@@ -0,0 +1,188 @@
+import { v } from "convex/values";
+import { internalQuery, mutation, query } from "./_generated/server.js";
+import { MAX_SITES_PER_OWNER } from "./constants.js";
+import { fail } from "./errors.js";
+import {
+  cleanString,
+  normalizeDomains,
+  originAllowed,
+  sanitizeCurrency,
+  sanitizeOpaqueId,
+  validateTimezone,
+} from "./sanitize.js";
+import { siteFieldsValidator } from "./validators.js";
+
+const siteDocumentValidator = siteFieldsValidator.extend({
+  _id: v.id("sites"),
+  _creationTime: v.number(),
+});
+
+export const create = mutation({
+  args: {
+    ownerId: v.string(),
+    name: v.string(),
+    domains: v.array(v.string()),
+    networkId: v.optional(v.string()),
+    timezone: v.optional(v.string()),
+    currency: v.optional(v.string()),
+    cookieless: v.optional(v.boolean()),
+  },
+  returns: v.id("sites"),
+  handler: async (ctx, args) => {
+    const ownerId = cleanString(args.ownerId, 128);
+    const name = cleanString(args.name, 120);
+    if (!ownerId || !name) fail("INVALID_SITE", "ownerId and name are required");
+
+    const existing = await ctx.db
+      .query("sites")
+      .withIndex("by_ownerId_and_name", (range) =>
+        range.eq("ownerId", ownerId).eq("name", name),
+      )
+      .unique();
+    if (existing) return existing._id;
+
+    const sites = await ctx.db
+      .query("sites")
+      .withIndex("by_ownerId", (range) => range.eq("ownerId", ownerId))
+      .take(MAX_SITES_PER_OWNER + 1);
+    if (sites.length >= MAX_SITES_PER_OWNER) {
+      fail("LIMIT_EXCEEDED", "site limit reached", {
+        limit: MAX_SITES_PER_OWNER,
+      });
+    }
+
+    let domains: string[];
+    let timezone: string | undefined;
+    let networkId: string | undefined;
+    let currency: string;
+    try {
+      domains = normalizeDomains(args.domains);
+      timezone = validateTimezone(args.timezone);
+      networkId = args.networkId
+        ? sanitizeOpaqueId(args.networkId, "networkId")
+        : undefined;
+      currency = sanitizeCurrency(args.currency ?? "USD");
+    } catch (error) {
+      fail("INVALID_SITE", error instanceof Error ? error.message : "invalid site");
+    }
+    const now = Date.now();
+    return await ctx.db.insert("sites", {
+      ownerId,
+      name,
+      domains,
+      networkId,
+      timezone,
+      currency,
+      cookieless: args.cookieless ?? true,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const update = mutation({
+  args: {
+    siteId: v.id("sites"),
+    name: v.optional(v.string()),
+    domains: v.optional(v.array(v.string())),
+    networkId: v.optional(v.union(v.string(), v.null())),
+    timezone: v.optional(v.union(v.string(), v.null())),
+    currency: v.optional(v.string()),
+    cookieless: v.optional(v.boolean()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const site = await ctx.db.get("sites", args.siteId);
+    if (!site) fail("NOT_FOUND", "site not found");
+
+    const patch: {
+      name?: string;
+      domains?: string[];
+      networkId?: string | undefined;
+      timezone?: string | undefined;
+      currency?: string;
+      cookieless?: boolean;
+      updatedAt: number;
+    } = { updatedAt: Date.now() };
+    if (args.name !== undefined) {
+      const name = cleanString(args.name, 120);
+      if (!name) fail("INVALID_SITE", "name is required");
+      const existing = await ctx.db
+        .query("sites")
+        .withIndex("by_ownerId_and_name", (range) =>
+          range.eq("ownerId", site.ownerId).eq("name", name),
+        )
+        .unique();
+      if (existing && existing._id !== site._id) {
+        fail("CONFLICT", "another site already uses this name");
+      }
+      patch.name = name;
+    }
+    try {
+      if (args.domains !== undefined) patch.domains = normalizeDomains(args.domains);
+      if (args.timezone !== undefined) {
+        patch.timezone = args.timezone === null
+          ? undefined
+          : validateTimezone(args.timezone);
+      }
+      if (args.networkId !== undefined) {
+        patch.networkId = args.networkId === null
+          ? undefined
+          : sanitizeOpaqueId(args.networkId, "networkId");
+      }
+      if (args.currency !== undefined) {
+        patch.currency = sanitizeCurrency(args.currency);
+      }
+    } catch (error) {
+      fail("INVALID_SITE", error instanceof Error ? error.message : "invalid site");
+    }
+    if (
+      patch.currency !== undefined &&
+      site.currency !== undefined &&
+      site.currency !== patch.currency
+    ) {
+      fail("CONFLICT", "site currency cannot be changed");
+    }
+    if (args.cookieless !== undefined) patch.cookieless = args.cookieless;
+    await ctx.db.patch("sites", args.siteId, patch);
+    return null;
+  },
+});
+
+export const get = query({
+  args: { siteId: v.id("sites") },
+  returns: v.union(siteDocumentValidator, v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.db.get("sites", args.siteId);
+  },
+});
+
+export const listByOwner = query({
+  args: {
+    ownerId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(siteDocumentValidator),
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 50;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+      fail("INVALID_ARGUMENT", "limit must be an integer between 1 and 100");
+    }
+    return await ctx.db
+      .query("sites")
+      .withIndex("by_ownerId", (range) =>
+        range.eq("ownerId", cleanString(args.ownerId, 128)),
+      )
+      .order("desc")
+      .take(limit);
+  },
+});
+
+export const checkOrigin = internalQuery({
+  args: { siteId: v.id("sites"), origin: v.string() },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const site = await ctx.db.get("sites", args.siteId);
+    return site !== null && originAllowed(args.origin, site.domains);
+  },
+});

package/src/component/validators.ts

@@ -0,0 +1,226 @@
+import { v, type Infer } from "convex/values";
+
+export const eventTypeValidator = v.union(
+  v.literal("pageview"),
+  v.literal("click"),
+  v.literal("custom"),
+  v.literal("conversion"),
+  v.literal("heartbeat"),
+  v.literal("outbound"),
+);
+
+export const propertyValueValidator = v.union(
+  v.string(),
+  v.number(),
+  v.boolean(),
+  v.null(),
+);
+
+export const eventPropertiesValidator = v.record(
+  v.string(),
+  propertyValueValidator,
+);
+
+export const trackerEventValidator = v.object({
+  eventId: v.string(),
+  sessionId: v.string(),
+  visitorId: v.string(),
+  type: eventTypeValidator,
+  name: v.optional(v.string()),
+  path: v.string(),
+  referrer: v.optional(v.string()),
+  timestamp: v.number(),
+  sequence: v.number(),
+  target: v.optional(v.string()),
+  href: v.optional(v.string()),
+  properties: v.optional(eventPropertiesValidator),
+  revenueCents: v.optional(v.number()),
+  currency: v.optional(v.string()),
+  affiliateSlug: v.optional(v.string()),
+});
+
+export const ingestContextValidator = v.object({
+  country: v.optional(v.string()),
+  city: v.optional(v.string()),
+  latitude: v.optional(v.number()),
+  longitude: v.optional(v.number()),
+  browser: v.optional(v.string()),
+  os: v.optional(v.string()),
+  device: v.optional(v.string()),
+});
+
+export const siteFieldsValidator = v.object({
+  ownerId: v.string(),
+  name: v.string(),
+  domains: v.array(v.string()),
+  networkId: v.optional(v.string()),
+  timezone: v.optional(v.string()),
+  currency: v.optional(v.string()),
+  cookieless: v.boolean(),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+export const sessionFieldsValidator = v.object({
+  siteId: v.id("sites"),
+  sessionId: v.string(),
+  visitorId: v.string(),
+  startedAt: v.number(),
+  lastSeenAt: v.number(),
+  entryPath: v.string(),
+  exitPath: v.string(),
+  referrer: v.optional(v.string()),
+  source: v.string(),
+  utmSource: v.optional(v.string()),
+  utmMedium: v.optional(v.string()),
+  utmCampaign: v.optional(v.string()),
+  country: v.optional(v.string()),
+  city: v.optional(v.string()),
+  latitude: v.optional(v.number()),
+  longitude: v.optional(v.number()),
+  browser: v.string(),
+  os: v.string(),
+  device: v.string(),
+  eventCount: v.number(),
+  pageviewCount: v.number(),
+  durationMs: v.number(),
+  conversionCount: v.number(),
+  revenueCents: v.number(),
+  currency: v.optional(v.string()),
+  affiliateSlug: v.optional(v.string()),
+  affiliateId: v.optional(v.id("affiliates")),
+  affiliateAttributedAt: v.optional(v.number()),
+  affiliateExpiresAt: v.optional(v.number()),
+});
+
+export const eventFieldsValidator = v.object({
+  siteId: v.id("sites"),
+  eventId: v.string(),
+  sessionId: v.string(),
+  visitorId: v.string(),
+  type: eventTypeValidator,
+  name: v.optional(v.string()),
+  path: v.string(),
+  referrer: v.optional(v.string()),
+  timestamp: v.number(),
+  sequence: v.number(),
+  target: v.optional(v.string()),
+  href: v.optional(v.string()),
+  properties: v.optional(eventPropertiesValidator),
+  revenueCents: v.optional(v.number()),
+  currency: v.optional(v.string()),
+  affiliateSlug: v.optional(v.string()),
+  country: v.optional(v.string()),
+  city: v.optional(v.string()),
+  latitude: v.optional(v.number()),
+  longitude: v.optional(v.number()),
+  browser: v.string(),
+  os: v.string(),
+  device: v.string(),
+});
+
+export const dimensionTypeValidator = v.union(
+  v.literal("source"),
+  v.literal("page"),
+  v.literal("country"),
+  v.literal("device"),
+  v.literal("browser"),
+  v.literal("event"),
+  v.literal("goal"),
+);
+
+export const dimensionSlotValidator = v.object({
+  type: dimensionTypeValidator,
+  slot: v.number(),
+  value: v.string(),
+  count: v.number(),
+  revenueCents: v.number(),
+});
+
+export const aggregateFieldsValidator = v.object({
+  siteId: v.id("sites"),
+  granularity: v.union(v.literal("hour"), v.literal("day")),
+  bucketStart: v.number(),
+  shard: v.number(),
+  events: v.number(),
+  pageviews: v.number(),
+  clicks: v.number(),
+  customEvents: v.number(),
+  outboundClicks: v.number(),
+  sessions: v.number(),
+  visitors: v.number(),
+  conversions: v.number(),
+  revenueCents: v.number(),
+  dimensions: v.array(dimensionSlotValidator),
+});
+
+export const goalMatchTypeValidator = v.union(
+  v.literal("pageview"),
+  v.literal("custom"),
+);
+
+export const goalFieldsValidator = v.object({
+  siteId: v.id("sites"),
+  key: v.string(),
+  name: v.string(),
+  matchType: goalMatchTypeValidator,
+  matchValue: v.string(),
+  valueCents: v.optional(v.number()),
+  active: v.boolean(),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+export const funnelStepValidator = v.object({
+  type: v.union(v.literal("pageview"), v.literal("custom")),
+  value: v.string(),
+  name: v.string(),
+});
+
+export const funnelFieldsValidator = v.object({
+  siteId: v.id("sites"),
+  key: v.string(),
+  name: v.string(),
+  steps: v.array(funnelStepValidator),
+  conversionWindowMs: v.number(),
+  active: v.boolean(),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+export const affiliateFieldsValidator = v.object({
+  siteId: v.id("sites"),
+  slug: v.string(),
+  name: v.string(),
+  commissionBps: v.number(),
+  attributionWindowDays: v.number(),
+  active: v.boolean(),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+export const ingestResultValidator = v.object({
+  accepted: v.number(),
+  duplicates: v.number(),
+  rejected: v.number(),
+});
+
+export const trustedConversionValidator = v.object({
+  siteId: v.id("sites"),
+  eventId: v.string(),
+  sessionId: v.string(),
+  visitorId: v.string(),
+  timestamp: v.number(),
+  revenueCents: v.number(),
+  currency: v.string(),
+  path: v.optional(v.string()),
+  goalKey: v.optional(v.string()),
+  properties: v.optional(eventPropertiesValidator),
+});
+
+
+export type TrackerEvent = Infer<typeof trackerEventValidator>;
+export type IngestContext = Infer<typeof ingestContextValidator>;
+export type EventProperties = Infer<typeof eventPropertiesValidator>;
+export type FunnelStep = Infer<typeof funnelStepValidator>;
+export type EventType = Infer<typeof eventTypeValidator>;

package/src/test.ts

@@ -0,0 +1,19 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+export { schema, modules };
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "rastroAnalytics",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };