@chipmobilesdk/rn-payment 0.5.0 → 0.7.0

package/lib/module/engine/purchase.js

@@ -0,0 +1,390 @@
+"use strict";
+
+/**
+ * The purchase flow.
+ *
+ * Ordering here is deliberate and load-bearing:
+ *
+ * 1. Refuse early and cheaply — disabled, not ready, already busy, environment
+ *    blocked, unknown product — so nothing reaches the store that should not.
+ * 2. Launch, and map every store outcome onto a typed result (FR-005).
+ * 3. Pending stops here: it is persisted and signalled, but **never granted**
+ *    (FR-037).
+ * 4. Validate with the app's backend, if one is configured, and only for a
+ *    **newly completed** purchase (FR-069a).
+ * 5. Grant the entitlement, then finalize. In that order — the user gets what
+ *    they paid for before the bookkeeping completes, so a finalize failure never
+ *    withholds a paid entitlement. Finalization is still guaranteed, by the
+ *    persisted queue.
+ */
+
+import { withTimeout } from "../core/mutex.js";
+import { PURCHASE_FLOW_CEILING_MS } from "../core/timers.js";
+import { PaymentError } from "../diagnostics/errors.js";
+import { storeIdForProductKey } from "../entitlements/mapping.js";
+import { toPersistedRecord } from "./sync.js";
+/** The error code each failed purchase kind is reported under (PAY-19). */
+import { createReceiptValidation } from "./receiptValidation.js";
+import { FAILURE_CODES, mapFailure } from "./purchaseFailure.js";
+export function createPurchaseFlow(deps) {
+  const {
+    resolved
+  } = deps;
+  // The backend check and what to do when it cannot answer (receiptValidation).
+  const {
+    askHook,
+    validate
+  } = createReceiptValidation({
+    config: deps.config,
+    platform: deps.platform,
+    resolved,
+    emit: deps.emit
+  });
+  const toRef = record => ({
+    transactionId: record.transactionId,
+    productKey: record.productKey
+  });
+
+  /** Writes or replaces the record for one transaction. */
+  const upsert = record => {
+    const snapshot = deps.snapshot();
+    const others = snapshot.purchases.filter(p => p.transactionId !== record.transactionId);
+    deps.commit({
+      ...snapshot,
+      purchases: [...others, record]
+    });
+  };
+  const recordFor = (purchase, productKey) => toPersistedRecord(resolved, purchase, productKey, deps.snapshot().purchases.find(p => p.transactionId === purchase.transactionId));
+
+  /**
+   * Calls the app's hook under `timeouts.validateMs`.
+   *
+   * Unbounded, a hook that never answers held the purchase lock and, through
+   * revalidation, the sync flight for the rest of the session. A timeout rejects,
+   * so callers treat it exactly like a hook that throws: unavailable (FR-072b).
+   */
+  /**
+   * Settlements in progress, by transaction.
+   *
+   * The Play binding delivers a launched purchase twice: to the launch and, at
+   * the same moment, to the session-long update listener. Both paths reach
+   * `settle`, and without this the hook ran twice and the purchase was settled
+   * twice. The second caller joins the first and gets the same result.
+   */
+  const inFlightSettle = new Map();
+  const settleOnce = (purchase, productKey, correlationId) => {
+    const running = inFlightSettle.get(purchase.transactionId);
+    if (running) {
+      return running;
+    }
+    const flight = settle(purchase, productKey, correlationId).finally(() => {
+      inFlightSettle.delete(purchase.transactionId);
+    });
+    inFlightSettle.set(purchase.transactionId, flight);
+    return flight;
+  };
+
+  /** Persists a completed purchase, grants it, then finalizes. */
+  const settle = async (purchase, productKey, correlationId) => {
+    const decision = await validate(purchase, productKey, correlationId);
+    if (decision.outcome === 'rejected') {
+      upsert({
+        ...recordFor(purchase, productKey),
+        validationState: 'rejected',
+        finalizeState: 'queued'
+      });
+      // Still finalized with the store: the money moved, so leaving it
+      // unacknowledged would have Google refund it while our backend has
+      // already decided the user is not entitled. Refunding is the app owner's
+      // call, not a side effect of a bookkeeping omission.
+      await deps.finalizer.enqueue(purchase.transactionId);
+      return {
+        kind: 'validation_rejected',
+        productKey,
+        reason: decision.reason
+      };
+    }
+    upsert({
+      ...recordFor(purchase, productKey),
+      validationState: decision.outcome === 'granted_pending_revalidation' ? 'queued_for_revalidation' : 'approved',
+      finalizeState: 'queued'
+    });
+
+    // Grant is already live at this point: `commit` recomputed entitlements.
+    // Finalize second, so a store hiccup cannot withhold what was paid for.
+    await deps.finalizer.enqueue(purchase.transactionId);
+    const record = deps.snapshot().purchases.find(p => p.transactionId === purchase.transactionId);
+    return {
+      kind: 'success',
+      productKey,
+      transaction: record ? toRef(record) : {
+        transactionId: purchase.transactionId,
+        productKey
+      }
+    };
+  };
+  const handlePending = (purchase, productKey) => {
+    // The same pending transaction arrives from the launch and from the update
+    // listener (see `inFlightSettle`). The signal is about a purchase becoming
+    // pending, so it fires once per transaction, not once per delivery.
+    const alreadyPending = deps.snapshot().purchases.some(p => p.transactionId === purchase.transactionId && p.state === 'pending');
+    upsert(recordFor(purchase, productKey));
+    if (!alreadyPending) {
+      deps.emit({
+        type: 'purchase_pending',
+        productKey
+      });
+    }
+    return {
+      kind: 'pending',
+      productKey,
+      transaction: {
+        transactionId: purchase.transactionId,
+        productKey
+      }
+    };
+  };
+
+  /**
+   * The store returned a purchase in a state it could not name — neither paid
+   * nor pending. Nothing is granted, persisted or acknowledged on it.
+   *
+   * Retrying is the repair path: if the money did move, the store answers
+   * `already_owned`, which re-syncs and grants (FR-033).
+   */
+  const handleUnspecified = (productKey, correlationId) => {
+    deps.emit({
+      type: 'purchase_failed',
+      productKey,
+      code: 'PAYMENT_STORE_ERROR',
+      retryable: true,
+      correlationId
+    });
+    return {
+      kind: 'store_error',
+      productKey,
+      code: 'PAYMENT_STORE_ERROR'
+    };
+  };
+
+  /** What the store is asked for: the product and, for a plan change, what it replaces. */
+  const launchRequest = (productKey, storeProductId, options) => {
+    const replaceKey = options?.replaceProductKey;
+    return {
+      storeProductId,
+      productType: resolved.entries.get(productKey)?.productType ?? 'one_time_permanent',
+      offerKey: options?.offerKey,
+      obfuscatedAccountId: options?.obfuscatedAccountId,
+      // Present only for a plan change. The store needs the token of the
+      // subscription being replaced so it migrates the existing purchase instead
+      // of creating a second one (FR-065), and its product id to apply the
+      // replacement mode.
+      replacePurchaseToken: replaceKey ? deps.snapshot().purchases.find(p => p.productKey === replaceKey && p.state === 'purchased')?.token : undefined,
+      replaceStoreProductId: replaceKey ? storeIdForProductKey(resolved, replaceKey) : undefined,
+      prorationMode: options?.prorationMode
+    };
+  };
+
+  /**
+   * The launch timeout covers opening the store surface only; time the user
+   * spends inside it is the store's, not ours (FR-035). A provider that reports
+   * nothing until the flow ends gives no "opened" moment to time, so it gets only
+   * `PURCHASE_FLOW_CEILING_MS`: far beyond any real purchase, there so a binding
+   * that never answers cannot hold the purchase lock for the whole session.
+   */
+  const launch = request => {
+    const launched = deps.provider.launchPurchase(request);
+    const includesStoreTime = deps.provider.capabilities().purchaseOutcomeIncludesStoreTime;
+    return withTimeout(launched, includesStoreTime ? PURCHASE_FLOW_CEILING_MS : resolved.timeouts.purchaseLaunchMs, () => new PaymentError({
+      code: 'PAYMENT_TIMEOUT',
+      message: 'Opening the purchase surface timed out',
+      operation: 'purchase',
+      retryable: true
+    }));
+  };
+  return {
+    async purchase(productKey, options) {
+      if (!resolved.enabled) {
+        return {
+          kind: 'disabled'
+        };
+      }
+      const status = deps.statusKind();
+      if (status !== 'ready') {
+        return {
+          kind: 'not_ready',
+          status
+        };
+      }
+      const storeProductId = storeIdForProductKey(resolved, productKey);
+      if (!storeProductId) {
+        return {
+          kind: 'unknown_product',
+          productKey
+        };
+      }
+
+      // The block that makes a developer mistake unable to move real money.
+      // Gated on the provider actually being one that would: the fake store
+      // must still be able to complete a purchase in a test (FR-014).
+      if (deps.provider.capabilities().createsRealTransactions && !deps.mayCreateRealTransaction()) {
+        deps.recordBlockedOperation(productKey);
+        return {
+          kind: 'environment_blocked',
+          productKey,
+          environment: deps.config.environment
+        };
+      }
+      const correlationId = deps.nextCorrelationId();
+
+      // Exclusive, not single-flight: a second purchase is refused rather than
+      // joined or queued, so no second store surface opens (FR-031).
+      const attempt = await deps.runExclusive(async () => {
+        deps.emit({
+          type: 'purchase_started',
+          productKey,
+          correlationId
+        });
+        let outcome;
+        try {
+          outcome = await launch(launchRequest(productKey, storeProductId, options));
+        } catch {
+          deps.emit({
+            type: 'purchase_failed',
+            productKey,
+            code: 'PAYMENT_TIMEOUT',
+            retryable: true,
+            correlationId
+          });
+          return {
+            kind: 'timeout',
+            productKey
+          };
+        }
+        if (!outcome.ok) {
+          const mapped = mapFailure(outcome.reason, productKey, deps.statusKind());
+          if (mapped.kind === 'user_cancelled') {
+            // A normal outcome. Reported on its own channel so it is never
+            // counted as a technical failure (FR-032).
+            deps.emit({
+              type: 'purchase_cancelled',
+              productKey,
+              correlationId
+            });
+            return mapped;
+          }
+          if (mapped.kind === 'already_owned') {
+            // How a reinstall or a new device repairs itself (FR-033).
+            deps.requestSync('already_owned');
+            return mapped;
+          }
+          deps.emit({
+            type: 'purchase_failed',
+            productKey,
+            code: FAILURE_CODES[mapped.kind] ?? 'PAYMENT_STORE_ERROR',
+            retryable: mapped.kind === 'network_error',
+            correlationId
+          });
+          return mapped;
+        }
+        if (outcome.purchase.state === 'pending') {
+          return handlePending(outcome.purchase, productKey);
+        }
+        if (outcome.purchase.state === 'unspecified') {
+          return handleUnspecified(productKey, correlationId);
+        }
+        deps.emit({
+          type: 'purchase_succeeded',
+          productKey,
+          correlationId
+        });
+        return settleOnce(outcome.purchase, productKey, correlationId);
+      });
+      if (!attempt.acquired) {
+        return {
+          kind: 'purchase_in_progress'
+        };
+      }
+      return attempt.value;
+    },
+    /**
+     * A store-pushed update.
+     *
+     * This is how a pending purchase that settled between sessions is granted
+     * without the user buying again (FR-039). It runs outside the exclusive lock
+     * because it is not a user-initiated purchase and must not be refused just
+     * because one is open.
+     */
+    async ingest(purchase) {
+      const productKey = resolved.byStoreId.get(purchase.storeProductId);
+      if (!productKey) {
+        return;
+      }
+      if (purchase.state === 'pending') {
+        handlePending(purchase, productKey);
+        return;
+      }
+      if (purchase.state === 'unspecified') {
+        // No basis to grant or to end anything. The next sync reports what
+        // the store actually holds.
+        return;
+      }
+      const existing = deps.snapshot().purchases.find(p => p.transactionId === purchase.transactionId);
+
+      // Already settled and validated: nothing to redo, and re-running the hook
+      // here would break FR-069a's "new purchases only" rule.
+      if (existing && existing.state === 'purchased' && existing.validationState !== 'not_required') {
+        await deps.finalizer.enqueue(purchase.transactionId);
+        return;
+      }
+      await settleOnce(purchase, productKey, deps.nextCorrelationId());
+    },
+    async revalidate() {
+      const hook = deps.config.validateTransaction;
+      if (!hook) {
+        return;
+      }
+      const queued = deps.snapshot().purchases.filter(p => p.validationState === 'queued_for_revalidation');
+      for (const record of queued) {
+        const entry = resolved.entries.get(record.productKey);
+        let approved;
+        try {
+          const decision = await askHook(hook, {
+            productKey: record.productKey,
+            productType: entry?.productType ?? 'one_time_permanent',
+            // Re-validation deliberately carries no payload: the original
+            // verification material is not persisted (FR-056), so the backend
+            // re-checks by transaction against its own record of the purchase —
+            // which is why the transaction id has to travel with it.
+            verificationPayload: '',
+            correlationId: deps.nextCorrelationId(),
+            transactionId: record.transactionId,
+            platform: deps.platform
+          });
+          approved = decision.approved;
+        } catch {
+          // Still unreachable. Leave it queued and try again next sync rather
+          // than revoking from a paying user because our backend is down.
+          continue;
+        }
+        const snapshot = deps.snapshot();
+        deps.commit({
+          ...snapshot,
+          purchases: snapshot.purchases.map(p => p.transactionId === record.transactionId ? {
+            ...p,
+            validationState: approved ? 'approved' : 'rejected',
+            // A rejection on recovery revokes, which is the bound on the
+            // exposure `grant_and_queue` accepts (FR-072a).
+            state: approved ? p.state : 'revoked'
+          } : p)
+        });
+        deps.emit({
+          type: 'validation_decided',
+          productKey: record.productKey,
+          decision: approved ? 'approved' : 'rejected'
+        });
+      }
+    }
+  };
+}
+//# sourceMappingURL=purchase.js.map

package/lib/module/engine/purchase.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["withTimeout","PURCHASE_FLOW_CEILING_MS","PaymentError","storeIdForProductKey","toPersistedRecord","createReceiptValidation","FAILURE_CODES","mapFailure","createPurchaseFlow","deps","resolved","askHook","validate","config","platform","emit","toRef","record","transactionId","productKey","upsert","snapshot","others","purchases","filter","p","commit","recordFor","purchase","find","inFlightSettle","Map","settleOnce","correlationId","running","get","flight","settle","finally","delete","set","decision","outcome","validationState","finalizeState","finalizer","enqueue","kind","reason","transaction","handlePending","alreadyPending","some","state","type","handleUnspecified","code","retryable","launchRequest","storeProductId","options","replaceKey","replaceProductKey","productType","entries","offerKey","obfuscatedAccountId","replacePurchaseToken","token","undefined","replaceStoreProductId","prorationMode","launch","request","launched","provider","launchPurchase","includesStoreTime","capabilities","purchaseOutcomeIncludesStoreTime","timeouts","purchaseLaunchMs","message","operation","enabled","status","statusKind","createsRealTransactions","mayCreateRealTransaction","recordBlockedOperation","environment","nextCorrelationId","attempt","runExclusive","ok","mapped","requestSync","acquired","value","ingest","byStoreId","existing","revalidate","hook","validateTransaction","queued","entry","approved","verificationPayload","map"],"sourceRoot":"../../../src","sources":["engine/purchase.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/engine/purchaseFailure.js

@@ -0,0 +1,72 @@
+"use strict";
+
+/**
+ * What a refused purchase means to the app (PAY-19).
+ *
+ * The store answers with a reason of its own; this turns it into the result the
+ * app sees, under the code it can branch on, so no store vocabulary leaks out.
+ * Split from the flow next door, which is about the sequence of calls.
+ */
+
+export const FAILURE_CODES = {
+  network_error: 'PAYMENT_NETWORK_ERROR',
+  unknown_product: 'PAYMENT_UNKNOWN_PRODUCT',
+  ineligible: 'PAYMENT_INELIGIBLE',
+  product_unavailable_in_region: 'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION'
+};
+
+/** Maps a provider failure onto the public vocabulary, so no store code leaks out. */
+export function mapFailure(reason, productKey, status) {
+  switch (reason) {
+    case 'user_cancelled':
+      return {
+        kind: 'user_cancelled',
+        productKey
+      };
+    case 'already_owned':
+      return {
+        kind: 'already_owned',
+        productKey
+      };
+    case 'ineligible':
+      return {
+        kind: 'ineligible',
+        productKey
+      };
+    case 'unknown_product':
+      return {
+        kind: 'unknown_product',
+        productKey
+      };
+    case 'product_unavailable_in_region':
+      return {
+        kind: 'product_unavailable_in_region',
+        productKey
+      };
+    case 'not_ready':
+      // The engine's real status, not a guess (PAY-19).
+      return {
+        kind: 'not_ready',
+        status
+      };
+    case 'network_error':
+      return {
+        kind: 'network_error',
+        productKey
+      };
+    case 'timeout':
+      return {
+        kind: 'timeout',
+        productKey
+      };
+    case 'store_error':
+      return {
+        kind: 'store_error',
+        productKey,
+        code: 'PAYMENT_STORE_ERROR'
+      };
+  }
+}
+
+/** Plan-change parameters, which only `subscriptions.ts` supplies. */
+//# sourceMappingURL=purchaseFailure.js.map

package/lib/module/engine/purchaseFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["FAILURE_CODES","network_error","unknown_product","ineligible","product_unavailable_in_region","mapFailure","reason","productKey","status","kind","code"],"sourceRoot":"../../../src","sources":["engine/purchaseFailure.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA,OAAO,MAAMA,aAAwE,GAAG;EACvFC,aAAa,EAAE,uBAAuB;EACtCC,eAAe,EAAE,yBAAyB;EAC1CC,UAAU,EAAE,oBAAoB;EAChCC,6BAA6B,EAAE;AAChC,CAAC;;AAED;AACA,OAAO,SAASC,UAAUA,CACzBC,MAA6B,EAC7BC,UAAsB,EACtBC,MAAyB,EACR;EACjB,QAAQF,MAAM;IACb,KAAK,gBAAgB;MACpB,OAAO;QAAEG,IAAI,EAAE,gBAAgB;QAAEF;MAAW,CAAC;IAC9C,KAAK,eAAe;MACnB,OAAO;QAAEE,IAAI,EAAE,eAAe;QAAEF;MAAW,CAAC;IAC7C,KAAK,YAAY;MAChB,OAAO;QAAEE,IAAI,EAAE,YAAY;QAAEF;MAAW,CAAC;IAC1C,KAAK,iBAAiB;MACrB,OAAO;QAAEE,IAAI,EAAE,iBAAiB;QAAEF;MAAW,CAAC;IAC/C,KAAK,+BAA+B;MACnC,OAAO;QAAEE,IAAI,EAAE,+BAA+B;QAAEF;MAAW,CAAC;IAC7D,KAAK,WAAW;MACf;MACA,OAAO;QAAEE,IAAI,EAAE,WAAW;QAAED;MAAO,CAAC;IACrC,KAAK,eAAe;MACnB,OAAO;QAAEC,IAAI,EAAE,eAAe;QAAEF;MAAW,CAAC;IAC7C,KAAK,SAAS;MACb,OAAO;QAAEE,IAAI,EAAE,SAAS;QAAEF;MAAW,CAAC;IACvC,KAAK,aAAa;MACjB,OAAO;QAAEE,IAAI,EAAE,aAAa;QAAEF,UAAU;QAAEG,IAAI,EAAE;MAAsB,CAAC;EACzE;AACD;;AAEA","ignoreList":[]}

package/lib/module/engine/receiptValidation.js

@@ -0,0 +1,87 @@
+"use strict";
+
+/**
+ * Asking the app's backend whether a purchase is real (FR-069a, FR-072b).
+ *
+ * The hook is optional and bounded by a timeout, and its answer decides whether
+ * an entitlement is granted — so what happens when it throws, times out, or is
+ * absent is the whole point of this module. Split from the flow next door,
+ * which is about the sequence of store calls.
+ *
+ * A hook that could not answer is never an implicit approval: the configured
+ * `onValidationUnavailable` decides, and the default refuses.
+ */
+
+import { withTimeout } from "../core/mutex.js";
+import { PaymentError } from "../diagnostics/errors.js";
+
+/** What the backend decided about one purchase. */
+
+export function createReceiptValidation(deps) {
+  const {
+    resolved
+  } = deps;
+  const askHook = (hook, candidate) => withTimeout(hook(candidate), resolved.timeouts.validateMs, () => new PaymentError({
+    code: 'PAYMENT_VALIDATION_UNAVAILABLE',
+    message: 'The validation hook did not answer in time',
+    operation: 'validate',
+    retryable: true
+  }));
+
+  /**
+   * Runs the app's backend check, if configured.
+   *
+   * Called for newly completed purchases only (FR-069a) — sync and restore trust
+   * a decision already made, which is what keeps restore working while the
+   * backend is unreachable.
+   */
+  const validate = async (purchase, productKey, correlationId) => {
+    const hook = deps.config.validateTransaction;
+    if (!hook) {
+      return {
+        outcome: 'approved'
+      };
+    }
+    const entry = resolved.entries.get(productKey);
+    try {
+      const decision = await askHook(hook, {
+        productKey,
+        productType: entry?.productType ?? 'one_time_permanent',
+        verificationPayload: purchase.verificationPayload ?? '',
+        correlationId,
+        transactionId: purchase.transactionId,
+        platform: deps.platform
+      });
+      deps.emit({
+        type: 'validation_decided',
+        productKey,
+        decision: decision.approved ? 'approved' : 'rejected'
+      });
+      return decision.approved ? {
+        outcome: 'approved'
+      } : {
+        outcome: 'rejected',
+        reason: decision.reason
+      };
+    } catch {
+      // A hook that throws is unavailable, never an implicit approval (FR-072b).
+      const fallback = resolved.onValidationUnavailable;
+      deps.emit({
+        type: 'validation_unavailable',
+        productKey,
+        fallback
+      });
+      return fallback === 'grant_and_queue' ? {
+        outcome: 'granted_pending_revalidation'
+      } : {
+        outcome: 'rejected',
+        reason: 'validation_unavailable'
+      };
+    }
+  };
+  return {
+    askHook,
+    validate
+  };
+}
+//# sourceMappingURL=receiptValidation.js.map

package/lib/module/engine/receiptValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["withTimeout","PaymentError","createReceiptValidation","deps","resolved","askHook","hook","candidate","timeouts","validateMs","code","message","operation","retryable","validate","purchase","productKey","correlationId","config","validateTransaction","outcome","entry","entries","get","decision","productType","verificationPayload","transactionId","platform","emit","type","approved","reason","fallback","onValidationUnavailable"],"sourceRoot":"../../../src","sources":["engine/receiptValidation.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA,SAASA,WAAW,QAAQ,kBAAe;AAC3C,SAASC,YAAY,QAAQ,0BAAuB;;AASpD;;AAMA,OAAO,SAASC,uBAAuBA,CAACC,IAA2B,EAAE;EACpE,MAAM;IAAEC;EAAS,CAAC,GAAGD,IAAI;EAEzB,MAAME,OAAO,GAAGA,CACfC,IAAuD,EACvDC,SAA2E,KAE3EP,WAAW,CACVM,IAAI,CAACC,SAAS,CAAC,EACfH,QAAQ,CAACI,QAAQ,CAACC,UAAU,EAC5B,MACC,IAAIR,YAAY,CAAC;IAChBS,IAAI,EAAE,gCAAgC;IACtCC,OAAO,EAAE,4CAA4C;IACrDC,SAAS,EAAE,UAAU;IACrBC,SAAS,EAAE;EACZ,CAAC,CACH,CAAC;;EAEF;AACD;AACA;AACA;AACA;AACA;AACA;EACC,MAAMC,QAAQ,GAAG,MAAAA,CAChBC,QAA0B,EAC1BC,UAAsB,EACtBC,aAAqB,KAKjB;IACJ,MAAMX,IAAI,GAAGH,IAAI,CAACe,MAAM,CAACC,mBAAmB;IAC5C,IAAI,CAACb,IAAI,EAAE;MACV,OAAO;QAAEc,OAAO,EAAE;MAAW,CAAC;IAC/B;IAEA,MAAMC,KAAK,GAAGjB,QAAQ,CAACkB,OAAO,CAACC,GAAG,CAACP,UAAU,CAAC;IAC9C,IAAI;MACH,MAAMQ,QAAQ,GAAG,MAAMnB,OAAO,CAACC,IAAI,EAAE;QACpCU,UAAU;QACVS,WAAW,EAAEJ,KAAK,EAAEI,WAAW,IAAI,oBAAoB;QACvDC,mBAAmB,EAAEX,QAAQ,CAACW,mBAAmB,IAAI,EAAE;QACvDT,aAAa;QACbU,aAAa,EAAEZ,QAAQ,CAACY,aAAa;QACrCC,QAAQ,EAAEzB,IAAI,CAACyB;MAChB,CAAC,CAAC;MACFzB,IAAI,CAAC0B,IAAI,CAAC;QACTC,IAAI,EAAE,oBAAoB;QAC1Bd,UAAU;QACVQ,QAAQ,EAAEA,QAAQ,CAACO,QAAQ,GAAG,UAAU,GAAG;MAC5C,CAAC,CAAC;MACF,OAAOP,QAAQ,CAACO,QAAQ,GACrB;QAAEX,OAAO,EAAE;MAAW,CAAC,GACvB;QAAEA,OAAO,EAAE,UAAU;QAAEY,MAAM,EAAER,QAAQ,CAACQ;MAAO,CAAC;IACpD,CAAC,CAAC,MAAM;MACP;MACA,MAAMC,QAAQ,GAAG7B,QAAQ,CAAC8B,uBAAuB;MACjD/B,IAAI,CAAC0B,IAAI,CAAC;QAAEC,IAAI,EAAE,wBAAwB;QAAEd,UAAU;QAAEiB;MAAS,CAAC,CAAC;MACnE,OAAOA,QAAQ,KAAK,iBAAiB,GAClC;QAAEb,OAAO,EAAE;MAA+B,CAAC,GAC3C;QAAEA,OAAO,EAAE,UAAU;QAAEY,MAAM,EAAE;MAAyB,CAAC;IAC7D;EACD,CAAC;EAED,OAAO;IAAE3B,OAAO;IAAES;EAAS,CAAC;AAC7B","ignoreList":[]}