@obhco/pay 0.0.0-stage → 0.1.0

package/dist/store.d.ts

@@ -0,0 +1,420 @@
+import type { CheckoutRedirect } from "./types.js";
+export type PaymentStatus = "pending" | "completed" | "failed" | "cancelled" | "expired";
+export type PaymentEnvironment = "live" | "test";
+export type InstallmentInfo = {
+    /** Gateway purchase type, e.g. `BNPL` or `CREDIT`. */
+    purchaseType: string;
+    count: number | null;
+};
+/**
+ * One payment attempt as the service stores it. A customer retrying the same
+ * order creates a new record (a new `reference` and `attempt`), never a
+ * mutation of a failed one.
+ */
+export type PaymentRecord = {
+    /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+    reference: string;
+    /** The service's own order id. */
+    orderId: string;
+    /** 1 for the first attempt on `orderId`, then 2, 3, … */
+    attempt: number;
+    gateway: string;
+    /** Digits-only number sent to the gateway; unique per gateway. */
+    gatewayOrderId: string;
+    /** Whole Rials as a digit string. */
+    amount: string;
+    currency: "IRR";
+    description: string;
+    status: PaymentStatus;
+    environment: PaymentEnvironment;
+    returnUrl: string | null;
+    customerMobile: string | null;
+    metadata: Record<string, unknown>;
+    providerSessionId: string | null;
+    providerReference: string | null;
+    traceNumber: string | null;
+    maskedCardNumber: string | null;
+    resultCode: number | null;
+    resultText: string | null;
+    installment: InstallmentInfo | null;
+    redirect: CheckoutRedirect | null;
+    /** Sanitised gateway callback body, kept for audit and retried verifies. */
+    callbackPayload: Record<string, unknown> | null;
+    createdAt: Date;
+    expiresAt: Date | null;
+    callbackReceivedAt: Date | null;
+    completedAt: Date | null;
+    failedAt: Date | null;
+    /** Last status OBH acknowledged. `null` until the first successful report. */
+    reportedStatus: PaymentStatus | null;
+    reportedAt: Date | null;
+};
+export type PaymentPatch = Partial<Omit<PaymentRecord, "reference">>;
+/**
+ * Persistence the host application provides. Everything the package needs is
+ * a handful of lookups and one compare-and-set, so it maps onto any SQL or
+ * document database. `MemoryPaymentStore` is the reference implementation.
+ */
+export interface PaymentStore {
+    /** Returns the next digits-only order number for `gateway`. */
+    nextGatewayOrderId(gateway: string): Promise<string>;
+    insert(record: PaymentRecord): Promise<PaymentRecord>;
+    findByReference(reference: string): Promise<PaymentRecord | null>;
+    /** Attempts for one order, oldest first. */
+    listByOrderId(orderId: string): Promise<PaymentRecord[]>;
+    findByGatewayOrderId(gateway: string, gatewayOrderId: string): Promise<PaymentRecord | null>;
+    findBySessionId(gateway: string, sessionId: string): Promise<PaymentRecord | null>;
+    /** Unconditional patch of fields that do not change `status`. */
+    update(reference: string, patch: PaymentPatch): Promise<PaymentRecord>;
+    /**
+     * Applies `patch` only while the stored status equals `from`. Returns the
+     * updated record, or `null` when another request already moved it. This is
+     * what keeps a double callback from completing a payment twice.
+     */
+    transition(reference: string, from: PaymentStatus, patch: PaymentPatch & {
+        status: PaymentStatus;
+    }): Promise<PaymentRecord | null>;
+    /** Pending payments created before `before`, oldest first. */
+    listPending(before: Date, limit: number): Promise<PaymentRecord[]>;
+    /** Records whose `status` differs from `reportedStatus`. */
+    listUnreported(limit: number): Promise<PaymentRecord[]>;
+}
+/** In-process store for tests and local development. Not for production. */
+export declare class MemoryPaymentStore implements PaymentStore {
+    private readonly records;
+    private counter;
+    nextGatewayOrderId(): Promise<string>;
+    insert(record: PaymentRecord): Promise<{
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+        /** The service's own order id. */
+        orderId: string;
+        /** 1 for the first attempt on `orderId`, then 2, 3, … */
+        attempt: number;
+        gateway: string;
+        /** Digits-only number sent to the gateway; unique per gateway. */
+        gatewayOrderId: string;
+        /** Whole Rials as a digit string. */
+        amount: string;
+        currency: "IRR";
+        description: string;
+        status: PaymentStatus;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        metadata: Record<string, unknown>;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        resultCode: number | null;
+        resultText: string | null;
+        installment: InstallmentInfo | null;
+        redirect: CheckoutRedirect | null;
+        /** Sanitised gateway callback body, kept for audit and retried verifies. */
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        expiresAt: Date | null;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        /** Last status OBH acknowledged. `null` until the first successful report. */
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+    }>;
+    findByReference(reference: string): Promise<{
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+        /** The service's own order id. */
+        orderId: string;
+        /** 1 for the first attempt on `orderId`, then 2, 3, … */
+        attempt: number;
+        gateway: string;
+        /** Digits-only number sent to the gateway; unique per gateway. */
+        gatewayOrderId: string;
+        /** Whole Rials as a digit string. */
+        amount: string;
+        currency: "IRR";
+        description: string;
+        status: PaymentStatus;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        metadata: Record<string, unknown>;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        resultCode: number | null;
+        resultText: string | null;
+        installment: InstallmentInfo | null;
+        redirect: CheckoutRedirect | null;
+        /** Sanitised gateway callback body, kept for audit and retried verifies. */
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        expiresAt: Date | null;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        /** Last status OBH acknowledged. `null` until the first successful report. */
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+    } | null>;
+    listByOrderId(orderId: string): Promise<{
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+        /** The service's own order id. */
+        orderId: string;
+        /** 1 for the first attempt on `orderId`, then 2, 3, … */
+        attempt: number;
+        gateway: string;
+        /** Digits-only number sent to the gateway; unique per gateway. */
+        gatewayOrderId: string;
+        /** Whole Rials as a digit string. */
+        amount: string;
+        currency: "IRR";
+        description: string;
+        status: PaymentStatus;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        metadata: Record<string, unknown>;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        resultCode: number | null;
+        resultText: string | null;
+        installment: InstallmentInfo | null;
+        redirect: CheckoutRedirect | null;
+        /** Sanitised gateway callback body, kept for audit and retried verifies. */
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        expiresAt: Date | null;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        /** Last status OBH acknowledged. `null` until the first successful report. */
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+    }[]>;
+    findByGatewayOrderId(gateway: string, gatewayOrderId: string): Promise<{
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+        /** The service's own order id. */
+        orderId: string;
+        /** 1 for the first attempt on `orderId`, then 2, 3, … */
+        attempt: number;
+        gateway: string;
+        /** Digits-only number sent to the gateway; unique per gateway. */
+        gatewayOrderId: string;
+        /** Whole Rials as a digit string. */
+        amount: string;
+        currency: "IRR";
+        description: string;
+        status: PaymentStatus;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        metadata: Record<string, unknown>;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        resultCode: number | null;
+        resultText: string | null;
+        installment: InstallmentInfo | null;
+        redirect: CheckoutRedirect | null;
+        /** Sanitised gateway callback body, kept for audit and retried verifies. */
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        expiresAt: Date | null;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        /** Last status OBH acknowledged. `null` until the first successful report. */
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+    } | null>;
+    findBySessionId(gateway: string, sessionId: string): Promise<{
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+        /** The service's own order id. */
+        orderId: string;
+        /** 1 for the first attempt on `orderId`, then 2, 3, … */
+        attempt: number;
+        gateway: string;
+        /** Digits-only number sent to the gateway; unique per gateway. */
+        gatewayOrderId: string;
+        /** Whole Rials as a digit string. */
+        amount: string;
+        currency: "IRR";
+        description: string;
+        status: PaymentStatus;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        metadata: Record<string, unknown>;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        resultCode: number | null;
+        resultText: string | null;
+        installment: InstallmentInfo | null;
+        redirect: CheckoutRedirect | null;
+        /** Sanitised gateway callback body, kept for audit and retried verifies. */
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        expiresAt: Date | null;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        /** Last status OBH acknowledged. `null` until the first successful report. */
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+    } | null>;
+    update(reference: string, patch: PaymentPatch): Promise<{
+        installment: InstallmentInfo | null;
+        amount: string;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        resultCode: number | null;
+        redirect: CheckoutRedirect | null;
+        expiresAt: Date | null;
+        status: PaymentStatus;
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        metadata: Record<string, unknown>;
+        orderId: string;
+        attempt: number;
+        gateway: string;
+        gatewayOrderId: string;
+        currency: "IRR";
+        description: string;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        resultText: string | null;
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+    }>;
+    transition(reference: string, from: PaymentStatus, patch: PaymentPatch & {
+        status: PaymentStatus;
+    }): Promise<{
+        installment: InstallmentInfo | null;
+        amount: string;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        resultCode: number | null;
+        redirect: CheckoutRedirect | null;
+        expiresAt: Date | null;
+        status: "failed" | "pending" | "completed" | "cancelled" | "expired";
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        metadata: Record<string, unknown>;
+        orderId: string;
+        attempt: number;
+        gateway: string;
+        gatewayOrderId: string;
+        currency: "IRR";
+        description: string;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        resultText: string | null;
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+    } | null>;
+    listPending(before: Date, limit: number): Promise<{
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+        /** The service's own order id. */
+        orderId: string;
+        /** 1 for the first attempt on `orderId`, then 2, 3, … */
+        attempt: number;
+        gateway: string;
+        /** Digits-only number sent to the gateway; unique per gateway. */
+        gatewayOrderId: string;
+        /** Whole Rials as a digit string. */
+        amount: string;
+        currency: "IRR";
+        description: string;
+        status: PaymentStatus;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        metadata: Record<string, unknown>;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        resultCode: number | null;
+        resultText: string | null;
+        installment: InstallmentInfo | null;
+        redirect: CheckoutRedirect | null;
+        /** Sanitised gateway callback body, kept for audit and retried verifies. */
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        expiresAt: Date | null;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        /** Last status OBH acknowledged. `null` until the first successful report. */
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+    }[]>;
+    listUnreported(limit: number): Promise<{
+        /** Unique id of this attempt, e.g. `PAY-3F9A…`. */
+        reference: string;
+        /** The service's own order id. */
+        orderId: string;
+        /** 1 for the first attempt on `orderId`, then 2, 3, … */
+        attempt: number;
+        gateway: string;
+        /** Digits-only number sent to the gateway; unique per gateway. */
+        gatewayOrderId: string;
+        /** Whole Rials as a digit string. */
+        amount: string;
+        currency: "IRR";
+        description: string;
+        status: PaymentStatus;
+        environment: PaymentEnvironment;
+        returnUrl: string | null;
+        customerMobile: string | null;
+        metadata: Record<string, unknown>;
+        providerSessionId: string | null;
+        providerReference: string | null;
+        traceNumber: string | null;
+        maskedCardNumber: string | null;
+        resultCode: number | null;
+        resultText: string | null;
+        installment: InstallmentInfo | null;
+        redirect: CheckoutRedirect | null;
+        /** Sanitised gateway callback body, kept for audit and retried verifies. */
+        callbackPayload: Record<string, unknown> | null;
+        createdAt: Date;
+        expiresAt: Date | null;
+        callbackReceivedAt: Date | null;
+        completedAt: Date | null;
+        failedAt: Date | null;
+        /** Last status OBH acknowledged. `null` until the first successful report. */
+        reportedStatus: PaymentStatus | null;
+        reportedAt: Date | null;
+    }[]>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

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

package/dist/store.js

@@ -0,0 +1,68 @@
+/** In-process store for tests and local development. Not for production. */
+export class MemoryPaymentStore {
+    records = new Map();
+    counter = 0;
+    async nextGatewayOrderId() {
+        this.counter += 1;
+        return String(Date.now()) + String(this.counter).padStart(3, "0");
+    }
+    async insert(record) {
+        if (this.records.has(record.reference)) {
+            throw new Error(`Payment ${record.reference} already exists.`);
+        }
+        this.records.set(record.reference, { ...record });
+        return { ...record };
+    }
+    async findByReference(reference) {
+        const record = this.records.get(reference);
+        return record ? { ...record } : null;
+    }
+    async listByOrderId(orderId) {
+        return [...this.records.values()]
+            .filter((record) => record.orderId === orderId)
+            .sort((a, b) => a.attempt - b.attempt)
+            .map((record) => ({ ...record }));
+    }
+    async findByGatewayOrderId(gateway, gatewayOrderId) {
+        const found = [...this.records.values()].find((record) => record.gateway === gateway && record.gatewayOrderId === gatewayOrderId);
+        return found ? { ...found } : null;
+    }
+    async findBySessionId(gateway, sessionId) {
+        const found = [...this.records.values()].find((record) => record.gateway === gateway && record.providerSessionId === sessionId);
+        return found ? { ...found } : null;
+    }
+    async update(reference, patch) {
+        const current = this.records.get(reference);
+        if (!current) {
+            throw new Error(`Payment ${reference} was not found.`);
+        }
+        const next = { ...current, ...patch };
+        this.records.set(reference, next);
+        return { ...next };
+    }
+    async transition(reference, from, patch) {
+        const current = this.records.get(reference);
+        if (!current || current.status !== from) {
+            return null;
+        }
+        const next = { ...current, ...patch };
+        this.records.set(reference, next);
+        return { ...next };
+    }
+    async listPending(before, limit) {
+        return [...this.records.values()]
+            .filter((record) => record.status === "pending" &&
+            record.createdAt.getTime() < before.getTime())
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+            .slice(0, limit)
+            .map((record) => ({ ...record }));
+    }
+    async listUnreported(limit) {
+        return [...this.records.values()]
+            .filter((record) => record.status !== record.reportedStatus)
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+            .slice(0, limit)
+            .map((record) => ({ ...record }));
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Gateway-level types. An adapter talks to one bank gateway; it knows nothing
+ * about storage or OBH. The orchestrator in `pay.ts` combines adapters with a
+ * `PaymentStore` and the finance reporter.
+ */
+export type ProviderPaymentStatus = "COMPLETED" | "FAILED" | "PENDING";
+export type CheckoutSessionInput = {
+    paymentReference: string;
+    /** Digits-only order number sent to the gateway (unique per terminal). */
+    gatewayOrderId: string;
+    serviceSlug: string;
+    /** Whole Rials, as a digit string. */
+    amount: string;
+    currency: "IRR";
+    description: string;
+    returnUrl: string | null;
+    /** Public URL the gateway sends the customer back to. */
+    callbackUrl: string;
+    metadata: Record<string, unknown>;
+    /** Customer mobile number (`09xxxxxxxxx`). Required by Digipay. */
+    customerMobile?: string | null;
+};
+/**
+ * How the customer's browser gets to the bank. Most gateways take a plain
+ * redirect; Mellat (Behpardakht) needs an auto-submitted POST form.
+ */
+export type CheckoutRedirect = {
+    method: "GET";
+    url: string;
+} | {
+    method: "POST";
+    url: string;
+    fields: Record<string, string>;
+};
+export type CheckoutSession = {
+    providerSessionId: string;
+    providerReference: string | null;
+    checkoutUrl: string | null;
+    /** Set when the redirect is not a plain GET of `checkoutUrl`. */
+    redirect?: CheckoutRedirect;
+    expiresAt: Date;
+    resultCode: number;
+    resultMessage: string;
+};
+export type VerifyPaymentInput = {
+    providerSessionId: string | null;
+    providerReference: string | null;
+    gatewayOrderId?: string;
+    expectedAmount?: string;
+    payload?: Record<string, unknown>;
+};
+export type VerifyPaymentResult = {
+    status: ProviderPaymentStatus;
+    providerReference: string;
+    traceNumber: string | null;
+    maskedCardNumber: string | null;
+    resultCode: number;
+    resultMessage: string;
+    verifiedAmount: string | null;
+    verifiedOrderId: string | null;
+    verifiedAt: Date | null;
+    failureReason: string | null;
+    metadata: Record<string, unknown>;
+};
+export type PaymentGatewayKind = "card" | "installment";
+/** Public description of a gateway. Credentials never appear here. */
+export type PaymentGatewayDescriptor = {
+    code: string;
+    name: string;
+    /** Persian label suitable for a checkout page. */
+    displayName: string;
+    description: string;
+    kind: PaymentGatewayKind;
+    requiresCustomerMobile: boolean;
+    minAmount: string | null;
+};
+/**
+ * What an adapter learned from the bank's callback request, before any
+ * server-to-server verification.
+ */
+export type ParsedCallback = {
+    /** Token / authority / RefId the gateway issued when the session opened. */
+    sessionId: string | null;
+    /** Numeric order number echoed back by the gateway. */
+    gatewayOrderId: string | null;
+    /** `verify` when the bank reports success; `failed` for cancel/decline. */
+    outcome: "verify" | "failed";
+    resultCode: number;
+    resultText: string;
+    providerReference: string | null;
+    maskedCardNumber: string | null;
+    /** Sanitised copy of the callback body, kept for audit and re-verify. */
+    payload: Record<string, unknown>;
+};
+export interface PaymentGatewayAdapter {
+    readonly code: string;
+    readonly descriptor: PaymentGatewayDescriptor;
+    /** True when credentials are present in the environment. */
+    isConfigured(): boolean;
+    createCheckoutSession(input: CheckoutSessionInput): Promise<CheckoutSession>;
+    verifyPayment(input: VerifyPaymentInput): Promise<VerifyPaymentResult>;
+    /** Reads the callback request body or query into a normalized shape. */
+    parseCallback(payload: Record<string, string | null | undefined>): ParsedCallback;
+}
+export declare class PaymentProviderError extends Error {
+    code: string;
+    resultCode?: number;
+    constructor(code: string, message: string, resultCode?: number);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Gateway-level types. An adapter talks to one bank gateway; it knows nothing
+ * about storage or OBH. The orchestrator in `pay.ts` combines adapters with a
+ * `PaymentStore` and the finance reporter.
+ */
+export class PaymentProviderError extends Error {
+    code;
+    resultCode;
+    constructor(code, message, resultCode) {
+        super(message);
+        this.name = "PaymentProviderError";
+        this.code = code;
+        this.resultCode = resultCode;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0GH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,CAAQ;IACZ,UAAU,CAAS;IAEnB,YAAY,IAAY,EAAE,OAAe,EAAE,UAAmB;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;CACF"}