Data quality, privacy, and delivery

Product decisions are only as reliable as event freshness, identity semantics, and delivery behavior. AnalyticsCLI separates these concerns so an agent can say when a metric is trustworthy and when instrumentation must be fixed first.

Identity modes

• aggregate: a new event-scoped ID for every privacy-safe counter;
• strict: short-lived anonymous identity with no cross-surface linkage;
• full: persistent identity only when the host application enables it;
• consent_gated: the SDK default, strict until full-tracking consent is granted.

An aggregate pageview is not a user or session. Query it with event_count. Use person-level funnels or retention only for events backed by stable anonymous or identified identities. Generic queries return machine-readable quality warnings when unique-user or unique-session metrics are requested for known aggregate events.

Release and Debug isolation

Release is the decision dataset. Debug is the instrumentation dataset. Keep them separate in dashboards, CLI commands, MCP calls, exports, and agent prompts.

If Release is empty while Debug contains events, validate the runtime environment, publishable key, deployed SDK version, collector response, and real user traffic before analyzing the product.

Delivery behavior

The TypeScript SDK uses a bounded queue. It retries temporary network, timeout, rate-limit, and server errors; permanent client errors are reported and removed so they cannot block the queue forever. Oversized or non-serializable events are isolated from healthy events.

Use payload-free diagnostics:

const analytics = init({
  apiKey: '<publishable-key>',
  maxQueueSize: 1000,
  onEventsDropped(diagnostic) {
    console.warn(diagnostic.reason, diagnostic.count);
  },
});

At process or test boundaries, drain with a timeout:

const result = await analytics.flushAll({ timeoutMs: 5000 });
if (!result.drained) {
  console.warn(result.reason, result.pending);
}

await analytics.shutdownAsync({ timeoutMs: 5000 });

Existing flush() and synchronous shutdown() remain available.

Privacy defense in depth

The SDK and ingest path filter known personal-data and secret-like keys, including nested objects and arrays. This is a safety net, not permission to send unrestricted payloads. Event schemas should still prohibit personal content, secrets, precise free-text, raw receipts, authentication data, and payment credentials.

Prefer enums, booleans, numeric buckets, stable product identifiers, and coarse geography. Review schema discovery regularly:

analyticscli schema events --last 30d --limit 100

Before trusting a chart

Check:

1. latest event time;
2. Release/Debug mode;
3. event definition and aliases;
4. stable or aggregate identity;
5. sample size and comparison window;
6. app version, platform, and product surface;
7. query-plan and quality warnings;
8. known deployment, crash, revenue, or campaign changes.

The analyticscli agent brief command performs this first-pass audit and gives the next bounded queries to run.