saasco-sdk 0.1.44 → 0.2.3

package/src/index.d.ts

@@ -1,5 +0,0 @@
-export * from './lib/analytics';
-export * from './lib/getBrowserContext';
-export * from './lib/tracking';
-export * from './lib/timezones';
-export * from './lib/integrations';

package/src/lib/analytics.d.ts

@@ -1,134 +0,0 @@
-import { FacebookPixelIntegrationConfig } from './integrations/facebook-pixel';
-import { PinterestTagIntegrationConfig } from './integrations/pinterest-tag';
-import { TikTokPixelIntegrationConfig } from './integrations/tiktok-pixel';
-declare global {
-    interface Window {
-        saascoAutoPageTrackingActive?: boolean;
-        saasco: Saasco;
-    }
-}
-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;
-};
-export type IntegrationConfigBase = {
-    type: string;
-    config: Record<string, any>;
-    debug?: boolean;
-};
-export type IntegrationsConfig = (FacebookPixelIntegrationConfig | PinterestTagIntegrationConfig | TikTokPixelIntegrationConfig)[];
-export declare class Saasco {
-    private config;
-    private lastPageViewPath;
-    private isInitialized;
-    private integrationManager;
-    private logger;
-    /**
-     * Creates an instance of 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;
-    });
-    init(): void;
-    disableDebug(): void;
-    enableDebug(): 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 Saasco API
-     * If you have a proxy set up, it will send the data to the proxy and you can handle forawrding the data to the Saasco events API
-     * @param path
-     * @param data
-     */
-    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
-     */
-    private initAutoPageTracking;
-    getIntegrationsStats(): {
-        currentEnvironment: import("./integrations/integration-manager").IntegrationEnvironment;
-        integrations: {
-            name: string;
-            status: import("./integrations/integration-manager").IntegrationStatus;
-            environments: import("./integrations/integration-manager").IntegrationEnvironment[];
-        }[];
-        queueLength: number;
-        readyCount: number;
-        periodicFlushEnabled: boolean;
-        flushInterval: number;
-        context: import("./integrations/integration-manager").AnalyticsContext;
-    };
-}
-export {};

package/src/lib/getBrowserContext.d.ts

@@ -1,2 +0,0 @@
-import { BrowserContext } from './tracking';
-export declare function getBrowserContext(): BrowserContext;

package/src/lib/integrations/facebook-pixel.d.ts

@@ -1,34 +0,0 @@
-import { IntegrationConfigBase } from '../analytics';
-import { Integration } from './integration-manager';
-declare global {
-    interface Window {
-        fbq?: Fbq;
-        _fbq?: Fbq;
-    }
-    interface Fbq {
-        (...args: any[]): void;
-        queue?: any[];
-        loaded?: boolean;
-        version?: string;
-        disablePushState?: boolean;
-        allowDuplicatePageViews?: boolean;
-    }
-}
-export type FacebookEventMapping = {
-    [key: string]: StandardFacebookEvent;
-};
-export type FacebookPixelIntegrationConfig = IntegrationConfigBase & {
-    type: 'facebook-pixel';
-    config: FacebookPixelConfig;
-};
-export type FacebookPixelConfig = {
-    pixelId: string;
-    eventMapping?: FacebookEventMapping;
-    automaticConfiguration?: boolean;
-};
-export declare const standardFacebookEvents: readonly ["AddPaymentInfo", "AddToCart", "AddToWishlist", "CompleteRegistration", "Contact", "CustomizeProduct", "Donate", "FindLocation", "InitiateCheckout", "Lead", "Purchase", "Schedule", "Search", "StartTrial", "SubmitApplication", "Subscribe", "ViewContent", "PageView"];
-export type StandardFacebookEvent = (typeof standardFacebookEvents)[number];
-/**
- * Create a Facebook Pixel integration instance
- */
-export declare function createFacebookPixelIntegration(config: FacebookPixelConfig, debug?: boolean): Integration;

package/src/lib/integrations/index.d.ts

@@ -1,4 +0,0 @@
-export * from './integration-manager';
-export * from './facebook-pixel';
-export * from './pinterest-tag';
-export * from './tiktok-pixel';

package/src/lib/integrations/integration-manager.d.ts

@@ -1,119 +0,0 @@
-import { LogLevel } from '../utils';
-export type EventType = 'identify' | 'track';
-export type AnalyticsContext = {
-    distinctId?: string | null;
-    anonymousId?: string | null;
-    sessionId?: string | null;
-    [key: string]: unknown;
-};
-export type EventEnvelope = {
-    id: string;
-    type: EventType;
-    timestamp: number;
-    name?: string;
-    properties?: Record<string, unknown>;
-    context: AnalyticsContext;
-};
-export type IntegrationEnvironment = 'client' | 'server';
-export 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>;
-};
-export type IntegrationStatus = 'idle' | 'loading' | 'ready' | 'error';
-export type IntegrationState = {
-    integration: Integration;
-    status: IntegrationStatus;
-};
-export 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;
-};
-export 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(): {
-        currentEnvironment: IntegrationEnvironment;
-        integrations: {
-            name: string;
-            status: IntegrationStatus;
-            environments: IntegrationEnvironment[];
-        }[];
-        queueLength: number;
-        readyCount: number;
-        periodicFlushEnabled: boolean;
-        flushInterval: number;
-        context: AnalyticsContext;
-    };
-}

package/src/lib/integrations/pinterest-tag.d.ts

@@ -1,37 +0,0 @@
-import { IntegrationConfigBase } from '../analytics';
-import { Integration } from './integration-manager';
-declare global {
-    interface Window {
-        pintrk?: Pintrk;
-        _pintrk?: Pintrk;
-    }
-    interface Pintrk {
-        (...args: any[]): void;
-        queue?: any[];
-        loaded?: boolean;
-        version?: string;
-    }
-}
-export type PinterestEventMapping = {
-    [key: string]: StandardPinterestEvent;
-};
-export type PinterestTagIntegrationConfig = IntegrationConfigBase & {
-    type: 'pinterest-tag';
-    config: PinterestTagConfig;
-};
-export type PinterestTagConfig = {
-    tagId: string;
-    eventMapping?: PinterestEventMapping;
-    automaticConfiguration?: boolean;
-};
-/**
- * Standard Pinterest events
- * Reference: https://www.pinterest.com/_/_/help/business/article/event-code
- */
-export declare const standardPinterestEvents: readonly ["checkout", "addtocart", "pagevisit", "signup", "watchvideo", "lead", "search", "viewcategory", "custom", "addpaymentinfo", "addtowishlist", "initiatecheckout", "subscribe", "viewcontent"];
-export type StandardPinterestEvent = (typeof standardPinterestEvents)[number];
-/**
- * Create a Pinterest Tag integration instance
- * Documentation: https://help.pinterest.com/en/business/article/install-the-pinterest-tag
- */
-export declare function createPinterestTagIntegration(config: PinterestTagConfig, debug?: boolean): Integration;

package/src/lib/integrations/tiktok-pixel.d.ts

@@ -1,59 +0,0 @@
-/**
- * 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
- */
-import { IntegrationConfigBase } from '../analytics';
-import { Integration } from './integration-manager';
-declare global {
-    interface Window {
-        ttq?: Ttq;
-        TiktokAnalyticsObject?: string;
-    }
-    interface Ttq {
-        (...args: any[]): void;
-        methods?: string[];
-        _i?: Record<string, any>;
-        _t?: Record<string, number>;
-        _o?: Record<string, any>;
-        load?: (pixelId: string, options?: any) => void;
-        page?: () => void;
-        track?: (eventName: string, properties?: Record<string, unknown>) => void;
-        identify?: (properties?: Record<string, unknown>) => void;
-        setAndDefer?: (obj: any, method: string) => void;
-        instance?: (pixelId: string) => any;
-    }
-}
-export type TikTokEventMapping = {
-    [key: string]: StandardTikTokEvent;
-};
-export type TikTokPixelIntegrationConfig = IntegrationConfigBase & {
-    type: 'tiktok-pixel';
-    config: TikTokPixelConfig;
-};
-export 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
- */
-export declare const standardTikTokEvents: readonly ["AddPaymentInfo", "AddToCart", "AddToWishlist", "ApplicationApproval", "CompleteRegistration", "Contact", "CustomizeProduct", "Download", "FindLocation", "InitiateCheckout", "Lead", "Purchase", "Schedule", "Search", "StartTrial", "SubmitApplication", "Subscribe", "ViewContent", "PageView"];
-export type StandardTikTokEvent = (typeof standardTikTokEvents)[number];
-/**
- * Create a TikTok Pixel integration instance
- */
-export declare function createTikTokPixelIntegration(config: TikTokPixelConfig, debug?: boolean): Integration;

package/src/lib/self-execute-analytics.d.ts

@@ -1,6 +0,0 @@
-import { Saasco } from './analytics';
-declare global {
-    interface Window {
-        saasco: Saasco;
-    }
-}

package/src/lib/timezones.d.ts

@@ -1,3 +0,0 @@
-export declare const timezones: {
-    [key: string]: string;
-};

package/src/lib/tracking/index.d.ts

@@ -1 +0,0 @@
-export * from './types';

package/src/lib/tracking/types.d.ts

@@ -1,73 +0,0 @@
-import { z } from 'zod';
-export declare const browserContextSchema: z.ZodObject<{
-    $locale: z.ZodString;
-    $location: z.ZodString;
-    $href: z.ZodString;
-    $pathname: z.ZodString;
-    $referrer: z.ZodString;
-    $screenDPI: z.ZodNumber;
-    $screenHeight: z.ZodNumber;
-    $screenWidth: z.ZodNumber;
-    $title: z.ZodString;
-    $userAgent: z.ZodString;
-    $utmSource: z.ZodNullable<z.ZodString>;
-    $utmMedium: z.ZodNullable<z.ZodString>;
-    $utmCampaign: z.ZodNullable<z.ZodString>;
-    $utmTerm: z.ZodNullable<z.ZodString>;
-    $utmContent: z.ZodNullable<z.ZodString>;
-    $utmId: z.ZodNullable<z.ZodString>;
-    $utmSourcePlatform: z.ZodNullable<z.ZodString>;
-    $utmCampaignId: z.ZodNullable<z.ZodString>;
-    $utmCreativeFormat: z.ZodNullable<z.ZodString>;
-    $utmMarketingTactic: z.ZodNullable<z.ZodString>;
-    $utmAdSource: z.ZodNullable<z.ZodString>;
-    $utmAdId: z.ZodNullable<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    $locale: string;
-    $location: string;
-    $href: string;
-    $pathname: string;
-    $referrer: string;
-    $screenDPI: number;
-    $screenHeight: number;
-    $screenWidth: number;
-    $title: string;
-    $userAgent: string;
-    $utmSource: string | null;
-    $utmMedium: string | null;
-    $utmCampaign: string | null;
-    $utmTerm: string | null;
-    $utmContent: string | null;
-    $utmId: string | null;
-    $utmSourcePlatform: string | null;
-    $utmCampaignId: string | null;
-    $utmCreativeFormat: string | null;
-    $utmMarketingTactic: string | null;
-    $utmAdSource: string | null;
-    $utmAdId: string | null;
-}, {
-    $locale: string;
-    $location: string;
-    $href: string;
-    $pathname: string;
-    $referrer: string;
-    $screenDPI: number;
-    $screenHeight: number;
-    $screenWidth: number;
-    $title: string;
-    $userAgent: string;
-    $utmSource: string | null;
-    $utmMedium: string | null;
-    $utmCampaign: string | null;
-    $utmTerm: string | null;
-    $utmContent: string | null;
-    $utmId: string | null;
-    $utmSourcePlatform: string | null;
-    $utmCampaignId: string | null;
-    $utmCreativeFormat: string | null;
-    $utmMarketingTactic: string | null;
-    $utmAdSource: string | null;
-    $utmAdId: string | null;
-}>;
-export type BrowserContext = z.infer<typeof browserContextSchema>;
-export type SuperContext = Record<string, any>;

package/src/lib/utils/getIntegrationLoggerLevel.d.ts

@@ -1,8 +0,0 @@
-import { LogLevel } from './logger';
-export declare const isServer: boolean;
-/**
- * Get the logger level for a specific integration
- * Supports URL parameters like saasco-debug-{integration-type}=true
- * If debug is true or URL param is true, sets level to DEBUG (3), otherwise WARN
- */
-export declare function getIntegrationLoggerLevel(integrationName: string, debug?: boolean): LogLevel;

package/src/lib/utils/index.d.ts

@@ -1,3 +0,0 @@
-export * from './logger';
-export * from './getIntegrationLoggerLevel';
-export * from './uuid';

package/src/lib/utils/logger.d.ts

@@ -1,30 +0,0 @@
-export declare enum LogLevel {
-    ERROR = 0,
-    WARN = 1,
-    INFO = 2,
-    DEBUG = 3
-}
-export type AnalyticsLoggerConfig = {
-    level: LogLevel;
-    label: string;
-};
-export declare class AnalyticsLogger {
-    private config;
-    constructor(config: AnalyticsLoggerConfig);
-    debug(...args: any[]): void;
-    /**
-     * Log debug information
-     */
-    info(...args: any[]): void;
-    /**
-     * Log warning information
-     */
-    warn(...args: any[]): void;
-    /**
-     * Log error information
-     */
-    error(...args: any[]): {
-        success: boolean;
-        message: string;
-    };
-}

package/src/lib/utils/uuid.d.ts

@@ -1,5 +0,0 @@
-/**
- * Generate a collision-resistant UUID
- * Uses lukeed's UUID v4 implementation for consistent, fast UUID generation
- */
-export declare function uuid(): string;