@fanfare-io/fanfare-sdk-react 0.5.0 → 0.7.0

package/README.md

@@ -44,6 +44,22 @@ Customization has four levels of increasing specificity: `theme`, `variant`, `sl
 
 `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.
 
+## Error handling
+
+The widget classifies every failure into one of four **dispositions** and surfaces it accordingly, so a recoverable error stays in context instead of replacing the screen:
+
+- **INLINE** — recoverable in place (e.g. a wrong OTP). Shown under the active field; journey state is preserved.
+- **STEP_RESET** — the current step's setup is stale (e.g. an expired code). The step re-arms (resend).
+- **RESTART** — the session/admission is no longer valid. The widget reroutes via the journey rather than dead-ending.
+- **PANEL** — terminal. The full-screen error panel — now the exception, not the default.
+
+The displayed copy is **always SDK-owned i18n** (localized via your `FanfareProvider` locale), never the raw server response — a raw payload can never reach the UI.
+
+`onError(error)` receives the real, structured `FanfareError` (it is an `Error` subclass, so the `(error: Error) => void` signature is unchanged). Read `error.code`, `error.status`, `error.action`, and `error.details` for telemetry/handling. Two notes:
+
+- **`onError` now fires more often.** Recoverable inline errors (e.g. an incorrect OTP) now reach `onError` too, not just terminal failures. Treat `onError` as a notification/telemetry channel — do **not** drive full-screen rendering from it, or an inline typo would flash a full-screen error. Filter on `error.code` or the disposition if you need to react only to terminal failures.
+- **Copy is sanitized; details are not.** The strings the widget renders are i18n copy; `error.details` may contain raw server data — log it deliberately, don't surface it to end users.
+
 ## Documentation
 
 - [React components guide](https://docs.fanfare.io/sdk/components/react)

package/dist/components/auth/otp-input.d.ts

@@ -26,6 +26,8 @@ export interface OTPInputProps {
     disabled?: boolean;
     /** Auto focus first input */
     autoFocus?: boolean;
+    /** id of an external element describing the current error (links digits to an AlertPanel). */
+    ariaDescribedBy?: string;
     /** Additional class name */
     className?: string;
 }

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';
 export interface ExperienceJourneyOptions {
     accessCode?: string;
@@ -14,7 +15,10 @@ export interface UseExperienceJourneyResult {
     journey: JourneyHandle | null;
     view: JourneyView | null;
     snapshot: JourneySnapshot | null;
+    /** @deprecated Prefer `fanfareError` for structured, leak-safe handling. */
     error: string | null;
+    /** Structured error from the last failed `start`, preserved for classification. */
+    fanfareError: FanfareError | null;
     start: (options?: ExperienceJourneyOptions) => Promise<JourneyView>;
 }
 export declare function useExperienceJourney(experienceId: string | undefined, options?: UseExperienceJourneyOptions): UseExperienceJourneyResult;