settld 0.1.2 → 0.2.0

package/scripts/dev/sdk-first-run.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+# shellcheck source=/dev/null
+source "$ROOT_DIR/scripts/dev/env.sh"
+
+if [[ -z "${SETTLD_API_KEY:-}" ]]; then
+  SETTLD_API_KEY="$(bash "$ROOT_DIR/scripts/dev/new-sdk-key.sh" --print-only)"
+  export SETTLD_API_KEY
+fi
+
+cd "$ROOT_DIR"
+npm run -s sdk:first-run
+
+echo
+echo "Billable events snapshot:"
+curl -sS "$SETTLD_BASE_URL/ops/finance/billable-events?period=$(date -u +%Y-%m)" \
+  -H "authorization: Bearer $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" | jq .
+

package/scripts/dev/smoke-x402-gateway.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT"
+
+API_PID=""
+UPSTREAM_PID=""
+GATEWAY_PID=""
+FIRST_HEADERS=""
+RUNTIME_ENV_FILE=""
+
+cleanup() {
+  set +e
+  if [[ -n "${FIRST_HEADERS:-}" && -f "${FIRST_HEADERS:-}" ]]; then rm -f "${FIRST_HEADERS:-}"; fi
+  if [[ -n "${RUNTIME_ENV_FILE:-}" && -f "${RUNTIME_ENV_FILE:-}" ]]; then rm -f "${RUNTIME_ENV_FILE:-}"; fi
+  if [[ -n "${GATEWAY_PID:-}" ]]; then kill "${GATEWAY_PID}" >/dev/null 2>&1 || true; fi
+  if [[ -n "${UPSTREAM_PID:-}" ]]; then kill "${UPSTREAM_PID}" >/dev/null 2>&1 || true; fi
+  if [[ -n "${API_PID:-}" ]]; then kill "${API_PID}" >/dev/null 2>&1 || true; fi
+}
+trap cleanup EXIT
+
+# Ensure scripts/dev/env.sh + scripts/dev/new-sdk-key.sh target the local API and do not clobber repo env files.
+RUNTIME_ENV_FILE="$(mktemp)"
+export SETTLD_BASE_URL="http://127.0.0.1:3000"
+export SETTLD_TENANT_ID="tenant_default"
+export SETTLD_RUNTIME_ENV_FILE="${RUNTIME_ENV_FILE}"
+export SETTLD_ENV_FILE="/dev/null"
+
+echo "[smoke] starting Settld API on :3000"
+PROXY_OPS_TOKEN=tok_ops PORT=3000 node src/api/server.js >/tmp/settld_api_smoke.log 2>&1 &
+API_PID="$!"
+
+echo "[smoke] waiting for API readiness"
+for i in $(seq 1 60); do
+  if curl -fsS "http://127.0.0.1:3000/healthz" >/dev/null; then break; fi
+  sleep 1
+  if [[ "$i" == "60" ]]; then
+    echo "[smoke] API did not become ready; tailing logs" >&2
+    tail -n 200 /tmp/settld_api_smoke.log >&2 || true
+    exit 1
+  fi
+done
+
+echo "[smoke] minting an API key"
+bash scripts/dev/new-sdk-key.sh --ops-token tok_ops >/dev/null
+# shellcheck source=/dev/null
+source "${RUNTIME_ENV_FILE}"
+if [[ -z "${SETTLD_API_KEY:-}" ]]; then
+  echo "[smoke] SETTLD_API_KEY not set after new-sdk-key.sh" >&2
+  exit 1
+fi
+
+echo "[smoke] starting mock upstream on :9402"
+PORT=9402 node services/x402-gateway/examples/upstream-mock.js >/tmp/settld_x402_upstream_smoke.log 2>&1 &
+UPSTREAM_PID="$!"
+
+echo "[smoke] waiting for upstream readiness"
+for i in $(seq 1 30); do
+  if curl -fsS "http://127.0.0.1:9402/healthz" >/dev/null; then break; fi
+  sleep 0.2
+  if [[ "$i" == "30" ]]; then
+    echo "[smoke] upstream did not become ready; tailing logs" >&2
+    tail -n 200 /tmp/settld_x402_upstream_smoke.log >&2 || true
+    exit 1
+  fi
+done
+
+echo "[smoke] starting gateway on :8402"
+SETTLD_API_URL="http://127.0.0.1:3000" \
+SETTLD_API_KEY="${SETTLD_API_KEY}" \
+UPSTREAM_URL="http://127.0.0.1:9402" \
+X402_AUTOFUND=1 \
+HOLDBACK_BPS=1000 \
+DISPUTE_WINDOW_MS=86400000 \
+PORT=8402 \
+node services/x402-gateway/src/server.js >/tmp/settld_x402_gateway_smoke.log 2>&1 &
+GATEWAY_PID="$!"
+
+echo "[smoke] waiting for gateway readiness"
+for i in $(seq 1 30); do
+  if curl -fsS "http://127.0.0.1:8402/healthz" >/dev/null; then break; fi
+  sleep 0.2
+  if [[ "$i" == "30" ]]; then
+    echo "[smoke] gateway did not become ready; tailing logs" >&2
+    tail -n 200 /tmp/settld_x402_gateway_smoke.log >&2 || true
+    exit 1
+  fi
+done
+
+echo "[smoke] driving 402 -> gate/create"
+FIRST_HEADERS="$(mktemp)"
+curl -isS "http://127.0.0.1:8402/resource" | tee "${FIRST_HEADERS}" >/dev/null
+GATE_ID="$(
+  awk 'BEGIN{IGNORECASE=1} $1 ~ /^x-settld-gate-id:$/ {print $2}' "${FIRST_HEADERS}" | tr -d '\r' | head -n 1
+)"
+if [[ -z "${GATE_ID:-}" ]]; then
+  echo "[smoke] missing x-settld-gate-id header" >&2
+  cat "${FIRST_HEADERS}" >&2 || true
+  exit 1
+fi
+echo "[smoke] gateId=${GATE_ID}"
+
+echo "[smoke] driving verify-before-release"
+curl -isS "http://127.0.0.1:8402/resource" \
+  -H "x-settld-gate-id: ${GATE_ID}" \
+  -H "x-payment: paid" >/dev/null
+
+echo "[smoke] fetching gate state from API"
+curl -fsS "http://127.0.0.1:3000/x402/gate/${GATE_ID}" \
+  -H "x-proxy-tenant-id: tenant_default" \
+  -H "authorization: Bearer ${SETTLD_API_KEY}" \
+  -H "x-settld-protocol: 1.0" | jq '{gateStatus:.gate.status, settlementStatus:.settlement.status, holdback:.gate.holdback}'
+
+echo "[smoke] ok"

package/scripts/dev/start-api.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+# shellcheck source=/dev/null
+source "$ROOT_DIR/scripts/dev/env.sh"
+
+if [[ -z "${DATABASE_URL:-}" ]]; then
+  cat <<'EOF'
+DATABASE_URL is not set.
+
+Set it in .env.dev:
+  DATABASE_URL=postgresql://...
+EOF
+  exit 1
+fi
+
+: "${STORE:=pg}"
+: "${PROXY_PG_SCHEMA:=public}"
+: "${PROXY_MIGRATE_ON_STARTUP:=1}"
+
+cd "$ROOT_DIR"
+exec npm run dev:api
+

package/scripts/doctor/mcp-host.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(SCRIPT_DIR, "..", "..");
+const DEFAULT_REPORT_PATH = "artifacts/ops/mcp-host-smoke.json";
+const SMOKE_SCRIPT_PATH = path.join(REPO_ROOT, "scripts", "ci", "run-mcp-host-smoke.mjs");
+
+function usage() {
+  process.stderr.write("usage:\n");
+  process.stderr.write("  settld doctor [--help] [--report <path>]\n");
+}
+
+function readArgValue(argv, index, rawArg) {
+  const arg = String(rawArg ?? "");
+  const eq = arg.indexOf("=");
+  if (eq >= 0) return { value: arg.slice(eq + 1), nextIndex: index };
+  return { value: String(argv[index + 1] ?? ""), nextIndex: index + 1 };
+}
+
+function parseArgs(argv) {
+  const out = {
+    help: false,
+    reportPath: path.resolve(process.cwd(), DEFAULT_REPORT_PATH)
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = String(argv[i] ?? "");
+    if (arg === "--help" || arg === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (arg === "--report" || arg.startsWith("--report=")) {
+      const parsed = readArgValue(argv, i, arg);
+      const rawPath = parsed.value.trim();
+      if (!rawPath) throw new Error("--report requires a non-empty path");
+      out.reportPath = path.resolve(process.cwd(), rawPath);
+      i = parsed.nextIndex;
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+
+  return out;
+}
+
+function runSmoke(reportPath) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [SMOKE_SCRIPT_PATH], {
+      cwd: REPO_ROOT,
+      env: { ...process.env, MCP_HOST_SMOKE_REPORT_PATH: reportPath },
+      stdio: "inherit"
+    });
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      resolve({
+        code: Number.isInteger(code) ? code : 1,
+        signal: signal ?? null
+      });
+    });
+  });
+}
+
+async function readReportSafe(reportPath) {
+  try {
+    const raw = await fs.readFile(reportPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function printDoctorSummary({ ok, reportPath, report, smoke }) {
+  process.stdout.write(`${ok ? "PASS" : "FAIL"} mcp-host-compatibility\n`);
+  process.stdout.write(`report: ${reportPath}\n`);
+  if (!ok) {
+    if (report?.error?.message) {
+      process.stdout.write(`error: ${String(report.error.message)}\n`);
+    } else if (smoke.signal) {
+      process.stdout.write(`error: smoke runner terminated by signal ${smoke.signal}\n`);
+    } else if (Number.isInteger(smoke.code) && smoke.code !== 0) {
+      process.stdout.write(`error: smoke runner exited with code ${smoke.code}\n`);
+    } else {
+      process.stdout.write("error: failed to read smoke report\n");
+    }
+  }
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    usage();
+    process.stderr.write(`${err?.message ?? String(err)}\n`);
+    process.exit(1);
+  }
+
+  if (args.help) {
+    usage();
+    process.exit(0);
+  }
+
+  const smoke = await runSmoke(args.reportPath);
+  const report = await readReportSafe(args.reportPath);
+  const ok = smoke.code === 0 && report?.ok === true;
+  printDoctorSummary({ ok, reportPath: args.reportPath, report, smoke });
+  process.exit(ok ? 0 : 1);
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(err)}\n`);
+  process.exit(1);
+});

package/scripts/examples/produce-and-verify-jobproof.mjs

@@ -0,0 +1,191 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+import { createChainedEvent, appendChainedEvent } from "../../src/core/event-chain.js";
+import { GOVERNANCE_STREAM_ID } from "../../src/core/governance.js";
+import { DEFAULT_TENANT_ID } from "../../src/core/tenancy.js";
+import { buildJobProofBundleV1 } from "../../src/core/proof-bundle.js";
+
+function usage() {
+  // eslint-disable-next-line no-console
+  console.error("usage: node scripts/examples/produce-and-verify-jobproof.mjs [--out <dir>]");
+  process.exit(2);
+}
+
+function bytes(text) {
+  return new TextEncoder().encode(text);
+}
+
+async function ensureEmptyDir(dir) {
+  await fs.rm(dir, { recursive: true, force: true });
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function writeFilesToDirSorted({ files, outDir }) {
+  const entries = Array.from(files.entries()).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  for (const [name, content] of entries) {
+    const fp = path.join(outDir, name);
+    // eslint-disable-next-line no-await-in-loop
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    // eslint-disable-next-line no-await-in-loop
+    await fs.writeFile(fp, content);
+  }
+}
+
+async function readFixtureKeypairs() {
+  const p = path.resolve(process.cwd(), "test", "fixtures", "keys", "fixture_keypairs.json");
+  const raw = await fs.readFile(p, "utf8");
+  return JSON.parse(raw);
+}
+
+async function readTrustFile() {
+  const p = path.resolve(process.cwd(), "test", "fixtures", "bundles", "v1", "trust.json");
+  const raw = await fs.readFile(p, "utf8");
+  return JSON.parse(raw);
+}
+
+async function runVerifyCli({ bundleDir, outJsonPath, env }) {
+  const bin = path.resolve(process.cwd(), "packages", "artifact-verify", "bin", "settld-verify.js");
+  const proc = spawn(process.execPath, [bin, "--format", "json", "--strict", "--job-proof", bundleDir], {
+    env: { ...process.env, ...(env ?? {}) },
+    stdio: ["ignore", "pipe", "inherit"]
+  });
+  const stdout = [];
+  proc.stdout.on("data", (d) => stdout.push(d));
+  const code = await new Promise((resolve, reject) => {
+    proc.on("error", reject);
+    proc.on("close", (code) => resolve(code ?? 1));
+  });
+  const out = Buffer.concat(stdout).toString("utf8");
+  await fs.writeFile(outJsonPath, out, "utf8");
+  if (code !== 0) throw new Error(`settld-verify failed with exit code ${code}`);
+  return out;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  let outDir = path.resolve(process.cwd(), "out", "produce-and-verify-jobproof");
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--out") {
+      outDir = path.resolve(process.cwd(), String(argv[i + 1] ?? ""));
+      if (!outDir) usage();
+      i += 1;
+      continue;
+    }
+    if (a === "--help" || a === "-h") usage();
+    usage();
+  }
+
+  const trust = await readTrustFile();
+  const keypairs = await readFixtureKeypairs();
+
+  const govSigner = { keyId: keypairs.govRoot.keyId, privateKeyPem: keypairs.govRoot.privateKeyPem };
+  const serverSigner = { keyId: keypairs.serverA.keyId, privateKeyPem: keypairs.serverA.privateKeyPem };
+  const serverKeys = {
+    serverA: keypairs.serverA,
+    serverB: keypairs.serverB,
+    signerA: serverSigner
+  };
+
+  const tenantId = "tenant_example";
+  const jobId = "job_example";
+  const generatedAt = "2026-02-02T00:00:00.000Z";
+
+  // Governance stream: register serverA signer key (minimal).
+  let governanceEvents = [];
+  governanceEvents = appendChainedEvent({
+    events: governanceEvents,
+    signer: serverKeys.signerA,
+    event: createChainedEvent({
+      id: "evt_gov_serverA_registered",
+      streamId: GOVERNANCE_STREAM_ID,
+      type: "SERVER_SIGNER_KEY_REGISTERED",
+      at: generatedAt,
+      actor: { type: "system", id: "proxy" },
+      payload: {
+        tenantId: DEFAULT_TENANT_ID,
+        keyId: serverKeys.serverA.keyId,
+        publicKeyPem: serverKeys.serverA.publicKeyPem,
+        registeredAt: generatedAt,
+        reason: "example"
+      }
+    })
+  });
+  const governanceSnapshot = {
+    streamId: GOVERNANCE_STREAM_ID,
+    lastChainHash: governanceEvents.at(-1)?.chainHash ?? null,
+    lastEventId: governanceEvents.at(-1)?.id ?? null
+  };
+
+  // Job stream: create job (minimal).
+  let jobEvents = [];
+  jobEvents = appendChainedEvent({
+    events: jobEvents,
+    signer: serverKeys.signerA,
+    event: createChainedEvent({
+      id: "evt_job_created",
+      streamId: jobId,
+      type: "JOB_CREATED",
+      at: generatedAt,
+      actor: { type: "system", id: "proxy" },
+      payload: { jobId }
+    })
+  });
+  const jobSnapshot = { id: jobId, lastChainHash: jobEvents.at(-1)?.chainHash ?? null, lastEventId: jobEvents.at(-1)?.id ?? null };
+
+  const publicKeyByKeyId = new Map([
+    [serverKeys.serverA.keyId, serverKeys.serverA.publicKeyPem],
+    [serverKeys.serverB.keyId, serverKeys.serverB.publicKeyPem]
+  ]);
+
+  const { files } = buildJobProofBundleV1({
+    tenantId,
+    jobId,
+    jobEvents,
+    jobSnapshot,
+    governanceEvents,
+    governanceSnapshot,
+    tenantGovernanceEvents: [],
+    tenantGovernanceSnapshot: { streamId: GOVERNANCE_STREAM_ID, lastChainHash: null, lastEventId: null },
+    governancePolicy: null,
+    governancePolicySigner: govSigner,
+    revocationList: null,
+    artifacts: [],
+    contractDocsByHash: new Map(),
+    publicKeyByKeyId,
+    signerKeys: [],
+    manifestSigner: serverKeys.signerA,
+    verificationReportSigner: serverKeys.signerA,
+    timestampAuthoritySigner: null,
+    toolVersion: "0.0.0-example",
+    toolCommit: "0123456789abcdef0123456789abcdef01234567",
+    requireHeadAttestation: true,
+    generatedAt
+  });
+
+  const bundleDir = path.join(outDir, "bundle");
+  const verifyOutPath = path.join(outDir, "settld-verify-output.json");
+
+  await ensureEmptyDir(outDir);
+  await ensureEmptyDir(bundleDir);
+  await writeFilesToDirSorted({ files, outDir: bundleDir });
+
+  // Verify strictly using the public CLI entrypoint, and write VerifyCliOutput.v1 JSON.
+  await runVerifyCli({
+    bundleDir,
+    outJsonPath: verifyOutPath,
+    env: {
+      SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON: JSON.stringify(trust.governanceRoots ?? {}),
+      SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON: JSON.stringify(trust.timeAuthorities ?? {})
+    }
+  });
+
+  // eslint-disable-next-line no-console
+  console.log(`wrote bundle: ${bundleDir}`);
+  // eslint-disable-next-line no-console
+  console.log(`wrote verify output: ${verifyOutPath}`);
+}
+
+await main();

package/scripts/examples/sdk-first-paid-rfq.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import random
+import sys
+import time
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO_ROOT / "packages" / "api-sdk-python"))
+
+from settld_api_sdk import SettldClient  # noqa: E402
+
+
+def _unique_suffix() -> str:
+    return f"{int(time.time() * 1000):x}_{random.randint(0, 0xFFFFFF):06x}"
+
+
+def _fixture_keys() -> tuple[str, str]:
+    fixture_path = REPO_ROOT / "test" / "fixtures" / "keys" / "fixture_keypairs.json"
+    with fixture_path.open("r", encoding="utf-8") as fp:
+        raw = json.load(fp)
+    poster = str(raw["serverA"]["publicKeyPem"])
+    bidder = str(raw["serverB"]["publicKeyPem"])
+    return poster, bidder
+
+
+def main() -> int:
+    base_url = os.environ.get("SETTLD_BASE_URL", "http://127.0.0.1:3000")
+    tenant_id = os.environ.get("SETTLD_TENANT_ID", "tenant_default")
+    api_key = os.environ.get("SETTLD_API_KEY")
+    if not api_key:
+        print("SETTLD_API_KEY is not set; calls will fail unless API auth is disabled.", file=sys.stderr)
+
+    poster_key, bidder_key = _fixture_keys()
+    suffix = _unique_suffix()
+
+    client = SettldClient(
+        base_url=base_url,
+        tenant_id=tenant_id,
+        api_key=api_key,
+    )
+
+    result = client.first_paid_rfq(
+        {
+            "poster_agent": {
+                "agentId": f"agt_py_poster_{suffix}",
+                "displayName": "Python SDK Poster",
+                "owner": {"ownerType": "service", "ownerId": "svc_sdk_py_paid_rfq"},
+                "capabilities": ["request"],
+                "publicKeyPem": poster_key,
+            },
+            "bidder_agent": {
+                "agentId": f"agt_py_bidder_{suffix}",
+                "displayName": "Python SDK Bidder",
+                "owner": {"ownerType": "service", "ownerId": "svc_sdk_py_paid_rfq"},
+                "capabilities": ["translate", "summarize"],
+                "publicKeyPem": bidder_key,
+            },
+            "payer_credit": {"amountCents": 2500, "currency": "USD"},
+            "rfq": {
+                "rfqId": f"rfq_py_{suffix}",
+                "title": "Translate launch note",
+                "capability": "translate",
+                "budgetCents": 1200,
+                "currency": "USD",
+            },
+            "bid": {
+                "bidId": f"bid_py_{suffix}",
+                "amountCents": 1100,
+                "currency": "USD",
+                "etaSeconds": 600,
+            },
+            "completed_metrics": {"settlementReleaseRatePct": 100, "latencyMs": 375},
+        }
+    )
+
+    verification_body = result.get("verification", {}).get("body", {})
+    verification_status = None
+    if isinstance(verification_body, dict):
+        verification = verification_body.get("verification", {})
+        if isinstance(verification, dict):
+            verification_status = verification.get("verificationStatus")
+        if verification_status is None:
+            verification_status = verification_body.get("verificationStatus")
+
+    settlement_body = result.get("settlement", {}).get("body", {})
+    settlement_status = settlement_body.get("settlement", {}).get("status") if isinstance(settlement_body, dict) else None
+
+    summary = {
+        "rfqId": result.get("ids", {}).get("rfq_id"),
+        "runId": result.get("ids", {}).get("run_id"),
+        "posterAgentId": result.get("ids", {}).get("poster_agent_id"),
+        "bidderAgentId": result.get("ids", {}).get("bidder_agent_id"),
+        "verificationStatus": verification_status,
+        "settlementStatus": settlement_status,
+    }
+    print(json.dumps(summary, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/examples/sdk-first-verified-run.mjs

@@ -0,0 +1,85 @@
+import { generateKeyPairSync } from "node:crypto";
+
+import { SettldClient } from "../../packages/api-sdk/src/index.js";
+
+function generatePublicKeyPem() {
+  const { publicKey } = generateKeyPairSync("ed25519");
+  return publicKey.export({ format: "pem", type: "spki" }).toString("utf8");
+}
+
+function uniqueSuffix() {
+  return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+async function main() {
+  const baseUrl = process.env.SETTLD_BASE_URL ?? "http://127.0.0.1:3000";
+  const tenantId = process.env.SETTLD_TENANT_ID ?? "tenant_default";
+  const apiKey = process.env.SETTLD_API_KEY ?? "";
+
+  if (!apiKey) {
+    // eslint-disable-next-line no-console
+    console.error("SETTLD_API_KEY is not set; the example will only work when API auth is disabled.");
+  }
+
+  const client = new SettldClient({
+    baseUrl,
+    tenantId,
+    apiKey: apiKey || undefined
+  });
+
+  const suffix = uniqueSuffix();
+  const runId = `run_sdk_${suffix}`;
+  const disputeWindowDaysRaw = process.env.SETTLD_SDK_DISPUTE_WINDOW_DAYS ?? null;
+  const disputeWindowDays =
+    disputeWindowDaysRaw === null || disputeWindowDaysRaw === undefined || String(disputeWindowDaysRaw).trim() === ""
+      ? null
+      : Number(disputeWindowDaysRaw);
+  if (disputeWindowDays !== null && (!Number.isSafeInteger(disputeWindowDays) || disputeWindowDays < 0)) {
+    throw new TypeError("SETTLD_SDK_DISPUTE_WINDOW_DAYS must be a non-negative integer");
+  }
+
+  const result = await client.firstVerifiedRun({
+    payeeAgent: {
+      agentId: `agt_payee_${suffix}`,
+      displayName: "SDK Demo Payee",
+      owner: { ownerType: "service", ownerId: "svc_sdk_demo" },
+      capabilities: ["translate", "summarize"],
+      publicKeyPem: generatePublicKeyPem()
+    },
+    payerAgent: {
+      agentId: `agt_payer_${suffix}`,
+      displayName: "SDK Demo Payer",
+      owner: { ownerType: "service", ownerId: "svc_sdk_demo" },
+      capabilities: ["dispatch"],
+      publicKeyPem: generatePublicKeyPem()
+    },
+    payerCredit: { amountCents: 5000, currency: "USD" },
+    settlement: {
+      amountCents: 1250,
+      currency: "USD",
+      ...(disputeWindowDays !== null ? { disputeWindowDays } : {})
+    },
+    run: {
+      runId,
+      taskType: "translation",
+      inputRef: `urn:sdk:first-run:${suffix}`
+    },
+    completedMetrics: { latencyMs: 420 }
+  });
+
+  const verificationStatus =
+    result.verification?.body?.verification?.verificationStatus ?? result.verification?.body?.verificationStatus ?? null;
+
+  const summary = {
+    runId: result.ids.runId,
+    payeeAgentId: result.ids.payeeAgentId,
+    payerAgentId: result.ids.payerAgentId,
+    runStatus: result.runCompleted?.body?.run?.status ?? null,
+    verificationStatus,
+    settlementStatus: result.settlement?.body?.settlement?.status ?? null
+  };
+
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+}
+
+await main();