@shroud-fi/x402 0.1.4 → 0.1.5

package/src/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared types used by both server and client.
+ */
+
+import type { Address, Hex } from 'viem';
+import type {
+  X402FacilitatorConfig,
+  X402PaymentRequirements,
+} from './protocol.js';
+
+/**
+ * Hint object returned alongside a freshly generated challenge.
+ *
+ * The server uses these values to emit an ERC-5564 Announcement event AFTER
+ * the payment settles (out-of-scope for this milestone — operator wires the
+ * on-chain emit). Carrying it on the challenge object lets the server
+ * correlate "this challenge → this announcement" without re-derivation.
+ *
+ * Privacy: contains only the ephemeral public key + view tag + the freshly
+ * derived stealth address. None of these leak the recipient's main wallet.
+ */
+export interface X402StealthAnnouncementHint {
+  readonly ephemeralPubKey: Hex;
+  readonly viewTag: number;
+  readonly stealthAddress: Address;
+}
+
+/**
+ * The full server-side challenge object. Comes out of `x402.challenge(...)`.
+ *
+ * `status` + `headers` + `body` are wire-shaped — operator's HTTP framework
+ * adapter simply spreads them onto its response. `announcement` is internal
+ * metadata for the operator's scanner integration.
+ */
+export interface X402Challenge {
+  readonly status: 402;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: {
+    readonly x402Version: 2;
+    readonly error: string;
+    readonly accepts: readonly X402PaymentRequirements[];
+  };
+  readonly announcement: X402StealthAnnouncementHint;
+}
+
+/**
+ * Result of `x402.verify(...)`.
+ *
+ * Privacy: no amount, no signature, no nonce. `error` is a short tag string
+ * only ('signature_invalid', 'amount_mismatch', 'expired', etc) — never the
+ * full underlying error or any bytes.
+ */
+export interface X402PaymentVerification {
+  readonly valid: boolean;
+  readonly settledTxHash?: Hex;
+  readonly error?: string;
+}
+
+/**
+ * `createX402Server` config.
+ *
+ * Privacy: the `recipientMetaAddress` is the server agent's PUBLIC meta-address
+ * (`st:base:0x...`). No private keys ever appear in this config.
+ */
+export interface X402ServerConfig {
+  /** Transport for reads + chain id lookups. */
+  readonly transport: import('@shroud-fi/transport').ShroudFiTransport;
+  /** ERC-6538 meta-address string (`st:base:0x...`) for the receiving agent. */
+  readonly recipientMetaAddress: string;
+  /** ERC-20 asset address (must be the canonical USDC for the chain). */
+  readonly asset: Address;
+  /** EVM chain id (must match the asset's deployment). */
+  readonly chainId: number;
+  /** Default price in token base units (uint256). */
+  readonly defaultPriceAtomic: bigint;
+  /** Optional facilitator override; defaults to PayAI free-tier. */
+  readonly facilitator?: X402FacilitatorConfig;
+}
+
+/**
+ * `createX402Client` config.
+ *
+ * Privacy: the client uses the transport's `walletClient.account` for
+ * signing. The private key never appears here directly — it lives inside
+ * the viem account, scoped to the transport's lifetime.
+ */
+export interface X402ClientConfig {
+  /** Transport with a configured `walletClient` (account required). */
+  readonly transport: import('@shroud-fi/transport').ShroudFiTransport;
+  /** Optional facilitator override; defaults to PayAI free-tier. */
+  readonly facilitator?: X402FacilitatorConfig;
+}
+
+/**
+ * What a client `.fetch(...)` call surfaces beyond the standard Response.
+ * Non-standard `x402Settlement` property is attached when the server returned
+ * `X-PAYMENT-RESPONSE`. Optional — present only on successful auto-pay.
+ */
+export interface X402PaymentResult {
+  readonly txHash: Hex;
+  readonly settledAt: number;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "test", "node_modules"]
+}