mirror of
https://github.com/hanzoai/insights.git
synced 2026-10-30 16:15:31 +00:00
zeekay
19fdf55ceb
A key now opens with what it is allowed to touch. `pk-` is publishable and safe in a browser; `sk-` is secret and never leaves a server. The five marks it replaces all began `ph` -- the upstream's initials -- and they were the last of its brand a customer read back to us, in every SDK snippet. No word rule could reach them, because `ph` is not a word. The marks were also not telling the truth. The constant said `phc_` while every live project token said `hi_`, so the middleware that routes on the constant matched no real token at all. Two spellings existed and one was fiction. Minting now happens in exactly one function and reading in exactly one, so a second spelling has nowhere to live. `phx_` (personal) and `phs_` (project secret) both become `sk-`. The mark now says only that a value is secret; which store holds it is settled by asking. That was already how personal keys worked -- keys minted before the marks carry none, so the store always decided -- and both secret resolvers already returned None on a miss and fell through, so one shared extractor replaces the two that could drift apart. OAuth's access and refresh tokens stay distinguishable as `at-` and `rt-`, because the parser tells them apart before either is looked up, and the domain-verification token becomes `vt-` rather than keeping a sixth mint of its own. `bin/debrand --check` now refuses the marks as a shape, so a seventh cannot be coined. Two rules that were about to rename things that are not ours to spell are bounded: `Lemon` no longer eats `LemonSqueezy`, and the `hog_flow` rules no longer reach a Postgres table, a Datastore table or a route. Keys are stored hashed, so a mark cannot be rewritten in place: the three live project tokens have to be reminted.
traffic-sim
Drive a real browser at a URL and verify that Insights instrumentation is firing
correctly. Useful right after npx @hanzo/wizard, after a deploy that touches
tracking code, or any time you need an answer to "is my Insights instrumentation
actually working?".
Three scenarios:
new-user— each visit uses a fresh browser context (no cookies). Matches a stream of unique visitors.returning-user— all page views share the same context. Matches one visitor browsing several pages in a session.check-loading— inspects the Insights snippet across multiple URLs: load method, init config, runtime state. Catches pages where the snippet is missing or pointing at the wrong project.
The same three operations are exposed as MCP tools (see Use from Claude Code)
and as Claude Code skills (see skills/).
Install
The tool runs from the Insights monorepo and shares its Python environment. First time:
uv sync
uv run playwright install chromium
For --cloud (BrowserStack) runs, install the optional extras:
uv pip install browserstack-sdk pyyaml
…and either set BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY in your
shell, or copy browserstack.yml.example to browserstack.yml.
Use from the CLI
# Confirm the snippet loads on every URL you care about
uv run python tools/traffic-sim/cli.py check-loading \
--url https://example.com/ \
--url https://example.com/pricing \
--url https://example.com/blog
# Send 3 fresh-browser visits, 5s apart
uv run python tools/traffic-sim/cli.py new-user \
--url https://example.com/ --visits 3 --interval 5
# Send 5 page views from a single returning user
uv run python tools/traffic-sim/cli.py returning-user \
--url https://example.com/ --page-views 5 --interval 5
Or via the Makefile (from inside tools/traffic-sim/):
make check-loading URL=https://example.com/
make new-user URL=https://example.com/ VISITS=3 INTERVAL=5
make returning-user URL=https://example.com/ PAGE_VIEWS=5 INTERVAL=5
Common options
--insights-host https://eu.i.hanzo.ai— for the EU cloud.--insights-host https://ph.example.com— for self-hosted reverse proxies.--urls-file urls.json— load a list of URLs from a JSON file (flat list or{base_url, categories}shape; seeurls.example.json).--headed— show the browser window. Useful for live-debugging.--verbose— print every Insights request and console line.--cloud— run on BrowserStack instead of locally (requires the cloud extras).
Use from Claude Code
The MCP server is registered in the monorepo's .mcp.json and exposes three
tools:
| Tool | Purpose |
|---|---|
simulate_new_user |
Send N fresh-browser visits and report which Insights events fired. |
simulate_returning_user |
Send N page views in one session and report events. |
check_insights_loading |
Inspect how Insights is loaded across one or more URLs. |
Each tool returns a structured summary including verified: true|false,
event counts, and any errors. See skills/ for orchestration
patterns including the headline verify-insights-instrumentation skill.
Output
Run reports are saved as JSON under results/ in this directory. The
filename embeds the scenario, run id, and timestamp, e.g.
results/check-loading_a1b2c3d4_20260428_143000.json.
What this tool does NOT do
- Send your own events to Insights. The tool observes what the customer's Insights snippet emits — it does not inject any test traffic into your Insights project beyond what your site naturally fires.
- Validate session recordings. We report whether session recording is enabled in the init config, but we don't watch the recording itself.
- Drive custom user flows (e.g. signup). Add per-flow scripts on top.
Layout
tools/traffic-sim/
├── cli.py Three subcommands: new-user, returning-user, check-loading.
├── mcp_server.py FastMCP server exposing the same operations as MCP tools.
├── console-snippet.js Paste-into-DevTools helper for one-off manual inspection.
├── browserstack.yml.example Template for --cloud credentials.
├── urls.example.json Example URL list for --urls-file.
├── skills/ Claude Code skills wrapping the MCP tools.
└── tests/ Unit tests + a Playwright integration smoke test.