@faremeter/rides 0.16.0 → 0.17.1

package/dist/src/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * @title Rides Package
+ * @sidebarTitle Rides
+ * @description High-level payer interface for multi-chain x402 payments
+ * @packageDocumentation
+ */
 export { payer, createPayer } from "./internal.js";
+export type { WalletAdapter } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/src/index.js

@@ -1 +1,7 @@
+/**
+ * @title Rides Package
+ * @sidebarTitle Rides
+ * @description High-level payer interface for multi-chain x402 payments
+ * @packageDocumentation
+ */
 export { payer, createPayer } from "./internal.js";

package/dist/src/internal.d.ts

@@ -1,19 +1,46 @@
 import { type WrapOpts } from "@faremeter/fetch";
-import { type KnownNetwork, type KnownAsset } from "./types.js";
+import { type KnownNetwork, type KnownAsset, type WalletAdapter } from "./types.js";
+/**
+ * Configuration options for creating a payer instance.
+ */
 export interface CreatePayerArgs {
+    /** Networks to enable for payments. Defaults to all known networks. */
     networks?: KnownNetwork[];
+    /** Assets to enable for payments. Defaults to all known assets. */
     assets?: KnownAsset[];
+    /** Custom fetch function to wrap. Defaults to globalThis.fetch. */
     fetch?: typeof globalThis.fetch;
+    /** Additional options for fetch wrapping and balance checks. */
     options?: {
+        /** Options passed to the fetch wrapper. */
         fetch?: WrapOpts;
+        /** If true, skips balance validation before payment attempts. */
         disableBalanceChecks?: boolean;
     };
 }
+/**
+ * Creates a payer instance that manages wallets and payment-enabled fetch.
+ *
+ * The payer automatically handles x402 payment flows by wrapping fetch with
+ * payment capabilities. Wallets must be added via addLocalWallet before
+ * making paid requests.
+ *
+ * @param args - Optional configuration for networks, assets, and fetch behavior
+ * @returns A payer object with addLocalWallet and fetch methods
+ */
 export declare function createPayer(args?: CreatePayerArgs): {
+    addWalletAdapter: (adapter: WalletAdapter) => void;
     addLocalWallet: (input: unknown) => Promise<void>;
     fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 };
+/**
+ * Default payer instance with all networks and assets enabled.
+ *
+ * Use addLocalWallet to attach wallet credentials before making requests
+ * with the fetch method.
+ */
 export declare const payer: {
+    addWalletAdapter: (adapter: WalletAdapter) => void;
     addLocalWallet: (input: unknown) => Promise<void>;
     fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 };

package/dist/src/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/internal.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,QAAQ,EAEd,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,UAAU,EAGhB,MAAM,SAAS,CAAC;AAKjB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,QAAQ,CAAC;QACjB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAMD,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,eAAe;4BAuEhB,OAAO;mBAiC5B,WAAW,GAAG,GAAG,SACjB,WAAW,KACjB,OAAO,CAAC,QAAQ,CAAC;EAKvB;AAED,eAAO,MAAM,KAAK;4BA1CgB,OAAO;mBAiC5B,WAAW,GAAG,GAAG,SACjB,WAAW,KACjB,OAAO,CAAC,QAAQ,CAAC;CAOU,CAAC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/internal.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,QAAQ,EAEd,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,UAAU,EAGf,KAAK,aAAa,EACnB,MAAM,SAAS,CAAC;AAMjB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,mEAAmE;IACnE,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,gEAAgE;IAChE,OAAO,CAAC,EAAE;QACR,2CAA2C;QAC3C,KAAK,CAAC,EAAE,QAAQ,CAAC;QACjB,iEAAiE;QACjE,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAQD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,eAAe;gCAoFb,aAAa;4BAUhB,OAAO;mBA2B5B,WAAW,GAAG,GAAG,SACjB,WAAW,KACjB,OAAO,CAAC,QAAQ,CAAC;EAKvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK;gCApDmB,aAAa;4BAUhB,OAAO;mBA2B5B,WAAW,GAAG,GAAG,SACjB,WAAW,KACjB,OAAO,CAAC,QAAQ,CAAC;CAaU,CAAC"}

package/dist/src/internal.js

@@ -1,13 +1,22 @@
-import { x402PaymentId } from "@faremeter/types/x402";
 import {} from "@faremeter/types/client";
 import { wrap as wrapFetch, chooseFirstAvailable, } from "@faremeter/fetch";
-import {} from "@faremeter/types/client";
 import { KnownNetworks, KnownAssets, } from "./types.js";
+import { logger } from "./logger.js";
 import * as solana from "./solana.js";
 import * as evm from "./evm.js";
 function idKey({ network, scheme, asset }) {
     return `${network}\0${scheme}\0${asset}`;
 }
+/**
+ * Creates a payer instance that manages wallets and payment-enabled fetch.
+ *
+ * The payer automatically handles x402 payment flows by wrapping fetch with
+ * payment capabilities. Wallets must be added via addLocalWallet before
+ * making paid requests.
+ *
+ * @param args - Optional configuration for networks, assets, and fetch behavior
+ * @returns A payer object with addLocalWallet and fetch methods
+ */
 export function createPayer(args) {
     const { networks = KnownNetworks, assets = KnownAssets, fetch = globalThis.fetch, } = args ?? {};
     const paymentHandlers = [];
@@ -32,11 +41,17 @@ export function createPayer(args) {
                 if (getBalance === undefined) {
                     continue;
                 }
-                const balance = await getBalance();
+                let balance;
+                try {
+                    balance = await getBalance();
+                }
+                catch (cause) {
+                    logger.warning(`failed to check balance on ${req.network} for ${req.scheme}, skipping`, { cause });
+                    continue;
+                }
                 // XXX - We need to do a better job of understanding decimals here.
-                if (balance.amount < BigInt(req.maxAmountRequired)) {
-                    // eslint-disable-next-line no-console
-                    console.log(`Not paying with ${balance.name} on ${req.network} using the ${req.scheme} scheme: balance is ${balance.amount} which is less than ${req.maxAmountRequired}`);
+                if (balance.amount < BigInt(req.amount)) {
+                    logger.info(`Not paying with ${balance.name} on ${req.network} using the ${req.scheme} scheme: balance is ${balance.amount} which is less than ${req.amount}`);
                     continue;
                 }
                 viableOptions.push(e);
@@ -54,12 +69,24 @@ export function createPayer(args) {
         });
     };
     let _fetch;
+    /**
+     * Registers a wallet adapter directly, bypassing the plugin system.
+     *
+     * @param adapter - The wallet adapter to register
+     */
+    const addWalletAdapter = (adapter) => {
+        _fetch = undefined;
+        paymentHandlers.push(adapter.paymentHandler);
+        for (const id of adapter.x402Id) {
+            balanceLookup.set(idKey(id), adapter.getBalance);
+        }
+    };
     return {
+        addWalletAdapter,
         addLocalWallet: async (input) => {
             if (input === undefined) {
                 throw new Error("undefined is not a valid local wallet");
             }
-            _fetch = undefined;
             const newWallets = [];
             for (const adapter of adapters) {
                 const res = await adapter.addLocalWallet(input);
@@ -71,11 +98,8 @@ export function createPayer(args) {
             if (newWallets.length === 0) {
                 throw new Error("couldn't find any way to use provided local wallet information");
             }
-            paymentHandlers.push(...newWallets.map((x) => x.paymentHandler));
             for (const wallet of newWallets) {
-                for (const id of wallet.x402Id) {
-                    balanceLookup.set(idKey(id), wallet.getBalance);
-                }
+                addWalletAdapter(wallet);
             }
         },
         fetch: async (input, init) => {
@@ -84,4 +108,10 @@ export function createPayer(args) {
         },
     };
 }
+/**
+ * Default payer instance with all networks and assets enabled.
+ *
+ * Use addLocalWallet to attach wallet credentials before making requests
+ * with the fetch method.
+ */
 export const payer = createPayer();

package/dist/src/logger.d.ts

@@ -0,0 +1,2 @@
+export declare const logger: import("@faremeter/logs").Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/src/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM,kCAA0C,CAAC"}

package/dist/src/logger.js

@@ -0,0 +1,2 @@
+import { getLogger } from "@faremeter/logs";
+export const logger = await getLogger(["faremeter", "rides"]);

package/dist/src/solana.d.ts

@@ -1,7 +1,7 @@
 import { type WalletAdapter } from "./types.js";
 import { Keypair } from "@solana/web3.js";
 export declare function findNetworkMintCombinations(networks: readonly string[], assets: readonly string[]): {
-    cluster: "testnet" | "devnet" | "mainnet-beta";
+    cluster: "testnet" | "mainnet-beta" | "devnet";
     mints: {
         address: string;
         name: "USDC";

package/dist/src/solana.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solana.d.ts","sourceRoot":"","sources":["../../src/solana.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,EAAa,OAAO,EAA6B,MAAM,iBAAiB,CAAC;AAWhF,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,MAAM,EAAE,SAAS,MAAM,EAAE;;;;;;IA2B1B;AAED,eAAO,MAAM,YAAY,8IAKvB,CAAC;AAEH,wBAAsB,SAAS,CAAC,KAAK,EAAE,OAAO,gCAe7C;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB;4BAQtB,OAAO;cAwDxC"}
+{"version":3,"file":"solana.d.ts","sourceRoot":"","sources":["../../src/solana.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,EAAa,OAAO,EAA6B,MAAM,iBAAiB,CAAC;AAWhF,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,MAAM,EAAE,SAAS,MAAM,EAAE;;;;;;IA2B1B;AAED,eAAO,MAAM,YAAY,8IAKvB,CAAC;AAEH,wBAAsB,SAAS,CAAC,KAAK,EAAE,OAAO,gCAe7C;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB;4BAQtB,OAAO;cA0DxC"}

package/dist/src/solana.js

@@ -1,5 +1,5 @@
 import { match } from "arktype";
-import { lookupX402Network, lookupKnownSPLToken, } from "@faremeter/info/solana";
+import { clusterToCAIP2, lookupKnownSPLToken, } from "@faremeter/info/solana";
 import { createLocalWallet } from "@faremeter/wallet-solana";
 import { exact } from "@faremeter/payment-solana";
 import {} from "./types.js";
@@ -73,11 +73,13 @@ export function createAdapter(opts) {
                     const connection = new Connection(clusterApiUrl(cluster), "confirmed");
                     const wallet = await createLocalWallet(cluster, privateKey);
                     res.push({
-                        x402Id: lookupX402Network(cluster).map((network) => ({
-                            scheme: "exact",
-                            asset: mint.address,
-                            network,
-                        })),
+                        x402Id: [
+                            {
+                                scheme: "exact",
+                                asset: mint.address,
+                                network: clusterToCAIP2(cluster).caip2,
+                            },
+                        ],
                         paymentHandler: exact.createPaymentHandler(wallet, new PublicKey(mint.address), connection),
                         getBalance: async () => {
                             let balance = await getTokenBalance({

package/dist/src/types.d.ts

@@ -1,4 +1,3 @@
-import { x402PaymentId } from "@faremeter/types/x402";
 import { type PaymentHandler } from "@faremeter/types/client";
 export declare const KnownNetworks: readonly ["base", "base-sepolia", "monad", "monad-testnet", "polygon", "polygon-amoy", "solana", "solana-devnet"];
 export type KnownNetwork = (typeof KnownNetworks)[number];
@@ -10,8 +9,13 @@ export type Balance = {
     decimals: number;
 };
 export type GetBalance = () => Promise<Balance>;
+export type PaymentIdV2 = {
+    scheme: string;
+    network: string;
+    asset: string;
+};
 export interface WalletAdapter {
-    x402Id: x402PaymentId[];
+    x402Id: PaymentIdV2[];
     paymentHandler: PaymentHandler;
     getBalance: GetBalance;
 }

package/dist/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,eAAO,MAAM,aAAa,mHAShB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,WAAW,mBAAoB,CAAC;AAC7C,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC;CACrE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,eAAO,MAAM,aAAa,mHAShB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,WAAW,mBAAoB,CAAC;AAE7C,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC;CACrE"}

package/dist/src/types.js

@@ -1,4 +1,3 @@
-import { x402PaymentId } from "@faremeter/types/x402";
 import {} from "@faremeter/types/client";
 export const KnownNetworks = [
     "base",