@wireai/activation 0.1.0

package/dist/questionnaire/index.d.mts

@@ -0,0 +1,249 @@
+import React__default from 'react';
+import { O as OnboardingTheme } from '../types-BKfpdZzX.mjs';
+import { C as CoachmarkStorage } from '../types-GL_hQ0TN.mjs';
+import { W as WireFeatures, a as WireFeaturesConfig } from '../types-CMuOexw0.mjs';
+export { G as GateRules, a as GateSignals, e as evaluateGate, r as resolveRules } from '../decision-Cl8OFYzu.mjs';
+
+/**
+ * The firing verdict - the SAME contract on both sides of the seam. `decideQuestionnaire`
+ * turns local rules into one of these; a server `{fire, reason}` (from
+ * GET /v1/questionnaires/decision) is the exact same shape and OVERRIDES the local one.
+ */
+interface QuestionnaireDecision {
+    fire: boolean;
+    reason?: string;
+}
+/**
+ * The questionnaire the kit renders. Comes from the server decision (`questionnaire`
+ * field) or a local literal. `id` is required (the once-gate + keys derive from it); the
+ * labels and title are optional (sensible defaults render when absent). The optional
+ * firing-rule fields are the LOCAL fallback the decision hook evaluates when no server
+ * decision is passed, mirroring `ReviewConfig`.
+ */
+interface QuestionnaireDefinition {
+    /** Gate key. Seen/last-shown/session keys derive from it (`wire_questionnaire_<id>_*`). */
+    id: string;
+    /** Popup heading. Defaults to a neutral prompt when absent. */
+    title?: string;
+    /** Label for the MANDATORY opinion box ("what do you think about the app"). */
+    opinion_label?: string;
+    /** Label for the first OPTIONAL box ("help us improve"). */
+    improve_label?: string;
+    /** Label for the second OPTIONAL box ("suggestions"). */
+    suggestions_label?: string;
+    /** Master local switch. Default true. */
+    enabled?: boolean;
+    /** Require at least this many sessions on the device before showing. Default 0. */
+    minSessions?: number;
+    /** Require at least this many tracked app events before showing. Default 0. */
+    minEvents?: number;
+    /** Suppress a re-prompt within this many days of the last shown. Default 0 (off). */
+    cooldownDays?: number;
+    /** Show at most once per app version (seen-gate keyed by `appVersion`). Default true. */
+    oncePerVersion?: boolean;
+    /** The current app version, for the once-per-version seen gate. */
+    appVersion?: string;
+    /**
+     * Client fallback ONLY: if no server decision arrives within this many ms of mount,
+     * fall back to the local rules. Null/absent → evaluate local rules immediately.
+     */
+    timeoutFallbackMs?: number | null;
+}
+/** The user's three answers. `opinion` is the only mandatory one. */
+interface QuestionnaireAnswers {
+    /** The mandatory "what do you think about the app" free text. */
+    opinion: string;
+    /** The optional "help us improve" free text. */
+    improve?: string;
+    /** The optional "suggestions" free text. */
+    suggestions?: string;
+}
+/** Non-PII correlation extras sent with a submission (the `meta` bucket in the POST body). */
+interface QuestionnaireMeta {
+    user_id?: string | null;
+    device_key?: string | null;
+    session_count?: number | null;
+}
+/**
+ * The POST body sent to `POST /v1/questionnaires/{id}/responses` (mirrors the server
+ * contract). `opinion` is always present; `improve`/`suggestions` are null when empty.
+ */
+interface QuestionnaireSubmission {
+    session_id: string | null;
+    answers: {
+        opinion: string;
+        improve: string | null;
+        suggestions: string | null;
+    };
+    meta: QuestionnaireMeta;
+}
+/**
+ * The GET /v1/questionnaires/decision response. `fire` gates showing; `questionnaire` is
+ * the definition to render when firing. Hard fail-open on the transport: an unreachable
+ * endpoint or a 404 resolves to null so the host simply never shows the gate.
+ */
+interface QuestionnaireDecisionResponse {
+    fire: boolean;
+    reason?: string;
+    questionnaire?: QuestionnaireDefinition | null;
+}
+/** The analytics moments, mirrored on the coachmark callback convention (no PII, no free text). */
+type QuestionnaireGateEventName = "questionnaire_prompt_shown" | "questionnaire_submitted" | "questionnaire_dismissed";
+/** One analytics moment. Carries the gate id only; answers ride ONLY in the POST body. */
+interface QuestionnaireGateEvent {
+    name: QuestionnaireGateEventName;
+    /** The gate id (`questionnaire.id`). */
+    id: string;
+}
+/** Where kit → server requests go (same tenant creds as the onboarding flow). */
+interface QuestionnaireTarget {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`). */
+    serverUrl: string;
+    /** Tenant API key, sent as `Authorization: Bearer`. */
+    apiKey: string;
+}
+/** Props for the `QuestionnaireGate` popup component. */
+interface QuestionnaireGateProps {
+    /** The questionnaire to render (title + labels + id). */
+    questionnaire: QuestionnaireDefinition;
+    /** Where to POST the submission. Omit to skip the network (callbacks still fire). */
+    target?: QuestionnaireTarget;
+    /** The onboarding/session id correlated with the response, when known. */
+    sessionId?: string | null;
+    /** Small non-PII extras stored with the response (user_id, device_key, session_count). */
+    meta?: QuestionnaireMeta;
+    /** Fired at each analytics moment (host wires it to its own analytics). No PII. */
+    onEvent?: (event: QuestionnaireGateEvent) => void;
+    /** Called once the gate is resolved (submitted or dismissed). */
+    onResolved?: () => void;
+    /** Called when the gate first renders to the user (also fires `questionnaire_prompt_shown`). */
+    onShown?: () => void;
+    /** Partial theme merged over the active onboarding theme. */
+    theme?: Partial<OnboardingTheme>;
+    /** Show a Skip/Not now control. Default true (always skippable, never a dead end). */
+    dismissible?: boolean;
+}
+/** Options for `useQuestionnaireGate` - the WHEN decision. */
+interface UseQuestionnaireGateOptions {
+    /** The questionnaire definition (id + local firing rules). */
+    config: QuestionnaireDefinition;
+    /** Server-provided decision (from GET /v1/questionnaires/decision). OVERRIDES local rules. */
+    decision?: QuestionnaireDecision;
+    /** Current tracked app-event count (host-owned), for the `minEvents` rule. */
+    events?: number;
+    /** Sync gate storage. Defaults to the storage injected by CoachmarkProvider. */
+    storage?: CoachmarkStorage | null;
+    /** Testing override; defaults to the global `isTestingCoachmark` flag. */
+    isTesting?: boolean;
+    /**
+     * OPTIONAL feature-flag wiring - the questionnaire MASTER switch. When
+     * `flags.questionnaire.enabled` is false, the gate NEVER fires (`visible` stays false,
+     * verdict reason `feature_disabled`), whatever the local rules or a server decision say -
+     * it composes as an extra AND on top of the decision seam. Provide pre-resolved `features`,
+     * OR a `featuresConfig` to lazily fetch once, OR mount a `WireFeaturesProvider` above
+     * (context is read automatically). Omit all three and the questionnaire stays on (fail-open).
+     */
+    features?: WireFeatures;
+    /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
+    featuresConfig?: WireFeaturesConfig;
+}
+/** What `useQuestionnaireGate` returns. */
+interface QuestionnaireGateController {
+    /** Whether the gate should be shown right now. */
+    visible: boolean;
+    /** The resolved verdict (local rules or the server override). For debugging/analytics. */
+    decision: QuestionnaireDecision;
+    /** Persist the last-shown timestamp. Call when the gate becomes visible. */
+    markShown: () => void;
+    /** Write the once-per-user seen gate. Call when the gate is resolved. */
+    markResolved: () => void;
+}
+
+/**
+ * QuestionnaireGate - the skippable pre-onboarding questionnaire popup.
+ *
+ * A centered popup (over the shared `CenteredModal` shell) with three inputs:
+ *   • a MANDATORY multiline "what do you think about the app" box (~4 lines), and
+ *   • two OPTIONAL smaller boxes ("help us improve" + "suggestions").
+ * Send is disabled ONLY until the opinion box has text; the two optional boxes never gate it.
+ * The gate is ALWAYS skippable (a "Not now"/"Skip" link plays the popup exit), so it is never
+ * a dead end. On send it builds the contract body and fire-and-forgets it to the Wire server,
+ * then shows a warm thank-you until the user taps the backdrop to close.
+ *
+ * The form NEVER asks for identity (no name / email / contact field): the host already
+ * identifies the user via `sessionId` + `meta` (user_id, device_key, session_count), which is
+ * all the POST body carries alongside the answers. Every visual value comes from the
+ * OnboardingTheme; analytics are callback-based (no PII - answers go ONLY in the POST body).
+ */
+
+declare const QuestionnaireGate: React__default.FC<QuestionnaireGateProps>;
+
+declare const useQuestionnaireGate: ({ config: configProp, decision: decisionProp, events, storage, isTesting, features, featuresConfig, }: UseQuestionnaireGateOptions) => QuestionnaireGateController;
+
+/**
+ * The seam. `decision` absent → the local verdict stands; present → it overrides. Same
+ * contract philosophy as `decideReview(local, decision?)`.
+ */
+declare const decideQuestionnaire: (local: QuestionnaireDecision, decision?: QuestionnaireDecision) => QuestionnaireDecision;
+/**
+ * Build the `POST /v1/questionnaires/{id}/responses` body. `opinion` is the only mandatory
+ * answer (trimmed); `improve`/`suggestions` are trimmed and sent as `null` when empty. The
+ * `meta` bucket carries the non-PII correlation fields (user_id / device_key / session_count),
+ * each defaulting to null. Free text lives ONLY here, never in analytics events.
+ */
+declare const buildQuestionnaireSubmission: (input: {
+    answers: QuestionnaireAnswers;
+    sessionId?: string | null;
+    meta?: QuestionnaireMeta;
+}) => QuestionnaireSubmission;
+
+/**
+ * transport.ts - kit → Wire server requests for the questionnaire module, all fire-and-forget
+ * (a pre-onboarding questionnaire must NEVER break the app). Mirrors `submitReview`: a thin
+ * fetch wrapper, Bearer tenant key, swallow every error.
+ *
+ *   • submitQuestionnaireResponse → POST {serverUrl}/v1/questionnaires/{id}/responses
+ *   • fetchQuestionnaireDecision  → GET  {serverUrl}/v1/questionnaires/decision  (best-effort)
+ *
+ * The decision fetch is HARD fail-open on the "never show" side: an unreachable endpoint, a
+ * non-2xx (incl. 404), a missing `fetch`, or bad JSON all resolve to null, so a host wiring
+ * pure server-directed firing simply shows nothing - exactly the reviews decision seam.
+ */
+
+/**
+ * POST a questionnaire response. Fire-and-forget: a missing target, a missing id, a build
+ * error, a missing `fetch`, or a network failure is swallowed and the call returns immediately.
+ */
+declare const submitQuestionnaireResponse: (target: QuestionnaireTarget | undefined, id: string, submission: QuestionnaireSubmission) => void;
+/** Options for the best-effort decision fetch. `deviceKey` groups a device's sessions server-side. */
+interface FetchQuestionnaireDecisionOptions {
+    /** The onboarding/session id to correlate with, when known. */
+    sessionId?: string;
+    /** A stable, non-PII device id - the decision endpoint reads it for min-sessions. */
+    deviceKey?: string;
+}
+/**
+ * Best-effort fetch of the server firing decision. Returns the parsed
+ * `{ fire, reason, questionnaire }` on a 2xx, else null. NEVER throws - any failure resolves
+ * to null (fail-safe: the host shows nothing). The kit does not call this internally; a host
+ * that wants server-directed firing awaits it and passes the result to `useQuestionnaireGate`
+ * (the same AI seam the reviews gate uses).
+ */
+declare const fetchQuestionnaireDecision: (target: QuestionnaireTarget | undefined, options?: FetchQuestionnaireDecisionOptions) => Promise<QuestionnaireDecisionResponse | null>;
+
+/**
+ * Runtime helpers for the questionnaire gate: the `wire_questionnaire_*` gate keys. The
+ * gate reuses the SAME injected sync storage + global testing flag as the coachmark engine
+ * (via `resolveStorage`/`readInt`/`writeInt`, re-exported from the reviews runtime), so a
+ * host that mounted CoachmarkProvider gets questionnaire gating for free - no second storage
+ * to wire. Once-per-user is keyed on the questionnaire `id`.
+ */
+
+/** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
+declare const questionnaireSeenKey: (id: string, version?: string) => string;
+/** Last-shown timestamp key (epoch ms), for the cooldown rule. */
+declare const questionnaireLastShownKey: (id: string) => string;
+/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+declare const questionnaireSessionsKey: (id: string) => string;
+
+export { type FetchQuestionnaireDecisionOptions, type QuestionnaireAnswers, type QuestionnaireDecision, type QuestionnaireDecisionResponse, type QuestionnaireDefinition, QuestionnaireGate, type QuestionnaireGateController, type QuestionnaireGateEvent, type QuestionnaireGateEventName, type QuestionnaireGateProps, type QuestionnaireMeta, type QuestionnaireSubmission, type QuestionnaireTarget, type UseQuestionnaireGateOptions, buildQuestionnaireSubmission, decideQuestionnaire, fetchQuestionnaireDecision, questionnaireLastShownKey, questionnaireSeenKey, questionnaireSessionsKey, submitQuestionnaireResponse, useQuestionnaireGate };

package/dist/questionnaire/index.d.ts

@@ -0,0 +1,249 @@
+import React__default from 'react';
+import { O as OnboardingTheme } from '../types-BKfpdZzX.js';
+import { C as CoachmarkStorage } from '../types-GL_hQ0TN.js';
+import { W as WireFeatures, a as WireFeaturesConfig } from '../types-CMuOexw0.js';
+export { G as GateRules, a as GateSignals, e as evaluateGate, r as resolveRules } from '../decision-CFvGY6nP.js';
+
+/**
+ * The firing verdict - the SAME contract on both sides of the seam. `decideQuestionnaire`
+ * turns local rules into one of these; a server `{fire, reason}` (from
+ * GET /v1/questionnaires/decision) is the exact same shape and OVERRIDES the local one.
+ */
+interface QuestionnaireDecision {
+    fire: boolean;
+    reason?: string;
+}
+/**
+ * The questionnaire the kit renders. Comes from the server decision (`questionnaire`
+ * field) or a local literal. `id` is required (the once-gate + keys derive from it); the
+ * labels and title are optional (sensible defaults render when absent). The optional
+ * firing-rule fields are the LOCAL fallback the decision hook evaluates when no server
+ * decision is passed, mirroring `ReviewConfig`.
+ */
+interface QuestionnaireDefinition {
+    /** Gate key. Seen/last-shown/session keys derive from it (`wire_questionnaire_<id>_*`). */
+    id: string;
+    /** Popup heading. Defaults to a neutral prompt when absent. */
+    title?: string;
+    /** Label for the MANDATORY opinion box ("what do you think about the app"). */
+    opinion_label?: string;
+    /** Label for the first OPTIONAL box ("help us improve"). */
+    improve_label?: string;
+    /** Label for the second OPTIONAL box ("suggestions"). */
+    suggestions_label?: string;
+    /** Master local switch. Default true. */
+    enabled?: boolean;
+    /** Require at least this many sessions on the device before showing. Default 0. */
+    minSessions?: number;
+    /** Require at least this many tracked app events before showing. Default 0. */
+    minEvents?: number;
+    /** Suppress a re-prompt within this many days of the last shown. Default 0 (off). */
+    cooldownDays?: number;
+    /** Show at most once per app version (seen-gate keyed by `appVersion`). Default true. */
+    oncePerVersion?: boolean;
+    /** The current app version, for the once-per-version seen gate. */
+    appVersion?: string;
+    /**
+     * Client fallback ONLY: if no server decision arrives within this many ms of mount,
+     * fall back to the local rules. Null/absent → evaluate local rules immediately.
+     */
+    timeoutFallbackMs?: number | null;
+}
+/** The user's three answers. `opinion` is the only mandatory one. */
+interface QuestionnaireAnswers {
+    /** The mandatory "what do you think about the app" free text. */
+    opinion: string;
+    /** The optional "help us improve" free text. */
+    improve?: string;
+    /** The optional "suggestions" free text. */
+    suggestions?: string;
+}
+/** Non-PII correlation extras sent with a submission (the `meta` bucket in the POST body). */
+interface QuestionnaireMeta {
+    user_id?: string | null;
+    device_key?: string | null;
+    session_count?: number | null;
+}
+/**
+ * The POST body sent to `POST /v1/questionnaires/{id}/responses` (mirrors the server
+ * contract). `opinion` is always present; `improve`/`suggestions` are null when empty.
+ */
+interface QuestionnaireSubmission {
+    session_id: string | null;
+    answers: {
+        opinion: string;
+        improve: string | null;
+        suggestions: string | null;
+    };
+    meta: QuestionnaireMeta;
+}
+/**
+ * The GET /v1/questionnaires/decision response. `fire` gates showing; `questionnaire` is
+ * the definition to render when firing. Hard fail-open on the transport: an unreachable
+ * endpoint or a 404 resolves to null so the host simply never shows the gate.
+ */
+interface QuestionnaireDecisionResponse {
+    fire: boolean;
+    reason?: string;
+    questionnaire?: QuestionnaireDefinition | null;
+}
+/** The analytics moments, mirrored on the coachmark callback convention (no PII, no free text). */
+type QuestionnaireGateEventName = "questionnaire_prompt_shown" | "questionnaire_submitted" | "questionnaire_dismissed";
+/** One analytics moment. Carries the gate id only; answers ride ONLY in the POST body. */
+interface QuestionnaireGateEvent {
+    name: QuestionnaireGateEventName;
+    /** The gate id (`questionnaire.id`). */
+    id: string;
+}
+/** Where kit → server requests go (same tenant creds as the onboarding flow). */
+interface QuestionnaireTarget {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`). */
+    serverUrl: string;
+    /** Tenant API key, sent as `Authorization: Bearer`. */
+    apiKey: string;
+}
+/** Props for the `QuestionnaireGate` popup component. */
+interface QuestionnaireGateProps {
+    /** The questionnaire to render (title + labels + id). */
+    questionnaire: QuestionnaireDefinition;
+    /** Where to POST the submission. Omit to skip the network (callbacks still fire). */
+    target?: QuestionnaireTarget;
+    /** The onboarding/session id correlated with the response, when known. */
+    sessionId?: string | null;
+    /** Small non-PII extras stored with the response (user_id, device_key, session_count). */
+    meta?: QuestionnaireMeta;
+    /** Fired at each analytics moment (host wires it to its own analytics). No PII. */
+    onEvent?: (event: QuestionnaireGateEvent) => void;
+    /** Called once the gate is resolved (submitted or dismissed). */
+    onResolved?: () => void;
+    /** Called when the gate first renders to the user (also fires `questionnaire_prompt_shown`). */
+    onShown?: () => void;
+    /** Partial theme merged over the active onboarding theme. */
+    theme?: Partial<OnboardingTheme>;
+    /** Show a Skip/Not now control. Default true (always skippable, never a dead end). */
+    dismissible?: boolean;
+}
+/** Options for `useQuestionnaireGate` - the WHEN decision. */
+interface UseQuestionnaireGateOptions {
+    /** The questionnaire definition (id + local firing rules). */
+    config: QuestionnaireDefinition;
+    /** Server-provided decision (from GET /v1/questionnaires/decision). OVERRIDES local rules. */
+    decision?: QuestionnaireDecision;
+    /** Current tracked app-event count (host-owned), for the `minEvents` rule. */
+    events?: number;
+    /** Sync gate storage. Defaults to the storage injected by CoachmarkProvider. */
+    storage?: CoachmarkStorage | null;
+    /** Testing override; defaults to the global `isTestingCoachmark` flag. */
+    isTesting?: boolean;
+    /**
+     * OPTIONAL feature-flag wiring - the questionnaire MASTER switch. When
+     * `flags.questionnaire.enabled` is false, the gate NEVER fires (`visible` stays false,
+     * verdict reason `feature_disabled`), whatever the local rules or a server decision say -
+     * it composes as an extra AND on top of the decision seam. Provide pre-resolved `features`,
+     * OR a `featuresConfig` to lazily fetch once, OR mount a `WireFeaturesProvider` above
+     * (context is read automatically). Omit all three and the questionnaire stays on (fail-open).
+     */
+    features?: WireFeatures;
+    /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
+    featuresConfig?: WireFeaturesConfig;
+}
+/** What `useQuestionnaireGate` returns. */
+interface QuestionnaireGateController {
+    /** Whether the gate should be shown right now. */
+    visible: boolean;
+    /** The resolved verdict (local rules or the server override). For debugging/analytics. */
+    decision: QuestionnaireDecision;
+    /** Persist the last-shown timestamp. Call when the gate becomes visible. */
+    markShown: () => void;
+    /** Write the once-per-user seen gate. Call when the gate is resolved. */
+    markResolved: () => void;
+}
+
+/**
+ * QuestionnaireGate - the skippable pre-onboarding questionnaire popup.
+ *
+ * A centered popup (over the shared `CenteredModal` shell) with three inputs:
+ *   • a MANDATORY multiline "what do you think about the app" box (~4 lines), and
+ *   • two OPTIONAL smaller boxes ("help us improve" + "suggestions").
+ * Send is disabled ONLY until the opinion box has text; the two optional boxes never gate it.
+ * The gate is ALWAYS skippable (a "Not now"/"Skip" link plays the popup exit), so it is never
+ * a dead end. On send it builds the contract body and fire-and-forgets it to the Wire server,
+ * then shows a warm thank-you until the user taps the backdrop to close.
+ *
+ * The form NEVER asks for identity (no name / email / contact field): the host already
+ * identifies the user via `sessionId` + `meta` (user_id, device_key, session_count), which is
+ * all the POST body carries alongside the answers. Every visual value comes from the
+ * OnboardingTheme; analytics are callback-based (no PII - answers go ONLY in the POST body).
+ */
+
+declare const QuestionnaireGate: React__default.FC<QuestionnaireGateProps>;
+
+declare const useQuestionnaireGate: ({ config: configProp, decision: decisionProp, events, storage, isTesting, features, featuresConfig, }: UseQuestionnaireGateOptions) => QuestionnaireGateController;
+
+/**
+ * The seam. `decision` absent → the local verdict stands; present → it overrides. Same
+ * contract philosophy as `decideReview(local, decision?)`.
+ */
+declare const decideQuestionnaire: (local: QuestionnaireDecision, decision?: QuestionnaireDecision) => QuestionnaireDecision;
+/**
+ * Build the `POST /v1/questionnaires/{id}/responses` body. `opinion` is the only mandatory
+ * answer (trimmed); `improve`/`suggestions` are trimmed and sent as `null` when empty. The
+ * `meta` bucket carries the non-PII correlation fields (user_id / device_key / session_count),
+ * each defaulting to null. Free text lives ONLY here, never in analytics events.
+ */
+declare const buildQuestionnaireSubmission: (input: {
+    answers: QuestionnaireAnswers;
+    sessionId?: string | null;
+    meta?: QuestionnaireMeta;
+}) => QuestionnaireSubmission;
+
+/**
+ * transport.ts - kit → Wire server requests for the questionnaire module, all fire-and-forget
+ * (a pre-onboarding questionnaire must NEVER break the app). Mirrors `submitReview`: a thin
+ * fetch wrapper, Bearer tenant key, swallow every error.
+ *
+ *   • submitQuestionnaireResponse → POST {serverUrl}/v1/questionnaires/{id}/responses
+ *   • fetchQuestionnaireDecision  → GET  {serverUrl}/v1/questionnaires/decision  (best-effort)
+ *
+ * The decision fetch is HARD fail-open on the "never show" side: an unreachable endpoint, a
+ * non-2xx (incl. 404), a missing `fetch`, or bad JSON all resolve to null, so a host wiring
+ * pure server-directed firing simply shows nothing - exactly the reviews decision seam.
+ */
+
+/**
+ * POST a questionnaire response. Fire-and-forget: a missing target, a missing id, a build
+ * error, a missing `fetch`, or a network failure is swallowed and the call returns immediately.
+ */
+declare const submitQuestionnaireResponse: (target: QuestionnaireTarget | undefined, id: string, submission: QuestionnaireSubmission) => void;
+/** Options for the best-effort decision fetch. `deviceKey` groups a device's sessions server-side. */
+interface FetchQuestionnaireDecisionOptions {
+    /** The onboarding/session id to correlate with, when known. */
+    sessionId?: string;
+    /** A stable, non-PII device id - the decision endpoint reads it for min-sessions. */
+    deviceKey?: string;
+}
+/**
+ * Best-effort fetch of the server firing decision. Returns the parsed
+ * `{ fire, reason, questionnaire }` on a 2xx, else null. NEVER throws - any failure resolves
+ * to null (fail-safe: the host shows nothing). The kit does not call this internally; a host
+ * that wants server-directed firing awaits it and passes the result to `useQuestionnaireGate`
+ * (the same AI seam the reviews gate uses).
+ */
+declare const fetchQuestionnaireDecision: (target: QuestionnaireTarget | undefined, options?: FetchQuestionnaireDecisionOptions) => Promise<QuestionnaireDecisionResponse | null>;
+
+/**
+ * Runtime helpers for the questionnaire gate: the `wire_questionnaire_*` gate keys. The
+ * gate reuses the SAME injected sync storage + global testing flag as the coachmark engine
+ * (via `resolveStorage`/`readInt`/`writeInt`, re-exported from the reviews runtime), so a
+ * host that mounted CoachmarkProvider gets questionnaire gating for free - no second storage
+ * to wire. Once-per-user is keyed on the questionnaire `id`.
+ */
+
+/** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
+declare const questionnaireSeenKey: (id: string, version?: string) => string;
+/** Last-shown timestamp key (epoch ms), for the cooldown rule. */
+declare const questionnaireLastShownKey: (id: string) => string;
+/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+declare const questionnaireSessionsKey: (id: string) => string;
+
+export { type FetchQuestionnaireDecisionOptions, type QuestionnaireAnswers, type QuestionnaireDecision, type QuestionnaireDecisionResponse, type QuestionnaireDefinition, QuestionnaireGate, type QuestionnaireGateController, type QuestionnaireGateEvent, type QuestionnaireGateEventName, type QuestionnaireGateProps, type QuestionnaireMeta, type QuestionnaireSubmission, type QuestionnaireTarget, type UseQuestionnaireGateOptions, buildQuestionnaireSubmission, decideQuestionnaire, fetchQuestionnaireDecision, questionnaireLastShownKey, questionnaireSeenKey, questionnaireSessionsKey, submitQuestionnaireResponse, useQuestionnaireGate };