@crossmint/wallets-sdk 1.0.0 → 1.0.2

package/README.md

@@ -1 +1,222 @@
 # @crossmint/wallets-sdk
+
+Typescript SDK for creating and managing [Crossmint Wallets](https://docs.crossmint.com) on EVM, Solana, and Stellar chains.
+
+## Prerequisites
+
+Get a Crossmint API key from the [developer console](https://docs.crossmint.com/introduction/platform/api-keys). Ensure your key has the **Wallet API** scopes enabled.
+
+- **Client-side** (browser): Use a client API key
+- **Server-side** (Node.js): Use a server API key
+
+## Installation
+
+```bash
+npm install @crossmint/wallets-sdk
+# or
+pnpm add @crossmint/wallets-sdk
+# or
+yarn add @crossmint/wallets-sdk
+```
+
+## Quick Start
+
+### Server-side (Node.js)
+
+```ts
+import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";
+
+const crossmint = createCrossmint({ apiKey: "<YOUR_SERVER_API_KEY>" });
+const wallets = CrossmintWallets.from(crossmint);
+
+// Create a wallet with a server signer
+const wallet = await wallets.createWallet({
+  chain: "base-sepolia",
+  recovery: { type: "server", secret: "<RECOVERY_SECRET>" },
+});
+
+console.log(wallet.address);
+
+// Send tokens
+const tx = await wallet.send("0xRecipientAddress", "usdc", "10");
+console.log(tx.explorerLink);
+```
+
+### Client-side (Headless)
+
+For client-side usage without React, you can use the SDK directly with JWT authentication:
+
+```ts
+import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";
+
+const crossmint = createCrossmint({ apiKey: "<YOUR_CLIENT_API_KEY>" });
+crossmint.setJwt("<USER_JWT>");
+
+const wallets = CrossmintWallets.from(crossmint);
+
+const wallet = await wallets.getWallet({ chain: "base-sepolia" });
+console.log(wallet.address);
+```
+
+> For React apps, use [`@crossmint/client-sdk-react-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-ui) which provides `CrossmintWalletProvider`, hooks, and built-in UI for OTP and passkey flows.
+
+## Core Concepts
+
+### Signers
+
+Wallets SDK uses a two-tier signer model:
+
+- **Recovery signer** — High-security, used for wallet recovery and adding new signers. Supports email OTP, phone OTP, external wallet, or server key.
+- **Operational signer** — Low-friction, used for day-to-day signing. The default is the **device signer**, which uses hardware-backed keys (no OTP needed). Also supports passkey, server key, and external wallet.
+
+When no operational signer is available, the recovery signer automatically serves as a fallback for signing.
+
+### Wallet Lifecycle
+
+```ts
+// Create a new wallet
+const wallet = await wallets.createWallet({
+  chain: "base-sepolia",
+  recovery: { type: "email", email: "user@example.com" },
+  signers: [{ type: "device" }], // optional — device is the default
+});
+
+// Retrieve an existing wallet (client-side)
+const wallet = await wallets.getWallet({ chain: "base-sepolia" });
+
+// Retrieve an existing wallet (server-side)
+const wallet = await wallets.getWallet("0xWalletAddress", {
+  chain: "base-sepolia",
+});
+```
+
+## Usage
+
+### Balances
+
+```ts
+const balances = await wallet.balances();
+
+console.log(balances.nativeToken.amount);
+console.log(balances.usdc.amount);
+```
+
+### Send Tokens
+
+```ts
+const tx = await wallet.send("0xRecipient", "usdc", "100");
+console.log(tx.explorerLink);
+```
+
+### Transfers
+
+```ts
+const transfers = await wallet.transfers({
+  tokens: "usdc",
+  status: "successful",
+});
+```
+
+### NFTs
+
+```ts
+const nfts = await wallet.nfts({ perPage: 10, page: 1 });
+```
+
+### Chain-Specific Transactions
+
+```ts
+import { EVMWallet, SolanaWallet, StellarWallet } from "@crossmint/wallets-sdk";
+
+// EVM — smart contract interaction
+const evmWallet = EVMWallet.from(wallet);
+const tx = await evmWallet.sendTransaction({
+  to: "0xContractAddress",
+  abi: contractAbi,
+  functionName: "mint",
+  args: [1],
+  value: 0n,
+});
+
+// EVM — sign a message
+const sig = await evmWallet.signMessage({ message: "Hello" });
+
+// EVM — viem public client
+const client = evmWallet.getViemClient();
+
+// Solana
+const solWallet = SolanaWallet.from(wallet);
+const solTx = await solWallet.sendTransaction({
+  serializedTransaction: "<base64-encoded-transaction>",
+});
+
+// Stellar
+const stellarWallet = StellarWallet.from(wallet);
+const stellarTx = await stellarWallet.sendTransaction({
+  contractId: "C...",
+  method: "transfer",
+  args: { to: "G...", amount: "1000000" },
+});
+```
+
+### Signer Management
+
+```ts
+// Add a new signer
+await wallet.addSigner({ type: "server", secret: "<SECRET>" });
+
+// List signers
+const signers = await wallet.signers();
+console.log(signers); // [{ type: "device", locator: "device:...", status: "success" }, ...]
+
+// Set the active signer
+await wallet.useSigner({ type: "server", secret: "<SECRET>" });
+
+// Recovery flow (new device)
+if (wallet.needsRecovery()) {
+  await wallet.recover(); // uses recovery signer to register a new device signer
+}
+```
+
+### Transaction Approval (Prepare-Only Mode)
+
+For flows that require multi-step approval:
+
+```ts
+// Create a transaction without auto-approving
+const pendingTx = await wallet.send("0xRecipient", "usdc", "10", {
+  prepareOnly: true,
+});
+console.log(pendingTx.transactionId);
+
+// Approve later
+const result = await wallet.approve({
+  transactionId: pendingTx.transactionId,
+});
+```
+
+## Signer Types
+
+| Type | Use Case | Platforms |
+|---|---|---|
+| `device` | Default day-to-day signer. Hardware-backed, no OTP. | Browser, React Native |
+| `server` | Server-side automated operations (AI agents, backends). | Node.js |
+| `email` | OTP-based recovery signer. | All |
+| `phone` | OTP-based recovery signer. | All |
+| `passkey` | WebAuthn/FIDO2 biometric signer. | Browser (EVM only) |
+| `external-wallet` | Bring-your-own key (MetaMask, KMS, etc). | All |
+
+## React / React Native
+
+For React applications, use [`@crossmint/client-sdk-react-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-ui) which provides wallet providers, hooks (`useWallet`, `useWalletOtpSigner`), and built-in UI for OTP and passkey flows.
+
+For React Native, see [`@crossmint/client-sdk-react-native-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-native-ui).
+
+## Documentation
+
+- [Crossmint Wallets Docs](https://docs.crossmint.com)
+- [SDK Reference](https://docs.crossmint.com/sdk-reference/wallets)
+
+## License
+
+Apache-2.0

package/dist/api/__tests__/constants.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkJ33QM2IDcjs = require('../../chunk-J33QM2ID.cjs');require('../../chunk-2GKPWQBQ.cjs');exports.DELAY_LONG = _chunkJ33QM2IDcjs.i; exports.DELAY_MEDIUM = _chunkJ33QM2IDcjs.h; exports.DELAY_RATE_LIMIT_WINDOW = _chunkJ33QM2IDcjs.j; exports.DELAY_SHORT = _chunkJ33QM2IDcjs.g; exports.HTTP_ERROR_STATUSES = _chunkJ33QM2IDcjs.a; exports.MOCK_API_KEY = _chunkJ33QM2IDcjs.m; exports.TEST_ADDRESSES = _chunkJ33QM2IDcjs.k; exports.TEST_VALUES = _chunkJ33QM2IDcjs.l; exports.TIMEOUT_LONG = _chunkJ33QM2IDcjs.f; exports.TIMEOUT_MEDIUM = _chunkJ33QM2IDcjs.e; exports.TIMEOUT_SHORT = _chunkJ33QM2IDcjs.d; exports.TOKEN_LOCATORS = _chunkJ33QM2IDcjs.c; exports.WALLET_LOCATORS = _chunkJ33QM2IDcjs.b;

package/dist/api/__tests__/constants.d.cts

@@ -0,0 +1,104 @@
+import { a3 as WalletLocator } from '../../types-DfT-EHk3.cjs';
+import 'viem';
+import '../gen/types.gen.cjs';
+import 'ox';
+import '@crossmint/client-sdk-window';
+import '@crossmint/client-signers';
+import '@crossmint/common-sdk-base';
+import '../../chains/chains.cjs';
+import '@solana/web3.js';
+import 'abitype';
+import '../../utils/device-signers/DeviceSignerKeyStorage.cjs';
+
+declare const HTTP_ERROR_STATUSES: readonly [{
+    readonly status: 400;
+    readonly message: "Bad Request";
+}, {
+    readonly status: 401;
+    readonly message: "Unauthorized";
+}, {
+    readonly status: 403;
+    readonly message: "Forbidden";
+}, {
+    readonly status: 404;
+    readonly message: "Not Found";
+}, {
+    readonly status: 429;
+    readonly message: "Rate limit exceeded";
+}, {
+    readonly status: 500;
+    readonly message: "Internal server error";
+}, {
+    readonly status: 502;
+    readonly message: "Bad Gateway";
+}, {
+    readonly status: 503;
+    readonly message: "Service Unavailable";
+}];
+/**
+ * General-purpose wallet locators for unit and integration tests.
+ * Includes both locator format strings (me:chain:type) and actual addresses.
+ * Used for testing wallet operations that accept WalletLocator type.
+ */
+declare const WALLET_LOCATORS: {
+    readonly evmSmart: WalletLocator;
+    readonly evmMpc: WalletLocator;
+    readonly solanaSmart: WalletLocator;
+    readonly solanaAddress: WalletLocator;
+    readonly evmAddress: WalletLocator;
+    readonly evmAddressWithSpecialChars: WalletLocator;
+};
+declare const TOKEN_LOCATORS: {
+    readonly eth: "base-sepolia:eth";
+    readonly usdc: "base-sepolia:usdc";
+    readonly sol: "solana:sol";
+    readonly customContract: "base-sepolia:0x1234567890123456789012345678901234567890";
+    readonly tokenWithSpecialChars: "base-sepolia:0xABCDEFabcdef0123456789ABCDEFabcdef012345";
+};
+declare const TIMEOUT_SHORT = 30000;
+declare const TIMEOUT_MEDIUM = 60000;
+declare const TIMEOUT_LONG = 120000;
+declare const DELAY_SHORT = 200;
+declare const DELAY_MEDIUM = 500;
+declare const DELAY_LONG = 1000;
+declare const DELAY_RATE_LIMIT_WINDOW = 2000;
+/**
+ * Real blockchain addresses for integration tests with specific purposes.
+ * These are actual addresses used in integration tests for:
+ * - Admin signers (external wallet addresses for wallet creation)
+ * - Recipients (addresses to send tokens to)
+ * - Error testing (non-existent addresses)
+ * - General test operations
+ * Note: These are actual addresses, not locator format strings.
+ */
+declare const TEST_ADDRESSES: {
+    readonly EVM_ADMIN_SIGNER: "0xe5E91D9b21C3563011cc332B050150fb9211bBEB";
+    readonly SOLANA_ADMIN_SIGNER: "CsHuaddA9J8j9vSTdL9wpvBsyjYe4F7iQQLuPg3EUqsU";
+    readonly EVM_RECIPIENT: "0xDF8b5F9c19E187f1Ea00730a1e46180152244315";
+    readonly EVM_NON_EXISTENT: "0x0000000000000000000000000000000000000000";
+    readonly EVM_TEST: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd";
+};
+declare const TEST_VALUES: {
+    readonly FUNDING_AMOUNT_SMALL: 1;
+    readonly FUNDING_AMOUNT_LARGE: 10;
+    readonly SEND_AMOUNT_SMALL: "0.0001";
+    readonly SEND_AMOUNT_VERY_SMALL: "0.000000000000000001";
+    readonly SEND_AMOUNT_ZERO: "0";
+    readonly SEND_AMOUNT_INVALID: "999999999999999999.0";
+    readonly SEND_AMOUNT_EXTREME: "999999999999999999999999999999.999999999999999999";
+    readonly LONG_STRING_LENGTH: 10000;
+    readonly CONCURRENT_REQUESTS: 3;
+    readonly RAPID_SEQUENTIAL_COUNT: 3;
+    readonly RATE_LIMIT_BATCH_SIZE: 5;
+    readonly RATE_LIMIT_BATCHES: 3;
+    readonly RATE_LIMIT_RAPID_COUNT: 20;
+    readonly RATE_LIMIT_STRESS_COUNT: 50;
+    readonly APPROVE_TRANSACTION_MAX_RETRIES: 10;
+};
+/**
+ * Mock API key for unit tests.
+ * This is a valid development API key format used for testing purposes only.
+ */
+declare const MOCK_API_KEY = "ck_development_A61UZQnvjSQcM5qVBaBactgqebxafWAVsNdD2xLkgBxoYuH5q2guM8r9DUmZQzE1WYyoByGVYpEG2o9gVSzAZFsrLbfKGERUJ6D5CW6S9AsJGAc3ctgrsD4n2ioekzGj7KPbLwT3SysDjMamYXLxEroUbQSdwf6aLF4zeEpECq2crkTUQeLFzxzmjWNxFDHFYefDrfrFPCURvBXJLf5pCxCQ";
+
+export { DELAY_LONG, DELAY_MEDIUM, DELAY_RATE_LIMIT_WINDOW, DELAY_SHORT, HTTP_ERROR_STATUSES, MOCK_API_KEY, TEST_ADDRESSES, TEST_VALUES, TIMEOUT_LONG, TIMEOUT_MEDIUM, TIMEOUT_SHORT, TOKEN_LOCATORS, WALLET_LOCATORS };

package/dist/api/__tests__/constants.d.ts

@@ -0,0 +1,104 @@
+import { a3 as WalletLocator } from '../../types-vcGYTcL0.js';
+import 'viem';
+import '../gen/types.gen.js';
+import 'ox';
+import '@crossmint/client-sdk-window';
+import '@crossmint/client-signers';
+import '@crossmint/common-sdk-base';
+import '../../chains/chains.js';
+import '@solana/web3.js';
+import 'abitype';
+import '../../utils/device-signers/DeviceSignerKeyStorage.js';
+
+declare const HTTP_ERROR_STATUSES: readonly [{
+    readonly status: 400;
+    readonly message: "Bad Request";
+}, {
+    readonly status: 401;
+    readonly message: "Unauthorized";
+}, {
+    readonly status: 403;
+    readonly message: "Forbidden";
+}, {
+    readonly status: 404;
+    readonly message: "Not Found";
+}, {
+    readonly status: 429;
+    readonly message: "Rate limit exceeded";
+}, {
+    readonly status: 500;
+    readonly message: "Internal server error";
+}, {
+    readonly status: 502;
+    readonly message: "Bad Gateway";
+}, {
+    readonly status: 503;
+    readonly message: "Service Unavailable";
+}];
+/**
+ * General-purpose wallet locators for unit and integration tests.
+ * Includes both locator format strings (me:chain:type) and actual addresses.
+ * Used for testing wallet operations that accept WalletLocator type.
+ */
+declare const WALLET_LOCATORS: {
+    readonly evmSmart: WalletLocator;
+    readonly evmMpc: WalletLocator;
+    readonly solanaSmart: WalletLocator;
+    readonly solanaAddress: WalletLocator;
+    readonly evmAddress: WalletLocator;
+    readonly evmAddressWithSpecialChars: WalletLocator;
+};
+declare const TOKEN_LOCATORS: {
+    readonly eth: "base-sepolia:eth";
+    readonly usdc: "base-sepolia:usdc";
+    readonly sol: "solana:sol";
+    readonly customContract: "base-sepolia:0x1234567890123456789012345678901234567890";
+    readonly tokenWithSpecialChars: "base-sepolia:0xABCDEFabcdef0123456789ABCDEFabcdef012345";
+};
+declare const TIMEOUT_SHORT = 30000;
+declare const TIMEOUT_MEDIUM = 60000;
+declare const TIMEOUT_LONG = 120000;
+declare const DELAY_SHORT = 200;
+declare const DELAY_MEDIUM = 500;
+declare const DELAY_LONG = 1000;
+declare const DELAY_RATE_LIMIT_WINDOW = 2000;
+/**
+ * Real blockchain addresses for integration tests with specific purposes.
+ * These are actual addresses used in integration tests for:
+ * - Admin signers (external wallet addresses for wallet creation)
+ * - Recipients (addresses to send tokens to)
+ * - Error testing (non-existent addresses)
+ * - General test operations
+ * Note: These are actual addresses, not locator format strings.
+ */
+declare const TEST_ADDRESSES: {
+    readonly EVM_ADMIN_SIGNER: "0xe5E91D9b21C3563011cc332B050150fb9211bBEB";
+    readonly SOLANA_ADMIN_SIGNER: "CsHuaddA9J8j9vSTdL9wpvBsyjYe4F7iQQLuPg3EUqsU";
+    readonly EVM_RECIPIENT: "0xDF8b5F9c19E187f1Ea00730a1e46180152244315";
+    readonly EVM_NON_EXISTENT: "0x0000000000000000000000000000000000000000";
+    readonly EVM_TEST: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd";
+};
+declare const TEST_VALUES: {
+    readonly FUNDING_AMOUNT_SMALL: 1;
+    readonly FUNDING_AMOUNT_LARGE: 10;
+    readonly SEND_AMOUNT_SMALL: "0.0001";
+    readonly SEND_AMOUNT_VERY_SMALL: "0.000000000000000001";
+    readonly SEND_AMOUNT_ZERO: "0";
+    readonly SEND_AMOUNT_INVALID: "999999999999999999.0";
+    readonly SEND_AMOUNT_EXTREME: "999999999999999999999999999999.999999999999999999";
+    readonly LONG_STRING_LENGTH: 10000;
+    readonly CONCURRENT_REQUESTS: 3;
+    readonly RAPID_SEQUENTIAL_COUNT: 3;
+    readonly RATE_LIMIT_BATCH_SIZE: 5;
+    readonly RATE_LIMIT_BATCHES: 3;
+    readonly RATE_LIMIT_RAPID_COUNT: 20;
+    readonly RATE_LIMIT_STRESS_COUNT: 50;
+    readonly APPROVE_TRANSACTION_MAX_RETRIES: 10;
+};
+/**
+ * Mock API key for unit tests.
+ * This is a valid development API key format used for testing purposes only.
+ */
+declare const MOCK_API_KEY = "ck_development_A61UZQnvjSQcM5qVBaBactgqebxafWAVsNdD2xLkgBxoYuH5q2guM8r9DUmZQzE1WYyoByGVYpEG2o9gVSzAZFsrLbfKGERUJ6D5CW6S9AsJGAc3ctgrsD4n2ioekzGj7KPbLwT3SysDjMamYXLxEroUbQSdwf6aLF4zeEpECq2crkTUQeLFzxzmjWNxFDHFYefDrfrFPCURvBXJLf5pCxCQ";
+
+export { DELAY_LONG, DELAY_MEDIUM, DELAY_RATE_LIMIT_WINDOW, DELAY_SHORT, HTTP_ERROR_STATUSES, MOCK_API_KEY, TEST_ADDRESSES, TEST_VALUES, TIMEOUT_LONG, TIMEOUT_MEDIUM, TIMEOUT_SHORT, TOKEN_LOCATORS, WALLET_LOCATORS };

package/dist/api/__tests__/constants.js

@@ -0,0 +1 @@
+import{a,b,c,d,e,f,g,h,i,j,k,l,m}from"../../chunk-DIGDDKSF.js";import"../../chunk-J3R36SGJ.js";export{i as DELAY_LONG,h as DELAY_MEDIUM,j as DELAY_RATE_LIMIT_WINDOW,g as DELAY_SHORT,a as HTTP_ERROR_STATUSES,m as MOCK_API_KEY,k as TEST_ADDRESSES,l as TEST_VALUES,f as TIMEOUT_LONG,e as TIMEOUT_MEDIUM,d as TIMEOUT_SHORT,c as TOKEN_LOCATORS,b as WALLET_LOCATORS};

package/dist/api/__tests__/test-utils.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkJ33QM2IDcjs = require('../../chunk-J33QM2ID.cjs');var _chunkIA6LDKX6cjs = require('../../chunk-IA6LDKX6.cjs');require('../../chunk-T3U46LK3.cjs');require('../../chunk-3TRQCN5N.cjs');require('../../chunk-LKQYA27B.cjs');var _chunk2GKPWQBQcjs = require('../../chunk-2GKPWQBQ.cjs');var _vitest = require('vitest');var b=({data:e,status:t=200,ok:n=!0,statusText:s="OK"})=>({json:_vitest.vi.fn().mockResolvedValue(e),ok:n,status:t,statusText:s}),j= exports.createMockSuccessResponse =e=>b({data:e}),P= exports.createMockErrorResponse =(e,t=400,n="Bad Request")=>b({data:e,status:t,ok:!1,statusText:n}),B= exports.createMockCrossmint =(e={})=>{let t=_chunk2GKPWQBQcjs.a.call(void 0, {apiKey:_chunkJ33QM2IDcjs.m},e);return _chunk2GKPWQBQcjs.b.call(void 0, _chunk2GKPWQBQcjs.a.call(void 0, {},t),{setJwt:_vitest.vi.fn().mockReturnThis()})},L= exports.createTestApiClient =e=>new (0, _chunkIA6LDKX6cjs.a)(e||B()),K= exports.createServerSideApiClient =()=>{let e=L();return Object.defineProperty(e,"isServerSide",{get:()=>!0,configurable:!0}),e},Y= exports.extractFetchCall =e=>{let t=e.mock.calls;if(t.length===0)return;let n=t[t.length-1];return{path:n[0],options:n[1]}},N= exports.expectRequestPath =(e,t)=>{_vitest.expect.call(void 0, e==null?void 0:e.path).toBe(t)},V= exports.expectCommonHeaders =e=>{_vitest.expect.call(void 0, e["Content-Type"]).toBe("application/json")},q= exports.expectRequestBody =(e,t)=>{_vitest.expect.call(void 0, e.body).toBe(JSON.stringify(t))},z= exports.validateRequest =(e,t,n)=>{_vitest.expect.call(void 0, e).toBeDefined(),e&&(N(e,t),e.options.headers&&V(e.options.headers),n!==void 0&&e.options&&q(e.options,n))},X= exports.testHttpErrorResponse =(e,t,n,s)=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){t.mockResolvedValue(P(n,s));let a=yield e();_vitest.expect.call(void 0, u(a)).toBe(!0),u(a)&&(_vitest.expect.call(void 0, a.error).toBe(!0),n.message&&_vitest.expect.call(void 0, a.message).toBe(n.message))}),Z= exports.testCommonHttpErrors =(s,a,...o)=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,[s,a,...o],function*(e,t,n=[]){for(let{status:c,message:g}of _chunkJ33QM2IDcjs.a){if(n.includes(c))continue;let l={error:!0,message:g};t.mockResolvedValueOnce(P(l,c));let m=yield e();_vitest.expect.call(void 0, u(m)).toBe(!0)}}),Q= exports.testNetworkError =(e,t)=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){t.mockRejectedValue(new Error("Network error")),yield _vitest.expect.call(void 0, e()).rejects.toThrow("Network error")}),ee= exports.testInvalidJsonResponse =(e,t)=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){let n={json:_vitest.vi.fn().mockRejectedValue(new Error("Invalid JSON")),ok:!0,status:200};t.mockResolvedValue(n),yield _vitest.expect.call(void 0, e()).rejects.toThrow()}),te= exports.testTimeoutError =(e,t)=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){t.mockImplementation(()=>new Promise((n,s)=>setTimeout(()=>s(new Error("Request timeout")),0))),yield _vitest.expect.call(void 0, e()).rejects.toThrow("Request timeout")}),ne= exports.testMalformedResponse =(e,t,n)=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){t.mockResolvedValue(j(n));let s=yield e();_vitest.expect.call(void 0, s).toEqual(n)}),se= exports.createMockWalletResponse =(e={})=>_chunk2GKPWQBQcjs.a.call(void 0, {address:_chunkJ33QM2IDcjs.b.evmAddress,chainType:"evm",type:"smart",config:{adminSigner:{type:"external-wallet",address:_chunkJ33QM2IDcjs.k.EVM_TEST}}},e),oe= exports.createMockSendResponse =(e={})=>_chunk2GKPWQBQcjs.a.call(void 0, {id:"txn-123",status:"pending",chainType:"evm",walletType:"evm-smart-wallet",params:{transaction:"0x1234567890abcdef",signer:"api-key:test"},onChain:{txId:"0xabcdef1234567890abcdef1234567890abcdef12",explorerLink:"https://explorer.example.com/tx/0xabcdef1234567890abcdef1234567890abcdef12"},createdAt:Date.now()},e);function u(e){return typeof e=="object"&&e!==null&&"error"in e&&e.error===!0}function h(e){return typeof e=="object"&&e!==null&&"address"in e&&"chainType"in e&&"type"in e}function $(e){return typeof e=="object"&&e!==null&&"id"in e&&"status"in e&&"chainType"in e}var x=e=>new Promise(t=>setTimeout(t,e)),re= exports.isValidEthereumAddress =e=>/^0x[a-fA-F0-9]{40}$/.test(e),ae= exports.isValidSolanaAddress =e=>/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(e),ie= exports.createIntegrationApiClient =(e,t,n={})=>{let s=_chunk2GKPWQBQcjs.a.call(void 0, _chunk2GKPWQBQcjs.a.call(void 0, {apiKey:e},t&&{overrideBaseUrl:t}),n),a=_chunk2GKPWQBQcjs.b.call(void 0, _chunk2GKPWQBQcjs.a.call(void 0, {},s),{setJwt:()=>a});return new (0, _chunkIA6LDKX6cjs.a)(a)},v= exports.TestDataFactory =class{constructor(){this.wallets=[];this.transactions=[]}addWallet(t){t&&!this.wallets.includes(t)&&this.wallets.push(t)}addTransaction(t){t&&!this.transactions.includes(t)&&this.transactions.push(t)}getWallet(t=0){return this.wallets[t]}getTransaction(t=0){return this.transactions[t]}hasWallets(){return this.wallets.length>0}clear(){this.wallets=[],this.transactions=[]}};function ce(s,a){return _chunk2GKPWQBQcjs.g.call(void 0, this,arguments,function*(e,t,n={}){if(t.hasWallets())return t.getWallet();let{chainType:o="evm",type:c="mpc",owner:g,testName:l="default"}=n,m=g||`userId:integration-${l}-${Date.now()}`,f=yield e.createWallet(_chunk2GKPWQBQcjs.a.call(void 0, {chainType:o,type:c},g&&{owner:m}));if(h(f))return t.addWallet(f.address),f.address})}function pe(e,t,n){return _chunk2GKPWQBQcjs.g.call(void 0, this,null,function*(){let s=yield e.createWallet(n);return h(s)&&t.addWallet(s.address),s})}function ue(e,t){_vitest.expect.call(void 0, u(e)).toBe(!0),t&&_vitest.expect.call(void 0, e.message).toBeDefined()}function le(e){_vitest.expect.call(void 0, h(e)).toBe(!0)}function de(e){_vitest.expect.call(void 0, $(e)).toBe(!0)}var I=(e,t,n,s="usdxm",a="base-sepolia")=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){let o={amount:n,token:s,chain:a},c=yield e.fundWallet(t,o);if(u(c))throw new Error(`Failed to fund wallet: ${c.message||"Unknown error"}`);return yield x(_chunkJ33QM2IDcjs.i),c}),U= exports.approveTransaction =(a,o,c,...g)=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,[a,o,c,...g],function*(e,t,n,s=_chunkJ33QM2IDcjs.l.APPROVE_TRANSACTION_MAX_RETRIES){var m;for(let f=0;f<s;f++){let d=yield e.getTransaction(t,n);if(u(d))throw new Error(`Transaction not found: ${d.message||"Unknown error"}`);if("status"in d&&(d.status==="success"||d.status==="failed"))return d;let T="approvals"in d?(m=d.approvals)==null?void 0:m.pending:void 0;if(T&&T.length>0){let O={approvals:T.map(_=>({signer:_.signer.locator,signature:""}))},C=yield e.approveTransaction(t,n,O);if(u(C))throw new Error(`Failed to approve transaction: ${C.message||"Unknown error"}`);yield x(_chunkJ33QM2IDcjs.j);continue}yield x(_chunkJ33QM2IDcjs.i)}let l=yield e.getTransaction(t,n);if(u(l))throw new Error(`Transaction not found after retries: ${l.message||"Unknown error"}`);if(!("status"in l))throw new Error("Transaction response missing status property");return l}),me= exports.fundWalletAndWait =(e,t,n=1,s="usdxm",a="base-sepolia")=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){return I(e,t,n,s,a)}),fe= exports.sendTokenAndApprove =(e,t,n,s,a)=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){let o=yield e.send(t,n,{recipient:s,amount:a});if(u(o))throw new Error(`Failed to send token: ${o.message||"Unknown error"}`);if(typeof o=="object"&&o!==null&&"id"in o&&typeof o.id=="string")return U(e,t,o.id);throw new Error("Transaction ID not found in send response")}),ge= exports.ensureWalletFunded =(e,t,n=1,s="usdxm",a="base-sepolia")=>_chunk2GKPWQBQcjs.g.call(void 0, void 0,null,function*(){try{yield I(e,t,n,s,a)}catch(o){let c=o instanceof Error?o.message:String(o);if(!c.includes("already funded")&&!c.includes("insufficient"))throw o}});exports.TestDataFactory = v; exports.approveTransaction = U; exports.createIntegrationApiClient = ie; exports.createMockCrossmint = B; exports.createMockErrorResponse = P; exports.createMockResponse = b; exports.createMockSendResponse = oe; exports.createMockSuccessResponse = j; exports.createMockWalletResponse = se; exports.createServerSideApiClient = K; exports.createTestApiClient = L; exports.createTestWallet = pe; exports.delay = x; exports.ensureWalletExists = ce; exports.ensureWalletFunded = ge; exports.expectCommonHeaders = V; exports.expectErrorResponse = ue; exports.expectRequestBody = q; exports.expectRequestPath = N; exports.expectSuccessTransactionResponse = de; exports.expectSuccessWalletResponse = le; exports.extractFetchCall = Y; exports.fundWallet = I; exports.fundWalletAndWait = me; exports.isErrorResponse = u; exports.isSuccessTransactionResponse = $; exports.isSuccessWalletResponse = h; exports.isValidEthereumAddress = re; exports.isValidSolanaAddress = ae; exports.sendTokenAndApprove = fe; exports.testCommonHttpErrors = Z; exports.testHttpErrorResponse = X; exports.testInvalidJsonResponse = ee; exports.testMalformedResponse = ne; exports.testNetworkError = Q; exports.testTimeoutError = te; exports.validateRequest = z;

package/dist/api/__tests__/test-utils.d.cts

@@ -0,0 +1,105 @@
+import { MockedFunction } from 'vitest';
+import { Crossmint } from '@crossmint/common-sdk-base';
+import { ApiClient } from '../client.cjs';
+import { a5 as CreateWalletResponse, a6 as SendResponse, a7 as CreateWalletParams, a3 as WalletLocator, Y as FundWalletResponse, a8 as GetTransactionResponse } from '../../types-DfT-EHk3.cjs';
+import '../../chains/chains.cjs';
+import 'viem';
+import '../gen/types.gen.cjs';
+import 'ox';
+import '@crossmint/client-sdk-window';
+import '@crossmint/client-signers';
+import '@solana/web3.js';
+import 'abitype';
+import '../../utils/device-signers/DeviceSignerKeyStorage.cjs';
+
+type MockResponseOptions<T> = {
+    data: T;
+    status?: number;
+    ok?: boolean;
+    statusText?: string;
+};
+type FetchCallInfo = {
+    path: string;
+    options: RequestInit;
+};
+declare const createMockResponse: <T>({ data, status, ok, statusText, }: MockResponseOptions<T>) => Response;
+declare const createMockSuccessResponse: <T>(data: T) => Response;
+declare const createMockErrorResponse: <T>(data: T, status?: number, statusText?: string) => Response;
+declare const createMockCrossmint: (overrides?: Partial<Crossmint>) => Crossmint;
+declare const createTestApiClient: (crossmint?: Crossmint) => ApiClient;
+declare const createServerSideApiClient: () => ApiClient;
+declare const extractFetchCall: (mockFn: MockedFunction<any> | MockedFunction<ApiClient["post"]> | MockedFunction<ApiClient["get"]>) => FetchCallInfo | undefined;
+declare const expectRequestPath: (call: FetchCallInfo | undefined, expectedPath: string) => void;
+declare const expectCommonHeaders: (headers: HeadersInit) => void;
+declare const expectRequestBody: (options: RequestInit, expectedBody: unknown) => void;
+declare const validateRequest: (call: FetchCallInfo | undefined, expectedPath: string, expectedBody?: unknown) => void;
+declare const testHttpErrorResponse: <T>(apiCall: () => Promise<T>, mockFn: MockedFunction<any> | MockedFunction<ApiClient["post"]> | MockedFunction<ApiClient["get"]>, errorData: {
+    error: boolean;
+    message?: string;
+}, statusCode: number) => Promise<void>;
+declare const testCommonHttpErrors: <T>(apiCall: () => Promise<T>, mockFn: MockedFunction<any> | MockedFunction<ApiClient["post"]> | MockedFunction<ApiClient["get"]>, skipStatuses?: number[]) => Promise<void>;
+declare const testNetworkError: <T>(apiCall: () => Promise<T>, mockFn: MockedFunction<any> | MockedFunction<ApiClient["post"]> | MockedFunction<ApiClient["get"]>) => Promise<void>;
+declare const testInvalidJsonResponse: <T>(apiCall: () => Promise<T>, mockFn: MockedFunction<any> | MockedFunction<ApiClient["post"]> | MockedFunction<ApiClient["get"]>) => Promise<void>;
+declare const testTimeoutError: <T>(apiCall: () => Promise<T>, mockFn: MockedFunction<any> | MockedFunction<ApiClient["post"]> | MockedFunction<ApiClient["get"]>) => Promise<void>;
+declare const testMalformedResponse: <T>(apiCall: () => Promise<T>, mockFn: MockedFunction<any> | MockedFunction<ApiClient["post"]> | MockedFunction<ApiClient["get"]>, malformedData: unknown) => Promise<void>;
+declare const createMockWalletResponse: (overrides?: Partial<CreateWalletResponse>) => CreateWalletResponse;
+declare const createMockSendResponse: (overrides?: Partial<SendResponse>) => SendResponse;
+interface ErrorResponse {
+    error: true;
+    message?: string;
+    details?: unknown;
+}
+interface SuccessWalletResponse {
+    address: string;
+    chainType: string;
+    type: string;
+    config?: {
+        adminSigner?: {
+            type: string;
+            address: string;
+        };
+    };
+}
+interface SuccessTransactionResponse {
+    id: string;
+    status: string;
+    chainType: string;
+}
+declare function isErrorResponse(response: unknown): response is ErrorResponse;
+declare function isSuccessWalletResponse(response: unknown): response is SuccessWalletResponse;
+declare function isSuccessTransactionResponse(response: unknown): response is SuccessTransactionResponse;
+declare const delay: (ms: number) => Promise<unknown>;
+declare const isValidEthereumAddress: (address: string) => boolean;
+declare const isValidSolanaAddress: (address: string) => boolean;
+/**
+ * Creates an API client for integration tests using environment variables.
+ * This is different from createTestApiClient which uses mocked data.
+ */
+declare const createIntegrationApiClient: (apiKey: string, baseUrl?: string, overrides?: Partial<Crossmint>) => ApiClient;
+declare class TestDataFactory {
+    private wallets;
+    private transactions;
+    addWallet(address: string): void;
+    addTransaction(id: string): void;
+    getWallet(index?: number): string | undefined;
+    getTransaction(index?: number): string | undefined;
+    hasWallets(): boolean;
+    clear(): void;
+}
+declare function ensureWalletExists(apiClient: ApiClient, testData: TestDataFactory, options?: {
+    chainType?: "evm" | "solana";
+    type?: "mpc" | "smart";
+    owner?: string;
+    testName?: string;
+}): Promise<string | undefined>;
+declare function createTestWallet(apiClient: ApiClient, testData: TestDataFactory, params: CreateWalletParams): Promise<CreateWalletResponse>;
+declare function expectErrorResponse(response: unknown, message?: string): asserts response is ErrorResponse;
+declare function expectSuccessWalletResponse(response: unknown): asserts response is SuccessWalletResponse;
+declare function expectSuccessTransactionResponse(response: unknown): asserts response is SuccessTransactionResponse;
+declare const fundWallet: (apiClient: ApiClient, walletLocator: WalletLocator, amount: number, token?: "usdxm", chain?: string) => Promise<FundWalletResponse>;
+declare const approveTransaction: (apiClient: ApiClient, walletLocator: WalletLocator, transactionId: string, maxRetries?: number) => Promise<GetTransactionResponse>;
+declare const fundWalletAndWait: (apiClient: ApiClient, walletLocator: WalletLocator, amount?: number, token?: "usdxm", chain?: string) => Promise<FundWalletResponse>;
+declare const sendTokenAndApprove: (apiClient: ApiClient, walletLocator: WalletLocator, tokenLocator: string, recipient: string, amount: string) => Promise<GetTransactionResponse>;
+declare const ensureWalletFunded: (apiClient: ApiClient, walletLocator: WalletLocator, amount?: number, token?: "usdxm", chain?: string) => Promise<void>;
+
+export { type ErrorResponse, type FetchCallInfo, type MockResponseOptions, type SuccessTransactionResponse, type SuccessWalletResponse, TestDataFactory, approveTransaction, createIntegrationApiClient, createMockCrossmint, createMockErrorResponse, createMockResponse, createMockSendResponse, createMockSuccessResponse, createMockWalletResponse, createServerSideApiClient, createTestApiClient, createTestWallet, delay, ensureWalletExists, ensureWalletFunded, expectCommonHeaders, expectErrorResponse, expectRequestBody, expectRequestPath, expectSuccessTransactionResponse, expectSuccessWalletResponse, extractFetchCall, fundWallet, fundWalletAndWait, isErrorResponse, isSuccessTransactionResponse, isSuccessWalletResponse, isValidEthereumAddress, isValidSolanaAddress, sendTokenAndApprove, testCommonHttpErrors, testHttpErrorResponse, testInvalidJsonResponse, testMalformedResponse, testNetworkError, testTimeoutError, validateRequest };