@sendmailos/sdk 1.0.0 → 1.1.1

package/dist/react/index.d.mts

@@ -137,4 +137,162 @@ interface SubscribeFormProps {
  */
 declare function SubscribeForm({ tags, onSuccess, onError, className, placeholder, buttonText, loadingText, successMessage, showNameFields, style, }: SubscribeFormProps): react_jsx_runtime.JSX.Element;
 
-export { SendMailOSProvider, SubscribeForm, type SubscribeFormProps, useSendMailOS, useSubscribe };
+interface PixelConfig {
+    /** Public API key (pk_live_... or pk_test_...) or legacy token */
+    token: string;
+    /** API endpoint for tracking events */
+    endpoint?: string;
+    /** Cookie name for anonymous ID storage */
+    cookieName?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Respect Do Not Track browser setting (default: true) */
+    respectDNT?: boolean;
+}
+interface TrackProps {
+    [key: string]: string | number | boolean | null | undefined | object;
+}
+/** Traits for identify calls */
+interface IdentifyTraits {
+    first_name?: string;
+    last_name?: string;
+    [key: string]: string | number | boolean | null | undefined | object;
+}
+declare class SendmailPixel {
+    private config;
+    private anonymousId;
+    private initialized;
+    private rules;
+    private identifiedEmail;
+    constructor(config: PixelConfig);
+    init(): void;
+    /**
+     * Opt out of all tracking
+     */
+    optOut(): void;
+    /**
+     * Opt back in to tracking
+     */
+    optIn(): void;
+    /**
+     * Check if user has opted out
+     */
+    isOptedOut(): boolean;
+    /**
+     * Reset identity (e.g., on logout)
+     */
+    reset(): void;
+    /**
+     * Get current visitor/anonymous ID
+     */
+    getVisitorId(): string;
+    /**
+     * Get identified email address
+     */
+    getIdentifiedEmail(): string | null;
+    track(eventName: string, properties?: TrackProps): void;
+    identify(email: string, traits?: TrackProps): void;
+    pageView(): void;
+    private getOrSetAnonymousId;
+    private sendEvent;
+    loadRules(): Promise<void>;
+    /**
+     * Smart Auto-Detection of Page Type & Context
+     * Uses Dynamic Rules + Static Heuristics
+     */
+    private detectContext;
+    private setupFormListeners;
+    private setupHistoryListeners;
+    private setCookie;
+    private getCookie;
+    private log;
+    private isDNTEnabled;
+    private checkUrlForSubscriber;
+    private setupDataAttributeTracking;
+    private getStoredEmail;
+    private storeEmail;
+    private isValidEmail;
+}
+
+/**
+ * React hook for SendMailOS Pixel tracking
+ */
+
+interface UsePixelOptions extends Omit<PixelConfig, 'token'> {
+}
+interface UsePixelReturn {
+    /** Track a custom event */
+    track: (eventName: string, properties?: TrackProps) => void;
+    /** Track a page view */
+    page: () => void;
+    /** Identify a user by email */
+    identify: (email: string, traits?: IdentifyTraits) => void;
+    /** Opt out of tracking */
+    optOut: () => void;
+    /** Opt back in to tracking */
+    optIn: () => void;
+    /** Check if opted out */
+    isOptedOut: () => boolean;
+    /** Reset identity (e.g., on logout) */
+    reset: () => void;
+    /** Get current visitor ID */
+    getVisitorId: () => string | null;
+    /** Pixel instance (for advanced usage) */
+    pixel: SendmailPixel | null;
+}
+/**
+ * React hook for pixel tracking
+ *
+ * @example
+ * ```tsx
+ * import { usePixel } from '@sendmailos/sdk/react';
+ *
+ * function MyComponent() {
+ *   const { track, identify } = usePixel('pk_live_...');
+ *
+ *   const handleClick = () => {
+ *     track('button_clicked', { button_id: 'cta' });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click me</button>;
+ * }
+ * ```
+ */
+declare function usePixel(token: string, options?: UsePixelOptions): UsePixelReturn;
+/**
+ * Hook to track page views on route changes
+ * Useful for Next.js App Router or React Router
+ *
+ * @example
+ * ```tsx
+ * import { usePageTracking } from '@sendmailos/sdk/react';
+ * import { usePathname } from 'next/navigation';
+ *
+ * function Layout({ children }) {
+ *   const pathname = usePathname();
+ *   usePageTracking('pk_live_...', pathname);
+ *   return children;
+ * }
+ * ```
+ */
+declare function usePageTracking(token: string, pathname: string, options?: UsePixelOptions): void;
+/**
+ * Hook to identify user when they log in
+ *
+ * @example
+ * ```tsx
+ * import { useIdentifyOnLogin } from '@sendmailos/sdk/react';
+ *
+ * function App() {
+ *   const { user } = useAuth();
+ *   useIdentifyOnLogin('pk_live_...', user?.email, {
+ *     first_name: user?.firstName,
+ *     plan: user?.plan,
+ *   });
+ *   return <Main />;
+ * }
+ * ```
+ */
+declare function useIdentifyOnLogin(token: string, email: string | null | undefined, traits?: IdentifyTraits, options?: UsePixelOptions): void;
+
+export { SendMailOSProvider, SubscribeForm, type SubscribeFormProps, type UsePixelOptions, type UsePixelReturn, useIdentifyOnLogin, usePageTracking, usePixel, useSendMailOS, useSubscribe };

package/dist/react/index.d.ts

@@ -137,4 +137,162 @@ interface SubscribeFormProps {
  */
 declare function SubscribeForm({ tags, onSuccess, onError, className, placeholder, buttonText, loadingText, successMessage, showNameFields, style, }: SubscribeFormProps): react_jsx_runtime.JSX.Element;
 
-export { SendMailOSProvider, SubscribeForm, type SubscribeFormProps, useSendMailOS, useSubscribe };
+interface PixelConfig {
+    /** Public API key (pk_live_... or pk_test_...) or legacy token */
+    token: string;
+    /** API endpoint for tracking events */
+    endpoint?: string;
+    /** Cookie name for anonymous ID storage */
+    cookieName?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Respect Do Not Track browser setting (default: true) */
+    respectDNT?: boolean;
+}
+interface TrackProps {
+    [key: string]: string | number | boolean | null | undefined | object;
+}
+/** Traits for identify calls */
+interface IdentifyTraits {
+    first_name?: string;
+    last_name?: string;
+    [key: string]: string | number | boolean | null | undefined | object;
+}
+declare class SendmailPixel {
+    private config;
+    private anonymousId;
+    private initialized;
+    private rules;
+    private identifiedEmail;
+    constructor(config: PixelConfig);
+    init(): void;
+    /**
+     * Opt out of all tracking
+     */
+    optOut(): void;
+    /**
+     * Opt back in to tracking
+     */
+    optIn(): void;
+    /**
+     * Check if user has opted out
+     */
+    isOptedOut(): boolean;
+    /**
+     * Reset identity (e.g., on logout)
+     */
+    reset(): void;
+    /**
+     * Get current visitor/anonymous ID
+     */
+    getVisitorId(): string;
+    /**
+     * Get identified email address
+     */
+    getIdentifiedEmail(): string | null;
+    track(eventName: string, properties?: TrackProps): void;
+    identify(email: string, traits?: TrackProps): void;
+    pageView(): void;
+    private getOrSetAnonymousId;
+    private sendEvent;
+    loadRules(): Promise<void>;
+    /**
+     * Smart Auto-Detection of Page Type & Context
+     * Uses Dynamic Rules + Static Heuristics
+     */
+    private detectContext;
+    private setupFormListeners;
+    private setupHistoryListeners;
+    private setCookie;
+    private getCookie;
+    private log;
+    private isDNTEnabled;
+    private checkUrlForSubscriber;
+    private setupDataAttributeTracking;
+    private getStoredEmail;
+    private storeEmail;
+    private isValidEmail;
+}
+
+/**
+ * React hook for SendMailOS Pixel tracking
+ */
+
+interface UsePixelOptions extends Omit<PixelConfig, 'token'> {
+}
+interface UsePixelReturn {
+    /** Track a custom event */
+    track: (eventName: string, properties?: TrackProps) => void;
+    /** Track a page view */
+    page: () => void;
+    /** Identify a user by email */
+    identify: (email: string, traits?: IdentifyTraits) => void;
+    /** Opt out of tracking */
+    optOut: () => void;
+    /** Opt back in to tracking */
+    optIn: () => void;
+    /** Check if opted out */
+    isOptedOut: () => boolean;
+    /** Reset identity (e.g., on logout) */
+    reset: () => void;
+    /** Get current visitor ID */
+    getVisitorId: () => string | null;
+    /** Pixel instance (for advanced usage) */
+    pixel: SendmailPixel | null;
+}
+/**
+ * React hook for pixel tracking
+ *
+ * @example
+ * ```tsx
+ * import { usePixel } from '@sendmailos/sdk/react';
+ *
+ * function MyComponent() {
+ *   const { track, identify } = usePixel('pk_live_...');
+ *
+ *   const handleClick = () => {
+ *     track('button_clicked', { button_id: 'cta' });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click me</button>;
+ * }
+ * ```
+ */
+declare function usePixel(token: string, options?: UsePixelOptions): UsePixelReturn;
+/**
+ * Hook to track page views on route changes
+ * Useful for Next.js App Router or React Router
+ *
+ * @example
+ * ```tsx
+ * import { usePageTracking } from '@sendmailos/sdk/react';
+ * import { usePathname } from 'next/navigation';
+ *
+ * function Layout({ children }) {
+ *   const pathname = usePathname();
+ *   usePageTracking('pk_live_...', pathname);
+ *   return children;
+ * }
+ * ```
+ */
+declare function usePageTracking(token: string, pathname: string, options?: UsePixelOptions): void;
+/**
+ * Hook to identify user when they log in
+ *
+ * @example
+ * ```tsx
+ * import { useIdentifyOnLogin } from '@sendmailos/sdk/react';
+ *
+ * function App() {
+ *   const { user } = useAuth();
+ *   useIdentifyOnLogin('pk_live_...', user?.email, {
+ *     first_name: user?.firstName,
+ *     plan: user?.plan,
+ *   });
+ *   return <Main />;
+ * }
+ * ```
+ */
+declare function useIdentifyOnLogin(token: string, email: string | null | undefined, traits?: IdentifyTraits, options?: UsePixelOptions): void;
+
+export { SendMailOSProvider, SubscribeForm, type SubscribeFormProps, type UsePixelOptions, type UsePixelReturn, useIdentifyOnLogin, usePageTracking, usePixel, useSendMailOS, useSubscribe };