sitepong 0.1.13 → 0.2.0

package/dist/index.d.mts

@@ -225,12 +225,20 @@ interface PerformanceConfig {
     apiKey: string;
     endpoint?: string;
     enabled?: boolean;
-    /** Collect Web Vitals (default: true) */
+    /** Collect Web Vitals via web-vitals library (default: true) */
     webVitals?: boolean;
     /** Report navigation timing (default: true) */
     navigationTiming?: boolean;
-    /** Report resource timing (default: false) */
+    /** Report resource timing with detailed breakdowns (default: true) */
     resourceTiming?: boolean;
+    /** Capture page load timing milestones (default: true) */
+    capturePageLoadTimings?: boolean;
+    /** Capture page render timing: Speed Index, TTI, Visually Complete (default: true) */
+    capturePageRenderTimings?: boolean;
+    /** URL prefixes to exclude from resource timing collection */
+    excludedResourceUrls?: string[];
+    /** Transform resource URLs before reporting (strip tokens, etc.) */
+    resourceNameSanitizer?: (url: string) => string;
     /** Custom endpoint for performance data */
     performanceEndpoint?: string;
     /** Flush interval in ms (default: 10000) */
@@ -241,12 +249,29 @@ interface PerformanceConfig {
 }
 interface WebVitals {
     lcp?: number;
-    fid?: number;
     cls?: number;
     fcp?: number;
     ttfb?: number;
     inp?: number;
 }
+interface ResourceTimingBreakdown {
+    queueing: number;
+    dnsLookup: number;
+    initialConnection: number;
+    ssl: number;
+    ttfb: number;
+    contentDownload: number;
+    total: number;
+    stalled: number;
+    cached: boolean;
+    failed: boolean;
+    responseStatus: number;
+    headerSize: number;
+    encodedBodySize: number;
+    decodedBodySize: number;
+    transferSize: number;
+    initiatorType: string;
+}
 interface PerformanceSpan {
     id: string;
     name: string;
@@ -276,31 +301,25 @@ declare class PerformanceManager {
     private vitals;
     private activeTransactions;
     private sampled;
+    private resourceObserver;
+    private resourceTimeMap;
+    private resourceCount;
+    private pageLoadTimer;
+    private pageRenderTimer;
     constructor(config: PerformanceConfig);
     init(): void;
-    /**
-     * Start a custom transaction for measuring operations
-     */
+    private initWebVitals;
+    private initResourceTiming;
+    private isServiceURL;
+    private processResourceEntry;
+    private initPageLoadTiming;
+    private initPageRenderTiming;
     startTransaction(name: string, data?: Record<string, unknown>): string;
-    /**
-     * End a transaction and report it
-     */
     endTransaction(id: string, status?: 'ok' | 'error'): void;
-    /**
-     * Start a span within a transaction
-     */
     startSpan(transactionId: string, name: string, data?: Record<string, unknown>): string;
-    /**
-     * End a span
-     */
     endSpan(transactionId: string, spanId: string, status?: 'ok' | 'error'): void;
-    /**
-     * Get current Web Vitals
-     */
     getVitals(): WebVitals;
     destroy(): void;
-    private observeWebVitals;
-    private collectNavigationTiming;
     private reportVital;
     private addMetric;
     private startFlushTimer;
@@ -632,6 +651,311 @@ interface DatabaseTrackerConfig {
     redactParams?: boolean;
 }
 
+/**
+ * SuperLink — deferred deep linking / smart links (OneLink/Branch-style).
+ *
+ * These types are platform-agnostic and shared between the web capture path
+ * and the React Native deferred-attribution path. They mirror the database
+ * schema (see supabase/migrations/*_superlink.sql): the redirect engine logs
+ * clicks + device fingerprints, and the mobile SDK matches on first launch to
+ * deliver the original deep link across the install gap.
+ */
+/**
+ * UTM parameters carried on a SuperLink. Keyed without the `utm_` prefix —
+ * the redirect URL's `utm_source`/`utm_medium`/… map to `source`/`medium`/…
+ * (self-contained so the SuperLink module has no cross-module dependencies).
+ */
+interface UtmParams {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+}
+/** Platforms recognised by the redirect engine (matches superlink_platform). */
+type SuperLinkPlatform = 'ios' | 'android' | 'desktop' | 'other';
+/** How a deferred click was matched to an install (matches superlink_match_type). */
+type SuperLinkMatchType = 'referrer' | 'clipboard' | 'qr' | 'identity' | 'fingerprint' | 'none';
+/** Lifecycle event types (matches superlink_event_type). */
+type SuperLinkEventType = 'clicked' | 'installed' | 'opened' | 'converted';
+/**
+ * Configuration for the SuperLink client.
+ */
+interface SuperLinkConfig {
+    /** Redirect engine base URL. Defaults to the shared short domain. */
+    endpoint?: string;
+    /** Optional SuperLink app id (superlink_apps.id) for store-URL / AASA context. */
+    appId?: string;
+    /** Stable per-install id reported at match time (superlink_clicks.install_id). */
+    installId?: string;
+    /** Emit verbose diagnostics to the console. */
+    debug?: boolean;
+}
+/**
+ * Resolved deep link payload delivered to the app, whether captured directly
+ * on the web (inbound params), via a Universal Link / App Link open, or matched
+ * deferentially on first launch after an install.
+ */
+interface SuperLinkDeepLink {
+    /** In-app route, e.g. "/products/42" (superlink_links.deep_link_path). */
+    deep_link_path: string | null;
+    /** Arbitrary payload delivered on open (superlink_links.deep_link_data). */
+    deep_link_data: Record<string, unknown>;
+    /** Campaign params carried from the click URL. */
+    utm: UtmParams;
+    /** Affiliate / referral params carried from the click URL. */
+    referral: Record<string, unknown>;
+    /** Opaque click token, when known (superlink_clicks.click_id). */
+    click_id?: string | null;
+    /** How this link was resolved. */
+    match_type: SuperLinkMatchType;
+    /** 0..1 confidence — deterministic matches are 1, fingerprint matches lower. */
+    confidence: number;
+}
+/** Server response to POST /match. */
+interface SuperLinkMatchResponse {
+    matched: boolean;
+    click_id?: string | null;
+    link_id?: string | null;
+    deep_link_path?: string | null;
+    deep_link_data?: Record<string, unknown>;
+    utm?: UtmParams;
+    referral?: Record<string, unknown>;
+    match_type?: SuperLinkMatchType;
+    confidence?: number;
+}
+/** Handler invoked with a resolved deferred deep link. */
+type DeferredDeepLinkHandler = (link: SuperLinkDeepLink) => void;
+/**
+ * Device fingerprint signals POSTed to /match. Mirrors the fingerprint columns
+ * on superlink_clicks. All fields are best-effort and optional.
+ */
+interface SuperLinkFingerprint {
+    platform: SuperLinkPlatform;
+    os?: string;
+    os_version?: string;
+    device_model?: string;
+    /** Browser name/UA, when known (web/desktop). */
+    browser?: string;
+    /** Coarse device class reported to the engine. */
+    device_type?: string;
+    /** Client IP, when the caller knows it (engine usually fills this in). */
+    ip?: string;
+    /** Raw user-agent string (web/desktop). */
+    user_agent?: string;
+    /** BCP-47 locale tag. */
+    language?: string;
+}
+/** Identity metadata for high-confidence matching against a click's metadata jsonb. */
+interface SuperLinkIdentityMetadata {
+    /** User-supplied email for matching. */
+    email?: string;
+    /** User-supplied phone number for matching. */
+    phone?: string;
+    /** App-level user id for matching. */
+    user_id?: string;
+    /** Generic id for matching. */
+    id?: string;
+    /** Arbitrary user-provided attributes for custom matching. */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Request body for POST /match. All fields are optional; the engine resolves in
+ * the order referrer → clipboard_token → qr_token → identity → fingerprint
+ * (first hit wins, best→worst).
+ */
+interface SuperLinkMatchRequest {
+    install_id?: string;
+    /** Android Play Install Referrer click_id (deterministic). */
+    referrer?: string;
+    /**
+     * iOS clipboard value: a raw click_id, "pongl.ink/c/<click_id>", or
+     * "https://pongl.ink/c/<click_id>". Passed through raw — the engine parses it.
+     */
+    clipboard_token?: string;
+    /**
+     * Scanned QR payload: a click-token URL (/c/<id>), a raw click_id, a link URL
+     * (pongl.ink/<slug>), or a bare <slug>. Passed through raw.
+     */
+    qr_token?: string;
+    /** Identity metadata matched against the click's metadata jsonb. */
+    identity?: SuperLinkIdentityMetadata;
+    fingerprint?: SuperLinkFingerprint;
+}
+
+/**
+ * SuperLink core client — platform-agnostic.
+ *
+ * Holds the configured endpoint + app context and exposes thin POST helpers
+ * for the redirect engine's /match and /events routes. Both the web capture
+ * path and the React Native deferred-attribution path share this instance.
+ *
+ * Uses the global `fetch` (present on browser, RN, and Node 18+) directly to
+ * avoid pulling in any DOM-only transport. All network calls are best-effort
+ * and never throw.
+ */
+
+/** Default shared short domain / redirect engine. */
+declare const DEFAULT_SUPERLINK_ENDPOINT = "https://pongl.ink";
+interface ResolvedSuperLinkConfig {
+    endpoint: string;
+    appId?: string;
+    installId?: string;
+    debug: boolean;
+}
+declare class SuperLinkClient {
+    config: ResolvedSuperLinkConfig;
+    constructor(config?: SuperLinkConfig);
+    /** Replace config in place (used by init() so module-level helpers see updates). */
+    configure(config: SuperLinkConfig): void;
+    private log;
+    /**
+     * POST /match — ask the redirect engine to resolve a deferred deep link from
+     * a click token (Android referrer / iOS clipboard) and/or a device
+     * fingerprint. Returns `{ matched: false }` on any error.
+     */
+    match(body: SuperLinkMatchRequest): Promise<SuperLinkMatchResponse>;
+    /**
+     * POST /events — report a lifecycle event (opened / converted) back to the
+     * redirect engine, which fans out to analytics + webhooks. Best-effort.
+     */
+    reportEvent(input: {
+        type: SuperLinkEventType;
+        click_id?: string | null;
+        link_id?: string | null;
+        platform?: SuperLinkPlatform;
+        match_type?: SuperLinkMatchType;
+        properties?: Record<string, unknown>;
+    }): Promise<boolean>;
+}
+/** The process-wide SuperLink client. */
+declare const superlinkClient: SuperLinkClient;
+
+/**
+ * SuperLink web capture.
+ *
+ * On first load, captures inbound deep-link params from the current location
+ * (a direct SuperLink open in the browser, or a query-decorated landing) and
+ * exposes them via getDeepLink(). The captured payload is cached for the rest
+ * of the session so repeated reads are stable.
+ *
+ * Guards every `window`/`sessionStorage` access so importing this module from a
+ * non-DOM bundle is harmless.
+ */
+
+/**
+ * Write a click token to the clipboard in URL form, for handoff to iOS app on install.
+ * Called by the interstitial right before redirect to App Store.
+ */
+declare function writeClipboardToken(clickId: string): void;
+/**
+ * Extract identity metadata from URL query params (?email=&phone=&custom=json).
+ * Used to seed the deferred link match with user-provided attributes.
+ */
+declare function extractIdentityMetadata(url?: string): SuperLinkIdentityMetadata | undefined;
+/**
+ * Capture inbound deep-link params from the current page URL. Idempotent: only
+ * the first call of the session parses; later calls return the cached payload.
+ */
+declare function captureWebDeepLink(): SuperLinkDeepLink | null;
+/**
+ * Return the captured inbound deep link for this session, capturing lazily on
+ * first call. Returns null when no SuperLink params were present.
+ */
+declare function getDeepLink(): SuperLinkDeepLink | null;
+/**
+ * Recover a deferred deep link AFTER the user provides an email/phone (or other
+ * identity) at signup. POSTs /match with { identity, install_id, fingerprint }
+ * so the engine can match the supplied identity against an unmatched click's
+ * metadata. Fires onDeferredDeepLink on a hit. Returns the resolved deep link,
+ * or null. Best-effort: never throws.
+ *
+ * @example
+ * ```ts
+ * import { identify } from 'sitepong';
+ * await identify({ email: user.email, user_id: user.id });
+ * ```
+ */
+declare function identify$1(identity: SuperLinkIdentityMetadata): Promise<SuperLinkDeepLink | null>;
+/**
+ * Complete attribution from a scanned QR payload. POSTs /match with
+ * { qr_token: scanned, install_id } — the raw scanned string is passed straight
+ * through, and the engine parses a click-token URL (/c/<id>), a raw click_id, a
+ * link URL (pongl.ink/<slug>), or a bare <slug>. Fires onDeferredDeepLink on a
+ * hit. Returns the resolved deep link, or null. Best-effort: never throws.
+ *
+ * @example
+ * ```ts
+ * import { completeFromScan } from 'sitepong';
+ * const link = await completeFromScan(qrCodeValue);
+ * ```
+ */
+declare function completeFromScan(scanned: string): Promise<SuperLinkDeepLink | null>;
+
+/**
+ * SuperLink deferred-deep-link registry — platform-agnostic.
+ *
+ * Holds the shared onDeferredDeepLink handler set, the cached last match, and
+ * the SuperLinkMatchResponse → SuperLinkDeepLink normaliser. Both the web/node
+ * recovery path (identify / completeFromScan) and the React Native first-launch
+ * attribution path emit through here so a single handler set sees every match.
+ */
+
+/**
+ * Register a handler fired when a deferred deep link is matched (first-launch
+ * attribution, identify(), or completeFromScan()). If a match already happened
+ * before registration, the handler is invoked immediately with the cached
+ * payload. Returns an unsubscribe fn.
+ */
+declare function onDeferredDeepLink(handler: DeferredDeepLinkHandler): () => void;
+/** The deferred deep link matched so far this process, if any. */
+declare function getMatchedDeepLink(): SuperLinkDeepLink | null;
+
+/**
+ * SuperLink URL parsing — platform-agnostic.
+ *
+ * Extracts the deep link payload encoded in a SuperLink URL: the path, any
+ * `~`-prefixed deep link data, UTM params, and `r_`-prefixed referral params.
+ * Works on both inbound web URLs and Universal Link / App Link opens. Uses the
+ * WHATWG `URL`, which is available on browser, RN (Hermes), and Node.
+ */
+
+/**
+ * Parse a SuperLink (or Universal/App Link) URL into a deep link payload.
+ * Returns null if the URL can't be parsed.
+ *
+ * Conventions carried in the query string:
+ *   - utm_*        → utm
+ *   - r_<key>      → referral (affiliate params)
+ *   - ~<key>       → deep_link_data (Branch-style)
+ *   - click_id     → click token
+ *   - $deep_link_path / dlp → explicit in-app route override
+ */
+declare function parseUniversalLink(url: string): SuperLinkDeepLink | null;
+
+/**
+ * SuperLink — deferred deep linking / smart links public surface.
+ *
+ * Platform-agnostic + web entry points. React Native deferred attribution
+ * lives in `src/react-native/superlink.ts` and is exported from
+ * `sitepong/react-native` so non-RN bundles never pull in native deps.
+ */
+
+/**
+ * Configure the SuperLink client. Safe to call on any platform.
+ *
+ * On web, this also captures any inbound deep-link params from the current
+ * URL immediately, so getDeepLink() is populated on first read.
+ *
+ * @example
+ * ```ts
+ * import { initSuperLink, getDeepLink } from 'sitepong';
+ * initSuperLink({ endpoint: 'https://go.acme.com', appId: 'abc' });
+ * const link = getDeepLink();
+ * ```
+ */
+declare function initSuperLink(config?: SuperLinkConfig): void;
+
 interface SitePongConfig {
     apiKey: string;
     endpoint?: string;
@@ -716,6 +1040,10 @@ interface SitePongInitConfig extends SitePongConfig {
         webVitals?: boolean;
         navigationTiming?: boolean;
         resourceTiming?: boolean;
+        capturePageLoadTimings?: boolean;
+        capturePageRenderTimings?: boolean;
+        excludedResourceUrls?: string[];
+        resourceNameSanitizer?: (url: string) => string;
         sampleRate?: number;
         flushInterval?: number;
         performanceEndpoint?: string;
@@ -988,4 +1316,4 @@ declare const isRemoteConfigFeatureEnabled: (key: string, defaultValue?: boolean
 declare const onRemoteConfigChange: (listener: (config: RemoteConfig) => void) => () => void;
 declare const registerIdentifyHook: (hook: (userId: string) => void) => () => void;
 
-export { type CapturedError, type CronCheckinOptions, type CronHandle, type DatabaseQueryEvent, type DatabaseTrackerConfig, type DeviceInfo, type DeviceSignals, type EnvironmentAdapter, type ErrorContext, type FraudCheckResult, GroupTraits, type MetricOptions, type MutableRNEnvironmentAdapter, type PerformanceConfig, type PerformanceSpan, type PerformanceTransaction, type PlatformName, type ProfileData, type ProfileFrame, type ProfilerConfig, type RemoteConfig, type RemoteConfigFeatures, type RemoteConfigSampling, ReplayConfig, type SitePongConfig, type SitePongInitConfig, type TraceContext, TracePropagator, TrackProperties, UserTraits, type VisitorIdResult, type WebManagerFactories, type WebVitals, addBreadcrumb, areFlagsReady, captureError, captureMessage, clearAnonymousId, clearUser, sitepong as client, createTraceContext, cronCheckin, cronStart, cronWrap, dbTrack, dbTrackSync, sitepong as default, endSpan, endTransaction, extractTrace, flush, flushMetrics, flushProfiles, generateSpanId, generateTraceId, getAllFlags, getAnonymousId, getDbNPlusOnePatterns, getDbQueryCount, getDeviceSignals, getFlag, getFraudCheck, getLatestProfile, getProfiles, getRemoteConfig, getReplaySessionId, getVariant, getVariantPayload, getVisitorId, getWebVitals, group, identify, init, initRN, isInitialized, isRemoteConfigFeatureEnabled, isReplayRecording, metricDistribution, metricGauge, metricHistogram, metricIncrement, metricStartTimer, metricTime, onRemoteConfigChange, profile, propagateTrace, refreshFlags, registerIdentifyHook, registerWebManagerFactories, resetAnalytics, resetDbQueryCount, setAnonymousId, setContext, setCurrentScreen, setEnvironment, setRNGetCurrentScreen, setTags, setUser, startProfileSpan, startReplay, startSpan, startTransaction, stopReplay, track, trackPageView, waitForFlags };
+export { type CapturedError, type CronCheckinOptions, type CronHandle, DEFAULT_SUPERLINK_ENDPOINT, type DatabaseQueryEvent, type DatabaseTrackerConfig, type DeferredDeepLinkHandler, type DeviceInfo, type DeviceSignals, type EnvironmentAdapter, type ErrorContext, type FraudCheckResult, GroupTraits, type MetricOptions, type MutableRNEnvironmentAdapter, type PerformanceConfig, type PerformanceSpan, type PerformanceTransaction, type PlatformName, type ProfileData, type ProfileFrame, type ProfilerConfig, type RemoteConfig, type RemoteConfigFeatures, type RemoteConfigSampling, ReplayConfig, type ResourceTimingBreakdown, type SitePongConfig, type SitePongInitConfig, SuperLinkClient, type SuperLinkConfig, type SuperLinkDeepLink, type SuperLinkEventType, type SuperLinkFingerprint, type SuperLinkIdentityMetadata, type SuperLinkMatchRequest, type SuperLinkMatchResponse, type SuperLinkMatchType, type SuperLinkPlatform, type TraceContext, TracePropagator, TrackProperties, UserTraits, type VisitorIdResult, type WebManagerFactories, type WebVitals, addBreadcrumb, areFlagsReady, captureError, captureMessage, captureWebDeepLink, clearAnonymousId, clearUser, sitepong as client, completeFromScan, createTraceContext, cronCheckin, cronStart, cronWrap, dbTrack, dbTrackSync, sitepong as default, endSpan, endTransaction, extractIdentityMetadata, extractTrace, flush, flushMetrics, flushProfiles, generateSpanId, generateTraceId, getAllFlags, getAnonymousId, getDbNPlusOnePatterns, getDbQueryCount, getDeepLink, getDeviceSignals, getFlag, getFraudCheck, getLatestProfile, getMatchedDeepLink, getProfiles, getRemoteConfig, getReplaySessionId, getVariant, getVariantPayload, getVisitorId, getWebVitals, group, identify, init, initRN, initSuperLink, isInitialized, isRemoteConfigFeatureEnabled, isReplayRecording, metricDistribution, metricGauge, metricHistogram, metricIncrement, metricStartTimer, metricTime, onDeferredDeepLink, onRemoteConfigChange, parseUniversalLink, profile, propagateTrace, refreshFlags, registerIdentifyHook, registerWebManagerFactories, resetAnalytics, resetDbQueryCount, setAnonymousId, setContext, setCurrentScreen, setEnvironment, setRNGetCurrentScreen, setTags, setUser, startProfileSpan, startReplay, startSpan, startTransaction, stopReplay, superlinkClient, identify$1 as superlinkIdentify, track, trackPageView, waitForFlags, writeClipboardToken };