@firstflow/react 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,668 @@
+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).
+ */
+interface NormalizedFieldConfig {
+    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;
+
+/** 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 SdkAgentConfigPayload = {
+    issues_config?: RawIssuesConfig;
+    feedback_config?: RawFeedbackConfig;
+    /** Active experiences including saved flow (nodes/edges from canvas). */
+    experiences?: SdkAgentConfigExperience[];
+};
+declare function fetchSdkAgentConfig(apiUrl: string, agentId: string): Promise<SdkAgentConfigPayload>;
+
+type FirstflowProviderProps = {
+    firstflow: FirstflowInstance;
+    children: ReactNode;
+    /** Optional payload from `fetchSdkAgentConfig` / `useCreateFirstflow` (issues, feedback, experiences). */
+    config?: SdkAgentConfigPayload | null;
+};
+/**
+ * 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;
+
+type UseCreateFirstflowOptions = {
+    fetchConfig?: boolean;
+};
+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;
+};
+declare function useCreateFirstflow(agentId: string, apiUrl: string, options?: UseCreateFirstflowOptions): UseCreateFirstflowResult;
+
+type UseFeedbackMessageResult = {
+    rating: 'like' | 'dislike' | null;
+    selectedTags: string[];
+    comment: string;
+    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;
+
+/**
+ * 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';
+/** Canonical style for analytics / UI (`inline` → `message`). */
+declare function normalizeFlowMessageStyle(style: FlowMessageStyle | undefined): FlowMessageStyle | undefined;
+type FlowMessageCtaType = 'none' | 'button' | 'link' | 'dismiss' | 'button_dismiss';
+type FlowCarouselCardButtonAction = 'prompt' | 'link';
+type FlowQuickReplyItem = {
+    label: string;
+    prompt?: string;
+};
+declare function normalizeFlowQuickReplyItem(entry: unknown): FlowQuickReplyItem;
+declare function normalizeFlowQuickReplyList(raw: unknown): FlowQuickReplyItem[];
+type FlowCarouselCard = {
+    id: string;
+    title: string;
+    description: string;
+    buttonText?: string;
+    buttonAction?: FlowCarouselCardButtonAction;
+    buttonUrl?: string;
+    buttonPrompt?: string;
+    showCardCta?: boolean;
+    secondaryButtonText?: string;
+    secondaryButtonAction?: FlowCarouselCardButtonAction;
+    secondaryButtonUrl?: string;
+    secondaryButtonPrompt?: string;
+    emoji?: string;
+    mediaType?: 'emoji' | 'image' | 'video';
+    imageUrl?: string;
+    videoUrl?: string;
+};
+type FlowMessageNodeConfig = {
+    messageContent?: string;
+    messageStyle?: FlowMessageStyle;
+    ctaType?: FlowMessageCtaType;
+    ctaText?: string;
+    /** Link CTA destination */
+    ctaUrl?: string;
+    /** Button / button_dismiss: user message sent when primary CTA is activated (falls back to label in host apps if empty). */
+    ctaPrompt?: string;
+    dismissText?: string;
+    /** Legacy flows may use `string[]`; normalize with `normalizeFlowQuickReplyList`. */
+    quickReplies?: Array<string | FlowQuickReplyItem>;
+    carouselCards?: FlowCarouselCard[];
+};
+type ExperienceMessageBlock = {
+    type: 'text';
+    body: string;
+} | {
+    type: 'carousel';
+    cards: FlowCarouselCard[];
+} | {
+    type: 'quick_replies';
+    options: FlowQuickReplyItem[];
+} | {
+    type: 'cta_primary';
+    label: string;
+    ctaType: FlowMessageCtaType;
+    url?: string;
+    /** Present for button / button_dismiss when dashboard set ctaPrompt */
+    promptText?: string;
+} | {
+    type: 'cta_dismiss';
+    label: string;
+};
+type ExperienceMessageAction = {
+    kind: 'cta_primary';
+    ctaType: FlowMessageCtaType;
+    label: string;
+    url?: string;
+    promptText?: string;
+} | {
+    kind: 'cta_dismiss';
+    label: string;
+} | {
+    kind: 'quick_reply';
+    label: string;
+    index: number;
+    promptText?: string;
+} | {
+    kind: 'carousel_cta';
+    cardId: string;
+    actionId?: string;
+    /** Resolved from card config; omitted if card not found */
+    buttonAction?: FlowCarouselCardButtonAction;
+    /** Primary or secondary button label */
+    label?: string;
+    linkUrl?: string;
+    promptText?: string;
+};
+/** Maps action kind → analytics `action` property (single source of truth). */
+declare const EXPERIENCE_MESSAGE_ANALYTICS_ACTION: Record<ExperienceMessageAction['kind'], string>;
+/**
+ * v4: Quick replies are `{ label, prompt? }[]` (normalized); `quick_replies` block options carry prompts; `quick_reply` actions include optional `promptText`.
+ * v3: `cta_primary` blocks carry optional `promptText` (dashboard `ctaPrompt`); `FlowMessageStyle` adds `message` (alias of legacy `inline`).
+ * v2: `FlowCarouselCard` supports optional per-card CTAs (`showCardCta`, `secondaryButtonText`, optional `buttonText`).
+ * v1: carousel cards required `buttonText`; consumers should ignore unknown keys on card objects.
+ */
+declare const EXPERIENCE_MESSAGE_BLOCKS_VERSION: 4;
+type ExperienceMessageUi = {
+    hasText: boolean;
+    hasPrimaryCta: boolean;
+    hasDismissCta: boolean;
+    hasQuickReplies: boolean;
+    hasCarousel: boolean;
+    messageStyle: FlowMessageStyle | undefined;
+};
+/**
+ * Canonical block order: text → carousel → quick_replies → cta_primary → cta_dismiss.
+ * Carousel card objects follow `FlowCarouselCard` (v2 fields optional for per-card CTAs).
+ */
+declare function buildExperienceMessageBlocks(config: FlowMessageNodeConfig): ExperienceMessageBlock[];
+declare function buildExperienceMessageUi(blocks: ExperienceMessageBlock[], messageStyle: FlowMessageStyle | undefined): ExperienceMessageUi;
+/**
+ * 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.
+ */
+declare function buildExperienceCarouselCtaAction(config: FlowMessageNodeConfig, cardId: string, actionId?: string): Extract<ExperienceMessageAction, {
+    kind: 'carousel_cta';
+}>;
+
+type UseExperienceMessageNodeOptions = {
+    config: FlowMessageNodeConfig;
+    nodeId: string;
+    experienceId: string;
+    conversationId?: string;
+    /** Merged into analytics props (non-reserved keys only if colliding — core ids always win). */
+    metadata?: Record<string, unknown>;
+    /**
+     * When true (default), fires first impression on mount via internal `reportShown()`.
+     * Set false for virtualized lists; call `reportShown()` when the row is visible (e.g. IntersectionObserver).
+     */
+    trackShownOnMount?: boolean;
+    /**
+     * Overrides the dedupe key. Include a per-flow UUID (e.g. `flowInstanceId`) if the same node may
+     * legitimately be shown twice in one session — otherwise dedupe drops the second impression.
+     */
+    impressionKey?: string;
+    /**
+     * When true (default), only one `EXPERIENCE_SHOWN` per impression key per page session.
+     * Set false to count every mount / every `reportShown()` call.
+     */
+    dedupeShown?: boolean;
+    onAction?: (e: ExperienceMessageAction) => void;
+    /**
+     * Transform props before `analytics.track`. Do not rename event names unless intentional.
+     * If this throws, base props are used and a warning is logged.
+     */
+    mapAnalytics?: (eventName: string, props: Record<string, unknown>) => Record<string, unknown>;
+};
+type UseExperienceMessageNodeHandlers = {
+    onPrimaryCta: () => void;
+    onDismissCta: () => void;
+    onQuickReply: (label: string, index: number) => void;
+    /**
+     * `actionId` is `primary` | `secondary`; defaults to `primary`.
+     * Fires `carousel_cta` with `buttonAction`, `label`, `linkUrl`, and `promptText` filled from `config.carouselCards` when the card exists.
+     */
+    onCarouselCta: (cardId: string, actionId?: string) => void;
+};
+type UseExperienceMessageNodeResult = {
+    config: FlowMessageNodeConfig;
+    blocks: ExperienceMessageBlock[];
+    blocksVersion: typeof EXPERIENCE_MESSAGE_BLOCKS_VERSION;
+    ui: ExperienceMessageUi;
+    handlers: UseExperienceMessageNodeHandlers;
+    /**
+     * Record `EXPERIENCE_SHOWN`. With `dedupeShown`, same `impressionKey` as an earlier successful
+     * track is a no-op. When `trackShownOnMount` is true, the mount effect counts as the first call.
+     */
+    reportShown: () => void;
+};
+/**
+ * Headless runtime for experience **Message** flow nodes: canonical `blocks` + `ui`, structured
+ * `onAction`, and `EXPERIENCE_SHOWN` / `EXPERIENCE_CLICKED` analytics (with optional dedupe and
+ * `mapAnalytics`). Requires `FirstflowProvider`.
+ *
+ * **Dedupe footgun:** Default impression key is stable per node + conversation. Re-visiting the same
+ * node in a new flow run without changing the key will not fire a second shown. Pass a unique
+ * `impressionKey` (e.g. including `flowInstanceId`) or set `dedupeShown: false`.
+ *
+ * **Block order:** text → carousel → quick_replies → cta_primary → cta_dismiss. v4 normalizes quick replies to `{ label, prompt? }` and adds `promptText` on `quick_reply` actions. v3 adds `promptText` on primary CTA blocks. v2 added per-card carousel CTA fields.
+ * **`onCarouselCta`:** emits `carousel_cta` with `buttonAction` / `label` / `linkUrl` / `promptText` resolved from `config.carouselCards` (dashboard prompt vs link per button).
+ *
+ * **Errors:** `onAction` and `mapAnalytics` are wrapped in try/catch; analytics still runs after
+ * `onAction` throws; if `mapAnalytics` throws, base props are tracked.
+ */
+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;
+    experienceId: string;
+    conversationId?: string;
+    metadata?: Record<string, unknown>;
+    trackShownOnMount?: boolean;
+    impressionKey?: string;
+    dedupeShown?: boolean;
+    onAction?: (e: ExperienceAnnouncementAction) => void;
+    mapAnalytics?: (eventName: string, props: Record<string, unknown>) => Record<string, unknown>;
+};
+type UseExperienceAnnouncementNodeHandlers = {
+    dismiss: () => void;
+    ctaClick: () => void;
+    cancelAutoHide: () => void;
+    reportShown: () => void;
+};
+type UseExperienceAnnouncementNodeResult = {
+    config: FlowAnnouncementNodeConfig;
+    content: ExperienceAnnouncementContent;
+    ui: ExperienceAnnouncementUi;
+    blocksVersion: typeof EXPERIENCE_ANNOUNCEMENT_BLOCKS_VERSION;
+    handlers: UseExperienceAnnouncementNodeHandlers;
+};
+/**
+ * Headless runtime for experience **Announcement** flow nodes: `content` + `ui`, structured
+ * `onAction` (cta_click, dismiss, auto_hidden), auto-hide timer, and EXPERIENCE_SHOWN /
+ * EXPERIENCE_CLICKED analytics. Requires `FirstflowProvider`.
+ */
+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;
+};
+/**
+ * Headless issue form: same validation + submit as {@link FormEngine} / {@link InlineIssueForm}.
+ * Build any UI; merge context from `open({ messageId, conversationId, … })` on submit.
+ */
+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;
+
+/**
+ * DOM adapter only: renders the React tree into target. No business logic.
+ * Renders FirstflowProvider + InlineIssueForm so firstflow.issue.open() works after mount.
+ */
+declare function mount(firstflow: FirstflowInstance, 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 InlineIssueForm(): react_jsx_runtime.JSX.Element | null;
+
+declare function IssueModal(): React.ReactPortal | null;
+
+type FormEngineProps = {
+    onSubmitSuccess?: () => void;
+    onCancel?: () => void;
+    submitLabel?: string;
+    cancelLabel?: string;
+};
+declare function FormEngine({ onSubmitSuccess, onCancel, submitLabel, cancelLabel, }: FormEngineProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Issue module types. Use the Issue namespace so the root package stays platform-first.
+ */
+
+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 IssueReporterContextValue = {
+    reporter: IssueReporterInstance;
+    isModalOpen: boolean;
+    openModal: (options?: OpenOptions) => void;
+    closeModal: () => void;
+    openOptionsRef: React.MutableRefObject<OpenOptions | undefined>;
+};
+type IssueReporterProviderProps = {
+    reporter: IssueReporterInstance;
+    children: ReactNode;
+};
+/**
+ * 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;
+
+/**
+ * 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;
+
+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 };