@fanfare-io/fanfare-sdk-core 0.1.0

package/dist/auth/auth.module.d.ts

@@ -0,0 +1,71 @@
+import { HttpClient } from '../core/http';
+import { AuthenticatedSession, AuthModule, AuthStatus, ExternalExchange, GuestSession, LoginOptions, OtpRequest, OtpVerify, Session } from './types';
+export declare class AuthenticationModule implements AuthModule {
+    private http;
+    private beaconHttp;
+    private logger;
+    private store;
+    private events;
+    private refreshTimer?;
+    private refreshPromise?;
+    constructor(http: HttpClient, beaconHttp: HttpClient);
+    /**
+     * Check current authentication status
+     */
+    check(): AuthStatus;
+    /**
+     * Create a guest session
+     */
+    guest(): Promise<GuestSession>;
+    /**
+     * Request OTP for email login
+     */
+    requestOtp(options: OtpRequest | string): Promise<void>;
+    /**
+     * Verify OTP and login
+     */
+    verifyOtp(options: OtpVerify | {
+        email: string;
+        code: string;
+    }): Promise<AuthenticatedSession>;
+    /**
+     * Exchange a one-time external auth code for an authenticated session
+     */
+    exchangeExternal(options: ExternalExchange | string): Promise<AuthenticatedSession>;
+    /**
+     * Login with email (combined OTP flow)
+     */
+    login(options: LoginOptions): Promise<void>;
+    /**
+     * Logout current session
+     */
+    logout(): Promise<void>;
+    /**
+     * Get current session
+     */
+    getSession(): Session | null;
+    /**
+     * Refresh the access token
+     */
+    refresh(): Promise<void>;
+    /**
+     * Internal refresh implementation
+     */
+    private _doRefresh;
+    /**
+     * Handle 401 responses
+     */
+    private handleUnauthorized;
+    /**
+     * Schedule token refresh 5 minutes before expiry
+     */
+    private scheduleTokenRefresh;
+    /**
+     * Cancel scheduled token refresh
+     */
+    private cancelTokenRefresh;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}

package/dist/auth/auth.module.js

@@ -0,0 +1 @@
+import{getLogger as e}from"../core/logger.js";import{getEventBus as t}from"../state/events.js";import{getSDKStore as s}from"../state/store.js";class r{constructor(r,o){this.logger=e(),this.store=s(),this.events=t(),this.http=r,this.beaconHttp=o,this.http.updateConfig({...this.http.getConfig(),onUnauthorized:async()=>{await this.handleUnauthorized()}});const i=this.store.beaconToken;i&&this.beaconHttp.updateConfig({...this.beaconHttp.getConfig(),headers:{...this.beaconHttp.getConfig().headers,"X-Beacon-Token":i}})}check(){const e=this.store.session;return e?{isAuthenticated:!0,session:e,isGuest:"guest"===e.type}:{isAuthenticated:!1}}async guest(){try{this.logger.info("Creating guest session");const{session:e,accessToken:t,refreshToken:s,beaconToken:r}=await this.http.post("/auth/guest");return this.store.setSession(e),this.store.setRefreshToken(s??null),this.store.setBeaconToken(r),this.http.updateConfig({...this.http.getConfig(),headers:{...this.http.getConfig().headers,Authorization:`Bearer ${t}`}}),this.beaconHttp.updateConfig({...this.beaconHttp.getConfig(),headers:{...this.beaconHttp.getConfig().headers,"X-Beacon-Token":r}}),this.scheduleTokenRefresh(e.expiresAt),this.events.emit("auth:authenticated",{session:e,isNew:!0}),e}catch(e){const t=e instanceof Error?e:new Error(String(e));throw this.logger.error("Failed to create guest session",t),this.events.emit("auth:error",{error:t,context:"guest"}),t}}async requestOtp(e){try{this.logger.info("Requesting OTP");const t="string"==typeof e?{email:e}:e;await this.http.post("/auth/otp/request",t)}catch(t){const e=t instanceof Error?t:new Error(String(t));throw this.logger.error("Failed to request OTP",e),this.events.emit("auth:error",{error:e,context:"requestOtp"}),e}}async verifyOtp(e){try{const t=e;this.logger.info("Verifying OTP",{email:t.email,phone:t.phone});const{session:s,accessToken:r,refreshToken:o,beaconToken:i}=await this.http.post("/auth/otp/verify",t);return this.store.setSession(s),this.store.setRefreshToken(o??null),this.store.setBeaconToken(i),this.http.updateConfig({...this.http.getConfig(),headers:{...this.http.getConfig().headers,Authorization:`Bearer ${r}`}}),this.beaconHttp.updateConfig({...this.beaconHttp.getConfig(),headers:{...this.beaconHttp.getConfig().headers,"X-Beacon-Token":i}}),this.scheduleTokenRefresh(s.expiresAt),this.events.emit("auth:authenticated",{session:s,isNew:!0}),s}catch(t){const e=t instanceof Error?t:new Error(String(t));throw this.logger.error("Failed to verify OTP",e),this.events.emit("auth:error",{error:e,context:"verifyOtp"}),e}}async exchangeExternal(e){try{const t="string"==typeof e?{exchangeCode:e}:e;this.logger.info("Exchanging external auth code");const{session:s,accessToken:r,refreshToken:o,beaconToken:i}=await this.http.post("/auth/external/exchange",t);return this.store.setSession(s),this.store.setRefreshToken(o??null),this.store.setBeaconToken(i),this.http.updateConfig({...this.http.getConfig(),headers:{...this.http.getConfig().headers,Authorization:`Bearer ${r}`}}),this.beaconHttp.updateConfig({...this.beaconHttp.getConfig(),headers:{...this.beaconHttp.getConfig().headers,"X-Beacon-Token":i}}),this.scheduleTokenRefresh(s.expiresAt),this.events.emit("auth:authenticated",{session:s,isNew:!0}),s}catch(t){const e=t instanceof Error?t:new Error(String(t));throw this.logger.error("Failed to exchange external auth code",e),this.events.emit("auth:error",{error:e,context:"exchangeExternal"}),e}}async login(e){await this.requestOtp({email:e.email})}async logout(){try{if(!this.store.session)return;this.cancelTokenRefresh(),await this.http.post("/auth/logout",{},{skipUnauthorizedHandler:!0}).catch(()=>{}),this.store.clearAll();const e=this.http.getConfig(),{Authorization:t,...s}=e.headers||{};this.http.updateConfig({...e,headers:s});const r=this.beaconHttp.getConfig(),{"X-Beacon-Token":o,...i}=r.headers||{};this.beaconHttp.updateConfig({...r,headers:i}),this.events.emit("auth:logout",{reason:"user"})}catch(e){const t=e instanceof Error?e:new Error(String(e));throw this.logger.error("Error during logout",t),this.store.clearAll(),t}}getSession(){return this.store.session}async refresh(){return this.refreshPromise?(this.logger.debug("Refresh already in progress, returning existing promise"),this.refreshPromise):(this.refreshPromise=this._doRefresh().finally(()=>{this.refreshPromise=void 0}),this.refreshPromise)}async _doRefresh(){try{this.logger.info("Refreshing access token");const{accessToken:e,refreshToken:t,beaconToken:s}=await this.http.post("/auth/refresh",{});this.store.setRefreshToken(t??null),this.store.setBeaconToken(s),this.http.updateConfig({...this.http.getConfig(),headers:{...this.http.getConfig().headers,Authorization:`Bearer ${e}`}}),this.beaconHttp.updateConfig({...this.beaconHttp.getConfig(),headers:{...this.beaconHttp.getConfig().headers,"X-Beacon-Token":s}});const r=this.store.session;r&&r.expiresAt&&this.scheduleTokenRefresh(r.expiresAt),this.store.session&&this.events.emit("auth:refreshed",{session:this.store.session})}catch(e){const t=e instanceof Error?e:new Error(String(e));throw this.logger.error("Failed to refresh token",t),await this.logout(),t}}async handleUnauthorized(){this.logger.warn("Received 401, attempting to refresh token");try{await this.refresh()}catch(e){const t=e instanceof Error?e:new Error(String(e));this.logger.error("Failed to handle 401",t),this.events.emit("auth:error",{error:new Error("Session expired"),context:"unauthorized"})}}scheduleTokenRefresh(e){this.cancelTokenRefresh();const t=Date.now(),s=new Date(e).getTime()-3e5,r=s-t;r<=0?this.refresh().catch(e=>{this.logger.error("Failed to refresh expired token",e)}):(this.logger.debug("Scheduling token refresh",{expiresAt:new Date(e).toISOString(),refreshAt:new Date(s).toISOString(),delayMs:r}),this.refreshTimer=setTimeout(()=>{this.refresh().catch(e=>{this.logger.error("Scheduled token refresh failed",e)})},r))}cancelTokenRefresh(){this.refreshTimer&&(clearTimeout(this.refreshTimer),this.refreshTimer=void 0,this.logger.debug("Cancelled token refresh timer"))}destroy(){this.cancelTokenRefresh(),this.refreshPromise=void 0}}export{r as AuthenticationModule};

package/dist/auth/index.d.ts

@@ -0,0 +1 @@
+export type { AuthModule, AuthStatus, AuthenticatedSession, Consumer, ExternalExchange, GuestSession, LoginOptions, OtpRequest, OtpVerify, Session, } from './types';

package/dist/auth/index.js

@@ -0,0 +1 @@
+

package/dist/auth/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Authentication type definitions
+ */
+/**
+ * Authentication module interface
+ */
+export interface AuthModule {
+    /**
+     * Check current authentication status
+     */
+    check(): AuthStatus;
+    /**
+     * Create a guest session
+     */
+    guest(): Promise<GuestSession>;
+    /**
+     * Request OTP for email authentication
+     */
+    requestOtp(options: OtpRequest | string): Promise<void>;
+    /**
+     * Verify OTP and authenticate
+     */
+    verifyOtp(options: OtpVerify | {
+        email: string;
+        code: string;
+    }): Promise<AuthenticatedSession>;
+    /**
+     * Exchange a one-time external auth code for an authenticated session
+     */
+    exchangeExternal(options: ExternalExchange | string): Promise<AuthenticatedSession>;
+    /**
+     * Login with email (combined OTP flow)
+     */
+    login(options: LoginOptions): Promise<void>;
+    /**
+     * Logout and clear session
+     */
+    logout(): Promise<void>;
+    /**
+     * Get current session
+     */
+    getSession(): Session | null;
+    /**
+     * Refresh the access token
+     */
+    refresh(): Promise<void>;
+}
+/**
+ * Login options
+ */
+export interface LoginOptions {
+    email: string;
+}
+export interface OtpRequest {
+    email?: string;
+    phone?: string;
+    defaultCountry?: string;
+    name?: string;
+}
+export interface OtpVerify {
+    email?: string;
+    phone?: string;
+    code: string;
+    defaultCountry?: string;
+}
+export interface ExternalExchange {
+    exchangeCode: string;
+}
+/**
+ * Current authentication status
+ */
+export interface AuthStatus {
+    isAuthenticated: boolean;
+    isGuest?: boolean;
+    session?: Session;
+}
+/**
+ * Base session interface
+ */
+export interface Session {
+    type: "guest" | "authenticated";
+    consumerId: string;
+    email?: string;
+    phone?: string;
+    expiresAt: string;
+    deviceFingerprint?: string;
+}
+/**
+ * Guest session
+ */
+export interface GuestSession extends Session {
+    type: "guest";
+    guestId: string;
+    email: undefined;
+}
+/**
+ * Authenticated session
+ */
+export interface AuthenticatedSession extends Session {
+    type: "authenticated";
+    email?: string;
+    phone?: string;
+}
+/**
+ * Consumer information
+ */
+export interface Consumer {
+    id: string;
+    email?: string;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}

package/dist/beacon/batching.d.ts

@@ -0,0 +1,52 @@
+import { BeaconConfig, BeaconEventInput } from './types';
+/**
+ * Smart event batcher with requestIdleCallback and visibility change support
+ *
+ * Features:
+ * - Batches events in memory
+ * - Auto-flushes when batch size threshold reached
+ * - Auto-flushes after time threshold
+ * - Uses requestIdleCallback for smart batching during idle time
+ * - Auto-flushes on visibility change (tab hidden)
+ * - Auto-flushes on page unload (beforeunload/pagehide)
+ *
+ * @internal
+ */
+export declare class EventBatcher {
+    private queue;
+    private flushTimer;
+    private config;
+    private flushCallback;
+    private visibilityHandler;
+    private beforeUnloadHandler;
+    private pageHideHandler;
+    constructor(config: BeaconConfig, flushCallback: (events: BeaconEventInput[]) => Promise<void>);
+    /**
+     * Add an event to the batch queue
+     *
+     * @param event - Event to queue
+     */
+    add(event: BeaconEventInput): void;
+    /**
+     * Schedule a flush using requestIdleCallback for smart batching
+     *
+     * @private
+     */
+    private scheduleFlush;
+    /**
+     * Flush all pending events immediately
+     *
+     * @returns Promise that resolves when flush completes
+     */
+    flush(): Promise<void>;
+    /**
+     * Set up event listeners for auto-flush behavior
+     *
+     * @private
+     */
+    private setupListeners;
+    /**
+     * Remove event listeners and flush pending events
+     */
+    destroy(): void;
+}

package/dist/beacon/batching.js

@@ -0,0 +1 @@
+class e{constructor(e,i){this.queue=[],this.flushTimer=null,this.visibilityHandler=null,this.beforeUnloadHandler=null,this.pageHideHandler=null,this.config={maxBatchSize:e.maxBatchSize??50,maxBatchTime:e.maxBatchTime??5e3,flushOnVisibilityChange:e.flushOnVisibilityChange??!0,flushOnUnload:e.flushOnUnload??!0,disablePageContext:e.disablePageContext??!1,disableMarketingParams:e.disableMarketingParams??!1},this.flushCallback=i,this.setupListeners()}add(e){this.queue.push(e),this.queue.length>=this.config.maxBatchSize?this.flush():this.flushTimer||this.scheduleFlush()}scheduleFlush(){"undefined"!=typeof requestIdleCallback?requestIdleCallback(()=>{this.flushTimer=setTimeout(()=>this.flush(),this.config.maxBatchTime)},{timeout:this.config.maxBatchTime}):this.flushTimer=setTimeout(()=>this.flush(),this.config.maxBatchTime)}async flush(){if(this.flushTimer&&(clearTimeout(this.flushTimer),this.flushTimer=null),0===this.queue.length)return;const e=[...this.queue];this.queue=[],await this.flushCallback(e)}setupListeners(){"undefined"!=typeof window&&"undefined"!=typeof document&&(this.config.flushOnVisibilityChange&&(this.visibilityHandler=()=>{"hidden"===document.visibilityState&&this.flush()},document.addEventListener("visibilitychange",this.visibilityHandler)),this.config.flushOnUnload&&(this.pageHideHandler=()=>{this.flush()},window.addEventListener("pagehide",this.pageHideHandler),this.beforeUnloadHandler=()=>{this.flush()},window.addEventListener("beforeunload",this.beforeUnloadHandler)))}destroy(){"undefined"!=typeof window&&"undefined"!=typeof document&&(this.visibilityHandler&&document.removeEventListener("visibilitychange",this.visibilityHandler),this.beforeUnloadHandler&&window.removeEventListener("beforeunload",this.beforeUnloadHandler),this.pageHideHandler&&window.removeEventListener("pagehide",this.pageHideHandler)),this.flushTimer&&clearTimeout(this.flushTimer),this.flush()}}export{e as EventBatcher};

package/dist/beacon/beacon.module.d.ts

@@ -0,0 +1,58 @@
+import { HttpClient } from '../core/http';
+import { BeaconConfig, BeaconEventInput, BeaconModule } from './types';
+/**
+ * Beacon tracking module for client-side event tracking
+ *
+ * @internal
+ */
+export declare class BeaconTrackingModule implements BeaconModule {
+    private http;
+    private logger;
+    private events;
+    private store;
+    private batcher;
+    private config;
+    constructor(http: HttpClient, config?: BeaconConfig);
+    /**
+     * Track a single event
+     *
+     * Events are enriched with auto-generated fields and browser context,
+     * then queued for batching. The batch is sent when size/time thresholds
+     * are reached or on visibility change/page unload.
+     *
+     * @param event - Event to track
+     */
+    track(event: BeaconEventInput): Promise<void>;
+    /**
+     * Track multiple events in a batch
+     *
+     * Events are enriched and validated, then sent immediately
+     * (bypassing the batching queue).
+     *
+     * @param events - Events to track
+     */
+    trackBatch(events: BeaconEventInput[]): Promise<void>;
+    /**
+     * Flush pending events immediately
+     *
+     * Forces all queued events to be sent to the beacon endpoint.
+     */
+    flush(): Promise<void>;
+    /**
+     * Send events to beacon endpoint
+     *
+     * Uses single event endpoint for one event, batch endpoint for multiple.
+     * Gracefully degrades on errors (tracking failures don't break app).
+     *
+     * @param events - Events to send
+     * @returns true if sent successfully, false if failed
+     * @private
+     */
+    private sendBatch;
+    /**
+     * Cleanup and destroy the module
+     *
+     * Removes event listeners and flushes pending events.
+     */
+    destroy(): void;
+}

package/dist/beacon/beacon.module.js

@@ -0,0 +1 @@
+import{getLogger as t}from"../core/logger.js";import{getEventBus as e}from"../state/events.js";import{getSDKStore as r}from"../state/store.js";import{EventBatcher as s}from"./batching.js";import{enrichEvent as n}from"./enrichment.js";import{validateEvent as o}from"./validation.js";class i{constructor(n,o={}){this.logger=t(),this.events=e(),this.store=r(),this.http=n,this.config=o,this.batcher=new s(o,async t=>{await this.sendBatch(t)}),this.logger.debug("Beacon tracking module initialized",{config:o})}async track(t){try{const e=n(t,this.config);o(e),this.batcher.add(e),this.events.emit("beacon:queued",{event:e}),this.logger.debug("Event queued for tracking",{event:e})}catch(e){throw this.logger.error("Failed to queue event",{error:e,event:t}),this.events.emit("beacon:error",{error:e,event:t}),e}}async trackBatch(t){try{const e=t.map(t=>{const e=n(t,this.config);return o(e),e}),r=await this.sendBatch(e);this.logger[r?"info":"warn"](r?"Batch tracked successfully":"Batch queued but send failed",{count:e.length})}catch(e){throw this.logger.error("Failed to track batch",{error:e,count:t.length}),this.events.emit("beacon:error",{error:e,events:t}),e}}async flush(){await this.batcher.flush()}async sendBatch(t){if(0===t.length)return!0;try{const e=1===t.length?"/events":"/events/batch",r=1===t.length?t[0]:t,s=this.http.getConfig().headers?.["X-Organization-Id"],n="string"==typeof s?s:void 0,o=this.store.session?.consumerId,i=t=>({...t,...n?{organizationId:n}:{},...o?{consumerId:o}:{}}),a=Array.isArray(r)?r.map(i):i(r);return await this.http.post(e,a),this.events.emit("beacon:sent",{count:t.length}),this.logger.info("Events sent to beacon",{count:t.length}),!0}catch(e){return this.logger.error("Failed to send events",{error:e,count:t.length}),this.events.emit("beacon:error",{error:e,events:t}),!1}}destroy(){this.batcher.destroy()}}export{i as BeaconTrackingModule};

package/dist/beacon/enrichment.d.ts

@@ -0,0 +1,16 @@
+import { BeaconConfig, BeaconEventInput } from './types';
+/**
+ * Auto-enrich beacon event with generated fields and browser context
+ *
+ * Adds the following if not already present:
+ * - eventId (UUID v7 for time-based sorting)
+ * - eventTimestamp (ISO 8601, canonical event time)
+ * - eventProperties (empty object)
+ * - Page context (url, title, referrer)
+ * - Marketing parameters (UTM params from URL)
+ *
+ * @param event - Original event to enrich
+ * @param config - Beacon configuration
+ * @returns Enriched event
+ */
+export declare function enrichEvent(event: BeaconEventInput, config: BeaconConfig): BeaconEventInput;

package/dist/beacon/enrichment.js

@@ -0,0 +1 @@
+import{v7 as e}from"uuid";const t=1e6;function n(n,r){const o={...n};if(o.eventId||(o.eventId=e()),!o.eventTimestamp){const e=function(){const e=Date.now(),n=new Date(e).toISOString(),r=`${e}${function(){if("undefined"==typeof performance||"function"!=typeof performance.now)return"000000";return Math.floor(performance.now()%1*t).toString().padStart(6,"0")}()}`;return{eventTime:n,eventTimeNs:r}}();o.eventTimestamp=e.eventTime,o.eventTimestampNs=e.eventTimeNs}if(o.eventProperties||(o.eventProperties={}),!r.disablePageContext&&"undefined"!=typeof window&&(o.pageUrl||(o.pageUrl=window.location.href),o.pagePath||(o.pagePath=window.location.pathname),o.pageTitle||"undefined"==typeof document||(o.pageTitle=document.title),"undefined"!=typeof document&&document.referrer&&(o.referrerUrl||(o.referrerUrl=document.referrer),!o.referringDomain)))try{const e=new URL(document.referrer);o.referringDomain=e.hostname}catch{}if(!r.disableMarketingParams&&"undefined"!=typeof window)try{const e=new URLSearchParams(window.location.search);if(!o.utmSource){const t=e.get("utm_source");t&&(o.utmSource=t)}if(!o.utmMedium){const t=e.get("utm_medium");t&&(o.utmMedium=t)}if(!o.utmCampaign){const t=e.get("utm_campaign");t&&(o.utmCampaign=t)}if(!o.utmTerm){const t=e.get("utm_term");t&&(o.utmTerm=t)}if(!o.utmContent){const t=e.get("utm_content");t&&(o.utmContent=t)}}catch{}return o}export{n as enrichEvent};

package/dist/beacon/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Beacon Event Tracking Module
+ *
+ * Provides client-side event tracking with automatic enrichment,
+ * smart batching, and lightweight validation.
+ *
+ * @module beacon
+ */
+export { BeaconTrackingModule } from './beacon.module';
+export { enrichEvent } from './enrichment';
+export type { BeaconConfig, BeaconEvent, BeaconEventInput, BeaconModule } from './types';
+export { ValidationError, validateEvent } from './validation';

package/dist/beacon/public.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public beacon type surface.
+ *
+ * Mirrors exactly the beacon symbols on the root barrel — the runtime
+ * `BeaconTrackingModule`/`enrichEvent`/`validateEvent` are deliberately not
+ * re-exported here. `ValidationError` is kept because it is on the root barrel.
+ */
+export type { BeaconConfig, BeaconEvent, BeaconEventInput, BeaconModule } from './types';
+export { ValidationError } from './validation';

package/dist/beacon/public.js

@@ -0,0 +1 @@
+import{ValidationError as o}from"./validation.js";export{o as ValidationError};

package/dist/beacon/types.d.ts

@@ -0,0 +1,103 @@
+import { BeaconEvent, BeaconEventInput } from '@fanfare-io/fanfare-sdk-contracts/beacon';
+export type { BeaconEvent, BeaconEventInput };
+/**
+ * Beacon tracking module interface
+ */
+export interface BeaconModule {
+    /**
+     * Track a single event
+     *
+     * Events are automatically enriched with eventId, timestamp, page context,
+     * and marketing parameters before being queued for batch sending.
+     *
+     * @param event - Event to track
+     * @returns Promise that resolves when event is queued (not sent)
+     *
+     * @example
+     * ```typescript
+     * await fanfare.beacon.track({
+     *   eventName: "pageView",
+     *   eventProperties: {
+     *     pageType: "home"
+     *   }
+     * });
+     * ```
+     */
+    track(event: BeaconEventInput): Promise<void>;
+    /**
+     * Track multiple events in a batch
+     *
+     * Sends events immediately, bypassing the batching queue.
+     * Useful for tracking multiple related events atomically.
+     *
+     * @param events - Events to track
+     * @returns Promise that resolves when batch is sent
+     *
+     * @example
+     * ```typescript
+     * await fanfare.beacon.trackBatch([
+     *   { eventName: "pageView" },
+     *   { eventName: "productImpression", eventProperties: { productId: "123" } }
+     * ]);
+     * ```
+     */
+    trackBatch(events: BeaconEventInput[]): Promise<void>;
+    /**
+     * Flush pending events immediately
+     *
+     * Forces all queued events to be sent to the beacon endpoint.
+     * Automatically called on visibility change and page unload.
+     *
+     * @returns Promise that resolves when flush completes
+     *
+     * @example
+     * ```typescript
+     * await fanfare.beacon.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+}
+/**
+ * Beacon module configuration
+ */
+export interface BeaconConfig {
+    /**
+     * Base URL for beacon API
+     * When not specified, uses the environment-specific beacon URL
+     * @example "http://localhost:4803" (development)
+     * @example "https://beacon.fanfare.io" (production)
+     */
+    baseUrl?: string;
+    /**
+     * Maximum events to batch before auto-flush
+     * @default 50
+     */
+    maxBatchSize?: number;
+    /**
+     * Maximum time (ms) to wait before auto-flush
+     * @default 5000
+     */
+    maxBatchTime?: number;
+    /**
+     * Enable auto-flush on visibility change (tab hidden)
+     * @default true
+     */
+    flushOnVisibilityChange?: boolean;
+    /**
+     * Enable auto-flush on page unload
+     * @default true
+     */
+    flushOnUnload?: boolean;
+    /**
+     * Disable automatic page context enrichment
+     * When true, pageUrl, pageTitle, referrer, etc. will not be auto-populated
+     * @default false
+     */
+    disablePageContext?: boolean;
+    /**
+     * Disable automatic UTM parameter extraction
+     * When true, utm_* fields will not be auto-extracted from URL
+     * @default false
+     */
+    disableMarketingParams?: boolean;
+}

package/dist/beacon/validation.d.ts

@@ -0,0 +1,24 @@
+import { BeaconEventName } from '@fanfare-io/fanfare-sdk-contracts/beacon/names';
+import { BeaconEventInput } from './types';
+/**
+ * Validation error for beacon events
+ */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Lightweight validation for beacon events
+ *
+ * Only validates essential fields:
+ * - eventName is required and non-empty
+ * - eventId exists after enrichment
+ * - eventTimestamp exists after enrichment
+ * - eventProperties is an object if provided
+ *
+ * Server-side validation handles comprehensive validation.
+ *
+ * @param event - Event to validate
+ * @throws {ValidationError} If validation fails
+ */
+export declare function validateEvent(event: BeaconEventInput): void;
+export declare function isBeaconEventName(eventName: string): eventName is BeaconEventName;

package/dist/beacon/validation.js

@@ -0,0 +1 @@
+import{BeaconEventNames as e}from"@fanfare-io/fanfare-sdk-contracts/beacon/names";const t=new Set(e);class n extends Error{constructor(e){super(e),this.name="ValidationError"}}function r(r){if(!r.eventName||"string"!=typeof r.eventName)throw new n("eventName is required and must be a string");if(0===r.eventName.trim().length)throw new n("eventName cannot be empty");if(!t.has(r.eventName))throw new n(`eventName must be one of: ${e.join(", ")}`);if(!r.eventId)throw new n("eventId is required");if(!r.eventTimestamp)throw new n("eventTimestamp is required");if(void 0!==r.eventProperties&&"object"!=typeof r.eventProperties)throw new n("eventProperties must be an object");if(null===r.eventProperties)throw new n("eventProperties cannot be null")}export{n as ValidationError,r as validateEvent};

package/dist/challenges/challenge.module.d.ts

@@ -0,0 +1,9 @@
+import { HttpClient } from '../core/http';
+import { ChallengeInitiateRequest, ChallengeInitiateResponse, ChallengeModule, ChallengeVerifyRequest, ChallengeVerifyResponse } from './types';
+export declare class ChallengeManagementModule implements ChallengeModule {
+    private http;
+    private logger;
+    constructor(http: HttpClient);
+    initiate(input?: ChallengeInitiateRequest): Promise<ChallengeInitiateResponse>;
+    verify(input: ChallengeVerifyRequest): Promise<ChallengeVerifyResponse>;
+}

package/dist/challenges/challenge.module.js

@@ -0,0 +1 @@
+import{getLogger as t}from"../core/logger.js";class r{constructor(r){this.logger=t(),this.http=r}async initiate(t={}){try{return await this.http.post("/challenges/initiate",t)}catch(r){throw this.logger.error("Failed to initiate challenge",{error:r}),r}}async verify(t){try{return await this.http.post("/challenges/verify",t)}catch(r){throw this.logger.error("Failed to verify challenge",{error:r}),r}}}export{r as ChallengeManagementModule};

package/dist/challenges/index.d.ts

@@ -0,0 +1,3 @@
+export { ChallengeManagementModule } from './challenge.module';
+export { ChallengeProvider, ChallengePurpose, ChallengeType } from './types';
+export type { BotMitigationState, ChallengeInitiateRequest, ChallengeInitiateResponse, ChallengeModule, ChallengeVerifyRequest, ChallengeVerifyResponse, RoutingChallenge, } from './types';

package/dist/challenges/public.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public challenge type surface.
+ *
+ * Mirrors exactly the challenge symbols on the root barrel — the runtime
+ * `ChallengeManagementModule` from `challenge.module` is deliberately not
+ * re-exported here.
+ */
+export { ChallengeProvider, ChallengePurpose, ChallengeType } from './types';
+export type { BotMitigationState, ChallengeInitiateRequest, ChallengeInitiateResponse, ChallengeModule, ChallengeVerifyRequest, ChallengeVerifyResponse, RoutingChallenge, } from './types';

package/dist/challenges/public.js

@@ -0,0 +1 @@
+import{ChallengeProvider as a,ChallengePurpose as r,ChallengeType as e}from"@fanfare-io/fanfare-sdk-contracts/challenges";export{a as ChallengeProvider,r as ChallengePurpose,e as ChallengeType};

package/dist/challenges/types.d.ts

@@ -0,0 +1,33 @@
+import { BotMitigationState, ChallengePurpose, ChallengeType, RoutingChallenge } from '@fanfare-io/fanfare-sdk-contracts/challenges';
+export { ChallengeProvider, ChallengePurpose, ChallengeType } from '@fanfare-io/fanfare-sdk-contracts/challenges';
+export type { BotMitigationState, RoutingChallenge } from '@fanfare-io/fanfare-sdk-contracts/challenges';
+export type ChallengeInitiateRequest = {
+    purpose?: ChallengePurpose;
+    type?: ChallengeType;
+};
+export type ChallengeInitiateResponse = {
+    challenge?: RoutingChallenge;
+    botMitigation?: BotMitigationState;
+};
+export type ChallengeVerifyRequest = {
+    challengeId: string;
+    token: string;
+};
+export type ChallengeVerifyResponse = {
+    status: "passed";
+    passedUntil: string;
+} | {
+    status: "failed";
+    attemptsRemaining: number;
+    message?: string;
+    errorCodes?: string[];
+} | {
+    status: "blocked";
+    blockedUntil: string;
+    message: string;
+    errorCodes?: string[];
+};
+export interface ChallengeModule {
+    initiate(input?: ChallengeInitiateRequest): Promise<ChallengeInitiateResponse>;
+    verify(input: ChallengeVerifyRequest): Promise<ChallengeVerifyResponse>;
+}

package/dist/config/index.d.ts

@@ -0,0 +1,44 @@
+import { FanfareConfig } from '../types';
+/**
+ * API URLs by environment
+ */
+export declare const API_URLS: {
+    readonly production: "https://consumer.fanfare.io/api";
+    readonly development: "http://localhost:4802";
+};
+/**
+ * Beacon API URLs by environment
+ */
+export declare const BEACON_URLS: {
+    readonly production: "https://beacon.fanfare.io";
+    readonly development: "http://localhost:4803";
+};
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CONFIG: Partial<FanfareConfig>;
+/**
+ * Configuration manager
+ */
+export declare class Config {
+    private readonly config;
+    constructor(userConfig: FanfareConfig);
+    /**
+     * Get the API URL for the current environment
+     */
+    get apiUrl(): string;
+    /**
+     * Get the Beacon API URL for the current environment
+     */
+    get beaconUrl(): string;
+    /**
+     * Get the full configuration
+     */
+    get(): FanfareConfig & {
+        apiUrl?: string;
+    };
+    /**
+     * Get a specific configuration value
+     */
+    getValue<K extends keyof FanfareConfig>(key: K): K extends "apiUrl" ? string | undefined : Required<FanfareConfig>[K];
+}

package/dist/config/index.js

@@ -0,0 +1 @@
+import{createError as i}from"../core/errors.js";const n={production:"https://consumer.fanfare.io/api",development:"http://localhost:4802"},o={production:"https://beacon.fanfare.io",development:"http://localhost:4803"},t=/* @__PURE__ */new Set(["https://consumer.fanfare.io"]),e=/* @__PURE__ */new Set(["https://beacon.fanfare.io"]),r={environment:"production",auth:{persistSession:!0,sessionDuration:3600},logging:{level:"error"}};class a{constructor(n){if(this.config={organizationId:n.organizationId,publishableKey:n.publishableKey,environment:n.environment??r.environment??"production",apiUrl:n.apiUrl,credentials:n.credentials??"include",debug:n.debug??!1,auth:{...r.auth,...n.auth},logging:{...r.logging,...n.logging},sync:n.sync,beacon:n.beacon,features:{fingerprinting:n.features?.fingerprinting??!0}},!this.config.organizationId)throw i.invalidConfig("organizationId is required");if(!this.config.publishableKey)throw i.invalidConfig("publishableKey is required");"production"===this.config.environment&&(s("apiUrl",this.apiUrl,t),s("beacon.baseUrl",this.beaconUrl,e))}get apiUrl(){return this.config.apiUrl||n[this.config.environment]}get beaconUrl(){return this.config.beacon?.baseUrl||o[this.config.environment]}get(){return this.config}getValue(i){return this.config[i]}}function s(n,o,t){let e;try{e=new URL(o)}catch{throw i.invalidConfig(`${n} must be a valid URL in production`)}if("https:"!==e.protocol)throw i.invalidConfig(`${n} must use HTTPS in production`);if(!t.has(e.origin))throw i.invalidConfig(`${n} must use a trusted Fanfare destination in production`)}export{n as API_URLS,o as BEACON_URLS,a as Config,r as DEFAULT_CONFIG};

package/dist/core/client.d.ts

@@ -0,0 +1,15 @@
+import { FanfareConfig, FanfareSDK } from '../types';
+/** @internal Reset active instance guard (for testing only) */
+export declare function resetActiveInstance(): void;
+/**
+ * Initialize the Fanfare SDK
+ *
+ * @example
+ * ```typescript
+ * const fanfare = await Fanfare.init({
+ *   organizationId: 'org_123',
+ *   publishableKey: 'pk_live_xyz789'
+ * });
+ * ```
+ */
+export declare function init(config: FanfareConfig): Promise<FanfareSDK>;