@fanfare-io/fanfare-sdk-core 0.1.0

package/dist/handoff/handoff.module.d.ts

@@ -0,0 +1,184 @@
+import { HttpClient } from '../core/http';
+import { AdmissionProofHeaders } from '../security/admission-proof';
+import { SdkHandoffDistributionType } from '../types/distribution-type';
+/**
+ * Parameters for minting a handoff token. consumerId/organizationId/experience
+ * are NOT accepted from the caller — the server derives them from the verified
+ * capability grant so a client cannot mint a token for another consumer, org,
+ * or experience. The grant is the consumer's proof that it holds admission to
+ * the experience; it lives in journey routing state
+ * (`routing.selected.capabilityGrant`).
+ */
+export interface CreateHandoffTokenParams {
+    capabilityGrant: string;
+    expiresIn?: number;
+}
+/**
+ * Parameters for building a handoff URL
+ */
+export interface BuildHandoffUrlParams {
+    baseUrl: string;
+    token: string;
+    additionalParams?: Record<string, string>;
+}
+/**
+ * Admission context returned by the server on redemption
+ */
+export interface AdmissionContext {
+    consumerId: string;
+    organizationId: string;
+    experienceId: string;
+    experienceType: SdkHandoffDistributionType;
+    /**
+     * Origin of the merchant page that minted the handoff, attested by the
+     * server (signed into the token, captured from the mint request's `Origin`
+     * header). Used as the `postMessage` target origin when the checkout iframe
+     * reports completion to the merchant parent. Absent when the server captured
+     * no origin at mint time.
+     */
+    sourceOrigin?: string;
+}
+/**
+ * Stored admission data in sessionStorage
+ */
+export interface StoredAdmission {
+    context: AdmissionContext;
+    storedAt: string;
+    /**
+     * ISO-8601 timestamp echoing the server-verified handoff token expiry. The
+     * admission is only valid until this instant; past it, the stored admission
+     * is cleared and checkout is no longer permitted.
+     */
+    expiresAt: string;
+}
+/**
+ * Validation result for stored admission
+ */
+export interface AdmissionValidationResult {
+    valid: boolean;
+    reason?: string;
+    admission?: StoredAdmission;
+}
+/**
+ * Result of redeeming a handoff token
+ */
+export interface ProcessHandoffResult {
+    context: AdmissionContext;
+}
+/**
+ * Parameters for completing checkout
+ */
+export interface CompleteCheckoutParams {
+    success: boolean;
+    orderId?: string;
+    reason?: string;
+}
+/**
+ * Checkout status information
+ */
+export interface CheckoutStatus {
+    hasAdmission: boolean;
+    admission?: StoredAdmission;
+    canCheckout: boolean;
+}
+/**
+ * Parameters for building checkout URL with admission
+ */
+export interface BuildCheckoutUrlParams {
+    baseUrl: string;
+    admission: StoredAdmission;
+    additionalParams?: Record<string, string>;
+}
+export interface BuildAdmissionProofHeadersParams {
+    url: string;
+    method?: string;
+    nonce?: string;
+}
+export interface HandoffModuleOptions {
+    /**
+     * Merchant origins allowed to receive embedded checkout postMessage events.
+     * When provided, embedded messages to any other source origin are dropped.
+     * Values must be exact origins like "https://shop.example.com";
+     * an empty array intentionally denies all source origins.
+     */
+    allowedSourceOrigins?: string[];
+}
+export type { AdmissionProofHeaders } from '../security/admission-proof';
+/**
+ * Message sent to parent window in embedded mode
+ */
+export interface EmbeddedMessage {
+    type: string;
+    payload: unknown;
+    source: "fanfare-sdk";
+    timestamp: string;
+}
+/**
+ * Handoff module for managing server-minted handoff tokens
+ */
+export declare class HandoffModule {
+    private logger;
+    private readonly http;
+    private readonly allowedSourceOrigins?;
+    private readonly ADMISSION_KEY;
+    constructor(http: HttpClient, options?: HandoffModuleOptions);
+    /**
+     * Request a server-minted handoff token.
+     *
+     * @param params Mint parameters
+     * @returns Opaque, signed, short-TTL token string
+     */
+    createHandoffToken(params: CreateHandoffTokenParams): Promise<string>;
+    /**
+     * Build a handoff URL with the token and additional parameters
+     */
+    buildHandoffUrl(params: BuildHandoffUrlParams): string;
+    /**
+     * Redeem a handoff token via the server and store the admission context.
+     *
+     * The server verifies the signature, enforces expiry, and enforces
+     * single-use (replay rejection). This method does not inspect the token.
+     *
+     * @param token Opaque handoff token
+     * @returns Admission context
+     * @throws Error if the server rejects the token (invalid, expired, replayed)
+     */
+    processHandoffToken(token: string): Promise<ProcessHandoffResult>;
+    /**
+     * Validate stored admission
+     */
+    validateAdmission(): Promise<AdmissionValidationResult>;
+    getAdmissionKeyThumbprint(): Promise<string | null>;
+    buildAdmissionProofHeaders(params: BuildAdmissionProofHeadersParams): Promise<AdmissionProofHeaders>;
+    buildAdmissionGrantValidationHeaders(params: BuildAdmissionProofHeadersParams): Promise<AdmissionProofHeaders>;
+    private storeAdmission;
+    private getStoredAdmission;
+    private clearAdmission;
+    /**
+     * Clear all handoff-related data from sessionStorage
+     */
+    clearHandoffData(): void;
+    /**
+     * Complete the checkout process
+     */
+    completeCheckout(params: CompleteCheckoutParams): Promise<void>;
+    /**
+     * Get the current checkout status
+     */
+    getCheckoutStatus(): Promise<CheckoutStatus>;
+    /**
+     * Build a checkout URL with admission data
+     */
+    buildCheckoutUrlWithAdmission(params: BuildCheckoutUrlParams): string;
+    /**
+     * Send a message to parent window if in embedded mode
+     */
+    private sendEmbeddedMessage;
+    private resolveEmbeddedTargetOrigin;
+    private requireAllowedSourceOrigin;
+    private requireValidOrigin;
+    /**
+     * Check if running in embedded mode (iframe)
+     */
+    isEmbedded(): boolean;
+}

package/dist/handoff/handoff.module.js

@@ -0,0 +1 @@
+import{getLogger as e}from"../core/logger.js";import{isBrowser as r}from"../core/utils.js";import{getAdmissionKeyThumbprint as o,buildAdmissionProofHeaders as t}from"../security/admission-proof.js";const n="X-Sequence-Capability-Grant";class i{constructor(r,o={}){this.logger=e(),this.ADMISSION_KEY="fanfare_admission_grant",this.http=r,o.allowedSourceOrigins&&(this.allowedSourceOrigins=new Set(o.allowedSourceOrigins.map(e=>this.requireValidOrigin(e))))}async createHandoffToken(e){const{capabilityGrant:r,expiresIn:o}=e;this.logger.debug("Requesting handoff token",{expiresIn:o});try{const e=await this.http.post("/handoff/mint",void 0!==o?{expiresInSeconds:o}:{},{headers:{[n]:r}});return this.logger.info("Handoff token minted",{expiresAt:e.expiresAt,tokenLength:e.token.length}),e.token}catch(t){const e=t instanceof Error?t:new Error(String(t));throw this.logger.error("Failed to mint handoff token",e),e}}buildHandoffUrl(e){const{baseUrl:r,token:o,additionalParams:t={}}=e;try{const e=new URL(r);e.searchParams.set("fanfare_token",o);for(const[r,o]of Object.entries(t))e.searchParams.set(r,o);return e.toString()}catch(n){const e=n instanceof Error?n:new Error(String(n));throw this.logger.error("Failed to build handoff URL",e),e}}async processHandoffToken(e){if(!r())throw new Error("Handoff tokens can only be processed in browser environment");let o;this.logger.debug("Redeeming handoff token",{tokenLength:e.length});try{o=await this.http.post("/handoff/redeem",{token:e})}catch(i){const e=i instanceof Error?i:new Error(String(i));throw this.logger.error("Failed to redeem handoff token",e),e}const t={consumerId:o.consumerId,organizationId:o.organizationId,experienceId:o.experienceId,experienceType:o.experienceType,...o.sourceOrigin?{sourceOrigin:o.sourceOrigin}:{}},n={context:t,storedAt:/* @__PURE__ */(new Date).toISOString(),expiresAt:o.expiresAt};return this.storeAdmission(n),this.logger.info("Handoff token redeemed",{consumerId:t.consumerId,organizationId:t.organizationId,experienceId:t.experienceId}),{context:t}}async validateAdmission(){if(!r())return{valid:!1,reason:"Not in browser environment"};try{const e=this.getStoredAdmission();if(!e)return{valid:!1,reason:"No admission found"};const r=Date.parse(e.expiresAt);if(Number.isNaN(r)||Date.now()>r)return this.clearAdmission(),{valid:!1,reason:"Admission has expired"};return await o()?{valid:!0,admission:e}:(this.logger.warn("Admission proof key is unavailable for stored admission"),this.clearAdmission(),{valid:!1,reason:"Admission proof is unavailable"})}catch(e){const r=e instanceof Error?e:new Error(String(e));return this.logger.error("Failed to validate admission",r),{valid:!1,reason:"Validation error: "+r.message}}}async getAdmissionKeyThumbprint(){return await o()}async buildAdmissionProofHeaders(e){const r=await t(e);if(!r)throw new Error("DPoP proof generation requires browser crypto support");return r}async buildAdmissionGrantValidationHeaders(e){return await this.buildAdmissionProofHeaders(e)}storeAdmission(e){try{if("undefined"==typeof sessionStorage)return void this.logger.warn("SessionStorage not available");sessionStorage.setItem(this.ADMISSION_KEY,JSON.stringify(e))}catch(r){this.logger.error("Failed to store admission",r instanceof Error?r:new Error(String(r)))}}getStoredAdmission(){try{if("undefined"==typeof sessionStorage)return null;const e=sessionStorage.getItem(this.ADMISSION_KEY);return e?JSON.parse(e):null}catch(e){return this.logger.error("Failed to get stored admission",e instanceof Error?e:new Error(String(e))),null}}clearAdmission(){try{if("undefined"==typeof sessionStorage)return;sessionStorage.removeItem(this.ADMISSION_KEY)}catch(e){this.logger.error("Failed to clear admission",e instanceof Error?e:new Error(String(e)))}}clearHandoffData(){try{if("undefined"==typeof sessionStorage)return;sessionStorage.removeItem(this.ADMISSION_KEY)}catch(e){this.logger.error("Failed to clear handoff data",e instanceof Error?e:new Error(String(e)))}}async completeCheckout(e){const{success:r,orderId:o,reason:t}=e;try{const e=this.getStoredAdmission();if(!e)return void this.logger.warn("No admission found when completing checkout");this.logger.info("Checkout completion",{success:r,orderId:o,reason:t,consumerId:e.context.consumerId,organizationId:e.context.organizationId,experienceId:e.context.experienceId}),r?(this.sendEmbeddedMessage({type:"checkout-success",payload:{orderId:o,consumerId:e.context.consumerId,organizationId:e.context.organizationId,experienceId:e.context.experienceId}}),this.clearAdmission()):this.sendEmbeddedMessage({type:"checkout-failure",payload:{reason:t,canRetry:!0,consumerId:e.context.consumerId,organizationId:e.context.organizationId,experienceId:e.context.experienceId}})}catch(n){const e=n instanceof Error?n:new Error(String(n));throw this.logger.error("Failed to complete checkout",e),e}}async getCheckoutStatus(){try{const e=await this.validateAdmission();return e.valid&&e.admission?{hasAdmission:!0,admission:e.admission,canCheckout:!0}:{hasAdmission:!1,canCheckout:!1}}catch(e){const r=e instanceof Error?e:new Error(String(e));return this.logger.error("Failed to get checkout status",r),{hasAdmission:!1,canCheckout:!1}}}buildCheckoutUrlWithAdmission(e){const{baseUrl:r,admission:o,additionalParams:t={}}=e;try{const e=new URL(r);e.searchParams.set("fanfare_consumer",o.context.consumerId),e.searchParams.set("fanfare_org",o.context.organizationId),e.searchParams.set("fanfare_experience",o.context.experienceId),e.searchParams.set("fanfare_type",o.context.experienceType),e.searchParams.set("fanfare_expires",o.expiresAt);for(const[r,o]of Object.entries(t))e.searchParams.set(r,o);return e.toString()}catch(n){const e=n instanceof Error?n:new Error(String(n));throw this.logger.error("Failed to build checkout URL with admission",e),e}}sendEmbeddedMessage(e){try{if(!r()||window.parent===window)return;const o={...e,source:"fanfare-sdk",timestamp:/* @__PURE__ */(new Date).toISOString()},t=this.resolveEmbeddedTargetOrigin();if(!t)return;window.parent.postMessage(o,t)}catch(o){this.logger.error("Failed to send embedded message",o instanceof Error?o:new Error(String(o)))}}resolveEmbeddedTargetOrigin(){if(!r())return null;const e=this.getStoredAdmission()?.context.sourceOrigin;if(!e)return this.logger.warn("No source origin on stored admission; cannot address embedded checkout message"),null;try{return this.requireAllowedSourceOrigin(e)}catch(o){return this.logger.warn("Blocked embedded message to untrusted source origin",{reason:o instanceof Error?o.message:String(o)}),null}}requireAllowedSourceOrigin(e){const r=this.requireValidOrigin(e);if(this.allowedSourceOrigins&&!this.allowedSourceOrigins.has(r))throw new Error("Source origin is not allowlisted");return r}requireValidOrigin(e){let r;try{r=new URL(e)}catch{throw new Error("Source origin is invalid")}if("https:"!==r.protocol&&"http:"!==r.protocol||r.origin!==e)throw new Error("Source origin must be an absolute HTTP(S) origin");return r.origin}isEmbedded(){if(!r())return!1;try{return window.parent!==window}catch{return!1}}}export{i as HandoffModule};

package/dist/handoff/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handoff module exports
+ */
+export { HandoffModule } from './handoff.module';
+export type { AdmissionProofHeaders, BuildAdmissionProofHeadersParams, BuildHandoffUrlParams, CreateHandoffTokenParams, HandoffModuleOptions, } from './handoff.module';

package/dist/handoff/index.js

@@ -0,0 +1 @@
+import{HandoffModule as o}from"./handoff.module.js";export{o as HandoffModule};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fanfare Browser SDK
+ *
+ * Official SDK for integrating Fanfare's queue, draw, auction,
+ * and appointment experiences into your website.
+ *
+ * @packageDocumentation
+ */
+export { init as default, init } from './core/client';
+export type { FanfareConfig, FanfareSDK } from './types';
+export { version } from './version';

package/dist/index.js

@@ -0,0 +1 @@
+import{init as i,init as o}from"./core/client.js";import{version as r}from"./version.js";export{i as default,o as init,r as version};

package/dist/internals.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Internal adapter surface. Exists for the first-party framework adapters
+ * (fanfare-sdk-react/-solid) and internal tooling; it is NOT customer API and
+ * carries no stability guarantee — symbols here may change or disappear in any
+ * release. Customer-facing API lives on the domain subpaths (see
+ * docs/PUBLIC_SURFACE.md).
+ */
+export type { AppointmentDisplayState, AuctionDisplayState, DistributionDisplayState, DistributionMonitor, DrawDisplayState, MonitorUpdate, QueueDisplayState, TimedReleaseDisplayState, } from './experiences/distribution-monitor.types';
+export { SnapshotInvariantError, deriveSequenceState, getAdmissionGrant, getAdmissionGrantExpiresAt, getDistribution, getGates, getOffers, getParticipation, getSelected, getSequenceId, getSequencePhase, getSequenceState, isGateState, isRoutedState, } from './experiences/journey.machine';
+export { generateFingerprint, generateFingerprintSync } from './utils/fingerprint.module';
+export type { BrowserFingerprint } from './utils/fingerprint.module';

package/dist/internals.js

@@ -0,0 +1 @@
+import{SnapshotInvariantError as e,deriveSequenceState as r,getAdmissionGrant as i,getAdmissionGrantExpiresAt as o,getDistribution as m,getGates as n,getOffers as p,getParticipation as t,getSelected as s,getSequenceId as f,getSequencePhase as j,getSequenceState as u,isGateState as c,isRoutedState as l}from"./experiences/journey.machine.js";import{generateFingerprint as x,generateFingerprintSync as a}from"./utils/fingerprint.module.js";export{e as SnapshotInvariantError,r as deriveSequenceState,x as generateFingerprint,a as generateFingerprintSync,i as getAdmissionGrant,o as getAdmissionGrantExpiresAt,m as getDistribution,n as getGates,p as getOffers,t as getParticipation,s as getSelected,f as getSequenceId,j as getSequencePhase,u as getSequenceState,c as isGateState,l as isRoutedState};

package/dist/queues/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Queue module exports
+ */
+export * from './qualitative-bucket';
+export * from './types';

package/dist/queues/index.js

@@ -0,0 +1 @@
+import{bucketFromEtaSeconds as t,bucketI18nKey as o}from"./qualitative-bucket.js";import{QueueDenyReason as r}from"./types.js";export{r as QueueDenyReason,t as bucketFromEtaSeconds,o as bucketI18nKey};

package/dist/queues/qualitative-bucket.d.ts

@@ -0,0 +1,12 @@
+export type QualitativeBucket = "upNext" | "almostThere" | "nearTheFront" | "fewAhead" | "inTheLine";
+declare const I18N_KEYS: {
+    readonly upNext: "queue.bucket.upNext";
+    readonly almostThere: "queue.bucket.almostThere";
+    readonly nearTheFront: "queue.bucket.nearTheFront";
+    readonly fewAhead: "queue.bucket.fewAhead";
+    readonly inTheLine: "queue.bucket.inTheLine";
+};
+export type BucketI18nKey = (typeof I18N_KEYS)[QualitativeBucket];
+export declare function bucketFromEtaSeconds(etaSeconds: number): QualitativeBucket;
+export declare function bucketI18nKey(bucket: QualitativeBucket): BucketI18nKey;
+export {};

package/dist/queues/qualitative-bucket.js

@@ -0,0 +1 @@
+const e={upNext:"queue.bucket.upNext",almostThere:"queue.bucket.almostThere",nearTheFront:"queue.bucket.nearTheFront",fewAhead:"queue.bucket.fewAhead",inTheLine:"queue.bucket.inTheLine"};function u(e){return e<30?"upNext":e<120?"almostThere":e<300?"nearTheFront":e<900?"fewAhead":"inTheLine"}function t(u){return e[u]}export{u as bucketFromEtaSeconds,t as bucketI18nKey};

package/dist/queues/queue.module.d.ts

@@ -0,0 +1,42 @@
+import { HttpClient, RequestOptions } from '../core/http';
+import { MonitorUpdate } from '../experiences/distribution-monitor.types';
+import { Queue, QueueConsumerState, QueueModule } from './types';
+export declare class QueueManagementModule implements QueueModule {
+    private http;
+    private logger;
+    private store;
+    private events;
+    private trackedParticipations;
+    private pollingIntervals;
+    private inFlightRequests;
+    private monitorRuntime;
+    private monitorGenerations;
+    private readonly operationGenerations;
+    private destroyed;
+    private lifecycleGeneration;
+    constructor(http: HttpClient);
+    /**
+     * Get queue details
+     */
+    get(queueId: string): Promise<Queue>;
+    /**
+     * Enter a queue
+     */
+    enter(queueId: string, metadata?: Record<string, unknown>, options?: RequestOptions): Promise<QueueConsumerState>;
+    leave(queueId: string, options?: RequestOptions): Promise<void>;
+    status(queueId: string): Promise<QueueConsumerState>;
+    private _doStatus;
+    startMonitoring(id: string, context?: Record<string, unknown>, onUpdate?: (update: MonitorUpdate) => void): void;
+    stopMonitoring(id: string): void;
+    isMonitoring(id: string): boolean;
+    private startStatusPolling;
+    private stopStatusPolling;
+    private isStatusPolling;
+    private bumpMonitorGeneration;
+    private getOperationGeneration;
+    private bumpOperationGeneration;
+    private canApplyAsyncResult;
+    private buildTransition;
+    private applyTransition;
+    destroy(): void;
+}

package/dist/queues/queue.module.js

@@ -0,0 +1 @@
+import{createError as t}from"../core/errors.js";import{getLogger as e}from"../core/logger.js";import{DistributionMonitorRuntime as i}from"../experiences/distribution-monitor.runtime.js";import{getEventBus as s}from"../state/events.js";import{getSDKStore as n}from"../state/store.js";class o{constructor(t){this.logger=e(),this.store=n(),this.events=s(),this.trackedParticipations=/* @__PURE__ */new Map,this.pollingIntervals=/* @__PURE__ */new Map,this.inFlightRequests=/* @__PURE__ */new Map,this.monitorRuntime=new i,this.monitorGenerations=/* @__PURE__ */new Map,this.operationGenerations=/* @__PURE__ */new Map,this.destroyed=!1,this.lifecycleGeneration=0,this.http=t}async get(t){try{return await this.http.get(`/queues/${t}`)}catch(e){throw this.logger.error("Failed to get queue",{queueId:t,error:e}),e}}async enter(e,i,s){try{const n=this.lifecycleGeneration;if(!this.store.session)throw t.unauthorized("Not authenticated. Call auth.guest() or auth.login() first");const o=this.bumpOperationGeneration(e);this.logger.info("Entering queue",{queueId:e});const r=await this.http.post(`/queues/${e}/enter`,{metadata:i},s),a=this.buildTransition(e,r,{source:"enter",enteredAt:/* @__PURE__ */(new Date).toISOString(),metadata:i});return this.canApplyAsyncResult(e,n,void 0,o)?(this.applyTransition(e,a),r):r}catch(n){throw this.logger.error("Failed to enter queue",{queueId:e,error:n}),this.events.emit("queue:error",{queueId:e,error:n}),n}}async leave(t,e){try{const i=this.lifecycleGeneration,s=this.bumpOperationGeneration(t);if(this.logger.info("Leaving queue",{queueId:t}),await this.http.post(`/queues/${t}/leave`,void 0,e),!this.canApplyAsyncResult(t,i,void 0,s))return;this.trackedParticipations.delete(t),this.stopStatusPolling(t),this.events.emit("queue:left",{queueId:t,reason:"user"})}catch(i){throw this.logger.error("Failed to leave queue",{queueId:t,error:i}),this.events.emit("queue:error",{queueId:t,error:i}),i}}async status(t){const e=this.inFlightRequests.get(t);if(e)return this.logger.debug("Returning existing in-flight request",{queueId:t}),e;const i=this.lifecycleGeneration,s=this.bumpOperationGeneration(t),n=this._doStatus(t,i,void 0,s).finally(()=>{this.inFlightRequests.delete(t)});return this.inFlightRequests.set(t,n),n}async _doStatus(t,e,i,s){try{const n=await this.http.get(`/queues/${t}/status`);if(!this.canApplyAsyncResult(t,e,i,s))return n;const o=this.buildTransition(t,n,{source:"status",previousParticipation:this.trackedParticipations.get(t)});return this.applyTransition(t,o),this.events.emit("queue:status-updated",{queueId:t,status:n}),n}catch(n){if(n&&"object"==typeof n&&"status"in n&&404===n.status){const n={status:"NOT_QUEUED"};if(!this.canApplyAsyncResult(t,e,i,s))return n;const o=this.buildTransition(t,n,{source:"status",previousParticipation:this.trackedParticipations.get(t)});return this.applyTransition(t,o),this.events.emit("queue:status-updated",{queueId:t,status:n}),n}if(!this.canApplyAsyncResult(t,e,i,s))return{status:"NOT_QUEUED"};throw this.logger.error("Failed to get queue status",{queueId:t,error:n}),this.events.emit("queue:error",{queueId:t,error:n}),n}}startMonitoring(t,e,i){this.monitorRuntime.start(t,e,i),this.startStatusPolling(t)}stopMonitoring(t){this.stopStatusPolling(t),this.monitorRuntime.stop(t)}isMonitoring(t){return this.isStatusPolling(t)||this.monitorRuntime.has(t)}startStatusPolling(t,e=1e4){this.stopStatusPolling(t);const i=this.bumpMonitorGeneration(t);this.logger.debug("Starting queue polling",{queueId:t,intervalMs:e});const s=async()=>{const e=this.getOperationGeneration(t);try{await this._doStatus(t,this.lifecycleGeneration,i,e)}catch(s){if(!this.canApplyAsyncResult(t,this.lifecycleGeneration,i,e))return;this.logger.error("Polling error",{queueId:t,error:s})}};s(),this.pollingIntervals.set(t,setInterval(s,e))}stopStatusPolling(t){this.bumpMonitorGeneration(t);const e=this.pollingIntervals.get(t);e&&(clearInterval(e),this.pollingIntervals.delete(t),this.logger.debug("Stopped queue polling",{queueId:t}))}isStatusPolling(t){return this.pollingIntervals.has(t)}bumpMonitorGeneration(t){const e=(this.monitorGenerations.get(t)??0)+1;return this.monitorGenerations.set(t,e),e}getOperationGeneration(t){return this.operationGenerations.get(t)??0}bumpOperationGeneration(t){const e=this.getOperationGeneration(t)+1;return this.operationGenerations.set(t,e),e}canApplyAsyncResult(t,e,i,s){return!this.destroyed&&this.lifecycleGeneration===e&&((void 0===i||this.monitorGenerations.get(t)===i)&&(void 0===s||this.getOperationGeneration(t)===s))}buildTransition(t,e,{source:i,previousParticipation:s,enteredAt:n,metadata:o}){switch(e.status){case"QUEUED":return{trackedParticipation:{queueId:t,enteredAt:s?.enteredAt??n??/* @__PURE__ */(new Date).toISOString(),position:e.position,estimatedWaitTime:e.estimatedWaitTimeInSeconds,positionDisplayMode:e.positionDisplayMode,metadata:s?.metadata??o},displayState:{position:e.position,estimatedWaitTime:e.estimatedWaitTimeInSeconds,positionDisplayMode:e.positionDisplayMode},events:"enter"===i?[{type:"queue:entered",payload:{queueId:t,position:e.position,estimatedWaitTime:e.estimatedWaitTimeInSeconds}}]:void 0!==s?.position&&s.position!==e.position?[{type:"queue:position-changed",payload:{queueId:t,position:e.position,previousPosition:s.position}}]:[],monitorUpdate:null,stopMonitoring:!1};case"GRANTED":case"COMPLETED":return{trackedParticipation:null,events:[{type:"queue:granted",payload:{queueId:t,grant:e.admissionGrant}}],monitorUpdate:"status"===i?{type:"granted",token:e.admissionGrant,expiresAt:"expiresAt"in e&&e.expiresAt?new Date(e.expiresAt).getTime():void 0}:null,stopMonitoring:"status"===i};case"EXPIRED":return{trackedParticipation:null,events:[{type:"queue:expired",payload:{queueId:t}}],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"expired"}}:null,stopMonitoring:"status"===i};case"DENIED":return{trackedParticipation:null,events:[],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"denied",reason:e.reason}}:null,stopMonitoring:"status"===i};case"LEFT":return{trackedParticipation:null,events:[],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"left"}}:null,stopMonitoring:"status"===i};case"NOT_QUEUED":return{trackedParticipation:null,events:[],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"closed",reason:"not_queued"}}:null,stopMonitoring:"status"===i}}}applyTransition(t,e){if(e.trackedParticipation?this.trackedParticipations.set(t,e.trackedParticipation):this.trackedParticipations.delete(t),e.displayState){const i=this.monitorRuntime.getDisplayAtom(t);i&&i.set({type:"queue",...e.displayState})}for(const i of e.events)this.events.emit(i.type,i.payload);e.monitorUpdate&&this.monitorRuntime.notify(t,e.monitorUpdate),e.stopMonitoring&&this.stopStatusPolling(t)}destroy(){this.destroyed=!0,this.lifecycleGeneration+=1,this.pollingIntervals.forEach(t=>clearInterval(t)),this.pollingIntervals.clear(),this.inFlightRequests.clear(),this.trackedParticipations.clear(),this.monitorGenerations.clear(),this.operationGenerations.clear(),this.monitorRuntime.clear()}}export{o as QueueManagementModule};

package/dist/queues/types.d.ts

@@ -0,0 +1,112 @@
+import { RequestOptions } from '../core/http';
+/**
+ * Known queue deny reasons.
+ *
+ * When a consumer is denied entry to a queue, the `reason` field
+ * will contain one of these values (or a custom reason).
+ */
+export declare const QueueDenyReason: {
+    /** Consumer has exceeded their order limit for this experience */
+    readonly ORDER_LIMIT_EXCEEDED: "ORDER_LIMIT_EXCEEDED";
+    /** Queue has reached maximum capacity */
+    readonly CAPACITY_EXCEEDED: "CAPACITY_EXCEEDED";
+    /** Consumer validation failed */
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    /** Consumer is not part of the required audience */
+    readonly AUDIENCE_MISMATCH: "AUDIENCE_MISMATCH";
+    /** Queue is closed */
+    readonly QUEUE_CLOSED: "QUEUE_CLOSED";
+    /** Admission token has expired */
+    readonly ADMISSION_EXPIRED: "ADMISSION_EXPIRED";
+};
+export type QueueDenyReason = (typeof QueueDenyReason)[keyof typeof QueueDenyReason];
+/**
+ * Queue module interface
+ */
+export interface QueueModule {
+    /**
+     * Get queue details
+     */
+    get(queueId: string): Promise<Queue>;
+    /**
+     * Enter a queue (requires authentication)
+     */
+    enter(queueId: string, metadata?: Record<string, unknown>, options?: RequestOptions): Promise<QueueConsumerState>;
+    /**
+     * Leave a queue
+     */
+    leave(queueId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Get current status in queue
+     */
+    status(queueId: string): Promise<QueueConsumerState>;
+}
+/**
+ * Queue information
+ */
+export interface Queue {
+    id: string;
+    experienceId: string;
+    name: string;
+    status: "pending" | "open" | "closed" | "paused";
+    capacity?: number;
+    currentSize: number;
+    estimatedWaitTime?: number;
+    openAt?: string;
+    closeAt?: string;
+}
+/**
+ * Consumer state in queue
+ */
+export type QueueConsumerState = QueuedConsumerState | GrantedConsumerState | CompletedConsumerState | LeftConsumerState | DeniedConsumerState | NotQueuedConsumerState | ExpiredConsumerState;
+export interface QueuedConsumerState {
+    status: "QUEUED";
+    position: number;
+    estimatedWaitTimeInSeconds: number;
+    positionDisplayMode?: "precise" | "qualitative";
+}
+export interface GrantedConsumerState {
+    status: "GRANTED";
+    admissionGrant: string;
+    position?: number;
+    dequeuedAt?: string;
+    expiresAt?: string;
+}
+export interface CompletedConsumerState {
+    status: "COMPLETED";
+    admissionGrant: string;
+    completedAt?: string;
+    position?: number;
+}
+export interface LeftConsumerState {
+    status: "LEFT";
+    dequeuedAt?: string;
+    position?: number;
+}
+export interface DeniedConsumerState {
+    status: "DENIED";
+    reason: string;
+    dequeuedAt?: string;
+    position?: number;
+}
+export interface NotQueuedConsumerState {
+    status: "NOT_QUEUED";
+    dequeuedAt?: string;
+    position?: number;
+}
+export interface ExpiredConsumerState {
+    status: "EXPIRED";
+    expiredAt?: string;
+    position?: number;
+}
+/**
+ * Runtime-tracked queue participation
+ */
+export interface QueueParticipation {
+    queueId: string;
+    enteredAt: string;
+    position?: number;
+    estimatedWaitTime?: number;
+    positionDisplayMode?: "precise" | "qualitative";
+    metadata?: Record<string, unknown>;
+}

package/dist/queues/types.js

@@ -0,0 +1 @@
+const E={ORDER_LIMIT_EXCEEDED:"ORDER_LIMIT_EXCEEDED",CAPACITY_EXCEEDED:"CAPACITY_EXCEEDED",VALIDATION_FAILED:"VALIDATION_FAILED",AUDIENCE_MISMATCH:"AUDIENCE_MISMATCH",QUEUE_CLOSED:"QUEUE_CLOSED",ADMISSION_EXPIRED:"ADMISSION_EXPIRED"};export{E as QueueDenyReason};

package/dist/security/admission-proof.d.ts

@@ -0,0 +1,15 @@
+export declare const ADMISSION_KEY_THUMBPRINT_HEADER = "X-Admission-Key-Thumbprint";
+export declare const DPOP_HEADER = "DPoP";
+export declare const DPOP_NONCE_HEADER = "DPoP-Nonce";
+export interface AdmissionProofHeaders {
+    [ADMISSION_KEY_THUMBPRINT_HEADER]: string;
+    [DPOP_HEADER]: string;
+    [DPOP_NONCE_HEADER]?: string;
+}
+export declare function canonicalizeAdmissionProofUrl(url: string): string;
+export declare function getAdmissionKeyThumbprint(): Promise<string | null>;
+export declare function buildAdmissionProofHeaders(params: {
+    url: string;
+    method?: string;
+    nonce?: string;
+}): Promise<AdmissionProofHeaders | null>;

package/dist/security/admission-proof.js

@@ -0,0 +1 @@
+import{generateId as n}from"../core/utils.js";const t="X-Admission-Key-Thumbprint",e="DPoP",r="DPoP-Nonce",o="fanfare-admission-proof",c="keys",i="current";let a=null,u=null;function l(n){const t=new URL(n);return t.search="",t.hash="",t.toString()}async function s(){const n=await p();return n?.thumbprint??null}async function y(o){const c=await p();if(!c)return null;const i=o.method?.toUpperCase()??"POST",a={typ:"dpop+jwt",alg:"ES256",jwk:c.publicJwk},u={htm:i,htu:l(o.url),iat:Math.floor(Date.now()/1e3),jti:n(),...o.nonce?{nonce:o.nonce}:{}},s=`${d(a)}.${d(u)}`,y=await crypto.subtle.sign({name:"ECDSA",hash:"SHA-256"},c.privateKey,(new TextEncoder).encode(s));return{[t]:c.thumbprint,[e]:`${s}.${b(new Uint8Array(y))}`,...o.nonce?{[r]:o.nonce}:{}}}async function p(){if(u)return u;if(a)return await a;a=(async()=>{if("undefined"==typeof window||"undefined"==typeof document||!globalThis.crypto?.subtle)return null;const n=await async function(){if(!("indexedDB"in globalThis))return null;return await new Promise(n=>{try{const t=indexedDB.open(o,1);t.onupgradeneeded=()=>{const n=t.result;n.objectStoreNames.contains(c)||n.createObjectStore(c)},t.onsuccess=()=>n(t.result),t.onerror=()=>n(null),t.onblocked=()=>n(null)}catch{n(null)}})}();if(!n)return null;try{const t=await async function(n){try{const t=await f(n.transaction(c).objectStore(c).get(i));return t?.privateKey&&t.publicKey&&t.publicJwk&&t.thumbprint?t:null}catch{return null}}(n);if(t)return u=t,t;const e=await async function(){const n=await crypto.subtle.generateKey({name:"ECDSA",namedCurve:"P-256"},!1,["sign","verify"]),t=await crypto.subtle.exportKey("jwk",n.publicKey);return{privateKey:n.privateKey,publicKey:n.publicKey,publicJwk:t,thumbprint:await w(t)}}(),r=await async function(n,t){try{return await f(n.transaction(c,"readwrite").objectStore(c).put(t,i)),!0}catch{return!1}}(n,e);return r?(u=e,e):null}finally{n.close()}})();try{return await a}finally{a=null}}function f(n){return new Promise((t,e)=>{n.onsuccess=()=>t(n.result),n.onerror=()=>e(n.error??new Error("IndexedDB request failed"))})}async function w(n){const t=JSON.stringify({crv:n.crv,kty:n.kty,x:n.x,y:n.y}),e=await crypto.subtle.digest("SHA-256",(new TextEncoder).encode(t));return b(new Uint8Array(e))}function d(n){return b((new TextEncoder).encode(JSON.stringify(n)))}function b(n){let t="";for(const e of n)t+=String.fromCharCode(e);return btoa(t).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}export{t as ADMISSION_KEY_THUMBPRINT_HEADER,e as DPOP_HEADER,r as DPOP_NONCE_HEADER,y as buildAdmissionProofHeaders,l as canonicalizeAdmissionProofUrl,s as getAdmissionKeyThumbprint};

package/dist/state/capability-token-registry.d.ts

@@ -0,0 +1,44 @@
+import { RequestOptions } from '../core/http';
+import { DistributionSummary } from '../experiences/journey.types';
+import { SdkDistributionType } from '../types/distribution-type';
+export type CapabilitySequenceKey = `${string}:${string}`;
+export interface CapabilityTokenRecord {
+    experienceId: string;
+    sequenceId: string;
+    token: string;
+    expiresAt?: string;
+    expiresAtMs?: number;
+}
+export interface DistributionCapabilityBinding {
+    distributionId: string;
+    distributionType: SdkDistributionType;
+    experienceId: string;
+    sequenceId: string;
+    sequenceKey: CapabilitySequenceKey;
+}
+export declare function makeSequenceKey(experienceId: string, sequenceId: string): CapabilitySequenceKey;
+export declare function upsertSequenceToken(input: {
+    experienceId: string;
+    sequenceId: string;
+    token: string;
+    expiresAt?: string;
+}): void;
+export declare function bindDistribution(input: {
+    distributionId: string;
+    distributionType: SdkDistributionType;
+    experienceId: string;
+    sequenceId: string;
+}): void;
+export declare function bindDistributionContext(input: {
+    experienceId: string;
+    sequenceId: string;
+    distributionContext: DistributionSummary;
+}): void;
+export declare function resolveCapabilityOptions(lookup: {
+    distributionId?: string;
+    sequenceId?: string;
+    experienceId?: string;
+}, existingOptions?: RequestOptions, nowMs?: number): RequestOptions | undefined;
+export declare function clearSequenceContext(experienceId: string, sequenceId: string): void;
+export declare function clearExperienceContext(experienceId: string): void;
+export declare function clearExpired(nowMs?: number): void;

package/dist/state/capability-token-registry.js

@@ -0,0 +1 @@
+import{getSDKStore as e}from"./store.js";function i(e,i){return`${e}:${i}`}function t(t){const n=i(t.experienceId,t.sequenceId),r=t.expiresAt?new Date(t.expiresAt).getTime():void 0;e().upsertCapabilityToken(n,{experienceId:t.experienceId,sequenceId:t.sequenceId,token:t.token,expiresAt:t.expiresAt,expiresAtMs:r})}function n(t){const n=i(t.experienceId,t.sequenceId);e().bindDistribution(t.distributionId,{distributionId:t.distributionId,distributionType:t.distributionType,experienceId:t.experienceId,sequenceId:t.sequenceId,sequenceKey:n})}function r(e){const{experienceId:i,sequenceId:t,distributionContext:r}=e;n({distributionId:r.id,distributionType:r.type,experienceId:i,sequenceId:t}),r.waitlistId&&n({distributionId:r.waitlistId,distributionType:"waitlist",experienceId:i,sequenceId:t})}function s(t,n,r){if(n?.headers?.["X-Sequence-Capability-Grant"])return n;const s=e(),d=Date.now();let c;if(t.distributionId){const e=s.distributionCapabilityIndex[t.distributionId];e&&(c=e.sequenceKey)}if(!c&&t.experienceId&&t.sequenceId&&(c=i(t.experienceId,t.sequenceId)),!c)return n;const u=s.capabilityTokens[c];if(!u)return n;if(u.expiresAtMs&&u.expiresAtMs<=d)return n;const o={...n?.headers,"X-Sequence-Capability-Grant":u.token};return{...n,headers:o}}function d(i,t){e().clearCapabilityContext(i,t)}function c(i){e().clearExperienceCapabilityContext(i)}export{n as bindDistribution,r as bindDistributionContext,c as clearExperienceContext,d as clearSequenceContext,i as makeSequenceKey,s as resolveCapabilityOptions,t as upsertSequenceToken};