@ophirai/sdk 0.1.0

package/dist/transport.d.ts

@@ -0,0 +1,41 @@
+/** Configuration options for the JSON-RPC HTTP client. */
+export interface JsonRpcClientConfig {
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+}
+/**
+ * JSON-RPC 2.0 HTTP client for Ophir agent-to-agent communication.
+ * Handles request/response lifecycle, timeouts, and error mapping.
+ */
+export declare class JsonRpcClient {
+    private timeout;
+    constructor(config?: JsonRpcClientConfig);
+    /** Send a JSON-RPC 2.0 request and return the typed result.
+     * @param endpoint - The URL of the remote JSON-RPC server
+     * @param method - The JSON-RPC method name to invoke
+     * @param params - The parameters object to include in the request
+     * @param id - Optional request ID; a random UUID is generated if omitted
+     * @returns The parsed result field from the JSON-RPC response
+     * @throws {OphirError} SELLER_UNREACHABLE on network/timeout/HTTP errors
+     * @throws {OphirError} INVALID_MESSAGE on malformed JSON or JSON-RPC error responses
+     * @example
+     * ```typescript
+     * const client = new JsonRpcClient();
+     * const result = await client.send<Quote>('https://agent.example/rpc', 'ophir.propose', { terms });
+     * ```
+     */
+    send<T>(endpoint: string, method: string, params: object, id?: string): Promise<T>;
+    /** Send a JSON-RPC 2.0 notification (fire-and-forget, no response expected).
+     * @param endpoint - The URL of the remote JSON-RPC server
+     * @param method - The JSON-RPC method name to invoke
+     * @param params - The parameters object to include in the notification
+     * @returns Resolves when the request has been sent
+     * @throws {OphirError} SELLER_UNREACHABLE on network or timeout errors
+     * @example
+     * ```typescript
+     * const client = new JsonRpcClient();
+     * await client.sendNotification('https://agent.example/rpc', 'ophir.cancel', { agreement_id });
+     * ```
+     */
+    sendNotification(endpoint: string, method: string, params: object): Promise<void>;
+}

package/dist/transport.js

@@ -0,0 +1,127 @@
+import { OphirError, OphirErrorCode } from '@ophirai/protocol';
+const DEFAULT_TIMEOUT = 30_000;
+const USER_AGENT = 'ophir-sdk/0.1.0';
+/**
+ * JSON-RPC 2.0 HTTP client for Ophir agent-to-agent communication.
+ * Handles request/response lifecycle, timeouts, and error mapping.
+ */
+export class JsonRpcClient {
+    timeout;
+    constructor(config) {
+        this.timeout = config?.timeout ?? DEFAULT_TIMEOUT;
+    }
+    /** Send a JSON-RPC 2.0 request and return the typed result.
+     * @param endpoint - The URL of the remote JSON-RPC server
+     * @param method - The JSON-RPC method name to invoke
+     * @param params - The parameters object to include in the request
+     * @param id - Optional request ID; a random UUID is generated if omitted
+     * @returns The parsed result field from the JSON-RPC response
+     * @throws {OphirError} SELLER_UNREACHABLE on network/timeout/HTTP errors
+     * @throws {OphirError} INVALID_MESSAGE on malformed JSON or JSON-RPC error responses
+     * @example
+     * ```typescript
+     * const client = new JsonRpcClient();
+     * const result = await client.send<Quote>('https://agent.example/rpc', 'ophir.propose', { terms });
+     * ```
+     */
+    async send(endpoint, method, params, id) {
+        if (!endpoint || typeof endpoint !== 'string') {
+            throw new OphirError(OphirErrorCode.SELLER_UNREACHABLE, 'Endpoint must be a non-empty string');
+        }
+        const requestId = id ?? crypto.randomUUID();
+        const body = JSON.stringify({
+            jsonrpc: '2.0',
+            method,
+            params,
+            id: requestId,
+        });
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        let response;
+        try {
+            response = await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'User-Agent': USER_AGENT,
+                },
+                body,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new OphirError(OphirErrorCode.SELLER_UNREACHABLE, `Request to ${endpoint} timed out after ${this.timeout}ms`);
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new OphirError(OphirErrorCode.SELLER_UNREACHABLE, `Network error reaching ${endpoint}: ${message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            throw new OphirError(OphirErrorCode.SELLER_UNREACHABLE, `HTTP ${response.status} from ${endpoint}`, { status: response.status, statusText: response.statusText });
+        }
+        let json;
+        try {
+            json = await response.json();
+        }
+        catch {
+            throw new OphirError(OphirErrorCode.INVALID_MESSAGE, `Invalid JSON response from ${endpoint}`);
+        }
+        // Validate response ID matches request ID to prevent response spoofing
+        if (json.id !== undefined && json.id !== requestId) {
+            throw new OphirError(OphirErrorCode.INVALID_MESSAGE, `JSON-RPC response ID mismatch: expected ${requestId}, got ${String(json.id)}`);
+        }
+        if (json.error && typeof json.error === 'object') {
+            const err = json.error;
+            throw new OphirError(OphirErrorCode.INVALID_MESSAGE, err.message ?? 'JSON-RPC error', { code: err.code, data: err.data });
+        }
+        if (!('result' in json)) {
+            throw new OphirError(OphirErrorCode.INVALID_MESSAGE, `Missing 'result' field in JSON-RPC response from ${endpoint}`);
+        }
+        return json.result;
+    }
+    /** Send a JSON-RPC 2.0 notification (fire-and-forget, no response expected).
+     * @param endpoint - The URL of the remote JSON-RPC server
+     * @param method - The JSON-RPC method name to invoke
+     * @param params - The parameters object to include in the notification
+     * @returns Resolves when the request has been sent
+     * @throws {OphirError} SELLER_UNREACHABLE on network or timeout errors
+     * @example
+     * ```typescript
+     * const client = new JsonRpcClient();
+     * await client.sendNotification('https://agent.example/rpc', 'ophir.cancel', { agreement_id });
+     * ```
+     */
+    async sendNotification(endpoint, method, params) {
+        const body = JSON.stringify({
+            jsonrpc: '2.0',
+            method,
+            params,
+        });
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'User-Agent': USER_AGENT,
+                },
+                body,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new OphirError(OphirErrorCode.SELLER_UNREACHABLE, `Notification to ${endpoint} timed out after ${this.timeout}ms`);
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new OphirError(OphirErrorCode.SELLER_UNREACHABLE, `Network error sending notification to ${endpoint}: ${message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+import type { QuoteParams, FinalTerms } from '@ophirai/protocol';
+/** Configuration for connecting to the Solana escrow program. */
+export interface EscrowConfig {
+    /** Solana RPC endpoint URL (defaults to devnet). */
+    rpcUrl?: string;
+    /** Anchor program ID for the Ophir escrow program. */
+    programId?: string;
+}
+/** A service offering advertised by a seller agent. */
+export interface ServiceOffering {
+    /** Service category (e.g. 'inference', 'translation', 'data_processing'). */
+    category: string;
+    /** Human-readable description of the service. */
+    description: string;
+    /** Base price per unit as a decimal string (e.g. '0.005'). */
+    base_price: string;
+    /** Payment currency (e.g. 'USDC'). */
+    currency: string;
+    /** Pricing unit (e.g. 'request', 'token', 'MB'). */
+    unit: string;
+    /** Maximum concurrent capacity, if limited. */
+    capacity?: number;
+}
+/** Pricing strategy for automated quote generation by seller agents. */
+export interface PricingStrategy {
+    /** Strategy type: fixed base price, competitive (undercut), or dynamic. */
+    type: 'fixed' | 'competitive' | 'dynamic';
+    /** Margin adjustment factor (e.g. 0.1 for 10% margin). */
+    margin?: number;
+}
+/** Custom comparator function for ranking quotes. Return negative if `a` is preferred. */
+export type RankingFunction = (a: QuoteParams, b: QuoteParams) => number;
+/** Registration info for a known seller agent. */
+export interface SellerInfo {
+    /** Seller's did:key identifier. */
+    agentId: string;
+    /** Seller's HTTP endpoint for receiving JSON-RPC messages. */
+    endpoint: string;
+    /** Services offered by this seller. */
+    services: ServiceOffering[];
+}
+/** Finalized agreement between buyer and seller, signed by both parties. */
+export interface Agreement {
+    /** Unique agreement identifier. */
+    agreement_id: string;
+    /** RFQ that initiated this negotiation. */
+    rfq_id: string;
+    /** The quote or counter ID that was accepted. Stored so signatures can be independently verified. */
+    accepting_message_id: string;
+    /** Final agreed terms (price, currency, SLA, escrow). */
+    final_terms: FinalTerms;
+    /** SHA-256 hash of the canonicalized final terms. */
+    agreement_hash: string;
+    /** Buyer's Ed25519 signature over the unsigned accept payload (base64). */
+    buyer_signature: string;
+    /**
+     * Seller's Ed25519 counter-signature over the same unsigned accept payload (base64).
+     * Absent until the seller counter-signs the accept message.
+     */
+    seller_signature?: string;
+    /** On-chain escrow details, if funded. */
+    escrow?: {
+        /** Solana escrow PDA address (base58). */
+        address: string;
+        /** Transaction signature from escrow creation. */
+        txSignature: string;
+    };
+}
+/** Result of a dispute resolution. */
+export interface DisputeResult {
+    /** Unique dispute identifier. */
+    dispute_id: string;
+    /** Current dispute outcome. */
+    outcome: 'penalty_applied' | 'dismissed' | 'pending';
+    /** Transaction signature if an on-chain action was taken. */
+    txSignature?: string;
+}
+/** Result of a completed job execution. */
+export interface JobResult {
+    /** Agreement this job was executed under. */
+    agreement_id: string;
+    /** Job completion status. */
+    status: 'completed' | 'failed';
+    /** Observed SLA metrics from job execution. */
+    metrics?: Record<string, number>;
+}

package/dist/types.js

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

package/dist/x402.d.ts

@@ -0,0 +1,25 @@
+import type { Agreement } from './types.js';
+/** Generate x402-compatible payment headers from agreed terms.
+ * @param agreement - The finalized agreement containing price, currency, and escrow details
+ * @returns A record of X-Payment-* headers suitable for HTTP requests
+ * @example
+ * ```typescript
+ * const headers = agreementToX402Headers(agreement);
+ * const response = await fetch(url, { headers });
+ * ```
+ */
+export declare function agreementToX402Headers(agreement: Agreement): Record<string, string>;
+/** Parse x402 payment response headers into structured data.
+ * @param headers - The HTTP response headers (lookup is case-insensitive per HTTP spec)
+ * @returns Parsed payment details with price, currency, and paymentAddress
+ * @example
+ * ```typescript
+ * const payment = parseX402Response(response.headers);
+ * console.log(payment.price, payment.currency); // "0.01" "USDC"
+ * ```
+ */
+export declare function parseX402Response(headers: Record<string, string>): {
+    price: string;
+    currency: string;
+    paymentAddress: string;
+};

package/dist/x402.js

@@ -0,0 +1,54 @@
+/** Generate x402-compatible payment headers from agreed terms.
+ * @param agreement - The finalized agreement containing price, currency, and escrow details
+ * @returns A record of X-Payment-* headers suitable for HTTP requests
+ * @example
+ * ```typescript
+ * const headers = agreementToX402Headers(agreement);
+ * const response = await fetch(url, { headers });
+ * ```
+ */
+export function agreementToX402Headers(agreement) {
+    const terms = agreement.final_terms;
+    const headers = {
+        'X-Payment-Amount': terms.price_per_unit,
+        'X-Payment-Currency': terms.currency,
+        'X-Payment-Agreement-Id': agreement.agreement_id,
+        'X-Payment-Agreement-Hash': agreement.agreement_hash,
+        'X-Payment-Unit': terms.unit,
+    };
+    if (terms.escrow) {
+        headers['X-Payment-Network'] = terms.escrow.network;
+        headers['X-Payment-Escrow-Deposit'] = terms.escrow.deposit_amount;
+    }
+    if (agreement.escrow?.address) {
+        headers['X-Payment-Escrow-Address'] = agreement.escrow.address;
+    }
+    return headers;
+}
+/**
+ * Look up a header value case-insensitively.
+ */
+function getHeader(headers, name) {
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === lower)
+            return headers[key];
+    }
+    return undefined;
+}
+/** Parse x402 payment response headers into structured data.
+ * @param headers - The HTTP response headers (lookup is case-insensitive per HTTP spec)
+ * @returns Parsed payment details with price, currency, and paymentAddress
+ * @example
+ * ```typescript
+ * const payment = parseX402Response(response.headers);
+ * console.log(payment.price, payment.currency); // "0.01" "USDC"
+ * ```
+ */
+export function parseX402Response(headers) {
+    return {
+        price: getHeader(headers, 'X-Payment-Amount') ?? '0',
+        currency: getHeader(headers, 'X-Payment-Currency') ?? 'USDC',
+        paymentAddress: getHeader(headers, 'X-Payment-Address') ?? '',
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ophirai/sdk",
+  "version": "0.1.0",
+  "description": "SDK for the Ophir Agent Negotiation Protocol — BuyerAgent, SellerAgent, Ed25519 signing, Solana escrow, and SLA enforcement",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ophirai/ophir",
+    "directory": "packages/sdk"
+  },
+  "keywords": ["ai-agents", "negotiation", "sdk", "ed25519", "solana", "escrow", "sla", "agent-to-agent", "ophir", "did-key"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "files": ["dist", "README.md"],
+  "dependencies": {
+    "@ophirai/protocol": "*",
+    "@solana/web3.js": "^1.95.0",
+    "tweetnacl": "^1.0.3",
+    "bs58": "^6.0.0",
+    "json-stable-stringify": "^1.1.0",
+    "zod": "^3.23.0",
+    "express": "^4.18.0",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "@types/express": "^4.17.0",
+    "@types/json-stable-stringify": "^1.0.0",
+    "@types/uuid": "^10.0.0",
+    "tsx": "^4.0.0"
+  }
+}