@sendmailos/sdk 1.0.0 → 1.1.0

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 };

package/dist/index.js

@@ -434,6 +434,382 @@ var SendMailOS = class {
   }
 };
 
+// src/pixel.ts
+var OPT_OUT_KEY = "smp_opt_out";
+var IDENTIFIED_EMAIL_KEY = "smp_identified_email";
+var SendmailPixel = class {
+  constructor(config) {
+    this.initialized = false;
+    this.rules = [];
+    this.identifiedEmail = null;
+    this.config = {
+      endpoint: "https://sendmailos.com/api/pixel/track",
+      cookieName: "sm_anon_id",
+      debug: false,
+      respectDNT: true,
+      ...config
+    };
+    this.anonymousId = this.getOrSetAnonymousId();
+    this.identifiedEmail = this.getStoredEmail();
+  }
+  init() {
+    if (this.initialized) return;
+    if (typeof window === "undefined") {
+      return;
+    }
+    if (this.isOptedOut()) {
+      this.log("Tracking disabled (user opted out)");
+      return;
+    }
+    if (this.config.respectDNT && this.isDNTEnabled()) {
+      this.log("Tracking disabled (Do Not Track enabled)");
+      return;
+    }
+    this.initialized = true;
+    this.checkUrlForSubscriber();
+    this.loadRules();
+    this.pageView();
+    this.setupFormListeners();
+    this.setupHistoryListeners();
+    this.setupDataAttributeTracking();
+    this.log("Pixel initialized with Token:", this.config.token);
+  }
+  /**
+   * Opt out of all tracking
+   */
+  optOut() {
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem(OPT_OUT_KEY, "true");
+    }
+    this.log("User opted out of tracking");
+  }
+  /**
+   * Opt back in to tracking
+   */
+  optIn() {
+    if (typeof localStorage !== "undefined") {
+      localStorage.removeItem(OPT_OUT_KEY);
+    }
+    if (!this.initialized && typeof window !== "undefined") {
+      this.init();
+    }
+    this.log("User opted in to tracking");
+  }
+  /**
+   * Check if user has opted out
+   */
+  isOptedOut() {
+    if (typeof localStorage === "undefined") return false;
+    return localStorage.getItem(OPT_OUT_KEY) === "true";
+  }
+  /**
+   * Reset identity (e.g., on logout)
+   */
+  reset() {
+    this.identifiedEmail = null;
+    if (typeof localStorage !== "undefined") {
+      localStorage.removeItem(IDENTIFIED_EMAIL_KEY);
+    }
+    this.anonymousId = crypto.randomUUID();
+    this.setCookie(this.config.cookieName, this.anonymousId, 365);
+    this.log("Identity reset");
+  }
+  /**
+   * Get current visitor/anonymous ID
+   */
+  getVisitorId() {
+    return this.anonymousId;
+  }
+  /**
+   * Get identified email address
+   */
+  getIdentifiedEmail() {
+    return this.identifiedEmail;
+  }
+  track(eventName, properties = {}) {
+    this.sendEvent("track", {
+      event_name: eventName,
+      properties
+    });
+  }
+  identify(email, traits = {}) {
+    if (this.isOptedOut()) return;
+    this.identifiedEmail = email;
+    this.storeEmail(email);
+    this.sendEvent("identify", {
+      email,
+      traits
+    });
+  }
+  pageView() {
+    this.track("page_view", {
+      path: window.location.pathname,
+      title: document.title,
+      referrer: document.referrer,
+      url: window.location.href
+    });
+  }
+  // --- INTERNAL HELPERS ---
+  getOrSetAnonymousId() {
+    if (typeof document === "undefined") return "";
+    let id = this.getCookie(this.config.cookieName);
+    if (!id) {
+      id = crypto.randomUUID();
+      this.setCookie(this.config.cookieName, id, 365);
+    }
+    return id;
+  }
+  sendEvent(type, payload) {
+    if (typeof window === "undefined") return;
+    const smartContext = this.detectContext();
+    const body = {
+      type,
+      token: this.config.token,
+      // Send Token
+      anonymous_id: this.anonymousId,
+      url: window.location.href,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...payload
+    };
+    const context = {
+      userAgent: navigator.userAgent,
+      locale: navigator.language,
+      screen: { width: window.screen.width, height: window.screen.height },
+      search: window.location.search,
+      title: document.title,
+      referrer: document.referrer,
+      ...smartContext
+      // Merge smart context
+    };
+    const finalBody = { ...body, context };
+    if (navigator.sendBeacon && type === "track") {
+      const blob = new Blob([JSON.stringify(finalBody)], { type: "application/json" });
+      navigator.sendBeacon(this.config.endpoint, blob);
+    } else {
+      fetch(this.config.endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(finalBody),
+        keepalive: true
+      }).catch((err) => {
+        if (this.config.debug) console.error("[Pixel Error]", err);
+      });
+    }
+    this.log(`Event Sent [${type}]`, body);
+  }
+  // Call this after init to load rules
+  async loadRules() {
+    if (typeof window === "undefined") return;
+    try {
+      const res = await fetch(`${this.config.endpoint?.replace("/track", "")}/rules?token=${this.config.token}`);
+      if (res.ok) {
+        const data = await res.json();
+        this.rules = data.rules || [];
+      }
+    } catch (e) {
+    }
+  }
+  /**
+   * Smart Auto-Detection of Page Type & Context
+   * Uses Dynamic Rules + Static Heuristics
+   */
+  detectContext() {
+    if (typeof document === "undefined") return {};
+    const path = window.location.pathname.toLowerCase();
+    let context = {
+      page_type: "general",
+      // Default
+      topics: []
+    };
+    for (const rule of this.rules) {
+      let matched = false;
+      try {
+        if (rule.match_type === "exact" && path === rule.url_pattern) matched = true;
+        else if (rule.match_type === "contains" && path.includes(rule.url_pattern)) matched = true;
+        else if (rule.match_type === "regex" && new RegExp(rule.url_pattern).test(path)) matched = true;
+      } catch (e) {
+      }
+      if (matched) {
+        context.page_type = rule.page_type;
+        if (rule.selectors) {
+          for (const [key, selector] of Object.entries(rule.selectors)) {
+            const el = document.querySelector(selector);
+            if (el) {
+              const val = el.value || el.textContent || el.getAttribute("content");
+              if (val) context[key] = val.trim();
+            }
+          }
+        }
+        return context;
+      }
+    }
+    if (path.match(/\/(cart|basket|bag)/)) context.page_type = "cart";
+    else if (path.match(/\/(checkout|payment|order)/)) context.page_type = "checkout";
+    else if (path.match(/\/(product|item|p)\//)) context.page_type = "product";
+    else if (path.match(/\/(category|c|collection)\//)) context.page_type = "category";
+    else if (path.match(/\/(blog|article|post|news)/)) context.page_type = "content";
+    else if (path.match(/\/(login|signin)/)) context.page_type = "auth";
+    else if (path.match(/\/(signup|register)/)) context.page_type = "auth";
+    else if (path.match(/\/(pricing|plans)/)) context.page_type = "pricing";
+    else if (path.match(/\/(thank-you|confirmation|success)/)) context.page_type = "purchase_success";
+    const ogType = document.querySelector('meta[property="og:type"]')?.getAttribute("content");
+    if (ogType === "product") {
+      context.page_type = "product";
+      const price = document.querySelector('meta[property="product:price:amount"]')?.getAttribute("content");
+      if (price) context.product_price = price;
+      const currency = document.querySelector('meta[property="product:price:currency"]')?.getAttribute("content");
+      if (currency) context.currency = currency;
+    }
+    if (document.querySelector(".cart-total") || document.querySelector("#cart-summary")) {
+      context.page_type = "cart";
+    }
+    if (document.querySelector("#card-element") || document.querySelector('input[name="card_number"]')) {
+      context.page_type = "checkout";
+    }
+    const text = document.body.innerText.toLowerCase().slice(0, 2e3);
+    if (text.includes("out of stock")) context.stock_status = "out_of_stock";
+    if (text.includes("limited time")) context.urgency = "high";
+    return context;
+  }
+  setupFormListeners() {
+    if (typeof document === "undefined") return;
+    document.addEventListener("submit", (e) => {
+      const form = e.target;
+      if (!form) return;
+      const emailInput = form.querySelector('input[type="email"]');
+      if (emailInput && emailInput.value) {
+        this.log("Auto-detected email form submission", emailInput.value);
+        this.identify(emailInput.value);
+      }
+    }, true);
+  }
+  setupHistoryListeners() {
+    if (typeof window === "undefined") return;
+    const pushState = history.pushState;
+    history.pushState = (...args) => {
+      pushState.apply(history, args);
+      this.pageView();
+    };
+    window.addEventListener("popstate", () => {
+      this.pageView();
+    });
+  }
+  // --- COOKIE UTILS ---
+  setCookie(name, value, days) {
+    const d = /* @__PURE__ */ new Date();
+    d.setTime(d.getTime() + days * 24 * 60 * 60 * 1e3);
+    const expires = "expires=" + d.toUTCString();
+    document.cookie = name + "=" + value + ";" + expires + ";path=/;SameSite=Lax";
+  }
+  getCookie(name) {
+    const nameEQ = name + "=";
+    const ca = document.cookie.split(";");
+    for (let i = 0; i < ca.length; i++) {
+      let c = ca[i];
+      while (c.charAt(0) == " ") c = c.substring(1, c.length);
+      if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length, c.length);
+    }
+    return null;
+  }
+  log(...args) {
+    if (this.config.debug) {
+      console.log("[SendmailPixel]", ...args);
+    }
+  }
+  isDNTEnabled() {
+    if (typeof navigator === "undefined") return false;
+    return navigator.doNotTrack === "1" || window.doNotTrack === "1";
+  }
+  checkUrlForSubscriber() {
+    if (typeof window === "undefined") return;
+    const params = new URLSearchParams(window.location.search);
+    const subscriberEmail = params.get("smp_email");
+    const subscriberId = params.get("smp_sub");
+    if (subscriberEmail) {
+      try {
+        const email = atob(subscriberEmail);
+        if (this.isValidEmail(email)) {
+          this.identify(email);
+        }
+      } catch {
+        if (this.isValidEmail(subscriberEmail)) {
+          this.identify(subscriberEmail);
+        }
+      }
+    } else if (subscriberId) {
+      this.track("email_link_clicked", { subscriber_id: subscriberId });
+    }
+  }
+  setupDataAttributeTracking() {
+    if (typeof document === "undefined") return;
+    document.addEventListener("click", (e) => {
+      const target = e.target;
+      const tracked = target.closest("[data-smp-track]");
+      if (tracked) {
+        const eventName = tracked.getAttribute("data-smp-track");
+        const properties = {};
+        Array.from(tracked.attributes).forEach((attr) => {
+          if (attr.name.startsWith("data-smp-track-") && attr.name !== "data-smp-track") {
+            const propName = attr.name.replace("data-smp-track-", "").replace(/-/g, "_");
+            properties[propName] = attr.value;
+          }
+        });
+        if (eventName) {
+          this.track(eventName, properties);
+        }
+      }
+    });
+  }
+  getStoredEmail() {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage.getItem(IDENTIFIED_EMAIL_KEY);
+  }
+  storeEmail(email) {
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem(IDENTIFIED_EMAIL_KEY, email);
+    }
+  }
+  isValidEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+  }
+};
+var Pixel = SendmailPixel;
+function createGlobalPixel(config) {
+  const pixel = new SendmailPixel(config);
+  if (typeof window !== "undefined") {
+    const smpFunction = (method, ...args) => {
+      switch (method) {
+        case "track":
+          pixel.track(args[0], args[1]);
+          return void 0;
+        case "identify":
+          pixel.identify(args[0], args[1]);
+          return void 0;
+        case "page":
+          pixel.pageView();
+          return void 0;
+        case "optOut":
+          pixel.optOut();
+          return void 0;
+        case "optIn":
+          pixel.optIn();
+          return void 0;
+        case "isOptedOut":
+          return pixel.isOptedOut();
+        case "reset":
+          pixel.reset();
+          return void 0;
+        default:
+          console.warn(`[SendmailPixel] Unknown method: ${method}`);
+          return void 0;
+      }
+    };
+    window.smp = smpFunction;
+  }
+  pixel.init();
+  return pixel;
+}
+
 // src/utils/webhook.ts
 function verifyWebhookSignature(params) {
   const { payload, signature, timestamp, secret, tolerance = 300 } = params;
@@ -526,11 +902,14 @@ function constructWebhookEvent(payload, headers, secret) {
 
 exports.AuthenticationError = AuthenticationError;
 exports.NotFoundError = NotFoundError;
+exports.Pixel = Pixel;
 exports.RateLimitError = RateLimitError;
 exports.SendMailOS = SendMailOS;
 exports.SendMailOSError = SendMailOSError;
+exports.SendmailPixel = SendmailPixel;
 exports.ValidationError = ValidationError;
 exports.constructWebhookEvent = constructWebhookEvent;
+exports.createGlobalPixel = createGlobalPixel;
 exports.default = SendMailOS;
 exports.verifyWebhookSignature = verifyWebhookSignature;
 exports.verifyWebhookSignatureAsync = verifyWebhookSignatureAsync;