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

package/README.md

@@ -31,6 +31,17 @@ journey.view$.listen((view) => {
 
 The published artifact is self-contained: installable, runnable, and typecheckable using only public package dependencies.
 
+## Error handling (`./errors`)
+
+The `./errors` subpath exposes the client-side error policy the UI adapters route on:
+
+- `classify(code, status?, action?) → { disposition, autoRetryOnce }` — a pure function mapping an error to one of four dispositions (`INLINE` / `STEP_RESET` / `RESTART` / `PANEL`). It is the single source of truth the React/Solid adapters route on and the native SDKs mirror. Unknown codes default to `PANEL`.
+- `toDisplay(error, t) → DisplayError` — projects a `FanfareError` into a render-safe view model whose copy is always SDK-owned i18n (via an injected translator) and which, by type, can hold no raw server content.
+- `toDebug(error) → DebugErrorInfo` — the structured raw payload (status, ids, server `details`) for telemetry; never for rendering.
+- `ensureFanfareError(error)` — normalizes any thrown value into a `FanfareError`.
+
+`classify` takes no React/i18n dependency; the translator is injected as a structural `Translate` type.
+
 ## Documentation
 
 - [Core SDK quickstart](https://docs.fanfare.io/sdk/core/quickstart)

package/dist/core/error-display.d.ts

@@ -0,0 +1,48 @@
+import { Disposition } from './error-disposition';
+import { ConsumerApiError, FanfareError } from './errors';
+/** Options a bound translator accepts. Structurally matches the i18n `t`. */
+export interface TranslateOptions {
+    values?: Record<string, string | number>;
+    count?: number;
+    defaultValue?: string;
+}
+/** Structural type for an injected, locale-bound translate function. */
+export type Translate = (key: string, options?: TranslateOptions) => string;
+/**
+ * Sanitized, render-safe view of an error. Every string is SDK-owned i18n copy.
+ * Deliberately carries NO `details`/`status`/`requestId`/`body` — sanitization
+ * is a property of this type, not of the projector remembering to omit a field.
+ */
+export interface DisplayError {
+    readonly code: string;
+    /** Headline copy, present for terminal (PANEL) errors. */
+    readonly title?: string;
+    /** Primary message; always present. */
+    readonly description: string;
+    readonly disposition: Disposition;
+    /** Seconds until retry, for RATE_LIMITED countdowns (already interpolated into copy too). */
+    readonly retryAfter?: number;
+    /** Opaque support reference/confirmation codes — safe to show. */
+    readonly support?: ConsumerApiError["support"];
+}
+/** Structured debug payload for `onError` telemetry. NOT for rendering. */
+export interface DebugErrorInfo {
+    readonly code: string;
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly correlationId?: string;
+    /** Server `details`, or the raw response body when unenveloped. */
+    readonly details?: unknown;
+    readonly issues?: readonly unknown[];
+}
+/** Project a `FanfareError` into render-safe, i18n-owned `DisplayError`. Pure. */
+export declare function toDisplay(error: FanfareError, t: Translate): DisplayError;
+/**
+ * Normalize any thrown value into a `FanfareError` so the adapter sink can always
+ * classify and project it. SDK requests already throw `FanfareError`; this guards
+ * the rare plain-`Error`/non-error throw (treated as a terminal INTERNAL_ERROR —
+ * its raw message reaches `onError` via the debug channel but never the render seam).
+ */
+export declare function ensureFanfareError(error: unknown): FanfareError;
+/** Project a `FanfareError` into the structured debug payload for `onError`. Pure. */
+export declare function toDebug(error: FanfareError): DebugErrorInfo;

package/dist/core/error-display.js

@@ -0,0 +1 @@
+import{classify as r}from"./error-disposition.js";import{FanfareError as e,ErrorCodes as t}from"./errors.js";const o={[t.OTP_INVALID]:"auth.invalidCode",[t.OTP_EXPIRED]:"auth.codeExpired",[t.INVALID_SESSION]:"common.sessionExpired",[t.INVALID_REFRESH_TOKEN]:"common.sessionExpired"};function i(r){return"INLINE"===r||"STEP_RESET"===r?"error.inlineGeneric":"error.description"}function s(e,s){const{disposition:n}=r(e.code,e.status,e.action),d="number"==typeof e.retryAfter&&Number.isFinite(e.retryAfter)?e.retryAfter:void 0,c=function(r,e,s){return r===t.RATE_LIMITED?s?"error.rateLimited":"error.rateLimitedGeneric":o[r]??i(e)}(e.code,n,void 0!==d);let u=s(c,void 0!==d?{values:{seconds:d}}:void 0);u.includes("{{")&&(u=s(i(n)));const E="PANEL"===n?s("error.title"):void 0;return{code:e.code,title:E,description:u,disposition:n,retryAfter:e.retryAfter,support:e.support}}function n(r){if(r instanceof e)return r;const o=r instanceof Error?r.message:String(r);return new e(o,t.INTERNAL_ERROR)}function d(r){return{code:r.code,status:r.status,requestId:r.requestId,correlationId:r.correlationId,details:r.details,issues:r.issues}}export{n as ensureFanfareError,d as toDebug,s as toDisplay};

package/dist/core/error-disposition.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Error disposition policy — the SDK's client-side decision about HOW a failure
+ * should be surfaced, independent of any UI framework.
+ *
+ * This is deliberately separate from the wire contract (the server never sends a
+ * disposition) and from `classifyHttpError` (which only decides code +
+ * transport-retryability). It is the single source of truth that the React/Solid
+ * adapters route on and that the native SDKs mirror by hand.
+ */
+/**
+ * Where/how a failure is surfaced:
+ * - `INLINE` — recoverable in place under the active field; preserve journey state.
+ * - `STEP_RESET` — the current step's setup is dead; re-arm it (e.g. resend OTP),
+ *   discarding the now-invalid input.
+ * - `RESTART` — session/admission/capability is dead; reroute to an earlier step
+ *   (reuses the existing `view.reroute()` / `action: "reroute"` machinery).
+ * - `PANEL` — terminal; render the full-screen error panel. The conservative
+ *   default for anything not explicitly recoverable.
+ */
+export type Disposition = "INLINE" | "STEP_RESET" | "RESTART" | "PANEL";
+export interface ClassifyResult {
+    readonly disposition: Disposition;
+    /**
+     * Whether a single idempotent silent retry is permitted. Always `false` today:
+     * mutating POSTs carry no idempotency key, so a silent retry could double-submit.
+     * The flag is computed (transport-transient + not anti-fraud) so the eligibility
+     * rule is encoded now, but it is gated off until idempotency keys exist.
+     */
+    readonly autoRetryOnce: boolean;
+}
+/**
+ * Classify a failure into a UI disposition + auto-retry eligibility. Pure and
+ * framework-free. `status` is the HTTP status (used only for auto-retry
+ * eligibility — disposition is code-driven); `action` is the server flow hint.
+ */
+export declare function classify(code: string, status?: number, action?: string): ClassifyResult;

package/dist/core/error-disposition.js

@@ -0,0 +1 @@
+import{ErrorCodes as E}from"./errors.js";const I={[E.OTP_INVALID]:"INLINE",[E.INVALID_CREDENTIALS]:"INLINE",[E.VALIDATION_ERROR]:"INLINE",[E.RATE_LIMITED]:"INLINE",[E.SLOT_OUT_OF_WINDOW]:"INLINE",[E.OTP_EXPIRED]:"STEP_RESET",[E.BOT_CHALLENGE_INVALID]:"STEP_RESET",[E.BOT_CHALLENGE_EXPIRED]:"STEP_RESET",[E.SLOT_EXPIRED]:"STEP_RESET",[E.SLOT_NOT_AVAILABLE]:"STEP_RESET",[E.INVALID_SESSION]:"RESTART",[E.INVALID_REFRESH_TOKEN]:"RESTART",[E.UNAUTHORIZED]:"RESTART",[E.ENTRY_TOKEN_REQUIRED]:"RESTART",[E.ENTRY_TOKEN_INVALID]:"RESTART",[E.ENTRY_TOKEN_EXPIRED]:"RESTART",[E.ADMISSION_GRANT_INVALID]:"RESTART",[E.ADMISSION_PROOF_REQUIRED]:"RESTART",[E.ADMISSION_KEY_THUMBPRINT_REQUIRED]:"RESTART",[E.ADMISSION_ORIGINAL_ENTRY_REQUIRED]:"RESTART",[E.RATE_LIMIT_UNAVAILABLE]:"PANEL",[E.FINGERPRINT_REQUIRED]:"PANEL",[E.FINGERPRINT_DEVICE_MISMATCH]:"PANEL",[E.FINGERPRINT_INVALID]:"PANEL",[E.BOT_CHALLENGE_SUBJECT_MISMATCH]:"PANEL",[E.ADMISSION_KEY_MISMATCH]:"PANEL",[E.DISTRIBUTION_NOT_OPEN]:"PANEL",[E.DISTRIBUTION_CLOSED]:"PANEL",[E.DISTRIBUTION_FULL]:"PANEL",[E.DISTRIBUTION_ORDER_LIMIT]:"PANEL",[E.PROTOCOL_ERROR]:"PANEL"},T=/* @__PURE__ */new Set([E.ENTRY_TOKEN_MISMATCH]);function R(E,R,N){const _=function(E,R){return"reroute"===R&&T.has(E)?"RESTART":I[E]??"PANEL"}(E,N);return{disposition:_,autoRetryOnce:false}}export{R as classify};

package/dist/core/errors.d.ts

@@ -41,6 +41,7 @@ export declare const ErrorCodes: {
     readonly DISTRIBUTION_NOT_OPEN: "DISTRIBUTION_NOT_OPEN";
     readonly DISTRIBUTION_CLOSED: "DISTRIBUTION_CLOSED";
     readonly DISTRIBUTION_FULL: "DISTRIBUTION_FULL";
+    readonly DISTRIBUTION_ORDER_LIMIT: "DISTRIBUTION_ORDER_LIMIT";
     readonly FINGERPRINT_REQUIRED: "FINGERPRINT_REQUIRED";
     readonly FINGERPRINT_DEVICE_MISMATCH: "FINGERPRINT_DEVICE_MISMATCH";
     readonly FINGERPRINT_INVALID: "FINGERPRINT_INVALID";

package/dist/errors.d.ts

@@ -1,5 +1,9 @@
 /**
  * Public error surface. `classifyHttpError` is an internal helper and is not exported here.
  */
+export { ensureFanfareError, toDebug, toDisplay } from './core/error-display';
+export type { DebugErrorInfo, DisplayError, Translate, TranslateOptions } from './core/error-display';
+export { classify } from './core/error-disposition';
+export type { ClassifyResult, Disposition } from './core/error-disposition';
 export { ErrorCodes, FanfareError, ProtocolError, createError, isCapabilityGrantError, isCapabilityGrantRerouteError, isCapabilityTokenError, isCapabilityTokenRerouteError, isFanfareError, isProtocolError, } from './core/errors';
 export type { ErrorCode } from './core/errors';

package/dist/errors.js

@@ -1 +1 @@
-import{ErrorCodes as r,FanfareError as o,ProtocolError as e,createError as m,isCapabilityGrantError as p,isCapabilityGrantRerouteError as s,isCapabilityTokenError as t,isCapabilityTokenRerouteError as c,isFanfareError as f,isProtocolError as i}from"./core/errors.js";export{r as ErrorCodes,o as FanfareError,e as ProtocolError,m as createError,p as isCapabilityGrantError,s as isCapabilityGrantRerouteError,t as isCapabilityTokenError,c as isCapabilityTokenRerouteError,f as isFanfareError,i as isProtocolError};
+import{ensureFanfareError as r,toDebug as o,toDisplay as e}from"./core/error-display.js";import{classify as i}from"./core/error-disposition.js";import{ErrorCodes as s,FanfareError as m,ProtocolError as p,createError as t,isCapabilityGrantError as c,isCapabilityGrantRerouteError as f,isCapabilityTokenError as j,isCapabilityTokenRerouteError as d,isFanfareError as a,isProtocolError as l}from"./core/errors.js";export{s as ErrorCodes,m as FanfareError,p as ProtocolError,i as classify,t as createError,r as ensureFanfareError,c as isCapabilityGrantError,f as isCapabilityGrantRerouteError,j as isCapabilityTokenError,d as isCapabilityTokenRerouteError,a as isFanfareError,l as isProtocolError,o as toDebug,e as toDisplay};

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * SDK version
  * This is automatically updated during the build process
  */
-export declare const version = "0.5.0";
+export declare const version = "0.7.0";

package/dist/version.js

@@ -1 +1 @@
-const o="0.5.0";export{o as version};
+const o="0.7.0";export{o as version};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanfare-io/fanfare-sdk-core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Official Fanfare Browser SDK for queue, draw, auction, and appointment experiences",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -122,7 +122,7 @@
     "uuid": "^14.0.0",
     "wretch": "^2.11.0",
     "zustand": "^5.0.6",
-    "@fanfare-io/fanfare-sdk-contracts": "0.5.0"
+    "@fanfare-io/fanfare-sdk-contracts": "0.7.0"
   },
   "peerDependencies": {
     "valibot": "^1.1.0",
@@ -165,7 +165,7 @@
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4",
-    "@fanfare-io/shared-models": "0.5.0"
+    "@fanfare-io/shared-models": "0.7.0"
   },
   "sideEffects": false,
   "keywords": [