@armory-sh/client-viem 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sawyer Cutler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @armory-sh/client-viem
+
+Viem client for creating and signing Armory payments.
+
+## Install
+
+```bash
+bun add @armory-sh/client-viem
+```
+
+## Use
+
+```typescript
+import { createWalletClient, http } from 'viem'
+import { createArmoryPayment } from '@armory-sh/client-viem'
+
+const client = createWalletClient({ transport: http() })
+
+const payment = await createArmoryPayment(client, {
+  to: '0x...',
+  amount: 1000000n,
+  chainId: 'eip155:8453',
+  assetId: 'eip155:8453/erc20:0x...'
+})
+```
+
+---
+
+MIT License | Sawyer Cutler 2026 | Provided "AS IS" without warranty

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+import { Address, Account, WalletClient, Transport } from 'viem';
+import { CustomToken, PaymentPayloadV1, PaymentPayloadV2, NetworkId, TokenId, ArmoryPaymentResult, ValidationError } from '@armory-sh/base';
+export { ArmoryPaymentResult, FacilitatorConfig, NetworkId, TokenId } from '@armory-sh/base';
+
+type X402Wallet = {
+    type: "account";
+    account: Account;
+} | {
+    type: "walletClient";
+    walletClient: WalletClient;
+};
+type X402ProtocolVersion = 1 | 2 | "auto";
+/** Token configuration - can use pre-configured tokens from @armory-sh/tokens */
+type Token = CustomToken;
+interface X402ClientConfig {
+    wallet: X402Wallet;
+    version?: X402ProtocolVersion;
+    defaultExpiry?: number;
+    nonceGenerator?: () => string;
+    debug?: boolean;
+    /** Pre-configured token object (overrides individual fields below) */
+    token?: Token;
+    /** Override EIP-712 domain name for custom tokens */
+    domainName?: string;
+    /** Override EIP-712 domain version for custom tokens */
+    domainVersion?: string;
+}
+interface X402Client {
+    fetch: typeof fetch;
+    getAddress(): Address;
+    createPayment(amount: string, to: Address, contractAddress: Address, chainId: number, expiry?: number): Promise<PaymentPayloadV1 | PaymentPayloadV2>;
+    signPayment<T extends PaymentPayloadV1 | PaymentPayloadV2>(payload: Omit<T, "signature" | "v" | "r" | "s">): Promise<T>;
+}
+interface X402TransportConfig {
+    wallet: X402Wallet;
+    transport?: Transport;
+    version?: X402ProtocolVersion;
+    defaultExpiry?: number;
+    nonceGenerator?: () => string;
+    debug?: boolean;
+    /** Pre-configured token object */
+    token?: Token;
+    /** Override EIP-712 domain name */
+    domainName?: string;
+    /** Override EIP-712 domain version */
+    domainVersion?: string;
+}
+interface PaymentResult {
+    success: boolean;
+    txHash?: string;
+    error?: string;
+    timestamp: number;
+}
+
+declare const createX402Client: (config: X402ClientConfig) => X402Client;
+declare const createX402Transport: (config: X402TransportConfig) => typeof fetch;
+
+declare class X402ClientError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+declare class SigningError extends X402ClientError {
+    constructor(message: string, cause?: unknown);
+}
+declare class PaymentError extends X402ClientError {
+    constructor(message: string, cause?: unknown);
+}
+
+/**
+ * Simple one-line payment API for Armory
+ * Focus on DX/UX - "everything just magically works"
+ */
+
+/**
+ * Simple wallet configuration
+ * Pass a viem Account or WalletClient directly
+ */
+type SimpleWallet = {
+    account: Account;
+} | {
+    walletClient: WalletClient;
+};
+/**
+ * Make a payment-protected API request with one line of code
+ *
+ * @example
+ * ```ts
+ * const result = await armoryPay(
+ *   { account },                    // wallet
+ *   "https://api.example.com/data", // URL
+ *   "base",                         // network
+ *   "usdc"                          // token
+ * );
+ *
+ * if (result.success) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+declare const armoryPay: <T = unknown>(wallet: SimpleWallet, url: string, network: NetworkId, token: TokenId, options?: {
+    /** Request method (default: GET) */
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** Request body (for POST/PUT/PATCH) */
+    body?: unknown;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Protocol version (default: auto-detect) */
+    version?: 1 | 2 | "auto";
+    /** Payment amount in token units (default: from 402 header) */
+    amount?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}) => Promise<ArmoryPaymentResult<T>>;
+/**
+ * Make a GET request with payment
+ */
+declare const armoryGet: <T = unknown>(wallet: SimpleWallet, url: string, network: NetworkId, token: TokenId, options?: Omit<Parameters<typeof armoryPay>[4], "method">) => Promise<ArmoryPaymentResult<T>>;
+/**
+ * Make a POST request with payment
+ */
+declare const armoryPost: <T = unknown>(wallet: SimpleWallet, url: string, network: NetworkId, token: TokenId, body?: unknown, options?: Omit<Parameters<typeof armoryPay>[4], "method" | "body">) => Promise<ArmoryPaymentResult<T>>;
+/**
+ * Get the wallet address from a SimpleWallet
+ */
+declare const getWalletAddress: (wallet: SimpleWallet) => Address;
+/**
+ * Validate a network identifier without making a request
+ */
+declare const validateNetwork: (network: NetworkId) => ValidationError | {
+    success: true;
+    network: string;
+};
+/**
+ * Validate a token identifier without making a request
+ */
+declare const validateToken: (token: TokenId, network?: NetworkId) => ValidationError | {
+    success: true;
+    token: string;
+    network: string;
+};
+/**
+ * Get list of available networks
+ */
+declare const getNetworks: () => string[];
+/**
+ * Get list of available tokens
+ */
+declare const getTokens: () => string[];
+
+export { PaymentError, type PaymentResult, SigningError, type SimpleWallet, type Token, type X402Client, type X402ClientConfig, X402ClientError, type X402ProtocolVersion, type X402TransportConfig, type X402Wallet, armoryGet, armoryPay, armoryPost, createX402Client, createX402Transport, getNetworks, getTokens, getWalletAddress, validateNetwork, validateToken };

package/dist/index.js

@@ -0,0 +1,421 @@
+// src/client.ts
+import {
+  encodePaymentV1,
+  encodePaymentV2,
+  V1_HEADERS,
+  V2_HEADERS,
+  createEIP712Domain,
+  createTransferWithAuthorization,
+  EIP712_TYPES
+} from "@armory-sh/base";
+
+// src/errors.ts
+var X402ClientError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "X402ClientError";
+    this.cause = cause;
+  }
+};
+var SigningError = class extends X402ClientError {
+  constructor(message, cause) {
+    super(`Signing failed: ${message}`, cause);
+    this.name = "SigningError";
+  }
+};
+var PaymentError = class extends X402ClientError {
+  constructor(message, cause) {
+    super(`Payment failed: ${message}`, cause);
+    this.name = "PaymentError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_EXPIRY = 3600;
+var DEFAULT_NONCE = () => `${Date.now()}`;
+var parseSignature = (signature) => {
+  const sig = signature.slice(2);
+  return {
+    v: parseInt(sig.slice(128, 130), 16) + 27,
+    r: `0x${sig.slice(0, 64)}`,
+    s: `0x${sig.slice(64, 128)}`
+  };
+};
+var getWalletAddress = (wallet) => wallet.type === "account" ? wallet.account.address : wallet.walletClient.account.address;
+var signTypedData = (wallet, domain, types, message) => {
+  if (wallet.type === "account" && !wallet.account.signTypedData) {
+    throw new SigningError("Account does not support signTypedData");
+  }
+  const params = {
+    domain,
+    types,
+    primaryType: "TransferWithAuthorization",
+    message
+  };
+  return wallet.type === "account" ? wallet.account.signTypedData(params) : wallet.walletClient.signTypedData({ ...params, account: wallet.walletClient.account });
+};
+var withCustomDomain = (domain, domainName, domainVersion) => domainName || domainVersion ? { ...domain, name: domainName ?? domain.name, version: domainVersion ?? domain.version } : domain;
+var toNetworkName = (chainId) => chainId === 1 ? "ethereum" : chainId === 8453 ? "base" : "evm";
+var createPaymentV1 = async (wallet, from, to, amount, chainId, contractAddress, nonce, expiry, domainName, domainVersion) => {
+  const domain = createEIP712Domain(chainId, contractAddress);
+  const value = createTransferWithAuthorization({
+    from,
+    to,
+    value: BigInt(Math.floor(parseFloat(amount) * 1e6)),
+    validAfter: 0n,
+    validBefore: BigInt(expiry),
+    nonce: BigInt(nonce)
+  });
+  const signature = await signTypedData(wallet, withCustomDomain(domain, domainName, domainVersion), EIP712_TYPES, value);
+  const { v, r, s } = parseSignature(signature);
+  return { from, to, amount, nonce, expiry, v, r, s, chainId, contractAddress, network: toNetworkName(chainId) };
+};
+var createPaymentV2 = async (wallet, from, to, amount, chainId, assetId, nonce, expiry, domainName, domainVersion) => {
+  const contractAddress = assetId.split(":")[2];
+  const domain = createEIP712Domain(chainId, contractAddress);
+  const value = createTransferWithAuthorization({
+    from,
+    to,
+    value: BigInt(Math.floor(parseFloat(amount) * 1e6)),
+    validAfter: 0n,
+    validBefore: BigInt(expiry),
+    nonce: BigInt(nonce)
+  });
+  const signature = await signTypedData(wallet, withCustomDomain(domain, domainName, domainVersion), EIP712_TYPES, value);
+  const { v, r, s } = parseSignature(signature);
+  return {
+    from,
+    to,
+    amount,
+    nonce,
+    expiry,
+    signature: { v, r, s },
+    chainId: `eip155:${chainId}`,
+    assetId
+  };
+};
+var detectVersion = (response, version) => {
+  if (version === 1) return 1;
+  if (version === 2) return 2;
+  const headers = response.headers;
+  if (headers.has(V1_HEADERS.PAYMENT_RESPONSE) || headers.has("X-PAYMENT-REQUIRED")) {
+    return 1;
+  }
+  return 2;
+};
+var parseRequirements = (response, version) => {
+  if (version === 1) {
+    const text = response.headers.get("X-PAYMENT-REQUIRED");
+    if (text) {
+      try {
+        const json = atob(text);
+        return JSON.parse(json);
+      } catch {
+        throw new PaymentError("Failed to decode v1 payment requirements");
+      }
+    }
+    return {
+      amount: "1.0",
+      network: "base",
+      contractAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      payTo: "0x0000000000000000000000000000000000000000",
+      expiry: Math.floor(Date.now() / 1e3) + 3600
+    };
+  }
+  const v2Text = response.headers.get(V2_HEADERS.PAYMENT_REQUIRED);
+  if (v2Text) {
+    try {
+      return JSON.parse(v2Text);
+    } catch {
+      throw new PaymentError("Failed to decode v2 payment requirements");
+    }
+  }
+  return {
+    amount: "1.0",
+    to: "0x0000000000000000000000000000000000000000",
+    chainId: "eip155:8453",
+    assetId: "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    nonce: `${Date.now()}`,
+    expiry: Math.floor(Date.now() / 1e3) + 3600
+  };
+};
+var createPaymentFromRequirements = async (wallet, requirements, version, getAddress, nonceGenerator, domainName, domainVersion) => {
+  const from = getAddress();
+  const nonce = nonceGenerator();
+  const expiry = requirements.expiry;
+  if (version === 1) {
+    const req2 = requirements;
+    return createPaymentV1(
+      wallet,
+      from,
+      req2.payTo,
+      req2.amount,
+      req2.network === "base" ? 8453 : 1,
+      req2.contractAddress,
+      nonce,
+      expiry,
+      domainName,
+      domainVersion
+    );
+  }
+  const req = requirements;
+  const chainId = parseInt(req.chainId.split(":")[1], 10);
+  const to = typeof req.to === "string" ? req.to : "0x0000000000000000000000000000000000000000";
+  return createPaymentV2(wallet, from, to, req.amount, chainId, req.assetId, nonce, expiry, domainName, domainVersion);
+};
+var addPaymentHeader = (headers, payment, version) => {
+  if (version === 1) {
+    headers.set(V1_HEADERS.PAYMENT, encodePaymentV1(payment));
+  } else {
+    headers.set(V2_HEADERS.PAYMENT_SIGNATURE, encodePaymentV2(payment));
+  }
+};
+var checkSettlement = (response, version) => {
+  const v1Header = response.headers.get(V1_HEADERS.PAYMENT_RESPONSE);
+  const v2Header = response.headers.get(V2_HEADERS.PAYMENT_RESPONSE);
+  let settlement = null;
+  if (version === 1 && v1Header) {
+    try {
+      const json = atob(v1Header);
+      settlement = JSON.parse(json);
+    } catch {
+    }
+  } else if (version === 2 && v2Header) {
+    try {
+      settlement = JSON.parse(v2Header);
+    } catch {
+    }
+  }
+  if (settlement) {
+    const success = "success" in settlement ? settlement.success : settlement.status === "success";
+    if (!success) {
+      const error = "error" in settlement ? settlement.error : "Payment settlement failed";
+      throw new PaymentError(error);
+    }
+  }
+};
+var createFetch = (wallet, config) => {
+  const { version = "auto", nonceGenerator = DEFAULT_NONCE, debug = false, domainName, domainVersion } = config;
+  const getAddress = () => getWalletAddress(wallet);
+  return async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    if (debug) {
+      console.log(`[X402] Fetching: ${url}`);
+    }
+    let response = await fetch(input, init);
+    if (response.status === 402) {
+      if (debug) {
+        console.log(`[X402] Payment required for: ${url}`);
+      }
+      const detectedVersion = detectVersion(response, version);
+      if (debug) {
+        console.log(`[X402] Detected protocol v${detectedVersion}`);
+      }
+      const requirements = parseRequirements(response, detectedVersion);
+      if (debug) {
+        console.log(`[X402] Payment requirements:`, requirements);
+      }
+      const payment = await createPaymentFromRequirements(wallet, requirements, detectedVersion, getAddress, nonceGenerator, domainName, domainVersion);
+      if (debug) {
+        console.log(`[X402] Created payment:`, payment);
+      }
+      const headers = new Headers(init?.headers);
+      addPaymentHeader(headers, payment, detectedVersion);
+      response = await fetch(input, { ...init, headers });
+      if (debug) {
+        console.log(`[X402] Payment response status: ${response.status}`);
+      }
+      checkSettlement(response, detectedVersion);
+    }
+    return response;
+  };
+};
+var extractDomainConfig = (config) => config.token ? { domainName: config.token.name, domainVersion: config.token.version } : { domainName: config.domainName, domainVersion: config.domainVersion };
+var createX402Client = (config) => {
+  const { wallet, version = "auto", defaultExpiry = DEFAULT_EXPIRY, nonceGenerator = DEFAULT_NONCE } = config;
+  const { domainName, domainVersion } = extractDomainConfig(config);
+  const getAddress = () => getWalletAddress(wallet);
+  const fetchFn = createFetch(wallet, { version, defaultExpiry, nonceGenerator, debug: config.debug, domainName, domainVersion });
+  return {
+    fetch: fetchFn,
+    getAddress,
+    async createPayment(amount, to, contractAddress, chainId, expiry) {
+      const from = getAddress();
+      const nonce = nonceGenerator();
+      const validExpiry = expiry ?? Math.floor(Date.now() / 1e3) + defaultExpiry;
+      const targetVersion = version === "auto" ? 1 : version;
+      if (targetVersion === 1) {
+        return createPaymentV1(wallet, from, to, amount, chainId, contractAddress, nonce, validExpiry, domainName, domainVersion);
+      }
+      const assetId = `eip155:${chainId}/erc20:${contractAddress}`;
+      return createPaymentV2(wallet, from, to, amount, chainId, assetId, nonce, validExpiry, domainName, domainVersion);
+    },
+    async signPayment(payload) {
+      const from = getAddress();
+      const chainId = typeof payload.chainId === "number" ? payload.chainId : parseInt(payload.chainId.split(":")[1], 10);
+      const to = payload.to;
+      const expiry = payload.expiry;
+      const nonce = nonceGenerator();
+      if ("contractAddress" in payload) {
+        const input2 = payload;
+        return createPaymentV1(
+          wallet,
+          from,
+          to,
+          input2.amount,
+          chainId,
+          input2.contractAddress,
+          nonce,
+          expiry,
+          domainName,
+          domainVersion
+        );
+      }
+      const input = payload;
+      return createPaymentV2(
+        wallet,
+        from,
+        to,
+        input.amount,
+        chainId,
+        input.assetId,
+        nonce,
+        expiry,
+        domainName,
+        domainVersion
+      );
+    }
+  };
+};
+var createX402Transport = (config) => {
+  const { wallet, transport, version, defaultExpiry, nonceGenerator, debug, token, domainName, domainVersion } = config;
+  return createFetch(wallet, { version, defaultExpiry, nonceGenerator, debug, token, domainName, domainVersion });
+};
+
+// src/simple.ts
+import {
+  resolveNetwork,
+  resolveToken,
+  validatePaymentConfig,
+  isValidationError,
+  getAvailableNetworks,
+  getAvailableTokens
+} from "@armory-sh/base";
+var armoryPay = async (wallet, url, network, token, options) => {
+  try {
+    const x402Wallet = "account" in wallet ? { type: "account", account: wallet.account } : { type: "walletClient", walletClient: wallet.walletClient };
+    const config = validatePaymentConfig(network, token);
+    if (isValidationError(config)) {
+      return {
+        success: false,
+        code: config.code,
+        message: config.message,
+        details: config
+      };
+    }
+    const client = createX402Client({
+      wallet: x402Wallet,
+      version: options?.version ?? "auto",
+      token: config.token.config,
+      debug: options?.debug ?? false
+    });
+    const method = options?.method ?? "GET";
+    const headers = new Headers(options?.headers ?? {});
+    let response;
+    if (method === "GET") {
+      response = await client.fetch(url, { method, headers });
+    } else {
+      response = await client.fetch(url, {
+        method,
+        headers,
+        body: JSON.stringify(options?.body)
+      });
+    }
+    if (response.status === 402) {
+      return {
+        success: false,
+        code: "PAYMENT_REQUIRED",
+        message: "Payment required but could not be completed automatically"
+      };
+    }
+    if (!response.ok) {
+      const error = await response.text();
+      return {
+        success: false,
+        code: "PAYMENT_DECLINED",
+        message: `Request failed: ${response.status} ${error}`
+      };
+    }
+    const data = await response.json();
+    const txHash = response.headers.get("X-PAYMENT-RESPONSE") || response.headers.get("PAYMENT-RESPONSE");
+    return {
+      success: true,
+      data,
+      ...txHash && { txHash }
+    };
+  } catch (error) {
+    return {
+      success: false,
+      code: "NETWORK_ERROR",
+      message: error instanceof Error ? error.message : "Unknown error occurred",
+      details: error
+    };
+  }
+};
+var armoryGet = (wallet, url, network, token, options) => {
+  return armoryPay(wallet, url, network, token, { ...options, method: "GET" });
+};
+var armoryPost = (wallet, url, network, token, body, options) => {
+  return armoryPay(wallet, url, network, token, { ...options, method: "POST", body });
+};
+var getWalletAddress2 = (wallet) => {
+  return "account" in wallet ? wallet.account.address : wallet.walletClient.account.address;
+};
+var validateNetwork = (network) => {
+  const resolved = resolveNetwork(network);
+  if (isValidationError(resolved)) {
+    return resolved;
+  }
+  return { success: true, network: resolved.config.name };
+};
+var validateToken = (token, network) => {
+  let resolvedNetwork = void 0;
+  if (network) {
+    const networkResult = resolveNetwork(network);
+    if (isValidationError(networkResult)) {
+      return networkResult;
+    }
+    resolvedNetwork = networkResult;
+  }
+  const resolved = resolveToken(token, resolvedNetwork);
+  if (isValidationError(resolved)) {
+    return resolved;
+  }
+  return {
+    success: true,
+    token: resolved.config.symbol,
+    network: resolved.network.config.name
+  };
+};
+var getNetworks = () => {
+  return getAvailableNetworks();
+};
+var getTokens = () => {
+  return getAvailableTokens();
+};
+export {
+  PaymentError,
+  SigningError,
+  X402ClientError,
+  armoryGet,
+  armoryPay,
+  armoryPost,
+  createX402Client,
+  createX402Transport,
+  getNetworks,
+  getTokens,
+  getWalletAddress2 as getWalletAddress,
+  validateNetwork,
+  validateToken
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@armory-sh/client-viem",
+  "version": "0.2.0",
+  "license": "MIT",
+  "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/*": "./dist/*.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thegreataxios/armory.git",
+    "directory": "packages/client-viem"
+  },
+  "dependencies": {
+    "@armory-sh/base": "workspace:*",
+    "viem": "2.45.0"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "bun-types": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "example": "bun run examples/"
+  }
+}