@firstflow/react 0.0.1 → 0.0.101

package/dist/index.d.mts

@@ -1,283 +1,124 @@
+import { R as RawIssuesConfig, a as RawFeedbackConfig, E as ExperienceSettings, U as UserContext, A as AudienceMembershipMap, S as SurveySubmitPayload, b as SurveyQuestion, c as SurveyAnswerValue, d as SurveyModulePublic, F as FirstflowInstance$1, C as CreateFirstflowOptions } from './events-DAiGBrYc.mjs';
+export { e as AnalyticsModulePublic, f as AudienceConfig, g as AudienceRule, h as CHAT_MESSAGE_SENT, i as EXPERIENCE_ANALYTICS_TYPE, j as EXPERIENCE_CLICKED, k as EXPERIENCE_SHOWN, l as FirstflowWidgetUi, m as RuleOperator, n as SURVEY_COMPLETED, o as SurveyExperience } from './events-DAiGBrYc.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
-interface CreateFirstflowOptions {
-    agentId: string;
-    apiUrl: string;
-    /** Jitsu host for analytics; defaults to shared Firstflow Jitsu if omitted */
-    jitsuHost?: string;
-    /** Jitsu write key for analytics; defaults to shared key if omitted */
-    jitsuWriteKey?: string;
-    /** When set without fetchConfig, seeds message feedback UI (agents.feedback_config shape). */
-    feedbackConfig?: RawFeedbackConfig | null;
-}
-/**
- * Public API for the issue module only (open, submit, getConfig, destroy).
- * Internal wiring (setConfig, setOpenHandler) is not exposed.
- */
-interface IssueModulePublic {
-    open(options?: OpenOptions): void;
-    submit(data: IssueReportData): Promise<void>;
-    getConfig(): NormalizedConfig;
-    destroy(): void;
-}
-/** Analytics API exposed on the platform instance. Used by all feature modules. */
-interface AnalyticsModulePublic {
-    track(eventName: string, properties?: Record<string, unknown>): void;
-    identify(userId?: string, traits?: Record<string, unknown>): void;
-    page(name?: string, properties?: Record<string, unknown>): void;
-}
-/**
- * Root platform instance: agent identity, analytics, and feature modules.
- * Represents the runtime context for this agent at this API.
- */
-interface FirstflowInstance {
-    readonly agentId: string;
-    readonly apiUrl: string;
-    analytics: AnalyticsModulePublic;
-    issue: IssueModulePublic;
-    feedback: FeedbackModulePublic;
-}
-/**
- * Raw issues config as received from API (e.g. agent.issues_config).
- */
-interface RawIssueFieldConfig {
-    id?: string;
-    allowed?: boolean;
-    label?: string;
-    type?: "text" | "textarea" | "select";
-    required?: boolean;
-    options?: string[];
-}
-interface RawIssuesConfig {
-    enabled?: boolean;
-    promptText?: string;
-    fields?: RawIssueFieldConfig[];
-}
-interface RawFeedbackFormConfig {
-    tags?: string[];
-    heading?: string;
-    placeholder?: string;
-    showTags?: boolean;
-    showComment?: boolean;
-}
-interface RawFeedbackConfig {
-    enabled?: boolean;
-    like?: RawFeedbackFormConfig;
-    dislike?: RawFeedbackFormConfig;
-}
-interface NormalizedFeedbackFormConfig {
-    tags: string[];
-    heading: string;
-    placeholder: string;
-    showTags: boolean;
-    showComment: boolean;
-}
-interface NormalizedFeedbackConfig {
-    enabled: boolean;
-    like: NormalizedFeedbackFormConfig;
-    dislike: NormalizedFeedbackFormConfig;
-}
-interface MessageFeedbackSubmitPayload {
-    conversationId: string;
-    messageId: string;
-    rating: "like" | "dislike";
-    /** Used by MessageFeedback UI only; not included on the Jitsu event. */
-    tags?: string[];
-    comment?: string;
-    /** Mirrors config: whether tags/comment were enabled for this sentiment at submit time. */
-    showTags?: boolean;
-    showComment?: boolean;
-    messagePreview?: string;
-    /**
-     * Arbitrary JSON-serializable key/value bag (e.g. locale, page_url, model, experiment_id).
-     * Sent on the Jitsu event as property `metadata` after JSON round-trip (max ~32KB serialized).
-     */
-    metadata?: Record<string, unknown>;
-}
-interface FeedbackModulePublic {
-    submit(payload: MessageFeedbackSubmitPayload): Promise<void>;
-    getConfig(): NormalizedFeedbackConfig;
-    isEnabled(): boolean;
-}
 /**
- * Normalized field config used internally (after filtering allowed, defaulting type/label).
+ * Runtime flow returned by `GET /agents/:id/config` (`flow` on each experience).
+ * Editor-only fields (viewport, measured, positions, React Flow styles) are omitted server-side.
  */
-interface NormalizedFieldConfig {
+type SdkRuntimeFlowNode = {
     id: string;
-    type: "text" | "textarea" | "select";
-    label: string;
-    required: boolean;
-    options?: string[];
-}
-/**
- * Normalized config: single source of truth for the SDK.
- */
-interface NormalizedConfig {
-    agentId: string;
-    apiUrl: string;
-    enabled: boolean;
-    promptText: string;
-    fields: NormalizedFieldConfig[];
-}
-/**
- * Form field values only (keys = field ids). Validated before submit.
- * Validation applies to this only.
- */
-type IssueFormValues = Record<string, string | undefined>;
-/**
- * Context metadata: set programmatically (e.g. open({ messageId })). Never validated.
- * Merged with form values at submit time. Users can add arbitrary JSON-serializable keys/values.
- */
-type IssueContextMetadata = {
-    conversationId?: string;
-    messageId?: string;
-    sessionId?: string;
-    agentId?: string;
-    model?: string;
-} & Record<string, unknown>;
-/**
- * Options passed to open() (e.g. "Report this response").
- */
-type OpenOptions = IssueContextMetadata;
-/**
- * Final submission payload: form values + context metadata. Sent to transport.
- * Values can be primitives (form fields) or arbitrary JSON-serializable metadata.
- */
-type IssuePayload = Record<string, unknown>;
-/**
- * Options for createIssueReporter. Config is optional; when omitted, defaults are used.
- * When analytics is omitted, a default analytics instance is created (same Jitsu config).
- */
-interface CreateIssueReporterOptions {
-    agentId: string;
-    apiUrl: string;
-    config?: Partial<RawIssuesConfig>;
-    /** Platform analytics; issue module calls analytics.track('issue_submitted', payload). Defaults to createAnalytics({ agentId }) when omitted. */
-    analytics?: AnalyticsModulePublic;
-}
-/**
- * Validation result.
- */
-interface ValidationResult {
-    valid: boolean;
-    errors?: Record<string, string>;
-}
-type IssueReportData = Record<string, unknown>;
-/**
- * Instance returned by createIssueReporter.
- * setConfig is used internally when config is loaded asynchronously (e.g. via useCreateFirstflow + fetchConfig).
- */
-interface IssueReporterInstance {
-    getConfig(): NormalizedConfig;
-    setConfig(config: NormalizedConfig): void;
-    reportIssue(data: IssueReportData): Promise<void>;
-    open(options?: OpenOptions): void;
-    setOpenHandler(handler: ((options?: OpenOptions) => void) | undefined): void;
-    destroy(): void;
-}
-
-/**
- * Platform event names. Feature modules use these when calling analytics.track().
- * Do not rename existing events (e.g. issue_submitted) to avoid breaking pipelines.
- */
-/** Issue module — backward compatible */
-declare const ISSUE_SUBMITTED = "issue_submitted";
-/** Future modules */
-declare const FEEDBACK_SUBMITTED = "feedback_submitted";
-declare const SURVEY_COMPLETED = "survey_completed";
-declare const EXPERIENCE_SHOWN = "experience_shown";
-declare const EXPERIENCE_CLICKED = "experience_clicked";
-declare const CHAT_MESSAGE_SENT = "chat_message_sent";
-
-declare function createFirstflow(options: CreateFirstflowOptions): FirstflowInstance;
-
+    type?: string;
+    data?: Record<string, unknown>;
+};
+type SdkRuntimeFlowEdge = {
+    id?: string;
+    source: string;
+    target: string;
+};
+type SdkRuntimeFlow = {
+    nodes: SdkRuntimeFlowNode[];
+    edges: SdkRuntimeFlowEdge[];
+};
 /** Active experience row as returned on public agent config (subset of DB). */
 type SdkAgentConfigExperience = {
     id?: string;
     name?: string | null;
     status?: string | null;
-    flow?: {
-        nodes?: unknown[];
-        edges?: unknown[];
-    } | null;
+    type?: string | null;
+    flow?: SdkRuntimeFlow | null;
+    settings?: ExperienceSettings | null;
+};
+/** Optional widget branding from the agent record (public config). */
+type SdkAgentWidgetUi = {
+    /** Hex (or CSS color) used for announcement CTAs / accents when set. */
+    primaryColor?: string;
 };
 type SdkAgentConfigPayload = {
     issues_config?: RawIssuesConfig;
     feedback_config?: RawFeedbackConfig;
-    /** Active experiences including saved flow (nodes/edges from canvas). */
+    /** Active experiences with runtime flow graphs (SDK-safe shape). */
     experiences?: SdkAgentConfigExperience[];
+    /** From `agent.widget_ui` or top-level `primary_color` when present. */
+    widget_ui?: SdkAgentWidgetUi | null;
 };
-declare function fetchSdkAgentConfig(apiUrl: string, agentId: string): Promise<SdkAgentConfigPayload>;
+declare function fetchSdkAgentConfig(apiUrl: string, agentId: string, apiKey?: string): Promise<SdkAgentConfigPayload>;
 
 type FirstflowProviderProps = {
-    firstflow: FirstflowInstance;
+    agentId: string;
+    apiKey?: string;
     children: ReactNode;
-    /** Optional payload from `fetchSdkAgentConfig` / `useCreateFirstflow` (issues, feedback, experiences). */
-    config?: SdkAgentConfigPayload | null;
+    fallback?: ReactNode;
+    onError?: (error: Error) => void;
+    initialSdkPayload?: SdkAgentConfigPayload | null;
+    user?: UserContext | null;
+    audienceMembership?: AudienceMembershipMap;
+    autoFetchAudienceMembership?: boolean;
 };
-/**
- * Provides the platform instance to the tree. Transitional: delegates to
- * IssueReporterProvider with the internal issue instance so that
- * firstflow.issue.open() opens the modal. This is a migration/composition step;
- * the final architecture may use a single provider for multiple feature modules.
- */
-declare function FirstflowProvider({ firstflow, children, config }: FirstflowProviderProps): react_jsx_runtime.JSX.Element;
-declare function useFirstflow(): FirstflowInstance;
-/** SDK agent config (including `experiences`) when passed to `FirstflowProvider`; otherwise null. */
-declare function useFirstflowConfig(): SdkAgentConfigPayload | null;
+declare function FirstflowProvider({ agentId, apiKey, children, fallback, onError, initialSdkPayload, user, audienceMembership, autoFetchAudienceMembership, }: FirstflowProviderProps): react_jsx_runtime.JSX.Element;
 
-type UseCreateFirstflowOptions = {
-    fetchConfig?: boolean;
+type AudienceOverrides = {
+    blockedExperiences: string[];
+    forcedExperiences: string[];
 };
-type UseCreateFirstflowResult = {
-    firstflow: FirstflowInstance | null;
-    loading: boolean;
-    error: Error | null;
-    /** Full SDK config from `GET /agents/:id/config` when `fetchConfig: true`; otherwise null. */
-    config: SdkAgentConfigPayload | null;
+
+type NormalizedExperienceRow = {
+    experienceId: string;
+    name?: string | null;
+    status: string | null;
+    type?: string | null;
+    settings?: ExperienceSettings | null;
+    flow?: {
+        nodes?: unknown[];
+        edges?: unknown[];
+    } | null;
+};
+
+type FirstflowRuntimeSnapshot = {
+    version: number;
+    user: UserContext | null;
+    audienceMembership: AudienceMembershipMap;
+    overrides: AudienceOverrides;
+    experienceRows: NormalizedExperienceRow[];
 };
-declare function useCreateFirstflow(agentId: string, apiUrl: string, options?: UseCreateFirstflowOptions): UseCreateFirstflowResult;
 
-type UseFeedbackMessageResult = {
-    rating: 'like' | 'dislike' | null;
-    selectedTags: string[];
-    comment: string;
+declare function useFirstflowSelector<T>(selector: (snapshot: FirstflowRuntimeSnapshot) => T): T;
+
+type UseFirstflowSurveyOptions = {
+    experienceId: string;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    mapSubmit?: (payload: SurveySubmitPayload) => SurveySubmitPayload;
+};
+type UseFirstflowSurveyResult = {
+    surveyId: string;
+    questions: SurveyQuestion[];
+    currentIndex: number;
+    currentQuestion: SurveyQuestion | null;
+    answers: Record<string, SurveyAnswerValue>;
+    setAnswer: (questionId: string, value: SurveyAnswerValue) => void;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    canSubmit: boolean;
+    isEnabled: boolean;
     submitting: boolean;
     submitted: boolean;
     error: string | null;
-    setRating: (r: 'like' | 'dislike') => void;
-    toggleTag: (tag: string) => void;
-    setComment: (c: string) => void;
     submit: () => Promise<void>;
     clearError: () => void;
-    isEnabled: boolean;
-    config: NormalizedFeedbackConfig | null;
-    sideConfig: NormalizedFeedbackFormConfig | null;
 };
-type UseFeedbackMessageOptions = {
-    conversationId: string;
-    messageId: string;
-    messagePreview: string;
-    metadata?: Record<string, unknown>;
-};
-/**
- * **Module mode** — `useFeedback()`
- * Returns `firstflow.feedback`: programmatic `submit(payload)`, `getConfig()`, `isEnabled()` (e.g. Thread slot, one-off submits).
- *
- * **Message mode** — `useFeedback({ conversationId, messageId, messagePreview, metadata? })`
- * Headless per-message state: rating, tags, comment, `submit()`, localStorage.
- */
-declare function useFeedback(): FeedbackModulePublic;
-declare function useFeedback(options: UseFeedbackMessageOptions): UseFeedbackMessageResult;
+declare function useFirstflowSurvey(): SurveyModulePublic;
+declare function useFirstflowSurvey(options: UseFirstflowSurveyOptions): UseFirstflowSurveyResult;
+
+declare function useExperienceEligibility(experienceId: string): boolean;
 
 /**
  * Runtime types for experience "Message" flow nodes (aligned with dashboard CardData.config).
  * @see blocksVersion — increment when block union or order semantics change.
  */
-type FlowMessageStyle = 'message'
-/** @deprecated Dashboard now saves `message`; kept for older flows */
- | 'inline' | 'card' | 'carousel' | 'quick_replies' | 'rich_card';
+type FlowMessageStyle = 'message' | 'inline' | 'card' | 'carousel' | 'quick_replies' | 'rich_card';
 /** Canonical style for analytics / UI (`inline` → `message`). */
 declare function normalizeFlowMessageStyle(style: FlowMessageStyle | undefined): FlowMessageStyle | undefined;
 type FlowMessageCtaType = 'none' | 'button' | 'link' | 'dismiss' | 'button_dismiss';
@@ -288,6 +129,18 @@ type FlowQuickReplyItem = {
 };
 declare function normalizeFlowQuickReplyItem(entry: unknown): FlowQuickReplyItem;
 declare function normalizeFlowQuickReplyList(raw: unknown): FlowQuickReplyItem[];
+/** Optional pills above the title (future dashboard or custom JSON). */
+type FlowRichCardTag = {
+    label: string;
+    bg?: string;
+    color?: string;
+};
+/** Optional meta row under the description (e.g. date, duration). */
+type FlowRichCardMetaItem = {
+    label: string;
+    icon?: string;
+};
+type FlowRichCardMediaType = 'image' | 'emoji';
 type FlowCarouselCard = {
     id: string;
     title: string;
@@ -319,6 +172,16 @@ type FlowMessageNodeConfig = {
     /** Legacy flows may use `string[]`; normalize with `normalizeFlowQuickReplyList`. */
     quickReplies?: Array<string | FlowQuickReplyItem>;
     carouselCards?: FlowCarouselCard[];
+    /** Rich card: hero image URL (http/https). */
+    richCardImageUrl?: string;
+    /** Rich card: headline (defaults to first line of `messageContent`). */
+    richCardTitle?: string;
+    /** Rich card: hero mode — `image` uses URL when valid; `emoji` uses placeholder with `richCardEmoji`. */
+    richCardMediaType?: FlowRichCardMediaType;
+    /** Rich card: shown in hero when there is no image or media type is `emoji`. */
+    richCardEmoji?: string;
+    richCardTags?: FlowRichCardTag[];
+    richCardMeta?: FlowRichCardMetaItem[];
 };
 type ExperienceMessageBlock = {
     type: 'text';
@@ -388,6 +251,14 @@ type ExperienceMessageUi = {
  */
 declare function buildExperienceMessageBlocks(config: FlowMessageNodeConfig): ExperienceMessageBlock[];
 declare function buildExperienceMessageUi(blocks: ExperienceMessageBlock[], messageStyle: FlowMessageStyle | undefined): ExperienceMessageUi;
+/**
+ * Returns a safe http(s) URL for rich-card images, or `undefined` if invalid.
+ */
+declare function tryParseHttpImageUrl(raw: string | undefined): string | undefined;
+/**
+ * Coerces dashboard / runtime JSON into `FlowMessageNodeConfig` for slot rendering and hooks.
+ */
+declare function parseFlowMessageNodeConfig(raw: Record<string, unknown>): FlowMessageNodeConfig;
 /**
  * Builds the `carousel_cta` action payload from node config (prompt vs link per button).
  * Host apps should open `linkUrl` or send `promptText` / `label` as the user message — same rules as the dashboard preview.
@@ -396,6 +267,121 @@ declare function buildExperienceCarouselCtaAction(config: FlowMessageNodeConfig,
     kind: 'carousel_cta';
 }>;
 
+/**
+ * Runtime types for experience "Announcement" flow nodes (aligned with dashboard CardData.config).
+ * @see blocksVersion — increment when content/ui semantics change.
+ */
+type FlowAnnouncementStyle = 'chat_bubble' | 'card' | 'banner' | 'tooltip' | 'spotlight';
+type FlowAnnouncementTheme = 'info' | 'success' | 'warning' | 'promo' | 'neutral';
+type FlowAnnouncementPosition = 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+type FlowAnnouncementNodeConfig = {
+    announcementStyle?: FlowAnnouncementStyle;
+    announcementTheme?: FlowAnnouncementTheme;
+    announcementTitle?: string;
+    announcementBody?: string;
+    announcementEmoji?: string;
+    /** Hero image (http/https); when absent, emoji placeholder is used. */
+    announcementImageUrl?: string;
+    /** Optional pill label (e.g. “What’s new”); defaults from theme when empty. */
+    announcementBadge?: string;
+    /** Small icon/emoji before badge text (e.g. ★). */
+    announcementBadgeIcon?: string;
+    ctaText?: string;
+    ctaUrl?: string;
+    announcementDismissible?: boolean;
+    announcementAutoHide?: boolean;
+    announcementAutoHideDelay?: number;
+    announcementPosition?: FlowAnnouncementPosition;
+};
+type ExperienceAnnouncementAction = {
+    kind: 'cta_click';
+    label: string;
+    url?: string;
+} | {
+    kind: 'dismiss';
+} | {
+    kind: 'auto_hidden';
+};
+/** Maps action kind → analytics `action` property (single source of truth). */
+declare const EXPERIENCE_ANNOUNCEMENT_ANALYTICS_ACTION: Record<ExperienceAnnouncementAction['kind'], string>;
+declare const EXPERIENCE_ANNOUNCEMENT_BLOCKS_VERSION: 1;
+/** Trimmed display fields; omit keys when empty. */
+type ExperienceAnnouncementContent = {
+    title?: string;
+    body?: string;
+    emoji?: string;
+    ctaLabel?: string;
+    ctaUrl?: string;
+};
+type ExperienceAnnouncementUi = {
+    hasTitle: boolean;
+    hasBody: boolean;
+    hasEmoji: boolean;
+    hasCta: boolean;
+    isDismissible: boolean;
+    autoHide: boolean;
+    autoHideDelay: number;
+    position: FlowAnnouncementPosition | undefined;
+    style: FlowAnnouncementStyle | undefined;
+    theme: FlowAnnouncementTheme | undefined;
+};
+/**
+ * Maps raw dashboard/API config to a safe `FlowAnnouncementNodeConfig`.
+ */
+declare function normalizeFlowAnnouncementNodeConfig(raw: Record<string, unknown> | FlowAnnouncementNodeConfig | undefined | null): FlowAnnouncementNodeConfig;
+declare function buildExperienceAnnouncementContent(config: FlowAnnouncementNodeConfig): ExperienceAnnouncementContent;
+declare function buildExperienceAnnouncementUi(config: FlowAnnouncementNodeConfig, content: ExperienceAnnouncementContent): ExperienceAnnouncementUi;
+
+type SlotCandidateType = 'survey' | 'message' | 'announcement';
+type SlotCandidateSurvey = {
+    type: 'survey';
+    experienceId: string;
+    settings: ExperienceSettings | null;
+};
+type SlotTourMessageStep = {
+    nodeId: string;
+    config: Record<string, unknown>;
+};
+type SlotCandidateMessage = {
+    type: 'message';
+    experienceId: string;
+    nodeId: string;
+    config: Record<string, unknown>;
+    settings: ExperienceSettings | null;
+    /** Tour flows: walk these in order before the slot marks the experience consumed. */
+    tourSteps?: SlotTourMessageStep[];
+};
+type SlotCandidateAnnouncement = {
+    type: 'announcement';
+    experienceId: string;
+    nodeId: string;
+    config: Record<string, unknown>;
+    settings: ExperienceSettings | null;
+};
+type NormalizedSlotCandidate = SlotCandidateSurvey | SlotCandidateMessage | SlotCandidateAnnouncement;
+/** Matches survey/card theming (`light` / `dark` / system `auto`). */
+type ExperienceSlotAppearance = 'light' | 'dark' | 'auto';
+/** Props for `ExperienceSlot` (implementation typically under `src/components`). */
+type ExperienceSlotProps = {
+    mode?: 'single' | 'queue';
+    typeFilter?: SlotCandidateType[];
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    showInlineFeedback?: boolean;
+    onShow?: (experienceId: string, type: SlotCandidateType) => void;
+    onQueueEmpty?: () => void;
+    renderCandidate?: (candidate: NormalizedSlotCandidate, advance: () => void) => ReactNode;
+    className?: string;
+    /** Applied to `Survey` and message card experiences. */
+    appearance?: ExperienceSlotAppearance;
+    /** Fired for message card CTAs after internal analytics; use for chat prompts or host UX. */
+    onExperienceMessageAction?: (action: ExperienceMessageAction) => void;
+    /** Fired for announcement actions after internal analytics. */
+    onExperienceAnnouncementAction?: (action: ExperienceAnnouncementAction) => void;
+};
+
+declare function useFirstflowResolveExperience(experienceId: string): NormalizedSlotCandidate | null;
+
 type UseExperienceMessageNodeOptions = {
     config: FlowMessageNodeConfig;
     nodeId: string;
@@ -464,65 +450,6 @@ type UseExperienceMessageNodeResult = {
  */
 declare function useExperienceMessageNode(options: UseExperienceMessageNodeOptions): UseExperienceMessageNodeResult;
 
-/**
- * Runtime types for experience "Announcement" flow nodes (aligned with dashboard CardData.config).
- * @see blocksVersion — increment when content/ui semantics change.
- */
-type FlowAnnouncementStyle = 'chat_bubble' | 'card' | 'banner' | 'tooltip' | 'spotlight';
-type FlowAnnouncementTheme = 'info' | 'success' | 'warning' | 'promo' | 'neutral';
-type FlowAnnouncementPosition = 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
-type FlowAnnouncementNodeConfig = {
-    announcementStyle?: FlowAnnouncementStyle;
-    announcementTheme?: FlowAnnouncementTheme;
-    announcementTitle?: string;
-    announcementBody?: string;
-    announcementEmoji?: string;
-    ctaText?: string;
-    ctaUrl?: string;
-    announcementDismissible?: boolean;
-    announcementAutoHide?: boolean;
-    announcementAutoHideDelay?: number;
-    announcementPosition?: FlowAnnouncementPosition;
-};
-type ExperienceAnnouncementAction = {
-    kind: 'cta_click';
-    label: string;
-    url?: string;
-} | {
-    kind: 'dismiss';
-} | {
-    kind: 'auto_hidden';
-};
-/** Maps action kind → analytics `action` property (single source of truth). */
-declare const EXPERIENCE_ANNOUNCEMENT_ANALYTICS_ACTION: Record<ExperienceAnnouncementAction['kind'], string>;
-declare const EXPERIENCE_ANNOUNCEMENT_BLOCKS_VERSION: 1;
-/** Trimmed display fields; omit keys when empty. */
-type ExperienceAnnouncementContent = {
-    title?: string;
-    body?: string;
-    emoji?: string;
-    ctaLabel?: string;
-    ctaUrl?: string;
-};
-type ExperienceAnnouncementUi = {
-    hasTitle: boolean;
-    hasBody: boolean;
-    hasEmoji: boolean;
-    hasCta: boolean;
-    isDismissible: boolean;
-    autoHide: boolean;
-    autoHideDelay: number;
-    position: FlowAnnouncementPosition | undefined;
-    style: FlowAnnouncementStyle | undefined;
-    theme: FlowAnnouncementTheme | undefined;
-};
-/**
- * Maps raw dashboard/API config to a safe `FlowAnnouncementNodeConfig`.
- */
-declare function normalizeFlowAnnouncementNodeConfig(raw: Record<string, unknown> | FlowAnnouncementNodeConfig | undefined | null): FlowAnnouncementNodeConfig;
-declare function buildExperienceAnnouncementContent(config: FlowAnnouncementNodeConfig): ExperienceAnnouncementContent;
-declare function buildExperienceAnnouncementUi(config: FlowAnnouncementNodeConfig, content: ExperienceAnnouncementContent): ExperienceAnnouncementUi;
-
 type UseExperienceAnnouncementNodeOptions = {
     config: FlowAnnouncementNodeConfig | Record<string, unknown>;
     nodeId: string;
@@ -555,114 +482,148 @@ type UseExperienceAnnouncementNodeResult = {
  */
 declare function useExperienceAnnouncementNode(options: UseExperienceAnnouncementNodeOptions): UseExperienceAnnouncementNodeResult;
 
-type UseIssueFormResult = {
-    /** Current field values (ids from config). */
-    values: IssueFormValues;
-    setValue: (fieldId: string, value: string) => void;
-    setValues: (next: IssueFormValues) => void;
-    errors: Record<string, string>;
-    submitting: boolean;
-    submitted: boolean;
-    submitError: string | null;
-    /** Validate only; sets `errors`. Returns whether valid. */
-    validate: () => boolean;
-    /** Validate, then `reportIssue` with merged `open()` context (messageId, etc.). */
-    submit: () => Promise<void>;
-    /** Clear values to empty, errors, submit state. */
-    reset: () => void;
-    clearSubmitError: () => void;
-    isEnabled: boolean;
-    config: NormalizedConfig;
-    fields: NormalizedFieldConfig[];
-    promptText: string;
+type FreqRecord = {
+    count: number;
+    window_start: string;
 };
+type StorageScope = "local" | "session";
+interface StorageAdapter {
+    get(experienceId: string, scope: StorageScope): FreqRecord | null;
+    set(experienceId: string, rec: FreqRecord, scope: StorageScope): void;
+    clear(experienceId: string, scope: StorageScope): void;
+}
+declare function createStorageAdapter(): StorageAdapter;
+declare function clearFrequencyRecords(): void;
+declare function markExperienceShown(experienceId: string, frequency: ExperienceSettings["frequency"], storage: StorageAdapter, now?: number): void;
+
 /**
- * Headless issue form: same validation + submit as {@link FormEngine} / {@link InlineIssueForm}.
- * Build any UI; merge context from `open({ messageId, conversationId, … })` on submit.
+ * Fixed backend base URL for all Firstflow SDK HTTP calls (config, audience, overrides).
+ * Not configurable by consumers.
  */
-declare function useIssueForm(): UseIssueFormResult;
-
-type MessageFeedbackProps = {
-    conversationId: string;
-    messageId: string;
-    messagePreview: string;
-    className?: string;
-    /** Merged into each Jitsu `feedback_submitted` event as `metadata` (JSON-serializable). */
-    metadata?: Record<string, unknown>;
-    /**
-     * `inline` — thumbs beside the message; tag/comment form full width below when a rating is chosen.
-     * `default` — full card with preview + thumbs.
-     */
-    variant?: 'default' | 'inline';
-    /** Styling for the expanded form when `variant="inline"` (thumbs stay unchanged). */
-    inlineFormSurface?: 'light' | 'dark';
-};
-declare function MessageFeedback({ conversationId, messageId, messagePreview, className, metadata, variant, inlineFormSurface, }: MessageFeedbackProps): react_jsx_runtime.JSX.Element | null;
+declare const FIRSTFLOW_PUBLIC_API_BASE_URL = "http://localhost:3002";
 
 /**
  * DOM adapter only: renders the React tree into target. No business logic.
- * Renders FirstflowProvider + InlineIssueForm so firstflow.issue.open() works after mount.
+ * Renders FirstflowProvider with declarative bootstrap options.
  */
-declare function mount(firstflow: FirstflowInstance, target: HTMLElement): () => void;
+declare function mount(options: {
+    agentId: string;
+    apiKey?: string;
+    initialSdkPayload?: SdkAgentConfigPayload | null;
+}, target: HTMLElement): () => void;
 
-declare function useIssueReporter(): {
-    reporter: IssueReporterInstance;
-    open: (options?: OpenOptions) => void;
-    reportIssue: (data: IssueReportData) => Promise<void>;
-    submit: (data: IssueReportData) => Promise<void>;
-    config: NormalizedConfig;
-    isModalOpen: boolean;
-    closeModal: () => void;
+declare function ExperienceSlot({ mode, typeFilter, conversationId, metadata, onShow, onQueueEmpty, renderCandidate, className, appearance, onExperienceMessageAction, onExperienceAnnouncementAction, }: ExperienceSlotProps): react_jsx_runtime.JSX.Element | null;
+
+type SurveyAppearance = "light" | "dark" | "auto";
+type SurveyProps = {
+    experienceId: string;
+    layout?: "paginated" | "all";
+    appearance?: SurveyAppearance;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    onSubmit?: (answers: Record<string, SurveyAnswerValue>) => void;
+    onSubmitted?: () => void;
+    onError?: (error: string) => void;
+    /** `layout="all"` Skip only. Paginated Skip advances to the next question. */
+    onDismissed?: () => void;
+    className?: string;
+    classNames?: {
+        root?: string;
+        question?: string;
+        nav?: string;
+        error?: string;
+        success?: string;
+    };
 };
+declare function Survey({ experienceId, layout, appearance, conversationId, metadata, onSubmit, onSubmitted, onError, onDismissed, className, classNames: classNameMap, }: SurveyProps): react_jsx_runtime.JSX.Element;
 
-declare function InlineIssueForm(): react_jsx_runtime.JSX.Element | null;
+type ExperienceMessageCardProps = {
+    experienceId: string;
+    nodeId: string;
+    config: FlowMessageNodeConfig;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    /** Called after exit animation so the slot can advance. */
+    onComplete: () => void;
+    appearance?: SurveyAppearance;
+    className?: string;
+    /** Host hook for prompts / side effects (analytics still run inside the message hook). */
+    onMessageAction?: (action: ExperienceMessageAction) => void;
+};
+declare function ExperienceMessageCard({ experienceId, nodeId, config, conversationId, metadata, onComplete, appearance, className, onMessageAction, }: ExperienceMessageCardProps): react_jsx_runtime.JSX.Element;
 
-declare function IssueModal(): React.ReactPortal | null;
+type ExperienceMessageRichCardProps = {
+    experienceId: string;
+    nodeId: string;
+    config: FlowMessageNodeConfig;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    onComplete: () => void;
+    appearance?: SurveyAppearance;
+    className?: string;
+    onMessageAction?: (action: ExperienceMessageAction) => void;
+};
+declare function ExperienceMessageRichCard({ experienceId, nodeId, config, conversationId, metadata, onComplete, appearance, className, onMessageAction, }: ExperienceMessageRichCardProps): react_jsx_runtime.JSX.Element;
 
-type FormEngineProps = {
-    onSubmitSuccess?: () => void;
-    onCancel?: () => void;
-    submitLabel?: string;
-    cancelLabel?: string;
+type ExperienceMessageCarouselProps = {
+    experienceId: string;
+    nodeId: string;
+    config: FlowMessageNodeConfig;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    onComplete: () => void;
+    appearance?: SurveyAppearance;
+    className?: string;
+    onMessageAction?: (action: ExperienceMessageAction) => void;
 };
-declare function FormEngine({ onSubmitSuccess, onCancel, submitLabel, cancelLabel, }: FormEngineProps): react_jsx_runtime.JSX.Element | null;
+declare function ExperienceMessageCarousel({ experienceId, nodeId, config, conversationId, metadata, onComplete, appearance, className, onMessageAction, }: ExperienceMessageCarouselProps): react_jsx_runtime.JSX.Element | null;
 
-/**
- * Issue module types. Use the Issue namespace so the root package stays platform-first.
- */
+type ExperienceMessageInlineProps = {
+    experienceId: string;
+    nodeId: string;
+    config: FlowMessageNodeConfig;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    onComplete: () => void;
+    appearance?: SurveyAppearance;
+    className?: string;
+    onMessageAction?: (action: ExperienceMessageAction) => void;
+};
+declare function ExperienceMessageInline({ experienceId, nodeId, config, conversationId, metadata, onComplete, appearance, className, onMessageAction, }: ExperienceMessageInlineProps): react_jsx_runtime.JSX.Element;
 
-type issue_IssueContextMetadata = IssueContextMetadata;
-type issue_NormalizedConfig = NormalizedConfig;
-type issue_NormalizedFieldConfig = NormalizedFieldConfig;
-type issue_OpenOptions = OpenOptions;
-type issue_RawIssueFieldConfig = RawIssueFieldConfig;
-type issue_RawIssuesConfig = RawIssuesConfig;
-type issue_ValidationResult = ValidationResult;
-declare namespace issue {
-  export type { IssueFormValues as FormValues, issue_IssueContextMetadata as IssueContextMetadata, issue_NormalizedConfig as NormalizedConfig, issue_NormalizedFieldConfig as NormalizedFieldConfig, issue_OpenOptions as OpenOptions, IssuePayload as Payload, issue_RawIssueFieldConfig as RawIssueFieldConfig, issue_RawIssuesConfig as RawIssuesConfig, issue_ValidationResult as ValidationResult };
-}
+type ExperienceAnnouncementCardProps = {
+    experienceId: string;
+    nodeId: string;
+    config: FlowAnnouncementNodeConfig | Record<string, unknown>;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    onComplete: () => void;
+    appearance?: SurveyAppearance;
+    className?: string;
+    onAnnouncementAction?: (action: ExperienceAnnouncementAction) => void;
+};
+declare function ExperienceAnnouncementCard({ experienceId, nodeId, config: configInput, conversationId, metadata, onComplete, appearance, className, onAnnouncementAction, }: ExperienceAnnouncementCardProps): react_jsx_runtime.JSX.Element;
 
-type IssueReporterContextValue = {
-    reporter: IssueReporterInstance;
-    isModalOpen: boolean;
-    openModal: (options?: OpenOptions) => void;
-    closeModal: () => void;
-    openOptionsRef: React.MutableRefObject<OpenOptions | undefined>;
-};
-type IssueReporterProviderProps = {
-    reporter: IssueReporterInstance;
-    children: ReactNode;
+type WidgetSlotProps = Omit<ExperienceSlotProps, "conversationId" | "metadata">;
+type FirstflowWidgetProps = {
+    children: React.ReactNode;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    experiencePlacement?: "stack" | "overlay";
+    className?: string;
+    classNames?: {
+        root?: string;
+        chat?: string;
+        overlayLayer?: string;
+        overlayCard?: string;
+    };
+    experienceSlotProps?: WidgetSlotProps;
 };
-/**
- * Provides React bindings and modal state only. Config lifecycle and submission stay in the reporter instance.
- */
-declare function IssueReporterProvider({ reporter, children, }: IssueReporterProviderProps): react_jsx_runtime.JSX.Element;
-declare function useIssueReporterContext(): IssueReporterContextValue;
+declare function FirstflowWidget({ children, conversationId, metadata, experiencePlacement, className, classNames: classNameMap, experienceSlotProps, }: FirstflowWidgetProps): react_jsx_runtime.JSX.Element;
 
-/**
- * Factory: returns an instance. No global state; callback ref from Provider for open().
- * Issue events are sent via the platform analytics layer only (no direct Jitsu/backend calls).
- */
-declare function createIssueReporter(options: CreateIssueReporterOptions): IssueReporterInstance;
+/** Public platform instance (issue + message-feedback modules omitted from typings until re-enabled on the main export). */
+type FirstflowInstance = Omit<FirstflowInstance$1, "issue" | "feedback">;
+declare function createFirstflow(options: CreateFirstflowOptions): FirstflowInstance;
+declare function useFirstflow(): FirstflowInstance;
 
-export { type AnalyticsModulePublic, CHAT_MESSAGE_SENT, type CreateFirstflowOptions, type CreateIssueReporterOptions, EXPERIENCE_ANNOUNCEMENT_ANALYTICS_ACTION, EXPERIENCE_ANNOUNCEMENT_BLOCKS_VERSION, EXPERIENCE_CLICKED, EXPERIENCE_MESSAGE_ANALYTICS_ACTION, EXPERIENCE_MESSAGE_BLOCKS_VERSION, EXPERIENCE_SHOWN, type ExperienceAnnouncementAction, type ExperienceAnnouncementContent, type ExperienceAnnouncementUi, type ExperienceMessageAction, type ExperienceMessageBlock, type ExperienceMessageUi, FEEDBACK_SUBMITTED, type FeedbackModulePublic, type FirstflowInstance, FirstflowProvider, type FlowAnnouncementNodeConfig, type FlowAnnouncementPosition, type FlowAnnouncementStyle, type FlowAnnouncementTheme, type FlowCarouselCard, type FlowCarouselCardButtonAction, type FlowMessageCtaType, type FlowMessageNodeConfig, type FlowMessageStyle, type FlowQuickReplyItem, FormEngine, type FormEngineProps, ISSUE_SUBMITTED, InlineIssueForm, issue as Issue, type IssueContextMetadata, type IssueFormValues, IssueModal, type IssueModulePublic, type IssuePayload, type IssueReporterInstance, IssueReporterProvider, MessageFeedback, type MessageFeedbackProps, type MessageFeedbackSubmitPayload, type NormalizedConfig, type NormalizedFeedbackConfig, type NormalizedFieldConfig, type OpenOptions, type RawFeedbackConfig, type RawIssueFieldConfig, type RawIssuesConfig, SURVEY_COMPLETED, type SdkAgentConfigExperience, type SdkAgentConfigPayload, type UseCreateFirstflowOptions, type UseCreateFirstflowResult, type UseExperienceAnnouncementNodeHandlers, type UseExperienceAnnouncementNodeOptions, type UseExperienceAnnouncementNodeResult, type UseExperienceMessageNodeHandlers, type UseExperienceMessageNodeOptions, type UseExperienceMessageNodeResult, type UseFeedbackMessageOptions, type UseFeedbackMessageResult, type UseIssueFormResult, type ValidationResult, buildExperienceAnnouncementContent, buildExperienceAnnouncementUi, buildExperienceCarouselCtaAction, buildExperienceMessageBlocks, buildExperienceMessageUi, createFirstflow, createIssueReporter, fetchSdkAgentConfig, mount, normalizeFlowAnnouncementNodeConfig, normalizeFlowMessageStyle, normalizeFlowQuickReplyItem, normalizeFlowQuickReplyList, useCreateFirstflow, useExperienceAnnouncementNode, useExperienceMessageNode, useFeedback, useFirstflow, useFirstflowConfig, useIssueForm, useIssueReporter, useIssueReporterContext };
+export { AudienceMembershipMap, type AudienceOverrides, CreateFirstflowOptions, EXPERIENCE_ANNOUNCEMENT_ANALYTICS_ACTION, EXPERIENCE_ANNOUNCEMENT_BLOCKS_VERSION, EXPERIENCE_MESSAGE_ANALYTICS_ACTION, EXPERIENCE_MESSAGE_BLOCKS_VERSION, type ExperienceAnnouncementAction, ExperienceAnnouncementCard, type ExperienceAnnouncementCardProps, type ExperienceAnnouncementContent, type ExperienceAnnouncementUi, type ExperienceMessageAction, type ExperienceMessageBlock, ExperienceMessageCard, type ExperienceMessageCardProps, ExperienceMessageCarousel, type ExperienceMessageCarouselProps, ExperienceMessageInline, type ExperienceMessageInlineProps, ExperienceMessageRichCard, type ExperienceMessageRichCardProps, type ExperienceMessageUi, ExperienceSlot, type ExperienceSlotAppearance, type ExperienceSlotProps, FIRSTFLOW_PUBLIC_API_BASE_URL, type FirstflowInstance, FirstflowProvider, FirstflowWidget, type FirstflowWidgetProps, type FlowAnnouncementNodeConfig, type FlowAnnouncementPosition, type FlowAnnouncementStyle, type FlowAnnouncementTheme, type FlowCarouselCard, type FlowCarouselCardButtonAction, type FlowMessageCtaType, type FlowMessageNodeConfig, type FlowMessageStyle, type FlowQuickReplyItem, type FlowRichCardMediaType, type FlowRichCardMetaItem, type FlowRichCardTag, type NormalizedSlotCandidate, type SdkAgentConfigExperience, type SdkAgentConfigPayload, type SdkAgentWidgetUi, type SdkRuntimeFlow, type SdkRuntimeFlowEdge, type SdkRuntimeFlowNode, type SlotCandidateAnnouncement, type SlotCandidateMessage, type SlotCandidateSurvey, type SlotCandidateType, type SlotTourMessageStep, Survey, SurveyAnswerValue, type SurveyAppearance, SurveyModulePublic, type SurveyProps, SurveyQuestion, SurveySubmitPayload, type UseExperienceAnnouncementNodeHandlers, type UseExperienceAnnouncementNodeOptions, type UseExperienceAnnouncementNodeResult, type UseExperienceMessageNodeHandlers, type UseExperienceMessageNodeOptions, type UseExperienceMessageNodeResult, type UseFirstflowSurveyOptions, type UseFirstflowSurveyResult, UserContext, buildExperienceAnnouncementContent, buildExperienceAnnouncementUi, buildExperienceCarouselCtaAction, buildExperienceMessageBlocks, buildExperienceMessageUi, clearFrequencyRecords, createFirstflow, createStorageAdapter, fetchSdkAgentConfig, markExperienceShown, mount, normalizeFlowAnnouncementNodeConfig, normalizeFlowMessageStyle, normalizeFlowQuickReplyItem, normalizeFlowQuickReplyList, parseFlowMessageNodeConfig, tryParseHttpImageUrl, useExperienceAnnouncementNode, useExperienceEligibility, useExperienceMessageNode, useFirstflow, useFirstflowResolveExperience, useFirstflowSelector, useFirstflowSurvey };