@arkyc/widget 1.2.11 → 2.0.0

package/dist/types.d.mts

@@ -3,7 +3,7 @@ import { FaceAnalyzer, FaceTuning } from "./face.mjs";
 import { AddressFormData } from "./ui.mjs";
 import { ProviderSignalHints } from "./client.mjs";
 import { WidgetRealtimeFactory } from "./realtime.mjs";
-import { DocumentType, LivenessChallenge, ProjectBranding, WidgetResult } from "@arkyc/types";
+import { DocumentType, LivenessChallenge, ProjectBranding, SessionTransitionEvent, WidgetResult } from "@arkyc/types";
 
 //#region src/types.d.ts
 interface RgbData {
@@ -15,18 +15,58 @@ interface RgbData {
   str: string;
 }
 /**
- * An event surfaced to consumers through `onEvent` / `handle.on(name, cb)`. The
- * stream is a firehose: `session.transition` (live status changes, from the
- * configured transport) plus the lifecycle events `complete` / `error` / `close`.
+ * Payload for `session.transition` — a live verification status change relayed
+ * from the configured transport (pusher/firebase/polling). A widget-scoped
+ * subset of the server's {@link SessionTransitionEvent} (no org/project ids).
  */
-interface WidgetEvent {
-  /** Event name, e.g. `session.transition`, `complete`, `error`, `close`. */
-  name: string;
-  /** Event payload (shape depends on `name`). */
-  data?: unknown;
+type WidgetSessionTransitionData = Pick<SessionTransitionEvent, 'session_id' | 'status' | 'previous_status'>;
+/**
+ * Payload for `error` — a non-terminal failure surfaced as it happens (an
+ * expired session/token becomes knowable without waiting for the user to
+ * dismiss the screen). `status`/`error` are present only for typed API errors.
+ */
+interface WidgetErrorData {
+  /** Human-readable failure message. */
+  message: string;
+  /** HTTP status code, when the failure came from a typed API error. */
+  status?: number;
+  /** Stable machine-readable error key, when the failure came from a typed API error. */
+  error?: string;
+}
+/**
+ * The set of widget events and the payload each delivers. This is the single
+ * source of truth for event names and their `data` shapes: `onEvent`,
+ * {@link WidgetEvent}, {@link WidgetEventListener}, and {@link WidgetHandle.on}
+ * are all derived from it, so a listener's `data` is typed from the name.
+ */
+interface WidgetEventMap {
+  /** Live status change (fires on every real transition, once per change). */
+  'session.transition': WidgetSessionTransitionData;
+  /** The flow settled successfully; carries the final verification result. */
+  complete: WidgetResult;
+  /** A failure occurred (may be recoverable; the flow has not necessarily ended). */
+  error: WidgetErrorData;
+  /** The widget was closed (camera released). No payload. */
+  close: undefined;
 }
-/** Subscribe to a named widget event; returns an unsubscribe function. */
-type WidgetEventListener = (data: unknown) => void;
+/** A widget event name — one of the keys of {@link WidgetEventMap}. */
+type WidgetEventName = keyof WidgetEventMap;
+/**
+ * An event surfaced to consumers through `onEvent`. Discriminated on `name`, so
+ * a `switch (event.name)` narrows `event.data` to the matching payload. The
+ * stream is a firehose: `session.transition` (live status changes) plus the
+ * lifecycle events `complete` / `error` / `close`.
+ */
+type WidgetEvent = { [K in WidgetEventName]: {
+  /** Event name (discriminant). */name: K; /** Event payload for this `name` (see {@link WidgetEventMap}). */
+  data: WidgetEventMap[K];
+} }[WidgetEventName];
+/**
+ * Subscribe callback for a single named widget event; receives that event's
+ * payload (typed from the name via {@link WidgetEventMap}). Defaults to the
+ * union of all payloads when the name isn't fixed.
+ */
+type WidgetEventListener<K extends WidgetEventName = WidgetEventName> = (data: WidgetEventMap[K]) => void;
 /** Configuration for a {@link WidgetController}. */
 interface WidgetControllerConfig {
   /** Short-lived client token for this session. */
@@ -151,11 +191,13 @@ interface WidgetHandle {
   /** Close the widget and release the camera (fires `onClose`). */
   close: () => void;
   /**
-   * Subscribe to a named widget event (e.g. `session.transition`, `complete`).
-   * Returns an unsubscribe function. Registering a listener activates the event
-   * stream (events are only delivered while at least one listener is active).
+   * Subscribe to a named widget event (`session.transition`, `complete`,
+   * `error`, `close`). The `listener`'s `data` is typed from the `event` name
+   * via {@link WidgetEventMap}. Returns an unsubscribe function. Registering a
+   * listener activates the event stream (events are only delivered while at
+   * least one listener is active).
    */
-  on: (event: string, listener: WidgetEventListener) => () => void;
+  on: <K extends WidgetEventName>(event: K, listener: WidgetEventListener<K>) => () => void;
 }
 /** High-level events the view raises back to the controller. */
 interface ViewHandlers {
@@ -181,5 +223,5 @@ interface ViewHandlers {
   onShareLocation(): boolean | Promise<boolean>;
 }
 //#endregion
-export { BaseWidgetOptions, MountWidgetOptions, RgbData, ViewHandlers, WidgetControllerConfig, WidgetEvent, WidgetEventListener, WidgetHandle };
+export { BaseWidgetOptions, MountWidgetOptions, RgbData, ViewHandlers, WidgetControllerConfig, WidgetErrorData, WidgetEvent, WidgetEventListener, WidgetEventMap, WidgetEventName, WidgetHandle, WidgetSessionTransitionData };
 //# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;UAQiB,OAAA;EACf,GAAA;IAAO,CAAA;IAAW,CAAA;IAAW,CAAA;EAAA;EAC7B,GAAA;AAAA;;;;;AAAG;UAQY,WAAA;EAAW;EAE1B,IAAA;EAAA;EAEA,IAAI;AAAA;;KAIM,mBAAA,IAAuB,IAAa;;UAG/B,sBAAA;EAAA;EAEf,KAAA;;EAEA,OAAA;EAUU;EARV,OAAA;EAUkB;EARlB,UAAA;EACA,QAAA,GAAW,eAAA;EAsBL;;;;EAjBN,OAAA,GAAU,mBAAA;EACV,UAAA,IAAc,MAAA,EAAQ,YAAA;EACtB,OAAA,IAAW,KAAA,EAAO,KAAA;EAClB,OAAA;EAqCuC;;;;;EA/BvC,OAAA,IAAW,KAAA,EAAO,WAAA;EAdlB;EAgBA,QAAA;EAXA;EAaA,YAAA;EAGA,KAAA,UAAe,KAAA;EACf,GAAA,GAAM,QAAA;EACN,GAAA,GAAM,MAAA;EACN,GAAA,GAAM,SAAA;EAjBY;;;;;EAuBlB,YAAA,GAAe,YAAA;EAdf;EAgBA,UAAA,GAAa,UAAA;EAXb;;;;;EAiBA,gBAAA,GAAmB,gBAAA;EAdnB;EAgBA,cAAA,GAAiB,cAAA;EAVjB;;;;EAeA,eAAA,GAAkB,qBAAA;EAPC;EASnB,SAAA,IAAa,EAAA,cAAgB,EAAA;EAPZ;EASjB,WAAA;EAJkB;EAMlB,MAAA;EAJa;EAMb,QAAA;EAJA;EAMA,eAAA;AAAA;;UAIe,iBAAA;EAJA;EAMf,KAAA;EAFgC;EAIhC,OAAA;EAaW;;;;;EAPX,OAAA;EA4BM;;;;EAvBN,UAAA;EA+BmB;EA7BnB,QAAA,GAAW,eAAA;EA+BoB;;;;EA1B/B,UAAA;EAPA;EASA,OAAA,GAAU,mBAAA;EACV,UAAA,IAAc,MAAA,EAAQ,YAAA;EACtB,OAAA,IAAW,KAAA,EAAO,KAAA;EAClB,OAAA;EAHU;;;;;;EAUV,OAAA,IAAW,KAAA,EAAO,WAAA;EAGlB,KAAA,UAAe,KAAA;EACf,GAAA,GAAM,QAAA;EACN,GAAA,GAAM,MAAA;EACN,GAAA,GAAM,SAAA;EAHN;EAKA,YAAA,GAAe,YAAA;EAJf;EAMA,UAAA,GAAa,UAAA;EALb;EAOA,gBAAA,GAAmB,gBAAA;EANnB;EAQA,cAAA,GAAiB,cAAA;AAAA;;UAIF,kBAAA,SAA2B,iBAAiB;EAR9C;EAUb,SAAA,WAAoB,WAAA;AAAA;;UAIL,YAAA;EAVgB;EAY/B,KAAA;EARe;;;;;EAcf,EAAA,GAAK,KAAA,UAAe,QAAA,EAAU,mBAAmB;AAAA;;UAIlC,YAAA;EACf,OAAA;EACA,OAAA;EACA,kBAAA,CAAmB,IAAA,EAAM,YAAA,EAAc,OAAA;EAPU;EASjD,OAAA,CAAQ,IAAA,EAAM,IAAA;EATd;;;;EAcA,gBAAA,CAAiB,KAAA,EAAO,IAAA,SAAa,SAAA,EAAW,iBAAA,IAAqB,MAAA,GAAS,IAAA;EAd7B;EAgBjD,aAAA;EAZ2B;EAc3B,UAAA;EAXyB;EAazB,cAAA;EANwB;EAQxB,SAAA,CAAU,IAAA,EAAM,eAAA;EAR8D;EAU9E,eAAA,cAA6B,OAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkyc/widget",
-  "version": "1.2.11",
+  "version": "2.0.0",
   "description": "Embeddable, framework-agnostic Arkyc identity-verification widget",
   "license": "MIT",
   "keywords": [
@@ -39,8 +39,9 @@
     "dist"
   ],
   "dependencies": {
+    "@arkstack/realtime": "^0.19.4",
     "qrcode-generator": "^1.4.4",
-    "@arkyc/types": "^1.2.11"
+    "@arkyc/types": "^2.0.0"
   },
   "peerDependencies": {
     "firebase": "^11.0.0",