Analytics
Overview
rocketride/analytics mints bound per-app event reporters, bare bones by
design. A host (the platform shell) creates one reporter per app with
createReporter(app, sink) and hands it over; the app calls
report(event, props, options?) with any string event name and a free-form
props bag. There is no central event list: each app owns its own taxonomy
(home-ui keeps its event names in its own repo, the VS Code extension keeps
its own, and so on). What the shared layer guarantees is that every reported
event carries an app property identifying the emitting app, fixed at
creation — there is no module-global "current app" state, so a late event
from a backgrounded app still names its true emitter. The Python mirror lives
at rocketride.analytics in the Python SDK.
Apps running on the platform shell do not call createReporter themselves —
the shell mints their reporter and hands it over (useReport() from the shell
API). The shell stamps the app descriptor's
id, or its optional telemetryId alias (for apps whose dashboards predate
the descriptor id). The alias is honoured only for first-party apps (id
rocketride or starting rocketride.). It must match
^[A-Za-z0-9._-]{1,128}$, must not be shell, and must not be another
registered app's id. Otherwise the shell stamps the id, with no warning. The
alias is chosen once on the descriptor, never per event. Creating reporters directly is for hosts and for standalone code
with its own transport.
Import
import { createReporter, type Reporter, type ReportSink, type SendOptions } from 'rocketride/analytics';
API
// The HOST mints one reporter per app. The sink is whatever function ships
// events (the shell's capture queue, HTTP, a logger, ...).
const report = createReporter('rocket-ui', (event, props, options) => mySink.send(event, props, options));
// The app just calls it:
report('nav:click', { target: 'pricing' });
// → sink receives ('nav:click', { app: 'rocket-ui', target: 'pricing' }, undefined)
createReporter(app, sink)— returns the app's boundreport. Theappstamp is closed over for the reporter's lifetime and is stamped last, so caller props can never overwrite it.report(event, props?, options?)— forwards to the sink withappstamped into the props. Enforcement is string-ish only: a non-string or empty event name is a silent no-op, and nothing else is validated. It never throws — telemetry must never break the app.
Capture Options
The optional third argument passes delivery hints to sinks that understand them (sinks that don't simply ignore the argument):
type SendOptions = { transport?: 'sendBeacon'; timestamp?: Date; uuid?: string };
transport: 'sendBeacon'— the page may be torn down a moment later (a CTA that starts an OAuth redirect): ask for teardown-surviving delivery.timestamp— back-date a replayed event to when it was observed.uuid— make the capture idempotent, so an at-least-once replay dedupes instead of double-counting.
Event Names
By convention event names are object:action — lowercase, colon-separated
(chat:message_sent, store:app_add). The convention is documentation, not
enforcement: report() accepts any string so an app can evolve its taxonomy
without touching this module. Each app should keep its own documented event
list next to its call sites.
What This Module Is Not
It is not a taxonomy and not a transport. There is no event-name union, no
typed property shapes, no PostHog dependency, and no network I/O — the sink a
host injects does the sending. Earlier revisions centralised a strict
cross-app taxonomy and, later, a module-global initReport(app, sink); both
were removed — the taxonomy in favour of per-app ownership, the global in
favour of bound reporters whose app stamp cannot be re-pointed by whichever
app initialised last.