@fanfare-io/fanfare-sdk-react 0.11.0 → 0.12.0

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

@@ -0,0 +1,10 @@
+import { CheckoutProcessingSlotProps } from '../widgets/experience-widget';
+import * as React from "react";
+/**
+ * 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): React.ReactElement;

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 { PaymentCollectionSlotProps } from '../widgets/experience-widget';
+import * as React from "react";
+/**
+ * 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({ preAuthAmount, preAuthCurrencyCode, savedPaymentMethods, paymentProvider, onEnter, isEntering, intent, pendingAction, onRetryPaymentConfig, ...slotProps }: PaymentCollectionSlotProps): React.ReactElement;

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

@@ -0,0 +1,10 @@
+import { ReceiptSlotProps } from '../widgets/experience-widget';
+import * as React from "react";
+/**
+ * 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): React.ReactElement;

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

@@ -0,0 +1,18 @@
+import { ReservationCheckoutSlotProps } from '../widgets/experience-widget';
+import * as React from "react";
+/**
+ * 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({ reservation, savedPaymentMethods, processor, paymentProvider, pendingAction, onConfirm, onResume, isConfirming, onRetryPaymentConfig, ...slotProps }: ReservationCheckoutSlotProps): React.ReactElement;

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

@@ -0,0 +1,29 @@
+import { StripeClientConfig } from './stripe-client';
+/**
+ * The SDK's card-entry field: a Stripe Card Element and the controller that turns it into a
+ * payment-method id. It knows nothing about reservations, pre-auth, or amounts.
+ *
+ * `@stripe/stripe-js` is a type-only dependency across the SDK, so no vendor bytes ship in any
+ * chunk. This module is the one lazy split: it is reached only through a dynamic `import()` from
+ * the panel that renders new-card entry, so the Card Element wiring stays out of the adapter's
+ * entry chunk. Nothing statically imported from `src/index.ts` may reach it.
+ *
+ * Stripe.js is unsupported inside a shadow root, and the Solid adapter's web components attach one
+ * unconditionally, so the element mounts into a container this file appends to the light DOM and
+ * positions over its in-panel anchor. The theme's custom properties do not cross the shadow
+ * boundary, so the resolved values the card style needs are copied onto that container.
+ */
+import * as React from "react";
+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;
+}
+export declare function StripeCardField({ config, onController, onChange }: StripeCardFieldProps): React.ReactElement;

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/checkout/use-payment-challenge.d.ts

@@ -0,0 +1,32 @@
+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: PaymentChallengePhase;
+    /** Localized copy for the attempt that produced it; terminal until another attempt starts. */
+    error: string | null;
+    /** Set together with `error`, and cleared when the next attempt starts. */
+    recovery: 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 usePaymentChallenge(config: StripeClientConfig | null): PaymentChallenge;

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

@@ -0,0 +1,8 @@
+import { PaymentMethodSummary } from '@fanfare-io/fanfare-sdk-core/experiences';
+/**
+ * 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 usePaymentMethodSelection(savedPaymentMethods: PaymentMethodSummary[]): [string | undefined, (id: string) => void];

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, WidgetVariant } from '../../theme';
 import { AuthInputMode } from '../auth/auth-input';
 import * as React from "react";
@@ -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;
@@ -93,6 +161,10 @@ export interface ExperienceWidgetSlots {
     enterable?: (props: EnterableSlotProps) => React.ReactNode;
     participating?: (props: ParticipatingSlotProps) => React.ReactNode;
     granted?: (props: GrantedSlotProps) => React.ReactNode;
+    paymentCollection?: (props: PaymentCollectionSlotProps) => React.ReactNode;
+    reservationCheckout?: (props: ReservationCheckoutSlotProps) => React.ReactNode;
+    checkoutProcessing?: (props: CheckoutProcessingSlotProps) => React.ReactNode;
+    receipt?: (props: ReceiptSlotProps) => React.ReactNode;
     expired?: (props: ExpiredSlotProps) => React.ReactNode;
     ended?: (props: EndedSlotProps) => React.ReactNode;
     error?: (props: ErrorSlotProps) => React.ReactNode;
@@ -129,12 +201,16 @@ export interface ExperienceWidgetProps {
     onJourneyChange?: (snapshot: JourneySnapshot) => void;
     /** Called when the journey receives a grant */
     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;
     /** Called when an error occurs */
     onError?: (error: Error) => void;
     /** Additional class name */
     className?: string;
 }
-export declare function ExperienceWidget({ experienceId, autoStart, accessCode, autoEnterWaitlist, theme, variant, slots, children, checkoutUrl, onJourneyChange, onGranted, onError, className, }: ExperienceWidgetProps): import("react/jsx-runtime").JSX.Element;
+export declare function ExperienceWidget({ experienceId, autoStart, accessCode, autoEnterWaitlist, theme, variant, slots, children, checkoutUrl, onJourneyChange, onGranted, onFanfareCheckout, onReserved, onError, className, }: ExperienceWidgetProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ExperienceWidget {
     var displayName: string;
 }

package/dist/hooks/use-fanfare-dom-bridge.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Mirrors one journey into a stable DOM target.
+ *
+ * The bridge latches `data-fanfare-version`, `data-fanfare-experience-id`,
+ * `data-fanfare-stage`, `data-fanfare-phase`, `data-fanfare-mechanism`,
+ * `data-fanfare-expires-at`, and `data-fanfare-outcome` on `opts.target`,
+ * defaulting to `document.documentElement`, and dispatches `fanfare:state-change`
+ * on that same element. Queue position is event-only, and a terminal outcome
+ * crosses as its type alone — the free-text qualifier that may accompany one
+ * stays on the typed SDK surface.
+ * Installation happens in an effect, so the first paint can be unbridged;
+ * vanilla `createDomBridge` stamps synchronously.
+ *
+ * Install stamps the current state and emits nothing; events are
+ * transition-only, so a consumer waiting for one may wait arbitrarily long — or
+ * forever, when the journey has ended or its queue is stable — and should read
+ * the latched attributes instead of expecting an initial event.
+ *
+ * Unmounting or changing `experienceId` disposes the bridge, which returns the
+ * bridge attributes to their pre-install state. Changing `opts.target` does not
+ * reinstall it. The target must be an
+ * already-mounted, stable element; a `ref.current` read in the render that
+ * creates the ref is null. Use this hook from a keyed subtree to move targets.
+ * `{ target: ref.current ?? undefined }` — the natural React spelling —
+ * silently bridges `document.documentElement`, because a nullish target is
+ * indistinguishable from "no target wanted".
+ *
+ * Calling this hook twice for the same experience and target is unsupported:
+ * it duplicates events, creates conflicting stamps, and allows one owner to
+ * remove the other owner's stamps during teardown. Distinct experiences alone
+ * do not separate two hooks: two calls with no `opts.target` both stamp
+ * `document.documentElement` and contend for the same attribute names, so give
+ * each call its own target when a page bridges more than one experience. The
+ * hook also creates the journey on read when one does not already exist, which
+ * arms its pollers.
+ *
+ * A reinstall emits nothing. When the context SDK identity changes — the `ssr`
+ * read-only SDK swapping to the live SDK on first paint, or a provider
+ * re-init — the hook disposes and reinstalls; install stamps without emitting,
+ * so an events-only consumer never learns of a delta it did not cause. The
+ * attributes remain correct.
+ *
+ * Dispose the bridge before destroying its handle or SDK. Destroying either
+ * while the bridge is live emits one final ready-projection event and restamps
+ * ready attributes — a reset the bridge cannot distinguish from a legitimate
+ * restart. Under `FanfareProvider`, unmount is safe: the provider defers SDK
+ * destruction through its lifecycle queue, so this hook's dispose runs first
+ * and that path emits no such event. When the provider replaces its SDK
+ * without unmounting the bridge — a change to a config value, or `ssr` mode
+ * dropping `publishableKey` — that ordering is not guaranteed and a live
+ * bridge may emit one final ready event and restamp. A caller supplying its
+ * own SDK through `FanfareContext` gets no deferral and is a direct-destroy
+ * caller.
+ */
+export declare function useFanfareDomBridge(experienceId: string | undefined, opts?: {
+    target?: Element;
+}): void;

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

@@ -0,0 +1,20 @@
+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 component.
+ *
+ * The handler is read from a ref refreshed on every render, so passing an inline
+ * closure never re-subscribes. The subscription is re-established when the SDK
+ * instance identity changes (the provider swapping its first-paint SDK for the
+ * live one) or when `event` changes; events emitted during such a swap are not
+ * delivered.
+ *
+ * @example
+ * ```tsx
+ * useSdkEvent("journey:granted", (data) => {
+ *   analytics.track("granted", { experienceId: data.experienceId });
+ * });
+ * ```
+ */
+export declare function useSdkEvent<K extends SDKEventKey>(event: K, handler: (data: SDKEvents[K]) => void): void;
+export {};