@fanfare-io/fanfare-sdk-solid 0.10.0 → 0.12.0

package/dist/components/checkout/checkout-processing-panel.d.ts

@@ -0,0 +1,10 @@
+import { JSX } from 'solid-js';
+import { CheckoutProcessingSlotProps } from '../widgets/experience-widget';
+/**
+ * Default processing panel shown for the gap between a submitted reservation checkout and the
+ * server's confirmation.
+ *
+ * The consumer must not navigate away while the payment settles, so the wait is announced rather
+ * than shown only as motion.
+ */
+export declare function CheckoutProcessingPanel(_props: CheckoutProcessingSlotProps): JSX.Element;

package/dist/components/checkout/create-payment-challenge.d.ts

@@ -0,0 +1,33 @@
+import { Accessor } from 'solid-js';
+import { StripeClientConfig } from './stripe-client';
+/** `idle` covers both "no challenge yet" and "this attempt has settled". */
+export type PaymentChallengePhase = "idle" | "challenging" | "resuming";
+/**
+ * How the last attempt ended, when it ended badly — the fact a panel needs to offer the right way
+ * out, which the error copy alone cannot carry.
+ *
+ * - `cancelled` — the prompt ended without the card being refused: the consumer dismissed it, or the
+ *   authentication behind it failed. Reopening that same prompt is the recovery.
+ * - `declined` — the card was refused, or the prompt could not be opened at all. That secret is
+ *   spent; only a fresh submission can produce another.
+ * - `resume_failed` — the prompt succeeded and the operation behind it did not. The challenge is
+ *   answered, so the recovery is to run that operation again, never to reopen the prompt.
+ */
+export type PaymentChallengeRecovery = "cancelled" | "declined" | "resume_failed";
+export interface PaymentChallenge {
+    phase: Accessor<PaymentChallengePhase>;
+    /** Localized copy for the attempt that produced it; terminal until another attempt starts. */
+    error: Accessor<string | null>;
+    /** Set together with `error`, and cleared when the next attempt starts. */
+    recovery: Accessor<PaymentChallengeRecovery | null>;
+    /**
+     * Open the bank prompt for `clientSecret`. Once per secret per instance: a repeat call carrying a
+     * secret this instance already launched is a no-op, and a genuinely new secret launches again.
+     */
+    launch: (clientSecret: string, resume: () => Promise<void>) => void;
+    /** Reopen the same prompt on the consumer's own instruction, then run the same resume. */
+    retry: (clientSecret: string, resume: () => Promise<void>) => void;
+}
+/** Test-only seam. Never exported from the adapter's public entry. */
+export declare function resetPaymentChallengeState(): void;
+export declare function createPaymentChallenge(config: Accessor<StripeClientConfig | null>): PaymentChallenge;

package/dist/components/checkout/create-payment-method-selection.d.ts

@@ -0,0 +1,9 @@
+import { PaymentMethodSummary } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { Accessor, Setter } from 'solid-js';
+/**
+ * Tracks the selected saved payment method for a checkout panel. The list can still be loading on
+ * mount (nothing selected yet) or a previously selected card can be removed out from under the
+ * panel — falls back to the default method, else the first, else `undefined`, both on initial
+ * mount and whenever the list changes, so submit never carries a stale/deleted `paymentMethodId`.
+ */
+export declare function createPaymentMethodSelection(savedPaymentMethods: Accessor<PaymentMethodSummary[]>): [Accessor<string | undefined>, Setter<string | undefined>];

package/dist/components/checkout/index.d.ts

@@ -0,0 +1,4 @@
+export { CheckoutProcessingPanel } from './checkout-processing-panel';
+export { PaymentCollectionPanel } from './payment-collection-panel';
+export { ReceiptPanel } from './receipt-panel';
+export { ReservationCheckoutPanel } from './reservation-checkout-panel';

package/dist/components/checkout/payment-collection-panel.d.ts

@@ -0,0 +1,18 @@
+import { JSX } from 'solid-js';
+import { PaymentCollectionSlotProps } from '../widgets/experience-widget';
+/**
+ * Default payment-collection panel for pre-auth distributions, rendered both when the consumer is
+ * about to enter and when a failed authorization leaves a retry open.
+ *
+ * The hold amount is rendered from the view's own figure — the client never derives one.
+ *
+ * The configuration block reaches this panel on the entry mount only. A retry is offered from an
+ * ended view, which carries none, so that mount renders payment as unavailable and a consumer with
+ * a saved method submits without needing Stripe.js at all.
+ *
+ * Entry has no server-side resume: a paused authorization is carried forward by submitting the
+ * identical payment input again, held here from the first submit, so exactly one payment method is
+ * minted across the whole flow. An ended view carries no pending action, so the retry mount reaches
+ * none of this.
+ */
+export declare function PaymentCollectionPanel(props: PaymentCollectionSlotProps): JSX.Element;

package/dist/components/checkout/receipt-panel.d.ts

@@ -0,0 +1,10 @@
+import { JSX } from 'solid-js';
+import { ReceiptSlotProps } from '../widgets/experience-widget';
+/**
+ * Default panel for a completed Fanfare-managed payment.
+ *
+ * The order reference is the outcome. An admission credential appears only on the arm that carries
+ * one, and stays subordinate to the purchase: payment is terminal, so a receipt must never read as
+ * the thing that admits its holder.
+ */
+export declare function ReceiptPanel(props: ReceiptSlotProps): JSX.Element;

package/dist/components/checkout/reservation-checkout-panel.d.ts

@@ -0,0 +1,18 @@
+import { JSX } from 'solid-js';
+import { ReservationCheckoutSlotProps } from '../widgets/experience-widget';
+/**
+ * Default reservation-checkout panel for post-win checkout flows.
+ *
+ * `Countdown`'s `onComplete` is a no-op: the journey machine owns the reservation's expiry (it
+ * arms its own timer and transitions the sequence to `ended` when the deadline passes), so the
+ * panel never disables itself locally — it simply stops being rendered once the phase changes.
+ *
+ * Elements renders only on the internal-processor arm. The discriminator is `processor`; an absent
+ * configuration block on that arm means the configuration read failed, which is a retryable outage
+ * inside a ticking window — never a signal that another processor is in play.
+ *
+ * A pending action adds visible substates over the same screen rather than replacing it: the card
+ * field stays mounted through the whole challenge, because a consumer whose bank prompt failed may
+ * need to submit again with the card they already typed.
+ */
+export declare function ReservationCheckoutPanel(props: ReservationCheckoutSlotProps): JSX.Element;

package/dist/components/checkout/stripe-card-field.d.ts

@@ -0,0 +1,20 @@
+import { JSX } from 'solid-js';
+import { StripeClientConfig } from './stripe-client';
+export interface StripeCardController {
+    /** Resolves the `pm_…` id, or rejects with an `Error` carrying already-localized copy. */
+    createPaymentMethod: () => Promise<string>;
+}
+export interface StripeCardFieldProps {
+    config: StripeClientConfig;
+    onController: (controller: StripeCardController | null) => void;
+    onChange?: (state: {
+        complete: boolean;
+        errorMessage: string | null;
+    }) => void;
+    /**
+     * The owning panel's account of everything it renders above this field. Its value carries no
+     * meaning; a change to it means the anchor may have moved and the portal frame needs re-measuring.
+     */
+    reflowKey?: string;
+}
+export declare function StripeCardField(props: StripeCardFieldProps): JSX.Element;

package/dist/components/checkout/stripe-client.d.ts

@@ -0,0 +1,71 @@
+import { ReservationPaymentAffordance } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { Stripe, StripeConstructor, StripeElementStyle } from '@stripe/stripe-js';
+/**
+ * The wire block a checkout-capable view carries, reached through the adapter's declared
+ * dependency on `fanfare-sdk-core` rather than the contracts package: core re-exports the contract
+ * types so adapter modules never resolve `@fanfare-io/fanfare-sdk-contracts` directly.
+ */
+type PaymentProviderConfig = NonNullable<ReservationPaymentAffordance["paymentProvider"]>;
+declare global {
+    interface Window {
+        Stripe?: StripeConstructor;
+    }
+}
+export interface StripeClientConfig {
+    publishableKey: string;
+    stripeAccount?: string;
+}
+/**
+ * Loads Stripe.js once per page. A failure is never retained: a memoized rejection would strand
+ * every subsequent payer on the page, not just the one whose load failed. Retry is the caller's
+ * decision — this module never schedules one.
+ */
+export declare function loadStripeJs(): Promise<StripeConstructor>;
+/**
+ * One Stripe client per (publishable key, connected account). A construction that rejects drops
+ * its cache entry for the same reason the loader does.
+ */
+export declare function getStripe(config: StripeClientConfig): Promise<Stripe>;
+/**
+ * Re-serializes a theme color into the spelling a CSS color parser produces.
+ *
+ * Custom properties are untyped, so a theme color arrives from `getComputedStyle` as whatever token
+ * stream the stylesheet declared — and a minifier is free to rewrite `oklch(0.63 0.24 25)` as
+ * `oklch(63% .24 25)`. Stripe's element options go through a stricter parser than CSS's: a spelling
+ * every browser accepts can still be rejected there, and the rejection is silent — the element
+ * mounts a frame that never renders its input. The invariant this restores is that colors reach
+ * Stripe in the serialization its parser accepts.
+ *
+ * `null` means the value is not a color the parser recognizes, and the caller must omit the key
+ * rather than guess: assigning an unparsable value leaves `fillStyle` on its previous one, so
+ * emitting the read-back would emit some other color entirely. Where no parser exists — server
+ * rendering, or a DOM without canvas — the value passes through: the mismatch only arises where a
+ * real browser serializes computed styles.
+ */
+export declare function normalizeCssColor(value: string): string | null;
+/**
+ * Maps the SDK theme's resolved custom properties onto the Card Element's `style` option. Stripe's
+ * `Appearance` API governs the Elements group Payment Element consumes and does not reach the
+ * legacy Card Element, so `style` is the only theming path — there is deliberately no second one.
+ *
+ * Property names are the values of `THEME_CSS_VARS` (the adapter's `theme/theme.types.ts`), spelled
+ * literally here because this file must stay identical across adapters. `--ff-color-primary` and
+ * `--ff-color-background` have no Card Element equivalent: the element's background is the host
+ * page's, supplied by the panel around the iframe.
+ *
+ * Every color is re-serialized on the way out; a color the parser rejects is omitted, which leaves
+ * Stripe on its own default for that slot. The font stack is not a color and is forwarded as read.
+ */
+export declare function deriveStripeCardStyle(root: HTMLElement): StripeElementStyle;
+/**
+ * The one binding between a view's wire configuration and a Stripe client.
+ *
+ * `null` means no usable Stripe client configuration reached this view. On a checkout-capable arm
+ * that has exactly one cause — the configuration read failed — because the processor discriminator
+ * is the `processor` field (reserved) or `checkoutMode` (enterable), never the presence of this
+ * block. The condition is transient and retryable.
+ */
+export declare function resolveStripeClientConfig(source: PaymentProviderConfig | undefined): StripeClientConfig | null;
+/** Test-only seam over every memo this module holds. Never exported from an adapter's public entry. */
+export declare function resetStripeClientCache(): void;
+export {};

package/dist/components/module/index.d.ts

@@ -1,5 +1,5 @@
 export { AlertPanel, type AlertPanelProps } from './alert-panel';
 export { InfoPanel, type InfoPanelProps } from './info-panel';
-export { normalizeOutcomeReason, type OutcomeReason } from './outcome-reason';
+export { normalizeOutcomeReason, normalizeSequenceOutcomeReason, type OutcomeReason } from './outcome-reason';
 export { PanelHeading, type PanelHeadingProps, type PanelHeadingVariant } from './panel-heading';
 export { PanelBody, PanelFooter, PanelLayout, type PanelBodyProps, type PanelFooterProps, type PanelLayoutProps, } from './panel-layout';

package/dist/components/module/outcome-reason.d.ts

@@ -16,8 +16,13 @@
  *   queue_denied / draw_denied / denied / lost -> not_selected
  *   timed_release_denied   ->  sold_out
  *   outbid                 ->  outbid
+ *   floor_unsold           ->  floor_unsold
  *   reserve_not_met        ->  reserve_not_met
  *   completed / already_completed -> completed (a success terminal, not a loss)
+ *   won                    ->  won
+ *   cancelled              ->  cancelled
+ *   no_show                ->  no_show
+ *   left                   ->  left (voluntary exit: leave/withdraw)
  *   closed / unknown / other -> ended
  *
  * The terminal projection carries the outcome TYPE (completed/denied/lost);
@@ -27,5 +32,9 @@
  * Static story lanes pass UI values directly (e.g. `"outbid"`); those
  * pass through unchanged.
  */
-export type OutcomeReason = "expired" | "not_selected" | "sold_out" | "outbid" | "reserve_not_met" | "completed" | "ended";
+export type OutcomeReason = "expired" | "not_selected" | "sold_out" | "outbid" | "floor_unsold" | "reserve_not_met" | "completed" | "won" | "cancelled" | "no_show" | "left" | "ended";
 export declare function normalizeOutcomeReason(reason: string | undefined): OutcomeReason;
+export declare function normalizeSequenceOutcomeReason(outcome: {
+    type: string;
+    reason?: string;
+} | undefined, fallbackReason?: string): OutcomeReason;

package/dist/components/widgets/experience-widget.d.ts

@@ -1,5 +1,5 @@
 import { BotMitigationState, RoutingChallenge } from '@fanfare-io/fanfare-sdk-core/challenges';
-import { JourneyHandle, JourneySnapshot, JourneyView, SequenceView } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { CheckoutNextAction, CheckoutProcessor, FanfareCheckoutResult, JourneyHandle, JourneySnapshot, JourneyView, PaymentInput, PaymentMethodSummary, ReservationPaymentAffordance, SequenceView } from '@fanfare-io/fanfare-sdk-core/experiences';
 import { BrandTheme } from '@fanfare-io/fanfare-sdk-core/theme';
 import { JSX } from 'solid-js';
 import { WidgetVariant } from '../../theme';
@@ -59,6 +59,74 @@ export interface GrantedSlotProps extends SlotProps {
     grant?: string;
     expiresAt?: number;
 }
+export interface PaymentCollectionSlotProps extends SlotProps {
+    preAuthAmount: string;
+    preAuthCurrencyCode: string;
+    savedPaymentMethods: PaymentMethodSummary[];
+    /** Rejects on a recoverable payment failure (e.g. a declined card) — the panel owns recovery UI for its own submit. */
+    onEnter: (paymentInput: PaymentInput) => Promise<void>;
+    isEntering: boolean;
+    /** "enter" collects payment before first entry; "reenter" collects payment to retry after a failed or expired authorization hold. */
+    intent: "enter" | "reenter";
+    /**
+     * Client configuration for the processor authorizing this entry, as the server supplied it.
+     * Carried by the enterable arm only — a retry is offered from an ended view, which holds no
+     * configuration.
+     */
+    paymentProvider?: PaymentProviderConfig;
+    /** Present while the processor is waiting on an out-of-band action; re-submitting entry resolves it. */
+    pendingAction?: CheckoutNextAction;
+    /**
+     * Re-reads the consumer's journeys from the server so a provider configuration that was missing
+     * or unreadable at render can arrive. This is the panel's only recovery when `paymentProvider` is
+     * absent — the value is a prop, so nothing the panel does to its own state can produce it.
+     */
+    onRetryPaymentConfig?: () => Promise<void>;
+}
+/**
+ * The processor's client configuration block, named through the affordance that carries it: core
+ * re-exports the affordance but not the contract's own name for this shape.
+ */
+type PaymentProviderConfig = NonNullable<ReservationPaymentAffordance["paymentProvider"]>;
+export interface ReservationCheckoutSlotProps extends SlotProps {
+    reservation: {
+        token: string;
+        expiresAt: number;
+    };
+    savedPaymentMethods: PaymentMethodSummary[];
+    /** Which processor executes this reservation's payment leg; narrow before rendering processor-specific UI. */
+    processor: CheckoutProcessor;
+    /** Client configuration for the processor settling this reservation, as the server supplied it. */
+    paymentProvider?: PaymentProviderConfig;
+    /** Present while the processor is waiting on an out-of-band action; complete it, then call `onResume`. */
+    pendingAction?: CheckoutNextAction;
+    /** Rejects on a recoverable payment failure (e.g. a declined card) — the panel owns recovery UI for its own submit. */
+    onConfirm: (paymentInput: PaymentInput) => Promise<void>;
+    /** Re-submits the paused checkout after `pendingAction` has been completed. Idempotent server-side. */
+    onResume: () => Promise<void>;
+    isConfirming: boolean;
+    /**
+     * Re-reads the consumer's journeys from the server so a provider configuration that was missing
+     * or unreadable at render can arrive. This is the panel's only recovery when `paymentProvider` is
+     * absent — the value is a prop, so nothing the panel does to its own state can produce it.
+     */
+    onRetryPaymentConfig?: () => Promise<void>;
+}
+export type CheckoutProcessingSlotProps = SlotProps;
+/**
+ * A Fanfare-managed payment is terminal: it produces a receipt, never an admission credential. The
+ * `grant` arm carries the credential the mechanism itself issued alongside the payment; a purchase
+ * that ends the journey has no credential to carry, so the arms are discriminated rather than
+ * making the grant optional — a slot implementation can never read one that does not exist.
+ */
+export type ReceiptSlotProps = SlotProps & ({
+    kind: "grant";
+    admissionGrant: string;
+    checkout: FanfareCheckoutResult;
+} | {
+    kind: "purchase";
+    checkout: FanfareCheckoutResult;
+});
 export interface ExpiredSlotProps extends SlotProps {
     reason: string;
     endedAt?: Date;
@@ -92,6 +160,10 @@ export interface ExperienceWidgetSlots {
     enterable?: (props: EnterableSlotProps) => JSX.Element;
     participating?: (props: ParticipatingSlotProps) => JSX.Element;
     granted?: (props: GrantedSlotProps) => JSX.Element;
+    paymentCollection?: (props: PaymentCollectionSlotProps) => JSX.Element;
+    reservationCheckout?: (props: ReservationCheckoutSlotProps) => JSX.Element;
+    checkoutProcessing?: (props: CheckoutProcessingSlotProps) => JSX.Element;
+    receipt?: (props: ReceiptSlotProps) => JSX.Element;
     expired?: (props: ExpiredSlotProps) => JSX.Element;
     ended?: (props: EndedSlotProps) => JSX.Element;
     error?: (props: ErrorSlotProps) => JSX.Element;
@@ -116,6 +188,10 @@ export interface ExperienceWidgetProps {
     checkoutUrl?: string;
     onJourneyChange?: (snapshot: JourneySnapshot) => void;
     onGranted?: (grant: string) => void;
+    /** Called when a Fanfare-managed checkout completes (pre-auth capture or post-win reservation checkout) */
+    onFanfareCheckout?: (result: FanfareCheckoutResult) => void;
+    /** Called when the consumer wins a `post_win` distribution and must complete checkout before `expiresAt` */
+    onReserved?: (expiresAt: number) => void;
     onError?: (error: Error) => void;
     class?: string;
     className?: string;

package/dist/components/widgets/index.d.ts

@@ -6,6 +6,6 @@
  *
  * @packageDocumentation
  */
-export { ExperienceWidget, type AccessCodeSlotProps, type AuthSlotProps, type ChallengeSlotProps, type EndedSlotProps, type EnterableSlotProps, type ErrorSlotProps, type ExperienceRenderProps, type ExperienceWidgetProps, type ExperienceWidgetSlots, type ExpiredSlotProps, type GrantedSlotProps, type LoadingSlotProps, type ParticipatingSlotProps, type SlotProps, type StartSlotProps, type UpcomingSlotProps, type WaitlistSlotProps, } from './experience-widget';
+export { ExperienceWidget, type AccessCodeSlotProps, type AuthSlotProps, type ChallengeSlotProps, type CheckoutProcessingSlotProps, type EndedSlotProps, type EnterableSlotProps, type ErrorSlotProps, type ExperienceRenderProps, type ExperienceWidgetProps, type ExperienceWidgetSlots, type ExpiredSlotProps, type GrantedSlotProps, type LoadingSlotProps, type ParticipatingSlotProps, type PaymentCollectionSlotProps, type ReceiptSlotProps, type ReservationCheckoutSlotProps, type SlotProps, type StartSlotProps, type UpcomingSlotProps, type WaitlistSlotProps, } from './experience-widget';
 export { LoadingView, StartView, UpcomingModule, WaitlistView, type LoadingViewProps, type StartViewProps, type UpcomingModuleProps, type WaitlistViewProps, } from '../internal';
 export { AppointmentModule, AuctionModule, DrawModule, QueueModule, TimedReleaseModule, type AppointmentModuleProps, type AuctionModuleProps, type DrawModuleProps, type QueueModuleProps, type TimedReleaseModuleProps, } from '../internal';

package/dist/hooks/index.d.ts

@@ -6,7 +6,9 @@
  * @packageDocumentation
  */
 export { useFanfareAuth } from './use-auth';
+export { createBeaconTracker } from './use-beacon-tracker';
 export { useExperienceJourney } from './use-experience-journey';
 export type { ExperienceJourneyOptions, UseExperienceJourneyOptions, UseExperienceJourneyResult, } from './use-experience-journey';
 export { useJourneySnapshot } from './use-journey-snapshot';
 export { useNanostore } from './use-nanostore';
+export { useSdkEvent } from './use-sdk-event';

package/dist/hooks/use-auth.d.ts

@@ -4,6 +4,7 @@ export declare function useFanfareAuth(): {
     isAuthenticated: import('solid-js').Accessor<boolean>;
     isGuest: import('solid-js').Accessor<boolean | undefined>;
     session: import('solid-js').Accessor<import('@fanfare-io/fanfare-sdk-core/auth').Session | undefined>;
+    identityExpiresAt: import('solid-js').Accessor<string | undefined>;
     guest: () => Promise<import('@fanfare-io/fanfare-sdk-core/auth').GuestSession>;
     requestOtp: (options: OtpRequest) => Promise<void>;
     verifyOtp: (options: OtpVerify) => Promise<import('@fanfare-io/fanfare-sdk-core/auth').AuthenticatedSession>;

package/dist/hooks/use-beacon-tracker.d.ts

@@ -0,0 +1,28 @@
+import { BoundBeaconTracker } from '@fanfare-io/fanfare-sdk-core/beacon';
+import { Accessor } from 'solid-js';
+/**
+ * Experience currently rendering around the consumer, as an accessor.
+ * `ExperienceWidget` publishes its `experienceId` here so descendants (slots,
+ * render-prop children, storefront components) can attribute beacon events
+ * without threading the id through props. It is an accessor, not a bare string,
+ * because Solid runs component setup once: a tracker must read the value at
+ * track time so a later change to the widget's `experienceId` prop is honored.
+ * Returns `null` outside any experience.
+ */
+export declare const ExperienceIdContext: import('solid-js').Context<Accessor<string | null>>;
+/**
+ * Creates a beacon tracker scoped to an experience.
+ *
+ * With no argument the tracker binds to the enclosing `ExperienceWidget`'s
+ * experience; pass an `experienceId` to bind explicitly (an override, or for use
+ * outside a widget). Called with neither an argument nor a surrounding
+ * experience, it throws rather than silently emitting unattributed events.
+ *
+ * The bound experience is resolved at each `track`/`trackBatch` call, so if the
+ * enclosing widget's `experienceId` changes, subsequent events follow it.
+ *
+ * @param experienceId - Experience to bind to; defaults to the enclosing widget's
+ * @returns A tracker whose `track`/`trackBatch` stamp events with the experience
+ *   and, once routed, the sequence
+ */
+export declare function createBeaconTracker(experienceId?: string): BoundBeaconTracker;

package/dist/hooks/use-experience-journey.d.ts

@@ -1,3 +1,4 @@
+import { FanfareError } from '@fanfare-io/fanfare-sdk-core/errors';
 import { JourneyHandle, JourneySnapshot, JourneyView } from '@fanfare-io/fanfare-sdk-core/experiences';
 import { MaybeAccessor } from '../utils/to-accessor';
 export interface ExperienceJourneyOptions {
@@ -12,6 +13,7 @@ export interface UseExperienceJourneyResult {
     view: () => JourneyView | null;
     snapshot: () => JourneySnapshot | null;
     error: () => string | null;
+    fanfareError: () => FanfareError | null;
     start: (options?: ExperienceJourneyOptions) => Promise<JourneyView>;
 }
 export declare function useExperienceJourney(experienceId: MaybeAccessor<string | undefined>, options?: UseExperienceJourneyOptions): UseExperienceJourneyResult;

package/dist/hooks/use-sdk-event.d.ts

@@ -0,0 +1,19 @@
+import { SDKEvents } from '@fanfare-io/fanfare-sdk-core/events';
+type SDKEventKey = keyof SDKEvents;
+/**
+ * Subscribe to a typed Fanfare SDK event for the lifetime of the owning scope.
+ *
+ * The SDK instance, the event name and the handler are all captured once at
+ * setup: the subscription is not re-established if the provider later swaps the
+ * SDK instance, `event` is read as a plain value rather than an accessor, and
+ * the handler passed on the first call is the one invoked for every delivery —
+ * unlike the React adapter, which reads its handler from a ref refreshed each
+ * render. Read reactive values inside the handler body, and call the hook again
+ * from a fresh scope to listen for a different event.
+ *
+ * The subscription attaches inside a `createEffect`, so events emitted between
+ * the hook call and the effect flush are not delivered, and under the server
+ * build — where effects never run — the hook is a no-op.
+ */
+export declare function useSdkEvent<K extends SDKEventKey>(event: K, handler: (data: SDKEvents[K]) => void): void;
+export {};

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { FanfareProvider, useFanfare } from './components/provider';
 export type { FanfareProviderProps } from './components/provider';
-export { useExperienceJourney, useFanfareAuth, useJourneySnapshot, useNanostore } from './hooks';
+export { createBeaconTracker, useExperienceJourney, useFanfareAuth, useJourneySnapshot, useNanostore, useSdkEvent, } from './hooks';
 export { I18nProvider, RTL_LOCALES, isRTLLocale, useTranslations } from './i18n';
 export type { I18nConfig, I18nProviderProps, Locale, PartialTranslationMessages, RTLLocale, TextDirection, TranslateFunction, TranslateOptions, TranslationKey, TranslationMessageKey, TranslationMessages, } from './i18n';
 export { THEME_CSS_VARS, ThemeProvider, buildThemeCssVars } from './theme';
@@ -21,7 +21,8 @@ export type { InfoPanelProps, OutcomeReason, PanelBodyProps, PanelFooterProps, P
 export { AccessCodeForm, ChallengeGate, EndedModule, ErrorView, GrantedPanel, OutcomePanel, } from './components/compositions';
 export type { AccessCodeFormProps, ChallengeGateProps, EndedModuleProps, ErrorViewProps, GrantedPanelProps, OutcomePanelProps, } from './components/compositions';
 export { ExperienceWidget } from './components/widgets';
-export type { AccessCodeSlotProps, AuthSlotProps, ChallengeSlotProps, EndedSlotProps, EnterableSlotProps, ErrorSlotProps, ExperienceRenderProps, ExperienceWidgetProps, ExperienceWidgetSlots, ExpiredSlotProps, GrantedSlotProps, LoadingSlotProps, ParticipatingSlotProps, SlotProps, StartSlotProps, UpcomingSlotProps, WaitlistSlotProps, } from './components/widgets';
+export type { AccessCodeSlotProps, AuthSlotProps, ChallengeSlotProps, CheckoutProcessingSlotProps, EndedSlotProps, EnterableSlotProps, ErrorSlotProps, ExperienceRenderProps, ExperienceWidgetProps, ExperienceWidgetSlots, ExpiredSlotProps, GrantedSlotProps, LoadingSlotProps, ParticipatingSlotProps, PaymentCollectionSlotProps, ReceiptSlotProps, ReservationCheckoutSlotProps, SlotProps, StartSlotProps, UpcomingSlotProps, WaitlistSlotProps, } from './components/widgets';
+export { CheckoutProcessingPanel, PaymentCollectionPanel, ReceiptPanel, ReservationCheckoutPanel, } from './components/checkout';
 export { LoadingView, StartView, UpcomingModule, WaitlistView } from './components/widgets';
 export type { LoadingViewProps, StartViewProps, UpcomingModuleProps, WaitlistViewProps } from './components/widgets';
 export { AuctionModule, DrawModule, QueueModule, TimedReleaseModule } from './components/widgets';