@ophirai/sdk 0.1.0

package/dist/__tests__/x402.test.js

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import { agreementToX402Headers, parseX402Response } from '../x402.js';
+function makeAgreement(overrides = {}) {
+    return {
+        agreement_id: 'agr_x402_001',
+        rfq_id: 'rfq_001',
+        accepting_message_id: 'quote_001',
+        final_terms: {
+            price_per_unit: '0.005',
+            currency: 'USDC',
+            unit: 'request',
+        },
+        agreement_hash: 'abcdef1234567890',
+        buyer_signature: 'buyer_sig',
+        seller_signature: 'seller_sig',
+        ...overrides,
+    };
+}
+describe('agreementToX402Headers', () => {
+    it('includes agreement ID in headers', () => {
+        const agreement = makeAgreement();
+        const headers = agreementToX402Headers(agreement);
+        expect(headers['X-Payment-Agreement-Id']).toBe('agr_x402_001');
+    });
+    it('includes price, currency, unit, and agreement hash', () => {
+        const agreement = makeAgreement();
+        const headers = agreementToX402Headers(agreement);
+        expect(headers['X-Payment-Amount']).toBe('0.005');
+        expect(headers['X-Payment-Currency']).toBe('USDC');
+        expect(headers['X-Payment-Unit']).toBe('request');
+        expect(headers['X-Payment-Agreement-Hash']).toBe('abcdef1234567890');
+    });
+    it('includes escrow network and deposit when final_terms has escrow', () => {
+        const agreement = makeAgreement({
+            final_terms: {
+                price_per_unit: '0.01',
+                currency: 'USDC',
+                unit: 'request',
+                escrow: {
+                    network: 'solana',
+                    deposit_amount: '100.0',
+                    release_condition: 'sla_met',
+                },
+            },
+        });
+        const headers = agreementToX402Headers(agreement);
+        expect(headers['X-Payment-Network']).toBe('solana');
+        expect(headers['X-Payment-Escrow-Deposit']).toBe('100.0');
+    });
+    it('includes escrow address when agreement has escrow PDA', () => {
+        const agreement = makeAgreement({
+            escrow: {
+                address: 'EscrowPDA_base58address',
+                txSignature: 'tx_sig_123',
+            },
+        });
+        const headers = agreementToX402Headers(agreement);
+        expect(headers['X-Payment-Escrow-Address']).toBe('EscrowPDA_base58address');
+    });
+    it('omits escrow headers when no escrow configured', () => {
+        const agreement = makeAgreement();
+        const headers = agreementToX402Headers(agreement);
+        expect(headers['X-Payment-Network']).toBeUndefined();
+        expect(headers['X-Payment-Escrow-Deposit']).toBeUndefined();
+        expect(headers['X-Payment-Escrow-Address']).toBeUndefined();
+    });
+    it('returns all expected header keys', () => {
+        const agreement = makeAgreement({
+            final_terms: {
+                price_per_unit: '0.01',
+                currency: 'USDC',
+                unit: 'token',
+                escrow: {
+                    network: 'solana',
+                    deposit_amount: '50',
+                    release_condition: 'job_complete',
+                },
+            },
+            escrow: {
+                address: 'PDA_addr',
+                txSignature: 'tx123',
+            },
+        });
+        const headers = agreementToX402Headers(agreement);
+        const keys = Object.keys(headers);
+        expect(keys).toContain('X-Payment-Amount');
+        expect(keys).toContain('X-Payment-Currency');
+        expect(keys).toContain('X-Payment-Agreement-Id');
+        expect(keys).toContain('X-Payment-Agreement-Hash');
+        expect(keys).toContain('X-Payment-Unit');
+        expect(keys).toContain('X-Payment-Network');
+        expect(keys).toContain('X-Payment-Escrow-Deposit');
+        expect(keys).toContain('X-Payment-Escrow-Address');
+    });
+});
+describe('parseX402Response', () => {
+    it('parses standard cased headers', () => {
+        const result = parseX402Response({
+            'X-Payment-Amount': '0.005',
+            'X-Payment-Currency': 'USDC',
+            'X-Payment-Address': 'addr_123',
+        });
+        expect(result.price).toBe('0.005');
+        expect(result.currency).toBe('USDC');
+        expect(result.paymentAddress).toBe('addr_123');
+    });
+    it('parses lowercase headers', () => {
+        const result = parseX402Response({
+            'x-payment-amount': '0.01',
+            'x-payment-currency': 'SOL',
+            'x-payment-address': 'sol_addr',
+        });
+        expect(result.price).toBe('0.01');
+        expect(result.currency).toBe('SOL');
+        expect(result.paymentAddress).toBe('sol_addr');
+    });
+    it('parses mixed-case headers', () => {
+        const result = parseX402Response({
+            'X-PAYMENT-AMOUNT': '1.5',
+            'X-Payment-currency': 'ETH',
+            'x-Payment-Address': 'eth_addr',
+        });
+        expect(result.price).toBe('1.5');
+        expect(result.currency).toBe('ETH');
+        expect(result.paymentAddress).toBe('eth_addr');
+    });
+    it('returns defaults when headers are missing', () => {
+        const result = parseX402Response({});
+        expect(result.price).toBe('0');
+        expect(result.currency).toBe('USDC');
+        expect(result.paymentAddress).toBe('');
+    });
+    it('returns partial defaults for partially present headers', () => {
+        const result = parseX402Response({
+            'X-Payment-Amount': '5.0',
+        });
+        expect(result.price).toBe('5.0');
+        expect(result.currency).toBe('USDC');
+        expect(result.paymentAddress).toBe('');
+    });
+});

package/dist/buyer.d.ts

@@ -0,0 +1,190 @@
+import type { QuoteParams, ServiceRequirement, BudgetConstraint, SLARequirement, ViolationEvidence } from '@ophirai/protocol';
+import { NegotiationSession } from './negotiation.js';
+import type { EscrowConfig, RankingFunction, SellerInfo, Agreement, DisputeResult } from './types.js';
+/** Configuration for creating a BuyerAgent. */
+export interface BuyerAgentConfig {
+    /** Optional Ed25519 keypair; auto-generated if omitted. */
+    keypair?: {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+    /** HTTP endpoint URL where this buyer listens for incoming quotes and counter-offers. */
+    endpoint: string;
+    /** Optional Solana escrow configuration for payment enforcement. */
+    escrowConfig?: EscrowConfig;
+    /** Optional Lockstep verification endpoint for SLA compliance monitoring. */
+    lockstepEndpoint?: string;
+}
+/**
+ * Buy-side negotiation agent. Sends RFQs, collects quotes, ranks them,
+ * and accepts/counters/rejects offers. Verifies seller signatures on all
+ * incoming messages.
+ */
+export declare class BuyerAgent {
+    private keypair;
+    private agentId;
+    private endpoint;
+    private transport;
+    private server;
+    private sessions;
+    private quoteListeners;
+    /** Tracks processed message IDs within the replay window to reject duplicate/replayed messages. */
+    private seenMessageIds;
+    constructor(config: BuyerAgentConfig);
+    /** Check if a message ID has already been processed (replay protection).
+     * Records the ID if new; throws DUPLICATE_MESSAGE if already seen.
+     * Periodically evicts entries older than the replay protection window. */
+    private enforceNoDuplicate;
+    /** Register JSON-RPC handlers for Quote, Counter, and Accept methods.
+     * Each handler validates the message schema, verifies the sender's Ed25519
+     * signature, checks expiration, enforces replay protection, and updates the session state. */
+    private registerHandlers;
+    /** Resolve all pending waitForQuotes() promises for the given RFQ and clear the listener queue. */
+    private notifyQuoteListeners;
+    /** Discover seller agents matching a service category. Currently returns empty; use direct endpoints.
+     * @param _query - Search criteria containing a service category and optional requirements
+     * @returns An empty array (placeholder for future discovery integration)
+     * @example
+     * ```typescript
+     * const sellers = await buyer.discover({ category: 'llm-inference' });
+     * ```
+     */
+    discover(_query: {
+        category: string;
+        requirements?: Record<string, unknown>;
+    }): Promise<SellerInfo[]>;
+    /** Send an RFQ to one or more sellers and return the negotiation session.
+     * @param params - RFQ parameters including seller targets, service requirements, budget, and SLA
+     * @param params.sellers - Seller endpoints (strings) or SellerInfo objects to receive the RFQ
+     * @param params.service - The service requirement describing what the buyer needs
+     * @param params.budget - Budget constraint with maximum price and currency
+     * @param params.sla - Optional SLA requirements for the service
+     * @param params.maxRounds - Optional maximum number of negotiation rounds
+     * @param params.timeout - Optional TTL in milliseconds for the RFQ
+     * @returns The newly created NegotiationSession tracking this RFQ
+     * @throws {OphirError} When a non-network error occurs sending to a seller
+     * @example
+     * ```typescript
+     * const session = await buyer.requestQuotes({
+     *   sellers: ['http://seller:3000'],
+     *   service: { category: 'llm-inference', params: {} },
+     *   budget: { max_price_per_unit: '0.01', currency: 'USDC' },
+     * });
+     * ```
+     */
+    requestQuotes(params: {
+        sellers: string[] | SellerInfo[];
+        service: ServiceRequirement;
+        budget: BudgetConstraint;
+        sla?: SLARequirement;
+        maxRounds?: number;
+        timeout?: number;
+    }): Promise<NegotiationSession>;
+    /** Wait for quotes to arrive, resolving when minQuotes are received or timeout elapses.
+     * @param session - The negotiation session to wait on
+     * @param options - Optional wait configuration
+     * @param options.minQuotes - Minimum number of quotes before resolving (default: 1)
+     * @param options.timeout - Maximum time to wait in milliseconds (default: 30000)
+     * @returns Array of quotes received so far when the condition is met or timeout elapses
+     * @example
+     * ```typescript
+     * const quotes = await buyer.waitForQuotes(session, { minQuotes: 2, timeout: 10000 });
+     * ```
+     */
+    waitForQuotes(session: NegotiationSession, options?: {
+        minQuotes?: number;
+        timeout?: number;
+    }): Promise<QuoteParams[]>;
+    /** Sort quotes by a ranking strategy (cheapest, fastest, best_sla, or custom function).
+     * @param quotes - Array of quotes to rank
+     * @param strategy - Ranking strategy: 'cheapest', 'fastest', 'best_sla', or a custom comparator (default: 'cheapest')
+     * @returns A new sorted array of quotes (best first)
+     * @example
+     * ```typescript
+     * const ranked = buyer.rankQuotes(quotes, 'fastest');
+     * const best = ranked[0];
+     * ```
+     */
+    rankQuotes(quotes: QuoteParams[], strategy?: 'cheapest' | 'fastest' | 'best_sla' | RankingFunction): QuoteParams[];
+    /** Compute a composite SLA quality score for ranking. Higher-is-better metrics (uptime, accuracy) add directly; lower-is-better metrics (latency, error rate) are inverted. */
+    private scoreSLA;
+    /** Accept a quote, creating a signed agreement with the seller. Verifies the seller's signature first.
+     * @param quote - The quote to accept, as received from a seller
+     * @returns A dual-signed Agreement containing final terms and both party signatures
+     * @throws {OphirError} When the seller's signature on the quote is invalid
+     * @throws {OphirError} When the seller's counter-signature on the accept is invalid
+     * @example
+     * ```typescript
+     * const agreement = await buyer.acceptQuote(quotes[0]);
+     * console.log(agreement.agreement_id);
+     * ```
+     */
+    acceptQuote(quote: QuoteParams): Promise<Agreement>;
+    /** Send a counter-offer proposing modified terms for a quote.
+     * @param quote - The original quote to counter
+     * @param modifications - Key-value map of proposed term changes (e.g., price, SLA targets)
+     * @param justification - Optional human-readable reason for the counter-offer
+     * @returns The updated NegotiationSession reflecting the new counter round
+     * @throws {OphirError} When no active session exists for the quote's RFQ ID
+     * @example
+     * ```typescript
+     * const session = await buyer.counter(quote, { price_per_unit: '0.008' }, 'Volume discount');
+     * ```
+     */
+    counter(quote: QuoteParams, modifications: Record<string, unknown>, justification?: string): Promise<NegotiationSession>;
+    /** Reject all quotes in a session and notify sellers.
+     * @param session - The negotiation session whose quotes should be rejected
+     * @param reason - Optional rejection reason sent to all sellers (default: 'Rejected by buyer')
+     * @returns Resolves when all rejection messages have been sent
+     * @throws {OphirError} When a non-network error occurs notifying a seller
+     * @example
+     * ```typescript
+     * await buyer.reject(session, 'Budget exceeded');
+     * ```
+     */
+    reject(session: NegotiationSession, reason?: string): Promise<void>;
+    /** File an SLA violation dispute against a seller for a given agreement.
+     * @param agreement - The agreement under which the violation occurred
+     * @param violation - Evidence of the SLA violation including metric name and observed value
+     * @returns A DisputeResult with the dispute ID and initial 'pending' outcome
+     * @throws {OphirError} When a non-network error occurs notifying the seller
+     * @example
+     * ```typescript
+     * const result = await buyer.dispute(agreement, {
+     *   metric: 'uptime_pct', observed: 95.0, threshold: 99.9,
+     * });
+     * ```
+     */
+    dispute(agreement: Agreement, violation: ViolationEvidence): Promise<DisputeResult>;
+    /** Get a negotiation session by its RFQ ID.
+     * @param rfqId - The RFQ identifier to look up
+     * @returns The matching NegotiationSession, or undefined if not found
+     */
+    getSession(rfqId: string): NegotiationSession | undefined;
+    /** Get all active negotiation sessions.
+     * @returns Array of all NegotiationSession instances tracked by this agent
+     */
+    getSessions(): NegotiationSession[];
+    /** Start the HTTP server to receive quotes and counter-offers.
+     * @param port - Port number to listen on (default: 3001). Pass 0 for a random available port.
+     * @returns Resolves when the server is listening
+     * @example
+     * ```typescript
+     * await buyer.listen(0);
+     * console.log(buyer.getEndpoint());
+     * ```
+     */
+    listen(port?: number): Promise<void>;
+    /** Stop the HTTP server and close all connections.
+     * @returns Resolves when the server has been shut down
+     */
+    close(): Promise<void>;
+    /** Get this agent's did:key identifier.
+     * @returns The agent's decentralized identifier (did:key)
+     */
+    getAgentId(): string;
+    /** Get this agent's HTTP endpoint URL.
+     * @returns The endpoint URL string (updated after listen() binds a port)
+     */
+    getEndpoint(): string;
+}