@mj-biz-apps/orders-core-entities-server 0.0.1 → 5.2.0

package/dist/PaymentProviderBehavior.js

@@ -0,0 +1,368 @@
+/**
+ * The parts of talking to a payment gateway that can be got wrong without a network — and therefore
+ * the parts worth proving without one.
+ *
+ * Three things live here, and each is here because its failure mode is silent:
+ *
+ *   1. MINOR-UNIT CONVERSION. Stripe and most gateways transact in the currency's smallest unit, so
+ *      $12.34 is `1234`. Getting that wrong is a factor-of-100 error that looks like a plausible
+ *      amount at both ends — charge 12 cents for a $12 order, or $1,234 for a $12.34 one. Worse, JPY
+ *      has NO minor unit, so the "obvious" `× 100` overcharges a Japanese customer a hundredfold.
+ *
+ *   2. WEBHOOK SIGNATURE VERIFICATION. The webhook route is unauthenticated by necessity (D19) — the
+ *      signature IS the authentication. A verifier that accepts anything is a public endpoint that
+ *      marks orders paid, and it passes every test that only ever feeds it valid input.
+ *
+ *   3. IDEMPOTENCY. Gateways retry, and they retry on success too — a webhook that times out on our
+ *      side is redelivered. Processing one twice books the cash twice.
+ *
+ * CONNECTS TO:
+ *   SERVER: ./BasePaymentProvider.ts and the drivers under it
+ *   ROUTE:  ./PaymentWebhookHandler.ts
+ *   DOC:    plans/archive/bizapps-orders-master.md D19, D37
+ */
+// WEB CRYPTO, NOT `node:crypto`. The shared server tsconfig sets `"types": []`, so this package has no
+// Node globals by design and no other file in it reaches for one. `globalThis.crypto` is typed by the
+// `dom` lib that IS included, exists in Node 18+, and needs no dependency — the only cost is that HMAC
+// becomes async, which the webhook path already is.
+/**
+ * Currencies with NO minor unit, so an amount is already in its smallest unit.
+ *
+ * From Stripe's zero-decimal list. Kept explicit rather than derived from `Intl` because the gateway's
+ * opinion is what matters here, not the locale database's: we must send what Stripe expects, and a
+ * disagreement between the two would be a hundredfold error in whichever direction it fell.
+ */
+const ZERO_DECIMAL = new Set([
+    'BIF', 'CLP', 'DJF', 'GNF', 'JPY', 'KMF', 'KRW', 'MGA', 'PYG', 'RWF',
+    'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF',
+]);
+/** Currencies whose smallest unit is a THOUSANDTH. Rare, and wrong by 10x if treated as ordinary. */
+const THREE_DECIMAL = new Set(['BHD', 'JOD', 'KWD', 'OMR', 'TND']);
+/** How many minor units make one major unit. */
+export function CurrencyExponent(currencyCode) {
+    const code = (currencyCode ?? 'USD').toUpperCase();
+    if (ZERO_DECIMAL.has(code))
+        return 0;
+    if (THREE_DECIMAL.has(code))
+        return 3;
+    return 2;
+}
+/**
+ * Turn an amount we hold as a decimal into the integer the gateway wants.
+ *
+ * Rounds rather than truncates, and rounds the SCALED value: `Math.round(12.345 * 100)` is 1235 while
+ * `Math.round(12.345) * 100` is 1200. Both look like money.
+ *
+ * Throws on a non-finite amount instead of sending `NaN` to a gateway, which some accept as zero.
+ */
+export function ToMinorUnits(amount, currencyCode) {
+    if (!Number.isFinite(amount)) {
+        throw new Error(`Cannot convert ${amount} to minor units — it is not a finite amount.`);
+    }
+    const factor = 10 ** CurrencyExponent(currencyCode);
+    // `Number.EPSILON` nudge for the same reason `Money()` uses one: 1.005 * 100 is 100.49999… in
+    // binary floating point, and rounding that gives 100 rather than 101.
+    return Math.round((amount + Number.EPSILON * Math.sign(amount)) * factor);
+}
+/** And back, for reading what the gateway reported. */
+export function FromMinorUnits(minor, currencyCode) {
+    if (!Number.isFinite(minor)) {
+        throw new Error(`Cannot convert ${minor} from minor units — it is not a finite amount.`);
+    }
+    const factor = 10 ** CurrencyExponent(currencyCode);
+    return Math.round((minor / factor) * 100) / 100;
+}
+/**
+ * Verify a Stripe-style `Stripe-Signature` header.
+ *
+ * The scheme: `t=<unix seconds>,v1=<hex hmac>[,v1=<another>]`, where the HMAC is SHA-256 over
+ * `${t}.${rawBody}` keyed with the endpoint secret. Multiple `v1` values appear during a secret
+ * rotation, and ANY match is a pass — a verifier that only reads the first one breaks silently
+ * halfway through a rotation, which is the worst possible moment.
+ *
+ * THE RAW BODY IS NOT NEGOTIABLE. The signature covers the exact bytes Stripe sent. Any JSON
+ * round-trip — key reordering, whitespace, unicode normalisation — changes them, and the signature
+ * then fails for a legitimate event. That is why the route captures the raw body before any parser
+ * touches it.
+ *
+ * TIMESTAMP TOLERANCE defends against replay: a valid old payload stays valid forever without it.
+ * Default five minutes, matching Stripe's own guidance. `nowSeconds` is a parameter so this is
+ * testable without waiting.
+ */
+export async function VerifyWebhookSignature(rawBody, signatureHeader, secret, opts = {}) {
+    if (!secret) {
+        // A missing secret must FAIL rather than skip verification. "No secret configured, so accept
+        // everything" turns a misconfiguration into an open endpoint that marks orders paid.
+        return { Valid: false, Reason: 'no endpoint secret is configured for this provider' };
+    }
+    if (!signatureHeader)
+        return { Valid: false, Reason: 'the request carried no signature header' };
+    let timestamp = null;
+    const candidates = [];
+    for (const part of signatureHeader.split(',')) {
+        const [key, value] = part.split('=', 2).map((s) => s?.trim());
+        if (key === 't' && value)
+            timestamp = Number(value);
+        if (key === 'v1' && value)
+            candidates.push(value);
+    }
+    if (timestamp == null || !Number.isFinite(timestamp)) {
+        return { Valid: false, Reason: 'the signature header carried no usable timestamp' };
+    }
+    if (!candidates.length)
+        return { Valid: false, Reason: 'the signature header carried no v1 signature' };
+    const tolerance = opts.ToleranceSeconds ?? 300;
+    const now = opts.NowSeconds ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > tolerance) {
+        return {
+            Valid: false,
+            Reason: `the signature timestamp is ${Math.abs(now - timestamp)}s away, outside the ${tolerance}s tolerance`,
+        };
+    }
+    const expected = await HmacSha256Hex(secret, `${timestamp}.${rawBody}`);
+    for (const candidate of candidates) {
+        if (SignaturesMatch(expected, candidate))
+            return { Valid: true };
+    }
+    return { Valid: false, Reason: 'no provided signature matched' };
+}
+/** HMAC-SHA256 as lowercase hex, via Web Crypto. */
+export async function HmacSha256Hex(secret, payload) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(payload));
+    return [...new Uint8Array(signature)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Constant-time hex comparison.
+ *
+ * `===` on a signature leaks how many leading characters were right through how long the comparison
+ * took. That is a real attack against a public endpoint, and the fix costs nothing. `timingSafeEqual`
+ * throws on a length mismatch, so the lengths are checked first — and a mismatched length is itself
+ * not secret, since the algorithm fixes it.
+ */
+export function SignaturesMatch(expected, provided) {
+    if (expected.length !== provided.length)
+        return false;
+    // XOR-accumulate every position rather than returning on the first difference. `Node`'s
+    // `timingSafeEqual` would do this for us but lives behind `node:crypto`; the loop is the same
+    // guarantee in six lines, and it never short-circuits.
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++) {
+        diff |= expected.charCodeAt(i) ^ provided.charCodeAt(i);
+    }
+    return diff === 0;
+}
+/**
+ * Map a gateway's own status onto ours.
+ *
+ * UNKNOWN MAPS TO `Processing`, NOT to `Succeeded` or `Failed`. A status we do not recognise means the
+ * gateway has told us something this code was not written for, and both confident answers are
+ * dangerous: `Succeeded` books cash that may not exist, `Failed` abandons a payment that may be fine.
+ * `Processing` is the honest reading — something is happening and we do not yet know what — and it
+ * leaves the payment for a human or a later event to resolve.
+ */
+export function MapStripeIntentStatus(providerStatus) {
+    switch ((providerStatus ?? '').toLowerCase()) {
+        case 'requires_payment_method':
+        case 'requires_confirmation':
+        case 'requires_action':
+        case 'requires_source':
+        case 'requires_source_action':
+            return 'RequiresPayment';
+        case 'processing':
+            return 'Processing';
+        case 'succeeded':
+            return 'Succeeded';
+        case 'canceled':
+        case 'cancelled':
+            return 'Canceled';
+        // Stripe has no `failed` intent status — a failure arrives as an EVENT against an intent that
+        // is back to requires_payment_method. `payment_intent.payment_failed` is mapped by the event
+        // reader, not here, and this case exists for gateways that do report it directly.
+        case 'failed':
+            return 'Failed';
+        default:
+            return 'Processing';
+    }
+}
+/**
+ * Decide what to do with an event, given what we have already seen.
+ *
+ * `AlreadyApplied` IS A SUCCESS, and that distinction is the whole point. A gateway that does not get
+ * a 2xx retries, so returning an error for a duplicate guarantees it comes back — forever. The
+ * response must say "yes, we have this" without doing the work twice.
+ *
+ * `Ignore` is for events we are not interested in. Gateways send far more than any one integration
+ * consumes, and treating an unrecognised event as an error means a Stripe dashboard full of red for
+ * events we were never going to read.
+ */
+export function DecideWebhookAction(input) {
+    if (!input.EventID) {
+        return { Action: 'Reject', Reason: 'the event carried no id, so it cannot be de-duplicated' };
+    }
+    if (input.AlreadySeen) {
+        return { Action: 'AlreadyApplied', Reason: `event ${input.EventID} has already been applied` };
+    }
+    if (!input.EventKind || !input.HandledKinds.includes(input.EventKind)) {
+        return { Action: 'Ignore', Reason: `'${input.EventKind ?? 'unknown'}' is not an event this integration acts on` };
+    }
+    if (!input.IntentKnown) {
+        // NOT an error. A gateway account may serve more than this application, and an intent we did
+        // not create is simply not ours — rejecting it would mean retries forever for someone else's
+        // traffic.
+        return { Action: 'Ignore', Reason: 'the event names a payment intent this application did not create' };
+    }
+    return { Action: 'Apply', Reason: `event ${input.EventID} is new and actionable` };
+}
+/**
+ * Split a captured amount into the cash actually received and the gateway's cut.
+ *
+ * The capture entry is `Dr Cash (net) / Dr Processing Fee / Cr A/R (gross)` (D18), so these three
+ * numbers must reconcile exactly or the entry will not balance. Deriving `net` by subtraction rather
+ * than trusting a reported net is deliberate: a gateway that rounds its own net differently would
+ * leave a penny with no home in the ledger.
+ *
+ * ALL THREE ARE EXACT AT 2DP, BUT `Net + Fee` IN JAVASCRIPT IS NOT. Adding two correctly-rounded
+ * decimals drifts in binary floating point — 32.06 + 1.27 is 33.330000000000005 — so a caller
+ * reconciling them must round the SUM before comparing, exactly as `Money()` does everywhere else in
+ * this package. This is the same hazard that made a balanced journal entry fail an exact-equality check
+ * in accounting; the numbers were never wrong, the comparison was.
+ */
+export function SplitCapturedAmount(grossAmount, feeAmount) {
+    const gross = Math.round(grossAmount * 100) / 100;
+    const fee = Math.round(Math.abs(feeAmount ?? 0) * 100) / 100;
+    if (fee > gross) {
+        throw new Error(`A processing fee of ${fee} cannot exceed the ${gross} captured. Booking this would credit ` +
+            `receivables less than the cash and fee together, and the entry would not balance.`);
+    }
+    return { Gross: gross, Fee: fee, Net: Math.round((gross - fee) * 100) / 100 };
+}
+// ─── Bank debits (ACH) ─────────────────────────────────────────────────────────────────────────
+/**
+ * Stripe's published US bank-debit price: 0.8% of the amount, capped at $5.
+ *
+ * FOR THE STUB ONLY, and the name says so deliberately. The live path reads the fee off the charge's
+ * balance transaction like every other capture — what Stripe actually charged is a fact, and computing
+ * it here would be this file's opinion competing with the gateway's record. A stub that reported a
+ * ZERO fee would be worse still: it would make the fee leg of the capture entry (D18) unreachable in
+ * every test, so the arithmetic most worth exercising would be the arithmetic never exercised. That is
+ * the same reasoning behind the card stub's 2.9% + 30c, and the same reason this constant will drift
+ * from Stripe's price list one day without breaking anything real.
+ *
+ * The cap is a MAJOR-UNIT USD figure. A bank debit is a US rail, so the currency is USD in practice;
+ * a caller passing anything else gets the percentage without the cap rather than a cap converted at a
+ * rate this module has no business knowing.
+ */
+export function AchFeeEstimate(grossAmount, currencyCode = 'USD') {
+    const gross = Math.round(Math.abs(grossAmount ?? 0) * 100) / 100;
+    if (!Number.isFinite(gross) || gross <= 0)
+        return 0;
+    const raw = gross * 0.008;
+    const capped = currencyCode.toUpperCase() === 'USD' ? Math.min(raw, 5) : raw;
+    return Math.round(capped * 100) / 100;
+}
+/**
+ * Decide what a bank-debit event does to its payment.
+ *
+ * THE ASYMMETRY IS THE WHOLE DESIGN. A card tells you at the till; a bank debit tells you up to four
+ * business days later, and it can tell you TWICE — "taken" and then, a week after that, "returned"
+ * (insufficient funds, account closed, unauthorised). So there is no single moment where the answer is
+ * known, and a payment has to be able to move forward AND backward:
+ *
+ *   Pending  + succeeded → `Promote`  the payment becomes Captured, which is what books the cash
+ *   Pending  + failed    → `Fail`     nothing was ever booked, so nothing needs reversing
+ *   Captured + failed    → `Reverse`  the money left again; a REVERSING payment says so in the ledger
+ *
+ * WHY `Reverse` AND NOT AN UPDATE. A returned debit is not "the payment never happened" — it happened,
+ * the ledger recorded it, a period may have closed over it. Editing the original would erase a true
+ * fact about a past date. A reversing payment is the same answer the rest of this application already
+ * gives (`ReversesPaymentHeaderID`, D53), and it leaves both facts standing.
+ *
+ * `None` covers the ordinary quiet cases — an event that changes nothing, a promotion that already
+ * happened — and is a SUCCESS. A gateway that does not get a 2xx retries forever.
+ */
+export function DecideSettlement(input) {
+    const header = (input.HeaderStatus ?? '').trim();
+    if (!header) {
+        // NOT an error. An intent can exist without a payment — a checkout the customer abandoned, or
+        // one whose payment has not been captured yet. There is simply nothing to settle.
+        return { Action: 'None', Reason: 'the intent has no payment to settle' };
+    }
+    switch (input.EventStatus) {
+        case 'Succeeded':
+            if (header === 'Pending') {
+                return { Action: 'Promote', Reason: 'the bank confirmed the debit, so the payment becomes Captured' };
+            }
+            if (header === 'Captured') {
+                return { Action: 'None', Reason: 'the payment is already Captured' };
+            }
+            // Succeeded against Failed / Refunded / Disputed. A bank does not un-return a debit, so
+            // this is either a gateway we have misread or an event arriving wildly out of order.
+            return {
+                Action: 'Hold',
+                Reason: `the bank reported success against a payment that is ${header} — this needs a person`,
+            };
+        case 'Failed':
+        case 'Canceled':
+            if (header === 'Pending') {
+                return { Action: 'Fail', Reason: 'the debit did not clear and nothing was booked' };
+            }
+            if (header === 'Captured') {
+                if (input.AlreadyReversed) {
+                    return { Action: 'None', Reason: 'this payment has already been reversed' };
+                }
+                if (!input.HeaderBooked) {
+                    // Captured without a journal entry should be impossible — booking is part of the
+                    // same transaction as the transition. If it happened, the two records disagree
+                    // about whether cash exists, and guessing which is right is how the disagreement
+                    // becomes permanent.
+                    return {
+                        Action: 'Hold',
+                        Reason: 'the payment is Captured but carries no journal entry, so what to reverse is unclear',
+                    };
+                }
+                return { Action: 'Reverse', Reason: 'the debit was returned after being booked, so the cash comes back out' };
+            }
+            if (header === 'Failed') {
+                return { Action: 'None', Reason: 'the payment is already Failed' };
+            }
+            return {
+                Action: 'Hold',
+                Reason: `the bank reported a failure against a payment that is ${header} — this needs a person`,
+            };
+        // Processing / RequiresPayment / unknown. The gateway is telling us it is still working, which
+        // is exactly the state a Pending payment already records.
+        default:
+            return { Action: 'None', Reason: `nothing to settle while the intent reads ${input.EventStatus ?? 'unknown'}` };
+    }
+}
+/**
+ * Whether a payment asking to be `Captured` must be held at `Pending` because its rail settles on
+ * somebody else's schedule.
+ *
+ * WHY THIS IS A FUNCTION AND NOT AN `IF` IN THE SAVE PATH. The rule used to live only in
+ * `Orders.CapturePayment`, which made it a rule that ONE CALLER followed rather than one the system
+ * enforced — a workflow, a UI form or a test builder writing `Status: 'Captured'` went straight past
+ * it and booked `Dr Cash` for a bank debit that had not cleared. Balanced, posted, and undetectable
+ * downstream. Stating it here means the entity server and the operation ask the same question of the
+ * same code instead of both remembering.
+ *
+ * THE PROMOTION MUST PASS. When the webhook moves a `Pending` payment to `Captured`, that IS the
+ * bank answering; holding it again would mean a bank debit could never book at all. The persisted
+ * status is the signal — already `Pending` means promotion, anything else means a caller declaring
+ * cash that has not moved.
+ */
+export function ShouldHoldForLateSettlement(facts) {
+    if (facts.RequestedStatus !== 'Captured')
+        return false;
+    if (!facts.HasProvider)
+        return false;
+    if (!facts.SettlesAsynchronously)
+        return false;
+    // The webhook promoting a payment that was already waiting — let it book.
+    if (facts.IsSaved && facts.PersistedStatus === 'Pending')
+        return false;
+    return true;
+}
+//# sourceMappingURL=PaymentProviderBehavior.js.map

package/dist/PaymentProviderBehavior.js.map

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

package/dist/PaymentProviderResolver.d.ts

@@ -0,0 +1,84 @@
+/**
+ * PaymentProviderResolver — turns a `PaymentProvider` row into a working driver.
+ *
+ * Two jobs, and the second is the one with teeth.
+ *
+ * 1. FIND THE DRIVER. `PaymentProviderType.Code` is the `@RegisterClass` key (D37), so resolution is a
+ *    ClassFactory lookup and adding a gateway needs no schema change. A missing registration REFUSES
+ *    rather than falling back to the base class: the base's methods all decline, so a fallback would
+ *    look like a gateway that cannot do anything rather than like a driver nobody registered — and the
+ *    difference is a five-minute fix versus an afternoon.
+ *
+ * 2. FIND THE CREDENTIALS, WITHOUT EVER STORING THEM. `PaymentProvider.CredentialsRef` is a POINTER —
+ *    the name of a place to look, not a secret. Nothing in this schema holds an API key, because a
+ *    database that holds live payment credentials is a database whose backups do too.
+ *
+ * THE SECRET SEAM. `CredentialsRef` resolves through `BaseSecretResolver`, registered by ClassFactory
+ * like everything else here. The default reads environment variables, which is right for a single
+ * deployment and inadequate for a real one — so a customer using Vault, AWS Secrets Manager or Azure
+ * Key Vault registers a subclass and changes no other code. Naming the seam is the point; pretending
+ * environment variables are a secret store would be the mistake.
+ *
+ * CREDENTIALS ARE NEVER CACHED. They are fetched per operation and dropped. A cache would keep live
+ * keys in process memory for the lifetime of a server for the sake of avoiding a lookup that happens
+ * once per payment, which is not a trade worth making.
+ *
+ * CONNECTS TO:
+ *   BASE:    ./BasePaymentProvider.ts
+ *   DRIVERS: ./StripePaymentProvider.ts · ./ManualPaymentProvider.ts · ./StoredValuePaymentProvider.ts
+ *   DOC:     plans/archive/bizapps-orders-master.md D19, D37
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { BasePaymentProvider, type PaymentCredentials, type PaymentProviderConfig } from './BasePaymentProvider.js';
+/**
+ * How a `CredentialsRef` becomes actual secrets.
+ *
+ * The default treats the ref as an environment-variable PREFIX, so `STRIPE_BLUECYPRESS` reads
+ * `STRIPE_BLUECYPRESS_API_KEY` and `STRIPE_BLUECYPRESS_WEBHOOK_SECRET`. Prefixed rather than a single
+ * variable because one deployment routinely holds several configured accounts — a live one and a test
+ * one at minimum — and they need separate keys.
+ */
+export declare class BaseSecretResolver {
+    /**
+     * Returns whatever it can find. An EMPTY result is not an error here: a Manual provider has no
+     * credentials at all, and the driver that needs a key is the one that should complain about its
+     * absence, with the context to say what it was trying to do.
+     */
+    Resolve(_credentialsRef: string | null | undefined): Promise<PaymentCredentials>;
+}
+/**
+ * The default: `CredentialsRef` is an environment-variable PREFIX.
+ *
+ * `STRIPE_BLUECYPRESS` reads `STRIPE_BLUECYPRESS_API_KEY` and `STRIPE_BLUECYPRESS_WEBHOOK_SECRET`.
+ * Prefixed rather than a single variable because one deployment routinely holds several configured
+ * accounts — a live one and a test one at minimum — and they need separate keys.
+ *
+ * Registered with NO key, so it is the fallback a deployment replaces by registering its own against
+ * `BaseSecretResolver` — the same shape as `DefaultPriceResolver`.
+ */
+export declare class EnvironmentSecretResolver extends BaseSecretResolver {
+    Resolve(credentialsRef: string | null | undefined): Promise<PaymentCredentials>;
+}
+/** Tree-shaking anchor for the secret seam. */
+export declare function LoadEnvironmentSecretResolver(): void;
+export declare class PaymentProviderNotConfiguredError extends Error {
+}
+/**
+ * Load a configured provider row and hand back a ready driver.
+ *
+ * Throws rather than returning null. Every caller of this is about to move money and cannot proceed
+ * without a driver, so there is no branch for a caller to take — and an exception carries the reason to
+ * a log, where a returned null would arrive as "cannot read property of undefined" somewhere else.
+ */
+export declare function ResolvePaymentProvider(paymentProviderID: string, provider: IMetadataProvider, user: UserInfo): Promise<BasePaymentProvider>;
+/** The configured account, with its type's code and capability flags flattened onto it. */
+export declare function LoadPaymentProviderConfig(paymentProviderID: string, provider: IMetadataProvider, user: UserInfo): Promise<PaymentProviderConfig>;
+/**
+ * Instantiate the driver for a config and attach everything it needs.
+ *
+ * Exposed separately from `ResolvePaymentProvider` so the webhook route can build a driver from a config
+ * it already loaded — the route resolves a provider from the URL before it has a payment in hand, and
+ * making it re-query would mean two lookups for one request.
+ */
+export declare function BuildPaymentProvider(config: PaymentProviderConfig, provider: IMetadataProvider, user: UserInfo): Promise<BasePaymentProvider>;
+//# sourceMappingURL=PaymentProviderResolver.d.ts.map

package/dist/PaymentProviderResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaymentProviderResolver.d.ts","sourceRoot":"","sources":["../src/PaymentProviderResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,iBAAiB,EAA6B,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAG9F,OAAO,EACH,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC7B,MAAM,0BAA0B,CAAC;AAYlC;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC3B;;;;OAIG;IACU,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGhG;AAED;;;;;;;;;GASG;AACH,qBACa,yBAA0B,SAAQ,kBAAkB;IACvC,OAAO,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAWxG;AAED,+CAA+C;AAC/C,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAED,qBAAa,iCAAkC,SAAQ,KAAK;CAAG;AAE/D;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CACxC,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,mBAAmB,CAAC,CAG9B;AAED,2FAA2F;AAC3F,wBAAsB,yBAAyB,CAC3C,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,qBAAqB,CAAC,CAyDhC;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACtC,MAAM,EAAE,qBAAqB,EAC7B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,mBAAmB,CAAC,CAiC9B"}