@sendmailos/sdk 1.0.0 → 1.1.1

package/README.md

@@ -33,7 +33,8 @@ await client.emails.send({
 
 - **Type-safe**: Full TypeScript support with exported types
 - **Lightweight**: Zero dependencies for core SDK
-- **React Components**: Pre-built components for common patterns
+- **Pixel Tracking**: Track website visitors and link to email campaigns
+- **React Components**: Pre-built components and hooks
 - **Webhook Verification**: Secure signature verification utilities
 - **Error Handling**: Custom error classes for different scenarios
 
@@ -101,6 +102,123 @@ const { domain } = await client.domains.create({
 console.log('DNS Records to add:', domain.dnsRecords);
 ```
 
+## Pixel Tracking
+
+Track website visitors and connect their behavior to email campaigns.
+
+### Basic Setup
+
+```typescript
+import { SendmailPixel } from '@sendmailos/sdk';
+
+const pixel = new SendmailPixel({
+  token: 'pk_live_your_public_key',
+  debug: false // Set true for console logging
+});
+
+pixel.init();
+```
+
+### Track Events
+
+```typescript
+// Track custom events
+pixel.track('button_clicked', { button_id: 'cta-signup' });
+
+// Track page views (called automatically on init)
+pixel.pageView();
+
+// Identify a visitor by email
+pixel.identify('user@example.com', {
+  first_name: 'John',
+  plan: 'premium'
+});
+```
+
+### Privacy Controls
+
+```typescript
+// Opt out of tracking (e.g., user declines cookies)
+pixel.optOut();
+
+// Opt back in
+pixel.optIn();
+
+// Check opt-out status
+if (pixel.isOptedOut()) {
+  console.log('Tracking disabled');
+}
+
+// Reset identity (e.g., on logout)
+pixel.reset();
+```
+
+### Global smp() Function
+
+For script tag usage, use `createGlobalPixel` to set up a global `smp()` function:
+
+```typescript
+import { createGlobalPixel } from '@sendmailos/sdk';
+
+createGlobalPixel({ token: 'pk_live_...' });
+
+// Now use anywhere:
+smp('track', 'event_name', { property: 'value' });
+smp('identify', 'user@example.com');
+smp('optOut');
+smp('optIn');
+```
+
+### React Pixel Hooks
+
+```tsx
+import { usePixel, usePageTracking, useIdentifyOnLogin } from '@sendmailos/sdk/react';
+
+// Basic usage
+function MyComponent() {
+  const { track, identify, optOut } = usePixel('pk_live_...');
+
+  return (
+    <button onClick={() => track('button_clicked', { id: 'cta' })}>
+      Click Me
+    </button>
+  );
+}
+
+// Auto page tracking (Next.js App Router)
+function Layout({ children }) {
+  const pathname = usePathname();
+  usePageTracking('pk_live_...', pathname);
+  return <>{children}</>;
+}
+
+// Auto identify on login
+function App() {
+  const { user } = useAuth();
+  useIdentifyOnLogin('pk_live_...', user?.email, {
+    first_name: user?.firstName,
+    plan: user?.plan
+  });
+  return <Main />;
+}
+```
+
+### Data Attributes
+
+Track clicks without JavaScript using HTML data attributes:
+
+```html
+<button data-smp-track="signup_clicked">Sign Up</button>
+
+<button
+  data-smp-track="button_clicked"
+  data-smp-track-button-id="cta-main"
+  data-smp-track-variant="blue"
+>
+  Get Started
+</button>
+```
+
 ## React Integration
 
 ```tsx

package/dist/index.d.mts

@@ -400,6 +400,93 @@ declare class SendMailOS {
     static get version(): string;
 }
 
+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;
+}
+/** Alias for PixelConfig for SDK consistency */
+type PixelOptions = PixelConfig;
+interface TrackProps {
+    [key: string]: string | number | boolean | null | undefined | object;
+}
+/** Alias for TrackProps */
+type TrackEventProperties = TrackProps;
+/** 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;
+}
+/** Alias for SendmailPixel for SDK consistency */
+declare const Pixel: typeof SendmailPixel;
+/**
+ * Create pixel and attach global smp() function
+ */
+declare function createGlobalPixel(config: PixelConfig): SendmailPixel;
+
 /**
  * Custom error classes for SendMailOS SDK
  */
@@ -477,4 +564,4 @@ declare function constructWebhookEvent<T = unknown>(payload: string, headers: {
     timestamp: string;
 }, secret: string): T;
 
-export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type DnsRecord, type Domain, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, NotFoundError, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, type Subscriber, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, constructWebhookEvent, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };
+export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type DnsRecord, type Domain, type IdentifyTraits, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, NotFoundError, Pixel, type PixelConfig, type PixelOptions, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, SendmailPixel, type Subscriber, type TrackEventProperties, type TrackProps, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, constructWebhookEvent, createGlobalPixel, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };

package/dist/index.d.ts

@@ -400,6 +400,93 @@ declare class SendMailOS {
     static get version(): string;
 }
 
+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;
+}
+/** Alias for PixelConfig for SDK consistency */
+type PixelOptions = PixelConfig;
+interface TrackProps {
+    [key: string]: string | number | boolean | null | undefined | object;
+}
+/** Alias for TrackProps */
+type TrackEventProperties = TrackProps;
+/** 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;
+}
+/** Alias for SendmailPixel for SDK consistency */
+declare const Pixel: typeof SendmailPixel;
+/**
+ * Create pixel and attach global smp() function
+ */
+declare function createGlobalPixel(config: PixelConfig): SendmailPixel;
+
 /**
  * Custom error classes for SendMailOS SDK
  */
@@ -477,4 +564,4 @@ declare function constructWebhookEvent<T = unknown>(payload: string, headers: {
     timestamp: string;
 }, secret: string): T;
 
-export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type DnsRecord, type Domain, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, NotFoundError, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, type Subscriber, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, constructWebhookEvent, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };
+export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type DnsRecord, type Domain, type IdentifyTraits, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, NotFoundError, Pixel, type PixelConfig, type PixelOptions, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, SendmailPixel, type Subscriber, type TrackEventProperties, type TrackProps, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, constructWebhookEvent, createGlobalPixel, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };