@amplifyup/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,309 @@
+import { C as CDPAdapter, A as AmplifyUpConfig, E as EventProperties, I as IdentifyTraits, a as EventTrackingConfig$1 } from './types-B9nHG2Cl.mjs';
+export { P as PageConfig, Z as ZoneConfig } from './types-B9nHG2Cl.mjs';
+
+/**
+ * AmplifyUp Tracking SDK
+ *
+ * Event tracking and personalization SDK for Pure AWS architecture.
+ *
+ * Uses AWS API Gateway for event ingestion and AWS Decision API for personalization.
+ * All runtime data (events, profiles, decisions) lives in AWS.
+ */
+
+interface EventTrackingConfig {
+    eventName: string;
+    eventType: string;
+    selector?: string;
+    description?: string;
+    properties?: string[];
+    enabled?: boolean;
+}
+declare class AmplifyUpSDK {
+    private adapter;
+    private config;
+    private apiGatewayUrl;
+    private orchestratorUrl;
+    private decisionApiUrl;
+    private initialized;
+    private highlightingEnabled;
+    private componentRegistry;
+    private messageListener;
+    private mutationObserver;
+    private isVisualEditorMode;
+    private eventSelectionMode;
+    private eventSelectionClickHandler;
+    private eventTrackingConfig;
+    private attachedEventListeners;
+    private trackingIntervals;
+    private trackingCleanup;
+    constructor(adapter?: CDPAdapter);
+    /**
+     * Detect if we're running in visual editor mode
+     * Returns true if:
+     * 1. Preview mode flag is set by proxy
+     * 2. We're in an iframe AND parent is from orchestrator domain
+     * 3. OR visualEditor/preview query parameter is present
+     */
+    private detectVisualEditorMode;
+    /**
+     * Check if we're in preview/composer mode (should disable tracking)
+     */
+    private isPreviewMode;
+    /**
+     * Get production URLs
+     *
+     * URLs are baked in at build time via tsup.config.ts
+     *
+     * API Gateway endpoints:
+     * - /v1/track - Event tracking (ingestion)
+     * - /v1/page - Page view tracking (ingestion)
+     * - /v1/personalize - Decision engine (personalization)
+     */
+    private getProductionUrls;
+    /**
+     * Initialize the SDK
+     * Automatically reads env vars and sets up tracking
+     */
+    init(config: AmplifyUpConfig): Promise<void>;
+    /**
+     * Check if SDK is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Clear all tracking intervals and event listeners
+     */
+    private clearTrackingIntervals;
+    /**
+     * Track a page view
+     */
+    page(url: string, properties?: EventProperties): void;
+    /**
+     * Track an event
+     */
+    track(eventName: string, properties?: EventProperties): void;
+    /**
+     * Track a button click or CTA interaction
+     */
+    trackClick(elementId: string, elementText: string, properties?: EventProperties): void;
+    /**
+     * Track form submission
+     */
+    trackFormSubmit(formId: string, formData?: EventProperties): void;
+    /**
+     * Track form field interaction
+     */
+    trackFormFieldInteraction(fieldName: string, fieldValue?: string): void;
+    /**
+     * Track product/content view
+     */
+    trackContentView(contentId: string, contentType: string, properties?: EventProperties): void;
+    /**
+     * Identify user (when they sign up or log in)
+     */
+    identify(userId: string, traits?: IdentifyTraits): void;
+    /**
+     * Track content engagement (when user interacts with personalized content)
+     */
+    trackContentEngagement(contentId: string, engagementType: 'view' | 'click' | 'dismiss'): void;
+    /**
+     * Reset user identity (logout)
+     */
+    reset(): void;
+    /**
+     * Get instance ID (anonymous ID)
+     */
+    getInstanceId(): string;
+    /**
+     * Get user ID
+     */
+    getUserId(): string | null;
+    /**
+     * Get tracking ID
+     */
+    getTrackingId(): string | undefined;
+    /**
+     * Get diagnostic information
+     * Useful for debugging from browser console
+     */
+    getDiagnostics(): {
+        initialized: boolean;
+        instanceId: string;
+        userId: string | null;
+        trackingId: string | undefined;
+        config: {
+            apiGatewayUrl?: string;
+            decisionApiUrl?: string;
+            orchestratorUrl?: string;
+            debug?: boolean;
+        };
+    };
+    /**
+     * Test tracking by sending a test event
+     */
+    testTracking(): void;
+    /**
+     * Verify AWS API Gateway connectivity
+     * Checks if AWS adapter is initialized and can send events
+     */
+    verifyAWSConnection(): {
+        connected: boolean;
+        message: string;
+        details?: any;
+    };
+    /**
+     * Get status summary (for console debugging)
+     */
+    getStatus(): string;
+    /**
+     * Get orchestrator URL
+     */
+    getOrchestratorUrl(): string | undefined;
+    /**
+     * Get decision API URL
+     */
+    getDecisionApiUrl(): string | undefined;
+    /**
+     * Build API URL for fetching page config from the Layout Provider
+     */
+    buildLayoutProviderUrl(route: string, preview?: boolean): string;
+    /**
+     * Fetch page configuration from orchestrator's Layout Provider
+     */
+    fetchPageConfig(route: string, preview?: boolean): Promise<any>;
+    /**
+     * Set up view-level event tracking based on configuration
+     */
+    setupEventTracking(eventConfig: EventTrackingConfig[]): void;
+    /**
+     * Attach event listeners to page elements based on view-level configuration
+     */
+    private attachEventListeners;
+    /**
+     * Map event type from config to DOM event type
+     */
+    private mapEventType;
+    /**
+     * Handle a tracked event and send to AWS API Gateway
+     */
+    private handleTrackedEvent;
+    /**
+     * Set up view tracking using IntersectionObserver
+     */
+    private setupViewTracking;
+    /**
+     * Clean up all attached event listeners
+     */
+    cleanupEventTracking(): void;
+    /**
+     * Manually trigger event tracking setup (useful after dynamic content loads)
+     */
+    refreshEventTracking(): void;
+    /**
+     * Set up postMessage listener for highlighting commands from orchestrator
+     */
+    private setupHighlightingListener;
+    /**
+     * Enable/disable event selection mode
+     * When enabled, clicks on elements send element info to parent for event configuration
+     */
+    private setEventSelectionMode;
+    /**
+     * Generate a CSS selector for an element
+     */
+    private generateSelectorForElement;
+    /**
+     * Enable component highlighting
+     */
+    private enableHighlighting;
+    /**
+     * Set up MutationObserver to watch for new components being added
+     */
+    private setupMutationObserver;
+    /**
+     * Disable component highlighting
+     */
+    private disableHighlighting;
+    /**
+     * Build component hierarchy for ancestor selection
+     */
+    private buildComponentHierarchy;
+    /**
+     * Send selection message to orchestrator (includes element bounds for overlay positioning).
+     */
+    private sendSelectionMessage;
+    /**
+     * Send component tree to orchestrator
+     * Note: Component tree is now sent from AmplifyRenderer based on layoutTree from pageConfig
+     * This method is kept for backwards compatibility but is no longer used
+     */
+    private sendComponentTree;
+    /**
+     * Apply component highlights
+     */
+    private applyComponentHighlights;
+    /**
+     * Cleanup: Remove message listener and observers
+     */
+    cleanup(): void;
+}
+/**
+ * Get or create the SDK instance
+ */
+declare function getSDK(adapter?: CDPAdapter): AmplifyUpSDK;
+/**
+ * Initialize the SDK (convenience function)
+ */
+declare function init(config: AmplifyUpConfig): Promise<void>;
+declare const page: (url: string, properties?: EventProperties) => void;
+declare const track: (eventName: string, properties?: EventProperties) => void;
+declare const trackClick: (elementId: string, elementText: string, properties?: EventProperties) => void;
+declare const trackFormSubmit: (formId: string, formData?: EventProperties) => void;
+declare const trackFormFieldInteraction: (fieldName: string, fieldValue?: string) => void;
+declare const trackContentView: (contentId: string, contentType: string, properties?: EventProperties) => void;
+declare const identify: (userId: string, traits?: IdentifyTraits) => void;
+declare const trackContentEngagement: (contentId: string, engagementType: "view" | "click" | "dismiss") => void;
+declare const reset: () => void;
+declare const getInstanceId: () => string;
+declare const getUserId: () => string | null;
+declare const getTrackingId: () => string | undefined;
+declare const getOrchestratorUrl: () => string | undefined;
+declare const buildLayoutProviderUrl: (route: string, preview?: boolean) => string;
+declare const buildPageRenderUrl: (route: string, preview?: boolean) => string;
+declare const fetchPageConfig: (route: string, preview?: boolean) => Promise<any>;
+declare const setupEventTracking: (config: EventTrackingConfig$1[]) => void;
+declare const cleanupEventTracking: () => void;
+declare const refreshEventTracking: () => void;
+declare const getDiagnostics: () => {
+    initialized: boolean;
+    instanceId: string;
+    userId: string | null;
+    trackingId: string | undefined;
+    config: {
+        apiGatewayUrl?: string;
+        decisionApiUrl?: string;
+        orchestratorUrl?: string;
+        debug?: boolean;
+    };
+};
+declare const getStatus: () => {
+    initialized: boolean;
+    instanceId: string;
+    userId: string | null;
+    trackingId: string | undefined;
+    config: {
+        apiGatewayUrl?: string;
+        decisionApiUrl?: string;
+        orchestratorUrl?: string;
+        debug?: boolean;
+    };
+};
+declare const testTracking: () => void;
+declare const verifyAWSConnection: () => {
+    connected: boolean;
+    message: string;
+    details?: any;
+};
+
+declare const _default: AmplifyUpSDK;
+
+export { AmplifyUpConfig, AmplifyUpSDK, CDPAdapter, EventProperties, EventTrackingConfig$1 as EventTrackingConfig, IdentifyTraits, buildLayoutProviderUrl, buildPageRenderUrl, cleanupEventTracking, _default as default, fetchPageConfig, getDiagnostics, getInstanceId, getOrchestratorUrl, getSDK, getStatus, getTrackingId, getUserId, identify, init, page, refreshEventTracking, reset, setupEventTracking, testTracking, track, trackClick, trackContentEngagement, trackContentView, trackFormFieldInteraction, trackFormSubmit, verifyAWSConnection };

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+import { C as CDPAdapter, A as AmplifyUpConfig, E as EventProperties, I as IdentifyTraits, a as EventTrackingConfig$1 } from './types-B9nHG2Cl.js';
+export { P as PageConfig, Z as ZoneConfig } from './types-B9nHG2Cl.js';
+
+/**
+ * AmplifyUp Tracking SDK
+ *
+ * Event tracking and personalization SDK for Pure AWS architecture.
+ *
+ * Uses AWS API Gateway for event ingestion and AWS Decision API for personalization.
+ * All runtime data (events, profiles, decisions) lives in AWS.
+ */
+
+interface EventTrackingConfig {
+    eventName: string;
+    eventType: string;
+    selector?: string;
+    description?: string;
+    properties?: string[];
+    enabled?: boolean;
+}
+declare class AmplifyUpSDK {
+    private adapter;
+    private config;
+    private apiGatewayUrl;
+    private orchestratorUrl;
+    private decisionApiUrl;
+    private initialized;
+    private highlightingEnabled;
+    private componentRegistry;
+    private messageListener;
+    private mutationObserver;
+    private isVisualEditorMode;
+    private eventSelectionMode;
+    private eventSelectionClickHandler;
+    private eventTrackingConfig;
+    private attachedEventListeners;
+    private trackingIntervals;
+    private trackingCleanup;
+    constructor(adapter?: CDPAdapter);
+    /**
+     * Detect if we're running in visual editor mode
+     * Returns true if:
+     * 1. Preview mode flag is set by proxy
+     * 2. We're in an iframe AND parent is from orchestrator domain
+     * 3. OR visualEditor/preview query parameter is present
+     */
+    private detectVisualEditorMode;
+    /**
+     * Check if we're in preview/composer mode (should disable tracking)
+     */
+    private isPreviewMode;
+    /**
+     * Get production URLs
+     *
+     * URLs are baked in at build time via tsup.config.ts
+     *
+     * API Gateway endpoints:
+     * - /v1/track - Event tracking (ingestion)
+     * - /v1/page - Page view tracking (ingestion)
+     * - /v1/personalize - Decision engine (personalization)
+     */
+    private getProductionUrls;
+    /**
+     * Initialize the SDK
+     * Automatically reads env vars and sets up tracking
+     */
+    init(config: AmplifyUpConfig): Promise<void>;
+    /**
+     * Check if SDK is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Clear all tracking intervals and event listeners
+     */
+    private clearTrackingIntervals;
+    /**
+     * Track a page view
+     */
+    page(url: string, properties?: EventProperties): void;
+    /**
+     * Track an event
+     */
+    track(eventName: string, properties?: EventProperties): void;
+    /**
+     * Track a button click or CTA interaction
+     */
+    trackClick(elementId: string, elementText: string, properties?: EventProperties): void;
+    /**
+     * Track form submission
+     */
+    trackFormSubmit(formId: string, formData?: EventProperties): void;
+    /**
+     * Track form field interaction
+     */
+    trackFormFieldInteraction(fieldName: string, fieldValue?: string): void;
+    /**
+     * Track product/content view
+     */
+    trackContentView(contentId: string, contentType: string, properties?: EventProperties): void;
+    /**
+     * Identify user (when they sign up or log in)
+     */
+    identify(userId: string, traits?: IdentifyTraits): void;
+    /**
+     * Track content engagement (when user interacts with personalized content)
+     */
+    trackContentEngagement(contentId: string, engagementType: 'view' | 'click' | 'dismiss'): void;
+    /**
+     * Reset user identity (logout)
+     */
+    reset(): void;
+    /**
+     * Get instance ID (anonymous ID)
+     */
+    getInstanceId(): string;
+    /**
+     * Get user ID
+     */
+    getUserId(): string | null;
+    /**
+     * Get tracking ID
+     */
+    getTrackingId(): string | undefined;
+    /**
+     * Get diagnostic information
+     * Useful for debugging from browser console
+     */
+    getDiagnostics(): {
+        initialized: boolean;
+        instanceId: string;
+        userId: string | null;
+        trackingId: string | undefined;
+        config: {
+            apiGatewayUrl?: string;
+            decisionApiUrl?: string;
+            orchestratorUrl?: string;
+            debug?: boolean;
+        };
+    };
+    /**
+     * Test tracking by sending a test event
+     */
+    testTracking(): void;
+    /**
+     * Verify AWS API Gateway connectivity
+     * Checks if AWS adapter is initialized and can send events
+     */
+    verifyAWSConnection(): {
+        connected: boolean;
+        message: string;
+        details?: any;
+    };
+    /**
+     * Get status summary (for console debugging)
+     */
+    getStatus(): string;
+    /**
+     * Get orchestrator URL
+     */
+    getOrchestratorUrl(): string | undefined;
+    /**
+     * Get decision API URL
+     */
+    getDecisionApiUrl(): string | undefined;
+    /**
+     * Build API URL for fetching page config from the Layout Provider
+     */
+    buildLayoutProviderUrl(route: string, preview?: boolean): string;
+    /**
+     * Fetch page configuration from orchestrator's Layout Provider
+     */
+    fetchPageConfig(route: string, preview?: boolean): Promise<any>;
+    /**
+     * Set up view-level event tracking based on configuration
+     */
+    setupEventTracking(eventConfig: EventTrackingConfig[]): void;
+    /**
+     * Attach event listeners to page elements based on view-level configuration
+     */
+    private attachEventListeners;
+    /**
+     * Map event type from config to DOM event type
+     */
+    private mapEventType;
+    /**
+     * Handle a tracked event and send to AWS API Gateway
+     */
+    private handleTrackedEvent;
+    /**
+     * Set up view tracking using IntersectionObserver
+     */
+    private setupViewTracking;
+    /**
+     * Clean up all attached event listeners
+     */
+    cleanupEventTracking(): void;
+    /**
+     * Manually trigger event tracking setup (useful after dynamic content loads)
+     */
+    refreshEventTracking(): void;
+    /**
+     * Set up postMessage listener for highlighting commands from orchestrator
+     */
+    private setupHighlightingListener;
+    /**
+     * Enable/disable event selection mode
+     * When enabled, clicks on elements send element info to parent for event configuration
+     */
+    private setEventSelectionMode;
+    /**
+     * Generate a CSS selector for an element
+     */
+    private generateSelectorForElement;
+    /**
+     * Enable component highlighting
+     */
+    private enableHighlighting;
+    /**
+     * Set up MutationObserver to watch for new components being added
+     */
+    private setupMutationObserver;
+    /**
+     * Disable component highlighting
+     */
+    private disableHighlighting;
+    /**
+     * Build component hierarchy for ancestor selection
+     */
+    private buildComponentHierarchy;
+    /**
+     * Send selection message to orchestrator (includes element bounds for overlay positioning).
+     */
+    private sendSelectionMessage;
+    /**
+     * Send component tree to orchestrator
+     * Note: Component tree is now sent from AmplifyRenderer based on layoutTree from pageConfig
+     * This method is kept for backwards compatibility but is no longer used
+     */
+    private sendComponentTree;
+    /**
+     * Apply component highlights
+     */
+    private applyComponentHighlights;
+    /**
+     * Cleanup: Remove message listener and observers
+     */
+    cleanup(): void;
+}
+/**
+ * Get or create the SDK instance
+ */
+declare function getSDK(adapter?: CDPAdapter): AmplifyUpSDK;
+/**
+ * Initialize the SDK (convenience function)
+ */
+declare function init(config: AmplifyUpConfig): Promise<void>;
+declare const page: (url: string, properties?: EventProperties) => void;
+declare const track: (eventName: string, properties?: EventProperties) => void;
+declare const trackClick: (elementId: string, elementText: string, properties?: EventProperties) => void;
+declare const trackFormSubmit: (formId: string, formData?: EventProperties) => void;
+declare const trackFormFieldInteraction: (fieldName: string, fieldValue?: string) => void;
+declare const trackContentView: (contentId: string, contentType: string, properties?: EventProperties) => void;
+declare const identify: (userId: string, traits?: IdentifyTraits) => void;
+declare const trackContentEngagement: (contentId: string, engagementType: "view" | "click" | "dismiss") => void;
+declare const reset: () => void;
+declare const getInstanceId: () => string;
+declare const getUserId: () => string | null;
+declare const getTrackingId: () => string | undefined;
+declare const getOrchestratorUrl: () => string | undefined;
+declare const buildLayoutProviderUrl: (route: string, preview?: boolean) => string;
+declare const buildPageRenderUrl: (route: string, preview?: boolean) => string;
+declare const fetchPageConfig: (route: string, preview?: boolean) => Promise<any>;
+declare const setupEventTracking: (config: EventTrackingConfig$1[]) => void;
+declare const cleanupEventTracking: () => void;
+declare const refreshEventTracking: () => void;
+declare const getDiagnostics: () => {
+    initialized: boolean;
+    instanceId: string;
+    userId: string | null;
+    trackingId: string | undefined;
+    config: {
+        apiGatewayUrl?: string;
+        decisionApiUrl?: string;
+        orchestratorUrl?: string;
+        debug?: boolean;
+    };
+};
+declare const getStatus: () => {
+    initialized: boolean;
+    instanceId: string;
+    userId: string | null;
+    trackingId: string | undefined;
+    config: {
+        apiGatewayUrl?: string;
+        decisionApiUrl?: string;
+        orchestratorUrl?: string;
+        debug?: boolean;
+    };
+};
+declare const testTracking: () => void;
+declare const verifyAWSConnection: () => {
+    connected: boolean;
+    message: string;
+    details?: any;
+};
+
+declare const _default: AmplifyUpSDK;
+
+export { AmplifyUpConfig, AmplifyUpSDK, CDPAdapter, EventProperties, EventTrackingConfig$1 as EventTrackingConfig, IdentifyTraits, buildLayoutProviderUrl, buildPageRenderUrl, cleanupEventTracking, _default as default, fetchPageConfig, getDiagnostics, getInstanceId, getOrchestratorUrl, getSDK, getStatus, getTrackingId, getUserId, identify, init, page, refreshEventTracking, reset, setupEventTracking, testTracking, track, trackClick, trackContentEngagement, trackContentView, trackFormFieldInteraction, trackFormSubmit, verifyAWSConnection };