@localpay/verification-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LocalPay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# @localpay/verification-engine
+
+Bank receipt verification engine for Ethiopian and East African banks.
+
+Supports: **CBE**, **Telebirr**, **Bank of Abyssinia**, **E-Birr**
+
+- Works in any Node.js project
+- Proxy support via a simple interface (you provide the config, we route the traffic)
+- Amount matching built into verification
+- Supports receipt links, SMS text, transaction references, and OCR images
+- Extensible — add new bank parsers by implementing one interface
+
+---
+
+## Installation
+
+```bash
+npm install @localpay/verification-engine
+```
+
+---
+
+## Quick start
+
+```ts
+import { VerificationEngine } from "@localpay/verification-engine";
+
+const engine = new VerificationEngine();
+
+const result = await engine.verify({
+  bank: "CBE",
+  amount: 500,
+  verMethod: "LINK",
+  rawProof: "https://apps.cbe.com.et:100/?id=FT26093JCD3218872366",
+});
+
+if (result.status === "SUCCESS") {
+  console.log(result.receipt.receipt.transactionNumber); // FT26093JCD32
+  console.log(result.receipt.receipt.amount); // "500"
+  console.log(result.receipt.receipt.receiverAccount); // account number
+}
+```
+
+---
+
+## Supported banks
+
+| parserKey   | Bank                        | Methods                         |
+| ----------- | --------------------------- | ------------------------------- |
+| `CBE`       | Commercial Bank of Ethiopia | LINK, SMS, TRANSACTION_REF, OCR |
+| `TELEBIRR`  | Telebirr                    | LINK, SMS, TRANSACTION_REF, OCR |
+| `ABYSSINIA` | Bank of Abyssinia           | LINK, SMS, TRANSACTION_REF, OCR |
+| `EBIRR`     | E-Birr                      | LINK, SMS, TRANSACTION_REF, OCR |
+
+---
+
+## Verification methods
+
+| Method            | Description                                         |
+| ----------------- | --------------------------------------------------- |
+| `LINK`            | Pass the receipt URL directly                       |
+| `SMS`             | Pass the raw SMS body — the parser extracts the URL |
+| `TRANSACTION_REF` | Pass only the transaction/reference number          |
+| `OCR`             | Pass an image path or `Buffer`; OCR runs internally |
+| `SCREENSHOT`      | Alias of `OCR` for screenshot image verification    |
+
+```ts
+const byReference = await engine.verify({
+  bank: "TELEBIRR",
+  amount: 250,
+  verMethod: "TRANSACTION_REF",
+  rawProof: "CG7X9A2B",
+});
+
+const byScreenshot = await engine.verify({
+  bank: "TELEBIRR",
+  amount: 250,
+  verMethod: "OCR",
+  rawProof: "/tmp/receipt-screenshot.png",
+});
+```
+
+The engine compares `payload.amount` with the parsed receipt amount. Use
+`amountTolerance` when small rounding differences are expected.
+
+```ts
+await engine.verify({
+  bank: "CBE",
+  amount: 500,
+  amountTolerance: 0.05,
+  verMethod: "LINK",
+  rawProof: "https://apps.cbe.com.et:100/?id=...",
+});
+```
+
+---
+
+## Proxy support
+
+Some banks block foreign IPs (e.g. Telebirr). Implement the `ProxyResolver`
+interface to provide per-country proxy config from your data store. The built-in
+parsers route HTTP and browser-backed fetches through this fetch service.
+
+```ts
+import {
+  VerificationEngine,
+  ProxyResolver,
+  ProxyConfig,
+  ProxyType,
+} from "@localpay/verification-engine";
+
+class MyProxyResolver implements ProxyResolver {
+  async resolve(countryCode: string): Promise<ProxyConfig | null> {
+    // Read from your database, config file, environment variable, etc.
+    const row = await db.countryProxy.findUnique({ where: { countryCode } });
+    if (!row?.proxyEnabled) return null;
+    return {
+      enabled: true,
+      url: row.proxyUrl,
+      type: row.proxyType as ProxyType,
+    };
+  }
+}
+
+const engine = new VerificationEngine({
+  proxyResolver: new MyProxyResolver(),
+});
+```
+
+---
+
+## Adding a new bank
+
+1. Implement the `ParserAndExtractor` interface:
+
+```ts
+import {
+  ParserAndExtractor,
+  ParserFetchContext,
+  RawReceipt,
+} from "@localpay/verification-engine";
+
+export class MyBankParser implements ParserAndExtractor {
+  extract(text: string, accountNumber?: string): { link: string } {
+    // Extract the receipt URL from SMS/OCR text
+    const match = text.match(/my-bank\.com\/receipt\/([A-Z0-9]+)/i);
+    if (!match) return { link: "" };
+    return { link: `https://my-bank.com/receipt/${match[1]}` };
+  }
+
+  transactionRef(transactionRef: string): { link: string } {
+    return { link: `https://my-bank.com/receipt/${transactionRef}` };
+  }
+
+  async fetch(
+    link: string,
+    context?: ParserFetchContext,
+  ): Promise<{ page: any }> {
+    const response = context
+      ? await context.fetcher.fetch(link, context.countryCode)
+      : await fetch(link).then(async (res) => ({ data: await res.text() }));
+
+    return { page: response.data };
+  }
+
+  async receiptParser(
+    page: any,
+  ): Promise<{ bank: string; receipt: RawReceipt }> {
+    // Parse the page and return structured data
+    return {
+      bank: "MY_BANK",
+      receipt: {
+        transactionNumber: "...",
+        date: "...",
+        amount: "...",
+        receiverAccount: "...",
+        receiverName: "...",
+      },
+    };
+  }
+}
+```
+
+2. Pass it to the engine:
+
+```ts
+import { PARSER_REGISTRY } from "@localpay/verification-engine";
+import { MyBankParser } from "./my-bank.parser";
+
+const engine = new VerificationEngine({
+  parsers: {
+    ...PARSER_REGISTRY,
+    MY_BANK: new MyBankParser(),
+  },
+});
+```
+
+---
+
+## NestJS integration
+
+```ts
+import { Injectable } from "@nestjs/common";
+import {
+  VerificationEngine,
+  ProxyResolver,
+} from "@localpay/verification-engine";
+import { PrismaService } from "./prisma.service";
+
+@Injectable()
+export class VerificationService {
+  private readonly engine: VerificationEngine;
+
+  constructor(private readonly prisma: PrismaService) {
+    const proxyResolver: ProxyResolver = {
+      resolve: async (countryCode) => {
+        const row = await prisma.countryProxy.findUnique({
+          where: { countryCode },
+        });
+        if (!row?.proxyEnabled) return null;
+        return { enabled: true, url: row.proxyUrl, type: row.proxyType as any };
+      },
+    };
+
+    this.engine = new VerificationEngine({ proxyResolver });
+  }
+
+  verify(payload: Parameters<VerificationEngine["verify"]>[0]) {
+    return this.engine.verify(payload);
+  }
+}
+```
+
+---
+
+## Publishing
+
+```bash
+# Build and test
+npm test
+
+# Publish (private)
+npm publish --access restricted
+
+# Make public later
+npm publish --access public
+```
+
+`puppeteer` is an optional peer dependency used by parsers that need a
+browser-rendered receipt page. HTTP/PDF-only parsers do not load it. Install it
+in host apps that verify Telebirr or Bank of Abyssinia browser-rendered receipts.

package/dist/core/bank-fetch.service.d.ts

@@ -0,0 +1,51 @@
+import { ProxyResolver } from "../shared/proxy.types";
+export interface BankFetchOptions {
+    responseType?: "arraybuffer" | "json" | "text";
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    validateStatus?: (status: number) => boolean;
+}
+export interface BrowserFetchOptions {
+    waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+    waitForSelector?: string;
+    timeoutMs?: number;
+}
+/**
+ * FetchError is thrown when all retry attempts are exhausted.
+ * Catch this in your service layer to handle network failures gracefully.
+ */
+export declare class FetchError extends Error {
+    readonly url: string;
+    readonly countryCode: string;
+    readonly cause: unknown;
+    constructor(url: string, countryCode: string, cause: unknown);
+}
+/**
+ * BankFetchService — single HTTP gateway for all bank parsers.
+ *
+ * Parsers never call axios directly. They call this service, which
+ * handles proxy routing, retries, and timeouts transparently.
+ *
+ * Usage:
+ *   const fetcher = new BankFetchService(myProxyResolver);
+ *   const { data } = await fetcher.fetch(url, 'ET', { responseType: 'text' });
+ *
+ * @param proxyResolver  Implement ProxyResolver in your host app to provide
+ *                       proxy config from your database or config store.
+ *                       Pass null to disable proxy support entirely.
+ */
+export declare class BankFetchService {
+    private readonly proxyResolver;
+    private readonly MAX_RETRIES;
+    private readonly DEFAULT_TIMEOUT_MS;
+    constructor(proxyResolver?: ProxyResolver | null);
+    fetch(url: string, countryCode: string, options?: BankFetchOptions): Promise<{
+        data: any;
+        status: number;
+        headers: any;
+    }>;
+    fetchBrowserPage(url: string, countryCode: string, options?: BrowserFetchOptions): Promise<{
+        data: string;
+    }>;
+}
+//# sourceMappingURL=bank-fetch.service.d.ts.map

package/dist/core/bank-fetch.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bank-fetch.service.d.ts","sourceRoot":"","sources":["../../src/core/bank-fetch.service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAa,MAAM,uBAAuB,CAAC;AAEjE,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,cAAc,GAAG,cAAc,CAAC;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;aAEjB,GAAG,EAAE,MAAM;aACX,WAAW,EAAE,MAAM;aACnB,KAAK,EAAE,OAAO;gBAFd,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO;CAOjC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,aAAa;IAH1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAK;IACjC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;gBAEhB,aAAa,GAAE,aAAa,GAAG,IAAW;IAEjE,KAAK,CACT,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAE,CAAC;IA0CjD,gBAAgB,CACpB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAiC7B"}

package/dist/core/bank-fetch.service.js

@@ -0,0 +1,147 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BankFetchService = exports.FetchError = void 0;
+const axios_1 = __importDefault(require("axios"));
+const https_proxy_agent_1 = require("https-proxy-agent");
+const socks_proxy_agent_1 = require("socks-proxy-agent");
+const proxy_types_1 = require("../shared/proxy.types");
+/**
+ * FetchError is thrown when all retry attempts are exhausted.
+ * Catch this in your service layer to handle network failures gracefully.
+ */
+class FetchError extends Error {
+    constructor(url, countryCode, cause) {
+        const reason = cause instanceof Error ? cause.message : "Unknown network error";
+        super(`Fetch failed for ${countryCode} — ${url}: ${reason}`);
+        this.url = url;
+        this.countryCode = countryCode;
+        this.cause = cause;
+        this.name = "FetchError";
+    }
+}
+exports.FetchError = FetchError;
+/**
+ * BankFetchService — single HTTP gateway for all bank parsers.
+ *
+ * Parsers never call axios directly. They call this service, which
+ * handles proxy routing, retries, and timeouts transparently.
+ *
+ * Usage:
+ *   const fetcher = new BankFetchService(myProxyResolver);
+ *   const { data } = await fetcher.fetch(url, 'ET', { responseType: 'text' });
+ *
+ * @param proxyResolver  Implement ProxyResolver in your host app to provide
+ *                       proxy config from your database or config store.
+ *                       Pass null to disable proxy support entirely.
+ */
+class BankFetchService {
+    constructor(proxyResolver = null) {
+        this.proxyResolver = proxyResolver;
+        this.MAX_RETRIES = 2;
+        this.DEFAULT_TIMEOUT_MS = 10000;
+    }
+    async fetch(url, countryCode, options = {}) {
+        const proxy = (await this.proxyResolver?.resolve(countryCode)) ?? null;
+        const timeoutMs = options.timeoutMs ?? this.DEFAULT_TIMEOUT_MS;
+        let lastError;
+        for (let attempt = 1; attempt <= this.MAX_RETRIES; attempt++) {
+            try {
+                const config = {
+                    url,
+                    method: "GET",
+                    responseType: options.responseType ?? "text",
+                    headers: options.headers ?? {},
+                    timeout: timeoutMs,
+                    validateStatus: options.validateStatus,
+                };
+                if (proxy?.enabled && proxy.url) {
+                    config.httpsAgent =
+                        proxy.type === proxy_types_1.ProxyType.SOCKS5
+                            ? new socks_proxy_agent_1.SocksProxyAgent(proxy.url)
+                            : new https_proxy_agent_1.HttpsProxyAgent(proxy.url);
+                    config.proxy = false;
+                }
+                const response = await (0, axios_1.default)(config);
+                return {
+                    data: response.data,
+                    status: response.status,
+                    headers: response.headers,
+                };
+            }
+            catch (err) {
+                lastError = err;
+                if (attempt < this.MAX_RETRIES) {
+                    await new Promise((r) => setTimeout(r, 1000));
+                }
+            }
+        }
+        throw new FetchError(url, countryCode, lastError);
+    }
+    async fetchBrowserPage(url, countryCode, options = {}) {
+        const proxy = (await this.proxyResolver?.resolve(countryCode)) ?? null;
+        const timeoutMs = options.timeoutMs ?? 60000;
+        const args = ["--no-sandbox", "--disable-setuid-sandbox"];
+        if (proxy?.enabled && proxy.url) {
+            args.push(`--proxy-server=${proxy.url}`);
+        }
+        const puppeteer = await Promise.resolve().then(() => __importStar(require("puppeteer")));
+        const browser = await puppeteer.default.launch({
+            headless: true,
+            args,
+        });
+        try {
+            const page = await browser.newPage();
+            await page.goto(url, {
+                waitUntil: options.waitUntil ?? "domcontentloaded",
+                timeout: timeoutMs,
+            });
+            if (options.waitForSelector) {
+                await page
+                    .waitForSelector(options.waitForSelector, { timeout: timeoutMs })
+                    .catch(() => { });
+            }
+            return { data: await page.content() };
+        }
+        finally {
+            await browser.close();
+        }
+    }
+}
+exports.BankFetchService = BankFetchService;
+//# sourceMappingURL=bank-fetch.service.js.map

package/dist/core/bank-fetch.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bank-fetch.service.js","sourceRoot":"","sources":["../../src/core/bank-fetch.service.ts"],"names":[],"mappings":"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"}

package/dist/core/verification-engine.d.ts

@@ -0,0 +1,68 @@
+import { ParserRegistry } from "../shared/parser.interface";
+import { ProxyResolver } from "../shared/proxy.types";
+export type VerificationMethod = "LINK" | "SMS" | "TRANSACTION_REF" | "OCR" | "SCREENSHOT";
+export type RawProof = string | Buffer;
+export interface VerifyPayload {
+    /** parserKey — e.g. 'CBE', 'TELEBIRR', 'ABYSSINIA', 'EBIRR' */
+    bank: string;
+    amount: number;
+    verMethod: VerificationMethod;
+    rawProof: RawProof;
+    accountNumber?: string;
+    countryCode?: string;
+    amountTolerance?: number;
+}
+export type VerifyResult = {
+    status: "SUCCESS";
+    receipt: {
+        bank: string;
+        receipt: {
+            transactionNumber: string;
+            date: string;
+            amount: string;
+            receiverAccount: string;
+            receiverName: string;
+        };
+    };
+} | {
+    status: "FAIL";
+    reason: string;
+};
+/**
+ * VerificationEngine — the main entry point for the package.
+ *
+ * Plain TypeScript class. No NestJS, no Prisma, no framework.
+ *
+ * Usage:
+ *
+ *   // Minimal — no proxy support
+ *   const engine = new VerificationEngine();
+ *
+ *   // With proxy support — implement ProxyResolver in your app
+ *   const engine = new VerificationEngine({ proxyResolver: myResolver });
+ *
+ *   // With custom parsers (extend or override)
+ *   const engine = new VerificationEngine({ parsers: { ...PARSER_REGISTRY, MY_BANK: new MyParser() } });
+ *
+ *   const result = await engine.verify({
+ *     bank: 'CBE',
+ *     amount: 500,
+ *     verMethod: 'LINK',
+ *     rawProof: 'https://apps.cbe.com.et:100/?id=FT26093JCD3218872366',
+ *   });
+ */
+export declare class VerificationEngine {
+    private readonly parsers;
+    private readonly fetcher;
+    private readonly ocrReader;
+    constructor(options?: {
+        proxyResolver?: ProxyResolver | null;
+        ocrReader?: (input: RawProof) => Promise<string>;
+        /** Override or extend the default parser registry */
+        parsers?: ParserRegistry;
+    });
+    verify(payload: VerifyPayload): Promise<VerifyResult>;
+    /** List all registered parser keys */
+    getSupportedBanks(): string[];
+}
+//# sourceMappingURL=verification-engine.d.ts.map

package/dist/core/verification-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-engine.d.ts","sourceRoot":"","sources":["../../src/core/verification-engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGtD,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,KAAK,GACL,iBAAiB,GACjB,KAAK,GACL,YAAY,CAAC;AAEjB,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,YAAY,GACpB;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE;YACP,iBAAiB,EAAE,MAAM,CAAC;YAC1B,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,MAAM,CAAC;YACf,eAAe,EAAE,MAAM,CAAC;YACxB,YAAY,EAAE,MAAM,CAAC;SACtB,CAAC;KACH,CAAC;CACH,GACD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;gBAErD,OAAO,CAAC,EAAE;QACpB,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;QACrC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;QACjD,qDAAqD;QACrD,OAAO,CAAC,EAAE,cAAc,CAAC;KAC1B;IAMK,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAwG3D,sCAAsC;IACtC,iBAAiB,IAAI,MAAM,EAAE;CAG9B"}