@wireai/activation 0.13.0 → 0.13.2

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, K as OnboardingEvent, L as OnboardingCopy, c as ClientEventTarget, M as DeviceContext, W as WireUserContext, b as ClientEvent, g as EnvelopeSource } from './currentSession-D7zabMXK.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, d as ClientEventType, N as DeviceFormFactor, D as DeviceKeyStorage, P as EXTRA_KEY_PREFIX, Q as IdentifyOnboardingBinding, T as IdentifyOnboardingOptions, U as IdentityRecord, V as IdentitySource, X as IdentitySpace, Y as OnboardingProgress, R as ResolveAutoDeviceKeyOptions, Z as ResolveUserContextOptions, _ as ResolvedUserContext, $ as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, a0 as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, a1 as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, a2 as hashEmailFnv1a, a3 as hostIdentity, a4 as hydrateAutoDeviceKey, a5 as hydrateDeviceIdentity, a6 as identifyOnboarding, a7 as isWireScalar, s as looksLikeEmail, t as makeSessionId, a8 as mintDeviceId, a9 as namespaceExtra, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, aa as resetIdentityProvenance, F as resolveAutoDeviceKey, ab as resolveIdentity, ac as resolveUserContext, ad as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-D7zabMXK.js';
+import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, c as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, U as PermissionPlacement, b as ClientEvent, g as EnvelopeSource } from './currentSession-DOVZEWJl.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-DOVZEWJl.js';
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.js';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-Cdgns6--.js';
-import { WireAIComponent, Message, WireAIResponse } from 'wireai-rn';
+import { WireAIComponent, InjectedProps, Message, WireAIResponse } from 'wireai-rn';
 import { a as WireFeaturesConfig, W as WireFeatures, b as WireOnboardingStorage } from './types-CKFhyrMu.js';
 export { D as DEFAULT_SESSION_TTL_MS, L as LoadedSession, O as OnboardingMode, c as clearPersistedSession, l as loadPersistedSession, p as peekPersistedSession, s as savePersistedSession, d as sessionStorageKey } from './types-CKFhyrMu.js';
 import { z } from 'zod';
@@ -550,6 +550,96 @@ declare const NumberStepperCard: WireAIComponent;
 
 declare const InterstitialCard: WireAIComponent;
 
+/**
+ * PermissionCard - the priming screen that stands in front of an OS permission dialog.
+ *
+ * THE PRIMING PATTERN, which is the entire point: the OS dialog opens from the primary press
+ * handler and from nowhere else. There is no mount effect, no auto-fire, no timer, and no code path
+ * from render to `request()`. iOS grants an app exactly ONE native notification prompt for its
+ * whole lifetime, so this cheap in-app screen spends first and only forwards the users who said
+ * yes. The secondary ("Maybe later") advances the flow with the prompt still unspent.
+ *
+ * THREE PRIMARY ACTIONS, picked from the non-prompting `getStatus` probe (never from `request`):
+ *   • ask (the default, and the only branch that can reach `request`)
+ *   • settings (status `blocked`: the OS would show nothing, so the only route left is Settings)
+ *   • continue (already granted, or a host that supplied no `request` at all - the kit declines to
+ *     fabricate a prompt it has no way to open)
+ *
+ * IT IS NOT A QUESTION. It sends nothing to the backend, appends nothing to the thread, and mints
+ * no `key` / `slot_id`, so `deriveAnswers` and every completion semantic are untouched. Every
+ * outcome, including a denial, continues the flow.
+ *
+ * Motion: the same register as the other value beats. The illustration springs in
+ * (STATUS_POP_SPRING, the StatusCard glyph pop) and the copy rises behind it on the interstitial
+ * head stagger. Reduce motion: final frame at once, like every other card.
+ *
+ * Registered as a `WireAIComponent` so a later server-emitted placement (AI-chosen timing) renders
+ * through the same component with no rewrite. It is deliberately NOT in `onboardingComponents`:
+ * that array is what the device ADVERTISES as renderable, and a backend told it may emit this card
+ * could emit one for a host that wired no `request`.
+ */
+
+/** The name the card is registered under, and the `component` stamped on its events. */
+declare const PERMISSION_CARD_NAME = "PermissionCard";
+/**
+ * The COPY half of the card, i.e. everything a server could legitimately author. The capability
+ * half (`request` / `getStatus` / `openSettings`) is host-injected and deliberately absent here:
+ * a schema field can only ever carry data, never a function, and the kit imports no native module.
+ */
+declare const schema: z.ZodObject<{
+    permission: z.ZodString;
+    title: z.ZodString;
+    message: z.ZodString;
+    primaryLabel: z.ZodString;
+    secondaryLabel: z.ZodString;
+    blockedTitle: z.ZodOptional<z.ZodString>;
+    blockedMessage: z.ZodOptional<z.ZodString>;
+    settingsLabel: z.ZodOptional<z.ZodString>;
+    continueLabel: z.ZodOptional<z.ZodString>;
+    illustration: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    message: string;
+    primaryLabel: string;
+    secondaryLabel: string;
+    permission: string;
+    blockedTitle?: string | undefined;
+    blockedMessage?: string | undefined;
+    settingsLabel?: string | undefined;
+    continueLabel?: string | undefined;
+    illustration?: string | undefined;
+}, {
+    title: string;
+    message: string;
+    primaryLabel: string;
+    secondaryLabel: string;
+    permission: string;
+    blockedTitle?: string | undefined;
+    blockedMessage?: string | undefined;
+    settingsLabel?: string | undefined;
+    continueLabel?: string | undefined;
+    illustration?: string | undefined;
+}>;
+type PermissionCardProps = z.infer<typeof schema> & Partial<InjectedProps> & {
+    /** THE ONLY function that can open an OS dialog. Called from the primary handler alone. */
+    request?: () => Promise<WirePermissionStatus>;
+    /** NON-PROMPTING status read. Decides which primary action is offered, nothing else. */
+    getStatus?: () => Promise<WirePermissionStatus>;
+    /** Open the OS settings page. Only reachable on the `blocked` route. */
+    openSettings?: () => void | Promise<void>;
+    /** Reports each moment for analytics. Never control flow. */
+    onStage?: (stage: PermissionStage, status?: WirePermissionStatus) => void;
+    /** Fires exactly once, with the outcome this screen produced. The flow advances on it. */
+    onSettled?: (outcome: WirePermissionOutcome) => void;
+};
+/** The typed component the flow renders directly (host-injected placement). */
+declare const PermissionCardView: React__default.NamedExoticComponent<PermissionCardProps>;
+/**
+ * The SDK registration object, so a server-emitted placement can adopt this exact screen later.
+ * Not part of `onboardingComponents` on purpose - see the file header.
+ */
+declare const PermissionCard: WireAIComponent;
+
 /**
  * The shared option shape for the choice cards (SelectionCard, CardGridSelectCard).
  *
@@ -1120,6 +1210,25 @@ type OnboardingFlowProps = {
      * `started` so host funnels don't double-count the session.
      */
     resumed?: boolean;
+    /**
+     * Host-declared permission screens injected into this server-driven stream. See
+     * `permissions/types.ts`: the OS dialog is only ever reached from the primary tap.
+     */
+    permissionScreens?: PermissionScreenConfig[];
+    /**
+     * Screen ids already settled in THIS session, restored from `storage` by WireOnboarding so an
+     * app kill mid-flow does not re-ask. Empty (the default) means "nothing settled yet".
+     */
+    settledPermissions?: readonly string[];
+    /**
+     * True while that restore is still in flight. Permission screens are suppressed until it lands,
+     * because showing one before the record is read is exactly the re-ask the record prevents. The
+     * read is short (one storage get, timeout-capped) and cannot outlive the first card's round trip
+     * in practice, so this normally never shows up as a delay.
+     */
+    permissionsPending?: boolean;
+    /** Persist one settled screen id (fire-and-forget; WireOnboarding owns the storage). */
+    onPermissionSettled?: (id: string, outcome: WirePermissionOutcome) => void;
 };
 declare const OnboardingFlow: React__default.FC<OnboardingFlowProps>;
 
@@ -1755,6 +1864,88 @@ interface RevenueCatBridge {
  */
 declare const createRevenueCatBridge: (config: RevenueCatBridgeConfig) => RevenueCatBridge;
 
+/**
+ * placement - WHERE an injected permission screen lands in a stream nobody knows the length of.
+ *
+ * The card stream is server-driven: the backend decides how many questions this user gets, and the
+ * count differs per user and per run. So a placement is never an index into a known list; it is a
+ * predicate evaluated against the card the flow is ABOUT to render, on every turn.
+ *
+ * THE CLAMP is the whole reason this is a function and not a comparison. `{ afterCard: 4 }` against
+ * a stream that ended after 3 would simply never fire, and "the screen silently never showed" is
+ * the exact failure a host cannot see. So an unreached target degrades to `"beforeEnd"`: the
+ * terminal card is the last position where the screen can still exist, so that is where it goes.
+ *
+ * PURE, no React, no React Native - the placement math is the part worth unit-testing.
+ */
+
+/** Where a screen sits when the host does not say. High intent, and it can never be clamped away. */
+declare const DEFAULT_PERMISSION_PLACEMENT: PermissionPlacement;
+/** The flow position a placement is resolved against. */
+type FlowPosition = {
+    /** 0-based index of the card about to render. `-1` when no card has arrived yet. */
+    cardIndex: number;
+    /** Whether that card is the terminal recap, i.e. the flow's last screen. */
+    isTerminal: boolean;
+};
+/** `afterCard` from a host is arbitrary input: floor it, floor it at 0, and never let NaN through. */
+declare const normalizeAfterCard: (value: number) => number;
+/**
+ * Is a screen with this placement due at this position?
+ *
+ * `>=` rather than `===` on purpose: due-ness is re-evaluated every render and a screen is settled
+ * the moment it is answered, so a target the flow has already passed (because a screen ahead of it
+ * in the array was on screen for those turns) still fires instead of being skipped forever.
+ */
+declare const isPermissionDue: (placement: PermissionPlacement, position: FlowPosition) => boolean;
+/**
+ * The stable id a screen is remembered by across a resume. Defaults to `<permission>:<index>`,
+ * which is right until the array is reordered - hence the documented `id` escape hatch.
+ */
+declare const permissionScreenId: (screen: PermissionScreenConfig, index: number) => string;
+/** A due screen and the id it is remembered by. */
+type DuePermissionScreen = {
+    screen: PermissionScreenConfig;
+    id: string;
+};
+/**
+ * The FIRST configured screen that is due here and has not already been settled in this session.
+ * One at a time, in array order, so two screens due at the same position queue rather than collide.
+ */
+declare const selectDuePermissionScreen: (screens: readonly PermissionScreenConfig[] | undefined, settled: readonly string[], position: FlowPosition) => DuePermissionScreen | undefined;
+
+/**
+ * permissionMemory - "shown exactly once per session", kept true across an app kill.
+ *
+ * The in-memory guard alone is not enough. The kit already resumes a killed onboarding into the
+ * SAME backend session (see `persistedSession.ts`), so without a persisted record the resumed mount
+ * would re-show a permission screen the user had already answered - and on the ask path that means
+ * a second dialog attempt against an OS that grants exactly one.
+ *
+ * The record is SCOPED TO THE SESSION ID, one entry, never a growing map: a record whose
+ * `sessionId` is not the session being resumed is stale by definition and reads as empty. That is
+ * also what makes a genuinely new onboarding start clean without anything having to expire it.
+ *
+ * Same host-injected `WireOnboardingStorage` and the same best-effort discipline as the session
+ * seed: reads race the shared ceiling and degrade to "nothing remembered", writes swallow every
+ * error. A broken storage adapter must never gate or break onboarding.
+ */
+
+/** Storage key for an app's settled permission screens, e.g. `wireai:permissions:acme`. */
+declare const permissionStorageKey: (appId: string) => string;
+/**
+ * PURE seam: which screen ids a stored blob contributes to THIS session. A corrupt entry, a
+ * malformed shape, or a record belonging to a different session all read as "nothing remembered",
+ * because re-showing a screen is a far cheaper failure than trusting another session's answers.
+ */
+declare const readSettledPermissions: (raw: string | null | undefined, sessionId: string) => string[];
+/** Read the settled ids for `sessionId`. Never throws, never hangs past the shared read ceiling. */
+declare const loadSettledPermissions: (storage: WireOnboardingStorage, key: string, sessionId: string) => Promise<string[]>;
+/** Persist the settled ids for `sessionId` - fire-and-forget, all errors swallowed. */
+declare const saveSettledPermissions: (storage: WireOnboardingStorage, key: string, sessionId: string, ids: readonly string[]) => void;
+/** Drop the record (fired alongside the session seed on completion) - fire-and-forget. */
+declare const clearSettledPermissions: (storage: WireOnboardingStorage, key: string) => void;
+
 /** The canonical event name for an app-open. A trigger keys off this exact string. */
 declare const SESSION_STARTED_EVENT: "app.session_started";
 /** Options for {@link reportSessionStart}. Everything except `target` is optional so a pre-auth
@@ -1986,4 +2177,4 @@ interface UseLifecycleEventsOptions {
  */
 declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
 
-export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardGridSelectCard, CardHandoff, type CardHandoffProps, type CardHandoffVariant, type CardOption, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, ErrorBlock, FIRST_OPEN_EVENT, IconRegistryProvider, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, PLAN_TIER_CONTEXT_KEY, type PlanTier, type PurchaseProps, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, type RevenueCatBridge, type RevenueCatBridgeConfig, type RevenueCatCustomerInfoLike, type RevenueCatEntitlementLike, type RevenueCatErrorLike, type RevenueCatOfferingLike, type RevenueCatPackageLike, type RevenueCatProductLike, type RevenueCatSink, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, type UseLifecycleEventsOptions, type UseSessionStartOptions, type UseWireActivation, WIRE_ENV_VARS, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, WIRE_PURCHASE_EVENTS, type WireActivation, type WireActivationConfig, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, type WirePurchaseEventName, WireUserContext, activeEntitlement, attributionMetadata, bumpActivationRevalidation, createRevenueCatBridge, createWireActivation, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, describeEntitlement, describeFailure, describePackage, detectAppVersion, detectNativeModel, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, getActivationRevalidationVersion, isFeaturesFresh, isOnboardingEnabled, isUserCancelled, lookupIconGlyph, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetActivationRevalidation, resetFirstOpenLatch, resetSessionStartGuard, resolvePlanTier, subscribeActivationRevalidation, themeFromBrand, useActivationRevalidation, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireActivation, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };
+export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardGridSelectCard, CardHandoff, type CardHandoffProps, type CardHandoffVariant, type CardOption, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DEFAULT_PERMISSION_PLACEMENT, DemoOnboarding, type DemoOnboardingProps, DeviceContext, type DuePermissionScreen, ErrorBlock, FIRST_OPEN_EVENT, type FlowPosition, IconRegistryProvider, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, PERMISSION_CARD_NAME, PLAN_TIER_CONTEXT_KEY, PermissionCard, type PermissionCardProps, PermissionCardView, PermissionPlacement, PermissionScreenConfig, PermissionStage, type PlanTier, type PurchaseProps, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, type RevenueCatBridge, type RevenueCatBridgeConfig, type RevenueCatCustomerInfoLike, type RevenueCatEntitlementLike, type RevenueCatErrorLike, type RevenueCatOfferingLike, type RevenueCatPackageLike, type RevenueCatProductLike, type RevenueCatSink, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, type UseLifecycleEventsOptions, type UseSessionStartOptions, type UseWireActivation, WIRE_ENV_VARS, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, WIRE_PURCHASE_EVENTS, type WireActivation, type WireActivationConfig, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, WirePermissionOutcome, WirePermissionStatus, type WirePurchaseEventName, WireUserContext, activeEntitlement, attributionMetadata, bumpActivationRevalidation, clearSettledPermissions, createRevenueCatBridge, createWireActivation, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, describeEntitlement, describeFailure, describePackage, detectAppVersion, detectNativeModel, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, getActivationRevalidationVersion, isFeaturesFresh, isOnboardingEnabled, isPermissionDue, isUserCancelled, loadSettledPermissions, lookupIconGlyph, mergeTheme, motionSpec, normalizeAfterCard, onboardingComponents, parseWireFeatures, permissionScreenId, permissionStorageKey, readCachedFeatures, readProgress, readSettledPermissions, reportFirstOpen, reportSessionStart, resetActivationRevalidation, resetFirstOpenLatch, resetSessionStartGuard, resolvePlanTier, saveSettledPermissions, selectDuePermissionScreen, subscribeActivationRevalidation, themeFromBrand, useActivationRevalidation, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireActivation, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };