@truxl/javascript-sdk 1.0.0

package/dist/tracking/events.d.ts

@@ -0,0 +1,27 @@
+/**
+ * High-level event tracking helpers.
+ *
+ * Provides convenience wrappers around `TruxlClient.track()` for common
+ * event types such as custom events and page views. Each helper enriches
+ * the event payload with contextual browser information.
+ */
+import { TruxlClient } from '../core/client';
+/**
+ * Track a custom event.
+ *
+ * @param client      The TruxlClient instance.
+ * @param eventName   A descriptive name for the event (e.g. "button_click",
+ *                    "signup_started").
+ * @param properties  Arbitrary key/value properties to attach to the event.
+ */
+export declare function trackEvent(client: TruxlClient, eventName: string, properties?: Record<string, unknown>): void;
+/**
+ * Track a page view event.
+ *
+ * Automatically captures the current URL, path, referrer, page title and
+ * other contextual data.
+ *
+ * @param client      The TruxlClient instance.
+ * @param properties  Optional extra properties to merge into the event.
+ */
+export declare function trackPageView(client: TruxlClient, properties?: Record<string, unknown>): void;

package/dist/tracking/forms.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Form submission tracking.
+ *
+ * Intercepts native `<form>` submit events via a delegated listener on
+ * `document` and tracks a `$form_submit` event with metadata about the
+ * form and its fields (excluding sensitive inputs such as passwords and
+ * credit card numbers).
+ */
+import { TruxlClient } from '../core/client';
+/**
+ * Start tracking form submissions. Idempotent -- calling this multiple
+ * times will not register duplicate listeners.
+ *
+ * @param client  The TruxlClient instance to report events to.
+ */
+export declare function startFormTracking(client: TruxlClient): void;
+/**
+ * Stop tracking form submissions and remove the event listener.
+ */
+export declare function stopFormTracking(): void;

package/dist/transport/beacon.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Beacon transport for page unload scenarios.
+ *
+ * Uses `navigator.sendBeacon()` which is designed to reliably deliver small
+ * payloads even when the page is being closed. This is the preferred
+ * transport for `beforeunload` / `visibilitychange` events where a normal
+ * `fetch()` would likely be cancelled by the browser.
+ *
+ * Falls back to a synchronous `XMLHttpRequest` (keepalive-style) when
+ * `sendBeacon` is not available.
+ */
+import { TruxlConfig } from '../core/config';
+export interface BeaconTransportOptions {
+    config: Required<TruxlConfig>;
+}
+export declare class BeaconTransport {
+    private config;
+    constructor(options: BeaconTransportOptions);
+    /**
+     * Send a payload via `navigator.sendBeacon`. Returns `true` when the
+     * browser accepted the request for delivery (note: this does NOT
+     * guarantee the server received it).
+     *
+     * Because `sendBeacon` is fire-and-forget, HMAC signing is performed
+     * synchronously using the pre-computed signature passed in via headers
+     * encoded as a Blob.
+     */
+    send(payload: unknown): Promise<boolean>;
+    /**
+     * Synchronous variant that can be called from `beforeunload` handlers
+     * where async work is unreliable. Requires the caller to pre-compute
+     * the HMAC signature.
+     */
+    sendSync(payload: unknown, precomputedSignature: string): boolean;
+    private isBeaconAvailable;
+    private sendViaBeacon;
+    private sendViaXHR;
+}

package/dist/transport/http.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Fetch-based HTTP transport with exponential back-off retry.
+ *
+ * Retry delays follow the pattern: baseDelay * 2^attempt
+ *   attempt 0 -> 1 s
+ *   attempt 1 -> 2 s
+ *   attempt 2 -> 4 s
+ *   attempt 3 -> 8 s
+ *   ...
+ *   capped at MAX_RETRY_DELAY (60 s)
+ *
+ * Only 5xx (server) errors and network failures are retried. 4xx responses
+ * are treated as permanent failures and are NOT retried.
+ */
+import { TruxlConfig } from '../core/config';
+import { Transport, TransportResult } from './transport';
+export interface HttpTransportOptions {
+    /** Fully resolved TruxlConfig (all optional fields filled in). */
+    config: Required<TruxlConfig>;
+}
+/**
+ * Low-level HTTP transport. Send a JSON payload to the Truxl ingestion
+ * endpoint with HMAC signing and automatic retry on transient errors.
+ */
+export declare class HttpTransport implements Transport {
+    private config;
+    constructor(options: HttpTransportOptions);
+    /**
+     * Send a JSON-serialisable payload to the batch endpoint.
+     *
+     * @param payload  The body to POST (will be JSON-stringified).
+     * @returns        A result object indicating success/failure and number of
+     *                 retries performed.
+     */
+    send(payload: unknown): Promise<TransportResult>;
+    private sendWithRetry;
+    /**
+     * Calculate the delay for a given retry attempt and sleep.
+     * delay = min(baseDelay * 2^attempt, MAX_RETRY_DELAY)
+     */
+    private wait;
+}

package/dist/transport/transport.d.ts

@@ -0,0 +1,9 @@
+export interface TransportResult {
+    ok: boolean;
+    status: number;
+    retries: number;
+}
+export interface Transport {
+    send(payload: unknown): Promise<TransportResult>;
+    destroy?(): void;
+}

package/dist/transport/websocket.d.ts

@@ -0,0 +1,19 @@
+import { TruxlConfig } from '../core/config';
+import { Transport, TransportResult } from './transport';
+export interface WebSocketTransportOptions {
+    config: Required<TruxlConfig>;
+}
+export declare class WebSocketTransport implements Transport {
+    private config;
+    private ws;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private pendingMessages;
+    private connected;
+    private destroyed;
+    constructor(options: WebSocketTransportOptions);
+    send(payload: unknown): Promise<TransportResult>;
+    destroy(): void;
+    private connect;
+    private scheduleReconnect;
+}