@tracelog/lib 2.9.0-rc.108.13 → 2.9.0-rc.108.16

package/dist/public-api.d.mts

@@ -495,10 +495,14 @@ interface Config {
     /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
     sendIntervalMs?: number;
     /**
-     * If true, the event queue is flushed automatically after every SPA navigation
-     * (`pushState`, `replaceState`, `popstate`, `hashchange`). Prevents batch loss when the
-     * user closes the tab mid-buffer between SPA route changes. No-op for MPAs (no SPA nav).
-     * @default true
+     * Opt-in: when `true`, the event queue is flushed after every SPA navigation
+     * (`pushState`, `replaceState`, `popstate`, `hashchange`). Defaults to `false`
+     * because per-route flushing can multiply request volume on SPA-heavy apps
+     * (one request per route change vs. one per `sendIntervalMs`). Enable only
+     * if you need delivery between route changes that's faster than
+     * `sendIntervalMs`; `flushOnPageHidden` (default `true`) already covers the
+     * common tab-close / app-background case on every stack. No-op for MPAs.
+     * @default false
      */
     flushOnSpaNavigation?: boolean;
     /**
@@ -1573,7 +1577,14 @@ declare class EventManager extends StateManager {
      * - No retry on failure (sendBeacon is fire-and-forget)
      * - 64KB payload limit (large batches may be truncated)
      *
-     * @returns `true` if all sends succeeded, `false` if any failed
+     * **In-flight contract**: if an async send is already running this call is
+     * deferred (queued for replay in the async send's `finally` block) and
+     * returns `false` — nothing has been delivered yet at the point of return.
+     * Mirrors `flushImmediately()`'s behaviour for the same condition.
+     *
+     * @returns `true` if at least one integration accepted the beacon batch
+     *          *during this call*, `false` otherwise (no events, all senders
+     *          failed, or the call was deferred behind an in-flight async send)
      *
      * @example
      * ```typescript
@@ -1587,44 +1598,6 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for flush details
      */
     flushImmediatelySync(): boolean;
-    /**
-     * Sends ONLY the most recently queued event via `navigator.sendBeacon()` in
-     * a dedicated single-event batch.
-     *
-     * **Purpose**: Guarantee delivery of an event that *must* survive an
-     * imminent page unload (purchase confirmation, signup completion, etc.),
-     * independent of the main queue's size or in-flight async send state.
-     *
-     * **Why a dedicated batch**: `flushImmediatelySync()` serialises the entire
-     * queue into one `sendBeacon` call. If the queue is heavy (>64KB) the
-     * beacon fails and the batch is persisted to `localStorage`, which is only
-     * recovered on the next `init()` — useless for one-shot conversion events
-     * where the user never returns.
-     *
-     * **Behaviour**:
-     * - Reads the last entry of `eventsQueue` (the just-tracked event).
-     * - Wraps it in its own `EventsQueue` and dispatches synchronously through
-     *   every `SenderManager` via `sendEventsQueueSync()`.
-     * - Leaves the main queue untouched; the same event will be re-delivered by
-     *   the next periodic / unload flush. Idempotency is the caller-side
-     *   contract: the backend MUST deduplicate by `event.id` (e.g. unique index
-     *   on the ingestion collection) — same guarantee the library already
-     *   relies on for the persisted-events recovery path.
-     *
-     * **Use it after** `track()` so the event is in the queue. Caller is
-     * responsible for verifying that `track()` actually queued the event
-     * (it can be dropped by rate limiting / sampling / `beforeSend`).
-     *
-     * **Standalone mode** (no senders configured): returns `false` without
-     * emitting. The subsequent main-queue drain (`flushImmediatelySync()`) is
-     * responsible for delivering the event to local listeners — emitting here
-     * too would surface the same event twice to a `tracelog.on('queue', ...)`
-     * subscriber.
-     *
-     * @returns `true` if at least one sender delivered the beacon successfully,
-     * `false` otherwise (including standalone mode — the drain handles it).
-     */
-    flushLastEventSync(): boolean;
     /**
      * Sets the custom headers provider callback for the custom integration.
      * Only affects requests to custom backend (not TraceLog SaaS).
@@ -2742,6 +2715,7 @@ declare const tracelog: {
     removeCustomHeaders: () => void;
     isInitialized: () => boolean;
     getSessionId: () => string | null;
+    getUserId: () => string | null;
     destroy: () => void;
     setQaMode: (enabled: boolean) => void;
     updateGlobalMetadata: (metadata: Record<string, MetadataType>) => void;

package/dist/public-api.d.ts

@@ -495,10 +495,14 @@ interface Config {
     /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
     sendIntervalMs?: number;
     /**
-     * If true, the event queue is flushed automatically after every SPA navigation
-     * (`pushState`, `replaceState`, `popstate`, `hashchange`). Prevents batch loss when the
-     * user closes the tab mid-buffer between SPA route changes. No-op for MPAs (no SPA nav).
-     * @default true
+     * Opt-in: when `true`, the event queue is flushed after every SPA navigation
+     * (`pushState`, `replaceState`, `popstate`, `hashchange`). Defaults to `false`
+     * because per-route flushing can multiply request volume on SPA-heavy apps
+     * (one request per route change vs. one per `sendIntervalMs`). Enable only
+     * if you need delivery between route changes that's faster than
+     * `sendIntervalMs`; `flushOnPageHidden` (default `true`) already covers the
+     * common tab-close / app-background case on every stack. No-op for MPAs.
+     * @default false
      */
     flushOnSpaNavigation?: boolean;
     /**
@@ -1573,7 +1577,14 @@ declare class EventManager extends StateManager {
      * - No retry on failure (sendBeacon is fire-and-forget)
      * - 64KB payload limit (large batches may be truncated)
      *
-     * @returns `true` if all sends succeeded, `false` if any failed
+     * **In-flight contract**: if an async send is already running this call is
+     * deferred (queued for replay in the async send's `finally` block) and
+     * returns `false` — nothing has been delivered yet at the point of return.
+     * Mirrors `flushImmediately()`'s behaviour for the same condition.
+     *
+     * @returns `true` if at least one integration accepted the beacon batch
+     *          *during this call*, `false` otherwise (no events, all senders
+     *          failed, or the call was deferred behind an in-flight async send)
      *
      * @example
      * ```typescript
@@ -1587,44 +1598,6 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for flush details
      */
     flushImmediatelySync(): boolean;
-    /**
-     * Sends ONLY the most recently queued event via `navigator.sendBeacon()` in
-     * a dedicated single-event batch.
-     *
-     * **Purpose**: Guarantee delivery of an event that *must* survive an
-     * imminent page unload (purchase confirmation, signup completion, etc.),
-     * independent of the main queue's size or in-flight async send state.
-     *
-     * **Why a dedicated batch**: `flushImmediatelySync()` serialises the entire
-     * queue into one `sendBeacon` call. If the queue is heavy (>64KB) the
-     * beacon fails and the batch is persisted to `localStorage`, which is only
-     * recovered on the next `init()` — useless for one-shot conversion events
-     * where the user never returns.
-     *
-     * **Behaviour**:
-     * - Reads the last entry of `eventsQueue` (the just-tracked event).
-     * - Wraps it in its own `EventsQueue` and dispatches synchronously through
-     *   every `SenderManager` via `sendEventsQueueSync()`.
-     * - Leaves the main queue untouched; the same event will be re-delivered by
-     *   the next periodic / unload flush. Idempotency is the caller-side
-     *   contract: the backend MUST deduplicate by `event.id` (e.g. unique index
-     *   on the ingestion collection) — same guarantee the library already
-     *   relies on for the persisted-events recovery path.
-     *
-     * **Use it after** `track()` so the event is in the queue. Caller is
-     * responsible for verifying that `track()` actually queued the event
-     * (it can be dropped by rate limiting / sampling / `beforeSend`).
-     *
-     * **Standalone mode** (no senders configured): returns `false` without
-     * emitting. The subsequent main-queue drain (`flushImmediatelySync()`) is
-     * responsible for delivering the event to local listeners — emitting here
-     * too would surface the same event twice to a `tracelog.on('queue', ...)`
-     * subscriber.
-     *
-     * @returns `true` if at least one sender delivered the beacon successfully,
-     * `false` otherwise (including standalone mode — the drain handles it).
-     */
-    flushLastEventSync(): boolean;
     /**
      * Sets the custom headers provider callback for the custom integration.
      * Only affects requests to custom backend (not TraceLog SaaS).
@@ -2742,6 +2715,7 @@ declare const tracelog: {
     removeCustomHeaders: () => void;
     isInitialized: () => boolean;
     getSessionId: () => string | null;
+    getUserId: () => string | null;
     destroy: () => void;
     setQaMode: (enabled: boolean) => void;
     updateGlobalMetadata: (metadata: Record<string, MetadataType>) => void;