@fanfare-io/fanfare-sdk-solid 0.23.0 → 0.25.0

package/README.md

@@ -44,6 +44,27 @@ Solid applications can use `FanfareProvider`, `ExperienceWidget`, and `useExperi
 
 `slots` override targeted states while keeping the default widget flow. `children` receives `{ journey, view, snapshot, error, start, isStarting }` when you want to render the full state yourself. Solid `ExperienceWidget` accepts both `class` and `className`.
 
+Marketing consent in `AuthForm` requires both `showMarketingSmsConsent` and a nonempty
+`marketingSmsMerchantName`. The built-in widget reads the merchant name from the public experience
+response, including before an authenticated experience session exists. Custom auth slots receive
+`marketingSmsMerchantName`; pass it through to `AuthForm` or `JourneyGate` to offer consent for that
+merchant. Sign-in remains available when the merchant name is unavailable.
+
+`AuthForm` keeps marketing copy off the initial phone screen. Continue opens an optional panel
+with the named merchant, Fanfare sender, phone number and full disclosure before any OTP request.
+Only "Yes, text me" opts in. It captures the displayed merchant, phone, disclosure, legal text,
+policy links and affirmative label in `marketingSmsConsentText`, then preserves that snapshot through
+OTP verification and resend. "No thanks" continues without marketing consent. Change number,
+returning from verification or changing the consent scope clears the choice and snapshot.
+Implicit submission can open the panel but cannot choose consent. Custom auth handlers must
+preserve the received choice and text through verification; a custom consent UI supplies its own
+actual displayed agreement. The server requires a nonblank text snapshot of at most 4,096 characters
+to record consent. Missing or invalid evidence leaves sign-in available without granting consent.
+This is client-reported audit evidence, not proof of what pixels were displayed.
+Release a matching core and adapter together: the built-in panel uses core's shared policy URLs
+and consent-text formatter. Deploy the generated database migration and server support before
+releasing SDK callers that supply the text.
+
 Mounted inside a shadow root, the widget's styleable elements export CSS parts named after their
 `data-slot`, so a page styles them with `::part()` — `fanfare-host::part(auction-cta)`. The
 attribution footer and every element that contains its "Powered by Fanfare" row are
@@ -52,6 +73,35 @@ card field is not a part either. A panel whose footer holds no attribution row k
 as a part — `auction-module` is one; [`docs/STYLING.md`](./docs/STYLING.md#parts) lists every
 part and every exception.
 
+### Experience timing
+
+`useExperienceTiming(() => experienceId)` takes the experience id as an accessor and reads that experience's public
+timing once when it mounts, and again when the id changes or you call `refresh()`:
+
+| `status()`  | `timing()`                                                                |
+| ----------- | ------------------------------------------------------------------------- |
+| `"loading"` | `undefined` — the first read for this experience has not finished         |
+| `"error"`   | `undefined` — the read failed; call `refresh()` to try again              |
+| `"ready"`   | the `ExperienceTiming`, or `null` when the experience publishes no timing |
+
+```tsx
+import { useExperienceTiming } from "@fanfare-io/fanfare-sdk-solid";
+import { Show } from "solid-js";
+
+function DropStatus(props: { experienceId: string }) {
+  const timing = useExperienceTiming(() => props.experienceId);
+  return <Show when={timing.status() === "ready" && timing.timing()}>{(t) => <span>{t().status}</span>}</Show>;
+}
+```
+
+`ExperienceTiming` is a type exported from `@fanfare-io/fanfare-sdk-core/experiences`. Its `status` is `upcoming`,
+`open` or `closed`, with `nextOpensAt` and `lastClosedAt` around it. `closesAt` is
+present only while the experience is open, and is `null` when the open run has no end. The primitive never polls
+or schedules a re-read at a boundary, and adds no retry of its own: once `ready`, the result stays as read until
+you call `refresh()`.
+During a refresh the previous result stays in place — a `ready` result keeps its timing and an `error` stays
+`error` — until the new read settles. Primitives that read the same experience at the same time share one request.
+
 ## Selection
 
 Some experiences capture which product and variant a consumer gets. `ExperienceWidget` renders that

package/dist/components/auth/auth-form.d.ts

@@ -2,7 +2,10 @@ import { JSX } from 'solid-js';
 import { PanelHeadingVariant } from '../module';
 import { AuthInputMode } from './auth-input';
 export interface AuthFormProps {
-    onSubmit?: (credential: string, type: AuthInputMode) => Promise<void>;
+    onSubmit?: (credential: string, type: AuthInputMode, options?: {
+        marketingSmsConsent: boolean;
+        marketingSmsConsentText?: string;
+    }) => Promise<void>;
     onVerify?: (otp: string) => Promise<void>;
     onSkip?: () => void | Promise<void>;
     onSuccess?: () => void;
@@ -14,11 +17,21 @@ export interface AuthFormProps {
     description?: string;
     /** When set, renders a countdown above the form. */
     countdownTo?: Date;
+    /** When set and `countdownTo` is not, renders the close time and a sign-in hint above the form. */
+    endedAt?: Date;
     submitLabel?: string;
     verifyLabel?: string;
     allowSkip?: boolean;
     skipLabel?: string;
     showBranding?: boolean;
+    /**
+     * Offers a separate optional marketing SMS panel after credential entry in
+     * phone mode. Off by default: set it only when `onSubmit` preserves its third argument through
+     * verification, so the explicit consent choice and displayed text are not silently dropped.
+     */
+    showMarketingSmsConsent?: boolean;
+    /** Merchant named in the consent disclosure. Consent is offered only when this is nonempty. */
+    marketingSmsMerchantName?: string;
     /** Initial step when mounting. Useful for SSR-resume or storybook lanes that need the verify step. */
     defaultStep?: "credential" | "verify";
     /** Initial credential (email or E.164 phone) — pairs with `defaultStep="verify"`. */

package/dist/components/compositions/journey-gate.d.ts

@@ -3,7 +3,10 @@ import { AuthInputMode } from '../auth/auth-input';
 export type JourneyGateStage = "auth" | "access_code" | "loading" | "none";
 export interface JourneyGateProps {
     stage: JourneyGateStage;
-    onAuthSubmit?: (credential: string, type: AuthInputMode) => Promise<void>;
+    onAuthSubmit?: (credential: string, type: AuthInputMode, options?: {
+        marketingSmsConsent: boolean;
+        marketingSmsConsentText?: string;
+    }) => Promise<void>;
     onAuthVerify?: (otp: string) => Promise<void>;
     onAuthSkip?: () => void | Promise<void>;
     onAuthSuccess?: () => void;
@@ -12,12 +15,16 @@ export interface JourneyGateProps {
     allowAuthSkip?: boolean;
     authSkipLabel?: string;
     allowAccessCodeSkip?: boolean;
+    /** Merchant identity from the experience for marketing SMS consent. */
+    marketingSmsMerchantName?: string;
     authTitle?: string;
     authDescription?: string;
     accessCodeTitle?: string;
     accessCodeDescription?: string;
     /** When the upcoming sequence opens — drives the countdown above the form. */
     startsAt?: Date;
+    /** When the drop closed — drives the ended line on the auth stage. */
+    endedAt?: Date;
     class?: string;
     className?: string;
     children?: JSX.Element;

package/dist/components/internal/draw-module.d.ts

@@ -8,6 +8,7 @@ import { OutcomeReason } from '../module';
 export interface DrawModuleProps {
     display$?: ReadableAtom<DrawDisplayState>;
     sequencePhase: "enterable" | "participating" | "settling" | "granted" | "ended";
+    loyaltyBiasEnabled?: boolean;
     canEnter: boolean;
     canLeave: boolean;
     /** Enter action handler; carries the entry pick on a selection-bearing draw. */

package/dist/components/internal/queue-module.d.ts

@@ -8,6 +8,9 @@ import { OutcomeReason } from '../module';
 export interface QueueModuleProps {
     display$?: ReadableAtom<QueueDisplayState>;
     sequencePhase: "enterable" | "participating" | "granted" | "ended";
+    /** Hide live rank-derived queue metrics while the canonical queue is still pre-open. */
+    hideQueueMetrics?: boolean;
+    loyaltyBiasEnabled?: boolean;
     canEnter: boolean;
     canLeave: boolean;
     onEnter: () => Promise<void>;

package/dist/components/module/fanfair-attribution.d.ts

@@ -0,0 +1,3 @@
+export declare function FanfairAttribution(props: {
+    enabled: boolean;
+}): import("solid-js").JSX.Element;

package/dist/components/primitives/checkbox.d.ts

@@ -0,0 +1,6 @@
+import { JSX } from 'solid-js';
+export interface CheckboxProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, "type"> {
+    /** Label rendered beside the control. */
+    label: JSX.Element;
+}
+export declare function Checkbox(props: CheckboxProps): JSX.Element;

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

@@ -1,6 +1,7 @@
 export { Badge, badgeVariants, type BadgeProps, type BadgeVariant } from './badge';
 export { Button, buttonVariants, type ButtonProps } from './button';
 export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cardVariants, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardProps, type CardTitleProps, } from './card';
+export { Checkbox, type CheckboxProps } from './checkbox';
 export { Countdown, type CountdownProps, type CountdownSize, type CountdownTone } from './countdown';
 export { FadePresence, type FadePresenceProps } from './fade-presence';
 export { FanfareLogo, type FanfareLogoProps } from './fanfare-logo';

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

@@ -31,9 +31,19 @@ export interface StartSlotProps extends SlotProps {
     isStarting: boolean;
 }
 export interface AuthSlotProps extends SlotProps {
-    onSubmit: (credential: string, type: AuthInputMode) => Promise<void>;
+    onSubmit: (credential: string, type: AuthInputMode, options?: {
+        marketingSmsConsent: boolean;
+        marketingSmsConsentText?: string;
+    }) => Promise<void>;
     onVerify: (otp: string) => Promise<void>;
     onSkip?: () => void;
+    /**
+     * Whether the sign-in should offer the optional marketing SMS panel. The widget sets it because its
+     * `onSubmit` reads the consent from its third argument; pass it to `AuthForm` with `onSubmit`.
+     */
+    showMarketingSmsConsent?: boolean;
+    /** Merchant identity to pass to AuthForm beside showMarketingSmsConsent. */
+    marketingSmsMerchantName?: string;
 }
 export interface AccessCodeSlotProps extends SlotProps {
     onSubmit: (code: string) => Promise<void>;

package/dist/hooks/index.d.ts

@@ -9,6 +9,8 @@ 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 { useExperienceTiming } from './use-experience-timing';
+export type { UseExperienceTimingResult } from './use-experience-timing';
 export { useJourneySnapshot } from './use-journey-snapshot';
 export { useNanostore } from './use-nanostore';
 export { useSdkEvent } from './use-sdk-event';

package/dist/hooks/use-auth-gate-experience-details.d.ts

@@ -0,0 +1,10 @@
+import { ExperienceTiming } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { Accessor } from 'solid-js';
+/**
+ * Auth can gate routing before an experience session exists, so its merchant identity and timing
+ * come from the public read until the session's own details name the merchant.
+ */
+export declare function useAuthGateExperienceDetails(experienceId: Accessor<string>, sessionName: Accessor<string | undefined>, sessionTiming: Accessor<ExperienceTiming | null | undefined>, enabled: Accessor<boolean>): {
+    merchantName: Accessor<string | undefined>;
+    timing: Accessor<ExperienceTiming | null | undefined>;
+};

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

@@ -0,0 +1,27 @@
+import { ExperienceTiming } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { Accessor } from 'solid-js';
+/**
+ * Result of {@link useExperienceTiming}.
+ *
+ * - `status() === "loading"`: the first read for this experience has not settled; `timing()` is `undefined`.
+ * - `status() === "error"`: the last read was rejected; `timing()` is `undefined` and `refresh()` reads again.
+ * - `status() === "ready"`: `timing()` is the experience's public timing, or `null` when it publishes none.
+ */
+export interface UseExperienceTimingResult {
+    status: Accessor<"loading" | "error" | "ready">;
+    timing: Accessor<ExperienceTiming | null | undefined>;
+    refresh(): Promise<void>;
+}
+/**
+ * Reads an experience's public timing once when it attaches, and again whenever
+ * `experienceId` changes or `refresh()` is called.
+ *
+ * The primitive never polls, retries or schedules work around the timing's
+ * boundaries; a caller that needs fresher timing calls `refresh()`. While a
+ * refresh is in flight the result is unchanged: a `ready` result keeps its last
+ * timing and an `error` result stays `error` until the read settles. Primitives
+ * that read the same experience at the same time on one SDK instance share a
+ * single request. Results from a superseded read, or from one still in flight
+ * after disposal, are dropped.
+ */
+export declare function useExperienceTiming(experienceId: Accessor<string>): UseExperienceTimingResult;

package/dist/index.d.ts

@@ -7,7 +7,8 @@
  */
 export { FanfareProvider, useFanfare } from './components/provider';
 export type { FanfareProviderProps } from './components/provider';
-export { createBeaconTracker, useExperienceJourney, useFanfareAuth, useJourneySnapshot, useNanostore, useSdkEvent, } from './hooks';
+export { createBeaconTracker, useExperienceJourney, useExperienceTiming, useFanfareAuth, useJourneySnapshot, useNanostore, useSdkEvent, } from './hooks';
+export type { UseExperienceTimingResult } 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';