wardx 0.2.2 → 0.5.0

package/README.md

@@ -83,6 +83,7 @@ wardx.event('match.started', { mode: 'ranked', country: 'AR' });
 wardx.counter('match.completed', { mode: 'ranked' }).inc();
 wardx.gauge('players.online').set(12);
 wardx.histogram('request.duration', { buckets: [10, 25, 50, 100, 250] }).observe(42);
+wardx.distinct('shot.traffic.hids', { result: 'violating' }).add(hid);
 
 const end = wardx.timer('matchmaking.duration');
 end({ result: 'success' });
@@ -277,7 +278,7 @@ If the event buffer is full, the SDK discards the new event and increments `ward
 
 **Objective:** Emit one named event and one counter per step. Compare those counts. Do not reconstruct a per-user path.
 
-Wardx does not store a user journey. Delivery is at-most-once. Production discards envelopes after ingest (`sink: "null"`). The aggregator counts events by name and role. Event attrs do not split that count. `sessionId` identifies the envelope. It is not a join key. There are no unique users, no ordered sequences, and no time between steps.
+Wardx does not store a user journey. Delivery is at-most-once. Production discards envelopes after ingest (`sink: "null"`). The aggregator counts events by name and role. Event attrs do not split that count. `sessionId` identifies the envelope. It is not a join key. `distinct` can estimate unique identifiers per named aggregate, but it does not provide ordered sequences or time between steps.
 
 Give each step its own name. Do not reuse `screen.view` with a `surface` attr as the funnel. Use `surface` only as a counter dimension when you also need a breakdown of one step.
 
@@ -309,7 +310,47 @@ function onOnboardingDone(wardx, userId) {
 
 On a backend that serves many users, increment the counters in process. Do not `event()` once per user action.
 
-Do not put `userId` on a counter dimension. Do not expect Mixpanel-style unique-user funnels from Wardx.
+Do not put `userId` on a counter dimension. For an approximate unique count at
+one step, use `distinct(stepName, dims).add(userId)`. It hashes with the required
+local `privacySalt` and sends only a 512-register HLL sketch (`p=9`, about 4.6%
+standard error). This still does not create a Mixpanel-style per-user funnel.
+
+## User retention: D1 / D7 / D30
+
+Call `wardx.retentionActivity(userId)` on the activity that defines a return,
+for example opening the app or starting a game. Use the same definition in all
+clients of the project. `userId` is required on every call, must be nonblank,
+and must remain stable across sessions and devices. `identify()` is not used
+as an implicit fallback.
+
+```js
+wardx.retentionActivity(userId);
+```
+
+The SDK sends a salted subject hash, never the raw ID. Keep `privacySalt` stable
+and identical across project clients; the server pins its fingerprint on the
+first accepted activity and rejects a different salt. Cohorts and returns are
+project-wide across roles and environments; use separate projects for separate
+populations such as production and testing.
+
+The server persists the earliest received activity date as the cohort and
+counts each user once on each UTC calendar day. D7 means activity **on** the
+seventh calendar day after the cohort date, not activity on or after D7.
+Duplicate activities do not increase the count. Delayed earlier activity can
+correct the cohort and its returns; subsequent activity never advances it.
+
+Query MCP `get_retention` with `project`, inclusive `from`, and exclusive `to`
+as `YYYY-MM-DD` cohort dates. Return dates need not fall inside that range.
+Each cohort contains `users` and D1/D7/D30 `returns` with `users`, `rate` (0–1),
+and `status`. Until the entire target UTC day has elapsed, the return is
+`pending` with null count and rate. Empty cohorts are omitted.
+
+Counts are exact for received activity, not proof of complete delivery. This
+uses the existing bounded, in-memory event buffer and at-most-once sync: lost
+batches can lose initial activity or returns. There is no historical backfill
+from ordinary events or `distinct`. Existing timestamp and late-data limits
+apply. A mature result can still change when accepted delayed activity arrives.
+Retention requires a server with this feature; older servers cannot compute it.
 
 ## Use case 8: Detect abnormal point accumulation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardx",
-  "version": "0.2.2",
+  "version": "0.5.0",
   "description": "Node.js SDK for Wardx telemetry, Remote Config, and experiments.",
   "keywords": [
     "wardx",
@@ -37,6 +37,6 @@
     "src"
   ],
   "dependencies": {
-    "@wardx/core": "0.2.2"
+    "@wardx/core": "0.5.0"
   }
-}
+}

package/src/WardxNode.js

@@ -43,6 +43,10 @@ export class WardxNode {
     this._enqueueSync({ bootstrap: true });
   }
 
+  retentionActivity(userId) {
+    this._core.retentionActivity(userId);
+  }
+
   identify(subjectId) {
     this._core.identify(subjectId);
   }
@@ -59,6 +63,10 @@ export class WardxNode {
     return this._core.histogram(name, a, b);
   }
 
+  distinct(name, dims) {
+    return this._core.distinct(name, dims);
+  }
+
   timer(name, dims) {
     return this._core.timer(name, dims);
   }

package/src/index.d.ts

@@ -7,6 +7,7 @@ import type {
   CreateWardxOptions,
   DimensionValue,
   Dimensions,
+  DistinctHandle,
   EventTraceRecord,
   Experiment,
   ExperimentGoalContext,
@@ -36,6 +37,7 @@ export type {
   CreateWardxOptions,
   DimensionValue,
   Dimensions,
+  DistinctHandle,
   EventTraceRecord,
   Experiment,
   ExperimentGoalContext,
@@ -74,10 +76,12 @@ export class WardxNode {
   config: ConfigApi;
   experiment: ExperimentApi;
   constructor(settings: ResolvedSettings);
+  retentionActivity(userId: string): void;
   identify(subjectId: string | null | undefined): void;
   counter(name: string, dims?: Dimensions | null): CounterHandle;
   gauge(name: string, dims?: Dimensions | null): GaugeHandle;
   histogram(name: string, a?: HistogramOptions | null, b?: HistogramOptions | null): HistogramHandle;
+  distinct(name: string, dims?: Dimensions | null): DistinctHandle;
   timer(name: string, dims?: Dimensions | null): StopTimer;
   event(name: string, attrs?: Attrs | null): void;
   flush(): Promise<void>;