@key0ai/key0 0.1.0 → 0.2.0

package/src/__tests__/x402-http-middleware.test.ts

@@ -1,13 +1,11 @@
 import { beforeEach, describe, expect, test } from "bun:test";
-import type { NextFunction, Request, Response } from "express";
 import { AccessTokenIssuer } from "../core/access-token.js";
 import { ChallengeEngine } from "../core/challenge-engine.js";
 import {
 	buildHttpPaymentRequirements,
-	createX402HttpMiddleware,
 	decodePaymentSignature,
 	settleViaFacilitator,
-} from "../integrations/x402-http-middleware.js";
+} from "../integrations/settlement.js";
 import { MockPaymentAdapter } from "../test-utils/index.js";
 import { TestChallengeStore, TestSeenTxStore } from "../test-utils/stores.js";
 import { CHAIN_CONFIGS } from "../types/config-shared.js";
@@ -49,61 +47,7 @@ function makeConfig(): SellerConfig {
 	};
 }
 
-function createMockRequest(body: any, headers: Record<string, string> = {}): Partial<Request> {
-	return {
-		body,
-		headers: headers as any,
-	};
-}
-
-function createMockResponse(): {
-	res: Partial<Response>;
-	statusCode: number;
-	jsonData: any;
-	nextCalled: boolean;
-	headers: Record<string, string>;
-} {
-	let statusCode = 200;
-	let jsonData: any = null;
-	const nextCalled = false;
-	const headers: Record<string, string> = {};
-
-	const res = {
-		status: function (code: number) {
-			statusCode = code;
-			return this;
-		},
-		json: function (data: any) {
-			jsonData = data;
-			return this;
-		},
-		send: function (_data: any) {
-			return this;
-		},
-		setHeader: function (name: string, value: string) {
-			headers[name] = value;
-			return this;
-		},
-	};
-
-	return {
-		res: res as Partial<Response>,
-		get statusCode() {
-			return statusCode;
-		},
-		get jsonData() {
-			return jsonData;
-		},
-		get headers() {
-			return headers;
-		},
-		get nextCalled() {
-			return nextCalled;
-		},
-	};
-}
-
-describe("x402-http-middleware", () => {
+describe("x402 settlement helpers", () => {
 	describe("buildHttpPaymentRequirements", () => {
 		test("should build correct payment requirements", () => {
 			const config = makeConfig();
@@ -114,7 +58,7 @@ describe("x402-http-middleware", () => {
 			// v2 response structure
 			expect(requirements.x402Version).toBe(2);
 			expect(requirements.resource).toBeDefined();
-			expect(requirements.resource.url).toBe("https://agent.example.com/a2a/jsonrpc");
+			expect(requirements.resource.url).toBe("https://agent.example.com/x402/access");
 			expect(requirements.resource.method).toBe("POST");
 
 			// Payment requirements
@@ -143,209 +87,13 @@ describe("x402-http-middleware", () => {
 		});
 	});
 
-	describe("createX402HttpMiddleware", () => {
-		let engine: ChallengeEngine;
-		let config: SellerConfig;
-		let middleware: ReturnType<typeof createX402HttpMiddleware>;
-
-		beforeEach(() => {
-			config = makeConfig();
-			const store = new TestChallengeStore();
-			const seenTxStore = new TestSeenTxStore();
-			const adapter = new MockPaymentAdapter();
-
-			engine = new ChallengeEngine({
-				config,
-				store,
-				seenTxStore,
-				adapter,
-			});
-
-			middleware = createX402HttpMiddleware(engine, config);
-		});
-
-		test("should pass through if X-A2A-Extensions header is present", async () => {
-			const req = createMockRequest(
-				{
-					method: "message/send",
-					params: {
-						message: {
-							parts: [
-								{
-									kind: "data",
-									data: { type: "AccessRequest", requestId: "test", planId: "basic" },
-								},
-							],
-						},
-					},
-				},
-				{
-					"x-a2a-extensions":
-						"https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2",
-				},
-			);
-
-			let nextCalled = false;
-			const next = (() => {
-				nextCalled = true;
-			}) as NextFunction;
-			const mockRes = createMockResponse();
-
-			await middleware(req as Request, mockRes.res as Response, next);
-
-			expect(nextCalled).toBe(true);
-		});
-
-		test("should pass through if not message/send", async () => {
-			const req = createMockRequest({
-				method: "task/get",
-				params: {},
-			});
-
-			let nextCalled = false;
-			const next = (() => {
-				nextCalled = true;
-			}) as NextFunction;
-			const mockRes = createMockResponse();
-
-			await middleware(req as Request, mockRes.res as Response, next);
-
-			expect(nextCalled).toBe(true);
-		});
-
-		test("should pass through if no AccessRequest in message parts", async () => {
-			const req = createMockRequest({
-				method: "message/send",
-				params: {
-					message: {
-						parts: [{ kind: "data", data: { type: "SomethingElse" } }],
-					},
-				},
-			});
-
-			let nextCalled = false;
-			const next = (() => {
-				nextCalled = true;
-			}) as NextFunction;
-			const mockRes = createMockResponse();
-
-			await middleware(req as Request, mockRes.res as Response, next);
-
-			expect(nextCalled).toBe(true);
-		});
-
-		test("should return HTTP 402 for AccessRequest without X-Payment", async () => {
-			const req = createMockRequest({
-				method: "message/send",
-				params: {
-					message: {
-						parts: [
-							{
-								kind: "data",
-								data: {
-									type: "AccessRequest",
-									requestId: "req-123",
-									planId: "basic",
-									resourceId: "default",
-								},
-							},
-						],
-					},
-				},
-			});
-
-			const next = (() => {}) as NextFunction;
-			const mockRes = createMockResponse();
-
-			await middleware(req as Request, mockRes.res as Response, next);
-
-			expect(mockRes.statusCode).toBe(402);
-			expect(mockRes.jsonData.x402Version).toBe(2);
-			expect(mockRes.jsonData.resource).toBeDefined();
-			expect(mockRes.jsonData.accepts).toHaveLength(1);
-			expect(mockRes.jsonData.accepts[0].amount).toBe("990000");
-
-			// challengeId from PENDING record should be in the response
-			expect(mockRes.jsonData.challengeId).toBeDefined();
-			expect(mockRes.jsonData.challengeId).toMatch(/^http-/);
-
-			// Check PAYMENT-REQUIRED header is set
-			expect(mockRes.headers["payment-required"]).toBeDefined();
-			const decodedHeader = JSON.parse(
-				Buffer.from(mockRes.headers["payment-required"]!, "base64").toString(),
-			);
-			expect(decodedHeader.x402Version).toBe(2);
-		});
-
-		test("should return 400 for invalid tier", async () => {
-			const req = createMockRequest({
-				method: "message/send",
-				params: {
-					message: {
-						parts: [
-							{
-								kind: "data",
-								data: {
-									type: "AccessRequest",
-									requestId: "req-123",
-									planId: "invalid-tier",
-									resourceId: "default",
-								},
-							},
-						],
-					},
-				},
-			});
-
-			const next = (() => {}) as NextFunction;
-			const mockRes = createMockResponse();
-
-			await middleware(req as Request, mockRes.res as Response, next);
-
-			expect(mockRes.statusCode).toBe(400);
-			expect(mockRes.jsonData.code).toBe("TIER_NOT_FOUND");
-		});
-
-		test("should parse AccessRequest from text part", async () => {
-			const req = createMockRequest({
-				method: "message/send",
-				params: {
-					message: {
-						parts: [
-							{
-								kind: "text",
-								text: JSON.stringify({
-									type: "AccessRequest",
-									requestId: "req-123",
-									planId: "basic",
-									resourceId: "default",
-								}),
-							},
-						],
-					},
-				},
-			});
-
-			const next = (() => {}) as NextFunction;
-			const mockRes = createMockResponse();
-
-			await middleware(req as Request, mockRes.res as Response, next);
-
-			expect(mockRes.statusCode).toBe(402);
-			expect(mockRes.jsonData.x402Version).toBe(2);
-
-			// Check PAYMENT-REQUIRED header is set
-			expect(mockRes.headers["payment-required"]).toBeDefined();
-		});
-	});
-
 	describe("settleViaFacilitator", () => {
 		const mockPaymentPayload = {
 			x402Version: 2,
 			network: "eip155:84532",
 			scheme: "exact",
 			resource: {
-				url: "https://agent.example.com/a2a/jsonrpc",
+				url: "https://agent.example.com/x402/access",
 				method: "POST",
 				description: "Access to default",
 				mimeType: "application/json",

package/src/core/__tests__/agent-card.test.ts

@@ -62,26 +62,25 @@ describe("buildAgentCard", () => {
 	test("has two A2A spec-compliant skills", () => {
 		const card = buildAgentCard(makeConfig());
 		expect(card.skills).toHaveLength(2);
-		expect(card.skills[0]!.id).toBe("discover-products");
+		expect(card.skills[0]!.id).toBe("discover-plans");
 		expect(card.skills[1]!.id).toBe("request-access");
 	});
 
-	test("discover-products skill has correct structure", () => {
+	test("discover-plans skill has correct structure", () => {
 		const card = buildAgentCard(makeConfig());
 		const skill = card.skills[0]!;
 
-		expect(skill.id).toBe("discover-products");
-		expect(skill.name).toBe("Discover Products");
-		expect(skill.description).toContain("Browse available products");
-		expect(skill.description).toContain("/x402/access");
+		expect(skill.id).toBe("discover-plans");
+		expect(skill.name).toBe("Discover Plans");
+		expect(skill.description).toContain("Browse available");
+		expect(skill.description).toContain("/discovery");
 		expect(skill.tags).toContain("discovery");
 		expect(skill.tags).toContain("catalog");
 		expect(skill.examples).toBeDefined();
 		expect(skill.examples!.length).toBeGreaterThan(0);
 
-		// A2A spec: skills should NOT have pricing, inputSchema, outputSchema, url
+		// A2A spec: skills should NOT have pricing, outputSchema, url
 		expect((skill as any).pricing).toBeUndefined();
-		expect((skill as any).inputSchema).toBeUndefined();
 		expect((skill as any).outputSchema).toBeUndefined();
 		expect((skill as any).url).toBeUndefined();
 	});
@@ -100,9 +99,13 @@ describe("buildAgentCard", () => {
 		expect(skill.examples).toBeDefined();
 		expect(skill.examples!.length).toBeGreaterThan(0);
 
-		// A2A spec: skills should NOT have pricing, inputSchema, outputSchema, url
+		// inputSchema is present for machine-readable validation
+		expect((skill as any).inputSchema).toBeDefined();
+		expect((skill as any).inputSchema.required).toContain("planId");
+		expect((skill as any).inputSchema.required).toContain("requestId");
+
+		// A2A spec: skills should NOT have pricing, outputSchema, url
 		expect((skill as any).pricing).toBeUndefined();
-		expect((skill as any).inputSchema).toBeUndefined();
 		expect((skill as any).outputSchema).toBeUndefined();
 		expect((skill as any).url).toBeUndefined();
 	});
@@ -113,7 +116,7 @@ describe("buildAgentCard", () => {
 		const discoverSkill = card.skills[0]!;
 		expect(discoverSkill.examples).toBeDefined();
 		expect(discoverSkill.examples!.length).toBeGreaterThan(0);
-		expect(discoverSkill.examples!.some((ex) => ex.includes("/x402/access"))).toBe(true);
+		expect(discoverSkill.examples!.some((ex) => ex.includes("/discovery"))).toBe(true);
 
 		const requestSkill = card.skills[1]!;
 		expect(requestSkill.examples).toBeDefined();
@@ -150,7 +153,7 @@ describe("buildAgentCard", () => {
 
 		// Still just two skills regardless of tier count
 		expect(card.skills).toHaveLength(2);
-		expect(card.skills[0]!.id).toBe("discover-products");
+		expect(card.skills[0]!.id).toBe("discover-plans");
 		expect(card.skills[1]!.id).toBe("request-access");
 	});
 

package/src/core/__tests__/storage-postgres.test.ts

@@ -300,7 +300,6 @@ function createMockSql() {
 	// Add helper methods
 	sql.unsafe = (str: string) => str;
 	sql.json = (obj: unknown) => obj;
-	// biome-ignore lint/suspicious/noExplicitAny: mock implementation
 	sql.begin = async (fn: (sql: any) => Promise<any>) => fn(sql);
 
 	// Expose tables for inspection
@@ -316,7 +315,6 @@ function createMockSql() {
 		(value: string): any;
 		unsafe(value: string): any;
 		json(value: unknown): any;
-		// biome-ignore lint/suspicious/noExplicitAny: mock type
 		begin(fn: (sql: any) => Promise<any>): Promise<any>;
 		_tables: Map<string, Row[]>; // for inspection
 	} & { _tables: Map<string, Row[]> };

package/src/core/agent-card.ts

@@ -8,30 +8,30 @@ export function buildAgentCard(config: SellerConfig): AgentCard {
 
 	const baseUrl = config.agentUrl.replace(/\/$/, "");
 
-	// Two A2A spec-compliant skills (no pricing, no inputSchema, no outputSchema, no url)
+	const planIds = config.plans.map((p) => p.planId);
+
+	// Two A2A spec-compliant skills
 	// Skill 1: Discovery (free) — browse the product catalog
 	// Skill 2: Purchase (x402-gated) — buy an access token
 	const skills: AgentSkill[] = [
 		{
-			id: "discover-products",
-			name: "Discover Products",
+			id: "discover-plans",
+			name: "Discover Plans",
 			description: [
-				`Browse available products and pricing for ${config.agentName}.`,
+				`Browse available plans and pricing for ${config.agentName}.`,
 				`Returns the product catalog with plan IDs, prices (USDC on ${networkName}), wallet address, and chain ID.`,
-				`POST to ${baseUrl}/x402/access with an empty body or without planId to discover products.`,
+				`GET to ${baseUrl}/discovery to discover plans.`,
 			].join(" "),
 			tags: ["discovery", "catalog", "x402"],
-			examples: [
-				`POST ${baseUrl}/x402/access with empty body {}`,
-				`Or call without planId to get 402 response with product catalog`,
-			],
+			examples: [`GET ${baseUrl}/discovery`],
+			endpoint: { url: `${baseUrl}/discovery`, method: "GET" },
 		},
 		{
 			id: "request-access",
 			name: "Request Access",
 			description: [
 				`Purchase access to a ${config.agentName} product plan via x402 payment on ${networkName}.`,
-				`First call discover-products to get available plans.`,
+				`First call discover-plans to get available plans.`,
 				`Then POST to ${baseUrl}/x402/access with planId and requestId to initiate purchase.`,
 				`Server responds with x402 payment challenge.`,
 				`Complete payment on-chain and include PAYMENT-SIGNATURE header to receive access token.`,
@@ -43,6 +43,22 @@ export function buildAgentCard(config: SellerConfig): AgentCard {
 				`Pay USDC on-chain, retry same request with PAYMENT-SIGNATURE header`,
 				`Receive 200 with access token`,
 			],
+			endpoint: { url: `${baseUrl}/x402/access`, method: "POST" },
+			inputSchema: {
+				type: "object",
+				required: ["planId", "requestId"],
+				properties: {
+					planId: { type: "string", enum: planIds },
+					requestId: { type: "string", format: "uuid" },
+				},
+			},
+			workflow: [
+				"POST body with planId + requestId to endpoint.url — expect 402",
+				"Extract payment requirements from 402 response body",
+				`Sign and broadcast USDC transfer on ${networkName}`,
+				"Retry same POST with PAYMENT-SIGNATURE header containing the transaction hash",
+				"Receive 200 with accessToken",
+			],
 		},
 	];
 

package/src/core/challenge-engine.ts

@@ -109,7 +109,7 @@ export class ChallengeEngine {
 			chainId: record.chainId,
 			destination: record.destination,
 			expiresAt: record.expiresAt.toISOString(),
-			description: `Send ${record.amount} USDC to ${record.destination} on chain ${record.chainId}. Then call the "submit-proof" skill with a PaymentProof containing the txHash, challengeId "${record.challengeId}", requestId "${record.requestId}", chainId ${record.chainId}, amount "${record.amount}", asset "USDC", and your fromAgentId.`,
+			description: `Send ${record.amount} USDC to ${record.destination} on chain ${record.chainId}. Then replay the same POST /x402/access request with the PAYMENT-SIGNATURE header containing the signed EIP-3009 authorization for challengeId "${record.challengeId}", requestId "${record.requestId}", chainId ${record.chainId}, amount "${record.amount}", asset "USDC".`,
 			resourceVerified: true,
 		};
 	}

package/src/core/index.ts

@@ -12,7 +12,7 @@ export { ChallengeEngine } from "./challenge-engine.js";
 export { validateSellerConfig } from "./config-validation.js";
 export type { RefundConfig, RefundResult } from "./refund.js";
 // Refund Utility
-export { processRefunds } from "./refund.js";
+export { processRefunds, retryFailedRefunds } from "./refund.js";
 export type { PostgresStoreConfig } from "./storage/postgres.js";
 // Storage — Postgres
 export {