@oobe-protocol-labs/sap-mcp-server 0.3.0 → 0.7.1

package/dist/payments/facilitator-rpc-fallback.js

@@ -0,0 +1,228 @@
+/**
+ * @name FacilitatorRpcFallback
+ * @description Resilient RPC endpoint failover with round-robin and timeouts
+ *   for x402 SVM facilitator operations.
+ *
+ * Strategy:
+ *   1. Round-robin — each call starts from the next endpoint in the rotation
+ *   2. Timeout — each attempt gets a configurable deadline (default 8s)
+ *   3. Failover — on transient errors or timeout, immediately tries the next endpoint
+ *   4. Multiple public mainnet RPCs are included as defaults to avoid rate limits
+ */
+import { logger, redactSensitiveString } from '../core/logger.js';
+/** Per-attempt timeout in milliseconds. If an RPC doesn't respond in this window, we move to the next. */
+const RPC_ATTEMPT_TIMEOUT_MS = 8_000;
+/** Round-robin counter — shared across all operations so calls distribute across endpoints. */
+let roundRobinIndex = 0;
+/**
+ * @name createResilientFacilitatorSigner
+ * @description Wraps one or more facilitator signers with round-robin load balancing,
+ *   per-attempt timeouts, and failover for transient RPC failures.
+ */
+export function createResilientFacilitatorSigner(endpoints) {
+    if (endpoints.length === 0) {
+        throw new Error('At least one facilitator RPC endpoint is required');
+    }
+    const primary = endpoints[0];
+    if (!primary) {
+        throw new Error('At least one facilitator RPC endpoint is required');
+    }
+    return {
+        getAddresses: () => primary.signer.getAddresses(),
+        signTransaction: (transaction, feePayer, network) => primary.signer.signTransaction(transaction, feePayer, network),
+        simulateTransaction: (transaction, network) => runWithRoundRobin(endpoints, 'simulateTransaction', network, endpoint => endpoint.signer.simulateTransaction(transaction, network)),
+        sendTransaction: (transaction, network) => runWithRoundRobin(endpoints, 'sendTransaction', network, endpoint => endpoint.signer.sendTransaction(transaction, network)),
+        confirmTransaction: (signature, network) => runWithRoundRobin(endpoints, 'confirmTransaction', network, endpoint => endpoint.signer.confirmTransaction(signature, network)),
+        simulateTransactionWithInnerInstructions: async (transaction, feePayer, network) => runWithRoundRobin(endpoints, 'simulateTransactionWithInnerInstructions', network, endpoint => {
+            if (!endpoint.signer.simulateTransactionWithInnerInstructions) {
+                throw new Error('simulateTransactionWithInnerInstructions is not available on facilitator signer');
+            }
+            return endpoint.signer.simulateTransactionWithInnerInstructions(transaction, feePayer, network);
+        }),
+        getConfirmedTransactionInnerInstructions: async (signature, network) => runWithRoundRobin(endpoints, 'getConfirmedTransactionInnerInstructions', network, endpoint => {
+            if (!endpoint.signer.getConfirmedTransactionInnerInstructions) {
+                return Promise.resolve(null);
+            }
+            return endpoint.signer.getConfirmedTransactionInnerInstructions(signature, network);
+        }),
+        getTokenAccountBalance: async (tokenAccountAddress, network) => runWithRoundRobin(endpoints, 'getTokenAccountBalance', network, endpoint => {
+            if (!endpoint.signer.getTokenAccountBalance) {
+                return Promise.resolve(null);
+            }
+            return endpoint.signer.getTokenAccountBalance(tokenAccountAddress, network);
+        }),
+        fetchAddressLookupTables: async (lookupTableAddresses, network) => runWithRoundRobin(endpoints, 'fetchAddressLookupTables', network, endpoint => {
+            if (!endpoint.signer.fetchAddressLookupTables) {
+                throw new Error('fetchAddressLookupTables is not available on facilitator signer');
+            }
+            return endpoint.signer.fetchAddressLookupTables(lookupTableAddresses, network);
+        }),
+    };
+}
+/**
+ * @name parseRpcFallbackUrls
+ * @description Parses comma-separated RPC fallback URLs from environment variables or config files.
+ */
+export function parseRpcFallbackUrls(value) {
+    if (!value) {
+        return [];
+    }
+    return uniqueRpcUrls(value.split(',').map(item => item.trim()).filter(Boolean));
+}
+/**
+ * @name uniqueRpcUrls
+ * @description Deduplicates RPC URLs while preserving priority order.
+ */
+export function uniqueRpcUrls(urls) {
+    const seen = new Set();
+    const unique = [];
+    for (const url of urls) {
+        if (seen.has(url)) {
+            continue;
+        }
+        seen.add(url);
+        unique.push(url);
+    }
+    return unique;
+}
+/**
+ * @name isTransientRpcError
+ * @description Returns true when an error is likely caused by endpoint health, lag, throttling, or transport.
+ */
+export function isTransientRpcError(error) {
+    const message = getErrorMessage(error).toLowerCase();
+    if (!message) {
+        return false;
+    }
+    if (message.startsWith('simulation failed:')
+        && !containsAny(message, [
+            'blockhash not found',
+            'minimum context slot',
+            'node is behind',
+            'behind by',
+            'fetch failed',
+            'slot was skipped',
+            'slot skipped',
+        ])) {
+        return false;
+    }
+    return containsAny(message, [
+        'fetch failed',
+        'network request failed',
+        'networkerror',
+        'socket hang up',
+        'connection closed',
+        'connection reset',
+        'connection refused',
+        'econnreset',
+        'econnrefused',
+        'etimedout',
+        'timeout',
+        'eai_again',
+        'too many requests',
+        'rate limit',
+        'forbidden',
+        'unauthorized',
+        '401',
+        '403',
+        '429',
+        '502',
+        '503',
+        '504',
+        'bad gateway',
+        'service unavailable',
+        'gateway timeout',
+        'node is behind',
+        'behind by',
+        'minimum context slot',
+        'slot was skipped',
+        'slot skipped',
+        'blockhash not found',
+        'failed to get latest blockhash',
+        'failed to get recent blockhash',
+    ]);
+}
+async function runWithRoundRobin(endpoints, operation, network, execute) {
+    if (endpoints.length === 0) {
+        throw new Error('No facilitator RPC endpoints configured');
+    }
+    // Advance the round-robin counter — each call starts from the next endpoint.
+    const startIndex = roundRobinIndex % endpoints.length;
+    roundRobinIndex = (roundRobinIndex + 1) % endpoints.length;
+    let lastError;
+    for (let attempt = 0; attempt < endpoints.length; attempt++) {
+        const index = (startIndex + attempt) % endpoints.length;
+        const endpoint = endpoints[index];
+        if (!endpoint)
+            continue;
+        try {
+            // Race the execution against a timeout — if the RPC is slow, we move on immediately.
+            const result = await withTimeout(execute(endpoint), RPC_ATTEMPT_TIMEOUT_MS, endpoint.label, operation);
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+            const hasNext = attempt < endpoints.length - 1;
+            const isTimeout = error instanceof RpcTimeoutError;
+            const isTransient = isTimeout || isTransientRpcError(error);
+            if (!hasNext || !isTransient) {
+                throw error;
+            }
+            logger.warn('x402 facilitator RPC endpoint failed; trying next (round-robin)', {
+                operation,
+                network,
+                endpoint: endpoint.rpcUrl ? redactSensitiveString(endpoint.rpcUrl) : endpoint.label,
+                reason: isTimeout ? 'timeout' : 'transient error',
+                error: isTimeout ? `Timed out after ${RPC_ATTEMPT_TIMEOUT_MS}ms` : getErrorMessage(error),
+            });
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(getErrorMessage(lastError));
+}
+/**
+ * Race a promise against a timeout. If the timeout fires, throw `RpcTimeoutError`.
+ */
+function withTimeout(promise, ms, label, operation) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new RpcTimeoutError(label, operation, ms));
+        }, ms);
+        promise
+            .then((result) => {
+            clearTimeout(timer);
+            resolve(result);
+        })
+            .catch((error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+/**
+ * Custom error for RPC timeouts — treated as transient by the failover loop.
+ */
+class RpcTimeoutError extends Error {
+    label;
+    operation;
+    timeoutMs;
+    constructor(label, operation, timeoutMs) {
+        super(`RPC timeout: ${label} did not respond to ${operation} within ${timeoutMs}ms`);
+        this.name = 'RpcTimeoutError';
+        this.label = label;
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+    }
+}
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return String(error);
+}
+function containsAny(message, needles) {
+    return needles.some(needle => message.includes(needle));
+}
+//# sourceMappingURL=facilitator-rpc-fallback.js.map

package/dist/payments/facilitator-rpc-fallback.js.map

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

package/dist/payments/json-rpc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-rpc.d.ts","sourceRoot":"","sources":["../../src/payments/json-rpc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CA0ChE"}
+{"version":3,"file":"json-rpc.d.ts","sourceRoot":"","sources":["../../src/payments/json-rpc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CA0ChE"}

package/dist/payments/json-rpc.js

@@ -2,6 +2,7 @@
  * @name JsonRpcPaymentIntrospection
  * @description Small JSON-RPC helpers used by the remote monetization gate without coupling payment logic to MCP tools.
  */
+import { canonicalizeToolName } from '../tools/tool-aliases.js';
 /**
  * @name isRecord
  * @description Checks whether a value can be treated as a plain object for protocol introspection.
@@ -39,7 +40,7 @@ export function parseJsonRpcBody(body) {
         }
         toolCalls.push({
             id: request.id,
-            toolName,
+            toolName: canonicalizeToolName(toolName),
             arguments: request.params.arguments,
         });
     }

package/dist/payments/json-rpc.js.map

@@ -1 +1 @@
-{"version":3,"file":"json-rpc.js","sourceRoot":"","sources":["../../src/payments/json-rpc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwCH;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAqB,EAAE,CAAC;IACtC,MAAM,SAAS,GAAkB,EAAE,CAAC;IAEpC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACnE,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAmB;YAC9B,OAAO,EAAE,UAAU,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;YACzD,EAAE,EAAE,OAAO,UAAU,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,UAAU,CAAC,EAAE,KAAK,QAAQ,IAAI,UAAU,CAAC,EAAE,KAAK,IAAI;gBAClG,CAAC,CAAC,UAAU,CAAC,EAAE;gBACf,CAAC,CAAC,SAAS;YACb,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEvB,IAAI,OAAO,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACjE,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QACrC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,SAAS;QACX,CAAC;QAED,SAAS,CAAC,IAAI,CAAC;YACb,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,QAAQ;YACR,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS;SACpC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,QAAQ;QACR,SAAS;QACT,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;QAChD,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;KAC7B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"json-rpc.js","sourceRoot":"","sources":["../../src/payments/json-rpc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAwChE;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAqB,EAAE,CAAC;IACtC,MAAM,SAAS,GAAkB,EAAE,CAAC;IAEpC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACnE,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAmB;YAC9B,OAAO,EAAE,UAAU,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;YACzD,EAAE,EAAE,OAAO,UAAU,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,UAAU,CAAC,EAAE,KAAK,QAAQ,IAAI,UAAU,CAAC,EAAE,KAAK,IAAI;gBAClG,CAAC,CAAC,UAAU,CAAC,EAAE;gBACf,CAAC,CAAC,SAAS;YACb,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEvB,IAAI,OAAO,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACjE,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QACrC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,SAAS;QACX,CAAC;QAED,SAAS,CAAC,IAAI,CAAC;YACb,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,QAAQ,EAAE,oBAAoB,CAAC,QAAQ,CAAC;YACxC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS;SACpC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,QAAQ;QACR,SAAS;QACT,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;QAChD,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;KAC7B,CAAC;AACJ,CAAC"}

package/dist/payments/monetization-gate.d.ts

@@ -10,6 +10,33 @@ import type { PaymentDecision } from './pricing.js';
  * @description Handler invoked after the payment gate has authorized or bypassed a request.
  */
 export type McpRequestHandler = (request: http.IncomingMessage, response: http.ServerResponse, parsedBody?: unknown) => Promise<void>;
+/**
+ * @name McpPaidRequestValidationContext
+ * @description Context provided to hosted transports before a paid request reaches the x402 facilitator.
+ */
+export interface McpPaidRequestValidationContext {
+    request: http.IncomingMessage;
+    parsedBody: unknown;
+    decision: Extract<PaymentDecision, {
+        required: true;
+    }>;
+}
+/**
+ * @name McpPaidRequestValidationFailure
+ * @description JSON-RPC error returned when a paid request cannot safely enter the payment flow.
+ */
+export interface McpPaidRequestValidationFailure {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/**
+ * @name McpMonetizationGateOptions
+ * @description Optional hooks used by HTTP transports to fail closed before facilitator verification.
+ */
+export interface McpMonetizationGateOptions {
+    validatePaidRequest?: (context: McpPaidRequestValidationContext) => McpPaidRequestValidationFailure | undefined;
+}
 /**
  * @name McpMonetizationGate
  * @description Applies x402 payment verification and settlement before forwarding requests to the MCP transport.
@@ -29,8 +56,22 @@ export declare class McpMonetizationGate {
      * @name handle
      * @description Authorizes a request via x402 when required, then forwards it to MCP and settles on success.
      */
-    handle(request: http.IncomingMessage, response: http.ServerResponse, next: McpRequestHandler): Promise<void>;
+    handle(request: http.IncomingMessage, response: http.ServerResponse, next: McpRequestHandler, options?: McpMonetizationGateOptions): Promise<void>;
+    /**
+     * @name handleSignedPayment
+     * @description Verifies a client-supplied x402 payment payload against the original accepted requirements.
+     */
+    private handleSignedPayment;
+    private callFacilitator;
     private buildRequestContext;
+    /**
+     * @name returnX402Challenge
+     * @description Returns a standard HTTP 402 payment challenge for non-MCP clients
+     * (x402scan discovery, curl, health checks). Decodes the PaymentRequired object
+     * from the PAYMENT-REQUIRED header and returns it as the response body so x402
+     * scanners can validate the challenge format.
+     */
+    private returnX402Challenge;
     private forwardAndSettle;
     private settleAndReplay;
 }
@@ -46,7 +87,7 @@ export declare function resolvePaymentNetwork(config: SapMcpConfig): string;
 export declare function normalizePaymentNetwork(network: string): string;
 /**
  * @name buildPaidVirtualPath
- * @description Builds the paid x402 virtual resource path, bound to the exact JSON-RPC request hash.
+ * @description Builds the paid x402 virtual resource path, bound to the canonical MCP method-and-params hash.
  */
 export declare function buildPaidVirtualPath(decision: Extract<PaymentDecision, {
     required: true;

package/dist/payments/monetization-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"monetization-gate.d.ts","sourceRoot":"","sources":["../../src/payments/monetization-gate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAU7B,OAAO,KAAK,EAAE,YAAY,EAA4B,MAAM,kBAAkB,CAAC;AAI/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAIpD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,IAAI,CAAC,eAAe,EAC7B,QAAQ,EAAE,IAAI,CAAC,cAAc,EAC7B,UAAU,CAAC,EAAE,OAAO,KACjB,OAAO,CAAC,IAAI,CAAC,CAAC;AA2BnB;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C,OAAO;IAWP;;;OAGG;WACiB,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IA6C7F;;;OAGG;IACU,MAAM,CACjB,OAAO,EAAE,IAAI,CAAC,eAAe,EAC7B,QAAQ,EAAE,IAAI,CAAC,cAAc,EAC7B,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC;IA4DhB,OAAO,CAAC,mBAAmB;YAmBb,gBAAgB;YAyDhB,eAAe;CAqC9B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAclE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAY/D;AA8ED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAGxH"}
+{"version":3,"file":"monetization-gate.d.ts","sourceRoot":"","sources":["../../src/payments/monetization-gate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAiB7B,OAAO,KAAK,EAAE,YAAY,EAA4B,MAAM,kBAAkB,CAAC;AAI/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAKpD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,IAAI,CAAC,eAAe,EAC7B,QAAQ,EAAE,IAAI,CAAC,cAAc,EAC7B,UAAU,CAAC,EAAE,OAAO,KACjB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,+BAA+B,KAAK,+BAA+B,GAAG,SAAS,CAAC;CACjH;AA+CD;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C,OAAO;IAWP;;;OAGG;WACiB,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IA6C7F;;;OAGG;IACU,MAAM,CACjB,OAAO,EAAE,IAAI,CAAC,eAAe,EAC7B,QAAQ,EAAE,IAAI,CAAC,cAAc,EAC7B,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC;IAiOhB;;;OAGG;YACW,mBAAmB;YAgKnB,eAAe;IAa7B,OAAO,CAAC,mBAAmB;IAoB3B;;;;;;OAMG;YACW,mBAAmB;YA8CnB,gBAAgB;YAyDhB,eAAe;CAsD9B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAclE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAY/D;AAgFD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAGxH"}