@getforty/widget 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,359 @@
+/**
+ * Widget Configuration Types
+ * These types are exported publicly for developers using the widget
+ */
+/**
+ * Primary configuration object passed to widget initialization
+ */
+interface WidgetConfig {
+    /** Workspace tracking ID (required) - format: gf_xxxxxxxxxxxx */
+    trackingId: string;
+    /** Display language (default: auto-detect from browser) */
+    locale?: "en" | "pt-BR" | string;
+    /** Custom translations to override built-in strings */
+    translations?: Partial<TranslationStrings>;
+    /** Visual customization options for forms */
+    theme?: WidgetTheme;
+    /** Rendering mode for forms */
+    mode?: "inline" | "modal";
+    /** Target element for inline mode (CSS selector or HTMLElement) */
+    container?: string | HTMLElement;
+    /** Show/hide GetForty branding */
+    showBranding?: boolean;
+    /** Automatically track page views */
+    autoTrackPageViews?: boolean;
+    /** Automatically display forms based on server-side conditions (default: true) */
+    autoDisplay?: boolean;
+    /** API base URL (default: https://getforty.club) */
+    apiBaseUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Observe parent window's dataLayer (Google Tag Manager) and automatically
+     * send events through GetForty tracking pipeline (opt-in)
+     *
+     * When enabled, watches for events pushed to window.dataLayer and forwards
+     * them to GetForty's backend, allowing you to leverage existing GTM integrations.
+     *
+     * Note: Only works in same-origin scenarios (cross-origin iframes not supported)
+     */
+    observeDataLayer?: boolean;
+    /**
+     * Prefix added to dataLayer event names when sent to GetForty
+     * (default: "gtm_")
+     *
+     * Example: dataLayer event "purchase" becomes "gtm_purchase" in GetForty
+     */
+    dataLayerEventPrefix?: string;
+    /**
+     * Filter which dataLayer events to send (optional)
+     * Can be a RegExp to test event names or a function that returns boolean
+     *
+     * Examples:
+     * - /^custom_/  (only events starting with "custom_")
+     * - (name) => name !== "gtm.js"  (exclude GTM internal events)
+     */
+    dataLayerEventFilter?: RegExp | ((eventName: string) => boolean);
+}
+/**
+ * Visual customization options for form UI
+ */
+interface WidgetTheme {
+    /** Primary color for buttons and accents (CSS color) */
+    primaryColor?: string;
+    /** Background color for widget container (CSS color) */
+    backgroundColor?: string;
+    /** Text color (CSS color) */
+    textColor?: string;
+    /** Font family (CSS font-family) */
+    fontFamily?: string;
+    /** Border radius for containers and inputs (CSS value) */
+    borderRadius?: string;
+}
+/**
+ * Options for tracking a custom event
+ */
+interface TrackEventOptions {
+    /** Custom properties to attach to the event */
+    properties?: Record<string, string | number | boolean | null>;
+    /** Override the auto-generated session ID */
+    sessionId?: string;
+    /** Override the identified user ID */
+    userId?: string;
+    /** Timestamp override (default: now) */
+    timestamp?: Date;
+}
+/**
+ * Options for identifying a user
+ */
+interface IdentifyOptions {
+    /** User traits/properties */
+    traits?: Record<string, string | number | boolean | null>;
+}
+/**
+ * Internal representation of a tracked event
+ */
+interface TrackedEvent {
+    /** Event name (e.g., 'page_view', 'purchase', 'signup') */
+    eventName: string;
+    /** Custom event properties */
+    properties?: Record<string, unknown>;
+    /** Session identifier (auto-generated or provided) */
+    sessionId: string;
+    /** User identifier (from identify() call) */
+    userId?: string;
+    /** Event timestamp */
+    timestamp: string;
+    /** Retry count for failed sends */
+    _retryCount?: number;
+}
+/**
+ * Localizable UI strings
+ */
+interface TranslationStrings {
+    submit: string;
+    submitting: string;
+    next: string;
+    previous: string;
+    skip: string;
+    required: string;
+    invalidEmail: string;
+    invalidNumber: string;
+    minLength: string;
+    maxLength: string;
+    loading: string;
+    success: string;
+    successMessage: string;
+    error: string;
+    networkError: string;
+    rateLimited: string;
+    tryAgain: string;
+    npsNotLikely: string;
+    npsVeryLikely: string;
+    closeModal: string;
+    formLabel: string;
+    questionOf: string;
+}
+/**
+ * Form configuration received from API
+ */
+interface FormConfig {
+    id: string;
+    title: string;
+    type: "NPS" | "CSAT" | "PMF" | "CUSTOM";
+    questions: Question[];
+    branding?: {
+        logoUrl?: string;
+        thankYouMessage?: string;
+        colors?: {
+            primary?: string;
+            background?: string;
+        };
+    };
+}
+/**
+ * Question definition within a form
+ */
+interface Question {
+    id: string;
+    type: "rating" | "nps" | "text" | "textarea" | "select" | "multiselect" | "scale";
+    label: string;
+    description?: string;
+    required: boolean;
+    options?: QuestionOption[];
+    validation?: {
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+    };
+}
+/**
+ * Option for select/multiselect questions
+ */
+interface QuestionOption {
+    value: string;
+    label: string;
+}
+/**
+ * Answer submitted for a question
+ */
+interface Answer {
+    questionId: string;
+    value: string | string[] | number;
+}
+/**
+ * Events emitted by widget for developer integration
+ */
+interface WidgetEventMap {
+    /** Widget started loading form configuration */
+    "load:start": {
+        formId: string;
+    };
+    /** Form configuration loaded successfully */
+    "load:success": {
+        form: FormConfig;
+    };
+    /** Form loading failed */
+    "load:error": {
+        error: string;
+        retryable: boolean;
+    };
+    /** Widget became visible (modal opened or inline rendered) */
+    open: {
+        mode: "inline" | "modal";
+    };
+    /** Widget hidden (modal closed) */
+    close: {
+        reason: "user" | "submitted" | "programmatic";
+    };
+    /** Form submission started */
+    "submit:start": {
+        answers: Answer[];
+    };
+    /** Form submission successful */
+    "submit:success": {
+        responseId: string;
+    };
+    /** Form submission failed */
+    "submit:error": {
+        error: string;
+        retryable: boolean;
+    };
+    /** Any error occurred */
+    error: {
+        type: "load" | "submit" | "network";
+        message: string;
+    };
+    /** Field received focus */
+    "field:focus": {
+        questionId: string;
+        questionLabel: string;
+    };
+    /** Field lost focus */
+    "field:blur": {
+        questionId: string;
+        questionLabel: string;
+    };
+    /** Field value changed */
+    "field:change": {
+        questionId: string;
+        questionLabel: string;
+    };
+    /** Field validation error */
+    "field:validation": {
+        questionId: string;
+        questionLabel: string;
+        error: string;
+    };
+}
+/**
+ * Public interface for the GetForty widget instance
+ */
+interface GetFortyWidgetInstance {
+    /**
+     * Track a custom event
+     * @param eventName - Name of the event (e.g., 'page_view', 'purchase')
+     * @param properties - Optional custom properties
+     */
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /**
+     * Identify the current user
+     * Sends user data to backend and links events/respondents
+     * @param userId - Unique user identifier
+     * @param traits - Optional user traits (email, name, plan, etc.)
+     */
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    /**
+     * Show a feedback form
+     * @param formId - The form ID to display
+     */
+    showForm(formId: string): void;
+    /**
+     * Hide the currently displayed form
+     */
+    hideForm(): void;
+    /**
+     * Subscribe to widget lifecycle events
+     * @param event - Event name
+     * @param callback - Event handler
+     */
+    on<K extends keyof WidgetEventMap>(event: K, callback: (data: WidgetEventMap[K]) => void): void;
+    /**
+     * Unsubscribe from widget lifecycle events
+     */
+    off<K extends keyof WidgetEventMap>(event: K, callback: (data: WidgetEventMap[K]) => void): void;
+    /**
+     * Flush any queued events immediately
+     */
+    flush(): Promise<void>;
+    /**
+     * Get the current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Destroy the widget and clean up resources
+     * Stops polling, clears timers, and removes DOM elements
+     */
+    destroy(): void;
+}
+
+/**
+ * Widget constants
+ */
+declare const VERSION = "0.1.0";
+
+/**
+ * @getforty/widget
+ * Embeddable feedback widget and event tracking SDK for GetForty
+ *
+ * Usage:
+ * ```typescript
+ * import { GetForty } from '@getforty/widget'
+ *
+ * const widget = await GetForty.init({
+ *   trackingId: 'gf_xxxxxxxxxxxx',
+ * })
+ *
+ * // Track events
+ * widget.track('page_view', { page: '/pricing' })
+ *
+ * // Identify users
+ * widget.identify('user_123', { email: 'user@example.com' })
+ *
+ * // Show forms programmatically
+ * widget.showForm('form-id')
+ *
+ * // Listen to events
+ * widget.on('submit:success', (data) => {
+ *   console.log('Feedback submitted!', data.responseId)
+ * })
+ * ```
+ */
+
+/**
+ * GetForty namespace
+ * Main entry point for the widget SDK
+ */
+declare const GetForty: {
+    /**
+     * Initialize the GetForty widget
+     * @param config - Widget configuration
+     * @returns Promise that resolves to a widget instance
+     * @throws Error if trackingId is missing or invalid
+     *
+     * @example
+     * ```typescript
+     * const widget = await GetForty.init({
+     *   trackingId: 'gf_xxxxxxxxxxxx',
+     *   debug: true, // Enable debug logging
+     * })
+     * ```
+     */
+    init(config: WidgetConfig): Promise<GetFortyWidgetInstance>;
+    /**
+     * Current SDK version
+     */
+    version: string;
+};
+
+export { type Answer, type FormConfig, GetForty, type GetFortyWidgetInstance, type IdentifyOptions, type Question, type TrackEventOptions, type TrackedEvent, type TranslationStrings, VERSION, type WidgetConfig, type WidgetEventMap, type WidgetTheme, GetForty as default };

package/dist/index.d.ts

@@ -0,0 +1,359 @@
+/**
+ * Widget Configuration Types
+ * These types are exported publicly for developers using the widget
+ */
+/**
+ * Primary configuration object passed to widget initialization
+ */
+interface WidgetConfig {
+    /** Workspace tracking ID (required) - format: gf_xxxxxxxxxxxx */
+    trackingId: string;
+    /** Display language (default: auto-detect from browser) */
+    locale?: "en" | "pt-BR" | string;
+    /** Custom translations to override built-in strings */
+    translations?: Partial<TranslationStrings>;
+    /** Visual customization options for forms */
+    theme?: WidgetTheme;
+    /** Rendering mode for forms */
+    mode?: "inline" | "modal";
+    /** Target element for inline mode (CSS selector or HTMLElement) */
+    container?: string | HTMLElement;
+    /** Show/hide GetForty branding */
+    showBranding?: boolean;
+    /** Automatically track page views */
+    autoTrackPageViews?: boolean;
+    /** Automatically display forms based on server-side conditions (default: true) */
+    autoDisplay?: boolean;
+    /** API base URL (default: https://getforty.club) */
+    apiBaseUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Observe parent window's dataLayer (Google Tag Manager) and automatically
+     * send events through GetForty tracking pipeline (opt-in)
+     *
+     * When enabled, watches for events pushed to window.dataLayer and forwards
+     * them to GetForty's backend, allowing you to leverage existing GTM integrations.
+     *
+     * Note: Only works in same-origin scenarios (cross-origin iframes not supported)
+     */
+    observeDataLayer?: boolean;
+    /**
+     * Prefix added to dataLayer event names when sent to GetForty
+     * (default: "gtm_")
+     *
+     * Example: dataLayer event "purchase" becomes "gtm_purchase" in GetForty
+     */
+    dataLayerEventPrefix?: string;
+    /**
+     * Filter which dataLayer events to send (optional)
+     * Can be a RegExp to test event names or a function that returns boolean
+     *
+     * Examples:
+     * - /^custom_/  (only events starting with "custom_")
+     * - (name) => name !== "gtm.js"  (exclude GTM internal events)
+     */
+    dataLayerEventFilter?: RegExp | ((eventName: string) => boolean);
+}
+/**
+ * Visual customization options for form UI
+ */
+interface WidgetTheme {
+    /** Primary color for buttons and accents (CSS color) */
+    primaryColor?: string;
+    /** Background color for widget container (CSS color) */
+    backgroundColor?: string;
+    /** Text color (CSS color) */
+    textColor?: string;
+    /** Font family (CSS font-family) */
+    fontFamily?: string;
+    /** Border radius for containers and inputs (CSS value) */
+    borderRadius?: string;
+}
+/**
+ * Options for tracking a custom event
+ */
+interface TrackEventOptions {
+    /** Custom properties to attach to the event */
+    properties?: Record<string, string | number | boolean | null>;
+    /** Override the auto-generated session ID */
+    sessionId?: string;
+    /** Override the identified user ID */
+    userId?: string;
+    /** Timestamp override (default: now) */
+    timestamp?: Date;
+}
+/**
+ * Options for identifying a user
+ */
+interface IdentifyOptions {
+    /** User traits/properties */
+    traits?: Record<string, string | number | boolean | null>;
+}
+/**
+ * Internal representation of a tracked event
+ */
+interface TrackedEvent {
+    /** Event name (e.g., 'page_view', 'purchase', 'signup') */
+    eventName: string;
+    /** Custom event properties */
+    properties?: Record<string, unknown>;
+    /** Session identifier (auto-generated or provided) */
+    sessionId: string;
+    /** User identifier (from identify() call) */
+    userId?: string;
+    /** Event timestamp */
+    timestamp: string;
+    /** Retry count for failed sends */
+    _retryCount?: number;
+}
+/**
+ * Localizable UI strings
+ */
+interface TranslationStrings {
+    submit: string;
+    submitting: string;
+    next: string;
+    previous: string;
+    skip: string;
+    required: string;
+    invalidEmail: string;
+    invalidNumber: string;
+    minLength: string;
+    maxLength: string;
+    loading: string;
+    success: string;
+    successMessage: string;
+    error: string;
+    networkError: string;
+    rateLimited: string;
+    tryAgain: string;
+    npsNotLikely: string;
+    npsVeryLikely: string;
+    closeModal: string;
+    formLabel: string;
+    questionOf: string;
+}
+/**
+ * Form configuration received from API
+ */
+interface FormConfig {
+    id: string;
+    title: string;
+    type: "NPS" | "CSAT" | "PMF" | "CUSTOM";
+    questions: Question[];
+    branding?: {
+        logoUrl?: string;
+        thankYouMessage?: string;
+        colors?: {
+            primary?: string;
+            background?: string;
+        };
+    };
+}
+/**
+ * Question definition within a form
+ */
+interface Question {
+    id: string;
+    type: "rating" | "nps" | "text" | "textarea" | "select" | "multiselect" | "scale";
+    label: string;
+    description?: string;
+    required: boolean;
+    options?: QuestionOption[];
+    validation?: {
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+    };
+}
+/**
+ * Option for select/multiselect questions
+ */
+interface QuestionOption {
+    value: string;
+    label: string;
+}
+/**
+ * Answer submitted for a question
+ */
+interface Answer {
+    questionId: string;
+    value: string | string[] | number;
+}
+/**
+ * Events emitted by widget for developer integration
+ */
+interface WidgetEventMap {
+    /** Widget started loading form configuration */
+    "load:start": {
+        formId: string;
+    };
+    /** Form configuration loaded successfully */
+    "load:success": {
+        form: FormConfig;
+    };
+    /** Form loading failed */
+    "load:error": {
+        error: string;
+        retryable: boolean;
+    };
+    /** Widget became visible (modal opened or inline rendered) */
+    open: {
+        mode: "inline" | "modal";
+    };
+    /** Widget hidden (modal closed) */
+    close: {
+        reason: "user" | "submitted" | "programmatic";
+    };
+    /** Form submission started */
+    "submit:start": {
+        answers: Answer[];
+    };
+    /** Form submission successful */
+    "submit:success": {
+        responseId: string;
+    };
+    /** Form submission failed */
+    "submit:error": {
+        error: string;
+        retryable: boolean;
+    };
+    /** Any error occurred */
+    error: {
+        type: "load" | "submit" | "network";
+        message: string;
+    };
+    /** Field received focus */
+    "field:focus": {
+        questionId: string;
+        questionLabel: string;
+    };
+    /** Field lost focus */
+    "field:blur": {
+        questionId: string;
+        questionLabel: string;
+    };
+    /** Field value changed */
+    "field:change": {
+        questionId: string;
+        questionLabel: string;
+    };
+    /** Field validation error */
+    "field:validation": {
+        questionId: string;
+        questionLabel: string;
+        error: string;
+    };
+}
+/**
+ * Public interface for the GetForty widget instance
+ */
+interface GetFortyWidgetInstance {
+    /**
+     * Track a custom event
+     * @param eventName - Name of the event (e.g., 'page_view', 'purchase')
+     * @param properties - Optional custom properties
+     */
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /**
+     * Identify the current user
+     * Sends user data to backend and links events/respondents
+     * @param userId - Unique user identifier
+     * @param traits - Optional user traits (email, name, plan, etc.)
+     */
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    /**
+     * Show a feedback form
+     * @param formId - The form ID to display
+     */
+    showForm(formId: string): void;
+    /**
+     * Hide the currently displayed form
+     */
+    hideForm(): void;
+    /**
+     * Subscribe to widget lifecycle events
+     * @param event - Event name
+     * @param callback - Event handler
+     */
+    on<K extends keyof WidgetEventMap>(event: K, callback: (data: WidgetEventMap[K]) => void): void;
+    /**
+     * Unsubscribe from widget lifecycle events
+     */
+    off<K extends keyof WidgetEventMap>(event: K, callback: (data: WidgetEventMap[K]) => void): void;
+    /**
+     * Flush any queued events immediately
+     */
+    flush(): Promise<void>;
+    /**
+     * Get the current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Destroy the widget and clean up resources
+     * Stops polling, clears timers, and removes DOM elements
+     */
+    destroy(): void;
+}
+
+/**
+ * Widget constants
+ */
+declare const VERSION = "0.1.0";
+
+/**
+ * @getforty/widget
+ * Embeddable feedback widget and event tracking SDK for GetForty
+ *
+ * Usage:
+ * ```typescript
+ * import { GetForty } from '@getforty/widget'
+ *
+ * const widget = await GetForty.init({
+ *   trackingId: 'gf_xxxxxxxxxxxx',
+ * })
+ *
+ * // Track events
+ * widget.track('page_view', { page: '/pricing' })
+ *
+ * // Identify users
+ * widget.identify('user_123', { email: 'user@example.com' })
+ *
+ * // Show forms programmatically
+ * widget.showForm('form-id')
+ *
+ * // Listen to events
+ * widget.on('submit:success', (data) => {
+ *   console.log('Feedback submitted!', data.responseId)
+ * })
+ * ```
+ */
+
+/**
+ * GetForty namespace
+ * Main entry point for the widget SDK
+ */
+declare const GetForty: {
+    /**
+     * Initialize the GetForty widget
+     * @param config - Widget configuration
+     * @returns Promise that resolves to a widget instance
+     * @throws Error if trackingId is missing or invalid
+     *
+     * @example
+     * ```typescript
+     * const widget = await GetForty.init({
+     *   trackingId: 'gf_xxxxxxxxxxxx',
+     *   debug: true, // Enable debug logging
+     * })
+     * ```
+     */
+    init(config: WidgetConfig): Promise<GetFortyWidgetInstance>;
+    /**
+     * Current SDK version
+     */
+    version: string;
+};
+
+export { type Answer, type FormConfig, GetForty, type GetFortyWidgetInstance, type IdentifyOptions, type Question, type TrackEventOptions, type TrackedEvent, type TranslationStrings, VERSION, type WidgetConfig, type WidgetEventMap, type WidgetTheme, GetForty as default };