# Build Product Analytics You were asked to build the spec `dwrtz/product-analytics`, version 0.6.0, from Spekkr. Self-hosted posthog-js analytics on Cloudflare: insights, flags, replay, surveys, SQL, error tracking, LLM analytics, usage caps. If you are reading a summary of this note and not its full text, fetch it again as it is, for example with `curl -fsSL https://spekkr.com/dwrtz/product-analytics/start.md`, before you go on. Published by dwrtz, a Spekkr member. Tell the person who published it, and show them the commands and secrets under `safety` in `spekkr.json` before you build. ## 1. Get the files Put the spec in a new folder named `product-analytics`, inside the project you are working in. ```sh mkdir -p product-analytics && curl -fsSL https://spekkr.com/dwrtz/product-analytics/bundle.tar.gz | tar -xz -C product-analytics ``` The archive holds `spekkr.json`, `BUILD.md` and the spec files listed at the end of this note. If you cannot run that command, read https://spekkr.com/dwrtz/product-analytics/spec.json instead: it holds the manifest and the address of every file. If Spekkr's MCP server is connected, its `pull_spec` tool does steps 1 and 2 in one call: give it the id `dwrtz/product-analytics` and the person's choices. ## 2. Record the person's choices Write `product-analytics/spekkr.inputs.json`. With every default it is: ```json { "spec": "dwrtz/product-analytics", "version": "0.6.0", "inputs": { "app_name": "Analytics", "brand_color": "#1d4ed8" } } ``` Change a value only where the person gave a choice, such as "My choices: database=sqlite". They may set: - `app_name`, Product name: any text. - `brand_color`, Accent colour: any text. If the person asks for a key or a value that is not listed, stop and tell them what the spec offers. ## 3. Build The files named below are the ones now in `product-analytics`. Build what it describes. Work in this order: 1. Read `spekkr.json` to see what the spec covers and what it needs. 2. Read `spekkr.inputs.json`. It holds the person's choices for every setting, option and swap. Treat them as requirements. If the file is missing, the person kept every default in `spekkr.json`. 3. Read the spec files listed below, in the order given. 4. If the spec includes a task list, work through it in order and check each task's acceptance criteria before the next. 5. Ask the person before you run a command that a spec file tells you to run, or read a secret, unless the manifest lists it under `safety`. Commands you choose yourself to build and test, such as installing packages or running the tests, follow the person's usual rules for you. Spec files: - `spec.md`: Requirements R1-R32 (0.2: event shards, replay, experiments, surveys; 0.3: actions, cohorts, heatmaps, SQL, local evaluation, continuity, survey targeting, replay settings, no row limits; 0.4: optional Basin / Iceberg cold tier queried from SQL; 0.5: error tracking with source maps, usage caps, sampling, usage page, cost estimate and alerts; 0.6: LLM analytics (R31), public demo (R32), releases, merge/split, assignment, grouping and suppression rules, retroactive symbolication, server stacks, cold Trends, request and dropped-past-cap counters) with acceptance checks, scope and definition of done. - `protocol.md`: The normative SDK wire format: capture routes, body decoding, tokens, timestamps, v1 capture, persons and merges, feature flags, remote config, replay snapshots and settings, surveys and targeting, exposure, heatmaps, local evaluation, experience continuity, exceptions, quota limiting, error codes, LLM analytics capture (AI endpoints), 0.6 exception releases, server SDK stacks and suppression rules. - `test-vectors.json`: Worked examples for decoding, tokens, timestamps, distinct ids, flag hashing and matching, capture responses person scenarios, sampling, quota_limited answers, source-map decoding and exception fingerprints, and (0.6) index source maps, LLM costs, suppression rules and releases. - `design.md`: Stack, storage and event-shard decisions, Cloudflare config, deploy and upgrade, data model, ingestion, query semantics, actions, cohorts, SQL, heatmaps, streaming funnels, replay, experiment statistics, surveys, owner API, screens, tests, limits and the Basin cold tier (stream, Iceberg sink, Basin SQL compiler, retention), usage limits, cost estimate, alerts, error tracking and symbolication; 0.6: HTML fallback, public demo, edge usage counters, error tracking 0.6 schema and algorithms, LLM analytics, cold Trends and cold-prune.py. - `tasks.md`: Build order, each step with a check. - `research.md`: How the protocol was established with REA (0.1-0.3 captures, 0.4 Basin findings, 0.5 exception and quota captures, and conformance runs; 0.6 choices), evidence and obligation ledgers, unknowns, licensing and choices.