{
  "manifest": {
    "spekkr": 1,
    "id": "dwrtz/product-analytics",
    "name": "Product Analytics",
    "summary": "Self-hosted posthog-js analytics on Cloudflare: insights, flags, replay, surveys, SQL, error tracking, LLM analytics, usage caps.",
    "keywords": [
      "product analytics",
      "posthog-js compatible",
      "session replay",
      "usage limits",
      "error tracking",
      "llm analytics",
      "experiments",
      "surveys",
      "feature flags",
      "iceberg cold tier",
      "self-hosted",
      "cloudflare workers"
    ],
    "kind": "web app",
    "version": "0.6.0",
    "author": {
      "id": "dwrtz",
      "name": "David Wurtz"
    },
    "targets": {
      "platforms": [
        "web",
        "backend"
      ],
      "stack": [
        "TypeScript",
        "Cloudflare Workers",
        "Cloudflare Durable Objects (SQLite)",
        "Cloudflare D1",
        "Cloudflare Queues",
        "Cloudflare R2",
        "Cloudflare Basin (Pipelines, Catalog, SQL)",
        "Wrangler",
        "lz-string",
        "posthog-js",
        "rrweb-player",
        "esbuild",
        "Vitest",
        "Playwright",
        "posthog-node",
        "Cloudflare Email Sending (optional)",
        "PyIceberg (optional cold-tier pruning)"
      ]
    },
    "customize": {
      "settings": [
        {
          "key": "app_name",
          "label": "Product name",
          "default": "Analytics",
          "help": "Shown in the web app's title, nav and sign-in screen."
        },
        {
          "key": "brand_color",
          "label": "Accent colour",
          "default": "#1d4ed8",
          "help": "As #rrggbb. Primary buttons, links and the first chart series."
        }
      ]
    },
    "files": [
      {
        "path": "spec.md",
        "about": "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."
      },
      {
        "path": "protocol.md",
        "about": "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."
      },
      {
        "path": "test-vectors.json",
        "about": "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."
      },
      {
        "path": "design.md",
        "about": "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."
      },
      {
        "path": "tasks.md",
        "about": "Build order, each step with a check."
      },
      {
        "path": "research.md",
        "about": "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."
      }
    ],
    "needs": {
      "permissions": [
        "shell",
        "network"
      ]
    },
    "demo": {
      "screenshots": [
        "shots/dashboard.png",
        "shots06/llm-analytics.png",
        "shots06/llm-trace.png",
        "shots06/error-tracking.png",
        "shots06/usage.png",
        "shots06/public-demo.png",
        "shots05/error-issue.png",
        "shots/replay-player.png",
        "shots/experiment-results.png",
        "shots/survey-results.png",
        "shots03/heatmap-clicks.png",
        "shots04/sql-cold.png"
      ]
    },
    "safety": {
      "commands": [
        "npm install",
        "npx wrangler d1 migrations apply DB --local",
        "npx wrangler dev",
        "npm test",
        "npm run e2e",
        "npx playwright install chromium"
      ]
    },
    "lineage": {},
    "changelog": [
      {
        "version": "0.6.0",
        "date": "2026-11-20",
        "note": "LLM analytics: $ai_generation/$ai_trace/$ai_span/$ai_embedding events from the PostHog AI SDKs (standard capture plus /i/v0/ai/batch, multipart /i/v0/ai and /i/v1/ai/events) with an overview (generations, tokens, cost from the SDK or a built-in price table, p50/p95 latency, errors, models), a filtered traces list and a trace page with a span tree and latency waterfall. Error tracking gains releases ($release/$app_version) with per-release source maps and retroactive symbolication on upload, merge and split, assignment, custom grouping rules, suppression rules sent to posthog-js remote config and enforced at ingest, Python/Go/Rust stacks and index (sectioned) source maps. Trends can read the Basin cold tier (Hot/Cold source), and scripts/cold-prune.py physically prunes cold rows past retention with PyIceberg. Usage counts flags, config and API requests and events/requests dropped past a cap, and the cost estimate leads with list price. Optional PUBLIC_DEMO=1 read-only demo mode with redaction; deep links serve the app. Upgrade: apply D1 migration 0005_v06.sql (projects.public_demo); Durable Objects upgrade themselves."
      },
      {
        "version": "0.5.0",
        "date": "2026-11-19",
        "note": "Error tracking: $exception events from posthog-js and posthog-node are grouped into issues by fingerprint (type plus top in-app frames, or $exception_fingerprint), with status, first/last seen, occurrences, affected users, stack traces symbolicated from uploaded source maps (API plus upload script), person and replay links, new-issue and regression alerts, and exception autocapture served in remote config. Usage: per-project monthly caps on events, recordings and replay bytes with drop or sample past the cap and quota_limited answers so posthog-js pauses; autocapture and replay sampling defaults for new projects; a Usage page with events per day by type, replay volume and an estimated Cloudflare cost; alerts at 50/80/100% of a cap and on daily spikes, in the app and optionally by Cloudflare Email Sending. D1 migration 0004_v05.sql."
      },
      {
        "version": "0.4.2",
        "date": "2026-11-19",
        "note": "Ingest-only hostnames are now opt-in: every hostname serves the full app unless listed in the new optional INGEST_HOSTS var, which keeps the 0.4.1 behaviour (SDK endpoints, /static and /_health only; pages redirect to SITE_URL). design.md recommends one instance per measured site on its own subdomain."
      },
      {
        "version": "0.4.1",
        "date": "2026-11-19",
        "note": "A Worker can serve extra hostnames, such as a first-party ingest subdomain on the measured site: SDK endpoints, /static and /_health answer on every host, while dashboard pages redirect to SITE_URL and other owner API writes there get 421, so sign-in and cookies stay on one origin. No config change."
      },
      {
        "version": "0.4.0",
        "date": "2026-11-19",
        "note": "Optional cold tier on Cloudflare Basin: every ingested event is also streamed through a Basin Pipelines Worker binding into an Apache Iceberg table in R2 (Basin Catalog), and the SQL editor gains a Cold source that compiles the same query language to Basin SQL with the project and retention filters always applied. Off unless the COLD_STREAM binding, BASIN_* vars and BASIN_TOKEN secret are set; upgrades a 0.3 instance in place (no D1 migration)."
      },
      {
        "version": "0.3.0",
        "date": "2026-11-18",
        "note": "Actions (CSS selector, text, href, URL matchers), static and dynamic cohorts usable as filters in insights, flags, surveys and experiments, click/rage/dead-click/mouse-move heatmaps and scroll depth over the live page or a recording, a read-only SQL editor across shards, posthog-node local evaluation, experience continuity, survey targeting/iterations/partial responses, replay sampling/triggers/network/console/canvas settings with paged playback, and streaming funnels and surveys without row limits. Upgrades a 0.2 instance in place (D1 0003, hourly cron)."
      },
      {
        "version": "0.2.0",
        "date": "2026-11-18",
        "note": "Session replay (posthog-js recorder, R2 chunks, rrweb-player), experiments (multivariate flags, Bayesian results), surveys (posthog-js /api/surveys, results) and time-sharded event storage past 10 GB per project with exact counts. Upgrades a 0.1 instance in place."
      },
      {
        "version": "0.1.1",
        "date": "2026-11-18",
        "note": "posthog-js is credited with its actual licence (Apache-2.0 and MIT). The e2e flag check waits for the flags reload after identify, so it also passes against a deployed instance over the network."
      },
      {
        "version": "0.1.0",
        "date": "2026-11-18",
        "note": "First version."
      }
    ]
  },
  "links": {
    "page": "./",
    "bundle": "bundle.tar.gz",
    "files": {
      "design.md": "files/design.md",
      "protocol.md": "files/protocol.md",
      "research.md": "files/research.md",
      "shots/dashboard.png": "files/shots/dashboard.png",
      "shots/experiment-results.png": "files/shots/experiment-results.png",
      "shots/replay-player.png": "files/shots/replay-player.png",
      "shots/survey-results.png": "files/shots/survey-results.png",
      "shots03/heatmap-clicks.png": "files/shots03/heatmap-clicks.png",
      "shots04/sql-cold.png": "files/shots04/sql-cold.png",
      "shots05/error-issue.png": "files/shots05/error-issue.png",
      "shots06/error-tracking.png": "files/shots06/error-tracking.png",
      "shots06/llm-analytics.png": "files/shots06/llm-analytics.png",
      "shots06/llm-trace.png": "files/shots06/llm-trace.png",
      "shots06/public-demo.png": "files/shots06/public-demo.png",
      "shots06/usage.png": "files/shots06/usage.png",
      "spec.md": "files/spec.md",
      "tasks.md": "files/tasks.md",
      "test-vectors.json": "files/test-vectors.json"
    }
  },
  "publishedBy": "dwrtz",
  "uploaded": {
    "design.md": {
      "bytes": 86951,
      "type": "text/plain; charset=utf-8"
    },
    "shots/dashboard.png": {
      "bytes": 107900,
      "type": "image/png"
    },
    "shots/experiment-results.png": {
      "bytes": 93630,
      "type": "image/png"
    },
    "shots/replay-player.png": {
      "bytes": 98754,
      "type": "image/png"
    },
    "shots/survey-results.png": {
      "bytes": 163067,
      "type": "image/png"
    },
    "shots03/heatmap-clicks.png": {
      "bytes": 161004,
      "type": "image/png"
    },
    "shots04/sql-cold.png": {
      "bytes": 76130,
      "type": "image/png"
    },
    "shots05/error-issue.png": {
      "bytes": 306862,
      "type": "image/png"
    },
    "shots06/error-tracking.png": {
      "bytes": 142045,
      "type": "image/png"
    },
    "shots06/llm-analytics.png": {
      "bytes": 137458,
      "type": "image/png"
    },
    "shots06/llm-trace.png": {
      "bytes": 95961,
      "type": "image/png"
    },
    "shots06/public-demo.png": {
      "bytes": 127722,
      "type": "image/png"
    },
    "shots06/usage.png": {
      "bytes": 104740,
      "type": "image/png"
    },
    "spec.md": {
      "bytes": 48607,
      "type": "text/plain; charset=utf-8"
    },
    "test-vectors.json": {
      "bytes": 51286,
      "type": "text/plain; charset=utf-8"
    }
  }
}
