wardx 0.4.0 → 0.5.0

package/README.md

@@ -315,6 +315,43 @@ one step, use `distinct(stepName, dims).add(userId)`. It hashes with the require
 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
 
 **When:** A game grants points, coins, or XP. You need to see whether the economy is consistent, or whether grants jumped outside the normal range.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardx",
-  "version": "0.4.0",
+  "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.4.0"
+    "@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);
   }

package/src/index.d.ts

@@ -76,6 +76,7 @@ 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;