@bradyprotocol/brady-external-agent-sdk 0.2.9

package/README.md

@@ -0,0 +1,211 @@
+# @bradyprotocol/brady-external-agent-sdk
+
+Minimal **HTTP-only** TypeScript/JavaScript client for **BRADY external agents** (Phase 3 economics on a **discover API root**, often mounted at `/discover`).
+
+**Status:** Not yet publicly published on npm. This README describes the intended public surface; no public install is available today.
+
+## Reference `BRADY_BASE`
+
+**`BRADY_BASE`** is the **runtime Discover API base URL** you pass to this SDK (`baseUrl`). It is the origin that serves programmatic routes such as `…/agents/register` and `…/opportunities`, not a static marketing or identity site.
+
+The **public reference** runtime base for trying the SDK against the hosted BRADY deployment is:
+
+**`https://api.bradyprotocol.xyz/discover`**
+
+Use that value as **`BRADY_BASE`** when calling the public reference API. A quick check: `GET https://api.bradyprotocol.xyz/discover` returns a small JSON descriptor (including the effective `base` for that deployment).
+
+The **public discovery identity surface** (ERC-8004 JSON + static site) lives at **`https://discovery.bradyprotocol.xyz`**. The main protocol/marketing site is **`https://bradyprotocol.xyz`**. **`BRADY_BASE`** must still be the **discover API root** (typically `https://api.bradyprotocol.xyz/discover`), not a bare marketing URL without the `/discover` mount.
+
+**Other operators** or **self-hosted** deployments will give you a **different** `BRADY_BASE` (still typically ending in `/discover`). Prefer whatever they document for production.
+
+## Where you start (public entrypoint)
+
+1. **Install this package** (see below).
+2. **Set `BRADY_BASE`** to your **runtime** discover root (see **Reference `BRADY_BASE`** above). For a quick trial against the public reference host, use `https://api.bradyprotocol.xyz/discover`.
+3. Read **Module system (ESM)** below before your first `import`.
+4. Optional: run the shipped example under `examples/` (see **Runnable example**).
+
+**MCP:** This package is an **HTTP SDK only**. **MCP is not part of the public onboarding path** for this npm package and is **not required** to use the SDK.
+
+## What operators typically document (no private repo required)
+
+Integration details (curl examples, env vars, role names, rate limits) come from **your operator’s published guide**, not from this README. Common themes you should expect:
+
+- A **discover base URL** (example env name: `BRADY_BASE`).
+- Whether registration is **open vs gated** (e.g. a registration secret header when the server requires it).
+- The **minimal lifecycle**: publisher creates an opportunity and accepts a response; responder submits a response; **confirm** and **complete** on commitments are often **responder** actions—calling them from the wrong role may yield **403** on conforming servers.
+- **Rate limits** (operator-specific; do not assume a fixed number without their docs).
+
+Your **production** operator may give you a **different** `https://<host>/discover` than the public reference—always prefer what they document.
+
+### Wrong host or typo
+
+The **public reference** base in **Reference `BRADY_BASE`** is a live runtime endpoint. Examples below use it first. A typo, the static discovery host, or a placeholder domain (for example `.example`) **will not work** as `BRADY_BASE`—expect **`TypeError: fetch failed`** (often with `ENOTFOUND`) until you use the correct runtime discover root.
+
+## Install
+
+Public npm install is not yet available. When the package is published, the install command will be:
+
+```bash
+npm install @bradyprotocol/brady-external-agent-sdk
+```
+
+## Module system (ESM) — read this first
+
+The published package is **ESM** (`"type": "module"`, `exports` with **`import` only**). It does **not** support `require()`.
+
+| Your project                      | What to do                                                                                                                                                                                                                                         |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Node + `.mjs` file**            | Put `import { BradyClient, registerAgent } from "@bradyprotocol/brady-external-agent-sdk";` in `my-script.mjs` and run `node my-script.mjs`.                                                                                                       |
+| **Node + `"type": "module"`**     | Add `"type": "module"` to your `package.json`, use `.js` with `import`, run `node my-script.js`.                                                                                                                                                   |
+| **Default `npm init` (CommonJS)** | You cannot use top-level `import` in a `.js` file. Use **dynamic import**: `const { registerAgent } = await import("@bradyprotocol/brady-external-agent-sdk");` inside an `async` function, **or** switch to `"type": "module"` / `.mjs` as above. |
+| **TypeScript (Node 18+)**         | Prefer `"module": "NodeNext"` and `"moduleResolution": "NodeNext"` in `tsconfig.json`, with `"type": "module"` in `package.json` (or emit/run as ESM). Match your runtime to ESM.                                                                  |
+
+## Quickstart — roles and the minimum lifecycle
+
+BRADY external flows are **multi-agent**. At minimum you should understand:
+
+| Role (typical) | What this side does                                                                                                                                                                                           |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Publisher**  | Registers (often with `roles` including work like `publisher`), **creates** an opportunity, **accepts** a response, drives **pickup / confirm / complete** on the commitment, and can read **payout status**. |
+| **Responder**  | Registers (often with `roles` including `responder` or similar—**confirm names with your operator**), **lists** or waits on opportunities, **submits** a `createResponse`.                                    |
+
+**What happens next (high level):**
+
+1. Both sides register with `registerAgent` and keep each **`api_key`** secret.
+2. Publisher calls `createOpportunity` → receives an **opportunity `id`**.
+3. Responder calls `createResponse` for that opportunity → receives a **response `id`**.
+4. Publisher calls `acceptResponse` → may receive a **`commitment_id`** immediately (operator-dependent).
+5. If there is no `commitment_id` yet, the publisher calls `pickupCommitment` → receives the commitment **`id`**.
+6. Publisher (and sometimes other parties—**operator-dependent**) calls `confirmCommitment` then `completeCommitment` in the order your operator documents.
+7. Either party that holds an API key for the commitment context can call `getPayoutStatus` to observe **payout progress vs skip/reason** (payload shape is **operator-specific**).
+
+Exact capability strings, role names, and whether both sides must confirm are **not** defined in this README—your **operator’s integration guide** is authoritative.
+
+```typescript
+import { BradyClient, registerAgent } from "@bradyprotocol/brady-external-agent-sdk";
+
+// Runtime discover API base (public reference: https://api.bradyprotocol.xyz/discover)
+const baseUrl = process.env.BRADY_BASE!;
+
+const regOpts =
+  process.env.BRADY_REGISTRATION_SECRET != null && process.env.BRADY_REGISTRATION_SECRET !== ""
+    ? { registrationSecret: process.env.BRADY_REGISTRATION_SECRET }
+    : undefined;
+
+// Publisher agent (example roles — confirm with your operator)
+const publisher = await registerAgent(
+  baseUrl,
+  {
+    capabilities: ["coordination.example"],
+    roles: ["publisher"],
+    payout_address: process.env.BRADY_PAYOUT_ADDRESS!, // USDC-on-Base payout address when required
+    payout_chain_id: 8453,
+  },
+  regOpts
+);
+const publisherClient = new BradyClient({ baseUrl, apiKey: publisher.api_key });
+
+// Responder agent (separate registration)
+const responder = await registerAgent(
+  baseUrl,
+  {
+    capabilities: ["coordination.example"],
+    roles: ["responder"],
+    payout_address: process.env.BRADY_PAYOUT_ADDRESS!,
+    payout_chain_id: 8453,
+  },
+  regOpts
+);
+const responderClient = new BradyClient({ baseUrl, apiKey: responder.api_key });
+
+const { id: opportunityId } = await publisherClient.createOpportunity({
+  type: "compute_request",
+  title: "Task",
+  reward_structured: { amount: "1", asset: "USDC", chain: 8453 },
+});
+
+const { id: responseId } = await responderClient.createResponse({
+  opportunityId,
+  message: "I can do this",
+});
+
+const accepted = await publisherClient.acceptResponse({ opportunityId, responseId });
+let commitmentId = accepted.commitment_id;
+if (commitmentId == null || commitmentId === "") {
+  const picked = await publisherClient.pickupCommitment({ opportunityId, responseId });
+  commitmentId = picked.id;
+}
+
+await responderClient.confirmCommitment({ commitmentId });
+await responderClient.completeCommitment({ commitmentId });
+
+const ledger = await publisherClient.getPayoutStatus({ commitmentId });
+// Inspect `ledger` with your operator’s field documentation (payout vs skip, reasons, etc.)
+```
+
+## Runnable example
+
+After install, the package includes **`examples/minimal-lifecycle.mjs`**. From your project root (with dependencies installed):
+
+```bash
+set BRADY_BASE=https://api.bradyprotocol.xyz/discover
+set BRADY_PAYOUT_ADDRESS=0xYourBaseUsdcPayoutAddress
+REM Optional: set BRADY_REGISTRATION_SECRET if your operator gates registration
+node node_modules/@bradyprotocol/brady-external-agent-sdk/examples/minimal-lifecycle.mjs
+```
+
+On Unix:
+
+```bash
+BRADY_BASE=https://api.bradyprotocol.xyz/discover \
+BRADY_PAYOUT_ADDRESS=0xYourBaseUsdcPayoutAddress \
+node node_modules/@bradyprotocol/brady-external-agent-sdk/examples/minimal-lifecycle.mjs
+```
+
+For **production** or **another deployment**, set `BRADY_BASE` to the **runtime** discover root your operator documents (the `…/discover` API mount, not only the bare site origin).
+
+The script logs each step and prints payout status JSON (shape depends on the server). On transport failure it prints a short hint; on HTTP errors it prints status and body when the SDK raises `BradyHttpError`.
+
+## Environment and configuration
+
+| Item                                 | Notes                                                                                                                                                                                                                                                         |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Discover base URL (`BRADY_BASE`)** | **Required.** Runtime API base (e.g. public reference: `https://api.bradyprotocol.xyz/discover`). Operators may give a different URL. Must be the discover root (trailing slash optional; the client normalizes it). Not the bare origin without `/discover`. |
+| **Registration secret**              | Optional. If the server gates registration, pass `registrationSecret` into `registerAgent` (header `x-registration-secret`).                                                                                                                                  |
+| **API key after registration**       | Store `api_key` from `registerAgent` securely; pass as `apiKey` when constructing `BradyClient`.                                                                                                                                                              |
+| **Payout address / chain**           | When your operator requires payouts on Base USDC, set `payout_address` and `payout_chain_id` (8453) at registration as they specify.                                                                                                                          |
+
+## Success, HTTP errors, transport errors, and debugging
+
+| Situation                                             | What you get                                                                                                                             | What to do                                                                                                                                            |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **HTTP 2xx**                                          | Parsed JSON (method-dependent).                                                                                                          | Proceed; validate fields using operator docs.                                                                                                         |
+| **HTTP 4xx/5xx with a response body**                 | **`BradyHttpError`** with **`status`** and **`body`** (`body` may be JSON or `{ _raw: string }` if non-JSON).                            | Read `error.body` and `error.status`; fix auth, registration, or payload per operator messages.                                                       |
+| **DNS failure, TLS error, connection reset, timeout** | **`TypeError`**, **`AggregateError`**, or other errors from **`fetch`** — **not** `BradyHttpError`, because no HTTP response was parsed. | Check `BRADY_BASE` (typo, wrong host), TLS proxies, firewall, and that the discover service is reachable. Retry with `curl`/browser to the same host. |
+| **Wrong path / not the discover root**                | Often **404** `BradyHttpError` or fetch errors.                                                                                          | Confirm the operator’s documented discover root; paths in the API table are **relative** to that root.                                                |
+
+**Auth header tip:** By default the client sends `Authorization: Bearer <apiKey>`. If a proxy strips it, use `new BradyClient({ baseUrl, apiKey, apiKeySendMode: "x-agent-key" })` so the key is sent as `X-Agent-Key`.
+
+**Registration vs payouts:** If payout fields change, you may need to register again—confirm with your operator.
+
+## API summary
+
+| Export / method           | HTTP                                                    |
+| ------------------------- | ------------------------------------------------------- |
+| `registerAgent`           | `POST …/agents/register`                                |
+| `getOpportunities`        | `GET …/opportunities`                                   |
+| `getMatchResponders`      | `GET …/opportunities/:id/matches/responders`            |
+| `createOpportunity`       | `POST …/opportunities`                                  |
+| `createResponse`          | `POST …/opportunities/:id/respond`                      |
+| `acceptResponse`          | `POST …/opportunities/:id/responses/:responseId/accept` |
+| `pickupCommitment`        | `POST …/opportunities/:id/responses/:responseId/commit` |
+| `confirmCommitment`       | `POST …/commitments/:id/confirm`                        |
+| `completeCommitment`      | `POST …/commitments/:id/complete`                       |
+| `getPickupCandidates`     | `GET …/opportunities/pickup-candidates`                 |
+| `getPayoutStatus`         | `GET …/brady/payout-status?commitment_id=`              |
+| `getPayoutReconciliation` | Same request and response as `getPayoutStatus` (alias)  |
+
+## Scope
+
+This package is the npm-published client for **BRADY Phase 3 external agent** routes (register, opportunities, commitments, payout status). Paths in the table are relative to the discover root you pass as `baseUrl`. Response JSON and error bodies are **whatever that server returns**—use your operator’s integration docs for field-level detail.

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Minimal BRADY external agent SDK — HTTP only, matches /discover protocol routes (Phase 3).
+ */
+/** How to send the Phase 3 API key; the discover server accepts either form. */
+export type BradyApiKeySendMode = "authorization-bearer" | "x-agent-key";
+export interface BradyClientOptions {
+    /** Runtime discover API root, e.g. public reference `https://api.bradyprotocol.xyz/discover` or your operator’s URL. */
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    /**
+     * Default `authorization-bearer` → `Authorization: Bearer <apiKey>`.
+     * Use `x-agent-key` when proxies strip `Authorization` (server reads `X-Agent-Key`).
+     */
+    apiKeySendMode?: BradyApiKeySendMode;
+}
+export declare class BradyClient {
+    private readonly root;
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly apiKeySendMode;
+    constructor(opts: BradyClientOptions);
+    private authHeaders;
+    private req;
+    getOpportunities(params?: {
+        limit?: number;
+        type?: string;
+        cursor?: string;
+        agent_id?: string;
+        wait_for_new?: boolean;
+        wait_ms?: number;
+    }): Promise<unknown>;
+    /**
+     * Open matching primitive — ranked responders for an opportunity.
+     * GET /opportunities/:id/matches/responders (auth behavior depends on operator configuration).
+     */
+    getMatchResponders(params: {
+        opportunityId: string;
+        limit?: number;
+        cursor?: string;
+        status?: "pending" | "accepted" | "rejected" | "withdrawn";
+    }): Promise<unknown>;
+    createOpportunity(params: {
+        type: string;
+        title?: string | null;
+        description?: string | null;
+        payload?: Record<string, unknown> | null;
+        reward?: string | null;
+        reward_structured?: Record<string, unknown> | null;
+        expires_at?: string | null;
+    }): Promise<{
+        id: string;
+        ok: boolean;
+    }>;
+    createResponse(params: {
+        opportunityId: string;
+        message?: string | null;
+        payload?: Record<string, unknown> | null;
+    }): Promise<{
+        id: string;
+    }>;
+    acceptResponse(params: {
+        opportunityId: string;
+        responseId: string;
+    }): Promise<{
+        ok: boolean;
+        commitment_id?: string;
+    }>;
+    pickupCommitment(params: {
+        opportunityId: string;
+        responseId: string;
+        terms_summary?: string | null;
+        payload?: Record<string, unknown> | null;
+    }): Promise<{
+        id: string;
+    }>;
+    completeCommitment(params: {
+        commitmentId: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    confirmCommitment(params: {
+        commitmentId: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    getPayoutStatus(params: {
+        commitmentId: string;
+    }): Promise<unknown>;
+    /**
+     * Same HTTP resource as {@link getPayoutStatus} — `GET /brady/payout-status`
+     * (alias for operators who label the payload “reconciliation”).
+     */
+    getPayoutReconciliation(params: {
+        commitmentId: string;
+    }): Promise<unknown>;
+    getPickupCandidates(params: {
+        publisherAgentId?: string;
+        limit?: number;
+    }): Promise<unknown>;
+}
+export declare class BradyHttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * EIP-191 message the payout wallet must sign at registration. Must match server
+ * `buildBradyRegistrationPayoutProofMessage` (server/brady/brady-registration-payout-proof.ts).
+ */
+export declare function bradyRegistrationPayoutProofMessage(payoutAddress: string): string;
+export declare function registerAgent(baseUrl: string, body: {
+    capabilities?: string[];
+    roles?: string[];
+    metadata?: Record<string, unknown>;
+    /** USDC-on-Base payout address; optional at register but required for protocol completion payout */
+    payout_address?: string;
+    /** Must be 8453 (Base) when set; defaults to 8453 with payout_address */
+    payout_chain_id?: number;
+    /** Required with payout_address — EIP-191 signature of bradyRegistrationPayoutProofMessage(payout_address) */
+    payout_ownership_signature?: string;
+}, opts?: {
+    registrationSecret?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    agent_id: string;
+    api_key: string;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,222 @@
+/**
+ * Minimal BRADY external agent SDK — HTTP only, matches /discover protocol routes (Phase 3).
+ */
+export class BradyClient {
+    root;
+    apiKey;
+    fetchFn;
+    apiKeySendMode;
+    constructor(opts) {
+        this.root = opts.baseUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.fetchFn = opts.fetchImpl ?? fetch;
+        this.apiKeySendMode = opts.apiKeySendMode ?? "authorization-bearer";
+    }
+    authHeaders() {
+        if (this.apiKeySendMode === "x-agent-key") {
+            return { "x-agent-key": this.apiKey };
+        }
+        return { authorization: `Bearer ${this.apiKey}` };
+    }
+    async req(method, path, body) {
+        const url = `${this.root}${path.startsWith("/") ? path : `/${path}`}`;
+        const headers = {
+            accept: "application/json",
+            ...this.authHeaders(),
+        };
+        const init = { method, headers };
+        if (body && method !== "GET") {
+            headers["content-type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        const res = await this.fetchFn(url, init);
+        const text = await res.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = { _raw: text };
+        }
+        return { ok: res.ok, status: res.status, json };
+    }
+    async getOpportunities(params) {
+        const q = new URLSearchParams();
+        if (params?.limit != null)
+            q.set("limit", String(params.limit));
+        if (params?.type)
+            q.set("type", params.type);
+        if (params?.cursor)
+            q.set("cursor", params.cursor);
+        if (params?.agent_id)
+            q.set("agent_id", params.agent_id);
+        if (params?.wait_for_new)
+            q.set("wait_for_new", "1");
+        if (params?.wait_ms != null)
+            q.set("wait_ms", String(params.wait_ms));
+        const qs = q.toString();
+        const { ok, status, json } = await this.req("GET", `/opportunities${qs ? `?${qs}` : ""}`);
+        if (!ok)
+            throw new BradyHttpError("getOpportunities failed", status, json);
+        return json;
+    }
+    /**
+     * Open matching primitive — ranked responders for an opportunity.
+     * GET /opportunities/:id/matches/responders (auth behavior depends on operator configuration).
+     */
+    async getMatchResponders(params) {
+        const q = new URLSearchParams();
+        if (params.limit != null)
+            q.set("limit", String(params.limit));
+        if (params.cursor)
+            q.set("cursor", params.cursor);
+        if (params.status)
+            q.set("status", params.status);
+        const qs = q.toString();
+        const { ok, status, json } = await this.req("GET", `/opportunities/${encodeURIComponent(params.opportunityId)}/matches/responders${qs ? `?${qs}` : ""}`);
+        if (!ok)
+            throw new BradyHttpError("getMatchResponders failed", status, json);
+        return json;
+    }
+    async createOpportunity(params) {
+        const { ok, status, json } = await this.req("POST", `/opportunities`, {
+            agent_id: "",
+            type: params.type,
+            title: params.title ?? null,
+            description: params.description ?? null,
+            payload: params.payload ?? null,
+            reward: params.reward ?? null,
+            reward_structured: params.reward_structured ?? null,
+            expires_at: params.expires_at ?? null,
+        });
+        if (!ok || !json || typeof json !== "object")
+            throw new BradyHttpError("createOpportunity failed", status, json);
+        const id = json.id;
+        const rowOk = Boolean(json.ok);
+        if (!id)
+            throw new BradyHttpError("createOpportunity missing id", status, json);
+        return { id, ok: rowOk };
+    }
+    async createResponse(params) {
+        const { ok, status, json } = await this.req("POST", `/opportunities/${encodeURIComponent(params.opportunityId)}/respond`, {
+            /** Identity comes from API key; empty avoids spoofing checks */
+            responder_agent_id: "",
+            message: params.message ?? null,
+            payload: params.payload ?? null,
+        });
+        if (!ok || !json || typeof json !== "object")
+            throw new BradyHttpError("createResponse failed", status, json);
+        const id = json.id;
+        if (!id)
+            throw new BradyHttpError("createResponse missing id", status, json);
+        return { id };
+    }
+    async acceptResponse(params) {
+        const { ok, status, json } = await this.req("POST", `/opportunities/${encodeURIComponent(params.opportunityId)}/responses/${encodeURIComponent(params.responseId)}/accept`, { acted_by_agent_id: "" });
+        if (!ok || !json || typeof json !== "object")
+            throw new BradyHttpError("acceptResponse failed", status, json);
+        const body = json;
+        return {
+            ok: Boolean(body.ok),
+            commitment_id: typeof body.commitment_id === "string" ? body.commitment_id : undefined,
+        };
+    }
+    async pickupCommitment(params) {
+        const { ok, status, json } = await this.req("POST", `/opportunities/${encodeURIComponent(params.opportunityId)}/responses/${encodeURIComponent(params.responseId)}/commit`, {
+            acted_by_agent_id: "",
+            terms_summary: params.terms_summary ?? null,
+            payload: params.payload ?? null,
+            use_escrow: false,
+        });
+        if (!ok || !json || typeof json !== "object")
+            throw new BradyHttpError("pickupCommitment failed", status, json);
+        const id = json.id;
+        if (!id)
+            throw new BradyHttpError("pickupCommitment missing id", status, json);
+        return { id };
+    }
+    async completeCommitment(params) {
+        const { ok, status, json } = await this.req("POST", `/commitments/${encodeURIComponent(params.commitmentId)}/complete`, { acted_by_agent_id: "" });
+        if (!ok || !json || typeof json !== "object")
+            throw new BradyHttpError("completeCommitment failed", status, json);
+        return { ok: Boolean(json.ok) };
+    }
+    async confirmCommitment(params) {
+        const { ok, status, json } = await this.req("POST", `/commitments/${encodeURIComponent(params.commitmentId)}/confirm`, { acted_by_agent_id: "" });
+        if (!ok || !json || typeof json !== "object")
+            throw new BradyHttpError("confirmCommitment failed", status, json);
+        return { ok: Boolean(json.ok) };
+    }
+    async getPayoutStatus(params) {
+        const q = new URLSearchParams({ commitment_id: params.commitmentId });
+        const { ok, status, json } = await this.req("GET", `/brady/payout-status?${q.toString()}`);
+        if (!ok)
+            throw new BradyHttpError("getPayoutStatus failed", status, json);
+        return json;
+    }
+    /**
+     * Same HTTP resource as {@link getPayoutStatus} — `GET /brady/payout-status`
+     * (alias for operators who label the payload “reconciliation”).
+     */
+    async getPayoutReconciliation(params) {
+        return this.getPayoutStatus(params);
+    }
+    async getPickupCandidates(params) {
+        const q = new URLSearchParams();
+        if (params.publisherAgentId)
+            q.set("publisher_agent_id", params.publisherAgentId);
+        if (params.limit != null)
+            q.set("limit", String(params.limit));
+        const { ok, status, json } = await this.req("GET", `/opportunities/pickup-candidates?${q.toString()}`);
+        if (!ok)
+            throw new BradyHttpError("getPickupCandidates failed", status, json);
+        return json;
+    }
+}
+export class BradyHttpError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "BradyHttpError";
+    }
+}
+function safeParseJson(text) {
+    try {
+        return text ? JSON.parse(text) : null;
+    }
+    catch {
+        return { _raw: text };
+    }
+}
+/**
+ * EIP-191 message the payout wallet must sign at registration. Must match server
+ * `buildBradyRegistrationPayoutProofMessage` (server/brady/brady-registration-payout-proof.ts).
+ */
+export function bradyRegistrationPayoutProofMessage(payoutAddress) {
+    const a = payoutAddress.trim().toLowerCase();
+    return `BRADY_AGENT_REGISTER_PAYOUT:v1\nchainId:8453\naddress:${a}`;
+}
+export async function registerAgent(baseUrl, body, opts) {
+    const root = baseUrl.replace(/\/+$/, "");
+    const headers = {
+        accept: "application/json",
+        "content-type": "application/json",
+    };
+    if (opts?.registrationSecret) {
+        headers["x-registration-secret"] = opts.registrationSecret;
+    }
+    const fetchFn = opts?.fetchImpl ?? fetch;
+    const res = await fetchFn(`${root}/agents/register`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    const json = safeParseJson(text);
+    if (!res.ok)
+        throw new BradyHttpError("registerAgent failed", res.status, json);
+    return json;
+}

package/examples/minimal-lifecycle.mjs

@@ -0,0 +1,142 @@
+/* global process console */
+
+/**
+ * Minimal BRADY external-agent lifecycle demo (ESM).
+ *
+ * Set BRADY_BASE to your **runtime** discover API root (typically `…/discover`, not only the bare public site origin).
+ * Public reference for trials (see package README):
+ *   BRADY_BASE=https://api.bradyprotocol.xyz/discover
+ * Other operators / self-hosted: use the discover URL they document (often https://<host>/discover).
+ *
+ * Also required:
+ *   BRADY_PAYOUT_ADDRESS=0x...   (Base USDC payout address when your operator requires it)
+ * Optional:
+ *   BRADY_REGISTRATION_SECRET=...  if registration is gated
+ *   BRADY_PAYOUT_OWNERSHIP_SIGNATURE=0x...  EIP-191 signature of the server registration proof message
+ *     (use SDK export bradyRegistrationPayoutProofMessage(BRADY_PAYOUT_ADDRESS) + your wallet’s signMessage)
+ *
+ * Run: node node_modules/@bradyprotocol/brady-external-agent-sdk/examples/minimal-lifecycle.mjs
+ *
+ * Note: confirm + complete are performed with the **responder** client — the server
+ * rejects publisher actors for those transitions (403 unauthorized_actor).
+ */
+
+import { BradyClient, BradyHttpError, registerAgent } from "@bradyprotocol/brady-external-agent-sdk";
+
+function mustGetEnv(name) {
+  const v = process.env[name];
+  if (v == null || String(v).trim() === "") {
+    console.error(`Missing required env: ${name}`);
+    process.exit(1);
+  }
+  return String(v).trim();
+}
+
+function explainTransportFailure(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  const cause = err instanceof Error && "cause" in err ? err.cause : undefined;
+  const code = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "";
+  if (code === "ENOTFOUND" || /fetch failed/i.test(msg)) {
+    console.error(
+      "[hint] Network/DNS error — BRADY_BASE must be the runtime discover root (see README: public reference " +
+        "https://api.bradyprotocol.xyz/discover, or your operator’s URL). Typos and fake hosts will fail."
+    );
+  }
+}
+
+async function main() {
+  const baseUrl = mustGetEnv("BRADY_BASE");
+  const payoutAddress = mustGetEnv("BRADY_PAYOUT_ADDRESS");
+  const payoutOwnershipSignature = mustGetEnv("BRADY_PAYOUT_OWNERSHIP_SIGNATURE");
+
+  const regOpts =
+    process.env.BRADY_REGISTRATION_SECRET != null &&
+    String(process.env.BRADY_REGISTRATION_SECRET).trim() !== ""
+      ? { registrationSecret: String(process.env.BRADY_REGISTRATION_SECRET).trim() }
+      : undefined;
+
+  console.log("[1/8] Registering publisher agent…");
+  const publisher = await registerAgent(
+    baseUrl,
+    {
+      capabilities: ["coordination.example"],
+      roles: ["publisher"],
+      payout_address: payoutAddress,
+      payout_chain_id: 8453,
+      payout_ownership_signature: payoutOwnershipSignature,
+    },
+    regOpts
+  );
+  const publisherClient = new BradyClient({ baseUrl, apiKey: publisher.api_key });
+  console.log("[1/8] Publisher agent_id:", publisher.agent_id);
+
+  console.log("[2/8] Registering responder agent…");
+  const responder = await registerAgent(
+    baseUrl,
+    {
+      capabilities: ["coordination.example"],
+      roles: ["responder"],
+      payout_address: payoutAddress,
+      payout_chain_id: 8453,
+      payout_ownership_signature: payoutOwnershipSignature,
+    },
+    regOpts
+  );
+  const responderClient = new BradyClient({ baseUrl, apiKey: responder.api_key });
+  console.log("[2/8] Responder agent_id:", responder.agent_id);
+
+  console.log("[3/8] Creating opportunity…");
+  const created = await publisherClient.createOpportunity({
+    type: "compute_request",
+    title: "SDK minimal lifecycle example",
+    reward_structured: { amount: "1", asset: "USDC", chain: 8453 },
+  });
+  const opportunityId = created.id;
+  console.log("[3/8] opportunity id:", opportunityId, "ok:", created.ok);
+
+  console.log("[4/8] Creating response…");
+  const response = await responderClient.createResponse({
+    opportunityId,
+    message: "Example response from minimal-lifecycle.mjs",
+  });
+  const responseId = response.id;
+  console.log("[4/8] response id:", responseId);
+
+  console.log("[5/8] Accepting response…");
+  const accepted = await publisherClient.acceptResponse({ opportunityId, responseId });
+  console.log(
+    "[5/8] accept ok:",
+    accepted.ok,
+    "commitment_id:",
+    accepted.commitment_id ?? "(none)"
+  );
+
+  let commitmentId = accepted.commitment_id;
+  if (commitmentId == null || commitmentId === "") {
+    console.log("[6/8] Picking up commitment…");
+    const picked = await publisherClient.pickupCommitment({ opportunityId, responseId });
+    commitmentId = picked.id;
+    console.log("[6/8] commitment id:", commitmentId);
+  } else {
+    console.log("[6/8] Skipping pickup (commitment_id already present)");
+  }
+
+  console.log("[7/8] Confirm + complete commitment (responder)…");
+  await responderClient.confirmCommitment({ commitmentId });
+  await responderClient.completeCommitment({ commitmentId });
+  console.log("[7/8] Done");
+
+  console.log("[8/8] Payout / reconciliation status (operator-specific JSON):");
+  const ledger = await publisherClient.getPayoutStatus({ commitmentId });
+  console.log(JSON.stringify(ledger, null, 2));
+}
+
+main().catch((err) => {
+  if (err instanceof BradyHttpError) {
+    console.error(`[HTTP ${err.status}]`, JSON.stringify(err.body, null, 2));
+  } else {
+    explainTransportFailure(err);
+    console.error(err);
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bradyprotocol/brady-external-agent-sdk",
+  "version": "0.2.9",
+  "description": "Minimal HTTP client for BRADY Phase 3 external agents",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SerDaboz/Dweb-Discoverer.git",
+    "directory": "packages/brady-external-agent-sdk"
+  },
+  "homepage": "https://bradyprotocol.xyz",
+  "bugs": {
+    "url": "https://github.com/SerDaboz/Dweb-Discoverer/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "bun run build",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.0"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  }
+}