@wireai/activation 0.9.0 → 0.9.1

package/dist/{transport-DzU-TqZz.d.ts → transport-B31G0Cib.d.ts}

@@ -20,17 +20,42 @@ import { k as ReviewTarget, g as ReviewDecisionResponse, j as ReviewSubmission }
  * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
  */
 declare const submitReview: (target: ReviewTarget | undefined, review: ReviewSubmission) => void;
-/** Options for the best-effort review decision fetch. */
+/**
+ * Options for the best-effort review decision fetch.
+ *
+ * ── WHAT THE DEPLOYED SERVER ACTUALLY READS (verified 2026-07-17) ────────────────────────
+ *
+ * `GET /v1/reviews/decision` declares exactly two query params — `session_id` and
+ * `device_key` — plus the `Authorization` header. That is the whole wire. Verified against
+ * the deployed OpenAPI schema, not against intent.
+ *
+ * This type is CLOSED on purpose. Hosts that hand-rolled this fetch invented `user_id` and
+ * `session_count` query params believing "the server ignores what it doesn't read, so passing
+ * it is always safe". Both are no-ops: the route declares neither. `session_count` is real, but
+ * only on the questionnaire POST body — which is precisely how it copy-pasted its way into a
+ * reviews call site and sat there doing nothing. They cost a wire lie — a call site that reads as though
+ * identity and a session counter reach the firing brain when neither does. So they are not
+ * offered here. Pass identity as `deviceKey`; the session count the server reasons about is the
+ * one IT derives from the event stream keyed by `deviceKey`, not one the client asserts.
+ *
+ * The client-side session floor is a LOCAL rule, not a wire param: use `ReviewConfig.minSessions`
+ * (evaluated by `useReviewGate` against the kit's own `wire_review_<id>_sessions` counter).
+ */
 interface FetchReviewDecisionOptions {
     /**
      * The onboarding session id, when there IS one. OPTIONAL on purpose: the review gate lives on
      * the home feed, where a user legitimately has no onboarding session. `deviceKey` is the real
-     * identity for this call. (Today's prod still requires `session_id` and answers 422 without it;
-     * the server relaxation is unmerged. A 422 is a non-2xx, so it returns null like any other
-     * failure, and the local rules stand. Permissive wire: do NOT make this required here.)
+     * identity for this call. (The server relaxed `session_id` to optional on 2026-07-16 and the
+     * relaxation IS deployed — the route no longer 422s without it. Permissive wire: do NOT make
+     * this required here.)
      */
     sessionId?: string;
-    /** A stable, non-PII device id. The decision endpoint reads it for cooldown + min-sessions. */
+    /**
+     * A stable, non-PII device id — THE identity for this call. The decision endpoint reads it for
+     * cooldown + min-sessions, and it is the key the server groups a device's events under. A host
+     * whose own identity is a user id passes that id here rather than reaching for a `user_id`
+     * param the route does not declare.
+     */
     deviceKey?: string;
 }
 /**
@@ -57,12 +82,29 @@ interface FetchReviewDecisionOptions {
  *   • else → null, and ONLY then. Null means "the server genuinely has no opinion", which is
  *            the one case where falling back to local rules is correct.
  *
- * Never throws: unreachable, non-2xx (incl. today's 422), bad JSON, or a missing `fetch` all
- * resolve to null. The kit does not call this internally; a host awaits it and passes the
- * result straight to `useReviewGate({ decision })`.
+ * Never throws: unreachable, non-2xx, bad JSON, or a missing `fetch` all resolve to null. The
+ * kit does not call this internally; a host awaits it and passes the result straight to
+ * `useReviewGate({ decision })`.
+ *
+ * ── DON'T RACE THIS AGAINST A LOCAL TIMER ────────────────────────────────────────────────
+ *
+ * The return type is `ReviewDecisionResponse`, which carries `arm` alongside `{fire, reason}`.
+ * Hand the WHOLE object to the gate and echo `arm` into the submission's `meta.firing_arm`;
+ * narrowing it to `{fire, reason}` on the way through silently kills per-arm attribution
+ * across a reweighting of the experiment.
+ *
+ * A host that starts its own dwell timer in parallel with this fetch has built a race a slow
+ * server loses: the timer fires, the local rules show the prompt, and the `{fire:false}` still
+ * in flight arrives too late to stop it. Do not hand-roll that. `useReviewGate` already owns
+ * the wait — set `ReviewConfig.timeoutFallbackMs` and the local rules stay parked until either
+ * the decision lands or the window expires, whichever comes first.
  *
  *   const decision = await fetchReviewDecision(target, { deviceKey });
- *   const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+ *   const gate = useReviewGate({
+ *     config: { id: "home", minSessions: 2, timeoutFallbackMs: 3000 },
+ *     decision: decision ?? undefined, // pass it whole — keep `arm`
+ *     storage,
+ *   });
  */
 declare const fetchReviewDecision: (target: ReviewTarget | undefined, options?: FetchReviewDecisionOptions) => Promise<ReviewDecisionResponse | null>;
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */

package/dist/{transport-f5VVB5hH.d.mts → transport-Bzb-bcB2.d.mts}

@@ -20,17 +20,42 @@ import { k as ReviewTarget, g as ReviewDecisionResponse, j as ReviewSubmission }
  * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
  */
 declare const submitReview: (target: ReviewTarget | undefined, review: ReviewSubmission) => void;
-/** Options for the best-effort review decision fetch. */
+/**
+ * Options for the best-effort review decision fetch.
+ *
+ * ── WHAT THE DEPLOYED SERVER ACTUALLY READS (verified 2026-07-17) ────────────────────────
+ *
+ * `GET /v1/reviews/decision` declares exactly two query params — `session_id` and
+ * `device_key` — plus the `Authorization` header. That is the whole wire. Verified against
+ * the deployed OpenAPI schema, not against intent.
+ *
+ * This type is CLOSED on purpose. Hosts that hand-rolled this fetch invented `user_id` and
+ * `session_count` query params believing "the server ignores what it doesn't read, so passing
+ * it is always safe". Both are no-ops: the route declares neither. `session_count` is real, but
+ * only on the questionnaire POST body — which is precisely how it copy-pasted its way into a
+ * reviews call site and sat there doing nothing. They cost a wire lie — a call site that reads as though
+ * identity and a session counter reach the firing brain when neither does. So they are not
+ * offered here. Pass identity as `deviceKey`; the session count the server reasons about is the
+ * one IT derives from the event stream keyed by `deviceKey`, not one the client asserts.
+ *
+ * The client-side session floor is a LOCAL rule, not a wire param: use `ReviewConfig.minSessions`
+ * (evaluated by `useReviewGate` against the kit's own `wire_review_<id>_sessions` counter).
+ */
 interface FetchReviewDecisionOptions {
     /**
      * The onboarding session id, when there IS one. OPTIONAL on purpose: the review gate lives on
      * the home feed, where a user legitimately has no onboarding session. `deviceKey` is the real
-     * identity for this call. (Today's prod still requires `session_id` and answers 422 without it;
-     * the server relaxation is unmerged. A 422 is a non-2xx, so it returns null like any other
-     * failure, and the local rules stand. Permissive wire: do NOT make this required here.)
+     * identity for this call. (The server relaxed `session_id` to optional on 2026-07-16 and the
+     * relaxation IS deployed — the route no longer 422s without it. Permissive wire: do NOT make
+     * this required here.)
      */
     sessionId?: string;
-    /** A stable, non-PII device id. The decision endpoint reads it for cooldown + min-sessions. */
+    /**
+     * A stable, non-PII device id — THE identity for this call. The decision endpoint reads it for
+     * cooldown + min-sessions, and it is the key the server groups a device's events under. A host
+     * whose own identity is a user id passes that id here rather than reaching for a `user_id`
+     * param the route does not declare.
+     */
     deviceKey?: string;
 }
 /**
@@ -57,12 +82,29 @@ interface FetchReviewDecisionOptions {
  *   • else → null, and ONLY then. Null means "the server genuinely has no opinion", which is
  *            the one case where falling back to local rules is correct.
  *
- * Never throws: unreachable, non-2xx (incl. today's 422), bad JSON, or a missing `fetch` all
- * resolve to null. The kit does not call this internally; a host awaits it and passes the
- * result straight to `useReviewGate({ decision })`.
+ * Never throws: unreachable, non-2xx, bad JSON, or a missing `fetch` all resolve to null. The
+ * kit does not call this internally; a host awaits it and passes the result straight to
+ * `useReviewGate({ decision })`.
+ *
+ * ── DON'T RACE THIS AGAINST A LOCAL TIMER ────────────────────────────────────────────────
+ *
+ * The return type is `ReviewDecisionResponse`, which carries `arm` alongside `{fire, reason}`.
+ * Hand the WHOLE object to the gate and echo `arm` into the submission's `meta.firing_arm`;
+ * narrowing it to `{fire, reason}` on the way through silently kills per-arm attribution
+ * across a reweighting of the experiment.
+ *
+ * A host that starts its own dwell timer in parallel with this fetch has built a race a slow
+ * server loses: the timer fires, the local rules show the prompt, and the `{fire:false}` still
+ * in flight arrives too late to stop it. Do not hand-roll that. `useReviewGate` already owns
+ * the wait — set `ReviewConfig.timeoutFallbackMs` and the local rules stay parked until either
+ * the decision lands or the window expires, whichever comes first.
  *
  *   const decision = await fetchReviewDecision(target, { deviceKey });
- *   const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+ *   const gate = useReviewGate({
+ *     config: { id: "home", minSessions: 2, timeoutFallbackMs: 3000 },
+ *     decision: decision ?? undefined, // pass it whole — keep `arm`
+ *     storage,
+ *   });
  */
 declare const fetchReviewDecision: (target: ReviewTarget | undefined, options?: FetchReviewDecisionOptions) => Promise<ReviewDecisionResponse | null>;
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",

package/src/reviews/transport.ts

@@ -39,17 +39,42 @@ export const submitReview = (
   }
 };
 
-/** Options for the best-effort review decision fetch. */
+/**
+ * Options for the best-effort review decision fetch.
+ *
+ * ── WHAT THE DEPLOYED SERVER ACTUALLY READS (verified 2026-07-17) ────────────────────────
+ *
+ * `GET /v1/reviews/decision` declares exactly two query params — `session_id` and
+ * `device_key` — plus the `Authorization` header. That is the whole wire. Verified against
+ * the deployed OpenAPI schema, not against intent.
+ *
+ * This type is CLOSED on purpose. Hosts that hand-rolled this fetch invented `user_id` and
+ * `session_count` query params believing "the server ignores what it doesn't read, so passing
+ * it is always safe". Both are no-ops: the route declares neither. `session_count` is real, but
+ * only on the questionnaire POST body — which is precisely how it copy-pasted its way into a
+ * reviews call site and sat there doing nothing. They cost a wire lie — a call site that reads as though
+ * identity and a session counter reach the firing brain when neither does. So they are not
+ * offered here. Pass identity as `deviceKey`; the session count the server reasons about is the
+ * one IT derives from the event stream keyed by `deviceKey`, not one the client asserts.
+ *
+ * The client-side session floor is a LOCAL rule, not a wire param: use `ReviewConfig.minSessions`
+ * (evaluated by `useReviewGate` against the kit's own `wire_review_<id>_sessions` counter).
+ */
 export interface FetchReviewDecisionOptions {
   /**
    * The onboarding session id, when there IS one. OPTIONAL on purpose: the review gate lives on
    * the home feed, where a user legitimately has no onboarding session. `deviceKey` is the real
-   * identity for this call. (Today's prod still requires `session_id` and answers 422 without it;
-   * the server relaxation is unmerged. A 422 is a non-2xx, so it returns null like any other
-   * failure, and the local rules stand. Permissive wire: do NOT make this required here.)
+   * identity for this call. (The server relaxed `session_id` to optional on 2026-07-16 and the
+   * relaxation IS deployed — the route no longer 422s without it. Permissive wire: do NOT make
+   * this required here.)
    */
   sessionId?: string;
-  /** A stable, non-PII device id. The decision endpoint reads it for cooldown + min-sessions. */
+  /**
+   * A stable, non-PII device id — THE identity for this call. The decision endpoint reads it for
+   * cooldown + min-sessions, and it is the key the server groups a device's events under. A host
+   * whose own identity is a user id passes that id here rather than reaching for a `user_id`
+   * param the route does not declare.
+   */
   deviceKey?: string;
 }
 
@@ -77,12 +102,29 @@ export interface FetchReviewDecisionOptions {
  *   • else → null, and ONLY then. Null means "the server genuinely has no opinion", which is
  *            the one case where falling back to local rules is correct.
  *
- * Never throws: unreachable, non-2xx (incl. today's 422), bad JSON, or a missing `fetch` all
- * resolve to null. The kit does not call this internally; a host awaits it and passes the
- * result straight to `useReviewGate({ decision })`.
+ * Never throws: unreachable, non-2xx, bad JSON, or a missing `fetch` all resolve to null. The
+ * kit does not call this internally; a host awaits it and passes the result straight to
+ * `useReviewGate({ decision })`.
+ *
+ * ── DON'T RACE THIS AGAINST A LOCAL TIMER ────────────────────────────────────────────────
+ *
+ * The return type is `ReviewDecisionResponse`, which carries `arm` alongside `{fire, reason}`.
+ * Hand the WHOLE object to the gate and echo `arm` into the submission's `meta.firing_arm`;
+ * narrowing it to `{fire, reason}` on the way through silently kills per-arm attribution
+ * across a reweighting of the experiment.
+ *
+ * A host that starts its own dwell timer in parallel with this fetch has built a race a slow
+ * server loses: the timer fires, the local rules show the prompt, and the `{fire:false}` still
+ * in flight arrives too late to stop it. Do not hand-roll that. `useReviewGate` already owns
+ * the wait — set `ReviewConfig.timeoutFallbackMs` and the local rules stay parked until either
+ * the decision lands or the window expires, whichever comes first.
  *
  *   const decision = await fetchReviewDecision(target, { deviceKey });
- *   const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+ *   const gate = useReviewGate({
+ *     config: { id: "home", minSessions: 2, timeoutFallbackMs: 3000 },
+ *     decision: decision ?? undefined, // pass it whole — keep `arm`
+ *     storage,
+ *   });
  */
 export const fetchReviewDecision = async (
   target: ReviewTarget | undefined,