@haven_ai/sdk 0.0.0-dev.202609031523.fd49e1a

package/examples/mcp-x402-sse.ts

@@ -0,0 +1,149 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import {
+  HavenClient,
+  HavenPaymentStateError,
+  type X402ResumeState,
+} from '@haven_ai/sdk'
+
+const mcpUrl = process.env.MCP_URL
+const apiKey = process.env.HAVEN_API_KEY
+const delegateKey = process.env.HAVEN_DELEGATE_KEY
+const baseUrl = process.env.HAVEN_API_URL
+const maxUsd = Number(process.env.MAX_X402_USD ?? '0.05')
+const resumeFile = process.env.HAVEN_X402_RESUME_FILE ?? '.haven-x402-resume.json'
+const resumePaymentId = process.env.HAVEN_RESUME_PAYMENT_ID
+
+if (!mcpUrl) throw new Error('MCP_URL is required')
+if (!apiKey) throw new Error('HAVEN_API_KEY is required')
+if (!delegateKey) throw new Error('HAVEN_DELEGATE_KEY is required')
+
+const haven = new HavenClient({ apiKey, delegateKey, baseUrl })
+
+async function initializeMcpSession(): Promise<string> {
+  const response = await fetch(mcpUrl!, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 'init-1',
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-03-26',
+        capabilities: {},
+        clientInfo: {
+          name: 'haven-x402-mcp-example',
+          version: '1.0.0',
+        },
+      },
+    }),
+  })
+
+  const sessionId = response.headers.get('mcp-session-id')
+  if (!sessionId) {
+    throw new Error('MCP initialize response did not include mcp-session-id')
+  }
+
+  return sessionId
+}
+
+function paidToolCallInit(sessionId: string): RequestInit {
+  return {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+      'mcp-session-id': sessionId,
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 'paid-call-1',
+      method: 'tools/call',
+      params: {
+        name: process.env.MCP_TOOL ?? 'paid_tool',
+        arguments: process.env.MCP_TOOL_ARGS
+          ? JSON.parse(process.env.MCP_TOOL_ARGS)
+          : {},
+      },
+    }),
+  }
+}
+
+function capturedRequest(url: string, init: RequestInit): X402ResumeState['request'] {
+  return {
+    url,
+    method: init.method ?? 'GET',
+    headers: Array.from(new Headers(init.headers).entries()),
+    body: typeof init.body === 'string' ? init.body : undefined,
+  }
+}
+
+async function printResponse(response: Response): Promise<void> {
+  console.log('HTTP', response.status, response.statusText)
+  console.log(await response.text())
+}
+
+async function resumeFromSavedState(): Promise<void> {
+  const state = JSON.parse(await readFile(resumeFile, 'utf8')) as X402ResumeState
+  const response = await haven.resumeX402Payment(state)
+  await printResponse(response)
+}
+
+async function resumeFromPaymentId(paymentId: string): Promise<void> {
+  const state = await haven.getResumeState(paymentId)
+  if (state.rail !== 'x402') {
+    throw new Error(`Payment ${paymentId} is ${state.rail}; this example resumes x402 payments only.`)
+  }
+
+  const sessionId = await initializeMcpSession()
+  const request = paidToolCallInit(sessionId)
+  state.request = capturedRequest(mcpUrl!, request)
+  state.url = state.request.url
+
+  const response = await haven.resumeX402Payment(state)
+  await printResponse(response)
+}
+
+async function quoteAndPay(): Promise<void> {
+  const sessionId = await initializeMcpSession()
+  const request = paidToolCallInit(sessionId)
+  const idempotencyKey = process.env.HAVEN_X402_IDEMPOTENCY_KEY ?? `mcp:${sessionId}:paid-call-1`
+
+  const quote = await haven.quoteX402(mcpUrl!, request, { idempotencyKey })
+  console.log('Quote', {
+    amount: quote.amount,
+    token: quote.token,
+    network: quote.network,
+    merchantAddress: quote.merchantAddress,
+    resourceUrl: quote.resourceUrl,
+  })
+
+  if (Number(quote.amount) > maxUsd) {
+    throw new Error(`Quote ${quote.amount} ${quote.token} is above cap ${maxUsd}`)
+  }
+
+  try {
+    const response = await haven.payX402Quote(quote)
+    await printResponse(response)
+  } catch (err) {
+    if (err instanceof HavenPaymentStateError && err.resumeState) {
+      await writeFile(resumeFile, JSON.stringify(err.resumeState, null, 2))
+      console.error(`Payment did not complete in one pass. Resume state saved to ${resumeFile}.`)
+      console.error(`Once the funding leg confirms, rerun with HAVEN_RESUME_PAYMENT_ID=${err.resumeState.paymentId}.`)
+      console.error(`The local file fallback is still available with HAVEN_X402_RESUME=1.`)
+      return
+    }
+
+    throw err
+  }
+}
+
+if (resumePaymentId) {
+  await resumeFromPaymentId(resumePaymentId)
+} else if (process.env.HAVEN_X402_RESUME === '1') {
+  await resumeFromSavedState()
+} else {
+  await quoteAndPay()
+}

package/examples/x402_openapi_python.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""
+Minimal non-TypeScript x402 proof of concept for the Haven OpenAPI surface.
+
+Requires:
+  pip install requests eth-keys
+
+Environment:
+  HAVEN_API_KEY        sk_agent_* from Haven
+  HAVEN_DELEGATE_KEY   local agent delegate private key; never sent to Haven
+  HAVEN_API_URL        default: https://havenbackend-production-8a00.up.railway.app
+  HAVEN_X402_URL       required: URL of any x402-gated (HTTP 402) resource to pay for
+
+This intentionally uses only documented HTTP endpoints:
+  GET  /openapi.json
+  POST /x402/authorize
+  POST /payments/{id}/sign
+"""
+
+import base64
+import json
+import os
+import sys
+
+import requests
+from eth_keys import keys
+
+
+API = os.environ.get("HAVEN_API_URL", "https://havenbackend-production-8a00.up.railway.app").rstrip("/")
+PAID_URL = os.environ["HAVEN_X402_URL"]  # any x402-gated resource to pay for
+API_KEY = os.environ["HAVEN_API_KEY"]
+DELEGATE_KEY = os.environ["HAVEN_DELEGATE_KEY"]
+
+
+def b64_json(value):
+  return base64.b64encode(json.dumps(value).encode()).decode()
+
+
+def decode_payment_required(response):
+  header = response.headers.get("PAYMENT-REQUIRED")
+  if not header:
+    raise RuntimeError(f"Expected PAYMENT-REQUIRED header, got HTTP {response.status_code}: {response.text}")
+  return json.loads(base64.b64decode(header).decode())
+
+
+def post_haven(path, payload):
+  response = requests.post(
+    f"{API}{path}",
+    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
+    json=payload,
+    timeout=60,
+  )
+  body = response.json()
+  if response.status_code >= 400:
+    raise RuntimeError(f"{path} failed with HTTP {response.status_code}: {body}")
+  return body
+
+
+def sign_raw_hash(sign_hash, private_key):
+  """Sign the raw Safe hash exactly as /payments/{id}/sign expects."""
+  key_hex = private_key[2:] if private_key.startswith("0x") else private_key
+  hash_hex = sign_hash[2:] if sign_hash.startswith("0x") else sign_hash
+  signature = keys.PrivateKey(bytes.fromhex(key_hex)).sign_msg_hash(bytes.fromhex(hash_hex))
+  v = signature.v + 27 if signature.v in (0, 1) else signature.v
+  return (
+    "0x"
+    + signature.r.to_bytes(32, "big").hex()
+    + signature.s.to_bytes(32, "big").hex()
+    + bytes([v]).hex()
+  )
+
+
+spec = requests.get(f"{API}/openapi.json", timeout=30).json()
+authorize_path = "/x402/authorize" if "/x402/authorize" in spec["paths"] else "/x402"
+
+initial = requests.get(PAID_URL, timeout=30)
+if initial.status_code != 402:
+  raise RuntimeError(f"Expected paid resource to return HTTP 402, got {initial.status_code}")
+
+payment_required = decode_payment_required(initial)
+accepted = payment_required["accepts"][0]
+
+authorization = post_haven(authorize_path, {
+  "url": payment_required["resource"]["url"],
+  "payTo": accepted["payTo"],
+  "merchantPayTo": accepted["payTo"],
+  "amount": accepted.get("amount") or accepted["maxAmountRequired"],
+  "asset": accepted["asset"],
+  "network": accepted["network"],
+  "description": payment_required["resource"].get("description"),
+  "idempotencyKey": f"python-openapi:{payment_required['resource']['url']}",
+})
+
+# A payment outside the agent's on-chain budget is DECLINED before any money
+# moves — /x402/authorize answers 403 delegation_budget_exceeded and no intent
+# row is created. There is no approval queue to wait on, so there is nothing to
+# poll: raise the budget in Haven and run this again.
+if not authorization.get("sign_data"):
+  print(json.dumps({
+    "status": authorization.get("status"),
+    "payment_id": authorization.get("payment_id"),
+    "next_action": authorization.get("next_action"),
+    "message": authorization.get("message"),
+  }, indent=2))
+  sys.exit("Haven returned no signing payload for this payment — nothing to sign and nothing queued.")
+
+sign_hash = authorization["sign_data"]["hash"]
+signature = sign_raw_hash(sign_hash, DELEGATE_KEY)
+
+result = post_haven(f"/payments/{authorization['payment_id']}/sign", {"signature": signature})
+tx_hash = result["tx_hash"]
+
+paid = requests.get(PAID_URL, headers={"PAYMENT-SIGNATURE": b64_json({"txHash": tx_hash})}, timeout=30)
+print(json.dumps({
+  "status": paid.status_code,
+  "payment_id": authorization["payment_id"],
+  "tx_hash": tx_hash,
+  "response": paid.json(),
+}, indent=2))

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@haven_ai/sdk",
+  "version": "0.0.0-dev.202609031523.fd49e1a",
+  "description": "TypeScript SDK for Haven — give AI agents budgeted, non-custodial payment ability. Pay x402 (HTTP 402) APIs in USDC within on-chain-enforced spending limits; the agent never holds funds or keys.",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "haven",
+    "ai-agent",
+    "agent-payments",
+    "x402",
+    "402",
+    "payments",
+    "spending-limit",
+    "budget",
+    "usdc",
+    "non-custodial",
+    "mcp",
+    "agentic-commerce",
+    "web3"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/d-hinders/Haven-AI.git",
+    "directory": "packages/sdk"
+  },
+  "dependencies": {
+    "ethers": "^6.13.0",
+    "viem": "^2.51.0",
+    "x402": "^1.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  },
+  "homepage": "https://haven.xyz"
+}