wardx 0.1.1 → 0.1.2

package/README.md

@@ -111,7 +111,7 @@ function completeMatch(wardx, mode) {
 }
 ```
 
-To detect abnormal grants, pair this counter with a histogram and a rare anomaly event. See use case 7.
+To detect abnormal grants, pair this counter with a histogram and a rare anomaly event. See use case 8.
 
 ### Procedure
 
@@ -257,7 +257,47 @@ An event is one row in the frame. A counter is a window sum. Use both when you n
 
 If the event buffer is full, the SDK discards the new event and increments `wardx.internal.events_dropped`.
 
-## Use case 7: Detect abnormal point accumulation
+## Use case 7: Measure a volume funnel
+
+**When:** You need drop-off between screens or steps in a client, for example onboarding or checkout.
+
+**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.
+
+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.
+
+```js
+function onOnboardingStart(wardx, channel) {
+  wardx.event('onboarding.start', { channel });
+  wardx.counter('onboarding.start', { channel }).inc();
+}
+
+function onOnboardingProfile(wardx) {
+  wardx.event('onboarding.profile');
+  wardx.counter('onboarding.profile').inc();
+}
+
+function onOnboardingDone(wardx, userId) {
+  wardx.event('onboarding.done');
+  wardx.counter('onboarding.done').inc();
+  wardx.experiment.goal('onboarding.done', { subjectId: userId });
+}
+```
+
+### Procedure
+
+1. Pick a prefix and a name per step: `onboarding.start`, `onboarding.profile`, `onboarding.done`.
+2. On the client path for that step, call `event` and `counter` with the same name.
+3. Put only low-cardinality attrs on the event. Put the breakdown you need to compare (`channel`, `mode`) on the counter dimensions.
+4. If the last step is an experiment conversion, also call `experiment.goal` with `subjectId`. That is one conversion, not an N-step funnel.
+5. From MCP, call `get_aggregates` with those names. Compare counter totals, or `eventNames` counts, in the same window. The drop from start to done is the volume funnel.
+
+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.
+
+## 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.
 
@@ -298,7 +338,7 @@ Do not put `userId` on a counter or histogram dimension. The SDK and the server
 
 If histogram max stays at the legal cap and `coins.awarded` tracks completed matches times the known reward, the economy is consistent at fleet scale. A specific player still requires the database audit log.
 
-## Use case 8: Get Remote Config for a user
+## Use case 9: Get Remote Config for a user
 
 **When:** The server has a config snapshot. You need a value in the application.
 
@@ -318,7 +358,7 @@ const delayMs = wardx.config.get('message.delayMs', 1000, { subjectId: req.userI
 
 The SDK updates the snapshot when a sync response contains a newer `configVersion`. Until that sync, `config.get` returns the fallback or the last snapshot.
 
-## Use case 9: Run an A/B experiment and record a goal
+## Use case 10: Run an A/B experiment and record a goal
 
 **When:** A Remote Config key is in an experiment. You need a variant for a user. You need a goal event.
 
@@ -350,7 +390,7 @@ The payload does not contain the raw `subjectId`.
 
 The assignment is local and deterministic. The same subject, experiment, and salt always get the same variant.
 
-## Use case 10: Continue when the ingest server is down
+## Use case 11: Continue when the ingest server is down
 
 **When:** The network fails, or the ingest server is not available.
 
@@ -374,7 +414,7 @@ The SDK still records in memory. A failed sync increments `wardx.internal.frames
 
 Do not use this SDK if you must not lose events. This SDK is best-effort.
 
-## Use case 11: Stop the SDK in a graceful shutdown
+## Use case 12: Stop the SDK in a graceful shutdown
 
 **When:** The process receives `SIGTERM` or you stop a test.
 
@@ -403,7 +443,7 @@ process.on('SIGINT', onStop);
 
 `flush` sends the current pending frames and does not stop the timers. Use `shutdown` when the process stops.
 
-## Use case 12: Trace measure calls while instrumenting
+## Use case 13: Trace measure calls while instrumenting
 
 **When:** You are adding counters, events, and logs and you want to see each call and each sync on stderr.
 

package/package.json

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