@cloudpayx/x402-pay 0.2.3 → 0.2.4

package/README.md

@@ -16,6 +16,23 @@ Self-funded agents can integrate without a cloudpayX account, dashboard, or mand
 **Protocol:** x402 V2, `exact`  
 **Assets:** XRP, RLUSD, Circle USDC
 
+## Quick start: validate a payment configuration
+
+Start with a no-wallet example before connecting a live XRPL signer.
+
+From the SDK project:
+
+    npm install
+    node examples/quickstart-validation.mjs
+
+The example imports the published SDK interface, configures an XRP purchase, and calls `validateSecureNodePurchase()`.
+
+It uses placeholder addresses and a signer that refuses to sign. **No funds move.**
+
+Validation confirms the guarded configuration structure. It does not authorize a payment, validate an address checksum, or verify settlement.
+
+For live integration, replace the placeholders with a compatible XRPL signer, real payment details, and your own authorization policy. Use `executeSecureNodePurchase()` for execution and `reconcileSecureNodePurchase()` for settlement verification.
+
 ## Capabilities
 
 - **Autonomous agent payments:** Agents can purchase compatible x402 resources using their own XRPL signing infrastructure.
@@ -69,16 +86,6 @@ Applications must secure their XRPL signing credentials independently. An agent
 
 Issued-token payments require applicable trustlines, sufficient balances, and XRP for network fees and reserves. Third-party resource delivery depends on the seller and network conditions.
 
-## Testing
-
-The v0.2.2 implementation completed:
-
-- **234 automated tests passed**
-- **0 test failures**
-- **Successful TypeScript build**
-
-Test coverage includes supported assets, authorization, guarded signing, persistent budgets, transaction journaling, HTTP resource protections, and settlement reconciliation.
-
 ## Resources
 
 - Website: https://cloudpayx.com

package/examples/quickstart-validation.mjs

@@ -0,0 +1,65 @@
+import { validateSecureNodePurchase } from '@cloudpayx/x402-pay';
+
+// Example-only addresses. No real wallet or signing credentials.
+const payer = 'r' + 'A'.repeat(25);
+const seller = 'r' + 'B'.repeat(25);
+const resource = 'https://example.com/paid-resource';
+
+const purchase = {
+  intent: {
+    intentId: 'cpx-quickstart-0001',
+    payer,
+    seller,
+    resource,
+    asset: 'XRP',
+    amount: '1000' // XRP amounts are in drops
+  },
+  journalDir: './cpx-quickstart-journal',
+  budgetCaps: {
+    xrpDrops: '1000000',
+    rlusd: '2',
+    usdc: '2'
+  },
+  signer: {
+    classicAddress: payer,
+    sign: async () => {
+      throw new Error('DEMO_SIGNING_DISABLED');
+    }
+  },
+  policy: {
+    assets: [{
+      kind: 'xrp',
+      asset: 'XRP',
+      maxAmountDrops: '1000'
+    }],
+    recipients: {
+      mode: 'allowlist',
+      addresses: [seller]
+    },
+    approval: {
+      mode: 'callback',
+      authorize: async () => false
+    }
+  },
+  oneShot: {
+    recipient: seller,
+    asset: 'XRP',
+    exactAmount: '1000',
+    maxFeeDrops: '100'
+  },
+  maxFeeDrops: '100',
+  request: {
+    url: resource,
+    init: {
+      method: 'POST',
+      body: '{}'
+    }
+  }
+};
+
+const valid = validateSecureNodePurchase(purchase);
+
+console.log('cpX x402 Pay');
+console.log('Configuration valid:', valid);
+console.log('No wallet connected. No transaction signed or submitted.');
+console.log('This checks configuration shape, not payment authorization or settlement.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudpayx/x402-pay",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "description": "XRPL-native x402 payment SDK for autonomous AI agents. Secure, wallet-agnostic XRP, RLUSD and Circle USDC payments with spending policies and verified settlement.",
   "dependencies": {
@@ -38,6 +38,7 @@
     "scripts/trusted-xrpl-primitives.mjs",
     "scripts/trusted-xrpl-recovery.mjs",
     "types/",
-    "README.md"
+    "README.md",
+    "examples/quickstart-validation.mjs"
   ]
 }

package/types/public-node.d.ts

@@ -1,4 +1,4 @@
-/** cpX x402 Pay private pre-release Node API; no wallet keys are handled here. */
+/** cpX x402 Pay supported Node.js API; no wallet keys are handled here. */
 import type { ClientXrplSigner } from '@x402/xrpl';
 import type { AgentPaymentConfig } from '../dist/src/policy.js';
 import type { GuardOptions } from '../dist/src/one_shot_guard.js';

package/README.before-0.2.3.bak

@@ -1,94 +0,0 @@
-# cpX x402 Pay | XRPL Agent Payment SDK
-
-**Purpose:** Let an unaffiliated, self-funded agent participate in the XRPL x402 economy without a cloudpayX registration, dashboard, Supabase session, or required wallet brand. This is an XRPL-native SDK for autonomous agents purchasing x402-protected resources.
-
-The SDK supports wallet-agnostic signing, three-asset payment policies, spending controls, guarded signing, and validated-ledger reconciliation. Agents must use compatible XRPL signers and maintain sufficient funds.
-
-## Source
-
-- `src/policy.ts` — strict, dependency-free XRPL x402 V2 policy checks.
-- `src/assets.ts` — verified XRPL mainnet XRP / Ripple RLUSD / Circle USDC identity constants and three-asset policy builder.
-- `src/index.ts` — adapter to the existing proven `@x402/core`, `@x402/fetch`, `@x402/xrpl` client.
-- `examples/feral-agent.example.ts` — signer-injection example; no secrets or hardcoded wallet provider.
-- `examples/simulation-only.mjs` — no-wallet, no-network, no-payment demonstration.
-- `tests/policy.test.mjs` and `tests/three-assets.test.mjs` — locally executable approval/denial tests for all three assets.
-
-## On your Mac (do not deploy yet)
-
-**Keep this a separate test folder, do not copy over `src/cloudpayx_x402_pay.ts` or `src/cloudpayx_x402_pay_configured.ts`.**
-
-1. Unzip, open Terminal in the unzipped directory.
-2. Run `npm install` (the official `@x402/*` packages are required for the SDK adapter).
-3. Run `npm run test:policy` and `npm run demo:dry-run`.
-4. Run `npm run build` to check SDK integration types against the actual installed packages.
-
-`npm run test:policy` needs only the TypeScript compiler, Node.js, and the dependency-free policy module. The build needs official x402 packages; network/package installation was unavailable during packaging.
-
-## Three verified XRPL mainnet assets
-
-The optional helper `createThreeAssetPolicy` pins the network to `xrpl:0` and enables ONLY these official asset identities:
-
-| Asset | x402 `asset` | x402 `extra.issuer` | Max amount unit |
-| --- | --- | --- | --- |
-| XRP | `XRP` | None | Integer drops (1 XRP = 1,000,000 drops) |
-| Ripple RLUSD | `524C555344000000000000000000000000000000` | `rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De` | Decimal RLUSD tokens |
-| Circle USDC on XRPL | `5553444300000000000000000000000000000000` | `rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE` | Decimal USDC tokens |
-
-Only these XRPL issuances are accepted by this helper, *not* similarly named bridged tokens, Base USDC, or arbitrary USD IOUs. Signing always uses a caller-supplied `ClientXrplSigner`. **There is no automatic token conversion, exchange quoting, currency netting, or account registration.**
-
-## Sample: permissionless, self-funded agent using all three
-
-```ts
-import { createCpXX402AgentPay, createThreeAssetPolicy } from './src/index.js';
-
-const { paidFetch } = createCpXX402AgentPay({
-  signer: MY_SECURE_XRPL_SIGNER, // compatible @x402/xrpl ClientXrplSigner
-  policy: createThreeAssetPolicy({
-    limits: {
-      xrpDrops: '50000', // 0.05 XRP
-      rlusd: '0.05',    // 0.05 RLUSD
-      usdc: '0.05'      // 0.05 Circle USDC (XRPL)
-    },
-    recipients: { mode: 'any' }, // opt-in open seller participation
-    approval: { mode: 'autonomous' } // explicit local operator/agent opt-in
-  })
-});
-const response = await paidFetch('https://a-trusted-x402-resource.example/report');
-```
-
-`MY_SECURE_XRPL_SIGNER` and seller URL are placeholders. Don't paste wallet secrets into this file. **An unknown agent can use the SDK with its own signer, but does not gain authority over anyone else's funds.**
-
-`npm run demo:dry-run` simulates XRP, RLUSD, and USDC policy decisions without a wallet or network.
-
-## Units are not interchangeable
-
-| XRPL asset | x402 `amount` units | `maxAmount...` example |
-| --- | --- | --- |
-| Native XRP | Drops (1,000,000 drops = 1 XRP) | `{kind:'xrp',asset:'XRP',maxAmountDrops:'50000'}` = 0.05 XRP |
-| RLUSD, USDC or other XRPL-issued token | Decimal issued-token value | `{kind:'issued', asset:'...', issuer:'...', maxAmount:'0.05'}` = 0.05 token |
-
-This module rejects scientific notation and prices above its exact cap. Limits are independent; they are **not** an equivalent USD portfolio budget. **Network fees are extra; the per-payment cap bounds the x402 transfer amount, not the combined cost including XRPL fees, trustline reserves, or issuer transfer fees.** XRPL recipient validation here only checks basic address *shape*. The underlying SDK/signer/facilitator must validate destination checksum, invoice/transaction binding, signature authorization, settlement, and errors.
-
-## Security boundaries
-
-- No Xaman dependency and no human cloudpayX account required for self-funded agents.
-- Strict XRPL mainnet `xrpl:0`, x402 V2, `exact` scheme, `areFeesSponsored=false`.
-- Explicit assets and exact amount caps; opt-in seller-neutral recipient policy or allowlist.
-- Explicit `autonomous` opt-in or application-provided authorization callback, with fail-closed exceptions.
-- A self-funded agent retains *unrestricted authority over its own signer*. A local SDK is **not a trust boundary** against an agent holding the key: it can bypass these checks. Hardware signers, dedicated wallets, and controlled signer services are needed for stronger enforcement.
-- **Security protections:** Spending budgets, duplicate-payment protection, resource-host validation, anti-SSRF controls, replay protection, fee budgeting, guarded signing, and validated-ledger reconciliation are covered by the SDK's security tests. These controls apply when payments use the guarded SDK interface.
-- The live x402 facilitator/service should validate transaction signatures and bind invoice, amount, asset, destination and network, as described in the XRPL exact scheme spec.
-
-## Operational conditions for USDC and RLUSD
-
-The agent wallet must have the required XRPL token trustline/balance/authorization (where applicable) and enough XRP for transaction fees and reserves. A valid policy decision **does not** guarantee a successful token payment or a resource response. The resource server must advertise a compatible x402 `accepts` entry; the SDK does not auto-swap XRP into stablecoins.
-
-XRPL-issued assets require sufficient balances, applicable trustlines, and XRP for fees and reserves. Payment success and resource delivery depend on the network and seller. An agent with unrestricted access to its own signing keys can bypass local SDK policies.
-
-**Official issuers:** [Ripple RLUSD](https://docs.ripple.com/products/stablecoin/developer-resources/rlusd-on-the-xrpl) and [Circle XRPL USDC](https://www.circle.com/blog/now-available-usdc-on-the-xrpl).
-
-## Integration guidance
-
-Use a dedicated, limited-balance XRPL wallet when integrating a new signer or seller. Validate the complete payment and resource-delivery flow before granting unattended spending authority. For stronger enforcement, keep signing authority outside the agent's direct control.
-
-Specifications: https://github.com/x402-foundation/x402/blob/main/specs/schemes/exact/scheme_exact_xrpl.md