@wireai/activation 0.9.1 → 0.10.0

package/AGENTS.md

@@ -123,6 +123,13 @@ write your own fetch.
   session. `deviceKey` is the identity that matters. Pass `sessionId` only when you have one.
 - Running a firing experiment? Echo the returned `arm` back as `meta.firing_arm` on the review
   submission so per-arm attribution survives a reweighting.
+- **Fire the gate off an in-app action.** `useWireActivation({ serverUrl, apiKey, deviceKey })`
+  (ROOT export) returns `{ track, sessionId, revalidation }`. `await track(name, meta?)` POSTs an
+  `app_event` (`question_key=name`) under the current session, resolves `true` on 2xx, and bumps
+  `revalidation`; list `revalidation` in the `fetchReviewDecision` / `fetchQuestionnaireDecision`
+  effect's deps so the gate re-fetches after the action and can fire. React-free factory:
+  `createWireActivation(config)`. This is the kit-owned replacement for hand-rolling
+  session-id + await-POST + revalidate.
 
 ## Gotchas (do not miss)
 

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [Unreleased]
+
+### Added: `wire.track` + `useWireActivation` (fire a gate off an in-app action)
+
+A kit-owned event-trigger surface so a consumer stops hand-rolling the session-id + await-POST +
+revalidate dance to make a review or questionnaire fire off an arbitrary in-app action (the
+workaround Morrow shipped). All additive; no existing API changed.
+
+- **`useWireActivation({ serverUrl, apiKey, deviceKey?, ... })`** (root export) returns
+  `{ track, sessionId, revalidation }`. `createWireActivation(config)` is the React-free factory
+  it wraps (returns `{ track, sessionId, subscribeRevalidation, getRevalidationVersion }`).
+- **`await track(name, meta?)`** POSTs `event_type='app_event'`, `question_key=name` under the
+  current `getCurrentSessionId()` plus `user_context.device_key` (via `reportClientEventAwait` to
+  `/v1/events`). Resolves `true` on a 2xx and only then bumps decision revalidation; resolves
+  `false` (no bump) on no current session, a blank name, or a failed POST. Never throws.
+- **Revalidation pub/sub** (`useActivationRevalidation`, `bumpActivationRevalidation`,
+  `subscribeActivationRevalidation`, `getActivationRevalidationVersion`) is a `globalThis`
+  `Symbol.for` singleton, so a `track()` on the root bundle reaches a gate subscribed from the
+  `./reviews` / `./questionnaire` subpath under `dist`. List `revalidation` in a
+  `fetchReviewDecision` / `fetchQuestionnaireDecision` effect's deps and the gate re-fetches after
+  the action, then fires.
+- Docs: new README section "Fire a review or questionnaire from an in-app action", an event-trigger
+  step in `INTEGRATION_PROMPT.md`, and entries in `llms.txt` / `AGENTS.md`.
+
 ## [0.9.1] — 2026-07-17
 
 ### Fixed: the review-decision wire is now documented as it actually is

package/INTEGRATION_PROMPT.md

@@ -43,7 +43,17 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    - Analytics: log via `toAnalyticsEvent(e)` → my logger, using the canonical `wire_onboarding_*` names.
 7. Navigation: mount the screen in my first-run/signup flow; branch to the static flow when the gate
    is off or config is missing.
-8. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
+8. Event triggers (only if I asked to fire a review/questionnaire off an in-app action): pick the
+   action that should trigger it (e.g. finishing a task, journaling a win) and its key, e.g.
+   `journal_done`. On my home/gate screen call
+   `const { track, sessionId, revalidation } = useWireActivation({ serverUrl: WIREAI_SERVER_URL, apiKey: WIREAI_API_KEY, appId: APP_ID, deviceKey })`
+   from `@wireai/activation`, fetch the gate decision in a `useEffect` keyed on `[revalidation]`
+   (`fetchReviewDecision({ serverUrl, apiKey }, { sessionId, deviceKey })` → set it into
+   `useReviewGate({ config, decision })`; questionnaires use `fetchQuestionnaireDecision` +
+   `useQuestionnaireGate` the same way), and at the action site call `await track("journal_done")`.
+   Do NOT hand-roll the session id or the POST; `wire.track` owns both and revalidates the gate on
+   a successful 2xx.
+9. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
 
 Report back: the files you changed (path:line), the typecheck result, and anything you couldn't
 infer about my conventions.

package/README.md

@@ -874,6 +874,68 @@ The next retention module reuses this exact server-directed shape:
 with the client once-gating per announcement id through the same storage. Same seam, no code
 yet.
 
+## Fire a review or questionnaire from an in-app action (`wire.track`)
+
+The decision seam above re-fetches on mount. But the gate usually sits on the home feed while
+the user goes *elsewhere* to do the thing that should trigger it (journals a win, finishes a
+task). The mount fetch ran before that event existed and never re-runs, so the trigger never
+lands. `wire.track` closes that loop. It posts the action, waits for the server to store it,
+then signals every gate to re-fetch. It is the kit-owned replacement for the session-id,
+await-POST, revalidate dance a host would otherwise hand-roll (`reportAppEvent` is the older
+fire-and-forget path; `wire.track` is the awaitable one that also revalidates).
+
+`useWireActivation` is the one import that gives you the whole surface. It takes the SAME
+`serverUrl` / `apiKey` as onboarding (never a second key) and returns `{ track, sessionId,
+revalidation }`:
+
+- **`track(name, meta?)`** is awaitable. `name` is the exact string a server firing trigger
+  matches on (`question_key`). It POSTs `event_type='app_event'` under the current
+  `getCurrentSessionId()` plus a `user_context.device_key`, resolves `true` once the server
+  has stored it (2xx) and only then bumps revalidation, and resolves `false` (no bump) when
+  there is no current session, a blank name, or the POST fails. It never throws.
+- **`sessionId`** is the current per-open session id (read fresh each render), or `undefined`.
+- **`revalidation`** is a counter that ticks on every successful `track()` from anywhere. List
+  it in a decision-fetch effect's deps and the fetch re-runs when it changes.
+
+### The `track` then re-fetch then fire wiring
+
+No single component closes the loop for you, because the decision fetch lives in your gate's
+host effect. Wire it once: fetch the decision on mount AND whenever `revalidation` ticks, then
+pass the result straight to the gate's `decision` prop. Pass the same `deviceKey` to both the
+hook and the fetch so the server reasons about one device.
+
+```tsx
+import { useEffect, useState } from "react";
+import { useWireActivation } from "@wireai/activation";
+import {
+  fetchReviewDecision,
+  useReviewGate,
+  type ReviewDecisionResponse,
+} from "@wireai/activation/reviews";
+
+const target = { serverUrl: SERVER_URL, apiKey: TENANT_KEY };
+const { track, sessionId, revalidation } = useWireActivation({ ...target, deviceKey });
+const [decision, setDecision] = useState<ReviewDecisionResponse>();
+
+// Re-fetch the server decision on mount AND every time a track() succeeds (revalidation ticks).
+useEffect(() => {
+  fetchReviewDecision(target, { sessionId, deviceKey }).then((d) => setDecision(d ?? undefined));
+}, [revalidation]);
+
+const gate = useReviewGate({ config: { id: "home", minSessions: 2 }, decision, storage });
+
+// …elsewhere, on the triggering action. Awaiting it means the re-fetch sees the event:
+await track("journal_done"); // POST stored → revalidation bumps → effect re-fetches → gate can fire
+```
+
+The questionnaire gate uses the identical shape: swap `fetchReviewDecision` / `useReviewGate`
+for `fetchQuestionnaireDecision` / `useQuestionnaireGate` from `@wireai/activation/questionnaire`
+(both take a `decision` prop). One `wire.track` call feeds every subscribed gate.
+
+If you are outside React (a service, a saga), `createWireActivation(config)` is the React-free
+factory. It returns `{ track, sessionId, subscribeRevalidation, getRevalidationVersion }`: the
+same `track`, plus the raw pub/sub the hook wraps for you.
+
 ## Feature controls (per-module kill switches)
 
 Every activation surface has a switch you can flip from the dashboard "in case of something":

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-Bzb-bcB2.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-Bs2JfTJ8.mjs';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-Bs2JfTJ8.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-DdDkprpM.mjs';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEventAwait, n as reportClientEvents, o as reportClientEventsAwait, p as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-DdDkprpM.mjs';
 import '../types-CNUqMK0D.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-B31G0Cib.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-61dcm3V-.js';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-61dcm3V-.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-D0Vq7_VE.js';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEventAwait, n as reportClientEvents, o as reportClientEventsAwait, p as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-D0Vq7_VE.js';
 import '../types-Buj9Lw9t.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';

package/dist/analytics/index.js

@@ -499,22 +499,38 @@ var useScreenTracking = (navigationRef, options = {}) => {
 
 // src/analytics/reportClientEvent.ts
 var makeSessionId = () => `wire_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
-var reportClientEvents = (target, events) => {
-  if (!(target == null ? void 0 : target.serverUrl) || events.length === 0) return;
+var buildEventsRequest = (target, events) => {
+  if (!(target == null ? void 0 : target.serverUrl) || events.length === 0) return null;
   try {
     const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
     const headers = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    void fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ events })
-    }).catch(() => {
+    return { url, init: { method: "POST", headers, body: JSON.stringify({ events }) } };
+  } catch {
+    return null;
+  }
+};
+var reportClientEvents = (target, events) => {
+  try {
+    const req = buildEventsRequest(target, events);
+    if (!req) return;
+    void fetch(req.url, req.init).catch(() => {
     });
   } catch {
   }
 };
 var reportClientEvent = (target, event) => reportClientEvents(target, [event]);
+var reportClientEventsAwait = async (target, events) => {
+  try {
+    const req = buildEventsRequest(target, events);
+    if (!req) return false;
+    const res = await fetch(req.url, req.init);
+    return Boolean(res && res.ok);
+  } catch {
+    return false;
+  }
+};
+var reportClientEventAwait = (target, event) => reportClientEventsAwait(target, [event]);
 
 // src/analytics/analyticsEvent.ts
 var WIRE_ONBOARDING_EVENTS = {
@@ -953,13 +969,18 @@ var createEventQueue = (options) => {
 };
 
 // src/analytics/currentSession.ts
-var _currentSessionId;
+var CURRENT_SESSION_ID_SLOT = /* @__PURE__ */ Symbol.for(
+  "@wireai/activation:currentSessionId"
+);
+var globalSlot = globalThis;
 var setCurrentSessionId = (id) => {
-  if (typeof id === "string" && id.length > 0) _currentSessionId = id;
+  if (typeof id === "string" && id.length > 0) {
+    globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+  }
 };
-var getCurrentSessionId = () => _currentSessionId;
+var getCurrentSessionId = () => globalSlot[CURRENT_SESSION_ID_SLOT];
 var resetCurrentSessionId = () => {
-  _currentSessionId = void 0;
+  globalSlot[CURRENT_SESSION_ID_SLOT] = void 0;
 };
 
 // src/identity/userIdentity.ts
@@ -1187,7 +1208,9 @@ exports.getCurrentSessionId = getCurrentSessionId;
 exports.makeSessionId = makeSessionId;
 exports.reportAppEvent = reportAppEvent;
 exports.reportClientEvent = reportClientEvent;
+exports.reportClientEventAwait = reportClientEventAwait;
 exports.reportClientEvents = reportClientEvents;
+exports.reportClientEventsAwait = reportClientEventsAwait;
 exports.resetCurrentSessionId = resetCurrentSessionId;
 exports.screenTrackingHandler = screenTrackingHandler;
 exports.setCurrentSessionId = setCurrentSessionId;