@arc402/sdk 0.2.0 → 0.3.1

package/README.md

@@ -1,5 +1,7 @@
 # @arc402/sdk
 
+[![npm](https://img.shields.io/npm/v/@arc402/sdk?color=blue)](https://www.npmjs.com/package/@arc402/sdk)
+
 Typed TypeScript SDK for the current ARC-402 network workflow: discovery, off-chain negotiation payloads, escrowed hiring, delivery verification, remediation, disputes, reputation signals, sponsorship, canonical capability taxonomy, governance reads, and operational-context reads.
 
 Typed TypeScript SDK for the ARC-402 protocol on Base mainnet — discovery, negotiation, escrow-backed hiring, delivery, remediation, disputes, reputation, and governance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc402/sdk",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "ARC-402 typed TypeScript SDK for discovery, negotiation, trust, and governed settlement",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/endpoint.ts

@@ -0,0 +1,142 @@
+/**
+ * HTTP endpoint helpers — resolve an agent's endpoint from AgentRegistry
+ * and notify it after onchain events (hire, handshake).
+ */
+import { ethers } from "ethers";
+import { AGENT_REGISTRY_ABI } from "./contracts";
+
+export const DEFAULT_REGISTRY_ADDRESS = "0xD5c2851B00090c92Ba7F4723FB548bb30C9B6865";
+
+export interface EndpointNotifyResult {
+  ok: boolean;
+  status?: number;
+  error?: string;
+}
+
+/**
+ * Reads an agent's public HTTP endpoint from AgentRegistry.
+ * Returns an empty string if the agent is not registered or has no endpoint.
+ */
+export async function resolveEndpoint(
+  agentAddress: string,
+  provider: ethers.Provider,
+  registryAddress = DEFAULT_REGISTRY_ADDRESS
+): Promise<string> {
+  const registry = new ethers.Contract(registryAddress, AGENT_REGISTRY_ABI, provider);
+  const agentData = await registry.getAgent(agentAddress);
+  return (agentData.endpoint as string) ?? "";
+}
+
+/**
+ * POSTs a JSON payload to `${endpoint}${path}`.
+ * Returns { ok, status } on success, { ok: false, error } on failure.
+ * Never throws.
+ */
+export async function notifyEndpoint(
+  endpoint: string,
+  path: string,
+  payload: Record<string, unknown>
+): Promise<EndpointNotifyResult> {
+  if (!endpoint) return { ok: false, error: "no endpoint" };
+  try {
+    const res = await fetch(`${endpoint}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    return { ok: res.ok, status: res.status };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Convenience: resolve an agent's endpoint then POST to /hire.
+ */
+export async function notifyHire(
+  agentAddress: string,
+  proposal: Record<string, unknown>,
+  provider: ethers.Provider,
+  registryAddress = DEFAULT_REGISTRY_ADDRESS
+): Promise<EndpointNotifyResult> {
+  const endpoint = await resolveEndpoint(agentAddress, provider, registryAddress);
+  return notifyEndpoint(endpoint, "/hire", proposal);
+}
+
+/**
+ * Convenience: resolve an agent's endpoint then POST to /handshake.
+ */
+export async function notifyHandshake(
+  agentAddress: string,
+  payload: Record<string, unknown>,
+  provider: ethers.Provider,
+  registryAddress = DEFAULT_REGISTRY_ADDRESS
+): Promise<EndpointNotifyResult> {
+  const endpoint = await resolveEndpoint(agentAddress, provider, registryAddress);
+  return notifyEndpoint(endpoint, "/handshake", payload);
+}
+
+/**
+ * Convenience: resolve an agent's endpoint then POST to /hire/accepted.
+ */
+export async function notifyHireAccepted(
+  agentAddress: string,
+  payload: Record<string, unknown>,
+  provider: ethers.Provider,
+  registryAddress = DEFAULT_REGISTRY_ADDRESS
+): Promise<EndpointNotifyResult> {
+  const endpoint = await resolveEndpoint(agentAddress, provider, registryAddress);
+  return notifyEndpoint(endpoint, "/hire/accepted", payload);
+}
+
+/**
+ * Convenience: resolve an agent's endpoint then POST to /delivery.
+ */
+export async function notifyDelivery(
+  agentAddress: string,
+  payload: Record<string, unknown>,
+  provider: ethers.Provider,
+  registryAddress = DEFAULT_REGISTRY_ADDRESS
+): Promise<EndpointNotifyResult> {
+  const endpoint = await resolveEndpoint(agentAddress, provider, registryAddress);
+  return notifyEndpoint(endpoint, "/delivery", payload);
+}
+
+/**
+ * Convenience: resolve an agent's endpoint then POST to /delivery/accepted.
+ */
+export async function notifyDeliveryAccepted(
+  agentAddress: string,
+  payload: Record<string, unknown>,
+  provider: ethers.Provider,
+  registryAddress = DEFAULT_REGISTRY_ADDRESS
+): Promise<EndpointNotifyResult> {
+  const endpoint = await resolveEndpoint(agentAddress, provider, registryAddress);
+  return notifyEndpoint(endpoint, "/delivery/accepted", payload);
+}
+
+/**
+ * Convenience: resolve an agent's endpoint then POST to /dispute.
+ */
+export async function notifyDispute(
+  agentAddress: string,
+  payload: Record<string, unknown>,
+  provider: ethers.Provider,
+  registryAddress = DEFAULT_REGISTRY_ADDRESS
+): Promise<EndpointNotifyResult> {
+  const endpoint = await resolveEndpoint(agentAddress, provider, registryAddress);
+  return notifyEndpoint(endpoint, "/dispute", payload);
+}
+
+/**
+ * Convenience: resolve an agent's endpoint then POST to /message.
+ */
+export async function notifyMessage(
+  agentAddress: string,
+  payload: Record<string, unknown>,
+  provider: ethers.Provider,
+  registryAddress = DEFAULT_REGISTRY_ADDRESS
+): Promise<EndpointNotifyResult> {
+  const endpoint = await resolveEndpoint(agentAddress, provider, registryAddress);
+  return notifyEndpoint(endpoint, "/message", payload);
+}

package/src/index.ts

@@ -29,3 +29,5 @@ export { buildMetadata, validateMetadata, encodeMetadata, decodeMetadata, upload
 export type { AgentMetadata, AgentMetadataModel, AgentMetadataTraining, AgentMetadataPricing, AgentMetadataSla, AgentMetadataContact, AgentMetadataSecurity } from "./metadata";
 export { ColdStartClient } from "./coldstart";
 export { MigrationClient } from "./migration";
+export { resolveEndpoint, notifyEndpoint, notifyHire, notifyHandshake, notifyHireAccepted, notifyDelivery, notifyDeliveryAccepted, notifyDispute, notifyMessage, DEFAULT_REGISTRY_ADDRESS } from "./endpoint";
+export type { EndpointNotifyResult } from "./endpoint";