gotcha-feedback 1.1.4 → 1.1.6

package/dist/index.d.mts

@@ -34,6 +34,25 @@ interface GotchaStyles {
     backdrop?: React.CSSProperties;
     spinner?: React.CSSProperties;
 }
+interface SubmissionContext {
+    url?: string;
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    language?: string;
+    timezone?: string;
+    screenResolution?: {
+        width: number;
+        height: number;
+    };
+    recentErrors?: Array<{
+        message: string;
+        source?: string;
+        timestamp: number;
+    }>;
+}
 interface SubmitResponsePayload {
     elementId: string;
     mode: ResponseMode;
@@ -44,15 +63,13 @@ interface SubmitResponsePayload {
     pollOptions?: string[];
     pollSelected?: string[];
     isBug?: boolean;
+    screenshot?: string;
     user?: GotchaUser;
-    context?: {
-        url?: string;
-        userAgent?: string;
-    };
+    context?: SubmissionContext;
 }
 interface GotchaResponse {
     id: string;
-    status: 'created' | 'duplicate' | 'updated';
+    status: 'created' | 'duplicate' | 'updated' | 'queued';
     createdAt: string;
     results?: PollResults;
 }
@@ -89,6 +106,8 @@ interface ScoreData {
     npsScore: number | null;
 }
 
+declare function getQueueLength(): number;
+
 interface GotchaThemeColors {
     primary: string;
     primaryHover: string;
@@ -277,8 +296,32 @@ interface GotchaProps {
     enableBugFlag?: boolean;
     /** Custom label for the bug flag toggle (default: "Report an issue") */
     bugFlagLabel?: string;
+    /** Enable screenshot capture when bug flag is toggled (requires html2canvas peer dep, falls back to native API) */
+    enableScreenshot?: boolean;
     /** When true and user has already responded, show submitted state and allow review/edit instead of new submission */
     onePerUser?: boolean;
+    /** When onePerUser is true, allow a new submission after this many days. Has no effect without onePerUser. */
+    cooldownDays?: number;
+    /** After submission, hide the widget for this many days (client-side, localStorage).
+     *  Independent of cooldownDays — the widget stays hidden for the full duration even if cooldown expires sooner. */
+    hideAfterSubmitDays?: number;
+    /** Delay showing widget by N seconds after page load */
+    showAfterSeconds?: number;
+    /** Show widget after user scrolls past this percentage (0-100) */
+    showAfterScrollPercent?: number;
+    /** Show widget after user has visited N times (uses localStorage) */
+    showAfterVisits?: number;
+    /** Show a follow-up question after low rating or negative vote */
+    followUp?: {
+        /** Rating threshold (inclusive) — e.g., 2 means ratings 1-2 trigger follow-up */
+        ratingThreshold?: number;
+        /** Also trigger on negative vote */
+        onNegativeVote?: boolean;
+        /** The prompt text shown */
+        promptText: string;
+        /** Placeholder for the follow-up textarea */
+        placeholder?: string;
+    };
     /** Enable entrance animations on the button and modal (default: true) */
     animated?: boolean;
     /** Called after successful submission */
@@ -290,7 +333,7 @@ interface GotchaProps {
     /** Called on error */
     onError?: (error: GotchaError) => void;
 }
-declare function Gotcha({ elementId, user, mode, showText, showRating, voteLabels, options, allowMultiple, npsQuestion, npsFollowUp, npsFollowUpPlaceholder, npsLowLabel, npsHighLabel, enableBugFlag, bugFlagLabel, onePerUser, animated, position, size, theme, customStyles, visible, showOnHover, touchBehavior, promptText, placeholder, submitText, thankYouMessage, onSubmit, onOpen, onClose, onError, }: GotchaProps): react_jsx_runtime.JSX.Element | null;
+declare function Gotcha({ elementId, user, mode, showText, showRating, voteLabels, options, allowMultiple, npsQuestion, npsFollowUp, npsFollowUpPlaceholder, npsLowLabel, npsHighLabel, enableBugFlag, bugFlagLabel, enableScreenshot, onePerUser, cooldownDays, hideAfterSubmitDays, showAfterSeconds, showAfterScrollPercent, showAfterVisits, followUp, animated, position, size, theme, customStyles, visible, showOnHover, touchBehavior, promptText, placeholder, submitText, thankYouMessage, onSubmit, onOpen, onClose, onError, }: GotchaProps): react_jsx_runtime.JSX.Element | null;
 
 type ScoreVariant = 'stars' | 'number' | 'compact' | 'votes';
 interface GotchaScoreProps {
@@ -325,6 +368,8 @@ declare function useGotcha(): {
             ticketId: string;
             status: string;
         }>;
+        flushQueue(): Promise<void>;
+        getQueueLength: typeof getQueueLength;
         getBaseUrl(): string;
     };
     /** Whether Gotcha is globally disabled */
@@ -335,6 +380,22 @@ declare function useGotcha(): {
     debug: boolean;
     /** Submit feedback programmatically */
     submitFeedback: (payload: Omit<SubmitResponsePayload, "context">) => Promise<GotchaResponse>;
+    /** Open a specific Gotcha modal by elementId */
+    openModal: (elementId: string) => void;
+    /** Close the currently open modal */
+    closeModal: () => void;
+    /** The currently open modal's elementId, or null */
+    activeModalId: string | null;
+};
+
+/**
+ * Hook to programmatically open/close a specific Gotcha widget.
+ * The corresponding <Gotcha elementId="..."> must be mounted for the modal to render.
+ */
+declare function useGotchaTrigger(elementId: string): {
+    open: () => void;
+    close: () => void;
+    isOpen: boolean;
 };
 
-export { Gotcha, type GotchaError, type GotchaProps, GotchaProvider, type GotchaProviderProps, type GotchaResponse, GotchaScore, type GotchaScoreProps, type GotchaStyles, type GotchaThemeConfig, type GotchaUser, type Position, type ResponseMode, type ScoreData, type Size, type Theme, type TouchBehavior, type VoteType, createTheme, useGotcha };
+export { Gotcha, type GotchaError, type GotchaProps, GotchaProvider, type GotchaProviderProps, type GotchaResponse, GotchaScore, type GotchaScoreProps, type GotchaStyles, type GotchaThemeConfig, type GotchaUser, type Position, type ResponseMode, type ScoreData, type Size, type SubmissionContext, type Theme, type TouchBehavior, type VoteType, createTheme, useGotcha, useGotchaTrigger };

package/dist/index.d.ts

@@ -34,6 +34,25 @@ interface GotchaStyles {
     backdrop?: React.CSSProperties;
     spinner?: React.CSSProperties;
 }
+interface SubmissionContext {
+    url?: string;
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    language?: string;
+    timezone?: string;
+    screenResolution?: {
+        width: number;
+        height: number;
+    };
+    recentErrors?: Array<{
+        message: string;
+        source?: string;
+        timestamp: number;
+    }>;
+}
 interface SubmitResponsePayload {
     elementId: string;
     mode: ResponseMode;
@@ -44,15 +63,13 @@ interface SubmitResponsePayload {
     pollOptions?: string[];
     pollSelected?: string[];
     isBug?: boolean;
+    screenshot?: string;
     user?: GotchaUser;
-    context?: {
-        url?: string;
-        userAgent?: string;
-    };
+    context?: SubmissionContext;
 }
 interface GotchaResponse {
     id: string;
-    status: 'created' | 'duplicate' | 'updated';
+    status: 'created' | 'duplicate' | 'updated' | 'queued';
     createdAt: string;
     results?: PollResults;
 }
@@ -89,6 +106,8 @@ interface ScoreData {
     npsScore: number | null;
 }
 
+declare function getQueueLength(): number;
+
 interface GotchaThemeColors {
     primary: string;
     primaryHover: string;
@@ -277,8 +296,32 @@ interface GotchaProps {
     enableBugFlag?: boolean;
     /** Custom label for the bug flag toggle (default: "Report an issue") */
     bugFlagLabel?: string;
+    /** Enable screenshot capture when bug flag is toggled (requires html2canvas peer dep, falls back to native API) */
+    enableScreenshot?: boolean;
     /** When true and user has already responded, show submitted state and allow review/edit instead of new submission */
     onePerUser?: boolean;
+    /** When onePerUser is true, allow a new submission after this many days. Has no effect without onePerUser. */
+    cooldownDays?: number;
+    /** After submission, hide the widget for this many days (client-side, localStorage).
+     *  Independent of cooldownDays — the widget stays hidden for the full duration even if cooldown expires sooner. */
+    hideAfterSubmitDays?: number;
+    /** Delay showing widget by N seconds after page load */
+    showAfterSeconds?: number;
+    /** Show widget after user scrolls past this percentage (0-100) */
+    showAfterScrollPercent?: number;
+    /** Show widget after user has visited N times (uses localStorage) */
+    showAfterVisits?: number;
+    /** Show a follow-up question after low rating or negative vote */
+    followUp?: {
+        /** Rating threshold (inclusive) — e.g., 2 means ratings 1-2 trigger follow-up */
+        ratingThreshold?: number;
+        /** Also trigger on negative vote */
+        onNegativeVote?: boolean;
+        /** The prompt text shown */
+        promptText: string;
+        /** Placeholder for the follow-up textarea */
+        placeholder?: string;
+    };
     /** Enable entrance animations on the button and modal (default: true) */
     animated?: boolean;
     /** Called after successful submission */
@@ -290,7 +333,7 @@ interface GotchaProps {
     /** Called on error */
     onError?: (error: GotchaError) => void;
 }
-declare function Gotcha({ elementId, user, mode, showText, showRating, voteLabels, options, allowMultiple, npsQuestion, npsFollowUp, npsFollowUpPlaceholder, npsLowLabel, npsHighLabel, enableBugFlag, bugFlagLabel, onePerUser, animated, position, size, theme, customStyles, visible, showOnHover, touchBehavior, promptText, placeholder, submitText, thankYouMessage, onSubmit, onOpen, onClose, onError, }: GotchaProps): react_jsx_runtime.JSX.Element | null;
+declare function Gotcha({ elementId, user, mode, showText, showRating, voteLabels, options, allowMultiple, npsQuestion, npsFollowUp, npsFollowUpPlaceholder, npsLowLabel, npsHighLabel, enableBugFlag, bugFlagLabel, enableScreenshot, onePerUser, cooldownDays, hideAfterSubmitDays, showAfterSeconds, showAfterScrollPercent, showAfterVisits, followUp, animated, position, size, theme, customStyles, visible, showOnHover, touchBehavior, promptText, placeholder, submitText, thankYouMessage, onSubmit, onOpen, onClose, onError, }: GotchaProps): react_jsx_runtime.JSX.Element | null;
 
 type ScoreVariant = 'stars' | 'number' | 'compact' | 'votes';
 interface GotchaScoreProps {
@@ -325,6 +368,8 @@ declare function useGotcha(): {
             ticketId: string;
             status: string;
         }>;
+        flushQueue(): Promise<void>;
+        getQueueLength: typeof getQueueLength;
         getBaseUrl(): string;
     };
     /** Whether Gotcha is globally disabled */
@@ -335,6 +380,22 @@ declare function useGotcha(): {
     debug: boolean;
     /** Submit feedback programmatically */
     submitFeedback: (payload: Omit<SubmitResponsePayload, "context">) => Promise<GotchaResponse>;
+    /** Open a specific Gotcha modal by elementId */
+    openModal: (elementId: string) => void;
+    /** Close the currently open modal */
+    closeModal: () => void;
+    /** The currently open modal's elementId, or null */
+    activeModalId: string | null;
+};
+
+/**
+ * Hook to programmatically open/close a specific Gotcha widget.
+ * The corresponding <Gotcha elementId="..."> must be mounted for the modal to render.
+ */
+declare function useGotchaTrigger(elementId: string): {
+    open: () => void;
+    close: () => void;
+    isOpen: boolean;
 };
 
-export { Gotcha, type GotchaError, type GotchaProps, GotchaProvider, type GotchaProviderProps, type GotchaResponse, GotchaScore, type GotchaScoreProps, type GotchaStyles, type GotchaThemeConfig, type GotchaUser, type Position, type ResponseMode, type ScoreData, type Size, type Theme, type TouchBehavior, type VoteType, createTheme, useGotcha };
+export { Gotcha, type GotchaError, type GotchaProps, GotchaProvider, type GotchaProviderProps, type GotchaResponse, GotchaScore, type GotchaScoreProps, type GotchaStyles, type GotchaThemeConfig, type GotchaUser, type Position, type ResponseMode, type ScoreData, type Size, type SubmissionContext, type Theme, type TouchBehavior, type VoteType, createTheme, useGotcha, useGotchaTrigger };