react-native-usesense 1.0.0 → 2.1.0

package/lib/commonjs/index.js

@@ -3,177 +3,250 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = exports.UseSense = void 0;
+Object.defineProperty(exports, "FlowError", {
+  enumerable: true,
+  get: function () {
+    return _flows.FlowError;
+  }
+});
+exports.UseSense = void 0;
+Object.defineProperty(exports, "UseSenseFlows", {
+  enumerable: true,
+  get: function () {
+    return _flows.UseSenseFlows;
+  }
+});
+exports.default = void 0;
 var _reactNative = require("react-native");
-const {
-  UseSenseModule
-} = _reactNative.NativeModules;
+var _flows = require("./flows");
+const LINKING_ERROR = `react-native-usesense: the native module could not be found.\n\n` + _reactNative.Platform.select({
+  ios: `iOS: run \`cd ios && pod install\` and rebuild the app.`,
+  android: `Android: rebuild the app after installing the package.`,
+  default: ''
+}) + `\n\nIf you're using Expo, the plugin must be consumed through a development build; it does not support Expo Go because it wraps a native camera SDK.`;
+const UseSenseModule = _reactNative.NativeModules.UseSenseModule;
 if (!UseSenseModule) {
-  throw new Error('react-native-usesense: NativeModule not found. Make sure you have linked the library correctly.\n' + 'iOS: Run `cd ios && pod install`\n' + 'Android: Rebuild the app after installing the package.');
+  throw new Error(LINKING_ERROR);
 }
 
-// ─── Types ───────────────────────────────────────────────────────────
+// ─── Types ───────────────────────────────────────────────────────────────
 
-/** Environment for the UseSense API. */
+/**
+ * Target environment for the UseSense API. `auto` asks the native SDK
+ * to detect from the API key prefix (`sk_sandbox_*` → sandbox,
+ * `sk_prod_*` → production).
+ */
 
-/** Session type for verification. */
+/** Type of verification session. */
 
-/** Challenge policy controlling verification difficulty. */
+/**
+ * Decision returned by the native SDK.
+ *
+ * These values come straight from the server's verdict and are
+ * exposed to the integrator for UI feedback only. The definitive
+ * verdict arrives at your backend via an HMAC-signed webhook; never
+ * trust the client-side decision for access-control.
+ */
 
-/** Decision returned by the verification engine. */
+/**
+ * Branding overrides applied to the native camera UI.
+ *
+ * - `logoUrl`, `primaryColor`, `buttonRadius`, `fontFamily` are
+ *   honoured on both iOS and Android.
+ * - `displayName`, `redirectUrl` are Android-only fields. They're
+ *   accepted on iOS for cross-platform API parity but ignored.
+ */
 
-/** Processing stage during server-side analysis. */
+/**
+ * Configuration for `UseSense.initialize`. The minimum required
+ * field is the API key; every other field has a sensible default.
+ */
 
 /**
- * Configuration for initializing the UseSense plugin.
- *
- * @example
- * ```ts
- * await UseSense.initialize({
- *   apiKey: 'your_api_key',
- *   environment: 'sandbox',
- * });
- * ```
+ * Request to start a verification session.
  */
 
 /**
- * Result returned when a verification session completes.
+ * Redacted decision object returned when a session completes.
  *
- * **Important:** This result is for UI feedback only.
- * The definitive verdict arrives at your backend via HMAC-signed webhook.
+ * This is the ONLY shape the plugin exposes to React Native. Pillar
+ * scores (channel trust, liveness, matchsense risk) are intentionally
+ * not included — the native SDKs strip those fields before returning
+ * across the bridge to prevent reverse-engineering of the server-side
+ * scoring logic. If you need full scoring details, consume the signed
+ * webhook delivered to your backend.
  */
 
 /**
- * Error returned when a verification session fails.
+ * Error thrown when a verification session fails.
+ *
+ * Matches the native SDKs' error shape: machine-readable code,
+ * human-readable message, retry hint.
  */
 
 /**
- * Events emitted during the verification session lifecycle.
+ * Lifecycle event types emitted by the native SDK during a
+ * verification session.
  */
 
-/** Options for starting a verification session. */
+/** Single event emitted during a session. */
 
-/** Status of a verification session. */
+/** Handle returned by `UseSense.addListener`. */
 
-/** Subscription handle returned by {@link UseSense.addListener}. */
-
-// ─── Implementation ──────────────────────────────────────────────────
+// ─── Implementation ──────────────────────────────────────────────────────
 
 const eventEmitter = new _reactNative.NativeEventEmitter(UseSenseModule);
 
 /**
  * UseSense React Native plugin.
  *
- * Provides human presence verification by wrapping the native UseSense
- * iOS and Android SDKs into a single cross-platform API.
+ * Human presence verification wrapping the native iOS and Android
+ * UseSense SDKs. Every session runs inside a full-screen native
+ * camera activity; the plugin is a thin bridge that forwards
+ * initialization, verification requests, and lifecycle events to
+ * the platform SDK and returns a redacted decision object.
  *
  * @example
  * ```ts
  * import { UseSense } from 'react-native-usesense';
  *
- * await UseSense.initialize({ apiKey: 'your_key', environment: 'sandbox' });
- * const result = await UseSense.startSession({ sessionType: 'enrollment' });
- * console.log(result.decision);
+ * await UseSense.initialize({
+ *   apiKey: 'sk_sandbox_...',
+ *   environment: 'sandbox',
+ * });
+ *
+ * const unsubscribe = UseSense.addListener((event) => {
+ *   console.log(event.type, event.data);
+ * });
+ *
+ * try {
+ *   const result = await UseSense.startVerification({
+ *     sessionType: 'enrollment',
+ *   });
+ *   console.log(result.decision); // 'APPROVE' | 'REJECT' | 'MANUAL_REVIEW'
+ * } finally {
+ *   unsubscribe.remove();
+ * }
  * ```
  */
 class UseSense {
   /**
-   * Initialize the UseSense plugin. Must be called once before any other method.
+   * Initialize the UseSense plugin. Must be called before any other
+   * method. Calling again with a different API key or environment
+   * replaces the previous configuration.
    *
-   * @param config - Plugin configuration including API key and environment.
-   * @throws {UseSenseError} If the API key is invalid or configuration is malformed.
+   * @throws {UseSenseError} If the API key is empty or initialization
+   * fails on the native side.
    */
   static async initialize(config) {
     if (!config.apiKey) {
-      throw {
+      const err = {
         code: 'invalid_config',
-        message: 'apiKey is required'
+        message: 'apiKey is required',
+        isRetryable: false
       };
+      throw err;
     }
     return UseSenseModule.initialize({
       apiKey: config.apiKey,
-      environment: config.environment ?? 'sandbox',
-      organizationId: config.organizationId,
-      sessionType: config.sessionType ?? 'enrollment',
-      identityId: config.identityId,
-      challengePolicy: config.challengePolicy ?? 'standard',
-      enableAudio: config.enableAudio ?? false,
-      timeout: config.timeout ?? 60000,
-      metadata: config.metadata
+      environment: config.environment ?? 'auto',
+      apiEndpoint: config.apiEndpoint,
+      branding: config.branding,
+      antispoofOnDeviceEnabled: config.antispoofOnDeviceEnabled ?? false,
+      liveSenseV4Enabled: config.liveSenseV4Enabled ?? false
     });
   }
 
   /**
-   * Start a verification session. Presents a full-screen native camera UI.
-   *
-   * The returned promise resolves when the session completes and the modal
-   * dismisses, or rejects if an error occurs.
-   *
-   * @param options - Optional overrides for session type and identity ID.
-   * @returns The verification result (for UI feedback only).
-   * @throws {UseSenseError} On failure or cancellation.
+   * Start a verification session. Presents a full-screen native
+   * camera activity. The returned promise resolves when the session
+   * completes or rejects with a `UseSenseError` (including the
+   * `USER_CANCELLED` / `session_cancelled` cases when the user
+   * dismisses the camera screen).
    */
-  static async startSession(options) {
-    return UseSenseModule.startSession(options ?? {});
+  static async startVerification(request) {
+    return UseSenseModule.startVerification({
+      sessionType: request.sessionType,
+      externalUserId: request.externalUserId,
+      identityId: request.identityId,
+      metadata: request.metadata
+    });
   }
 
   /**
-   * Cancel an in-progress verification session.
+   * Subscribe to real-time lifecycle events emitted by the native
+   * SDK during a verification session. Call this **before**
+   * `startVerification` so the subscription captures the earliest
+   * events (`SESSION_CREATED`, `PERMISSIONS_REQUESTED`).
    *
-   * The camera UI is dismissed and the `startSession` promise rejects
-   * with a `session_cancelled` error.
+   * Returns a subscription handle; call `.remove()` to stop
+   * receiving events.
    */
-  static async cancelSession() {
-    return UseSenseModule.cancelSession();
+  static addListener(callback) {
+    const subscription = eventEmitter.addListener('UseSenseEvent', raw => {
+      callback(raw);
+    });
+    return {
+      remove: () => subscription.remove()
+    };
   }
 
   /**
-   * Get the status of a verification session by ID.
-   *
-   * @param sessionId - The session ID to query.
-   * @returns The current status and optional result.
+   * Clear all event listeners and release native resources. Does not
+   * need to be called explicitly during normal usage; the plugin
+   * cleans up on process teardown. Useful when you want to re-
+   * initialize against a different API key or during test teardown.
    */
-  static async getSessionStatus(sessionId) {
-    return UseSenseModule.getSessionStatus(sessionId);
+  static async reset() {
+    return UseSenseModule.reset();
   }
 
   /**
-   * Subscribe to real-time events during the verification lifecycle.
-   *
-   * Call this before `startSession()` to receive all events.
-   *
-   * @param callback - Function invoked for each event.
-   * @returns A subscription handle with a `remove()` method.
-   *
-   * @example
-   * ```ts
-   * const listener = UseSense.addListener((event) => {
-   *   console.log(event.type);
-   * });
-   * // Later:
-   * listener.remove();
-   * ```
+   * Whether the native plugin has an active `UseSense` client. Set
+   * to `true` after a successful `initialize` and `false` after
+   * `reset`. Useful for feature-flagging UI that should only show
+   * when the SDK is ready.
    */
-  static addListener(callback) {
-    UseSenseModule.subscribeToEvents();
-    const subscription = eventEmitter.addListener('UseSenseEvent', callback);
-    return {
-      remove: () => {
-        subscription.remove();
-        UseSenseModule.unsubscribeFromEvents();
-      }
-    };
+  static async isInitialized() {
+    return UseSenseModule.isInitialized();
   }
 
+  // ─── LiveSense v4 ─────────────────────────────────────────────────────
+  // Phase 1 ticket R-1.
+  //
+  // v4 runs the perspective-distortion zoom-motion capture. Passthrough
+  // to the native SDK's startV4Session (iOS) / startV4Verification
+  // (Android). The returned promise resolves with the opaque verdict;
+  // sub-scores and pillar verdicts are never exposed.
+
   /**
-   * Get the native SDK version string.
+   * Start a LiveSense v4 session.
    *
-   * @returns Version string in semver format (e.g. `"1.0.0"`).
+   * The session must already have been created on your backend and the
+   * session_token + nonce forwarded to the client. The native SDK drives
+   * the camera, signs the frame hash chain with the platform-attested
+   * key, uploads, and returns the opaque verdict.
    */
-  static getSdkVersion() {
-    return UseSenseModule.getSdkVersion();
+  static async startV4Verification(request) {
+    return UseSenseModule.startV4Verification({
+      sessionId: request.sessionId,
+      sessionToken: request.sessionToken,
+      nonce: request.nonce,
+      apiBaseUrl: request.apiBaseUrl,
+      environment: request.environment ?? 'production',
+      displayName: request.displayName,
+      brandPrimaryColor: request.brandPrimaryColor
+    });
   }
 }
+
+// ─── LiveSense v4 types (R-1) ─────────────────────────────────────────────
+
+/**
+ * Opaque verdict from POST /v1/sessions/:id/result. Matches the server
+ * contract exactly; no sub-scores leak through.
+ */
 exports.UseSense = UseSense;
-var _default = exports.default = UseSense;
+var _default = exports.default = UseSense; // Slice 5d: Flows. A parallel surface to Sessions — host apps choose one
+// per call. See guides/flows/sessions-vs-flows in the API docs.
 //# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_reactNative","require","UseSenseModule","NativeModules","Error","eventEmitter","NativeEventEmitter","UseSense","initialize","config","apiKey","code","message","environment","organizationId","sessionType","identityId","challengePolicy","enableAudio","timeout","metadata","startSession","options","cancelSession","getSessionStatus","sessionId","addListener","callback","subscribeToEvents","subscription","remove","unsubscribeFromEvents","getSdkVersion","exports","_default","default"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;AAAA,IAAAA,YAAA,GAAAC,OAAA;AAEA,MAAM;EAAEC;AAAe,CAAC,GAAGC,0BAAa;AAExC,IAAI,CAACD,cAAc,EAAE;EACnB,MAAM,IAAIE,KAAK,CACb,mGAAmG,GACjG,oCAAoC,GACpC,wDACJ,CAAC;AACH;;AAEA;;AAEA;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAsBA;AACA;AACA;AACA;AACA;AACA;;AAwBA;AACA;AACA;;AAUA;AACA;AACA;;AASA;;AAQA;;AAQA;;AAMA;;AAEA,MAAMC,YAAY,GAAG,IAAIC,+BAAkB,CAACJ,cAAc,CAAC;;AAE3D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMK,QAAQ,CAAC;EACpB;AACF;AACA;AACA;AACA;AACA;EACE,aAAaC,UAAUA,CAACC,MAAsB,EAAiB;IAC7D,IAAI,CAACA,MAAM,CAACC,MAAM,EAAE;MAClB,MAAM;QAAEC,IAAI,EAAE,gBAAgB;QAAEC,OAAO,EAAE;MAAqB,CAAC;IACjE;IACA,OAAOV,cAAc,CAACM,UAAU,CAAC;MAC/BE,MAAM,EAAED,MAAM,CAACC,MAAM;MACrBG,WAAW,EAAEJ,MAAM,CAACI,WAAW,IAAI,SAAS;MAC5CC,cAAc,EAAEL,MAAM,CAACK,cAAc;MACrCC,WAAW,EAAEN,MAAM,CAACM,WAAW,IAAI,YAAY;MAC/CC,UAAU,EAAEP,MAAM,CAACO,UAAU;MAC7BC,eAAe,EAAER,MAAM,CAACQ,eAAe,IAAI,UAAU;MACrDC,WAAW,EAAET,MAAM,CAACS,WAAW,IAAI,KAAK;MACxCC,OAAO,EAAEV,MAAM,CAACU,OAAO,IAAI,KAAK;MAChCC,QAAQ,EAAEX,MAAM,CAACW;IACnB,CAAC,CAAC;EACJ;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACE,aAAaC,YAAYA,CAACC,OAA6B,EAA2B;IAChF,OAAOpB,cAAc,CAACmB,YAAY,CAACC,OAAO,IAAI,CAAC,CAAC,CAAC;EACnD;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,aAAaC,aAAaA,CAAA,EAAkB;IAC1C,OAAOrB,cAAc,CAACqB,aAAa,CAAC,CAAC;EACvC;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,aAAaC,gBAAgBA,CAACC,SAAiB,EAA0B;IACvE,OAAOvB,cAAc,CAACsB,gBAAgB,CAACC,SAAS,CAAC;EACnD;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACE,OAAOC,WAAWA,CAACC,QAAwC,EAAwB;IACjFzB,cAAc,CAAC0B,iBAAiB,CAAC,CAAC;IAClC,MAAMC,YAAY,GAAGxB,YAAY,CAACqB,WAAW,CAAC,eAAe,EAAEC,QAAQ,CAAC;IACxE,OAAO;MACLG,MAAM,EAAEA,CAAA,KAAM;QACZD,YAAY,CAACC,MAAM,CAAC,CAAC;QACrB5B,cAAc,CAAC6B,qBAAqB,CAAC,CAAC;MACxC;IACF,CAAC;EACH;;EAEA;AACF;AACA;AACA;AACA;EACE,OAAOC,aAAaA,CAAA,EAAW;IAC7B,OAAO9B,cAAc,CAAC8B,aAAa,CAAC,CAAC;EACvC;AACF;AAACC,OAAA,CAAA1B,QAAA,GAAAA,QAAA;AAAA,IAAA2B,QAAA,GAAAD,OAAA,CAAAE,OAAA,GAEc5B,QAAQ","ignoreList":[]}
+{"version":3,"names":["_reactNative","require","_flows","LINKING_ERROR","Platform","select","ios","android","default","UseSenseModule","NativeModules","Error","eventEmitter","NativeEventEmitter","UseSense","initialize","config","apiKey","err","code","message","isRetryable","environment","apiEndpoint","branding","antispoofOnDeviceEnabled","liveSenseV4Enabled","startVerification","request","sessionType","externalUserId","identityId","metadata","addListener","callback","subscription","raw","remove","reset","isInitialized","startV4Verification","sessionId","sessionToken","nonce","apiBaseUrl","displayName","brandPrimaryColor","exports","_default"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/flows.js

@@ -0,0 +1,99 @@
+/**
+ * React Native wrapper for the UseSense Flows runner.
+ *
+ * Coexists with the existing Sessions API (`UseSense.startSession`, etc.);
+ * this is a parallel surface, not a replacement. See `guides/flows/sessions-vs-flows`
+ * in the API docs for when to use which.
+ *
+ * Usage:
+ *
+ *   import { UseSenseFlows, FlowError } from 'react-native-usesense';
+ *
+ *   try {
+ *     const result = await UseSenseFlows.runFlow({ flowRunId, sdkToken });
+ *     console.log(result.outcome); // 'APPROVE' | 'REJECT' | 'MANUAL_REVIEW' | null
+ *   } catch (e) {
+ *     if (e instanceof FlowError) {
+ *       // e.code: 'token_expired' | 'token_invalid' | ...
+ *     }
+ *   }
+ */
+
+import { NativeModules, Platform } from 'react-native';
+const LINKING_ERROR = `react-native-usesense (flows): the native module could not be found.\n\n` + Platform.select({
+  ios: `iOS: run \`cd ios && pod install\` and rebuild the app.`,
+  android: `Android: rebuild the app after installing the package.`,
+  default: ''
+});
+
+// Lazy lookup so this module doesn't throw at import time on platforms that
+// haven't been re-linked yet. The Sessions module mirrors this pattern.
+function nativeModule() {
+  const m = NativeModules.UseSenseFlowsModule;
+  if (!m) throw new Error(LINKING_ERROR);
+  return m;
+}
+
+/**
+ * Server-driven flow run state. Host apps see only the terminal ones via
+ * `FlowRunResult`; intermediate states drive the runner internally.
+ */
+
+/** Terminal outcome of a flow run. */
+
+/**
+ * Uniform error taxonomy across every SDK. See `guides/flows/errors` in the
+ * API docs for per-code recovery patterns.
+ */
+
+const FLOW_ERROR_CODES = ['token_expired', 'token_invalid', 'network_unavailable', 'permission_denied', 'provider_unavailable', 'cancelled', 'unsupported_action', 'invalid_input', 'unknown'];
+function normaliseCode(code) {
+  return typeof code === 'string' && FLOW_ERROR_CODES.includes(code) ? code : 'unknown';
+}
+
+/** Result returned to the host app's `runFlow` promise on terminal state. */
+
+/**
+ * Typed error thrown by `runFlow` when the native runner reports a failure.
+ * Mirrors the web / iOS / Android / Flutter SDKs so host apps catch one
+ * taxonomy regardless of platform.
+ */
+export class FlowError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'FlowError';
+    this.code = code;
+  }
+}
+
+/** Options for `UseSenseFlows.runFlow`. */
+
+/**
+ * Public entry point for the Flows runner. Sessions APIs are untouched;
+ * this is a parallel namespace.
+ */
+export const UseSenseFlows = {
+  /**
+   * Run an operator-authored Flow inside the host app. Resolves with a
+   * [FlowRunResult] when the run reaches a terminal state (completed,
+   * cancelled, errored, abandoned). Rejects with a [FlowError] on transport
+   * / token / unsupported-action faults.
+   */
+  async runFlow(options) {
+    try {
+      const native = await nativeModule().runFlow(options.flowRunId, options.sdkToken, options.apiBaseUrl ?? null);
+      return {
+        flowRunId: native.flowRunId,
+        state: native.state,
+        outcome: native.outcome
+      };
+    } catch (e) {
+      // RN bridge errors are surfaced as `Error` with `.code` and `.message`
+      // properties when the native side calls `reject(code, message, null)`.
+      const code = normaliseCode(e.code);
+      const message = e.message ?? 'Flow failed';
+      throw new FlowError(code, message);
+    }
+  }
+};
+//# sourceMappingURL=flows.js.map

package/lib/module/flows.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["NativeModules","Platform","LINKING_ERROR","select","ios","android","default","nativeModule","m","UseSenseFlowsModule","Error","FLOW_ERROR_CODES","normaliseCode","code","includes","FlowError","constructor","message","name","UseSenseFlows","runFlow","options","native","flowRunId","sdkToken","apiBaseUrl","state","outcome","e"],"sourceRoot":"../../src","sources":["flows.ts"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,aAAa,EAAEC,QAAQ,QAAQ,cAAc;AAEtD,MAAMC,aAAa,GACjB,0EAA0E,GAC1ED,QAAQ,CAACE,MAAM,CAAC;EACdC,GAAG,EAAE,yDAAyD;EAC9DC,OAAO,EAAE,wDAAwD;EACjEC,OAAO,EAAE;AACX,CAAC,CAAC;;AAEJ;AACA;AACA,SAASC,YAAYA,CAAA,EAAG;EACtB,MAAMC,CAAC,GAAGR,aAAa,CAACS,mBAAmB;EAC3C,IAAI,CAACD,CAAC,EAAE,MAAM,IAAIE,KAAK,CAACR,aAAa,CAAC;EACtC,OAAOM,CAAC;AACV;;AAEA;AACA;AACA;AACA;;AAWA;;AAGA;AACA;AACA;AACA;;AAeA,MAAMG,gBAA0C,GAAG,CACjD,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,SAAS,CACD;AAEV,SAASC,aAAaA,CAACC,IAAa,EAAiB;EACnD,OAAO,OAAOA,IAAI,KAAK,QAAQ,IAAKF,gBAAgB,CAAuBG,QAAQ,CAACD,IAAI,CAAC,GACpFA,IAAI,GACL,SAAS;AACf;;AAEA;;AAaA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,SAAS,SAASL,KAAK,CAAC;EAEnCM,WAAWA,CAACH,IAAmB,EAAEI,OAAe,EAAE;IAChD,KAAK,CAACA,OAAO,CAAC;IACd,IAAI,CAACC,IAAI,GAAG,WAAW;IACvB,IAAI,CAACL,IAAI,GAAGA,IAAI;EAClB;AACF;;AAEA;;AAQA;AACA;AACA;AACA;AACA,OAAO,MAAMM,aAAa,GAAG;EAC3B;AACF;AACA;AACA;AACA;AACA;EACE,MAAMC,OAAOA,CAACC,OAAuB,EAA0B;IAC7D,IAAI;MACF,MAAMC,MAAM,GAAG,MAAMf,YAAY,CAAC,CAAC,CAACa,OAAO,CACzCC,OAAO,CAACE,SAAS,EACjBF,OAAO,CAACG,QAAQ,EAChBH,OAAO,CAACI,UAAU,IAAI,IACxB,CAAC;MACD,OAAO;QACLF,SAAS,EAAED,MAAM,CAACC,SAAS;QAC3BG,KAAK,EAAEJ,MAAM,CAACI,KAAK;QACnBC,OAAO,EAAEL,MAAM,CAACK;MAClB,CAAC;IACH,CAAC,CAAC,OAAOC,CAAC,EAAE;MACV;MACA;MACA,MAAMf,IAAI,GAAGD,aAAa,CAAEgB,CAAC,CAAuBf,IAAI,CAAC;MACzD,MAAMI,OAAO,GAAIW,CAAC,CAA0BX,OAAO,IAAI,aAAa;MACpE,MAAM,IAAIF,SAAS,CAACF,IAAI,EAAEI,OAAO,CAAC;IACpC;EACF;AACF,CAAC","ignoreList":[]}