@haven_ai/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,636 @@
+import { ethers } from 'ethers';
+
+// src/signer.ts
+
+// src/types.ts
+var HavenError = class extends Error {
+  constructor(message, code, statusCode, paymentId) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.paymentId = paymentId;
+    this.name = "HavenError";
+  }
+  code;
+  statusCode;
+  paymentId;
+};
+var HavenApiError = class extends HavenError {
+  constructor(message, statusCode, body) {
+    super(message, "API_ERROR", statusCode);
+    this.body = body;
+    this.name = "HavenApiError";
+  }
+  body;
+};
+var HavenSigningError = class extends HavenError {
+  constructor(message) {
+    super(message, "SIGNING_ERROR");
+    this.name = "HavenSigningError";
+  }
+};
+var HavenTimeoutError = class extends HavenError {
+  constructor(paymentId) {
+    super(
+      `Timed out waiting for payment ${paymentId} to confirm`,
+      "TIMEOUT",
+      void 0,
+      paymentId
+    );
+    this.name = "HavenTimeoutError";
+  }
+};
+
+// src/signer.ts
+function signHash(privateKey, hash) {
+  try {
+    const signingKey = new ethers.SigningKey(privateKey);
+    const sig = signingKey.sign(hash);
+    return sig.serialized;
+  } catch (err) {
+    throw new HavenSigningError(
+      `Failed to sign hash: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function addressFromKey(privateKey) {
+  try {
+    return new ethers.Wallet(privateKey).address;
+  } catch (err) {
+    throw new HavenSigningError(
+      `Invalid private key: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function verifySignature(hash, signature, expectedAddress) {
+  try {
+    const recovered = ethers.recoverAddress(hash, signature);
+    return recovered.toLowerCase() === expectedAddress.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+// src/x402.ts
+var SUPPORTED_X402_NETWORKS = {
+  "eip155:100": "Gnosis Chain",
+  "eip155:8453": "Base"
+};
+var GNOSIS_TOKENS = {
+  "0x0000000000000000000000000000000000000000": { symbol: "xDAI", decimals: 18 },
+  "0xcb444e90d8198415266c6a2724b7900fb12fc56e": { symbol: "EURe", decimals: 18 },
+  "0x2a22f9c3b484c3629090feed35f17ff8f88f76f0": { symbol: "USDC.e", decimals: 6 }
+};
+var BASE_TOKENS = {
+  "0x0000000000000000000000000000000000000000": { symbol: "ETH", decimals: 18 },
+  "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": { symbol: "USDC", decimals: 6 }
+};
+var NETWORK_TOKENS = {
+  "eip155:100": GNOSIS_TOKENS,
+  "eip155:8453": BASE_TOKENS
+};
+function parsePaymentRequired(response) {
+  const v2Header = response.headers.get("PAYMENT-REQUIRED");
+  if (v2Header) {
+    try {
+      return JSON.parse(atob(v2Header));
+    } catch {
+      throw new Error("Failed to decode PAYMENT-REQUIRED header");
+    }
+  }
+  const v1Header = response.headers.get("X-PAYMENT");
+  if (v1Header) {
+    try {
+      return JSON.parse(atob(v1Header));
+    } catch {
+      throw new Error("Failed to decode X-PAYMENT header");
+    }
+  }
+  throw new Error(
+    "No x402 payment headers found in 402 response. Expected PAYMENT-REQUIRED (v2) or X-PAYMENT (v1) header."
+  );
+}
+function selectPaymentOption(accepts) {
+  if (!accepts || accepts.length === 0) return null;
+  for (const opt of accepts) {
+    if (opt.network in SUPPORTED_X402_NETWORKS) {
+      const networkTokens = NETWORK_TOKENS[opt.network];
+      if (networkTokens?.[opt.asset.toLowerCase()]) return opt;
+    }
+  }
+  for (const opt of accepts) {
+    if (opt.network in SUPPORTED_X402_NETWORKS) {
+      return opt;
+    }
+  }
+  return null;
+}
+function encodePaymentProof(receipt) {
+  const payload = {
+    x402Version: 2,
+    payload: {
+      txHash: receipt.txHash,
+      paymentId: receipt.paymentId,
+      settledVia: "haven"
+    }
+  };
+  return btoa(JSON.stringify(payload));
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "http://localhost:3001";
+var CHAIN_EXPLORER_TX = {
+  100: "https://gnosisscan.io/tx",
+  8453: "https://basescan.org/tx"
+};
+function buildExplorerUrl(chainId, txHash) {
+  const base = CHAIN_EXPLORER_TX[chainId ?? 100] ?? CHAIN_EXPLORER_TX[100];
+  return `${base}/${txHash}`;
+}
+var DEFAULT_REQUEST_TIMEOUT = 3e4;
+var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
+var DEFAULT_POLLING_INTERVAL = 3e3;
+var HavenClient = class {
+  apiKey;
+  delegateKey;
+  baseUrl;
+  requestTimeout;
+  confirmationTimeout;
+  pollingInterval;
+  /** Delegate address derived from the private key (if provided) */
+  delegateAddress;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.delegateKey = config.delegateKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
+    this.confirmationTimeout = config.confirmationTimeout ?? DEFAULT_CONFIRMATION_TIMEOUT;
+    this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
+    if (this.delegateKey) {
+      this.delegateAddress = addressFromKey(this.delegateKey);
+    }
+  }
+  // ── High-Level API ───────────────────────────────────────────────
+  /**
+   * Send a payment in one call.
+   *
+   * Creates the intent, signs the hash, submits the signature,
+   * and polls until confirmed (or throws on failure/timeout).
+   *
+   * Requires `delegateKey` to be set in the client config.
+   */
+  async pay(request) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "Cannot use pay() without a delegateKey. Use createIntent() + submitSignature() for manual signing."
+      );
+    }
+    const intent = await this.createIntent(request);
+    const signature = this.sign(intent.signData.hash);
+    await this.submitSignature(intent.paymentId, signature);
+    return this.waitForConfirmation(intent.paymentId);
+  }
+  // ── Step-by-Step API ─────────────────────────────────────────────
+  /**
+   * Step 1: Create a payment intent.
+   *
+   * Returns the intent with the hash to sign.
+   */
+  async createIntent(request) {
+    const raw = await this.post("/payments", {
+      token: request.token,
+      amount: request.amount,
+      to: request.to
+    });
+    return {
+      paymentId: raw.payment_id,
+      status: "pending_signature",
+      expiresAt: raw.expires_at,
+      signData: raw.sign_data
+    };
+  }
+  /**
+   * Step 2: Sign a hash with the delegate key.
+   *
+   * Returns the 65-byte signature (0x-prefixed).
+   * Requires `delegateKey` to be set in the client config.
+   */
+  sign(hash) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "Cannot sign without a delegateKey. Pass the private key in HavenClient config, or sign externally."
+      );
+    }
+    const signature = signHash(this.delegateKey, hash);
+    if (!verifySignature(hash, signature, this.delegateAddress)) {
+      throw new HavenSigningError(
+        "Local signature verification failed \u2014 recovered address does not match delegate key."
+      );
+    }
+    return signature;
+  }
+  /**
+   * Step 3: Submit a signature to execute the payment.
+   *
+   * The signature can come from `client.sign()` or from external signing.
+   */
+  async submitSignature(paymentId, signature) {
+    const raw = await this.post(
+      `/payments/${paymentId}/sign`,
+      { signature }
+    );
+    return {
+      status: raw.status,
+      txHash: raw.tx_hash
+    };
+  }
+  /**
+   * Get the current status of a payment.
+   */
+  async getPayment(paymentId) {
+    const raw = await this.get(`/payments/${paymentId}`);
+    return this.mapPaymentResult(raw);
+  }
+  /**
+   * Poll until a payment reaches a terminal status (confirmed, failed, expired).
+   */
+  async waitForConfirmation(paymentId) {
+    const deadline = Date.now() + this.confirmationTimeout;
+    while (Date.now() < deadline) {
+      const result = await this.getPayment(paymentId);
+      if (result.status === "confirmed" || result.status === "failed" || result.status === "expired") {
+        return result;
+      }
+      await sleep(this.pollingInterval);
+    }
+    throw new HavenTimeoutError(paymentId);
+  }
+  // ── x402 Protocol Support ────────────────────────────────────────
+  /**
+   * Authorize an x402 payment.
+   *
+   * Takes the parsed PaymentRequired from a 402 response, selects a
+   * compatible payment option, signs and executes the payment through Haven.
+   *
+   * Requires `delegateKey` to be set in the client config.
+   */
+  async authorizeX402(paymentRequired) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "delegateKey is required for x402 payments. Pass it in the HavenClient config."
+      );
+    }
+    const option = selectPaymentOption(paymentRequired.accepts);
+    if (!option) {
+      throw new HavenApiError(
+        "No compatible payment option found in x402 requirements. Haven supports Gnosis Chain (eip155:100) and Base (eip155:8453).",
+        400
+      );
+    }
+    const raw = await this.post("/x402", {
+      url: paymentRequired.resource.url,
+      payTo: option.payTo,
+      amount: option.amount,
+      asset: option.asset,
+      network: option.network,
+      description: paymentRequired.resource.description
+    });
+    if (raw.success && raw.tx_hash) {
+      return {
+        success: true,
+        paymentId: raw.payment_id,
+        txHash: raw.tx_hash,
+        token: raw.token ?? "",
+        amount: raw.amount ?? "",
+        to: raw.to ?? "",
+        resourceUrl: paymentRequired.resource.url,
+        explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl(raw.chain_id, raw.tx_hash) : "")
+      };
+    }
+    if (!raw.sign_data?.hash) {
+      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+    }
+    const sig = signHash(this.delegateKey, raw.sign_data.hash);
+    const execResult = await this.post(
+      `/payments/${raw.payment_id}/sign`,
+      { signature: sig }
+    );
+    if (execResult.status !== "confirmed") {
+      throw new HavenApiError(
+        execResult.error ?? `x402 payment ${execResult.status}`,
+        502,
+        execResult
+      );
+    }
+    return {
+      success: true,
+      paymentId: raw.payment_id,
+      txHash: execResult.tx_hash ?? "",
+      token: execResult.token ?? raw.token ?? "",
+      amount: execResult.amount ?? raw.amount ?? "",
+      to: execResult.to ?? raw.to ?? "",
+      resourceUrl: paymentRequired.resource.url,
+      explorerUrl: execResult.explorer_url ?? (execResult.tx_hash ? buildExplorerUrl(execResult.chain_id, execResult.tx_hash) : "")
+    };
+  }
+  /**
+   * Fetch wrapper that automatically handles HTTP 402 responses.
+   *
+   * Works like the standard `fetch()` but intercepts 402 responses,
+   * pays via x402 through Haven, and retries the request.
+   *
+   * ```ts
+   * const response = await haven.fetch('https://paid-api.com/data')
+   * const data = await response.json()
+   * ```
+   *
+   * Requires `delegateKey` to be set in the client config.
+   */
+  async fetch(url, init) {
+    const response = await globalThis.fetch(url, init);
+    if (response.status !== 402) return response;
+    let paymentRequired;
+    try {
+      paymentRequired = parsePaymentRequired(response);
+    } catch {
+      return response;
+    }
+    const receipt = await this.authorizeX402(paymentRequired);
+    const retryHeaders = new Headers(init?.headers);
+    retryHeaders.set("PAYMENT-SIGNATURE", encodePaymentProof(receipt));
+    return globalThis.fetch(url, {
+      ...init,
+      headers: retryHeaders
+    });
+  }
+  // ── Tool Execution (for agent frameworks) ────────────────────────
+  /**
+   * Execute a tool call by name and input.
+   *
+   * Designed to plug directly into agent tool-call handlers:
+   *
+   * ```ts
+   * if (block.type === 'tool_use') {
+   *   const result = await haven.executeTool(block.name, block.input)
+   *   // send result back to the model
+   * }
+   * ```
+   */
+  async executeTool(toolName, input) {
+    if (toolName === "make_payment") {
+      const { token, amount, to } = input;
+      try {
+        const result = await this.pay({ token, amount, to });
+        return {
+          success: result.status === "confirmed",
+          payment_id: result.paymentId,
+          status: result.status,
+          tx_hash: result.txHash,
+          token: result.token,
+          amount: result.amount,
+          to: result.to,
+          explorer_url: result.explorerUrl,
+          error: result.errorMessage
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }
+    if (toolName === "authorize_x402_payment") {
+      const { url, payTo, amount, asset, network, description } = input;
+      try {
+        const receipt = await this.authorizeX402({
+          x402Version: 2,
+          resource: { url, description },
+          accepts: [
+            {
+              scheme: "exact",
+              network,
+              amount,
+              asset,
+              payTo,
+              maxTimeoutSeconds: 30
+            }
+          ]
+        });
+        return {
+          success: true,
+          payment_id: receipt.paymentId,
+          tx_hash: receipt.txHash,
+          token: receipt.token,
+          amount: receipt.amount,
+          to: receipt.to,
+          resource_url: receipt.resourceUrl,
+          explorer_url: receipt.explorerUrl
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }
+    if (toolName === "get_payment_status") {
+      const { payment_id } = input;
+      const result = await this.getPayment(payment_id);
+      return {
+        payment_id: result.paymentId,
+        status: result.status,
+        tx_hash: result.txHash,
+        token: result.token,
+        amount: result.amount,
+        to: result.to,
+        explorer_url: result.explorerUrl
+      };
+    }
+    throw new Error(`Unknown tool: ${toolName}`);
+  }
+  // ── HTTP Helpers ─────────────────────────────────────────────────
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.requestTimeout);
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        const message = data.error ?? data.details ?? `API request failed`;
+        throw new HavenApiError(message, res.status, data);
+      }
+      return data;
+    } catch (err) {
+      if (err instanceof HavenApiError) throw err;
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new HavenApiError(`Request to ${path} timed out`, 408);
+      }
+      throw new HavenApiError(
+        `Request to ${path} failed: ${err instanceof Error ? err.message : String(err)}`,
+        0
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  // ── Mapping Helpers ──────────────────────────────────────────────
+  mapPaymentResult(raw) {
+    return {
+      paymentId: raw.payment_id,
+      status: raw.status,
+      token: raw.token,
+      amount: raw.amount,
+      to: raw.to,
+      txHash: raw.tx_hash,
+      errorMessage: raw.error_message,
+      explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl(raw.chain_id, raw.tx_hash) : null),
+      createdAt: raw.created_at,
+      signedAt: raw.signed_at,
+      submittedAt: raw.submitted_at,
+      confirmedAt: raw.confirmed_at,
+      expiresAt: raw.expires_at
+    };
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/tools.ts
+var makePaymentSchema = {
+  type: "object",
+  properties: {
+    token: {
+      type: "string",
+      description: "Token to send. Gnosis Chain: EURe, USDC.e, xDAI. Base: USDC, ETH."
+    },
+    amount: {
+      type: "string",
+      description: 'Amount to send as a decimal string, e.g. "5.00"'
+    },
+    to: {
+      type: "string",
+      description: "Recipient Ethereum address (0x...)"
+    },
+    reason: {
+      type: "string",
+      description: "Brief reason for this payment (for audit trail)"
+    }
+  },
+  required: ["token", "amount", "to", "reason"]
+};
+var getPaymentStatusSchema = {
+  type: "object",
+  properties: {
+    payment_id: {
+      type: "string",
+      description: "The payment ID returned from make_payment"
+    }
+  },
+  required: ["payment_id"]
+};
+var authorizeX402Schema = {
+  type: "object",
+  properties: {
+    url: {
+      type: "string",
+      description: "The URL that returned HTTP 402"
+    },
+    payTo: {
+      type: "string",
+      description: "Payment recipient address from the 402 response"
+    },
+    amount: {
+      type: "string",
+      description: 'Payment amount in atomic units (e.g. "1000000" for 1 USDC)'
+    },
+    asset: {
+      type: "string",
+      description: "Token contract address from the 402 response"
+    },
+    network: {
+      type: "string",
+      description: 'CAIP-2 chain ID. "eip155:100" for Gnosis Chain, "eip155:8453" for Base.'
+    },
+    description: {
+      type: "string",
+      description: "Description of the resource being paid for"
+    }
+  },
+  required: ["url", "payTo", "amount", "asset", "network"]
+};
+var MAKE_PAYMENT_DESCRIPTION = "Send a payment from the Haven-managed Safe wallet. The payment will be validated against the agent's on-chain spending policy. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
+var GET_STATUS_DESCRIPTION = "Check the status of a previously initiated payment. Returns the current status, transaction hash (if confirmed), and payment details.";
+var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns 402 with x402 payment requirements, use this tool to pay and get access. Haven evaluates the payment against policy and executes from the Safe wallet.";
+function claudeTools() {
+  return [
+    {
+      name: "make_payment",
+      description: MAKE_PAYMENT_DESCRIPTION,
+      input_schema: makePaymentSchema
+    },
+    {
+      name: "get_payment_status",
+      description: GET_STATUS_DESCRIPTION,
+      input_schema: getPaymentStatusSchema
+    },
+    {
+      name: "authorize_x402_payment",
+      description: AUTHORIZE_X402_DESCRIPTION,
+      input_schema: authorizeX402Schema
+    }
+  ];
+}
+function openaiTools() {
+  return [
+    {
+      type: "function",
+      function: {
+        name: "make_payment",
+        description: MAKE_PAYMENT_DESCRIPTION,
+        parameters: makePaymentSchema
+      }
+    },
+    {
+      type: "function",
+      function: {
+        name: "get_payment_status",
+        description: GET_STATUS_DESCRIPTION,
+        parameters: getPaymentStatusSchema
+      }
+    },
+    {
+      type: "function",
+      function: {
+        name: "authorize_x402_payment",
+        description: AUTHORIZE_X402_DESCRIPTION,
+        parameters: authorizeX402Schema
+      }
+    }
+  ];
+}
+var havenTools = {
+  /** Tool definitions in Anthropic/Claude format */
+  claude: claudeTools,
+  /** Tool definitions in OpenAI function-calling format */
+  openai: openaiTools
+};
+
+export { HavenApiError, HavenClient, HavenError, HavenSigningError, HavenTimeoutError, addressFromKey, encodePaymentProof, havenTools, parsePaymentRequired, selectPaymentOption, signHash, verifySignature };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map