@a2hmarket/a2hmarket 2026.3.19

package/src/tools/tool-inbox.ts

@@ -0,0 +1,149 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { pullEvents, ackEvent, getEvent, historyByPeer } from "../api/inbox.js";
+
+export function registerInboxTools(api: OpenClawPluginApi): void {
+  api.registerTool(
+    {
+      name: "inbox_pull",
+      label: "Inbox Pull",
+      description:
+        "Pull unread messages from the A2HMarket inbox. Returns a list of pending messages from other agents.",
+      parameters: Type.Object({
+        limit: Type.Optional(
+          Type.Number({ description: "Max messages to pull (default: 10, max: 50)" }),
+        ),
+        cursor: Type.Optional(
+          Type.Number({ description: "Sequence cursor for pagination (default: 0)" }),
+        ),
+        peerId: Type.Optional(
+          Type.String({ description: "Filter messages from a specific agent ID" }),
+        ),
+      }),
+      execute(_toolCallId, params) {
+        const { limit = 10, cursor = 0, peerId } = params as {
+          limit?: number;
+          cursor?: number;
+          peerId?: string;
+        };
+        const safeLimit = Math.min(Math.max(1, limit), 50);
+
+        const result = pullEvents("default", cursor, safeLimit, peerId);
+
+        const items = result.events;
+        const messages = items.map((ev) => ({
+          event_id: ev.event_id,
+          peer_id: ev.peer_id,
+          preview: ev.preview,
+          payload: ev.payload,
+          created_at: ev.created_at,
+        }));
+        const text =
+          items.length === 0
+            ? "No new messages."
+            : `${items.length} message(s) (cursor: ${result.cursor}):\n${JSON.stringify(messages, null, 2)}`;
+
+        return {
+          content: [{ type: "text", text }],
+          details: {
+            ok: true,
+            count: items.length,
+            cursor: result.cursor,
+            messages,
+          },
+        };
+      },
+    },
+    { name: "inbox_pull" },
+  );
+
+  api.registerTool(
+    {
+      name: "inbox_ack",
+      label: "Inbox Ack",
+      description:
+        "Acknowledge (mark as processed) a message in the A2HMarket inbox. Always call this after reading a message.",
+      parameters: Type.Object({
+        eventId: Type.String({ description: "The event ID of the message to acknowledge" }),
+      }),
+      execute(_toolCallId, params) {
+        const { eventId } = params as { eventId: string };
+
+        const result = ackEvent("default", eventId);
+
+        return {
+          content: [{ type: "text", text: `Message ${eventId} acknowledged.` }],
+          details: { ok: true, eventId, ackedAt: result.acked_at },
+        };
+      },
+    },
+    { name: "inbox_ack" },
+  );
+
+  api.registerTool(
+    {
+      name: "inbox_get",
+      label: "Inbox Get",
+      description:
+        "Get the full payload of a single inbox message by event ID. Use this after inbox_pull to inspect attachment metadata, payment QR URLs, or other detailed fields not included in the preview.",
+      parameters: Type.Object({
+        eventId: Type.String({ description: "The event ID of the message to retrieve" }),
+      }),
+      execute(_toolCallId, params) {
+        const { eventId } = params as { eventId: string };
+
+        const ev = getEvent(eventId);
+        if (!ev) {
+          return {
+            content: [{ type: "text", text: `Event not found: ${eventId}` }],
+            details: { ok: false, error: `event not found: ${eventId}` },
+          };
+        }
+
+        return {
+          content: [{ type: "text", text: `Event ${eventId}:\n${JSON.stringify(ev, null, 2)}` }],
+          details: { ok: true, event: ev },
+        };
+      },
+    },
+    { name: "inbox_get" },
+  );
+
+  api.registerTool(
+    {
+      name: "inbox_history",
+      label: "Inbox History",
+      description:
+        "Query message history with a specific peer agent. Returns received (inbound) messages only — outbound messages are not stored in the inbox queue and cannot be retrieved here.",
+      parameters: Type.Object({
+        peerId: Type.String({ description: "The peer agent ID to fetch history for" }),
+        page: Type.Optional(Type.Number({ description: "Page number (1-based, default: 1)" })),
+        limit: Type.Optional(
+          Type.Number({ description: "Messages per page (default: 20, max: 100)" }),
+        ),
+      }),
+      execute(_toolCallId, params) {
+        const { peerId, page = 1, limit = 20 } = params as {
+          peerId: string;
+          page?: number;
+          limit?: number;
+        };
+        const safeLimit = Math.min(Math.max(1, limit), 100);
+        const safePage = Math.max(1, page);
+
+        const result = historyByPeer(peerId, safePage, safeLimit);
+
+        const text =
+          result.items.length === 0
+            ? `No message history found with peer ${peerId}.`
+            : `${result.total} message(s) with ${peerId} (page ${safePage}, showing ${result.items.length}):\n${JSON.stringify(result, null, 2)}`;
+
+        return {
+          content: [{ type: "text", text }],
+          details: { ok: true, ...result },
+        };
+      },
+    },
+    { name: "inbox_history" },
+  );
+}

package/src/tools/tool-order.ts

@@ -0,0 +1,210 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { createApiClient } from "../api-client.js";
+import { orderCreate, orderGet, orderAction, orderList } from "../api/order.js";
+import type { OrderAction } from "../api/order.js";
+
+// Valid order actions (underscore variant for tool input, hyphen variant for API)
+const ORDER_ACTIONS = [
+  "confirm",
+  "reject",
+  "cancel",
+  "confirm_received",
+  "confirm_service_completed",
+] as const;
+
+type ToolOrderAction = (typeof ORDER_ACTIONS)[number];
+
+/** Convert tool action (underscores) to API action (hyphens). */
+function toApiAction(action: ToolOrderAction): OrderAction {
+  return action.replace(/_/g, "-") as OrderAction;
+}
+
+export function registerOrderTools(api: OpenClawPluginApi): void {
+  api.registerTool(
+    {
+      name: "order_create",
+      label: "Order Create",
+      description: "Create a new order on the A2HMarket platform.",
+      parameters: Type.Object({
+        customerId: Type.String({ description: "Customer agent ID" }),
+        title: Type.String({ description: "Order title/description" }),
+        priceCent: Type.Number({
+          description: "Price in cents (e.g. 9900 = 99.00 yuan)",
+        }),
+        productId: Type.String({ description: "Product/works ID being ordered" }),
+        orderType: Type.Number({
+          description:
+            "Order type: 2=seller takes buyer demand task, 3=buyer purchases seller existing service",
+        }),
+      }),
+      async execute(_toolCallId, params) {
+        const { customerId, title, priceCent, productId, orderType } = params as {
+          customerId: string;
+          title: string;
+          priceCent: number;
+          productId: string;
+          orderType: number;
+        };
+
+        try {
+          const client = createApiClient();
+          const result = await orderCreate(client, {
+            customerId,
+            title,
+            content: title,
+            price: priceCent,
+            productId,
+            orderType: orderType as 2 | 3,
+          });
+
+          const data = result as Record<string, unknown>;
+          const orderId = (data?.order_id ?? data?.orderId ?? "unknown") as string;
+
+          return {
+            content: [{ type: "text", text: `Order created. Order ID: ${orderId}` }],
+            details: { ok: true, orderId, result },
+          };
+        } catch (err) {
+          const errMsg = String(err);
+          return {
+            content: [{ type: "text", text: `Order creation failed: ${errMsg}` }],
+            details: { ok: false, error: errMsg },
+          };
+        }
+      },
+    },
+    { name: "order_create" },
+  );
+
+  api.registerTool(
+    {
+      name: "order_get",
+      label: "Order Get",
+      description: "Query the details of an order by order ID.",
+      parameters: Type.Object({
+        orderId: Type.String({ description: "The order ID to look up" }),
+      }),
+      async execute(_toolCallId, params) {
+        const { orderId } = params as { orderId: string };
+
+        try {
+          const client = createApiClient();
+          const order = await orderGet(client, orderId);
+
+          return {
+            content: [{ type: "text", text: `Order ${orderId}:\n${JSON.stringify(order, null, 2)}` }],
+            details: { ok: true, order },
+          };
+        } catch (err) {
+          const errMsg = String(err);
+          return {
+            content: [
+              { type: "text", text: `Failed to get order ${orderId}: ${errMsg}` },
+            ],
+            details: { ok: false, error: errMsg },
+          };
+        }
+      },
+    },
+    { name: "order_get" },
+  );
+
+  api.registerTool(
+    {
+      name: "order_action",
+      label: "Order Action",
+      description:
+        "Perform an action on an order: confirm, reject, cancel, confirm_received, or confirm_service_completed.",
+      parameters: Type.Object({
+        orderId: Type.String({ description: "The order ID" }),
+        action: Type.Unsafe<ToolOrderAction>({
+          type: "string",
+          enum: [...ORDER_ACTIONS],
+          description:
+            "Action to perform: confirm | reject | cancel | confirm_received | confirm_service_completed",
+        }),
+      }),
+      async execute(_toolCallId, params) {
+        const { orderId, action } = params as {
+          orderId: string;
+          action: ToolOrderAction;
+        };
+
+        try {
+          const client = createApiClient();
+          const result = await orderAction(client, orderId, toApiAction(action));
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Order ${orderId}: action "${action}" completed successfully.`,
+              },
+            ],
+            details: { ok: true, orderId, action, result },
+          };
+        } catch (err) {
+          const errMsg = String(err);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Order action "${action}" failed for order ${orderId}: ${errMsg}`,
+              },
+            ],
+            details: { ok: false, error: errMsg },
+          };
+        }
+      },
+    },
+    { name: "order_action" },
+  );
+
+  api.registerTool(
+    {
+      name: "order_list",
+      label: "Order List",
+      description: "List sales or purchase orders on the A2HMarket platform.",
+      parameters: Type.Object({
+        kind: Type.Unsafe<"sales" | "purchase">({
+          type: "string",
+          enum: ["sales", "purchase"],
+          description: "Order list type: sales=as seller, purchase=as buyer",
+        }),
+        page: Type.Optional(Type.Number({ description: "Page number (1-based, default: 1)" })),
+        pageSize: Type.Optional(Type.Number({ description: "Page size (default: 10)" })),
+        status: Type.Optional(Type.String({ description: "Filter by order status" })),
+      }),
+      async execute(_toolCallId, params) {
+        const { kind, page, pageSize, status } = params as {
+          kind: "sales" | "purchase";
+          page?: number;
+          pageSize?: number;
+          status?: string;
+        };
+
+        try {
+          const client = createApiClient();
+          const result = await orderList(client, kind, {
+            page: page ?? 1,
+            pageSize: pageSize ?? 10,
+            status,
+          });
+
+          return {
+            content: [{ type: "text", text: `${kind} orders:\n${JSON.stringify(result, null, 2)}` }],
+            details: { ok: true, result },
+          };
+        } catch (err) {
+          const errMsg = String(err);
+          return {
+            content: [{ type: "text", text: `Order list failed: ${errMsg}` }],
+            details: { ok: false, error: errMsg },
+          };
+        }
+      },
+    },
+    { name: "order_list" },
+  );
+}

package/src/tools/tool-profile.ts

@@ -0,0 +1,40 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { createApiClient } from "../api-client.js";
+import { profileGet } from "../api/profile.js";
+
+export function registerProfileTool(api: OpenClawPluginApi): void {
+  api.registerTool(
+    {
+      name: "profile_get",
+      label: "Profile Get",
+      description: "Get your own A2HMarket agent profile information.",
+      parameters: Type.Object({}),
+      async execute(_toolCallId, _params) {
+        try {
+          const client = createApiClient();
+          const profile = await profileGet(client);
+
+          const nickname = profile.nickname ?? "unknown";
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Profile (${nickname}):\n${JSON.stringify(profile, null, 2)}`,
+              },
+            ],
+            details: { ok: true, profile },
+          };
+        } catch (err) {
+          const errMsg = String(err);
+          return {
+            content: [{ type: "text", text: `Failed to get profile: ${errMsg}` }],
+            details: { ok: false, error: errMsg },
+          };
+        }
+      },
+    },
+    { name: "profile_get" },
+  );
+}

package/src/tools/tool-send.ts

@@ -0,0 +1,81 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { readCredentials } from "../credentials.js";
+import { sendMessage } from "../api/send.js";
+
+export function registerSendTool(api: OpenClawPluginApi): void {
+  api.registerTool(
+    {
+      name: "send_message",
+      label: "Send Message",
+      description:
+        "Send an A2A message to another agent on the A2HMarket platform.",
+      parameters: Type.Object({
+        targetAgentId: Type.String({
+          description: "The target agent ID (e.g. ag_xxx)",
+        }),
+        text: Type.String({
+          description: "The message text to send",
+        }),
+        attachmentUrl: Type.Optional(
+          Type.String({ description: "Optional attachment URL" }),
+        ),
+        paymentQr: Type.Optional(
+          Type.String({ description: "Payment QR code image URL" }),
+        ),
+      }),
+      async execute(_toolCallId, params) {
+        const { targetAgentId, text, attachmentUrl, paymentQr } = params as {
+          targetAgentId: string;
+          text: string;
+          attachmentUrl?: string;
+          paymentQr?: string;
+        };
+
+        const creds = readCredentials();
+        if (!creds) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "A2HMarket not configured. Run: openclaw a2h setup",
+              },
+            ],
+            details: { ok: false, error: "not_configured" },
+          };
+        }
+
+        try {
+          const result = await sendMessage(creds, {
+            targetAgentId,
+            text,
+            attachmentUrl,
+            paymentQr,
+          });
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Message sent to ${targetAgentId}. Message ID: ${result.message_id}`,
+              },
+            ],
+            details: { ok: true, messageId: result.message_id },
+          };
+        } catch (err) {
+          const errMsg = String(err);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Failed to send message to ${targetAgentId}: ${errMsg}`,
+              },
+            ],
+            details: { ok: false, error: errMsg },
+          };
+        }
+      },
+    },
+    { name: "send_message" },
+  );
+}