@4mica/sdk 1.2.13 → 1.2.16

package/README.md

@@ -316,6 +316,13 @@ Notes:
 - `cancelWithdrawal(erc20Token?)`
 - `finalizeWithdrawal(erc20Token?)`
 
+ERC20 approval behavior:
+
+- `deposit(amount, erc20Token)` requires a prior `approveErc20(token, amount)` call.
+- `payTab(...)` auto-approves the Core4Mica contract when paying an ERC20 tab and the current
+  allowance is below the payment amount.
+- `approveErc20` returns `undefined` when the existing allowance is already sufficient.
+
 #### RecipientClient Methods
 
 - `createTab(userAddress, recipientAddress, erc20Token?, ttl?, guaranteeVersion?)`

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@4mica/sdk",
-    "version": "1.2.13",
+    "version": "1.2.15",
     "description": "TypeScript SDK for interacting with the 4Mica payment network",
     "license": "MIT",
     "repository": {
@@ -56,8 +56,12 @@
         "@quillai-network/wachai-validation-sdk": "^0.1.0",
         "viem": "^2.45.1"
     },
+    "optionalDependencies": {
+        "@coinbase/cdp-sdk": "^1.49.2"
+    },
     "devDependencies": {
-        "@4mica/x402": "^1.2.0",
+        "@4mica/x402": "^1.2.5",
+        "@coinbase/cdp-sdk": "^1.49.2",
         "@eslint/js": "^9.39.2",
         "@types/node": "^25.2.0",
         "@typescript-eslint/eslint-plugin": "^8.54.0",

package/dist/src/client/user.d.ts

@@ -1,4 +1,4 @@
-import { PaymentGuaranteeRequestClaims, PaymentGuaranteeRequestClaimsV2, PaymentSignature, SigningScheme, TabPaymentStatus, UserInfo } from '../models';
+import { PaymentGuaranteeRequestClaims, PaymentGuaranteeRequestClaimsV2, PaymentSignature, SigningScheme, TabInfo, TabPaymentStatus, UserInfo } from '../models';
 import type { TxReceiptWaitOptions } from '../contract';
 import type { Client } from './index';
 /** Payer-side operations: collateral management, payment signing, withdrawals. */
@@ -57,9 +57,23 @@ export declare class UserClient {
      */
     signPayment(claims: PaymentGuaranteeRequestClaims | PaymentGuaranteeRequestClaimsV2, scheme?: SigningScheme): Promise<PaymentSignature>;
     /**
-     * Pay a tab by transferring collateral to the recipient.
+     * List all tabs where the current signer is the payer.
      *
-     * Routes to `payTabErc20` when `erc20Token` is provided, otherwise `payTabEth`.
+     * @param settlementStatuses - Optional filter on settlement status (e.g. `['pending']`).
+     * @returns Array of tabs belonging to the current signer.
+     */
+    listTabs(settlementStatuses?: string[]): Promise<TabInfo[]>;
+    /**
+     * Pay a tab on-chain. Automatically resolves the recipient, asset, and amount
+     * from the tab and its latest guarantee.
+     *
+     * @param tabId - Tab identifier.
+     * @param waitOptions - Optional timeout/polling overrides.
+     * @throws if the tab is not found or has no guarantee.
+     */
+    payTab(tabId: number | bigint, waitOptions?: TxReceiptWaitOptions): Promise<unknown>;
+    /**
+     * Pay a tab on-chain with explicit parameters.
      *
      * @param tabId - Tab identifier.
      * @param reqId - Request ID from the latest guarantee (used for ETH payment memo).
@@ -68,7 +82,7 @@ export declare class UserClient {
      * @param erc20Token - ERC20 token address. Omit to pay in ETH.
      * @param waitOptions - Optional timeout/polling overrides.
      */
-    payTab(tabId: number | bigint, reqId: number | bigint, amount: number | bigint | string, recipientAddress: string, erc20Token?: string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
+    payTab(tabId: number | bigint, reqId: number | bigint, amount: number | bigint | string, recipientAddress: string, erc20Token?: string, waitOptions?: TxReceiptWaitOptions): Promise<unknown>;
     /**
      * Initiate a collateral withdrawal request. The withdrawal is subject to an
      * on-chain timelock before it can be finalised.

package/dist/src/client/user.js

@@ -79,18 +79,36 @@ class UserClient {
         return this.client.signer.signRequest(this.client.params, claims, scheme);
     }
     /**
-     * Pay a tab by transferring collateral to the recipient.
+     * List all tabs where the current signer is the payer.
      *
-     * Routes to `payTabErc20` when `erc20Token` is provided, otherwise `payTabEth`.
-     *
-     * @param tabId - Tab identifier.
-     * @param reqId - Request ID from the latest guarantee (used for ETH payment memo).
-     * @param amount - Amount to pay (in token base units / wei).
-     * @param recipientAddress - Address of the recipient.
-     * @param erc20Token - ERC20 token address. Omit to pay in ETH.
-     * @param waitOptions - Optional timeout/polling overrides.
+     * @param settlementStatuses - Optional filter on settlement status (e.g. `['pending']`).
+     * @returns Array of tabs belonging to the current signer.
      */
-    async payTab(tabId, reqId, amount, recipientAddress, erc20Token, waitOptions) {
+    async listTabs(settlementStatuses) {
+        const myAddress = (0, utils_1.normalizeAddress)(this.client.signer.signer.address);
+        const raw = await this.client.rpc.listUserTabs(myAddress, settlementStatuses);
+        return raw.map((t) => models_1.TabInfo.fromRpc(t));
+    }
+    async payTab(tabId, reqIdOrWaitOptions, amount, recipientAddress, erc20Token, waitOptions) {
+        // Simple overload: auto-resolve from tab + latest guarantee
+        if (reqIdOrWaitOptions === undefined ||
+            (typeof reqIdOrWaitOptions === 'object' &&
+                reqIdOrWaitOptions !== null &&
+                !('valueOf' in reqIdOrWaitOptions && typeof reqIdOrWaitOptions.valueOf() === 'bigint'))) {
+            const opts = reqIdOrWaitOptions;
+            const tab = await this.client.recipient.getTab(tabId);
+            if (!tab)
+                throw new Error(`Tab ${tabId} not found`);
+            const guarantee = await this.client.recipient.getLatestGuarantee(tabId);
+            if (!guarantee)
+                throw new Error(`Tab ${tabId} has no guarantee`);
+            const isEth = tab.assetAddress === '0x0000000000000000000000000000000000000000';
+            return isEth
+                ? this.client.gateway.payTabEth(tabId, guarantee.reqId, guarantee.amount, tab.recipientAddress, opts)
+                : this.client.gateway.payTabErc20(tabId, guarantee.amount, tab.assetAddress, tab.recipientAddress, opts);
+        }
+        // Explicit overload
+        const reqId = reqIdOrWaitOptions;
         if (erc20Token) {
             return this.client.gateway.payTabErc20(tabId, amount, erc20Token, recipientAddress, waitOptions);
         }

package/dist/src/contract.js

@@ -246,7 +246,11 @@ class ContractGateway {
     }
     async payTabErc20(tabId, amount, erc20Token, recipient, waitOptions) {
         const { gas, receipt } = this.splitWaitOptions(waitOptions);
-        const hash = await this.enqueueTx(() => this.contract.write.payTabInERC20Token([(0, utils_1.parseU256)(tabId), erc20Token, (0, utils_1.parseU256)(amount), recipient], {
+        const parsedAmount = (0, utils_1.parseU256)(amount);
+        // payTabInERC20Token uses safeTransferFrom, so the contract must be an
+        // approved spender. Auto-approve if the current allowance is insufficient.
+        await this.approveErc20(erc20Token, parsedAmount, waitOptions);
+        const hash = await this.enqueueTx(() => this.contract.write.payTabInERC20Token([(0, utils_1.parseU256)(tabId), erc20Token, parsedAmount, recipient], {
             gas: gas ?? DEFAULT_PAY_TAB_ERC20_GAS_LIMIT,
             ...this.defaultFeeParams(),
         }));

package/dist/src/index.d.ts

@@ -14,3 +14,4 @@ export * from './guarantee';
 export * from './bls';
 export * from './x402/index';
 export * from './client';
+export * from './wallet';

package/dist/src/index.js

@@ -30,3 +30,4 @@ __exportStar(require("./guarantee"), exports);
 __exportStar(require("./bls"), exports);
 __exportStar(require("./x402/index"), exports);
 __exportStar(require("./client"), exports);
+__exportStar(require("./wallet"), exports);

package/dist/src/rpc.d.ts

@@ -24,6 +24,7 @@ export declare class RpcProxy {
     listPendingRemunerations(recipientAddress: string): Promise<Record<string, unknown>[]>;
     getTab(tabId: number | bigint): Promise<Record<string, unknown> | null>;
     listRecipientTabs(recipientAddress: string, settlementStatuses?: string[]): Promise<Record<string, unknown>[]>;
+    listUserTabs(userAddress: string, settlementStatuses?: string[]): Promise<Record<string, unknown>[]>;
     getTabGuarantees(tabId: number | bigint): Promise<Record<string, unknown>[]>;
     getLatestGuarantee(tabId: number | bigint): Promise<Record<string, unknown> | null>;
     getGuarantee(tabId: number | bigint, reqId: number | bigint): Promise<Record<string, unknown> | null>;

package/dist/src/rpc.js

@@ -113,6 +113,14 @@ class RpcProxy {
         }
         return this.get(`/core/recipients/${recipientAddress}/tabs${query}`);
     }
+    async listUserTabs(userAddress, settlementStatuses) {
+        let query = '';
+        if (settlementStatuses?.length) {
+            query =
+                '?' + settlementStatuses.map((s) => `settlement_status=${encodeURIComponent(s)}`).join('&');
+        }
+        return this.get(`/core/users/${userAddress}/tabs${query}`);
+    }
     async getTabGuarantees(tabId) {
         return this.get(`/core/tabs/${serializeTabId(tabId)}/guarantees`);
     }

package/dist/src/wallet/cdp.d.ts

@@ -0,0 +1,13 @@
+import { type Account } from 'viem';
+export interface CdpAccountConfig {
+    /** CDP API key ID from the Coinbase Developer Platform dashboard. */
+    apiKeyId: string;
+    /** CDP API key secret from the Coinbase Developer Platform dashboard. */
+    apiKeySecret: string;
+    /** CDP wallet secret — required for account creation/signing operations. */
+    walletSecret: string;
+    /** Idempotency name — getOrCreateAccount always returns the same wallet for a given name. */
+    name: string;
+}
+/** Creates a viem Account backed by a Coinbase CDP MPC wallet (private key never leaves CDP). */
+export declare function createCdpAccount(config: CdpAccountConfig): Promise<Account>;

package/dist/src/wallet/cdp.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCdpAccount = createCdpAccount;
+const viem_1 = require("viem");
+const accounts_1 = require("viem/accounts");
+/** Creates a viem Account backed by a Coinbase CDP MPC wallet (private key never leaves CDP). */
+async function createCdpAccount(config) {
+    const { CdpClient } = await Promise.resolve().then(() => __importStar(require('@coinbase/cdp-sdk')));
+    const cdp = new CdpClient({
+        apiKeyId: config.apiKeyId,
+        apiKeySecret: config.apiKeySecret,
+        walletSecret: config.walletSecret,
+    });
+    const evmAccount = await cdp.evm.getOrCreateAccount({ name: config.name });
+    const address = evmAccount.address;
+    async function signMessage({ message }) {
+        if (typeof message === 'string') {
+            // CDP's signMessage applies the EIP-191 prefix internally.
+            const result = await cdp.evm.signMessage({ address, message });
+            return result.signature;
+        }
+        const hash = (0, viem_1.hashMessage)(message);
+        const result = await cdp.evm.signHash({ address, hash });
+        return result.signature;
+    }
+    async function signTypedData(parameters) {
+        // Always hash locally with viem (guaranteed correct EIP-712 encoding including
+        // non-standard types like uint64) and sign only the hash via CDP.
+        // CDP's native signTypedData can silently produce a wrong hash for custom types,
+        // which would pass without error but fail signature verification on the core side.
+        const hash = (0, viem_1.hashTypedData)(parameters);
+        const result = await cdp.evm.signHash({ address, hash });
+        return result.signature;
+    }
+    async function signTransaction(transaction, options) {
+        const serializer = options?.serializer ?? viem_1.serializeTransaction;
+        const hash = (0, viem_1.keccak256)(serializer(transaction));
+        const result = await cdp.evm.signHash({ address, hash });
+        const { r, s, yParity } = (0, viem_1.hexToSignature)(result.signature);
+        return serializer(transaction, { r, s, yParity });
+    }
+    // viem's signTypedData generic cannot be satisfied by a hand-rolled adapter without casting — same pattern as hdKeyToAccount.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (0, accounts_1.toAccount)({ address, signMessage, signTypedData, signTransaction });
+}

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

@@ -0,0 +1,2 @@
+export { createCdpAccount } from './cdp';
+export type { CdpAccountConfig } from './cdp';

package/dist/src/wallet/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCdpAccount = void 0;
+var cdp_1 = require("./cdp");
+Object.defineProperty(exports, "createCdpAccount", { enumerable: true, get: function () { return cdp_1.createCdpAccount; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4mica/sdk",
-  "version": "1.2.13",
+  "version": "1.2.16",
   "description": "TypeScript SDK for interacting with the 4Mica payment network",
   "license": "MIT",
   "repository": {
@@ -56,8 +56,12 @@
     "@quillai-network/wachai-validation-sdk": "^0.1.0",
     "viem": "^2.45.1"
   },
+  "optionalDependencies": {
+    "@coinbase/cdp-sdk": "^1.49.2"
+  },
   "devDependencies": {
-    "@4mica/x402": "^1.2.0",
+    "@4mica/x402": "^1.2.5",
+    "@coinbase/cdp-sdk": "^1.49.2",
     "@eslint/js": "^9.39.2",
     "@types/node": "^25.2.0",
     "@typescript-eslint/eslint-plugin": "^8.54.0",