saasco-sdk 0.1.45 → 0.2.4

package/dist/index.d.cts

@@ -0,0 +1,535 @@
+import { z } from 'zod';
+
+declare enum LogLevel {
+    ERROR = 0,
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3
+}
+
+type EventType = "identify" | "track";
+type AnalyticsContext = {
+    distinctId?: string | null;
+    anonymousId?: string | null;
+    sessionId?: string | null;
+    [key: string]: unknown;
+};
+type EventEnvelope = {
+    id: string;
+    type: EventType;
+    timestamp: number;
+    name?: string;
+    properties?: Record<string, unknown>;
+    context: AnalyticsContext;
+};
+type IntegrationEnvironment = "client" | "server";
+type Integration = {
+    /**
+     * The name of the integration
+     */
+    name: string;
+    /**
+     * The environments where this integration can run
+     */
+    environments: IntegrationEnvironment[];
+    /**
+     * The function to initialize the integration
+     */
+    init?: (context?: AnalyticsContext) => Promise<void> | void;
+    /**
+     * The function to track an event
+     */
+    track?: (name: string, properties?: Record<string, unknown>, context?: AnalyticsContext) => void;
+    /**
+     * The function to identify a user
+     */
+    identify?: (userId?: string | null, properties?: Record<string, unknown>, context?: AnalyticsContext) => void | Promise<void>;
+};
+type IntegrationStatus = "idle" | "loading" | "ready" | "error";
+type IntegrationState = {
+    integration: Integration;
+    status: IntegrationStatus;
+};
+type ManagerConfig = {
+    /**
+     * Enable logger level
+     */
+    loggerLevel?: LogLevel;
+    /**
+     * Max queue size, once it exceeds this number, the oldest event will be dropped
+     */
+    maxQueueSize?: number;
+    /**
+     * Max integration wait time, this is how long we will wait for an integration to be ready before flushing the queue. If an integration is not ready after this time it will miss any previous events.
+     */
+    maxIntegrationWaitTime?: number;
+    /**
+     * Periodic flush interval in milliseconds. Set to 0 to disable periodic flushing.
+     */
+    flushInterval?: number;
+};
+declare class IntegrationManager {
+    private context;
+    private integrations;
+    private globalQueue;
+    private config;
+    private logger;
+    private initTime;
+    private currentEnvironment;
+    private flushTimer?;
+    private unloadHandler?;
+    constructor(config?: ManagerConfig);
+    /**
+     * Shallow-merge context to keep it simple + predictable in v0
+     */
+    setContext(next: Partial<AnalyticsContext>): void;
+    /**
+     * Register and init an integration. When init resolves, we mark it ready and
+     * immediately flush any queued events in FIFO order to *all* ready integrations.
+     */
+    registerIntegration(integration: Integration): Promise<void>;
+    identify(userId?: string | null, traits?: Record<string, unknown>): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Core send path: if at least one integration is ready -> deliver immediately
+     * Else enqueue (bounded FIFO)
+     */
+    private send;
+    private deliver;
+    /**
+     * Flush queued events FIFO once at least one integration is ready.
+     */
+    private flush;
+    private readyCount;
+    private isReady;
+    /**
+     * Setup periodic flushing if enabled
+     */
+    private setupPeriodicFlushing;
+    /**
+     * Setup page unload handler for client environment
+     */
+    private setupUnloadHandler;
+    /** Debug helpers */
+    getStats(): {
+        context: AnalyticsContext;
+        currentEnvironment: IntegrationEnvironment;
+        flushInterval: number;
+        integrations: {
+            environments: IntegrationEnvironment[];
+            name: string;
+            status: IntegrationStatus;
+        }[];
+        periodicFlushEnabled: boolean;
+        queueLength: number;
+        readyCount: number;
+    };
+}
+
+type IntegrationConfigBase = {
+    type: string;
+    config: Record<string, any>;
+    debug?: boolean;
+};
+
+declare global {
+    interface Window {
+        fbq?: Fbq;
+        _fbq?: Fbq;
+    }
+    interface Fbq {
+        (...args: unknown[]): void;
+        queue?: unknown[];
+        loaded?: boolean;
+        version?: string;
+        disablePushState?: boolean;
+        allowDuplicatePageViews?: boolean;
+    }
+}
+type FacebookEventMapping = Record<string, StandardFacebookEvent>;
+type FacebookPixelIntegrationConfig = IntegrationConfigBase & {
+    type: "facebook-pixel";
+    config: FacebookPixelConfig;
+};
+type FacebookPixelConfig = {
+    pixelId: string;
+    eventMapping?: FacebookEventMapping;
+    automaticConfiguration?: boolean;
+};
+declare const standardFacebookEvents: readonly ["AddPaymentInfo", "AddToCart", "AddToWishlist", "CompleteRegistration", "Contact", "CustomizeProduct", "Donate", "FindLocation", "InitiateCheckout", "Lead", "Purchase", "Schedule", "Search", "StartTrial", "SubmitApplication", "Subscribe", "ViewContent", "PageView"];
+type StandardFacebookEvent = (typeof standardFacebookEvents)[number];
+/**
+ * Create a Facebook Pixel integration instance
+ */
+declare function createFacebookPixelIntegration(config: FacebookPixelConfig, debug?: boolean): Integration;
+
+declare global {
+    interface Window {
+        pintrk?: Pintrk;
+        _pintrk?: Pintrk;
+    }
+    interface Pintrk {
+        (...args: unknown[]): void;
+        queue?: unknown[];
+        loaded?: boolean;
+        version?: string;
+    }
+}
+type PinterestEventMapping = Record<string, StandardPinterestEvent>;
+type PinterestTagIntegrationConfig = IntegrationConfigBase & {
+    type: "pinterest-tag";
+    config: PinterestTagConfig;
+};
+type PinterestTagConfig = {
+    tagId: string;
+    eventMapping?: PinterestEventMapping;
+    automaticConfiguration?: boolean;
+};
+/**
+ * Standard Pinterest events
+ * Reference: https://www.pinterest.com/_/_/help/business/article/event-code
+ */
+declare const standardPinterestEvents: readonly ["checkout", "addtocart", "pagevisit", "signup", "watchvideo", "lead", "search", "viewcategory", "custom", "addpaymentinfo", "addtowishlist", "initiatecheckout", "subscribe", "viewcontent"];
+type StandardPinterestEvent = (typeof standardPinterestEvents)[number];
+/**
+ * Create a Pinterest Tag integration instance
+ * Documentation: https://help.pinterest.com/en/business/article/install-the-pinterest-tag
+ */
+declare function createPinterestTagIntegration(config: PinterestTagConfig, debug?: boolean): Integration;
+
+/**
+ * TikTok Pixel Integration
+ *
+ * This integration provides TikTok Pixel tracking capabilities including:
+ * - Event tracking for standard and custom events
+ * - Advanced matching with hashed user identification data
+ * - Automatic script loading and initialization
+ *
+ * Key Resources:
+ * - Advanced Matching: https://business-api.tiktok.com/portal/docs?rid=5ipocbxyw8v&id=1739585700402178
+ * - Standard Events: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+
+declare global {
+    interface Window {
+        ttq?: Ttq;
+        TiktokAnalyticsObject?: string;
+    }
+    interface Ttq {
+        (...args: unknown[]): void;
+        methods?: string[];
+        _i?: Record<string, unknown>;
+        _t?: Record<string, number>;
+        _o?: Record<string, unknown>;
+        load?: (pixelId: string, options?: Record<string, unknown>) => void;
+        page?: () => void;
+        track?: (eventName: string, properties?: Record<string, unknown>) => void;
+        identify?: (properties?: Record<string, unknown>) => void;
+        setAndDefer?: (obj: Record<string, unknown>, method: string) => void;
+        instance?: (pixelId: string) => Ttq;
+    }
+}
+type TikTokEventMapping = Record<string, StandardTikTokEvent>;
+type TikTokPixelIntegrationConfig = IntegrationConfigBase & {
+    type: "tiktok-pixel";
+    config: TikTokPixelConfig;
+};
+type TikTokPixelConfig = {
+    pixelId: string;
+    eventMapping?: TikTokEventMapping;
+    testMode?: boolean;
+};
+/**
+ * Standard TikTok events supported by the pixel
+ *
+ * Note: This list reflects TikTok's official standard events. Events like 'CompletePayment'
+ * are not standard events and should be tracked as custom events if needed.
+ *
+ * Documentation: https://business-api.tiktok.com/portal/docs?id=1771101186666498
+ */
+declare const standardTikTokEvents: readonly ["AddPaymentInfo", "AddToCart", "AddToWishlist", "ApplicationApproval", "CompleteRegistration", "Contact", "CustomizeProduct", "Download", "FindLocation", "InitiateCheckout", "Lead", "Purchase", "Schedule", "Search", "StartTrial", "SubmitApplication", "Subscribe", "ViewContent", "PageView"];
+type StandardTikTokEvent = (typeof standardTikTokEvents)[number];
+/**
+ * Create a TikTok Pixel integration instance
+ */
+declare function createTikTokPixelIntegration(config: TikTokPixelConfig, debug?: boolean): Integration;
+
+declare global {
+    interface Window {
+        saascoAutoPageTrackingActive?: boolean;
+        saasco: Saasco;
+        saascoLastIdentifyKey?: string;
+        /** Set once the lazy-loaded support script has been injected. */
+        __saascoSupportInjected?: boolean;
+        /** Set once the lazy-loaded social-proof loader script has been injected. */
+        __saascoSocialProofInjected?: boolean;
+    }
+}
+type Identity = {
+    userId: string | number;
+    anonymousId?: string | number;
+} | {
+    anonymousId: string | number;
+    userId?: string | number;
+};
+type Context = {
+    active?: boolean;
+};
+type TrackPayload = Identity & {
+    event: string;
+    sessionId?: string;
+    properties?: Record<string, any>;
+    context?: Context;
+};
+type DoRequestResponse = {
+    success: boolean;
+    message: string;
+};
+type IntegrationsConfig = (FacebookPixelIntegrationConfig | PinterestTagIntegrationConfig | TikTokPixelIntegrationConfig)[];
+/**
+ * Opt-in config for the support widget, set on the `Saasco` constructor.
+ * The widget is a cross-origin iframe loaded by a lean host-page loader
+ * (`saasco-support-loader.js`); no React ships in this analytics entry,
+ * which stays React-free by lazily injecting the loader rather than importing
+ * it. Providing this object opts in; pass `enabled: false` to keep it off (e.g.
+ * behind your own runtime flag). The projectId is shared from the analytics
+ * config — you never declare it twice.
+ */
+type SupportInit = {
+    /** Defaults to `true` when the `support` object is provided. */
+    enabled?: boolean;
+    /** Origin of the saasco app hosting the support API. Defaults server-side to where the widget bundle is served from. */
+    baseUrl?: string;
+    /** Input placeholder for the chat composer. */
+    placeholder?: string;
+    /**
+     * URL the loader is loaded from. Accepts either the analytics
+     * `saasco-sdk.js` URL (the loader URL is derived from it) or the
+     * `saasco-support-loader.js` URL directly. Defaults to deriving from the
+     * loaded analytics `<script>` tag, so CDN installs can omit it.
+     */
+    scriptUrl?: string;
+};
+/**
+ * Optional config for the Social Proof widget. Social proof is **always
+ * available wherever the analytics SDK runs** — you don't need to pass this
+ * object at all. Whether the widget actually renders is decided
+ * **server-side**: on init the SDK runs a cheap widget-payload check and lazily
+ * injects the dependency-free loader (`saasco-social-proof-loader.js`, ~71 KB
+ * gzipped) only when the project has the app enabled in the dashboard, so
+ * pages where it's off never download it — and the dashboard toggle controls
+ * every install (CDN and npm) uniformly.
+ *
+ * The loader + widget-payload origin is resolved automatically: the CDN
+ * `<script>` origin for CDN installs, else the public Saasco CDN for
+ * npm/bundled installs (which carry no script tag on the page). Pass this object
+ * only to override those defaults or to opt out: `enabled: false` (or
+ * `data-social-proof-enabled="false"` on the CDN tag) is a client kill-switch
+ * that skips the check entirely; `baseUrl`/`scriptUrl` point a same-origin,
+ * proxied, or self-hosted install at the right origin. The projectId is shared
+ * from the analytics config — you never declare it twice.
+ */
+type SocialProofInit = {
+    /**
+     * Client kill-switch. Defaults to `true`. When `false`, the SDK skips the
+     * server check and never injects the loader, regardless of the dashboard
+     * setting.
+     */
+    enabled?: boolean;
+    /**
+     * Origin of the saasco app hosting the social-proof widget-payload API.
+     * Defaults to the loader bundle's origin — the CDN `<script>` origin for CDN
+     * installs, else the public Saasco CDN for npm/bundled installs.
+     */
+    baseUrl?: string;
+    /**
+     * URL the loader is loaded from. Accepts either the analytics
+     * `saasco-sdk.js` URL (the loader URL is derived from it) or the
+     * `saasco-social-proof-loader.js` URL directly. Defaults to deriving from
+     * the loaded analytics `<script>` tag, so CDN installs can omit it.
+     */
+    scriptUrl?: string;
+};
+declare class Saasco {
+    private config;
+    private lastPageViewPath;
+    private isInitialized;
+    private integrationManager;
+    private logger;
+    private lastSupportIdentity;
+    /**
+     * Creates an instance of the Saasco SDK.
+     * @param config Configuration options.
+     * @param config.projectId The unique identifier for the project.
+     * @param config.proxy The URL of the proxy server to use, if any.
+     * @param config.autoPageTracking Whether to automatically track page views. Default is false.
+     * @param config.enabled Whether analytics is enabled. Default is true. Set to false for development and staging envioronments. Will still allow debug mode to be true, just no events will be sent
+     * @param config.debug Whether to log debug information. Default is false.
+     * @param config.trackUrlParams Whether to track URL parameters. Default is true.
+     * @param config.trackHashChanges Whether to track hash changes. Default is true.
+     * @param config.integrations Configuration for third-party integrations like Facebook Pixel.
+     */
+    constructor(config: {
+        projectId: string;
+        proxy?: string;
+        autoPageTracking?: {
+            enabled: boolean;
+            trackQueryParams?: boolean;
+            trackHash?: boolean;
+        };
+        enabled?: boolean;
+        debug?: boolean;
+        debugVerbose?: boolean;
+        integrations?: IntegrationsConfig;
+        support?: SupportInit;
+        socialProof?: SocialProofInit;
+    });
+    init(): void;
+    disableDebug(): void;
+    enableDebug(): void;
+    /**
+     * Enables and injects the support widget when it was constructed with
+     * `support: { enabled: false }`. Safe to call multiple times.
+     */
+    enableSupport(): void;
+    /**
+     * Enables and injects the social-proof widget (e.g. after constructing with
+     * `socialProof: { enabled: false }`, or when no `socialProof` block was
+     * passed). Injection still runs the server check, so the loader only
+     * downloads when the project has the app enabled in the dashboard.
+     * Safe to call multiple times — the loader injection is guarded against
+     * double-injection.
+     */
+    enableSocialProof(): void;
+    /**
+     * Initialize third-party integrations
+     */
+    private initIntegrations;
+    /**
+     * Track events with support for both client (Segment-style) and server (object-style) usage
+     * Client: track('User Signed Up', { plan: 'Pro' }, { source: 'client' })
+     * Server: track({ event: 'User Signed Up', userId: 'user_123', properties: { plan: 'Pro' } })
+     */
+    track(action: string, properties?: Record<string, any>, context?: Context): Promise<DoRequestResponse>;
+    track(payload: TrackPayload): Promise<DoRequestResponse>;
+    /**
+     * The page method lets you record page views on your website
+     * This records the page title and path and names the event useing the reserved property "Page Viewed"
+     *
+     * Before implementing this make sure you have disabled the autoPageTracking in the config or you will get duplicate page views
+     */
+    page(): Promise<DoRequestResponse> | undefined;
+    /**
+     * The identify method lets you tie a user to their actions and record traits about them.
+     * We recommend you call this when the user logs in and when any traits get updated.
+     * You can also identify a user as null when they logout to clear the user
+     *
+     * @param distinctId The user's id. This should be the user id from your database. This is optional and can be skipped, but you must provide an email address on the user properties.
+     * @param properties A dictionary of traits you know about the user like their email, name, plan etc.
+     * @param context Context for the identify call such as whether the user is active.
+     */
+    identify(properties: Record<string, any>, context?: Context): Promise<DoRequestResponse>;
+    identify(distinctId: string | number | null, properties?: Record<string, any>, context?: Context): Promise<DoRequestResponse>;
+    /**
+     * This should only be called when the user logs out
+     * It will reset the session, anonymous id, and user id
+     *
+     * All events after calling reset will be tracked as a new user
+     *
+     */
+    logout(): void;
+    /**
+     * Handles sending data to the Analytics API
+     * If you have a proxy set up, it will send the data to the proxy and you can handle forwarding the data to the Analytics events API
+     * @param path - API path relative to the analytics base URL
+     * @param data - Request payload to send
+     */
+    private doRequest;
+    /**
+     * If autoPageTracking is enabled, this will automatically track page views
+     * It listens to url changes to track new pages every time the url changes
+     * @returns void
+     */
+    private initAutoPageTracking;
+    getIntegrationsStats(): {
+        context: AnalyticsContext;
+        currentEnvironment: IntegrationEnvironment;
+        flushInterval: number;
+        integrations: {
+            environments: IntegrationEnvironment[];
+            name: string;
+            status: IntegrationStatus;
+        }[];
+        periodicFlushEnabled: boolean;
+        queueLength: number;
+        readyCount: number;
+    };
+    /**
+     * Lazily injects the support **loader** from the same `/sdk/` origin as
+     * the analytics bundle, forwarding the shared `projectId` and the widget
+     * config as `data-*` attributes. The loader (no React) injects the
+     * cross-origin embed iframe. Deferred (`async`) and guarded against
+     * double-injection so re-running `init()` is a no-op.
+     */
+    private injectSupport;
+    /**
+     * Lazily injects the social-proof loader (server-gated). See
+     * {@link injectSocialProofLoader}.
+     */
+    private injectSocialProof;
+    /**
+     * Records the latest CRM identity and forwards it to the support widget.
+     * No-op when support isn't enabled.
+     */
+    private updateSupportIdentity;
+    /**
+     * Pushes the current identity onto `window.SaascoSupport.identify`. The
+     * widget bundle publishes that global asynchronously, so this short-polls for
+     * it (same approach as tool registration); the load handler also calls this,
+     * so a fresh page load with a stored distinctId still identifies the chat.
+     */
+    private pushSupportIdentity;
+}
+
+/**
+ * Browser-collected context attached to track payloads by `getBrowserContext()`.
+ *
+ * Defined here rather than in `libs/analytics/sdk` because server and worker
+ * code validates it too. The SDK re-exports it, so `saasco-sdk`'s public API is
+ * unchanged — but a shared module importing the SDK barrel would drag the whole
+ * DOM-dependent bundle into every consumer's program, including the Cloudflare
+ * Worker, which has no DOM lib.
+ */
+declare const BrowserContextSchema: z.ZodObject<{
+    $href: z.ZodString;
+    $locale: z.ZodString;
+    $location: z.ZodString;
+    $pathname: z.ZodString;
+    $referrer: z.ZodString;
+    $referringDomain: z.ZodString;
+    $screenDPI: z.ZodNumber;
+    $screenHeight: z.ZodNumber;
+    $screenWidth: z.ZodNumber;
+    $title: z.ZodString;
+    $userAgent: z.ZodString;
+    $utmAdId: z.ZodNullable<z.ZodString>;
+    $utmAdSource: z.ZodNullable<z.ZodString>;
+    $utmCampaign: z.ZodNullable<z.ZodString>;
+    $utmCampaignId: z.ZodNullable<z.ZodString>;
+    $utmContent: z.ZodNullable<z.ZodString>;
+    $utmCreativeFormat: z.ZodNullable<z.ZodString>;
+    $utmId: z.ZodNullable<z.ZodString>;
+    $utmMarketingTactic: z.ZodNullable<z.ZodString>;
+    $utmMedium: z.ZodNullable<z.ZodString>;
+    $utmSource: z.ZodNullable<z.ZodString>;
+    $utmSourcePlatform: z.ZodNullable<z.ZodString>;
+    $utmTerm: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type BrowserContext = z.infer<typeof BrowserContextSchema>;
+type SuperContext = Record<string, unknown>;
+
+declare function getBrowserContext(): BrowserContext;
+
+declare const timezones: Record<string, string>;
+
+export { type AnalyticsContext, type BrowserContext, BrowserContextSchema, type EventEnvelope, type EventType, type FacebookEventMapping, type FacebookPixelConfig, type FacebookPixelIntegrationConfig, type Integration, type IntegrationConfigBase, type IntegrationEnvironment, IntegrationManager, type IntegrationState, type IntegrationStatus, type IntegrationsConfig, type ManagerConfig, type PinterestEventMapping, type PinterestTagConfig, type PinterestTagIntegrationConfig, Saasco, type SocialProofInit, type StandardFacebookEvent, type StandardPinterestEvent, type StandardTikTokEvent, type SuperContext, type SupportInit, type TikTokEventMapping, type TikTokPixelConfig, type TikTokPixelIntegrationConfig, createFacebookPixelIntegration, createPinterestTagIntegration, createTikTokPixelIntegration, getBrowserContext, standardFacebookEvents, standardPinterestEvents, standardTikTokEvents, timezones };