@envarai/envarpay 0.2.0-alpha.18 → 0.2.0-alpha.19

package/dist/commerce/card.js

@@ -14,7 +14,7 @@ export function createOfferCard(config, serviceId, offerId, origin) {
     if (!service || !offer)
         throw new CommerceError('offer_not_found', 'Service offer not found');
     const profile = offer.paymentProfile ? config.paymentProfiles[offer.paymentProfile] : null;
-    const payment = profile?.adapter === 'x402' ? { adapter: 'x402', network: profile.network, asset: profile.asset, payTo: profile.payTo } : profile ? { adapter: 'mpp', method: 'stripe', intent: 'charge', currency: profile.currency } : null;
+    const payment = profile?.adapter === 'x402' ? { adapter: 'x402', network: profile.network, asset: profile.asset, payTo: profile.payTo } : profile?.adapter === 'envar_balance' ? { adapter: 'envar_balance', currency: 'usd', accountRef: profile.accountRef } : profile ? { adapter: 'mpp', method: 'stripe', intent: 'charge', currency: profile.currency } : null;
     return AgentCard.fromJSON({
         name: service.name,
         description: `Deliverables: ${service.contract.deliverables.join(', ')}`,

package/dist/commerce/cli.js

@@ -17,6 +17,7 @@ import { EnvarSellerRuntime, PinnedUpstreams, restoreEnvarConfig } from './envar
 import { listenCommerce } from './http.js';
 import { CredentialVault } from './vault.js';
 import { X402Gate } from './x402.js';
+import { EnvarBalanceGate } from './envar-balance.js';
 import { evmReceiptVerifier, evmSettlementRecovery } from './chain.js';
 import { CommerceError } from './types.js';
 import { createNativeSkillExecutor } from './native-skills.js';
@@ -311,6 +312,11 @@ async function run() {
         gates.mpp = gate;
         stripeRecipientFor = ref => gate.merchantRecipient(ref);
     }
+    if (protocols.has('envar_balance')) {
+        if (!integration)
+            throw new CommerceError('balance_configuration', 'Envar balance requires an authenticated Envar seller integration');
+        gates.envar_balance = new EnvarBalanceGate({ store, vault: vault, claim: args => integration.claimBalancePayment(args) });
+    }
     const nativeSkills = secrets.skills ? createNativeSkillExecutor(secrets.skills, values.origin, config.agent.name) : undefined;
     const discovery = secrets.skills?.discovery?.enabledFromWeb ? new SkillDiscovery(secrets.skills, secrets.skills.discovery, values.origin) : undefined;
     if (nativeSkills)
@@ -325,6 +331,8 @@ async function run() {
                 throw new CommerceError('x402_configuration', 'Configure the required network RPC locally');
             if (profile.adapter === 'mpp' && !stripeRecipientFor?.(profile.accountRef))
                 throw new CommerceError('mpp_configuration', 'Configure and verify the merchant account locally');
+            if (profile.adapter === 'envar_balance' && !syncSettings?.policy.allowedBalanceAccounts?.includes(profile.accountRef))
+                throw new CommerceError('balance_configuration', 'Allow this balance receiving account locally');
         }
     };
     validateAdapters(config);

package/dist/commerce/config.js

@@ -135,6 +135,8 @@ export function loadCommerceConfig(value) {
                 throw new CommerceError('invalid_amount', 'Maximum total exceeds supported integer range');
             if (profile.adapter === 'mpp' && low < 50n)
                 throw new CommerceError('card_minimum', 'USD card orders must be at least 50 cents');
+            if (profile.adapter === 'envar_balance' && high > 2n ** 63n - 1n)
+                throw new CommerceError('balance_amount', 'Envar balance prices must fit signed micro-USD');
         }
     }
     return config;

package/dist/commerce/envar-balance.d.ts

@@ -0,0 +1,25 @@
+import { type PriceQuote } from './types.js';
+import { CommerceStore, type OrderRecord } from './store.js';
+import { CredentialVault } from './vault.js';
+export interface BalanceClaimArgs {
+    platformOrderId: string;
+    claimToken: string;
+    taskId: string;
+    quote: PriceQuote;
+}
+export interface EnvarBalanceGateOptions {
+    store: CommerceStore;
+    vault: CredentialVault;
+    claim: (args: BalanceClaimArgs) => Promise<Record<string, unknown>>;
+}
+export declare class EnvarBalanceGate {
+    private readonly options;
+    constructor(options: EnvarBalanceGateOptions);
+    private assertReceipt;
+    private settle;
+    handle(request: Request, order: OrderRecord): Promise<{
+        response: Response;
+    } | {
+        headers: Record<string, string>;
+    }>;
+}

package/dist/commerce/envar-balance.js

@@ -0,0 +1,65 @@
+/** Opt-in seller gate for a captured Envar account-balance claim. No x402 or MPP impersonation. */
+import { digest } from './config.js';
+import { CommerceError } from './types.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export class EnvarBalanceGate {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    assertReceipt(order, platformOrderId, receipt) {
+        const quote = order.quote, profile = quote.paymentProfile;
+        if (profile?.adapter !== 'envar_balance')
+            throw new CommerceError('balance_profile', 'Original quote is not an Envar balance offer');
+        if (receipt.state !== 'captured' || receipt.order_id !== platformOrderId ||
+            receipt.amount !== quote.amount || receipt.currency !== 'usd' || receipt.recipient !== profile?.accountRef ||
+            receipt.quote_id !== quote.quoteId || receipt.message_id !== quote.messageId ||
+            receipt.task_id !== order.taskId ||
+            receipt.service_id !== quote.serviceId || receipt.service_revision !== quote.serviceRevision ||
+            receipt.offer_id !== quote.offerId || receipt.input_digest !== quote.inputDigest ||
+            receipt.terms_digest !== quote.termsDigest ||
+            typeof receipt.economic_id !== 'string' || !/^ledger:[0-9a-f-]{36}$/i.test(receipt.economic_id))
+            throw new CommerceError('balance_receipt_mismatch', 'Platform capture differs from the frozen service order');
+    }
+    async settle(order, attemptId, saved) {
+        if (saved.quoteId !== order.quote.quoteId)
+            throw new CommerceError('balance_recovery_conflict', 'Original balance claim belongs to another quote');
+        let receipt;
+        try {
+            receipt = await this.options.claim({ platformOrderId: saved.platformOrderId, claimToken: saved.claimToken, taskId: order.taskId, quote: order.quote });
+            this.assertReceipt(order, saved.platformOrderId, receipt);
+        }
+        catch {
+            this.options.store.recordSettlement(attemptId, 'unknown', {});
+            return { response: Response.json({ error: 'balance_claim_unknown', taskId: order.taskId }, { status: 503, headers: { 'Cache-Control': 'no-store' } }) };
+        }
+        this.options.store.recordSettlement(attemptId, 'confirmed', receipt);
+        return { headers: { 'ENVAR-BALANCE-RECEIPT': String(receipt.economic_id) } };
+    }
+    async handle(request, order) {
+        const quote = order.quote, profile = quote.paymentProfile;
+        if (profile?.adapter !== 'envar_balance' || quote.currency !== 'usd' || quote.recipient !== profile.accountRef)
+            throw new CommerceError('balance_profile', 'This offer does not accept Envar account balance');
+        const prior = this.options.store.paymentForOrder(order.id);
+        if (order.paymentState === 'confirmed' && prior?.receipt)
+            return { headers: { 'ENVAR-BALANCE-RECEIPT': String(prior.receipt.economic_id) } };
+        if (['settling', 'unknown'].includes(order.paymentState)) {
+            if (!prior)
+                throw new CommerceError('balance_recovery_conflict', 'Original balance attempt is missing');
+            const saved = this.options.vault.get(prior.credentialRef);
+            return this.settle(order, prior.id, saved);
+        }
+        if (Date.now() >= Date.parse(quote.expiresAt))
+            return { response: Response.json({ error: 'quote_expired' }, { status: 409, headers: { 'Cache-Control': 'no-store' } }) };
+        const platformOrderId = request.headers.get('Envar-Balance-Order') ?? '';
+        const claimToken = request.headers.get('Envar-Balance-Claim') ?? '';
+        if (!platformOrderId && !claimToken)
+            return { response: Response.json({ error: 'envar_balance_required', taskId: order.taskId, quote: { quoteId: quote.quoteId, messageId: quote.messageId, serviceId: quote.serviceId, serviceRevision: quote.serviceRevision, offerId: quote.offerId, inputDigest: quote.inputDigest, termsDigest: quote.termsDigest, amount: quote.amount, currency: quote.currency, recipient: quote.recipient, expiresAt: quote.expiresAt } }, { status: 402, headers: { 'Cache-Control': 'no-store' } }) };
+        if (!UUID.test(platformOrderId) || claimToken.length < 32 || claimToken.length > 4096 || /\s/.test(claimToken))
+            throw new CommerceError('balance_claim', 'Use the original bounded platform balance claim');
+        const credentialRef = this.options.vault.put({ platformOrderId, claimToken, quoteId: quote.quoteId });
+        const economicKey = digest({ adapter: 'envar_balance', platformOrderId });
+        const attempt = this.options.store.reservePayment(order.id, order.caller, economicKey, credentialRef);
+        return this.settle(order, attempt, { platformOrderId, claimToken, quoteId: quote.quoteId });
+    }
+}

package/dist/commerce/envar.d.ts

@@ -16,6 +16,8 @@ export interface EnvarPolicy {
         facilitatorOrigin: string;
     }[];
     allowedMppAccounts: string[];
+    /** Explicit seller account references allowed to accept platform balance. */
+    allowedBalanceAccounts?: string[];
 }
 export interface EnvarCandidate {
     id: string;
@@ -81,6 +83,12 @@ export declare class EnvarIntegration {
     close(): void;
     private open;
     private request;
+    claimBalancePayment(args: {
+        platformOrderId: string;
+        claimToken: string;
+        taskId: string;
+        quote: PriceQuote;
+    }): Promise<Record<string, unknown>>;
     allowInstalledService(name: string): void;
     reportRuntime(value: unknown): Promise<{
         name: string;

package/dist/commerce/envar.js

@@ -136,6 +136,9 @@ export class EnvarIntegration {
         });
         if (this.policy.allowedMppAccounts.some((id) => !ID.test(id)))
             fail("envar_policy", "Configure explicit merchant account references");
+        this.policy.allowedBalanceAccounts ??= [];
+        if (this.policy.allowedBalanceAccounts.some((id) => !ID.test(id)))
+            fail("envar_policy", "Configure explicit balance account references");
         this.timeoutMs = options.timeoutMs ?? 10000;
         this.limitBytes = options.responseLimitBytes ?? 1048576;
         if (!Number.isInteger(this.timeoutMs) ||
@@ -214,12 +217,12 @@ export class EnvarIntegration {
     }
     async request(path, payload, eventId) {
         this.open();
-        if (![
+        if (!([
             "/api/v1/agent-config/candidates",
             "/api/v1/agent-config/acknowledgments",
             "/api/v1/commerce-reports",
             "/api/v1/agent-config/runtime",
-        ].includes(path))
+        ].includes(path) || /^\/api\/v1\/commerce\/payment-claims\/[0-9a-f-]{36}\/claim$/i.test(path)))
             fail("envar_path", "Unsupported platform integration operation");
         const token = await this.options.token();
         if (typeof token !== "string" ||
@@ -298,6 +301,19 @@ export class EnvarIntegration {
             fail("envar_response_json", "Platform response must be an object");
         return value;
     }
+    async claimBalancePayment(args) {
+        uuid(args.platformOrderId);
+        if (typeof args.claimToken !== 'string' || args.claimToken.length < 32 || args.claimToken.length > 4096 || /\s/.test(args.claimToken))
+            fail('envar_balance_claim', 'Use the original bounded platform claim');
+        return this.request(`/api/v1/commerce/payment-claims/${args.platformOrderId}/claim`, {
+            claim_token: args.claimToken, task_id: args.taskId,
+            quote_id: args.quote.quoteId, message_id: args.quote.messageId,
+            service_id: args.quote.serviceId, service_revision: args.quote.serviceRevision,
+            offer_id: args.quote.offerId, input_digest: args.quote.inputDigest,
+            terms_digest: args.quote.termsDigest, amount: args.quote.amount,
+            currency: args.quote.currency, recipient: args.quote.recipient,
+        }, args.platformOrderId);
+    }
     allowInstalledService(name) {
         if (!ID.test(name))
             fail('envar_policy', 'Invalid installed Skill name');
@@ -348,8 +364,10 @@ export class EnvarIntegration {
                     a.facilitatorOrigin === new URL(profile.facilitatorUrl).origin))
                     fail("envar_recipient_denied", "Receiving identity or facilitator is outside the local update grant");
             }
-            else if (!this.policy.allowedMppAccounts.includes(profile.accountRef))
+            else if (profile.adapter === "mpp" && !this.policy.allowedMppAccounts.includes(profile.accountRef))
                 fail("envar_merchant_denied", "Merchant account is outside the local update grant");
+            else if (profile.adapter === "envar_balance" && !this.policy.allowedBalanceAccounts.includes(profile.accountRef))
+                fail("envar_balance_denied", "Balance receiving account is outside the local update grant");
         }
         const prior = this.db
             .prepare("SELECT * FROM revisions WHERE id=? OR (local_service=? AND revision=?)")

package/dist/commerce/pricing.js

@@ -33,7 +33,7 @@ export function buildQuote(config, args) {
     if (amount >= 2n ** 256n)
         throw new CommerceError('invalid_amount', 'Quoted amount is too large');
     const profile = offer.paymentProfile ? config.paymentProfiles[offer.paymentProfile] : null;
-    const recipient = profile?.adapter === 'x402' ? profile.payTo : profile ? args.stripeRecipient : null;
+    const recipient = profile?.adapter === 'x402' ? profile.payTo : profile?.adapter === 'envar_balance' ? profile.accountRef : profile ? args.stripeRecipient : null;
     if (profile?.adapter === 'mpp' && !recipient)
         throw new CommerceError('merchant_not_ready', 'Resolve and verify the Stripe merchant before quoting');
     const now = args.now ?? new Date();

package/dist/commerce/runtime.d.ts

@@ -6,6 +6,7 @@ export * from './skill-gate.js';
 export * from './native-skills.js';
 export * from './http.js';
 export * from './x402.js';
+export * from './envar-balance.js';
 export * from './vault.js';
 export * from './chain.js';
 export * from './external-agent.js';

package/dist/commerce/runtime.js

@@ -6,6 +6,7 @@ export * from './skill-gate.js';
 export * from './native-skills.js';
 export * from './http.js';
 export * from './x402.js';
+export * from './envar-balance.js';
 export * from './vault.js';
 export * from './chain.js';
 export * from './external-agent.js';

package/dist/commerce/types.d.ts

@@ -39,6 +39,10 @@ export type PaymentProfile = {
     intent: 'charge';
     currency: 'usd';
     accountRef: string;
+} | {
+    adapter: 'envar_balance';
+    currency: 'usd';
+    accountRef: string;
 };
 export interface Service {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/envarpay",
-  "version": "0.2.0-alpha.18",
+  "version": "0.2.0-alpha.19",
   "description": "Independent A2A service commerce, budgeted buyers and x402/MPP payments",
   "type": "module",
   "license": "MIT",

package/schemas/envarpay.config.schema.json

@@ -45,6 +45,9 @@
           },
           {
             "$ref": "#/$defs/mpp"
+          },
+          {
+            "$ref": "#/$defs/envarBalance"
           }
         ]
       }
@@ -140,6 +143,16 @@
         }
       }
     },
+    "envarBalance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["adapter", "currency", "accountRef"],
+      "properties": {
+        "adapter": { "const": "envar_balance" },
+        "currency": { "const": "usd" },
+        "accountRef": { "$ref": "#/$defs/id" }
+      }
+    },
     "service": {
       "type": "object",
       "additionalProperties": false,