@407dev/events

Purpose

Published shared event schema, path normalization, wire layouts, queries, and beacon snippet builder for the platform's first-party analytics stack. Used across client site ingestion (@407dev/site-services), sink workers (apps/analytics-sink), API aggregation (apps/api), and the editor UI (apps/web).

Surface

• EVENT_SCHEMA_VERSION = 2 — frozen v2 schema version (src/schema.ts).
• parseIngestPayload(raw) / sanitizeProps(raw) — ingest validation, vitals metric extraction, and props key/byte capping.
• normalizeEventPath(rawUrl, opts) / referrerHost(raw, selfHost) — path, referrer, and UTM normalization (src/normalize.ts).
• toDataPoint(event) / fromDataPoint(row) — WAE column and double mappings (src/wire.ts).
• INSIGHTS_QUERIES, renderChannelCaseExpr(flavor), renderWaeSql(name, params), renderD1Sql(name, params) — named queries and SQL renderers (src/queries.ts).
• buildVisitorJourney(rows) — pure session grouping, dwell time calculation, and activity histogram construction (src/journey.ts).
• classifyUserAgent(ua) — lightweight User-Agent classifier for coarse browser, OS, and device categories (src/ua.ts).
• WEB_VITALS_THRESHOLDS, getVitalsRating(metric, value), computeExperienceScore(distMap) — Web Vitals thresholds, ratings, and experience score (src/vitals.ts).
• encodeArchiveBatch(events) / archiveObjectKey(siteId, date, id) — gzipped NDJSON archiving (src/ndjson.ts).
• buildBeaconSnippet(opts) / buildVitalsSnippet(opts) — browser tracking and Web Vitals script generators (src/snippet.ts).
• VITALS_BUNDLE_PATH, VITALS_BUNDLE_HASH, VITALS_BUNDLE_CODE, VITALS_PACKAGE_VERSION — build-time compiled web-vitals/attribution ESM asset and version metadata (src/vitalsBundle.generated.ts).
• PARQUET_SCHEMA_VERSION = 2, ROLLUP_SCHEMA_VERSION = 1, PARQUET_COLUMNS, DEEP_QUERIES, ROLLUP_QUERIES, renderDuckDbSql(name, params, files) — Parquet compaction schema, month rollups, and deep/all-time DuckDB SQL generation (src/deep.ts).
• PRIVACY_COLLECTION_MODEL — shared privacy model definitions (src/privacy.ts).

Patterns

• Ingest payload parsing: validates input shape, extracts u/r/e/p/vitals metrics, caps props to 8 keys and 512 bytes.
• Path normalization: lifts utm_* query parameters, strips fragments, normalizes trailing slashes, caps length at 128 characters, and collapses UUID/numeric segments.
• Query allowlist: callers supply named queries rather than arbitrary SQL; renderers inject site scoping, date boundaries, and city suppression floors safely.
• Snippet budgets: base beacon builder tested against strict <= 2048 B gzipped ceiling; vitals beacon builder <= 1024 B gzipped ceiling.

Integrations

• Consumed by @407dev/site-services for /_ev ingestion, identity hashing, UA classification, and D1 mirror rendering.
• Consumed by apps/analytics-sink for queue message decoding and R2 NDJSON/manifest writing.
• Consumed by apps/api for WAE SQL query rendering, vitals reshaping, and insights aggregation.
• Consumed by apps/web for shared types, vitals calculations, and privacy disclosures.

Constraints

• Nothing here may import from apps/* or private packages.
• Public npm package — API surface changes require a changeset.
• Must remain compatible with Cloudflare Workers, Node.js, and modern browser runtimes.

Gotchas

• Do not reuse normalizePath from @407dev/config — that normalizes CMS route keys, whereas normalizeEventPath handles URL search params, collapse patterns, and UTM lifting.
• WAE allows exactly one index (site); all other dimensions map to blobs 1..18 and doubles 1..7 (missing/unmeasured doubles store -1).