saasco-sdk 0.2.4 → 0.2.6

package/dist/index.d.cts

@@ -39,7 +39,7 @@ type Integration = {
     /**
      * The function to track an event
      */
-    track?: (name: string, properties?: Record<string, unknown>, context?: AnalyticsContext) => void;
+    track?: (name: string, properties?: Record<string, unknown>, context?: AnalyticsContext) => void | Promise<void>;
     /**
      * The function to identify a user
      */
@@ -51,6 +51,7 @@ type IntegrationState = {
     status: IntegrationStatus;
 };
 type ManagerConfig = {
+    deduplicationNamespace?: string;
     /**
      * Enable logger level
      */
@@ -60,7 +61,7 @@ type ManagerConfig = {
      */
     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.
+     * Max integration wait time, this is how long we will wait for an integration to be ready before flushing the queue. Unsent events expire after this time without consuming their delivery guard, so an explicit retry or page refresh can retry them.
      */
     maxIntegrationWaitTime?: number;
     /**
@@ -74,7 +75,6 @@ declare class IntegrationManager {
     private globalQueue;
     private config;
     private logger;
-    private initTime;
     private currentEnvironment;
     private flushTimer?;
     private unloadHandler?;
@@ -96,12 +96,10 @@ declare class IntegrationManager {
      */
     private send;
     private deliver;
-    /**
-     * Flush queued events FIFO once at least one integration is ready.
-     */
+    /** Each ready destination drains its own copy; a slow/blocked pixel cannot
+     * discard another pixel's queued events or hold up the ready destinations. */
     private flush;
     private readyCount;
-    private isReady;
     /**
      * Setup periodic flushing if enabled
      */
@@ -139,6 +137,8 @@ declare global {
     }
     interface Fbq {
         (...args: unknown[]): void;
+        callMethod?: (...args: unknown[]) => void;
+        push?: (...args: unknown[]) => void;
         queue?: unknown[];
         loaded?: boolean;
         version?: string;
@@ -217,13 +217,16 @@ declare global {
     }
     interface Ttq {
         (...args: unknown[]): void;
+        ready?: (callback: () => void) => 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;
+        track?: (eventName: string, properties?: Record<string, unknown>, options?: {
+            event_id: string;
+        }) => void;
         identify?: (properties?: Record<string, unknown>) => void;
         setAndDefer?: (obj: Record<string, unknown>, method: string) => void;
         instance?: (pixelId: string) => Ttq;
@@ -287,17 +290,22 @@ type DoRequestResponse = {
 };
 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.
+ * Optional config for the support widget. Support 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 `{ enabled }` check and lazily injects the lean loader
+ * (`saasco-support-loader.js`) only when the project has the widget 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 origin is resolved automatically: the CDN `<script>` origin for
+ * CDN installs, else the public Saasco CDN for npm/bundled installs. Pass this
+ * object only to override those defaults: `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 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. */
@@ -323,19 +331,11 @@ type SupportInit = {
  * 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,
+ * only to override those defaults: `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
@@ -357,12 +357,13 @@ declare class Saasco {
     private integrationManager;
     private logger;
     private lastSupportIdentity;
+    private ingestFailureKeys;
     /**
      * 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.autoPageTracking Whether to automatically track page views. Default is true.
      * @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.
@@ -387,20 +388,6 @@ declare class Saasco {
     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
      */
@@ -414,7 +401,7 @@ declare class Saasco {
     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"
+     * This records the page title and path and names the event using the reserved name "Page View"
      *
      * Before implementing this make sure you have disabled the autoPageTracking in the config or you will get duplicate page views
      */
@@ -465,11 +452,8 @@ declare class Saasco {
         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.
+     * Lazily injects the support **loader** (server-gated). See
+     * {@link injectSupportLoader}. Replays identity once the script loads.
      */
     private injectSupport;
     /**
@@ -479,14 +463,13 @@ declare class Saasco {
     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.
+     * it (same approach as tool registration). `injectSupport` calls this on
+     * script load (or immediately when the loader is already present).
      */
     private pushSupportIdentity;
 }

package/dist/index.d.ts

@@ -39,7 +39,7 @@ type Integration = {
     /**
      * The function to track an event
      */
-    track?: (name: string, properties?: Record<string, unknown>, context?: AnalyticsContext) => void;
+    track?: (name: string, properties?: Record<string, unknown>, context?: AnalyticsContext) => void | Promise<void>;
     /**
      * The function to identify a user
      */
@@ -51,6 +51,7 @@ type IntegrationState = {
     status: IntegrationStatus;
 };
 type ManagerConfig = {
+    deduplicationNamespace?: string;
     /**
      * Enable logger level
      */
@@ -60,7 +61,7 @@ type ManagerConfig = {
      */
     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.
+     * Max integration wait time, this is how long we will wait for an integration to be ready before flushing the queue. Unsent events expire after this time without consuming their delivery guard, so an explicit retry or page refresh can retry them.
      */
     maxIntegrationWaitTime?: number;
     /**
@@ -74,7 +75,6 @@ declare class IntegrationManager {
     private globalQueue;
     private config;
     private logger;
-    private initTime;
     private currentEnvironment;
     private flushTimer?;
     private unloadHandler?;
@@ -96,12 +96,10 @@ declare class IntegrationManager {
      */
     private send;
     private deliver;
-    /**
-     * Flush queued events FIFO once at least one integration is ready.
-     */
+    /** Each ready destination drains its own copy; a slow/blocked pixel cannot
+     * discard another pixel's queued events or hold up the ready destinations. */
     private flush;
     private readyCount;
-    private isReady;
     /**
      * Setup periodic flushing if enabled
      */
@@ -139,6 +137,8 @@ declare global {
     }
     interface Fbq {
         (...args: unknown[]): void;
+        callMethod?: (...args: unknown[]) => void;
+        push?: (...args: unknown[]) => void;
         queue?: unknown[];
         loaded?: boolean;
         version?: string;
@@ -217,13 +217,16 @@ declare global {
     }
     interface Ttq {
         (...args: unknown[]): void;
+        ready?: (callback: () => void) => 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;
+        track?: (eventName: string, properties?: Record<string, unknown>, options?: {
+            event_id: string;
+        }) => void;
         identify?: (properties?: Record<string, unknown>) => void;
         setAndDefer?: (obj: Record<string, unknown>, method: string) => void;
         instance?: (pixelId: string) => Ttq;
@@ -287,17 +290,22 @@ type DoRequestResponse = {
 };
 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.
+ * Optional config for the support widget. Support 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 `{ enabled }` check and lazily injects the lean loader
+ * (`saasco-support-loader.js`) only when the project has the widget 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 origin is resolved automatically: the CDN `<script>` origin for
+ * CDN installs, else the public Saasco CDN for npm/bundled installs. Pass this
+ * object only to override those defaults: `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 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. */
@@ -323,19 +331,11 @@ type SupportInit = {
  * 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,
+ * only to override those defaults: `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
@@ -357,12 +357,13 @@ declare class Saasco {
     private integrationManager;
     private logger;
     private lastSupportIdentity;
+    private ingestFailureKeys;
     /**
      * 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.autoPageTracking Whether to automatically track page views. Default is true.
      * @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.
@@ -387,20 +388,6 @@ declare class Saasco {
     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
      */
@@ -414,7 +401,7 @@ declare class Saasco {
     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"
+     * This records the page title and path and names the event using the reserved name "Page View"
      *
      * Before implementing this make sure you have disabled the autoPageTracking in the config or you will get duplicate page views
      */
@@ -465,11 +452,8 @@ declare class Saasco {
         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.
+     * Lazily injects the support **loader** (server-gated). See
+     * {@link injectSupportLoader}. Replays identity once the script loads.
      */
     private injectSupport;
     /**
@@ -479,14 +463,13 @@ declare class Saasco {
     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.
+     * it (same approach as tool registration). `injectSupport` calls this on
+     * script load (or immediately when the loader is already present).
      */
     private pushSupportIdentity;
 }