@fanfare-io/fanfare-sdk-core 0.1.0

package/dist/state/events.d.ts

@@ -0,0 +1,342 @@
+import { AuctionStatus } from '../auctions/types';
+import { Session } from '../auth/types';
+import { DrawResult } from '../draws/types';
+import { SequenceOutcome } from '../experiences/journey.types';
+import { QueueConsumerState } from '../queues/types';
+import { SdkDistributionType } from '../types/distribution-type';
+export interface AuthEvents {
+    "auth:authenticated": {
+        session: Session;
+        isNew: boolean;
+    };
+    "auth:refreshed": {
+        session: Session;
+    };
+    "auth:logout": {
+        reason?: string;
+    };
+    "auth:error": {
+        error: Error;
+        context: string;
+    };
+}
+export interface QueueEvents {
+    "queue:entered": {
+        queueId: string;
+        position: number;
+        estimatedWaitTime?: number;
+    };
+    "queue:left": {
+        queueId: string;
+        reason?: string;
+    };
+    "queue:position-changed": {
+        queueId: string;
+        position: number;
+        previousPosition: number;
+    };
+    "queue:granted": {
+        queueId: string;
+        grant: string;
+    };
+    "queue:expired": {
+        queueId: string;
+    };
+    "queue:error": {
+        queueId: string;
+        error: Error;
+    };
+    "queue:status-updated": {
+        queueId: string;
+        status: QueueConsumerState;
+    };
+}
+export interface DrawEvents {
+    "draw:entered": {
+        drawId: string;
+        entryNumber?: string;
+    };
+    "draw:left": {
+        drawId: string;
+    };
+    "draw:won": {
+        drawId: string;
+        result: DrawResult;
+    };
+    "draw:lost": {
+        drawId: string;
+        result: DrawResult;
+    };
+    "draw:expired": {
+        drawId: string;
+    };
+    "draw:error": {
+        drawId: string;
+        error: Error;
+    };
+    "draw:status-updated": {
+        drawId: string;
+        status: string;
+    };
+}
+export interface AuctionEvents {
+    "auction:entered": {
+        auctionId: string;
+    };
+    "auction:bid-placed": {
+        auctionId: string;
+        amount: string;
+        status: string;
+    };
+    "auction:outbid": {
+        auctionId: string;
+        yourBid: string;
+        highestBid: string;
+    };
+    "auction:winning": {
+        auctionId: string;
+        amount: string;
+        highestBid: string;
+    };
+    "auction:won": {
+        auctionId: string;
+        winningBid: string;
+    };
+    "auction:lost": {
+        auctionId: string;
+        highestBid: string;
+    };
+    "auction:left": {
+        auctionId: string;
+    };
+    "auction:error": {
+        auctionId: string;
+        error: Error;
+    };
+    "auction:status-updated": {
+        auctionId: string;
+        status: AuctionStatus;
+    };
+    "auction:watching-started": {
+        auctionId: string;
+        intervalMs: number;
+    };
+    "auction:watching-stopped": {
+        auctionId: string;
+    };
+    "auction:bid-updated": {
+        auctionId: string;
+        highestBid: string;
+        bidCount: number;
+    };
+    "auction:history-fetched": {
+        auctionId: string;
+        bidCount: number;
+    };
+    "auction:auto-rebid-enabled": {
+        auctionId: string;
+        maxBid: string;
+        increment: string;
+    };
+    "auction:auto-rebid-disabled": {
+        auctionId: string;
+        finalRebidCount: number;
+    };
+    "auction:auto-rebid-placed": {
+        auctionId: string;
+        amount: string;
+        remainingBudget: string;
+        status: string;
+    };
+    "auction:auto-rebid-max-reached": {
+        auctionId: string;
+        maxBid: string;
+        wouldNeedToBid: string;
+    };
+    "auction:auto-rebid-failed": {
+        auctionId: string;
+        error: Error;
+    };
+}
+export interface WaitlistEvents {
+    "waitlist:entered": {
+        waitlistId: string;
+        sequenceId: string;
+        enteredAt: string;
+    };
+    "waitlist:left": {
+        waitlistId: string;
+    };
+    "waitlist:error": {
+        waitlistId: string;
+        error: string;
+    };
+}
+export interface TimedReleaseEvents {
+    "timed_release:entered": {
+        timedReleaseId: string;
+        enteredAt: string;
+    };
+    "timed_release:left": {
+        timedReleaseId: string;
+    };
+    "timed_release:completed": {
+        timedReleaseId: string;
+        completedAt: string;
+    };
+    "timed_release:error": {
+        timedReleaseId: string;
+        error: Error;
+    };
+    "timed_release:status-updated": {
+        timedReleaseId: string;
+        status: string;
+    };
+}
+export interface ExperienceEvents {
+    "experience:entered": {
+        experienceId: string;
+        enteredAt: string;
+    };
+    "experience:left": {
+        experienceId: string;
+    };
+    "experience:sequence-selected": {
+        sequenceId: string;
+    };
+    "experience:distribution-entered": {
+        distributionType: SdkDistributionType;
+        distributionId: string;
+    };
+    "experience:error": {
+        experienceId: string;
+        error: string;
+    };
+}
+/**
+ * Categorisation of a `journey:error` event. New kinds may be added; consumers
+ * should use a default branch or the wildcard listener to avoid silent drops.
+ */
+export type JourneyErrorKind = "protocolError";
+/**
+ * Payload shape for `journey:error`. `protocolError` is emitted by the shared
+ * response-parse helper (`core/parse-response.ts`) when a server response
+ * fails valibot validation. `endpoint` identifies the call site for triage;
+ * `issues` carries the raw valibot issue list for diagnosis.
+ *
+ * Defined as a type alias (not an interface) so the structural shape
+ * satisfies `Record<string, unknown>` consumers like the Google Analytics
+ * adapter that subscribes via a wide event listener.
+ */
+export type JourneyErrorPayload = {
+    kind: JourneyErrorKind;
+    endpoint: string;
+    message: string;
+    requestId?: string;
+    issues?: unknown;
+};
+export interface JourneyEvents {
+    "journey:granted": {
+        experienceId: string;
+        sequenceId: string;
+        grant: string;
+    };
+    "journey:grant-claimed": {
+        experienceId: string;
+        sequenceId: string;
+        grant: string;
+    };
+    "journey:ended": {
+        experienceId: string;
+        sequenceId: string;
+        outcome: SequenceOutcome;
+    };
+    "journey:phase-changed": {
+        experienceId: string;
+        journeyStage: string;
+        sequencePhase?: string;
+    };
+    "journey:error": JourneyErrorPayload;
+}
+export interface NetworkEvents {
+    "network:online": Record<string, never>;
+    "network:offline": Record<string, never>;
+    "network:error": {
+        error: Error;
+        request?: {
+            url: string;
+            method: string;
+        };
+    };
+}
+export interface StateEvents {
+    "state:restored": {
+        experiences: string[];
+    };
+    "state:cleared": Record<string, never>;
+    "state:sync": {
+        key: string;
+        value: Session | null;
+    };
+}
+export interface BeaconEvents {
+    "beacon:queued": {
+        event: {
+            eventName: string;
+            eventId?: string;
+        };
+    };
+    "beacon:sent": {
+        count: number;
+    };
+    "beacon:error": {
+        error: unknown;
+        event?: unknown;
+        events?: unknown;
+        count?: number;
+    };
+}
+export interface SDKEvents extends AuthEvents, QueueEvents, DrawEvents, AuctionEvents, WaitlistEvents, TimedReleaseEvents, ExperienceEvents, JourneyEvents, NetworkEvents, StateEvents, BeaconEvents {
+}
+export type SDKEventKey = keyof SDKEvents;
+export type SDKEventData<K extends SDKEventKey> = SDKEvents[K];
+type EventListener<K extends SDKEventKey> = (data: SDKEventData<K>) => void;
+type WildcardListener = (event: SDKEventKey, data: SDKEventData<SDKEventKey>) => void;
+export declare class EventBus {
+    private listeners;
+    private logger;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends SDKEventKey>(event: K, listener: EventListener<K>): () => void;
+    on(event: "*", listener: WildcardListener): () => void;
+    /**
+     * Subscribe to an event once
+     */
+    once<K extends SDKEventKey>(event: K, listener: EventListener<K>): () => void;
+    /**
+     * Emit an event
+     */
+    emit<K extends SDKEventKey>(event: K, data: SDKEventData<K>): void;
+    /**
+     * Remove all listeners for an event
+     */
+    off(event?: SDKEventKey | "*"): void;
+    /**
+     * Get listener count for an event
+     */
+    listenerCount(event?: SDKEventKey | "*"): number;
+    /**
+     * Get all registered events
+     */
+    events(): (SDKEventKey | "*")[];
+}
+/**
+ * Get event bus instance
+ */
+export declare function getEventBus(): EventBus;
+/**
+ * Reset event bus (for testing)
+ */
+export declare function resetEventBus(): void;
+export {};

package/dist/state/events.js

@@ -0,0 +1 @@
+import{getLogger as e}from"../core/logger.js";class t{constructor(){this.listeners=/* @__PURE__ */new Map,this.logger=e()}on(e,t){this.listeners.has(e)||this.listeners.set(e,/* @__PURE__ */new Set);const r=this.listeners.get(e);return r&&(r.add(t),this.logger.debug("Event listener added",{event:e,listenerCount:r.size})),()=>{const r=this.listeners.get(e);r&&(r.delete(t),0===r.size&&this.listeners.delete(e),this.logger.debug("Event listener removed",{event:e}))}}once(e,t){const r=this.on(e,e=>{r(),t(e)});return r}emit(e,t){this.logger.debug("Event emitted",{event:e,data:t});const r=this.listeners.get(e);r&&r.forEach(r=>{try{r(t)}catch(s){this.logger.error("Error in event listener",{event:e,error:s})}});const s=this.listeners.get("*");s&&s.forEach(r=>{try{r(e,t)}catch(s){this.logger.error("Error in wildcard listener",{event:e,error:s})}})}off(e){e?(this.listeners.delete(e),this.logger.debug("All listeners removed for event",{event:e})):(this.listeners.clear(),this.logger.debug("All event listeners cleared"))}listenerCount(e){if(e)return this.listeners.get(e)?.size||0;let t=0;return this.listeners.forEach(e=>{t+=e.size}),t}events(){return Array.from(this.listeners.keys())}}let r=null;function s(){return r||(r=new t),r}export{t as EventBus,s as getEventBus};

package/dist/state/store.d.ts

@@ -0,0 +1,48 @@
+import { Session } from '../auth/types';
+import { JourneySnapshot } from '../experiences/journey.types';
+import { ExperienceSession } from '../experiences/types';
+import { CapabilityTokenRecord, DistributionCapabilityBinding } from './capability-token-registry';
+export interface SDKState {
+    session: Session | null;
+    refreshToken: string | null;
+    beaconToken: string | null;
+    activeExperiences: Record<string, ExperienceSession>;
+    activeJourneys: Record<string, JourneySnapshot>;
+    capabilityTokens: Record<string, CapabilityTokenRecord>;
+    distributionCapabilityIndex: Record<string, DistributionCapabilityBinding>;
+    versionMap: Record<string, number>;
+    setSession: (session: Session | null) => void;
+    setRefreshToken: (token: string | null) => void;
+    setBeaconToken: (token: string | null) => void;
+    addActiveExperience: (experienceId: string, session: ExperienceSession) => void;
+    removeActiveExperience: (experienceId: string) => void;
+    updateExperienceSession: (experienceId: string, updates: Partial<ExperienceSession>) => void;
+    clearActiveExperiences: () => void;
+    setJourneyState: (experienceId: string, journey: JourneySnapshot) => void;
+    removeJourney: (experienceId: string) => void;
+    clearJourneys: () => void;
+    upsertCapabilityToken: (key: string, record: CapabilityTokenRecord) => void;
+    bindDistribution: (distributionId: string, binding: DistributionCapabilityBinding) => void;
+    clearCapabilityContext: (experienceId: string, sequenceId: string) => void;
+    clearExperienceCapabilityContext: (experienceId: string) => void;
+    clearExpiredCapabilityTokens: (nowMs: number) => void;
+    clearAll: () => void;
+}
+export declare const useSDKStore: Omit<import('zustand/vanilla').StoreApi<SDKState>, "setState" | "persist"> & {
+    setState(partial: SDKState | Partial<SDKState> | ((state: SDKState) => SDKState | Partial<SDKState>), replace?: false | undefined): unknown;
+    setState(state: SDKState | ((state: SDKState) => SDKState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import('zustand/middleware').PersistOptions<SDKState, unknown, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: SDKState) => void) => () => void;
+        onFinishHydration: (fn: (state: SDKState) => void) => () => void;
+        getOptions: () => Partial<import('zustand/middleware').PersistOptions<SDKState, unknown, unknown>>;
+    };
+};
+/**
+ * Reset SDK store (for testing)
+ */
+export declare function resetSDKStore(): void;
+export declare const getSDKStore: () => SDKState;

package/dist/state/store.js

@@ -0,0 +1 @@
+import{persist as e,createJSONStorage as i}from"zustand/middleware";import{createStore as n}from"zustand/vanilla";import{isBrowser as t,isStorageAvailable as s}from"../core/utils.js";import{getEventBus as r}from"./events.js";const o=["session","activeJourneys","versionMap"],a=["session"];function c(e){if(!e||"object"!=typeof e)return{};const i=e,n={};for(const t of a)t in i&&(n[t]=i[t]);return n}function p(e){if(!e||"object"!=typeof e)return{};const i=e,n={};for(const t of o)t in i&&(n[t]="versionMap"===t?c(i[t]):i[t]);return n}const l=n()(e((e,i)=>({session:null,refreshToken:null,beaconToken:null,activeExperiences:{},activeJourneys:{},capabilityTokens:{},distributionCapabilityIndex:{},versionMap:{},setSession:n=>{e(e=>({session:n,versionMap:{...e.versionMap,session:(e.versionMap.session||0)+1}})),n&&r().emit("auth:authenticated",{session:n,isNew:!i().session})},setRefreshToken:i=>{e(e=>({refreshToken:i,versionMap:{...e.versionMap,refreshToken:(e.versionMap.refreshToken||0)+1}}))},setBeaconToken:i=>{e({beaconToken:i})},addActiveExperience:(i,n)=>{e(e=>({activeExperiences:{...e.activeExperiences,[i]:n},versionMap:{...e.versionMap,activeExperiences:(e.versionMap.activeExperiences||0)+1}}))},removeActiveExperience:i=>{e(e=>{const{[i]:n,...t}=e.activeExperiences;return{activeExperiences:t,versionMap:{...e.versionMap,activeExperiences:(e.versionMap.activeExperiences||0)+1}}})},updateExperienceSession:(i,n)=>{e(e=>{const t=e.activeExperiences[i];return t?{activeExperiences:{...e.activeExperiences,[i]:{...t,...n}},versionMap:{...e.versionMap,activeExperiences:(e.versionMap.activeExperiences||0)+1}}:e})},clearActiveExperiences:()=>{e(e=>({activeExperiences:{},versionMap:{...e.versionMap,activeExperiences:(e.versionMap.activeExperiences||0)+1}}))},setJourneyState:(i,n)=>{e(e=>({activeJourneys:{...e.activeJourneys,[i]:n}}))},removeJourney:i=>{e(e=>{const{[i]:n,...t}=e.activeJourneys;return{activeJourneys:t}})},clearJourneys:()=>{e(()=>({activeJourneys:{}}))},upsertCapabilityToken:(i,n)=>{e(e=>({capabilityTokens:{...e.capabilityTokens,[i]:n},versionMap:{...e.versionMap,capabilityTokens:(e.versionMap.capabilityTokens||0)+1}}))},bindDistribution:(i,n)=>{e(e=>({distributionCapabilityIndex:{...e.distributionCapabilityIndex,[i]:n},versionMap:{...e.versionMap,distributionCapabilityIndex:(e.versionMap.distributionCapabilityIndex||0)+1}}))},clearCapabilityContext:(i,n)=>{e(e=>{const t=`${i}:${n}`,{[t]:s,...r}=e.capabilityTokens,o={};for(const[i,n]of Object.entries(e.distributionCapabilityIndex))n.sequenceKey!==t&&(o[i]=n);return{capabilityTokens:r,distributionCapabilityIndex:o,versionMap:{...e.versionMap,capabilityTokens:(e.versionMap.capabilityTokens||0)+1,distributionCapabilityIndex:(e.versionMap.distributionCapabilityIndex||0)+1}}})},clearExperienceCapabilityContext:i=>{e(e=>{const n={};for(const[s,r]of Object.entries(e.capabilityTokens))r.experienceId!==i&&(n[s]=r);const t={};for(const[s,r]of Object.entries(e.distributionCapabilityIndex))r.experienceId!==i&&(t[s]=r);return{capabilityTokens:n,distributionCapabilityIndex:t,versionMap:{...e.versionMap,capabilityTokens:(e.versionMap.capabilityTokens||0)+1,distributionCapabilityIndex:(e.versionMap.distributionCapabilityIndex||0)+1}}})},clearExpiredCapabilityTokens:i=>{e(e=>{const n=/* @__PURE__ */new Set,t={};for(const[r,o]of Object.entries(e.capabilityTokens))o.expiresAtMs&&o.expiresAtMs<=i?n.add(r):t[r]=o;if(0===n.size)return e;const s={};for(const[i,r]of Object.entries(e.distributionCapabilityIndex))n.has(r.sequenceKey)||(s[i]=r);return{capabilityTokens:t,distributionCapabilityIndex:s,versionMap:{...e.versionMap,capabilityTokens:(e.versionMap.capabilityTokens||0)+1,distributionCapabilityIndex:(e.versionMap.distributionCapabilityIndex||0)+1}}})},clearAll:()=>{e({session:null,refreshToken:null,beaconToken:null,activeExperiences:{},activeJourneys:{},capabilityTokens:{},distributionCapabilityIndex:{},versionMap:{}}),r().emit("state:cleared",{})}}),{name:"fanfare-sdk-state",storage:i(()=>(()=>{if(t()&&s("localStorage"))return window.localStorage;const e={};return{getItem:i=>Object.prototype.hasOwnProperty.call(e,i)?e[i]:null,setItem:(i,n)=>{e[i]=n},removeItem:i=>{delete e[i]}}})()),partialize:e=>p(e),version:3,merge:(e,i)=>({...i,...p(e)}),onRehydrateStorage:()=>e=>{if(e){const i=e.activeJourneys??{};r().emit("state:restored",{experiences:Object.keys(i)})}}}));function v(){l.setState({session:null,refreshToken:null,beaconToken:null,activeExperiences:{},activeJourneys:{},capabilityTokens:{},distributionCapabilityIndex:{},versionMap:{}}),b=null}let b=null;const u=()=>b||(b=new Proxy({},{get:(e,i)=>Reflect.has(e,i)?e[i]:l.getState()[i],has:(e,i)=>Reflect.has(e,i)||i in l.getState(),ownKeys:e=>{const i=new Set(Reflect.ownKeys(l.getState()));for(const n of Reflect.ownKeys(e))i.add(n);return Array.from(i)},getOwnPropertyDescriptor:(e,i)=>{const n=Object.getOwnPropertyDescriptor(e,i);if(n)return n;const t=Object.getOwnPropertyDescriptor(l.getState(),i);return t?{...t,configurable:!0}:void 0}}),b);export{u as getSDKStore,v as resetSDKStore,l as useSDKStore};

package/dist/sync/broadcast-transport.d.ts

@@ -0,0 +1,19 @@
+import { ITransport } from './transport-interface';
+/**
+ * Check if BroadcastChannel API is supported
+ */
+export declare function isBroadcastChannelSupported(): boolean;
+/**
+ * BroadcastChannel transport implementation
+ */
+export declare class BroadcastChannelTransport implements ITransport {
+    private channelName;
+    private channel;
+    private messageHandler?;
+    private logger;
+    constructor(channelName: string);
+    send(message: unknown): void;
+    onMessage(handler: (event: MessageEvent) => void): () => void;
+    close(): void;
+    isAvailable(): boolean;
+}

package/dist/sync/broadcast-transport.js

@@ -0,0 +1 @@
+import{getLogger as e}from"../core/logger.js";import{isBrowser as a}from"../core/utils.js";function n(){if(!a())return!1;try{return"undefined"!=typeof window&&"BroadcastChannel"in window&&"function"==typeof window.BroadcastChannel}catch{return!1}}class s{constructor(a){if(this.channelName=a,this.channel=null,this.logger=e(),n())try{this.channel=new BroadcastChannel(a),this.logger.debug("BroadcastChannelTransport initialized",{channelName:a})}catch(s){this.logger.warn("Failed to create BroadcastChannel",{error:s,channelName:a}),this.channel=null}else this.logger.debug("BroadcastChannel not supported")}send(e){if(this.channel)try{this.channel.postMessage(e),this.logger.debug("Message sent via BroadcastChannel",{message:e})}catch(a){this.logger.warn("Failed to send message via BroadcastChannel",{error:a,message:e})}else this.logger.debug("BroadcastChannel not available, message not sent",{message:e})}onMessage(e){return this.channel?(this.messageHandler=e,this.channel.onmessage=e=>{this.logger.debug("Message received via BroadcastChannel",{data:e.data}),this.messageHandler&&this.messageHandler(e)},()=>{this.channel&&(this.channel.onmessage=null),this.messageHandler=void 0,this.logger.debug("BroadcastChannel listener removed")}):(this.logger.debug("BroadcastChannel not available, listener not added"),()=>{})}close(){if(this.channel){try{this.channel.close(),this.logger.debug("BroadcastChannel closed",{channelName:this.channelName})}catch(e){this.logger.warn("Error closing BroadcastChannel",{error:e})}this.channel=null}this.messageHandler=void 0}isAvailable(){return null!==this.channel}}export{s as BroadcastChannelTransport,n as isBroadcastChannelSupported};

package/dist/sync/cross-tab-coordinator.d.ts

@@ -0,0 +1,44 @@
+import { ExperienceJourney } from '../experiences/journey';
+interface CrossTabCoordinatorOptions {
+    enabled?: boolean;
+    channelName?: string;
+}
+export declare class CrossTabCoordinator {
+    private readonly transport;
+    private readonly logger;
+    private readonly enabled;
+    private readonly localOnly;
+    private readonly liveJourneys;
+    private readonly activeTabs;
+    private readonly runtimeOwners;
+    private readonly runtimeCursors;
+    private readonly unsubscribers;
+    private heartbeatTimer?;
+    private bootstrapTimer?;
+    private isApplyingRemoteUpdate;
+    private leaderId;
+    private bootstrapSettled;
+    constructor(options: CrossTabCoordinatorOptions);
+    registerJourney(journey: ExperienceJourney): void;
+    unregisterJourney(experienceId: string): void;
+    close(): void;
+    isEnabled(): boolean;
+    getTabId(): string;
+    isLeader(): boolean;
+    private handleMessage;
+    private handleLocalStateChange;
+    private applyBootstrapResponse;
+    private applyVersionedStoreField;
+    private applyJourneyUpsert;
+    private applyJourneyRemove;
+    private applyRuntimeState;
+    private syncRuntimeOwnership;
+    private stopRuntimeOwner;
+    private sendHeartbeat;
+    private requestBootstrap;
+    private markBootstrapSettled;
+    private recordHeartbeat;
+    private pruneDeadTabs;
+    private updateLeader;
+}
+export {};

package/dist/sync/cross-tab-coordinator.js

@@ -0,0 +1 @@
+import{getLogger as e}from"../core/logger.js";import{deepClone as t}from"../core/utils.js";import{useSDKStore as i}from"../state/store.js";import{isHeartbeatMessage as s,isDurableBootstrapRequestMessage as r,isDurableBootstrapResponseMessage as n,isSessionUpdateMessage as a,isCapabilityTokensUpdateMessage as o,isDistributionCapabilityIndexUpdateMessage as p,isJourneyUpsertMessage as d,isJourneyRemoveMessage as h,isRuntimeStateMessage as l}from"./protocol.js";import{ProtocolTransport as u}from"./protocol-transport.js";class c{constructor(c){if(this.logger=e(),this.liveJourneys=/* @__PURE__ */new Map,this.activeTabs=/* @__PURE__ */new Map,this.runtimeOwners=/* @__PURE__ */new Map,this.runtimeCursors=/* @__PURE__ */new Map,this.unsubscribers=[],this.isApplyingRemoteUpdate=!1,this.leaderId=null,this.bootstrapSettled=!1,this.handleMessage=e=>{if(s(e))return this.recordHeartbeat(e.source,e.payload.active),void this.markBootstrapSettled();if(this.recordHeartbeat(e.source,!0),this.markBootstrapSettled(),r(e)){if(this.isLeader()){const e=i.getState();this.transport.sendDurableBootstrapResponse({session:t(e.session),sessionVersion:e.versionMap.session||0,capabilityTokens:t(e.capabilityTokens),capabilityTokensVersion:e.versionMap.capabilityTokens||0,distributionCapabilityIndex:t(e.distributionCapabilityIndex),distributionCapabilityIndexVersion:e.versionMap.distributionCapabilityIndex||0,journeys:Object.fromEntries(Object.entries(e.activeJourneys).map(([e,i])=>[e,{snapshot:t(i),version:i.revision}]))})}}else n(e)?this.applyBootstrapResponse(e.payload):a(e)?this.applyVersionedStoreField("session",e.payload.value,e.payload.version):o(e)?this.applyVersionedStoreField("capabilityTokens",e.payload.value,e.payload.version):p(e)?this.applyVersionedStoreField("distributionCapabilityIndex",e.payload.value,e.payload.version):d(e)?this.applyJourneyUpsert(e.payload.experienceId,e.payload.snapshot,e.payload.version):h(e)?this.applyJourneyRemove(e.payload.experienceId,e.payload.version):l(e)&&this.applyRuntimeState(e.payload)},this.transport=new u(c.channelName),this.enabled=(c.enabled??!0)&&this.transport.isAvailable(),this.localOnly=!this.enabled,this.unsubscribers.push(i.subscribe((e,t)=>{this.isApplyingRemoteUpdate||this.handleLocalStateChange(e,t)})),this.enabled)return this.unsubscribers.push(this.transport.onMessage(this.handleMessage)),this.sendHeartbeat(!0),this.heartbeatTimer=setInterval(()=>{this.sendHeartbeat(!0),this.pruneDeadTabs()},2e3),this.requestBootstrap(),void(this.bootstrapTimer=setTimeout(()=>{this.markBootstrapSettled()},100));this.leaderId=this.transport.getTabId(),this.activeTabs.set(this.transport.getTabId(),Date.now()),this.bootstrapSettled=!0}registerJourney(e){this.liveJourneys.set(e.getExperienceId(),e),this.syncRuntimeOwnership()}unregisterJourney(e){this.stopRuntimeOwner(e,!1),this.liveJourneys.delete(e),this.runtimeCursors.delete(e)}close(){this.enabled&&this.sendHeartbeat(!1),this.bootstrapTimer&&(clearTimeout(this.bootstrapTimer),this.bootstrapTimer=void 0),this.heartbeatTimer&&(clearInterval(this.heartbeatTimer),this.heartbeatTimer=void 0);for(const e of Array.from(this.runtimeOwners.keys()))this.stopRuntimeOwner(e,!1);for(const e of this.unsubscribers)e();this.unsubscribers.length=0,this.transport.close()}isEnabled(){return this.enabled}getTabId(){return this.transport.getTabId()}isLeader(){return this.leaderId===this.transport.getTabId()}handleLocalStateChange(e,i){this.enabled&&e.session!==i.session&&this.transport.sendSessionUpdate(t(e.session),e.versionMap.session||0),this.enabled&&e.capabilityTokens!==i.capabilityTokens&&this.transport.sendCapabilityTokensUpdate(t(e.capabilityTokens),e.versionMap.capabilityTokens||0),this.enabled&&e.distributionCapabilityIndex!==i.distributionCapabilityIndex&&this.transport.sendDistributionCapabilityIndexUpdate(t(e.distributionCapabilityIndex),e.versionMap.distributionCapabilityIndex||0);const s=e.activeJourneys,r=i.activeJourneys,n=/* @__PURE__ */new Set([...Object.keys(s),...Object.keys(r)]);for(const a of n){const e=s[a],i=r[a];!this.enabled||!e||i&&e.revision===i.revision?this.enabled&&!e&&i&&this.transport.sendJourneyRemove(a,i.revision+1):this.transport.sendJourneyUpsert(a,t(e),e.revision)}s!==r&&this.syncRuntimeOwnership()}applyBootstrapResponse(e){this.applyVersionedStoreField("session",e.session,e.sessionVersion),this.applyVersionedStoreField("capabilityTokens",e.capabilityTokens,e.capabilityTokensVersion),this.applyVersionedStoreField("distributionCapabilityIndex",e.distributionCapabilityIndex,e.distributionCapabilityIndexVersion);for(const[t,i]of Object.entries(e.journeys))this.applyJourneyUpsert(t,i.snapshot,i.version)}applyVersionedStoreField(e,t,s){const r=i.getState();s<=(r.versionMap[e]||0)||(this.isApplyingRemoteUpdate=!0,i.setState({[e]:t,versionMap:{...r.versionMap,[e]:s}}),this.isApplyingRemoteUpdate=!1)}applyJourneyUpsert(e,t,s){const r=i.getState(),n=r.activeJourneys[e];n&&n.revision>=s||(this.isApplyingRemoteUpdate=!0,i.setState({activeJourneys:{...r.activeJourneys,[e]:t}}),this.isApplyingRemoteUpdate=!1,this.liveJourneys.get(e)?.reconcileSyncedSnapshot(t),this.syncRuntimeOwnership())}applyJourneyRemove(e,t){const s=i.getState(),r=s.activeJourneys[e];if(r&&r.revision>=t)return;const{[e]:n,...a}=s.activeJourneys;this.isApplyingRemoteUpdate=!0,i.setState({activeJourneys:a}),this.isApplyingRemoteUpdate=!1,this.liveJourneys.get(e)?.reconcileSyncedSnapshot(null),this.syncRuntimeOwnership()}applyRuntimeState(e){if(e.leaderId!==this.leaderId)return;const t=this.liveJourneys.get(e.experienceId);if(!t||this.isLeader())return;const i=t.getRuntimeBinding();if(!i||i.sequenceId!==e.sequenceId||i.participationId!==e.participationId||i.participationType!==e.participationType)return;const s=this.runtimeCursors.get(e.experienceId);s&&s.leaderId===e.leaderId&&s.runtimeVersion>=e.runtimeVersion||(this.runtimeCursors.set(e.experienceId,{leaderId:e.leaderId,runtimeVersion:e.runtimeVersion}),t.applyRuntimeState(e.state??null))}syncRuntimeOwnership(){if(this.bootstrapSettled){for(const[e,i]of this.liveJourneys.entries()){const s=i.getRuntimeBinding(),r=this.runtimeOwners.get(e);if(!this.isLeader()||!s){r?this.stopRuntimeOwner(e,!0):s||i.applyRuntimeState(null);continue}const n=`${s.sequenceId}:${s.participationType}:${s.participationId}`;if(r?.bindingKey===n)continue;r&&this.stopRuntimeOwner(e,!0),i.startRuntimeMonitoring();const a=i.getRuntimeDisplayAtom();if(!a)continue;let o=0;const p=i=>{o+=1,this.enabled&&this.transport.sendRuntimeState({experienceId:e,sequenceId:s.sequenceId,participationId:s.participationId,participationType:s.participationType,leaderId:this.transport.getTabId(),runtimeVersion:o,state:t(i.get())})},d=a.listen(()=>{p(a)});p(a),this.runtimeOwners.set(e,{bindingKey:n,sequenceId:s.sequenceId,participationId:s.participationId,participationType:s.participationType,unsubscribe:d,runtimeVersion:o})}for(const e of Array.from(this.runtimeOwners.keys()))this.liveJourneys.has(e)||this.stopRuntimeOwner(e,!0)}}stopRuntimeOwner(e,t){const i=this.runtimeOwners.get(e),s=this.liveJourneys.get(e);i?(i.unsubscribe(),t&&this.enabled&&this.isLeader()&&this.transport.sendRuntimeState({experienceId:e,sequenceId:i.sequenceId,participationId:i.participationId,participationType:i.participationType,leaderId:this.transport.getTabId(),runtimeVersion:i.runtimeVersion+1,state:null}),s?.stopRuntimeMonitoring(!0),this.runtimeOwners.delete(e)):this.runtimeOwners.delete(e)}sendHeartbeat(e){this.enabled&&(this.transport.sendHeartbeat(e),this.recordHeartbeat(this.transport.getTabId(),e))}requestBootstrap(){this.enabled&&this.transport.sendDurableBootstrapRequest()}markBootstrapSettled(){this.bootstrapSettled||(this.bootstrapSettled=!0,this.bootstrapTimer&&(clearTimeout(this.bootstrapTimer),this.bootstrapTimer=void 0),this.syncRuntimeOwnership())}recordHeartbeat(e,t){t||e===this.transport.getTabId()?this.activeTabs.set(e,Date.now()):this.activeTabs.delete(e),this.updateLeader()}pruneDeadTabs(){const e=Date.now();let t=!1;for(const[i,s]of this.activeTabs.entries())i!==this.transport.getTabId()&&e-s>6e3&&(this.activeTabs.delete(i),t=!0);t&&this.updateLeader()}updateLeader(){if(this.localOnly)return void(this.leaderId=this.transport.getTabId());const e=[this.transport.getTabId(),...this.activeTabs.keys()].sort()[0]??this.transport.getTabId();e!==this.leaderId&&(this.leaderId=e,this.runtimeCursors.clear(),this.logger.info("Cross-tab leader changed",{leaderId:e,tabId:this.transport.getTabId(),isLeader:this.isLeader()}),this.isLeader()||this.requestBootstrap(),this.syncRuntimeOwnership())}}export{c as CrossTabCoordinator};

package/dist/sync/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cross-tab coordination internals.
+ */
+export { CrossTabCoordinator } from './cross-tab-coordinator';
+export { DEFAULT_CHANNEL_NAME, PROTOCOL_VERSION, SyncMessageSchema, isCapabilityTokensUpdateMessage, isDistributionCapabilityIndexUpdateMessage, isDurableBootstrapRequestMessage, isDurableBootstrapResponseMessage, isHeartbeatMessage, isJourneyRemoveMessage, isJourneyUpsertMessage, isRuntimeStateMessage, isSessionUpdateMessage, type CapabilityTokensUpdateMessage, type DistributionCapabilityIndexUpdateMessage, type DurableBootstrapRequestMessage, type DurableBootstrapResponseMessage, type HeartbeatMessage, type JourneyRemoveMessage, type JourneyUpsertMessage, type RuntimeStateMessage, type SessionUpdateMessage, type SyncMessage, } from './protocol';
+export { ProtocolTransport, type OutgoingMessage } from './protocol-transport';
+export { RecoveryManager, type RecoveryStrategy, type UpdateQueue } from './recovery';
+export { InterTabTransport } from './transport';

package/dist/sync/localstorage-transport.d.ts

@@ -0,0 +1,32 @@
+import { ITransport } from './transport-interface';
+/**
+ * Check if localStorage is available and working
+ */
+export declare function isLocalStorageSupported(): boolean;
+/**
+ * localStorage transport implementation
+ *
+ * Uses localStorage with storage events for cross-tab communication.
+ * Messages are stored with incrementing counters to maintain order.
+ */
+export declare class LocalStorageTransport implements ITransport {
+    private readonly channel;
+    private readonly tabId;
+    private messageHandler?;
+    private storageHandler?;
+    private cleanupInterval?;
+    private lastProcessedCounter;
+    private logger;
+    constructor(channel: string);
+    private generateTabId;
+    private getCounterKey;
+    private getMessageKey;
+    private initializeCounter;
+    private getNextCounter;
+    private startCleanupInterval;
+    private cleanupOldMessages;
+    send(message: unknown): void;
+    onMessage(handler: (event: MessageEvent) => void): () => void;
+    close(): void;
+    isAvailable(): boolean;
+}

package/dist/sync/localstorage-transport.js

@@ -0,0 +1 @@
+import{getLogger as e}from"../core/logger.js";import{isStorageAvailable as t}from"../core/utils.js";function a(){return t("localStorage")}class s{constructor(t){this.lastProcessedCounter=0,this.logger=e(),this.channel=t,this.tabId=this.generateTabId(),a()?(this.startCleanupInterval(),this.initializeCounter(),this.logger.debug("LocalStorageTransport initialized",{channel:t,tabId:this.tabId})):this.logger.warn("localStorage not supported")}generateTabId(){return`${Date.now()}-${Math.random().toString(36).substr(2,9)}`}getCounterKey(){return`fanfare-sdk:${this.channel}:counter`}getMessageKey(e){return`fanfare-sdk:${this.channel}:msg:${e}`}initializeCounter(){try{const e=localStorage.getItem(this.getCounterKey());e?this.lastProcessedCounter=parseInt(e,10):localStorage.setItem(this.getCounterKey(),"0")}catch(e){this.logger.warn("Failed to initialize counter",{error:e})}}getNextCounter(){try{const e=this.getCounterKey(),t=parseInt(localStorage.getItem(e)||"0",10)+1;return localStorage.setItem(e,t.toString()),t}catch(e){return this.logger.warn("Failed to get next counter",{error:e}),Date.now()}}startCleanupInterval(){"undefined"!=typeof window&&window.setInterval?this.cleanupInterval=window.setInterval(()=>{this.cleanupOldMessages()},2e3):"undefined"!=typeof setInterval&&(this.cleanupInterval=setInterval(()=>{this.cleanupOldMessages()},2e3))}cleanupOldMessages(){if(a())try{const e=Date.now(),t=5e3,a=[];for(let s=0;s<localStorage.length;s++){const r=localStorage.key(s);if(r&&r.startsWith(`fanfare-sdk:${this.channel}:msg:`))try{const s=localStorage.getItem(r);if(!s)continue;e-JSON.parse(s).timestamp>t&&a.push(r)}catch{a.push(r)}}a.forEach(e=>{try{localStorage.removeItem(e),this.logger.debug("Removed old message",{key:e})}catch(t){this.logger.warn("Failed to remove old message",{key:e,error:t})}})}catch(e){this.logger.warn("Cleanup failed",{error:e})}}send(e){if(a())try{const t=this.getNextCounter(),a={tabId:this.tabId,timestamp:Date.now(),data:e},s=this.getMessageKey(t);localStorage.setItem(s,JSON.stringify(a)),this.logger.debug("Message sent via localStorage",{key:s,message:e})}catch(t){if(this.logger.warn("Failed to send message via localStorage",{error:t,message:e}),t instanceof Error&&"QuotaExceededError"===t.name){this.cleanupOldMessages();try{const t=this.getNextCounter(),a={tabId:this.tabId,timestamp:Date.now(),data:e},s=this.getMessageKey(t);localStorage.setItem(s,JSON.stringify(a))}catch{}}}else this.logger.debug("localStorage not available, message not sent",{message:e})}onMessage(e){return a()?(this.messageHandler=e,this.storageHandler=e=>{if(e.key&&e.newValue&&e.key.startsWith(`fanfare-sdk:${this.channel}:msg:`))try{const t=JSON.parse(e.newValue);if(t.tabId===this.tabId)return;const a=e.key.match(/msg:(\d+)$/);if(a){const s=parseInt(a[1],10);if(s>this.lastProcessedCounter){this.lastProcessedCounter=s,this.logger.debug("Message received via localStorage",{key:e.key,data:t.data,fromTab:t.tabId});const a=new MessageEvent("message",{data:t.data,origin:window.location.origin});this.messageHandler&&this.messageHandler(a)}}}catch(t){this.logger.warn("Failed to process storage event",{error:t,key:e.key})}},window.addEventListener("storage",this.storageHandler),()=>{this.storageHandler&&window.removeEventListener("storage",this.storageHandler),this.messageHandler=void 0,this.storageHandler=void 0,this.logger.debug("localStorage listener removed")}):(this.logger.debug("localStorage not available, listener not added"),()=>{})}close(){this.storageHandler&&(window.removeEventListener("storage",this.storageHandler),this.storageHandler=void 0),this.messageHandler=void 0,this.cleanupInterval&&("undefined"!=typeof window&&window.clearInterval?window.clearInterval(this.cleanupInterval):"undefined"!=typeof clearInterval&&clearInterval(this.cleanupInterval),this.cleanupInterval=void 0),this.cleanupOldMessages(),this.logger.debug("LocalStorageTransport closed",{channel:this.channel})}isAvailable(){return a()}}export{s as LocalStorageTransport,a as isLocalStorageSupported};

package/dist/sync/protocol-transport.d.ts

@@ -0,0 +1,51 @@
+import { CapabilityTokensUpdateMessage, DistributionCapabilityIndexUpdateMessage, DurableBootstrapRequestMessage, DurableBootstrapResponseMessage, HeartbeatMessage, JourneyRemoveMessage, JourneyUpsertMessage, RuntimeStateMessage, SessionUpdateMessage, SyncMessage } from './protocol';
+/**
+ * Message types that can be sent (without metadata)
+ */
+export type OutgoingMessage = Omit<DurableBootstrapRequestMessage, "id" | "timestamp" | "source" | "version"> | Omit<DurableBootstrapResponseMessage, "id" | "timestamp" | "source" | "version"> | Omit<SessionUpdateMessage, "id" | "timestamp" | "source" | "version"> | Omit<CapabilityTokensUpdateMessage, "id" | "timestamp" | "source" | "version"> | Omit<DistributionCapabilityIndexUpdateMessage, "id" | "timestamp" | "source" | "version"> | Omit<JourneyUpsertMessage, "id" | "timestamp" | "source" | "version"> | Omit<JourneyRemoveMessage, "id" | "timestamp" | "source" | "version"> | Omit<RuntimeStateMessage, "id" | "timestamp" | "source" | "version"> | Omit<HeartbeatMessage, "id" | "timestamp" | "source" | "version">;
+/**
+ * Protocol-aware transport for typed message exchange
+ */
+export declare class ProtocolTransport {
+    private transport;
+    private tabId;
+    private logger;
+    constructor(channelName?: string);
+    /**
+     * Send a message with automatic metadata addition and validation
+     */
+    sendMessage(message: OutgoingMessage): void;
+    /**
+     * Register a message handler with automatic validation
+     * @returns Unsubscribe function
+     */
+    onMessage(callback: (message: SyncMessage) => void): () => void;
+    /**
+     * Close the transport and clean up resources
+     */
+    close(): void;
+    /**
+     * Check if transport is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Get the tab ID for this instance
+     */
+    getTabId(): string;
+    /**
+     * Get the number of registered listeners
+     */
+    getListenerCount(): number;
+    sendDurableBootstrapRequest(): void;
+    sendDurableBootstrapResponse(payload: DurableBootstrapResponseMessage["payload"]): void;
+    sendSessionUpdate(value: unknown, version: number): void;
+    sendCapabilityTokensUpdate(value: unknown, version: number): void;
+    sendDistributionCapabilityIndexUpdate(value: unknown, version: number): void;
+    sendJourneyUpsert(experienceId: string, snapshot: unknown, version: number): void;
+    sendJourneyRemove(experienceId: string, version: number): void;
+    sendRuntimeState(payload: RuntimeStateMessage["payload"]): void;
+    /**
+     * Send a heartbeat message
+     */
+    sendHeartbeat(active: boolean): void;
+}

package/dist/sync/protocol-transport.js

@@ -0,0 +1 @@
+import*as e from"valibot";import{getLogger as s}from"../core/logger.js";import{generateId as t}from"../core/utils.js";import{DEFAULT_CHANNEL_NAME as r,SyncMessageSchema as o,PROTOCOL_VERSION as a}from"./protocol.js";import{InterTabTransport as i}from"./transport.js";class n{constructor(e=r){this.logger=s(),this.transport=new i(e),this.tabId=t(),this.logger.debug("ProtocolTransport initialized",{tabId:this.tabId,channelName:e})}sendMessage(s){const r={...s,id:t(),timestamp:Date.now(),source:this.tabId,version:a};try{const t=e.parse(o,r);this.transport.send(t),this.logger.debug("Protocol message sent",{type:s.type,id:r.id,source:this.tabId})}catch(i){this.logger.error("Invalid message format",{error:i,message:s})}}onMessage(s){return this.transport.on(t=>{try{const r=e.parse(o,t);if(r.source===this.tabId)return void this.logger.debug("Ignoring message from self",{type:r.type,id:r.id});this.logger.debug("Protocol message received",{type:r.type,id:r.id,source:r.source}),s(r)}catch(r){this.logger.warn("Received invalid message",{error:r,rawMessage:t})}})}close(){this.logger.debug("Closing ProtocolTransport",{tabId:this.tabId}),this.transport.close()}isAvailable(){return this.transport.isAvailable()}getTabId(){return this.tabId}getListenerCount(){return this.transport.getListenerCount()}sendDurableBootstrapRequest(){this.sendMessage({type:"durable:bootstrap:request",payload:{}})}sendDurableBootstrapResponse(e){this.sendMessage({type:"durable:bootstrap:response",payload:e})}sendSessionUpdate(e,s){this.sendMessage({type:"session:update",payload:{value:e,version:s}})}sendCapabilityTokensUpdate(e,s){this.sendMessage({type:"capability-tokens:update",payload:{value:e,version:s}})}sendDistributionCapabilityIndexUpdate(e,s){this.sendMessage({type:"distribution-capability-index:update",payload:{value:e,version:s}})}sendJourneyUpsert(e,s,t){this.sendMessage({type:"journey:upsert",payload:{experienceId:e,snapshot:s,version:t}})}sendJourneyRemove(e,s){this.sendMessage({type:"journey:remove",payload:{experienceId:e,version:s}})}sendRuntimeState(e){this.sendMessage({type:"runtime:state",payload:e})}sendHeartbeat(e){this.sendMessage({type:"heartbeat",payload:{active:e}})}}export{n as ProtocolTransport};