@vinaystwt/xmpp-router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xMPP contributors
+
+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/dist/router/src/index.d.ts

@@ -0,0 +1,23 @@
+import type { PaymentChallenge, RouteContext, RouteDecision, RouteKind, ServiceCatalogEntry, WorkflowEstimateResult, WorkflowEstimateStep } from '@xmpp/types';
+export declare function resolveCatalogEntry(input: RouteContext): ServiceCatalogEntry;
+export declare function estimateRouteCost(input: {
+    route: RouteKind;
+    url: string;
+    method?: string;
+    serviceId?: string;
+    projectedRequests?: number;
+    hasReusableSession?: boolean;
+}): number;
+export declare function getServiceCatalog(): ServiceCatalogEntry[];
+export declare function getServiceCatalogEntry(serviceId: string): ServiceCatalogEntry | null;
+export declare function createRouter(): {
+    preview(input: RouteContext): Promise<RouteDecision>;
+    chooseFromChallenge(input: RouteContext & {
+        challenge: PaymentChallenge;
+        hasReusableSession?: boolean;
+    }): Promise<RouteDecision>;
+    explain(input: RouteContext & {
+        hasReusableSession?: boolean;
+    }): RouteDecision;
+    estimateWorkflow(steps: WorkflowEstimateStep[]): WorkflowEstimateResult;
+};

package/dist/router/src/index.js

@@ -0,0 +1,432 @@
+const serviceCatalog = [
+    {
+        serviceId: 'research-api',
+        displayName: 'Research API',
+        description: 'Low-cost research lookups optimized for exact one-off payments.',
+        baseUrl: 'http://localhost:4101',
+        capabilities: {
+            x402: true,
+            mppCharge: false,
+            mppSession: false,
+        },
+        pricing: {
+            x402PerCallUsd: 0.01,
+            mppChargePerCallUsd: 0.03,
+            mppSessionOpenUsd: 0.005,
+            mppSessionPerCallUsd: 0.005,
+        },
+        routingHints: {
+            breakEvenCalls: 4,
+            streamingPreferred: false,
+            preferredSingleCall: 'x402',
+        },
+    },
+    {
+        serviceId: 'market-api',
+        displayName: 'Market API',
+        description: 'Premium market data endpoint exposed through MPP HTTP payment auth.',
+        baseUrl: 'http://localhost:4102',
+        capabilities: {
+            x402: false,
+            mppCharge: true,
+            mppSession: false,
+        },
+        pricing: {
+            x402PerCallUsd: 0.04,
+            mppChargePerCallUsd: 0.03,
+            mppSessionOpenUsd: 0.01,
+            mppSessionPerCallUsd: 0.01,
+        },
+        routingHints: {
+            breakEvenCalls: 3,
+            streamingPreferred: false,
+            preferredSingleCall: 'mpp-charge',
+        },
+    },
+    {
+        serviceId: 'stream-api',
+        displayName: 'Stream API',
+        description: 'Repeated tick stream designed to amortize cost over an MPP session.',
+        baseUrl: 'http://localhost:4103',
+        capabilities: {
+            x402: false,
+            mppCharge: false,
+            mppSession: true,
+        },
+        pricing: {
+            x402PerCallUsd: 0.01,
+            mppChargePerCallUsd: 0.03,
+            mppSessionOpenUsd: 0.005,
+            mppSessionPerCallUsd: 0.005,
+        },
+        routingHints: {
+            breakEvenCalls: 4,
+            streamingPreferred: true,
+            preferredSingleCall: 'x402',
+        },
+    },
+];
+const catalogByServiceId = new Map(serviceCatalog.map((entry) => [entry.serviceId, entry]));
+const discoveredCatalog = new Map();
+const discoveryTimestamps = new Map();
+const discoveryInFlight = new Map();
+const DISCOVERY_TTL_MS = 5 * 60 * 1000;
+function roundUsd(value) {
+    return Math.round(value * 1000) / 1000;
+}
+function fallbackServiceCatalogEntry(input) {
+    const hostname = new URL(input.url).host;
+    return {
+        serviceId: input.serviceId ?? hostname,
+        displayName: input.serviceId ?? hostname,
+        description: 'Fallback catalog entry inferred from request URL.',
+        baseUrl: `${new URL(input.url).origin}`,
+        source: 'fallback',
+        capabilities: {
+            x402: true,
+            mppCharge: true,
+            mppSession: true,
+        },
+        pricing: {
+            x402PerCallUsd: 0.01,
+            mppChargePerCallUsd: 0.03,
+            mppSessionOpenUsd: 0.005,
+            mppSessionPerCallUsd: 0.005,
+        },
+        routingHints: {
+            breakEvenCalls: 4,
+            streamingPreferred: false,
+            preferredSingleCall: 'x402',
+        },
+    };
+}
+function getProjectedRequests(input) {
+    return Math.max(1, input.projectedRequests ?? 1);
+}
+function mergeCatalogEntry(base, discovery, input) {
+    const modes = new Set(discovery.paymentModes ?? []);
+    const pricingHints = discovery.pricingHints ?? {};
+    const merged = {
+        ...base,
+        serviceId: discovery.serviceId ?? base.serviceId ?? input.serviceId ?? base.serviceId,
+        displayName: base.displayName,
+        description: base.description,
+        baseUrl: new URL(input.url).origin,
+        source: base.source === 'fallback' ? 'discovered' : 'hybrid',
+        capabilities: {
+            x402: modes.has('x402') || base.capabilities.x402,
+            mppCharge: modes.has('mpp-charge') || modes.has('MPP charge') || base.capabilities.mppCharge,
+            mppSession: modes.has('mpp-session') || modes.has('MPP session') || base.capabilities.mppSession,
+        },
+        pricing: {
+            x402PerCallUsd: typeof pricingHints.x402PerCallUsd === 'number'
+                ? pricingHints.x402PerCallUsd
+                : typeof pricingHints.perCallUsd === 'number' && modes.has('x402')
+                    ? pricingHints.perCallUsd
+                    : base.pricing.x402PerCallUsd,
+            mppChargePerCallUsd: typeof pricingHints.mppChargePerCallUsd === 'number'
+                ? pricingHints.mppChargePerCallUsd
+                : typeof pricingHints.perCallUsd === 'number' && (modes.has('mpp-charge') || modes.has('MPP charge'))
+                    ? pricingHints.perCallUsd
+                    : base.pricing.mppChargePerCallUsd,
+            mppSessionOpenUsd: typeof pricingHints.mppSessionOpenUsd === 'number'
+                ? pricingHints.mppSessionOpenUsd
+                : typeof pricingHints.sessionOpenUsd === 'number'
+                    ? pricingHints.sessionOpenUsd
+                    : base.pricing.mppSessionOpenUsd,
+            mppSessionPerCallUsd: typeof pricingHints.mppSessionPerCallUsd === 'number'
+                ? pricingHints.mppSessionPerCallUsd
+                : typeof pricingHints.perCallUsd === 'number' &&
+                    (modes.has('mpp-session') || modes.has('MPP session'))
+                    ? pricingHints.perCallUsd
+                    : base.pricing.mppSessionPerCallUsd,
+        },
+        routingHints: {
+            breakEvenCalls: typeof pricingHints.breakEvenRequests === 'number'
+                ? Math.max(1, Math.round(pricingHints.breakEvenRequests))
+                : base.routingHints.breakEvenCalls,
+            streamingPreferred: typeof pricingHints.streamingPreferred === 'boolean'
+                ? pricingHints.streamingPreferred
+                : base.routingHints.streamingPreferred,
+            preferredSingleCall: pricingHints.preferredSingleCall === 'mpp-charge'
+                ? 'mpp-charge'
+                : pricingHints.preferredSingleCall === 'x402'
+                    ? 'x402'
+                    : base.routingHints.preferredSingleCall,
+        },
+    };
+    return merged;
+}
+export function resolveCatalogEntry(input) {
+    const discovered = (input.serviceId ? discoveredCatalog.get(input.serviceId) : undefined) ??
+        [...discoveredCatalog.values()].find((entry) => input.url.startsWith(entry.baseUrl));
+    if (discovered) {
+        return discovered;
+    }
+    return ((input.serviceId ? catalogByServiceId.get(input.serviceId) : undefined) ??
+        serviceCatalog.find((entry) => input.url.startsWith(entry.baseUrl)) ??
+        fallbackServiceCatalogEntry(input));
+}
+async function discoverCatalogEntry(input) {
+    const existing = resolveCatalogEntry(input);
+    if (existing.source !== 'fallback') {
+        return existing;
+    }
+    const cacheKey = input.serviceId ?? new URL(input.url).origin;
+    const cachedAt = discoveryTimestamps.get(cacheKey);
+    if (cachedAt && Date.now() - cachedAt < DISCOVERY_TTL_MS) {
+        return existing;
+    }
+    const inflight = discoveryInFlight.get(cacheKey);
+    if (inflight) {
+        return (await inflight) ?? existing;
+    }
+    const discoveryPromise = (async () => {
+        try {
+            const response = await fetch(new URL('/.well-known/xmpp.json', input.url));
+            if (!response.ok) {
+                return null;
+            }
+            const discovery = (await response.json());
+            const merged = mergeCatalogEntry(existing, discovery, input);
+            discoveredCatalog.set(merged.serviceId, merged);
+            discoveryTimestamps.set(cacheKey, Date.now());
+            return merged;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            discoveryInFlight.delete(cacheKey);
+        }
+    })();
+    discoveryInFlight.set(cacheKey, discoveryPromise);
+    return (await discoveryPromise) ?? existing;
+}
+function getNaiveX402Cost(entry, projectedRequests) {
+    return projectedRequests * entry.pricing.x402PerCallUsd;
+}
+function getEstimatedCost(route, entry, projectedRequests, hasReusableSession = false) {
+    if (route === 'x402') {
+        return getNaiveX402Cost(entry, projectedRequests);
+    }
+    if (route === 'mpp-charge') {
+        return projectedRequests * entry.pricing.mppChargePerCallUsd;
+    }
+    const openCost = hasReusableSession || route === 'mpp-session-reuse' ? 0 : entry.pricing.mppSessionOpenUsd;
+    return openCost + projectedRequests * entry.pricing.mppSessionPerCallUsd;
+}
+export function estimateRouteCost(input) {
+    const context = normalizeContext(input);
+    const entry = resolveCatalogEntry(context);
+    return roundUsd(getEstimatedCost(input.route, entry, getProjectedRequests(context), input.hasReusableSession));
+}
+function supportsRoute(entry, route) {
+    if (route === 'x402') {
+        return entry.capabilities.x402;
+    }
+    if (route === 'mpp-charge') {
+        return entry.capabilities.mppCharge;
+    }
+    return entry.capabilities.mppSession;
+}
+function scoreRoute(input) {
+    const { entry, route, projectedRequests, streaming, hasReusableSession } = input;
+    const supported = supportsRoute(entry, route);
+    const estimatedTotalUsd = roundUsd(getEstimatedCost(route, entry, projectedRequests, hasReusableSession));
+    const naiveX402Cost = roundUsd(getNaiveX402Cost(entry, projectedRequests));
+    const savingsVsNaiveUsd = roundUsd(naiveX402Cost - estimatedTotalUsd);
+    const reasons = [];
+    let totalScore = supported ? 0.2 : -1;
+    if (!supported) {
+        reasons.push('Service catalog does not advertise this payment mode.');
+        return {
+            route,
+            supported,
+            estimatedTotalUsd,
+            savingsVsNaiveUsd,
+            totalScore,
+            reasons,
+        };
+    }
+    const costDeltaScore = Math.max(-0.2, Math.min(0.45, savingsVsNaiveUsd * 8));
+    totalScore += costDeltaScore;
+    if (costDeltaScore > 0) {
+        reasons.push(`Estimated ${route} cost is $${estimatedTotalUsd.toFixed(3)}, saving about $${Math.abs(savingsVsNaiveUsd).toFixed(3)} versus naive x402.`);
+    }
+    else if (costDeltaScore < 0) {
+        reasons.push(`Estimated ${route} cost is higher than x402 for this request shape.`);
+    }
+    else {
+        reasons.push('Estimated protocol cost is roughly neutral against naive x402.');
+    }
+    if (route === 'x402') {
+        if (projectedRequests === 1 && !streaming) {
+            totalScore += 0.28;
+            reasons.push('Exact settlement fits a single low-friction call.');
+        }
+        if (entry.routingHints.preferredSingleCall === 'x402') {
+            totalScore += 0.1;
+            reasons.push('Service catalog marks x402 as the preferred one-shot route.');
+        }
+        if (projectedRequests >= entry.routingHints.breakEvenCalls) {
+            totalScore -= 0.18;
+            reasons.push('Projected repeat volume weakens x402 because fees do not amortize.');
+        }
+    }
+    if (route === 'mpp-charge') {
+        if (projectedRequests === 1) {
+            totalScore += 0.2;
+            reasons.push('MPP charge fits premium one-shot HTTP payment auth.');
+        }
+        if (entry.routingHints.preferredSingleCall === 'mpp-charge') {
+            totalScore += 0.14;
+            reasons.push('Service catalog marks MPP charge as the preferred single-call route.');
+        }
+        if (projectedRequests >= entry.routingHints.breakEvenCalls) {
+            totalScore -= 0.08;
+            reasons.push('Repeated calls reduce the relative advantage of one-shot charge flows.');
+        }
+    }
+    if (route === 'mpp-session-open' || route === 'mpp-session-reuse') {
+        if (streaming || entry.routingHints.streamingPreferred) {
+            totalScore += 0.24;
+            reasons.push('Streaming or repeated access strongly favors session economics.');
+        }
+        if (projectedRequests >= entry.routingHints.breakEvenCalls) {
+            totalScore += 0.18;
+            reasons.push(`Projected usage crosses the ${entry.routingHints.breakEvenCalls}-call break-even point.`);
+        }
+        else {
+            totalScore -= 0.1;
+            reasons.push('Projected usage is below the session break-even threshold.');
+        }
+        if (route === 'mpp-session-reuse' || hasReusableSession) {
+            totalScore += 0.16;
+            reasons.push('Reusable session removes the channel open cost.');
+        }
+        else {
+            reasons.push('First session call still carries the channel open cost.');
+        }
+    }
+    return {
+        route,
+        supported,
+        estimatedTotalUsd,
+        savingsVsNaiveUsd,
+        totalScore: roundUsd(totalScore),
+        reasons,
+    };
+}
+function sortBreakdown(left, right) {
+    if (right.totalScore !== left.totalScore) {
+        return right.totalScore - left.totalScore;
+    }
+    return left.estimatedTotalUsd - right.estimatedTotalUsd;
+}
+function chooseBestDecision(entry, projectedRequests, breakdown) {
+    const best = [...breakdown].sort(sortBreakdown)[0];
+    return {
+        route: best.route,
+        reason: best.reasons[0] ?? 'xMPP selected the highest scoring route.',
+        score: best.totalScore,
+        projectedRequests,
+        estimatedTotalUsd: best.estimatedTotalUsd,
+        savingsVsNaiveUsd: best.savingsVsNaiveUsd,
+        service: entry,
+        breakdown: [...breakdown].sort(sortBreakdown),
+    };
+}
+function explainPreview(input) {
+    const entry = resolveCatalogEntry(input);
+    const projectedRequests = getProjectedRequests(input);
+    const streaming = Boolean(input.streaming);
+    const breakdown = [
+        'x402',
+        'mpp-charge',
+        input.hasReusableSession ? 'mpp-session-reuse' : 'mpp-session-open',
+    ].map((route) => scoreRoute({
+        entry,
+        route,
+        projectedRequests,
+        streaming,
+        hasReusableSession: input.hasReusableSession,
+    }));
+    return chooseBestDecision(entry, projectedRequests, breakdown);
+}
+export function getServiceCatalog() {
+    const merged = new Map(serviceCatalog.map((entry) => [entry.serviceId, entry]));
+    for (const entry of discoveredCatalog.values()) {
+        merged.set(entry.serviceId, entry);
+    }
+    return [...merged.values()];
+}
+export function getServiceCatalogEntry(serviceId) {
+    return discoveredCatalog.get(serviceId) ?? catalogByServiceId.get(serviceId) ?? null;
+}
+function normalizeContext(input) {
+    return {
+        ...input,
+        method: input.method ?? 'GET',
+    };
+}
+export function createRouter() {
+    return {
+        async preview(input) {
+            await discoverCatalogEntry(input);
+            return explainPreview(input);
+        },
+        async chooseFromChallenge(input) {
+            await discoverCatalogEntry(input);
+            if (input.challenge.kind === 'mpp-session') {
+                return explainPreview({
+                    ...input,
+                    hasReusableSession: input.hasReusableSession,
+                    streaming: input.streaming ?? true,
+                });
+            }
+            if (input.challenge.kind === 'mpp-charge') {
+                const decision = explainPreview(input);
+                return {
+                    ...decision,
+                    route: 'mpp-charge',
+                    reason: 'MPP charge challenge detected and the service is requesting one-shot auth.',
+                };
+            }
+            const decision = explainPreview(input);
+            return {
+                ...decision,
+                route: 'x402',
+                reason: 'x402 challenge detected and exact settlement is available immediately.',
+            };
+        },
+        explain(input) {
+            return explainPreview(input);
+        },
+        estimateWorkflow(steps) {
+            const breakdown = steps.map((step) => {
+                const decision = explainPreview(normalizeContext(step));
+                return {
+                    serviceId: decision.service?.serviceId ?? step.serviceId ?? new URL(step.url).host,
+                    displayName: decision.service?.displayName ?? step.serviceId ?? new URL(step.url).host,
+                    route: decision.route,
+                    projectedRequests: Math.max(1, step.projectedRequests),
+                    estimatedCostUsd: roundUsd(decision.estimatedTotalUsd ?? 0),
+                    savingsVsNaiveUsd: roundUsd(decision.savingsVsNaiveUsd ?? 0),
+                    reason: decision.reason,
+                };
+            });
+            const totalEstimatedCostUsd = roundUsd(breakdown.reduce((sum, item) => sum + item.estimatedCostUsd, 0));
+            const naiveX402CostUsd = roundUsd(steps.reduce((sum, step) => {
+                const entry = resolveCatalogEntry(normalizeContext(step));
+                return sum + getNaiveX402Cost(entry, Math.max(1, step.projectedRequests));
+            }, 0));
+            return {
+                totalEstimatedCostUsd,
+                naiveX402CostUsd,
+                savingsVsNaiveUsd: roundUsd(naiveX402CostUsd - totalEstimatedCostUsd),
+                breakdown,
+            };
+        },
+    };
+}

package/dist/router/src/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/router/src/index.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { createRouter, getServiceCatalogEntry } from './index.js';
+describe('router', () => {
+    const router = createRouter();
+    it('prefers x402 for low-volume calls', async () => {
+        const result = await router.preview({
+            url: 'http://localhost:4101/research?q=stellar',
+            method: 'GET',
+            projectedRequests: 1,
+            serviceId: 'research-api',
+        });
+        expect(result.route).toBe('x402');
+        expect(result.service?.serviceId).toBe('research-api');
+        expect(result.breakdown?.[0]?.route).toBe('x402');
+    });
+    it('prefers mpp charge for market-api single calls', async () => {
+        const result = await router.preview({
+            url: 'http://localhost:4102/quote?symbol=XLM',
+            method: 'GET',
+            projectedRequests: 1,
+            serviceId: 'market-api',
+        });
+        expect(result.route).toBe('mpp-charge');
+        expect(result.reason.toLowerCase()).toContain('saving');
+    });
+    it('prefers mpp session for repeated calls', async () => {
+        const result = await router.preview({
+            url: 'http://localhost:4103/stream/tick',
+            method: 'GET',
+            projectedRequests: 5,
+            serviceId: 'stream-api',
+            streaming: true,
+        });
+        expect(result.route).toBe('mpp-session-open');
+        expect(result.breakdown?.find((item) => item.route === 'mpp-session-open')?.supported).toBe(true);
+    });
+    it('promotes reusable session when one already exists', async () => {
+        const result = router.explain({
+            url: 'http://localhost:4103/stream/tick',
+            method: 'GET',
+            projectedRequests: 5,
+            serviceId: 'stream-api',
+            streaming: true,
+            hasReusableSession: true,
+        });
+        expect(result.route).toBe('mpp-session-reuse');
+    });
+    it('estimates a mixed workflow against naive x402 spend', () => {
+        const estimate = router.estimateWorkflow([
+            {
+                url: 'http://localhost:4101/research?q=stellar',
+                serviceId: 'research-api',
+                projectedRequests: 1,
+            },
+            {
+                url: 'http://localhost:4102/quote?symbol=XLM',
+                serviceId: 'market-api',
+                projectedRequests: 1,
+            },
+            {
+                url: 'http://localhost:4103/stream/tick',
+                serviceId: 'stream-api',
+                projectedRequests: 5,
+                streaming: true,
+            },
+        ]);
+        expect(estimate.breakdown).toHaveLength(3);
+        expect(estimate.totalEstimatedCostUsd).toBeGreaterThan(0);
+        expect(estimate.savingsVsNaiveUsd).toBeGreaterThanOrEqual(0);
+    });
+    it('exposes catalog entries for docs and operator views', () => {
+        const entry = getServiceCatalogEntry('market-api');
+        expect(entry?.displayName).toBe('Market API');
+        expect(entry?.capabilities.mppCharge).toBe(true);
+    });
+});

package/dist/types/src/index.d.ts

@@ -0,0 +1,343 @@
+export type RouteKind = 'x402' | 'mpp-charge' | 'mpp-session-open' | 'mpp-session-reuse';
+export type PaymentExecutionMode = 'mock' | 'testnet';
+export type PaymentExecutionStatus = 'mock-paid' | 'ready-for-testnet' | 'settled-testnet' | 'missing-config';
+export type RouteContext = {
+    url: string;
+    method: string;
+    serviceId?: string;
+    projectedRequests?: number;
+    streaming?: boolean;
+};
+export type ServiceCatalogEntry = {
+    serviceId: string;
+    displayName: string;
+    description: string;
+    baseUrl: string;
+    source?: 'static' | 'discovered' | 'hybrid' | 'fallback';
+    capabilities: {
+        x402: boolean;
+        mppCharge: boolean;
+        mppSession: boolean;
+    };
+    pricing: {
+        x402PerCallUsd: number;
+        mppChargePerCallUsd: number;
+        mppSessionOpenUsd: number;
+        mppSessionPerCallUsd: number;
+    };
+    routingHints: {
+        breakEvenCalls: number;
+        streamingPreferred: boolean;
+        preferredSingleCall: Extract<RouteKind, 'x402' | 'mpp-charge'>;
+    };
+};
+export type RouteScoreBreakdown = {
+    route: RouteKind;
+    supported: boolean;
+    estimatedTotalUsd: number;
+    savingsVsNaiveUsd: number;
+    totalScore: number;
+    reasons: string[];
+};
+export type RouteDecision = {
+    route: RouteKind;
+    reason: string;
+    score: number;
+    projectedRequests?: number;
+    estimatedTotalUsd?: number;
+    savingsVsNaiveUsd?: number;
+    service?: ServiceCatalogEntry;
+    breakdown?: RouteScoreBreakdown[];
+};
+export type ChallengeKind = 'x402' | 'mpp-charge' | 'mpp-session';
+export type PaymentChallenge = {
+    kind: ChallengeKind;
+    service: string;
+    amountUsd: number;
+    asset: 'USDC_TESTNET';
+    retryHeaderName: string;
+    retryHeaderValue: string;
+    sessionId?: string;
+};
+export type XmppFetchOptions = Omit<RouteContext, 'url' | 'method'> & {
+    agentId?: string;
+    maxAutoPayUsd?: number;
+    idempotencyKey?: string;
+};
+export type XmppAgentProfile = {
+    agentId: string;
+    displayName: string;
+    role: 'shared' | 'research' | 'market';
+    description: string;
+    dailyBudgetUsd: number;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    autopayMethods: string[];
+    enabled?: boolean;
+    policySource?: 'local' | 'contract' | 'fallback' | 'merged';
+};
+export type XmppSignedReceipt = {
+    receiptId: string;
+    issuedAt: string;
+    network: string;
+    agent: string;
+    serviceId: string;
+    url: string;
+    method: string;
+    route: RouteKind;
+    amountUsd: number;
+    txHash?: string;
+    explorerUrl?: string;
+    paymentReference?: string;
+    signature: string;
+};
+export type XmppSmartAccountExecution = {
+    configured: boolean;
+    preferred: boolean;
+    supported: boolean;
+    used: boolean;
+    contractId?: string | null;
+    fallbackReason?: string;
+};
+export type PaymentExecutionMetadata = {
+    mode: PaymentExecutionMode;
+    status: PaymentExecutionStatus;
+    route: RouteKind;
+    receiptId: string;
+    missingConfig?: string[];
+    evidenceHeaders?: Record<string, string>;
+    signedReceipt?: XmppSignedReceipt;
+    settlementStrategy?: 'keypair' | 'smart-account' | 'keypair-fallback';
+    executionNote?: string;
+    feeSponsored?: boolean;
+    feeSponsorPublicKey?: string;
+    feeBumpPublicKey?: string;
+    smartAccount?: XmppSmartAccountExecution;
+};
+export type PolicyDecision = {
+    allowed: boolean;
+    reason: string;
+    code: 'allowed' | 'blocked-domain' | 'blocked-path' | 'blocked-method' | 'blocked-service' | 'blocked-agent' | 'blocked-budget' | 'blocked-idempotency' | 'paused';
+    source?: 'local' | 'contract' | 'fallback';
+};
+export type PaymentExecutionResult = {
+    response: Response;
+    metadata: PaymentExecutionMetadata;
+};
+export type XmppFetchMetadata = {
+    route: RouteKind;
+    challenge?: PaymentChallenge;
+    retried: boolean;
+    execution?: PaymentExecutionMetadata;
+    policy?: PolicyDecision;
+    budget?: XmppBudgetSnapshot;
+    idempotentReplay?: boolean;
+};
+export type XmppSessionRecord = {
+    sessionId: string;
+    serviceId: string;
+    agent: string;
+    channelContractId: string;
+    route: string;
+    status: string;
+    totalAmountUsdCents: number;
+    callCount: number;
+    lastReceiptId: string;
+    updatedAtLedger: number;
+};
+export type WorkflowEstimateStep = {
+    url: string;
+    method?: string;
+    serviceId?: string;
+    projectedRequests: number;
+    streaming?: boolean;
+};
+export type WorkflowEstimateLineItem = {
+    serviceId: string;
+    displayName: string;
+    route: RouteKind;
+    projectedRequests: number;
+    estimatedCostUsd: number;
+    savingsVsNaiveUsd: number;
+    reason: string;
+};
+export type WorkflowEstimateResult = {
+    totalEstimatedCostUsd: number;
+    naiveX402CostUsd: number;
+    savingsVsNaiveUsd: number;
+    breakdown: WorkflowEstimateLineItem[];
+};
+export type XmppBudgetSnapshot = {
+    agentId: string;
+    agentDisplayName: string;
+    agentSpentThisSessionUsd: number;
+    agentRemainingDailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    callsThisService: number;
+    projectedCostIfRepeated5xUsd: number;
+    recommendation: string;
+};
+export type XmppRouteEvent = {
+    id: string;
+    timestamp: string;
+    agentId: string;
+    url: string;
+    method: string;
+    serviceId: string;
+    route: RouteKind;
+    status: 'settled' | 'denied' | 'preview';
+    amountUsd: number;
+    projectedRequests: number;
+    policyCode?: PolicyDecision['code'];
+    receiptId?: string;
+    txHash?: string;
+    explorerUrl?: string;
+    sessionId?: string;
+    signedReceipt?: XmppSignedReceipt;
+    feeSponsored?: boolean;
+    feeSponsorPublicKey?: string;
+    settlementStrategy?: PaymentExecutionMetadata['settlementStrategy'];
+    executionNote?: string;
+};
+export type XmppAgentStateSummary = {
+    agentId: string;
+    displayName: string;
+    role: XmppAgentProfile['role'];
+    description: string;
+    dailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    routeCounts: Record<RouteKind, number>;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    enabled?: boolean;
+    policySource?: XmppAgentProfile['policySource'];
+    autopayMethods?: string[];
+};
+export type XmppAgentPolicySnapshot = {
+    agentId: string;
+    enabled: boolean;
+    dailyBudgetUsd: number;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    autopayMethods: string[];
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppContractTreasurySnapshot = {
+    sharedTreasuryUsd: number;
+    totalSpentUsd: number;
+    remainingUsd: number;
+    paymentCount: number;
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppContractAgentTreasuryState = {
+    agentId: string;
+    spentUsd: number;
+    paymentCount: number;
+    lastServiceId: string;
+    lastRoute: string;
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppOperatorState = {
+    sharedTreasuryUsd: number;
+    sharedTreasuryRemainingUsd: number;
+    dailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    sessionSavingsUsd: number;
+    routeCounts: Record<RouteKind, number>;
+    serviceSpendUsd: Record<string, number>;
+    serviceCallCounts: Record<string, number>;
+    agentProfiles: XmppAgentProfile[];
+    agentStates: XmppAgentStateSummary[];
+    contractAgentPolicies?: XmppAgentPolicySnapshot[];
+    contractTreasury?: XmppContractTreasurySnapshot | null;
+    contractAgentTreasuryStates?: XmppContractAgentTreasuryState[];
+    openSessions: Array<Pick<XmppSessionRecord, 'sessionId' | 'serviceId' | 'callCount'>>;
+    recentEvents: XmppRouteEvent[];
+};
+export type XmppReceiptVerificationResult = {
+    valid: boolean;
+    agent: string;
+    receiptId: string;
+};
+export type XmppWalletInfo = {
+    connected: boolean;
+    paymentExecutionMode: PaymentExecutionMode;
+    network: string;
+    rpcUrl: string;
+    agentPublicKey: string | null;
+    settlementStrategy: 'smart-account-ready' | 'smart-account-x402-preferred' | 'smart-account-partial-fallback' | 'keypair-live';
+    smartAccount: {
+        ready: boolean;
+        mode: 'inactive' | 'x402-only' | 'full';
+        routeCoverage: 'inactive' | 'x402-only';
+        demoReady: boolean;
+        guardedFallback: boolean;
+        contractId: string | null;
+        wasmHash: string;
+        webauthnVerifierAddress: string;
+        ed25519VerifierAddress: string;
+        spendingLimitPolicyAddress: string;
+        thresholdPolicyAddress: string;
+        preferredRoutes: RouteKind[];
+        fallbackRoutes: RouteKind[];
+        supportedRoutes: RouteKind[];
+        unsupportedRoutes: RouteKind[];
+        unsupportedReason: string | null;
+        configuredMaxTransactionFeeStroops: number;
+        effectiveMaxTransactionFeeStroops: number;
+        feeFloorApplied: boolean;
+        preflightFailures: string[];
+        coverageMessage: string;
+        message: string;
+        operatorNotes: string[];
+    };
+    feeSponsorship: {
+        enabled: boolean;
+        available: boolean;
+        mppChargeEnabled: boolean;
+        mppSessionEnabled: boolean;
+        sponsorPublicKey: string | null;
+        feeBumpPublicKey: string | null;
+        message: string;
+    };
+    missingSecrets: string[];
+    message: string;
+};
+export type XmppHealthStatus = {
+    ok: boolean;
+    service: string;
+    network: string;
+    paymentExecutionMode: PaymentExecutionMode;
+    services: Record<string, string>;
+    smartAccount: {
+        configured: boolean;
+        routeCoverage: 'inactive' | 'x402-only';
+        x402Preferred: boolean;
+        mppFallback: boolean;
+        demoReady: boolean;
+        guardedFallback: boolean;
+        unsupportedRoutes: RouteKind[];
+        unsupportedReason: string | null;
+        configuredMaxTransactionFeeStroops: number;
+        effectiveMaxTransactionFeeStroops: number;
+        feeFloorApplied: boolean;
+        preflightFailures: string[];
+    };
+};
+export type XmppCatalogResponse = {
+    services: ServiceCatalogEntry[];
+};
+export type XmppPolicyPreviewResponse = {
+    policy: PolicyDecision;
+    routePreview: RouteDecision;
+};
+export type XmppGatewayFetchResponse = {
+    status: number;
+    routePreview: RouteDecision;
+    payment?: XmppFetchMetadata;
+    responseHeaders: Record<string, string>;
+    body: unknown;
+};

package/dist/types/src/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@vinaystwt/xmpp-router",
+  "version": "0.1.0",
+  "description": "Cost-aware route scoring and workflow estimation across x402, MPP charge, and MPP session flows.",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/router/src/index.js",
+  "types": "dist/router/src/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "homepage": "https://github.com/Vinaystwt/xMPP#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vinaystwt/xMPP.git",
+    "directory": "packages/router"
+  },
+  "bugs": {
+    "url": "https://github.com/Vinaystwt/xMPP/issues"
+  },
+  "keywords": [
+    "xmpp",
+    "router",
+    "stellar",
+    "x402",
+    "mpp"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/router/src/index.d.ts",
+      "import": "./dist/router/src/index.js",
+      "default": "./dist/router/src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@vinaystwt/xmpp-types": "0.1.0"
+  }
+}