@sluzen/sdk 1.0.0

package/README.md

@@ -0,0 +1,38 @@
+# @sluzen/sdk
+
+Client for **Sluzen** (x402 on the XRP Ledger).
+
+Agents and applications use this package to call HTTP APIs that require on-chain payment before granting access. Typed x402 contracts, a Base64 challenge codec, and `AgentClient` handle the handshake: decode the challenge, sign an XRPL `Payment` in **XRP drops** (`challenge.amount` is an integer drop count, not USD), retry with `PAYMENT-SIGNATURE`. Issued currencies (IOU/RLUSD) are not supported.
+
+## HTTP 402
+
+- **Challenge:** `402` **with** `PAYMENT-REQUIRED`. Only this is a quote to sign.
+- **Settlement / bind failure:** `402` **without** that header (or `409` replay). Do not treat every 402 as “sign this header”. `AgentClient` only negotiates the unsigned 402 that carries `PAYMENT-REQUIRED`.
+
+## Installation
+
+```bash
+npm i @sluzen/sdk
+```
+
+## Usage
+
+Set `CLIENT_WALLET_SEED` (XRPL wallet seed) and `XRPL_NODE` (rippled WebSocket URL), then:
+
+```typescript
+import { AgentClient } from "@sluzen/sdk";
+
+const client = new AgentClient({
+  baseUrl: "http://localhost:3000",
+  // walletSeed: "sEd7..." // optional if CLIENT_WALLET_SEED is set
+});
+
+const response = await client.request("/api/premium-data");
+console.log(response.status, response.data);
+```
+
+On a protected route, the client receives HTTP 402 + `PAYMENT-REQUIRED`, signs the XRPL payment, resends, and returns the upstream response plus any `PAYMENT-RESPONSE` hash.
+
+## License
+
+ISC

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import { type AgentClientOptions, type AgentResponse } from "./types.js";
+export declare class AgentClient {
+    private readonly baseUrl;
+    private readonly walletSeed;
+    private readonly fetchFn;
+    constructor(options: AgentClientOptions);
+    /**
+     * Negotiate a challenge only on unsigned 402 + PAYMENT-REQUIRED.
+     * A 402 without that header is a settlement/bind failure, not a new quote.
+     */
+    request(path: string, init?: RequestInit): Promise<AgentResponse>;
+    private signPayment;
+    private parseBody;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAC;AAMpB,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;gBAE3B,OAAO,EAAE,kBAAkB;IAUvC;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;YAyCzD,WAAW;YAsCX,SAAS;CAUxB"}

package/dist/client.js

@@ -0,0 +1,96 @@
+import { Client, Wallet } from "xrpl";
+import { decodeChallenge } from "./codec.js";
+import { CHALLENGE_NONCE_MEMO_TYPE, isXrpDropsCurrency, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, } from "./types.js";
+function utf8ToHex(value) {
+    return Buffer.from(value, "utf8").toString("hex").toUpperCase();
+}
+export class AgentClient {
+    baseUrl;
+    walletSeed;
+    fetchFn;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.walletSeed =
+            options.walletSeed ?? process.env.CLIENT_WALLET_SEED ?? "";
+        if (!this.walletSeed) {
+            throw new Error("CLIENT_WALLET_SEED environment variable is required");
+        }
+        this.fetchFn = options.fetchFn ?? fetch;
+    }
+    /**
+     * Negotiate a challenge only on unsigned 402 + PAYMENT-REQUIRED.
+     * A 402 without that header is a settlement/bind failure, not a new quote.
+     */
+    async request(path, init) {
+        const url = `${this.baseUrl}${path}`;
+        const initialResponse = await this.fetchFn(url, init);
+        if (initialResponse.status !== 402) {
+            const data = await this.parseBody(initialResponse);
+            return {
+                status: initialResponse.status,
+                data,
+                paymentResponse: initialResponse.headers.get(PAYMENT_RESPONSE_HEADER) ?? undefined,
+            };
+        }
+        const paymentRequired = initialResponse.headers.get(PAYMENT_REQUIRED_HEADER);
+        if (!paymentRequired) {
+            throw new Error("402 response missing PAYMENT-REQUIRED header");
+        }
+        const challenge = decodeChallenge(paymentRequired);
+        if (!challenge.nonce) {
+            throw new Error("402 challenge missing nonce");
+        }
+        const txBlob = await this.signPayment(challenge);
+        const headers = new Headers(init?.headers);
+        headers.set(PAYMENT_SIGNATURE_HEADER, txBlob);
+        const paidResponse = await this.fetchFn(url, { ...init, headers });
+        const data = await this.parseBody(paidResponse);
+        return {
+            status: paidResponse.status,
+            data,
+            paymentResponse: paidResponse.headers.get(PAYMENT_RESPONSE_HEADER) ?? undefined,
+        };
+    }
+    async signPayment(challenge) {
+        if (!isXrpDropsCurrency(challenge.currency)) {
+            throw new Error(`Issued currency ${challenge.currency} is not supported; Sluzen settles XRP drops only`);
+        }
+        const wallet = Wallet.fromSeed(this.walletSeed);
+        const node = process.env.XRPL_NODE;
+        if (!node) {
+            throw new Error("XRPL_NODE environment variable is required");
+        }
+        const client = new Client(node);
+        const payment = {
+            TransactionType: "Payment",
+            Account: wallet.address,
+            Destination: challenge.destination,
+            Amount: String(challenge.amount),
+            Memos: [
+                {
+                    Memo: {
+                        MemoType: utf8ToHex(CHALLENGE_NONCE_MEMO_TYPE),
+                        MemoData: utf8ToHex(challenge.nonce),
+                    },
+                },
+            ],
+        };
+        await client.connect();
+        try {
+            const prepared = await client.autofill(payment);
+            return wallet.sign(prepared).tx_blob;
+        }
+        finally {
+            await client.disconnect();
+        }
+    }
+    async parseBody(response) {
+        const contentType = response.headers.get("content-type") ?? "";
+        const text = await response.text();
+        if (contentType.includes("application/json") && text.length > 0) {
+            return JSON.parse(text);
+        }
+        return text;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/codec.d.ts

@@ -0,0 +1,4 @@
+import type { X402Challenge } from "./types.js";
+export declare function encodeChallenge(challenge: X402Challenge): string;
+export declare function decodeChallenge(encoded: string): X402Challenge;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,wBAAgB,eAAe,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAEhE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAI9D"}

package/dist/codec.js

@@ -0,0 +1,7 @@
+export function encodeChallenge(challenge) {
+    return Buffer.from(JSON.stringify(challenge)).toString("base64");
+}
+export function decodeChallenge(encoded) {
+    return JSON.parse(Buffer.from(encoded, "base64").toString("utf-8"));
+}
+//# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,eAAe,CAAC,SAAwB;IACtD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,IAAI,CAAC,KAAK,CACf,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAChC,CAAC;AACrB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./codec.js";
+export * from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./codec.js";
+export * from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/** Live product currency. Payment Amount is native XRPL drops (string). IOU/RLUSD is not implemented. */
+export declare const NATIVE_SETTLEMENT_CURRENCY: "XRP";
+export declare function isXrpDropsCurrency(currency: string): boolean;
+export interface X402Challenge {
+    network: string;
+    currency: string;
+    /** Integer XRP drops. Not USD microcents. */
+    amount: number;
+    destination: string;
+    expiration: number;
+    /** Server-issued challenge nonce; must appear in Payment Memos */
+    nonce: string;
+}
+export interface AgentResponse {
+    status: number;
+    data: unknown;
+    paymentResponse?: string;
+}
+export interface AgentClientOptions {
+    baseUrl: string;
+    walletSeed?: string;
+    fetchFn?: typeof fetch;
+}
+export declare const PAYMENT_REQUIRED_HEADER: "PAYMENT-REQUIRED";
+export declare const PAYMENT_SIGNATURE_HEADER: "PAYMENT-SIGNATURE";
+export declare const PAYMENT_RESPONSE_HEADER: "PAYMENT-RESPONSE";
+/** XRPL MemoType ASCII for challenge binding */
+export declare const CHALLENGE_NONCE_MEMO_TYPE: "pons/challenge-nonce";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,eAAO,MAAM,0BAA0B,EAAG,KAAc,CAAC;AAEzD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,eAAO,MAAM,uBAAuB,EAAG,kBAA2B,CAAC;AACnE,eAAO,MAAM,wBAAwB,EAAG,mBAA4B,CAAC;AACrE,eAAO,MAAM,uBAAuB,EAAG,kBAA2B,CAAC;AAEnE,gDAAgD;AAChD,eAAO,MAAM,yBAAyB,EAAG,sBAA+B,CAAC"}

package/dist/types.js

@@ -0,0 +1,11 @@
+/** Live product currency. Payment Amount is native XRPL drops (string). IOU/RLUSD is not implemented. */
+export const NATIVE_SETTLEMENT_CURRENCY = "XRP";
+export function isXrpDropsCurrency(currency) {
+    return currency.trim().toUpperCase() === NATIVE_SETTLEMENT_CURRENCY;
+}
+export const PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED";
+export const PAYMENT_SIGNATURE_HEADER = "PAYMENT-SIGNATURE";
+export const PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE";
+/** XRPL MemoType ASCII for challenge binding */
+export const CHALLENGE_NONCE_MEMO_TYPE = "pons/challenge-nonce";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAc,CAAC;AAEzD,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,0BAA0B,CAAC;AACtE,CAAC;AAyBD,MAAM,CAAC,MAAM,uBAAuB,GAAG,kBAA2B,CAAC;AACnE,MAAM,CAAC,MAAM,wBAAwB,GAAG,mBAA4B,CAAC;AACrE,MAAM,CAAC,MAAM,uBAAuB,GAAG,kBAA2B,CAAC;AAEnE,gDAAgD;AAChD,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAA+B,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sluzen/sdk",
+  "version": "1.0.0",
+  "description": "Sluzen x402 client — types, codec, and AgentClient for HTTP 402 payment flows on XRPL",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guidoalejo/pons-proxy-core.git",
+    "directory": "pons-sdk"
+  },
+  "homepage": "https://pons.network",
+  "keywords": [
+    "sluzen",
+    "x402",
+    "xrpl",
+    "pons",
+    "agentic-commerce",
+    "payment-required",
+    "http-402"
+  ],
+  "author": "Vectis",
+  "license": "ISC",
+  "dependencies": {
+    "xrpl": "^5.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}