@wireai/activation 0.14.2 → 0.15.0

package/src/types.ts

@@ -256,8 +256,11 @@ export type WireOnboardingProps = {
    *
    * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
    * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
-   * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
-   * verbatim and is never touched. See `autoJoinKey` for the opt-out and the two cases where the kit
+   * analytics surfaces mint and persist — so the default wiring joins. A `device_key` you DO pass
+   * wins verbatim and is never touched, provided it is a string with at least one non-whitespace
+   * character (`resolveIdentity`) — this map also accepts numbers and booleans, and a non-string or
+   * all-whitespace value is not a usable join key, so it is read as absent and the auto key is
+   * merged over it. See `autoJoinKey` for the opt-out and the two cases where the kit
    * still cannot fill the gap (no `storage`, or you opted out), which keep warning in dev.
    *
    * Never hand-write `userContext={{ deviceKey }}`: the server's device lookup reads `device_key`,
@@ -284,8 +287,11 @@ export type WireOnboardingProps = {
    * `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session; that restores the
    * pre-0.12.2 behavior exactly (nothing injected) and the dev warning fires again.
    *
-   * Two things this flag does NOT do. It never overrides a `device_key` you passed — a host-supplied
-   * key always wins, whatever this is set to. And it cannot conjure a key without `storage`: with no
+   * Two things this flag does NOT do. It never overrides a `device_key` you actually supplied — a
+   * host-supplied key always wins, whatever this is set to, where "supplied" means a string with at
+   * least one non-whitespace character (`resolveIdentity`); a non-string or an all-whitespace value
+   * is read as absent and the auto key is merged over it. And it cannot conjure a key without
+   * `storage`: with no
    * persistence the kit's id is minted fresh every launch, and a per-launch key corrupts
    * `min_sessions` instead of merely leaving the join empty, so the kit declines to inject and warns
    * in dev instead.

package/src/utils/submitResult.ts

@@ -21,19 +21,27 @@
  *
  * `submitReview` was a boolean for exactly one unpublished release, and the boolean WAS the bug.
  * `false` meant both "nothing reached the server" and "the server answered non-2xx", and the caller
- * treats `false` as "still owed" and re-posts. But the server mints its own row id
- * (`create_review` / `_new_id()`), and neither `CreateReviewRequest` nor the questionnaire response
- * body carries a client id, so there is NO idempotency key on the wire: a 502 returned AFTER the
- * insert commits means the re-post writes a SECOND row. A response of any status proves the server
- * was reached, and that is a different question from whether it liked the payload.
+ * treats `false` as "still owed" and re-posts. At the time neither body carried a client id, so
+ * there was NO idempotency key on the wire on either surface: a 502 returned AFTER the insert
+ * commits meant the re-post wrote a SECOND row. A response of any status proves the server was
+ * reached, and that is a different question from whether it liked the payload — which is why the
+ * three values stay, on both surfaces, whatever the wire gains.
  *
  * ── THE RESIDUAL, STATED HONESTLY ─────────────────────────────────────────────────────────────
  *
  * `unsent` is not proof the server never got it. A connection dropped after the request was written
  * — or after the row committed — surfaces as a thrown/rejected `fetch`, exactly like an offline
- * device. Retrying only on `unsent` is therefore SAFER, not SAFE. Closing that window needs a
- * CLIENT-MINTED IDEMPOTENCY KEY the server upserts on, which is a server change and not something
- * the kit can fake. Until it exists, prefer losing a row over inventing one: a lost detractor is a
- * gap in the data, a duplicated one is a lie in the data.
+ * device. Closing that window needs a client-minted idempotency key the server upserts on, and AS
+ * OF 2026-08-19 THE TWO SURFACES DIFFER — do not read this paragraph as one fact about both:
+ *
+ *   • REVIEWS — closed. `CreateReviewRequest` takes an optional `idempotency_key` and the server
+ *     upserts a derived row on it, so a `ReviewGate` re-post merges instead of duplicating. It is a
+ *     capability, not a guarantee: the server honours the key only when the post also carries a
+ *     unit to scope it to (`meta.device_key`, else `session_id`), so a caller that strips both is
+ *     back to the old behaviour.
+ *   • QUESTIONNAIRES — still open, and still exactly as this paragraph used to read for both. The
+ *     response body carries no client id and the server has no idempotency path for it at all, so
+ *     retrying only on `unsent` there is SAFER, not SAFE. Prefer losing a row over inventing one: a
+ *     lost detractor is a gap in the data, a duplicated one is a lie in the data.
  */
 export type SubmitResult = "accepted" | "rejected" | "unsent";