@chipi-stack/backend 13.13.0 → 14.1.0

package/dist/index.mjs

@@ -1,8 +1,9 @@
-import { isValidApiKey, ChipiAuthError, STARKNET_NETWORKS, API_VERSIONING, validateErrorResponse, ChipiApiError, handleApiError, WALLET_RPC_ENDPOINTS, WALLET_CLASS_HASHES, API_ENDPOINTS, ChipiTransactionError, formatAmount, SKU_CONTRACTS, CARRIER_IDS, SERVICE_TYPES, ChipiSessionError, SESSION_ERRORS, SESSION_DEFAULTS, SESSION_ENTRYPOINTS } from '@chipi-stack/shared';
+import { isValidApiKey, ChipiAuthError, STARKNET_NETWORKS, API_VERSIONING, validateErrorResponse, ChipiApiError, handleApiError, WALLET_RPC_ENDPOINTS, WALLET_CLASS_HASHES, API_ENDPOINTS, ChipiTransactionError, getWalletTypeFromClassHash, formatAmount, SKU_CONTRACTS, CARRIER_IDS, SERVICE_TYPES, ChipiSessionError, SESSION_ERRORS, SESSION_DEFAULTS, SESSION_ENTRYPOINTS, CONTRACT_ADDRESSES, TOKEN_DECIMALS } from '@chipi-stack/shared';
 import CryptoES from 'crypto-es';
-import { RpcProvider, ec, hash, Account, num, CairoCustomEnum, CairoOption, CairoOptionVariant, CallData, cairo, typedData } from 'starknet';
-import { STARKNET_CONTRACTS } from '@chipi-stack/types';
+import { RpcProvider, ec, hash, Account, num, CairoCustomEnum, CairoOption, CairoOptionVariant, CallData, cairo, typedData, uint256 } from 'starknet';
+import { STARKNET_CONTRACTS, Chain } from '@chipi-stack/types';
 export { Chain, ChainToken } from '@chipi-stack/types';
+import { buildX402TypedData } from '@chipi-stack/core';
 
 // src/chipi-sdk.ts
 var ChipiClient = class {
@@ -14,7 +15,7 @@ var ChipiClient = class {
     this.customAlphaUrl = config.alphaUrl;
     this.baseUrl = this.getBaseUrl();
     this.nodeUrl = config.nodeUrl || STARKNET_NETWORKS.MAINNET;
-    this.sdkVersion = "11.21.0";
+    this.sdkVersion = "14.0.0";
   }
   /**
    * Get the API public key (for internal SDK use)
@@ -25,10 +26,10 @@ var ChipiClient = class {
   getBaseUrl() {
     const version = `v${API_VERSIONING.VERSION}`;
     if (this.customAlphaUrl) {
-      const cleanUrl = this.customAlphaUrl.replace(/\/v\d+$/, "").replace(/\/$/, "");
+      const cleanUrl = this.customAlphaUrl.replace(/\/v\d+\/?$/, "").replace(/\/$/, "");
       return `${cleanUrl}/${version}`;
     }
-    return `https://celebrated-vision-production-66a5.up.railway.app/${version}`;
+    return `https://api.chipipay.com/${version}`;
   }
   /**
    * Add API version query parameters to track the API version being used
@@ -95,7 +96,6 @@ var ChipiClient = class {
       });
       const data = await response.json();
       if (!response.ok) {
-        console.error("there was an error", data);
         const errorData = validateErrorResponse(data);
         throw new ChipiApiError(
           errorData.message,
@@ -189,16 +189,26 @@ var ChipiClient = class {
   }
 };
 var encryptPrivateKey = (privateKey, password) => {
+  if (!privateKey || !password) {
+    throw new Error("Private key and password are required");
+  }
   return CryptoES.AES.encrypt(privateKey, password).toString();
 };
 var decryptPrivateKey = (encryptedPrivateKey, password) => {
+  if (!encryptedPrivateKey || !password) {
+    throw new Error("Encrypted private key and password are required");
+  }
   try {
     const bytes = CryptoES.AES.decrypt(encryptedPrivateKey, password);
     const decrypted = bytes.toString(CryptoES.enc.Utf8);
-    if (!decrypted) throw new Error("Decryption failed");
+    if (!decrypted) {
+      throw new Error("Decryption resulted in empty string");
+    }
     return decrypted;
   } catch (error) {
-    console.error("Decryption failed:", error);
+    if (error instanceof Error) {
+      throw error;
+    }
     throw new Error(`Decryption failed: ${error}`);
   }
 };
@@ -227,6 +237,7 @@ var ChipiWallets = class {
         userId,
         walletType = "CHIPI",
         // Default to CHIPI wallet
+        classHash: customClassHash,
         usePasskey,
         chain
       } = params;
@@ -242,11 +253,8 @@ var ChipiWallets = class {
       const provider = new RpcProvider({ nodeUrl: rpcUrl });
       const privateKeyAX = this.getPrivateKeyAX();
       const starkKeyPubAX = ec.starkCurve.getStarkKey(privateKeyAX);
-      const accountClassHash = walletType === "READY" ? WALLET_CLASS_HASHES.READY : WALLET_CLASS_HASHES.CHIPI;
-      const constructorCallData = this.buildConstructorCallData(
-        walletType,
-        starkKeyPubAX
-      );
+      const constructorCallData = this.buildConstructorCallData(walletType, starkKeyPubAX);
+      const accountClassHash = customClassHash ?? (walletType === "READY" ? WALLET_CLASS_HASHES.READY : WALLET_CLASS_HASHES.CHIPI);
       const publicKey = hash.calculateContractAddressFromHash(
         starkKeyPubAX,
         accountClassHash,
@@ -261,8 +269,8 @@ var ChipiWallets = class {
           chain,
           publicKey,
           walletType,
-          starkKeyPubAX
-          // Needed for backend to build deployment data
+          starkKeyPubAX,
+          ...customClassHash && { classHash: customClassHash }
         }
       });
       const { typedData: typedData2, accountClassHash: accountClassHashResponse } = typedDataResponse;
@@ -358,7 +366,7 @@ var ChipiWallets = class {
       if (err instanceof ChipiApiError && err.status === 404) {
         return null;
       }
-      throw new Error(`getWallet error: ${String(err)}`);
+      throw err;
     }
   }
   async updateWalletEncryption(params, bearerToken) {
@@ -386,7 +394,121 @@ var ChipiWallets = class {
     });
     return getBalanceResponse;
   }
+  /**
+   * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
+   * Returns typed data that must be signed by the wallet owner.
+   */
+  async prepareWalletUpgrade(params, bearerToken) {
+    return this.client.post({
+      endpoint: `${API_ENDPOINTS.CHIPI_WALLETS}/prepare-upgrade`,
+      bearerToken,
+      body: params
+    });
+  }
+  /**
+   * Execute a wallet upgrade after the owner has signed the typed data.
+   */
+  async executeWalletUpgrade(params, bearerToken) {
+    return this.client.post({
+      endpoint: `${API_ENDPOINTS.CHIPI_WALLETS}/upgrade`,
+      bearerToken,
+      body: params
+    });
+  }
 };
+function unwrapPrepareResponse(response) {
+  if (!response || typeof response !== "object") {
+    throw new Error(
+      "Invalid response from /transactions/prepare-typed-data: response is not an object"
+    );
+  }
+  if ("typedData" in response) {
+    const resp = response;
+    if (!resp.typedData || typeof resp.typedData !== "object" || !("types" in resp.typedData) || !("message" in resp.typedData)) {
+      throw new Error(
+        "Invalid response from /transactions/prepare-typed-data: typedData structure is invalid"
+      );
+    }
+    return { typedData: resp.typedData, walletType: resp.walletType };
+  }
+  if ("types" in response && "message" in response) {
+    return { typedData: response };
+  }
+  const apiMessage = typeof response.message === "string" ? response.message : void 0;
+  throw new Error(
+    apiMessage ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing"
+  );
+}
+function normalizeSignature(signature) {
+  if (Array.isArray(signature)) {
+    if (signature.length < 2) {
+      throw new Error(`Array signature must have at least 2 elements, got ${signature.length}`);
+    }
+    const r = signature[0];
+    const s = signature[1];
+    if (r == null || s == null) {
+      throw new Error(`Signature elements must not be null/undefined. Got r=${r}, s=${s}`);
+    }
+    return { r: String(r), s: String(s) };
+  }
+  if (signature && typeof signature === "object" && "r" in signature && "s" in signature) {
+    const sig = signature;
+    if (sig.r == null || sig.s == null) {
+      throw new Error(`Object signature has null/undefined fields. Got r=${sig.r}, s=${sig.s}`);
+    }
+    return {
+      r: String(sig.r),
+      s: String(sig.s)
+    };
+  }
+  throw new Error("Unrecognized signature format from account.signMessage()");
+}
+var ChipiPaymasterAdapter = class {
+  constructor(client, bearerToken) {
+    this.client = client;
+    this.bearerToken = bearerToken;
+  }
+  async execute({ account, calls }) {
+    const classHash = await account.getClassHashAt(account.address);
+    const walletType = getWalletTypeFromClassHash(classHash);
+    const accountClassHash = walletType ? WALLET_CLASS_HASHES[walletType] : classHash;
+    const prepareResponse = await this.client.post({
+      endpoint: "/transactions/prepare-typed-data",
+      bearerToken: this.bearerToken,
+      body: {
+        publicKey: account.address,
+        calls,
+        accountClassHash
+      }
+    });
+    const { typedData: typedData2, walletType: resolvedWalletType } = unwrapPrepareResponse(prepareResponse);
+    const signature = await account.signMessage(typedData2);
+    const normalizedSig = normalizeSignature(signature);
+    const result = await this.client.post({
+      endpoint: "/transactions/execute-sponsored-transaction",
+      bearerToken: this.bearerToken,
+      body: {
+        publicKey: account.address,
+        typedData: typedData2,
+        userSignature: normalizedSig,
+        walletType: resolvedWalletType ?? walletType,
+        saveToDatabase: true
+      }
+    });
+    if (!result || typeof result !== "object") {
+      throw new Error(
+        "Invalid response from /transactions/execute-sponsored-transaction: response is not an object"
+      );
+    }
+    const apiMessage = typeof result.message === "string" ? result.message : void 0;
+    if (!result.transactionHash) {
+      throw new Error(apiMessage ?? "Response does not contain transaction hash");
+    }
+    return result.transactionHash;
+  }
+};
+
+// src/execute-paymaster-transaction.ts
 var executePaymasterTransaction = async ({
   params,
   bearerToken,
@@ -399,14 +521,15 @@ var executePaymasterTransaction = async ({
         usePasskey ? "encryptKey is required when using passkey. The passkey authentication should have provided the encryptKey." : "encryptKey is required for transaction execution"
       );
     }
-    const rpcUrl = WALLET_RPC_ENDPOINTS.READY;
-    const accountClassHash = WALLET_CLASS_HASHES.READY;
-    const privateKeyDecrypted = decryptPrivateKey(
-      wallet.encryptedPrivateKey,
-      encryptKey
-    );
-    if (!privateKeyDecrypted) {
-      throw new Error("Failed to decrypt private key");
+    const walletType = wallet.walletType ?? "READY";
+    const isKnownType = Object.prototype.hasOwnProperty.call(WALLET_RPC_ENDPOINTS, walletType) && Object.prototype.hasOwnProperty.call(WALLET_CLASS_HASHES, walletType);
+    const rpcUrl = isKnownType ? WALLET_RPC_ENDPOINTS[walletType] : WALLET_RPC_ENDPOINTS["CHIPI"];
+    const accountClassHash = isKnownType ? WALLET_CLASS_HASHES[walletType] : WALLET_CLASS_HASHES["CHIPI"];
+    let privateKeyDecrypted;
+    try {
+      privateKeyDecrypted = decryptPrivateKey(wallet.encryptedPrivateKey, encryptKey);
+    } catch {
+      throw new Error("Failed to decrypt private key. Verify the encryptKey is correct.");
     }
     const provider = new RpcProvider({ nodeUrl: rpcUrl });
     const account = new Account({
@@ -429,42 +552,47 @@ var executePaymasterTransaction = async ({
       );
     }
     let typedData2;
-    let walletType;
+    let resolvedWalletType;
     if ("typedData" in prepareResponse) {
       const resp = prepareResponse;
       typedData2 = resp.typedData;
-      walletType = resp.walletType;
+      if (resp.walletType && Object.prototype.hasOwnProperty.call(WALLET_CLASS_HASHES, resp.walletType)) {
+        resolvedWalletType = resp.walletType;
+      }
     } else if (prepareResponse && "types" in prepareResponse && "message" in prepareResponse) {
       typedData2 = prepareResponse;
     } else {
-      const apiMessage = prepareResponse && typeof prepareResponse.message === "string" ? prepareResponse.message : void 0;
+      const apiMessage2 = prepareResponse && typeof prepareResponse.message === "string" ? prepareResponse.message : void 0;
       throw new Error(
-        apiMessage ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing. This may occur for older STARKNET wallets that don't support paymaster transactions. Please ensure the wallet is a CHIPI wallet type."
+        apiMessage2 ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing. This may occur for older STARKNET wallets that don't support paymaster transactions. Please ensure the wallet is a CHIPI wallet type."
       );
     }
-    if (!typedData2 || typeof typedData2 !== "object" || !("message" in typedData2)) {
+    if (!typedData2 || typeof typedData2 !== "object" || !("types" in typedData2) || !("message" in typedData2)) {
       throw new Error(
-        "Invalid typedData received from backend: missing 'message' field. This may occur for older STARKNET wallets that don't support paymaster transactions."
+        "Invalid typedData received from backend: missing 'types' or 'message' field. This may occur for older STARKNET wallets that don't support paymaster transactions."
       );
     }
     const userSignature = await account.signMessage(typedData2);
+    const normalizedSig = normalizeSignature(userSignature);
     const result = await client.post({
       endpoint: "/transactions/execute-sponsored-transaction",
       bearerToken,
       body: {
         publicKey: wallet.publicKey,
         typedData: typedData2,
-        userSignature: {
-          r: userSignature.r.toString(),
-          s: userSignature.s.toString(),
-          recovery: userSignature.recovery
-        },
+        userSignature: normalizedSig,
         saveToDatabase,
-        walletType
+        walletType: resolvedWalletType ?? walletType
       }
     });
-    if (!result.transactionHash) {
-      throw new Error("The response does not contain the transaction hash");
+    if (!result || typeof result !== "object") {
+      throw new Error(
+        "Invalid response from /transactions/execute-sponsored-transaction: response is not an object"
+      );
+    }
+    const apiMessage = typeof result.message === "string" ? result.message : void 0;
+    if (typeof result.transactionHash !== "string" || result.transactionHash.trim().length === 0) {
+      throw new Error(apiMessage ?? "Response does not contain transaction hash");
     }
     return result.transactionHash;
   } catch (error) {
@@ -479,16 +607,13 @@ var executePaymasterTransactionWithSession = async ({
 }) => {
   const { encryptKey, wallet, session, calls, saveToDatabase } = params;
   if (wallet.walletType !== "CHIPI") {
-    console.error(
-      "[ChipiSDK:Session:Execute] Invalid wallet type for session execution",
-      {
-        provided: wallet.walletType,
-        required: "CHIPI",
-        expectedClassHash: WALLET_CLASS_HASHES.CHIPI,
-        walletAddress: wallet.publicKey?.slice(0, 15) + "...",
-        hint: "Session keys only work with CHIPI wallets (SNIP-9 compatible)"
-      }
-    );
+    console.error("[ChipiSDK:Session:Execute] Invalid wallet type for session execution", {
+      provided: wallet.walletType,
+      required: "CHIPI",
+      expectedClassHash: WALLET_CLASS_HASHES.CHIPI,
+      walletAddress: wallet.publicKey?.slice(0, 15) + "...",
+      hint: "Session keys only work with CHIPI wallets (SNIP-9 compatible)"
+    });
     throw new ChipiSessionError(
       `Session execution requires CHIPI wallet type. Got: "${wallet.walletType || "undefined"}"`,
       SESSION_ERRORS.INVALID_WALLET_TYPE_FOR_SESSION
@@ -507,18 +632,14 @@ var executePaymasterTransactionWithSession = async ({
     );
   }
   try {
-    const sessionPrivateKey = decryptPrivateKey(
-      session.encryptedPrivateKey,
-      encryptKey
-    );
-    if (!sessionPrivateKey) {
-      console.error(
-        "[ChipiSDK:Session:Execute] Failed to decrypt session private key",
-        {
-          sessionPubKey: session.publicKey?.slice(0, 15) + "...",
-          hint: "Ensure the encryptKey matches the one used when creating the session"
-        }
-      );
+    let sessionPrivateKey;
+    try {
+      sessionPrivateKey = decryptPrivateKey(session.encryptedPrivateKey, encryptKey);
+    } catch {
+      console.error("[ChipiSDK:Session:Execute] Failed to decrypt session private key", {
+        sessionPubKey: session.publicKey?.slice(0, 15) + "...",
+        hint: "Ensure the encryptKey matches the one used when creating the session"
+      });
       throw new ChipiSessionError(
         "Failed to decrypt session private key. Verify the encryptKey is correct.",
         SESSION_ERRORS.SESSION_DECRYPTION_FAILED
@@ -537,7 +658,7 @@ var executePaymasterTransactionWithSession = async ({
       );
     }
     const accountClassHash = WALLET_CLASS_HASHES.CHIPI;
-    const typeDataResult = await client.post({
+    const prepareResponse = await client.post({
       endpoint: "/transactions/prepare-typed-data",
       bearerToken,
       body: {
@@ -547,7 +668,31 @@ var executePaymasterTransactionWithSession = async ({
         walletType: "CHIPI"
       }
     });
-    const msgHash = typedData.getMessageHash(typeDataResult, wallet.publicKey);
+    if (!prepareResponse || typeof prepareResponse !== "object") {
+      throw new ChipiSessionError(
+        "Invalid response from /transactions/prepare-typed-data: response is not an object",
+        SESSION_ERRORS.SESSION_INVALID_RESPONSE
+      );
+    }
+    let sessionTypedData;
+    if ("typedData" in prepareResponse && prepareResponse.typedData) {
+      const candidate = prepareResponse.typedData;
+      if (!candidate || typeof candidate !== "object" || !("types" in candidate) || !("message" in candidate)) {
+        throw new ChipiSessionError(
+          "Invalid response from /transactions/prepare-typed-data: typedData structure is invalid",
+          SESSION_ERRORS.SESSION_INVALID_RESPONSE
+        );
+      }
+      sessionTypedData = candidate;
+    } else if ("types" in prepareResponse && "message" in prepareResponse) {
+      sessionTypedData = prepareResponse;
+    } else {
+      throw new ChipiSessionError(
+        "Invalid response from /transactions/prepare-typed-data: typedData is missing",
+        SESSION_ERRORS.SESSION_INVALID_RESPONSE
+      );
+    }
+    const msgHash = typedData.getMessageHash(sessionTypedData, wallet.publicKey);
     const { r, s } = ec.starkCurve.sign(msgHash, sessionPrivateKey);
     const sessionSignature = [
       session.publicKey,
@@ -560,7 +705,7 @@ var executePaymasterTransactionWithSession = async ({
       bearerToken,
       body: {
         publicKey: wallet.publicKey,
-        typeData: typeDataResult,
+        typedData: sessionTypedData,
         // Session signature format - array of 4 hex strings
         userSignature: sessionSignature,
         saveToDatabase,
@@ -569,14 +714,21 @@ var executePaymasterTransactionWithSession = async ({
         // Flag to indicate session signature format
       }
     });
-    if (!result.transactionHash) {
-      console.error(
-        "[ChipiSDK:Session:Execute] No transaction hash in response",
-        {
-          result
-        }
+    if (!result || typeof result !== "object") {
+      throw new ChipiSessionError(
+        "Invalid response from /transactions/execute-sponsored-transaction: response is not an object",
+        SESSION_ERRORS.SESSION_INVALID_RESPONSE
+      );
+    }
+    if (typeof result.transactionHash !== "string" || result.transactionHash.trim().length === 0) {
+      const apiMessage = typeof result.message === "string" ? result.message : void 0;
+      console.error("[ChipiSDK:Session:Execute] No transaction hash in response", {
+        result
+      });
+      throw new ChipiSessionError(
+        apiMessage ?? "Response does not contain transaction hash",
+        SESSION_ERRORS.SESSION_INVALID_RESPONSE
       );
-      throw new Error("Response does not contain transaction hash");
     }
     return result.transactionHash;
   } catch (error) {
@@ -714,6 +866,24 @@ var ChipiTransactions = class {
     });
     return response;
   }
+  /**
+   * Get a single transaction by hash or internal ID
+   */
+  async getTransaction(hashOrId, bearerToken) {
+    return this.client.get({
+      endpoint: `${API_ENDPOINTS.TRANSACTIONS}/${hashOrId}`,
+      bearerToken
+    });
+  }
+  /**
+   * Get on-chain transaction status
+   */
+  async getTransactionStatus(hash3, bearerToken) {
+    return this.client.get({
+      endpoint: `${API_ENDPOINTS.TRANSACTIONS}/${hash3}/status`,
+      bearerToken
+    });
+  }
 };
 var ChipiExchanges = class {
   constructor(client) {
@@ -742,32 +912,21 @@ var ChipiSkuPurchases = class {
    * @returns Promise<SkuPurchaseResponse> - The purchase response with transaction details
    */
   async purchaseSku(params, bearerToken) {
-    const {
-      skuId,
-      skuReference,
-      currencyAmount,
-      currency,
-      chain,
-      token,
-      encryptKey,
-      wallet
-    } = params;
-    const usdAmount = await this.exchanges.getUsdAmount(
-      currencyAmount,
-      currency,
-      bearerToken
-    );
-    const tokenAddress = STARKNET_CONTRACTS[token].contractAddress;
-    if (usdAmount <= 0) {
-      throw new Error(
-        `Invalid USD amount: ${usdAmount}. Amount must be positive.`
-      );
+    const { skuId, skuReference, currencyAmount, currency, chain, token, encryptKey, wallet } = params;
+    if (chain !== Chain.STARKNET) {
+      throw new Error(`Unsupported chain for SKU purchases: ${chain}`);
+    }
+    const tokenConfig = STARKNET_CONTRACTS[token];
+    if (!tokenConfig?.contractAddress) {
+      throw new Error(`Unsupported token for Starknet SKU purchases: ${token}`);
+    }
+    const usdAmount = await this.exchanges.getUsdAmount(currencyAmount, currency, bearerToken);
+    const tokenAddress = tokenConfig.contractAddress;
+    if (!Number.isFinite(usdAmount) || usdAmount <= 0) {
+      throw new Error(`Invalid USD amount: ${usdAmount}. Amount must be positive.`);
     }
     const minUsdAmount = Math.max(usdAmount, 1e-6);
-    const parsedAmount = formatAmount(
-      minUsdAmount.toString(),
-      STARKNET_CONTRACTS[token].decimals
-    );
+    const parsedAmount = formatAmount(minUsdAmount.toString(), tokenConfig.decimals);
     const calls = [
       {
         contractAddress: tokenAddress,
@@ -929,6 +1088,12 @@ var ChipiSessions = class {
    */
   createSessionKey(params) {
     const { encryptKey, durationSeconds = SESSION_DEFAULTS.DURATION_SECONDS } = params;
+    if (typeof durationSeconds !== "number" || !Number.isFinite(durationSeconds) || !Number.isInteger(durationSeconds) || durationSeconds <= 0) {
+      throw new ChipiSessionError(
+        `Invalid session duration: ${durationSeconds}. Must be a positive integer.`,
+        SESSION_ERRORS.SESSION_CREATION_FAILED
+      );
+    }
     try {
       const rawPrivateKey = ec.starkCurve.utils.randomPrivateKey();
       const privateKeyHex = this.toHex(rawPrivateKey);
@@ -942,13 +1107,10 @@ var ChipiSessions = class {
       };
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
-      console.error(
-        "[ChipiSDK:Session:Create] Failed to generate session key",
-        {
-          error: err.message,
-          durationRequested: durationSeconds
-        }
-      );
+      console.error("[ChipiSDK:Session:Create] Failed to generate session key", {
+        error: err.message,
+        durationRequested: durationSeconds
+      });
       throw new ChipiSessionError(
         `Failed to create session key: ${err.message}`,
         SESSION_ERRORS.SESSION_CREATION_FAILED
@@ -983,22 +1145,15 @@ var ChipiSessions = class {
    */
   async addSessionKeyToContract(params, bearerToken) {
     const { encryptKey, wallet, sessionConfig } = params;
-    this.validateChipiWallet(
-      wallet.walletType,
-      "AddToContract",
-      wallet.publicKey
-    );
+    this.validateChipiWallet(wallet.walletType, "AddToContract", wallet.publicKey);
     try {
-      console.log(
-        "[ChipiSDK:Session:AddToContract] Registering session on-chain",
-        {
-          walletAddress: wallet.publicKey.slice(0, 15) + "...",
-          sessionPubKey: sessionConfig.sessionPublicKey.slice(0, 15) + "...",
-          validUntil: new Date(sessionConfig.validUntil * 1e3).toISOString(),
-          maxCalls: sessionConfig.maxCalls,
-          allowedEntrypoints: sessionConfig.allowedEntrypoints.length
-        }
-      );
+      console.log("[ChipiSDK:Session:AddToContract] Registering session on-chain", {
+        walletAddress: wallet.publicKey.slice(0, 15) + "...",
+        sessionPubKey: sessionConfig.sessionPublicKey.slice(0, 15) + "...",
+        validUntil: new Date(sessionConfig.validUntil * 1e3).toISOString(),
+        maxCalls: sessionConfig.maxCalls,
+        allowedEntrypoints: sessionConfig.allowedEntrypoints.length
+      });
       const calldata = [
         sessionConfig.sessionPublicKey,
         num.toHex(sessionConfig.validUntil),
@@ -1024,13 +1179,10 @@ var ChipiSessions = class {
         bearerToken,
         client: this.client
       });
-      console.log(
-        "[ChipiSDK:Session:AddToContract] Session registered successfully",
-        {
-          txHash,
-          sessionPubKey: sessionConfig.sessionPublicKey.slice(0, 15) + "..."
-        }
-      );
+      console.log("[ChipiSDK:Session:AddToContract] Session registered successfully", {
+        txHash,
+        sessionPubKey: sessionConfig.sessionPublicKey.slice(0, 15) + "..."
+      });
       return txHash;
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
@@ -1178,17 +1330,33 @@ var ChipiSessions = class {
       return sessionData;
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
-      console.error("[ChipiSDK:Session:GetData] Query failed", {
+      const sessionNotFoundPatterns = [
+        /entry point.*not found/i,
+        /requested entrypoint was not found/i,
+        /invalid message selector/i,
+        /contract not found/i,
+        /is not deployed/i,
+        /revert.*get_session_data/i
+      ];
+      const isSessionNotFound = sessionNotFoundPatterns.some((p) => p.test(err.message));
+      if (isSessionNotFound) {
+        console.log("[ChipiSDK:Session:GetData] Session not found on contract", {
+          walletAddress: walletAddress?.slice(0, 15) + "...",
+          sessionPubKey: sessionPublicKey?.slice(0, 15) + "..."
+        });
+        return {
+          isActive: false,
+          validUntil: 0,
+          remainingCalls: 0,
+          allowedEntrypoints: []
+        };
+      }
+      console.error("[ChipiSDK:Session:GetData] RPC/network error", {
         error: err.message,
         walletAddress: walletAddress?.slice(0, 15) + "...",
         sessionPubKey: sessionPublicKey?.slice(0, 15) + "..."
       });
-      return {
-        isActive: false,
-        validUntil: 0,
-        remainingCalls: 0,
-        allowedEntrypoints: []
-      };
+      throw err;
     }
   }
   /**
@@ -1252,6 +1420,240 @@ var ChipiSessions = class {
     });
   }
 };
+var InMemoryNonceStore = class {
+  constructor() {
+    this.used = /* @__PURE__ */ new Set();
+  }
+  has(nonce) {
+    return this.used.has(nonce);
+  }
+  consume(nonce) {
+    if (this.used.has(nonce)) return false;
+    this.used.add(nonce);
+    return true;
+  }
+};
+var X402Facilitator = class _X402Facilitator {
+  constructor(client, bearerToken, config) {
+    this.client = client;
+    this.bearerToken = bearerToken;
+    this.nonceStore = config?.nonceStore ?? new InMemoryNonceStore();
+    this.provider = config?.provider;
+  }
+  /**
+   * Factory method for simpler instantiation.
+   *
+   * @example
+   * ```typescript
+   * const facilitator = X402Facilitator.create({
+   *   apiKey: process.env.CHIPI_API_KEY!,
+   *   bearerToken: process.env.CHIPI_BEARER_TOKEN!,
+   * });
+   * ```
+   */
+  static create(options) {
+    const client = new ChipiClient({ apiPublicKey: options.apiKey });
+    return new _X402Facilitator(client, options.bearerToken, {
+      nonceStore: options.nonceStore,
+      provider: options.provider
+    });
+  }
+  /**
+   * Verify a payment signature is valid (doesn't execute the transfer).
+   *
+   * Checks:
+   * 1. Nonce has not been used (replay protection)
+   * 2. Payment has not expired (validUntil > now)
+   * 3. Asset is USDC mainnet
+   * 4. Amount is positive
+   * 5. Addresses are non-empty
+   */
+  async verify(payment) {
+    const { payload } = payment;
+    if (payment.x402Version !== 1) {
+      return { isValid: false, invalidReason: `Unsupported x402 version: ${payment.x402Version}` };
+    }
+    if (payment.network !== "starknet-mainnet") {
+      return { isValid: false, invalidReason: `Unsupported network: ${payment.network}` };
+    }
+    if (await this.nonceStore.has(payload.nonce)) {
+      return { isValid: false, invalidReason: "Nonce already used (replay)" };
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (payload.validUntil <= now) {
+      return { isValid: false, invalidReason: "Payment has expired (validUntil in the past)" };
+    }
+    const normalizedAsset = payload.asset.toLowerCase().replace(/^0x0+/, "0x");
+    const normalizedUsdc = CONTRACT_ADDRESSES.USDC_MAINNET.toLowerCase().replace(/^0x0+/, "0x");
+    if (normalizedAsset !== normalizedUsdc) {
+      return {
+        isValid: false,
+        invalidReason: `Unsupported asset: ${payload.asset}. Only USDC is accepted.`
+      };
+    }
+    let amount;
+    try {
+      amount = BigInt(payload.amount);
+    } catch {
+      return { isValid: false, invalidReason: "Invalid payment amount format" };
+    }
+    if (amount <= 0n) {
+      return { isValid: false, invalidReason: "Payment amount must be positive" };
+    }
+    if (!payload.fromAddress || !payload.toAddress) {
+      return { isValid: false, invalidReason: "Missing fromAddress or toAddress" };
+    }
+    const sigResult = await this.verifySignature(payment);
+    if (!sigResult.valid) {
+      return { isValid: false, invalidReason: sigResult.reason };
+    }
+    return { isValid: true };
+  }
+  /**
+   * Verify the SNIP-12 signature on a payment payload.
+   *
+   * If an RPC provider is configured, reconstructs the typed data, computes the
+   * message hash, and calls `is_valid_signature()` on the sender's account contract.
+   * Otherwise falls back to a presence-only check (backwards compatible).
+   */
+  async verifySignature(payment) {
+    if (!this.provider) {
+      if (!payment.payload?.signature?.r || !payment.payload?.signature?.s) {
+        return { valid: false, reason: "Missing signature" };
+      }
+      return { valid: true };
+    }
+    const payload = payment.payload;
+    if (!payload?.signature?.r || !payload?.signature?.s) {
+      return { valid: false, reason: "Missing signature" };
+    }
+    const paymentTypedData = buildX402TypedData({
+      from_address: payload.fromAddress,
+      to_address: payload.toAddress,
+      amount: payload.amount,
+      asset: payload.asset,
+      valid_until: String(payload.validUntil),
+      nonce: payload.nonce
+    });
+    const msgHash = typedData.getMessageHash(paymentTypedData, payload.fromAddress);
+    try {
+      const result = await this.provider.callContract({
+        contractAddress: payload.fromAddress,
+        entrypoint: "is_valid_signature",
+        calldata: [msgHash, "2", payload.signature.r, payload.signature.s]
+      });
+      const VALID = "0x56414c4944";
+      if (result[0] === VALID || result[0] === BigInt(VALID).toString()) {
+        return { valid: true };
+      }
+      return { valid: false, reason: "Invalid SNIP-12 signature" };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { valid: false, reason: `Signature verification failed: ${message}` };
+    }
+  }
+  /**
+   * Settle a verified payment by executing the USDC transfer via paymaster.
+   *
+   * IMPORTANT: Mark nonce as consumed BEFORE executing to prevent concurrent replays.
+   * If the transfer fails after nonce consumption, the nonce is still burned
+   * (caller should implement idempotency at a higher level if needed).
+   */
+  async settle(payment) {
+    const { payload } = payment;
+    const verification = await this.verify(payment);
+    if (!verification.isValid) {
+      return { success: false, errorReason: verification.invalidReason };
+    }
+    const consumed = await this.nonceStore.consume(payload.nonce);
+    if (!consumed) {
+      return { success: false, errorReason: "Nonce already consumed (concurrent replay)" };
+    }
+    try {
+      const amountU256 = uint256.bnToUint256(BigInt(payload.amount));
+      const transferCall = {
+        contractAddress: payload.asset,
+        entrypoint: "transfer",
+        calldata: [payload.toAddress, amountU256.low.toString(), amountU256.high.toString()]
+      };
+      const prepareResponse = await this.client.post({
+        endpoint: "/transactions/prepare-typed-data",
+        bearerToken: this.bearerToken,
+        body: {
+          publicKey: payload.fromAddress,
+          calls: [transferCall]
+        }
+      });
+      const result = await this.client.post({
+        endpoint: "/transactions/execute-sponsored-transaction",
+        bearerToken: this.bearerToken,
+        body: {
+          publicKey: payload.fromAddress,
+          typedData: prepareResponse.typedData,
+          userSignature: payload.signature,
+          walletType: prepareResponse.walletType,
+          saveToDatabase: true
+        }
+      });
+      if (typeof result?.transactionHash !== "string" || !result.transactionHash.trim()) {
+        return {
+          success: false,
+          errorReason: result?.message ?? "No transaction hash returned from paymaster"
+        };
+      }
+      return {
+        success: true,
+        transactionHash: result.transactionHash,
+        networkId: "starknet-mainnet"
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        errorReason: `Settlement failed: ${message}`
+      };
+    }
+  }
+};
+var signTypedData = async ({
+  params
+}) => {
+  try {
+    const { encryptKey, wallet, typedData: typedData2 } = params;
+    if (!encryptKey) {
+      throw new Error("encryptKey is required for signing typed data");
+    }
+    if (!wallet || !wallet.encryptedPrivateKey || !wallet.publicKey) {
+      throw new Error("wallet with publicKey and encryptedPrivateKey is required");
+    }
+    if (!typedData2) {
+      throw new Error("typedData is required for signing");
+    }
+    const walletType = wallet.walletType ?? "READY";
+    if (!Object.prototype.hasOwnProperty.call(WALLET_RPC_ENDPOINTS, walletType) || !Object.prototype.hasOwnProperty.call(WALLET_CLASS_HASHES, walletType)) {
+      throw new Error(`Unsupported wallet type: "${String(walletType)}"`);
+    }
+    const rpcUrl = WALLET_RPC_ENDPOINTS[walletType];
+    let privateKeyDecrypted;
+    try {
+      privateKeyDecrypted = decryptPrivateKey(wallet.encryptedPrivateKey, encryptKey);
+    } catch {
+      throw new Error("Failed to decrypt private key. Verify the encryptKey is correct.");
+    }
+    const provider = new RpcProvider({ nodeUrl: rpcUrl });
+    const account = new Account({
+      provider,
+      address: wallet.publicKey,
+      signer: privateKeyDecrypted
+    });
+    const signature = await account.signMessage(typedData2);
+    const normalizedSig = normalizeSignature(signature);
+    return normalizedSig;
+  } catch (error) {
+    console.error("Error signing typed data", error);
+    throw error;
+  }
+};
 
 // src/chipi-sdk.ts
 var ChipiSDK = class {
@@ -1274,6 +1676,9 @@ var ChipiSDK = class {
     this.recordSendTransaction = this.recordSendTransaction.bind(this);
     this.purchaseSku = this.purchaseSku.bind(this);
     this.getUsdAmount = this.getUsdAmount.bind(this);
+    this.signTypedData = this.signTypedData.bind(this);
+    this.createPaymasterAdapter = this.createPaymasterAdapter.bind(this);
+    this.createX402Facilitator = this.createX402Facilitator.bind(this);
   }
   /**
    * Resolve bearer token - uses provided token or falls back to apiSecretKey
@@ -1287,6 +1692,43 @@ var ChipiSDK = class {
     }
     return token;
   }
+  /**
+   * Create a PaymasterAdapter for use with TxBuilder.sendSponsored().
+   *
+   * @example
+   * ```typescript
+   * const sdk = new ChipiServerSDK({ apiPublicKey: "pk_...", apiSecretKey: "sk_..." });
+   * const paymaster = sdk.createPaymasterAdapter();
+   *
+   * const txHash = await new TxBuilder(account, { paymaster })
+   *   .transfer(USDC, [{ to, amount }])
+   *   .sendSponsored(); // gasless!
+   * ```
+   */
+  createPaymasterAdapter(bearerToken) {
+    const token = this.resolveBearerToken(bearerToken);
+    return new ChipiPaymasterAdapter(this.client, token);
+  }
+  /**
+   * Create an X402Facilitator for verifying and settling x402 payments.
+   *
+   * @example
+   * ```typescript
+   * const facilitator = sdk.createX402Facilitator();
+   *
+   * // With custom nonce store (Redis)
+   * const facilitator = sdk.createX402Facilitator(bearerToken, {
+   *   nonceStore: {
+   *     has: async (nonce) => (await redis.sismember("x402:nonces", nonce)) === 1,
+   *     consume: async (nonce) => (await redis.sadd("x402:nonces", nonce)) === 1,
+   *   },
+   * });
+   * ```
+   */
+  createX402Facilitator(bearerToken, config) {
+    const token = this.resolveBearerToken(bearerToken);
+    return new X402Facilitator(this.client, token, config);
+  }
   /**
    * Execute a gasless transaction
    */
@@ -1342,6 +1784,29 @@ var ChipiSDK = class {
       this.resolveBearerToken(bearerToken)
     );
   }
+  /**
+   * Sign SNIP-12 typed data without executing a transaction.
+   *
+   * Purely local operation: decrypt private key → sign → return { r, s }.
+   * No API calls are made. Useful for x402 payment signatures and other
+   * off-chain signing flows.
+   *
+   * @example
+   * ```typescript
+   * const { r, s } = await sdk.signTypedData({
+   *   params: {
+   *     encryptKey: pin,
+   *     wallet,
+   *     typedData: snip12TypedData,
+   *   },
+   * });
+   * ```
+   */
+  async signTypedData({
+    params
+  }) {
+    return signTypedData({ params });
+  }
   /**
    * Transfer tokens
    */
@@ -1401,7 +1866,6 @@ var ChipiSDK = class {
     params,
     bearerToken
   }) {
-    console.log("createWallet params:", params);
     return this.wallets.createWallet({
       ...params,
       bearerToken: this.resolveBearerToken(bearerToken)
@@ -1417,10 +1881,7 @@ var ChipiSDK = class {
     });
   }
   async getTransactionList(query, bearerToken) {
-    return this.transactions.getTransactionList(
-      query,
-      this.resolveBearerToken(bearerToken)
-    );
+    return this.transactions.getTransactionList(query, this.resolveBearerToken(bearerToken));
   }
   async getWallet(params, bearerToken) {
     return this.wallets.getWallet(params, this.resolveBearerToken(bearerToken));
@@ -1438,19 +1899,13 @@ var ChipiSDK = class {
     params,
     bearerToken
   }) {
-    return this.skuPurchases.purchaseSku(
-      params,
-      this.resolveBearerToken(bearerToken)
-    );
+    return this.skuPurchases.purchaseSku(params, this.resolveBearerToken(bearerToken));
   }
   /**
    * Get a SKU purchase by id
    */
   async getSkuPurchase(id, bearerToken) {
-    return this.skuPurchases.getSkuPurchase(
-      id,
-      this.resolveBearerToken(bearerToken)
-    );
+    return this.skuPurchases.getSkuPurchase(id, this.resolveBearerToken(bearerToken));
   }
   /// SKUS
   async getSkuList(params, bearerToken) {
@@ -1459,6 +1914,33 @@ var ChipiSDK = class {
   async getSku(id, bearerToken) {
     return this.skus.getSku(id, this.resolveBearerToken(bearerToken));
   }
+  /**
+   * Get a single transaction by hash or internal ID
+   */
+  async getTransaction(hashOrId, bearerToken) {
+    return this.transactions.getTransaction(hashOrId, this.resolveBearerToken(bearerToken));
+  }
+  /**
+   * Get on-chain transaction status (supports polling for confirmation)
+   */
+  async getTransactionStatus(hash3, bearerToken) {
+    return this.transactions.getTransactionStatus(hash3, this.resolveBearerToken(bearerToken));
+  }
+  /**
+   * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
+   * Returns typed data that must be signed by the wallet owner.
+   * Server-only: requires API secret key.
+   */
+  async prepareWalletUpgrade(params, bearerToken) {
+    return this.wallets.prepareWalletUpgrade(params, this.resolveBearerToken(bearerToken));
+  }
+  /**
+   * Execute a wallet upgrade after signing.
+   * Server-only: requires API secret key.
+   */
+  async executeWalletUpgrade(params, bearerToken) {
+    return this.wallets.executeWalletUpgrade(params, this.resolveBearerToken(bearerToken));
+  }
   async getUsdAmount(currencyAmount, currency, bearerToken) {
     return this.exchanges.getUsdAmount(
       currencyAmount,
@@ -1490,7 +1972,130 @@ var ChipiBrowserSDK = class extends ChipiSDK {
   // All methods are inherited from ChipiSDK
   // bearerToken parameter is required for each authenticated request
 };
+function amountToBaseUnits(amount, decimals) {
+  const [whole, frac = ""] = amount.split(".");
+  const fracPadded = (frac + "0".repeat(decimals)).slice(0, decimals);
+  return String(BigInt(whole + fracPadded));
+}
+function buildPaymentRequirement(config, resource) {
+  const amountBaseUnits = amountToBaseUnits(config.amount, TOKEN_DECIMALS.USDC);
+  return {
+    scheme: "exact",
+    network: "starknet-mainnet",
+    maxAmountRequired: amountBaseUnits,
+    resource,
+    description: config.description,
+    payTo: config.payTo,
+    maxTimeoutSeconds: 300,
+    asset: CONTRACT_ADDRESSES.USDC_MAINNET
+  };
+}
+function isFlatConfig(config) {
+  return "amount" in config && "recipient" in config;
+}
+function resolveConfig(config) {
+  if (isFlatConfig(config)) {
+    return {
+      facilitator: config.facilitator,
+      paymentConfig: {
+        amount: config.amount,
+        payTo: config.recipient,
+        description: config.description
+      },
+      verifyOnly: config.verifyOnly
+    };
+  }
+  return config;
+}
+function x402Middleware(config) {
+  const resolved = resolveConfig(config);
+  return async (req, res, next) => {
+    if (req.method === "OPTIONS") {
+      return next();
+    }
+    const paymentHeader = req.headers?.["x-payment"] ?? req.headers?.["X-PAYMENT"];
+    if (!paymentHeader) {
+      const resource = req.protocol && req.get ? `${req.protocol}://${req.get("host")}${req.originalUrl}` : req.url ?? "";
+      const requirement2 = buildPaymentRequirement(resolved.paymentConfig, resource);
+      return res.status(402).set("Payment-Required", JSON.stringify(requirement2)).json({
+        error: "Payment Required",
+        paymentRequirement: requirement2
+      });
+    }
+    let payment;
+    try {
+      payment = typeof paymentHeader === "string" ? JSON.parse(paymentHeader) : paymentHeader;
+    } catch {
+      return res.status(400).json({ error: "Malformed X-PAYMENT header: invalid JSON" });
+    }
+    const payload = payment?.payload;
+    const toAddress = typeof payload?.toAddress === "string" ? payload.toAddress : null;
+    const amount = typeof payload?.amount === "string" ? payload.amount : null;
+    const asset = typeof payload?.asset === "string" ? payload.asset : null;
+    if (!toAddress || !amount || !asset) {
+      return res.status(400).json({ error: "Malformed X-PAYMENT payload: missing required fields" });
+    }
+    const requirement = buildPaymentRequirement(resolved.paymentConfig, "");
+    const normalizeAddr = (a) => a.toLowerCase().replace(/^0x0+/, "0x");
+    if (normalizeAddr(toAddress) !== normalizeAddr(resolved.paymentConfig.payTo)) {
+      return res.status(402).json({
+        error: "Payment recipient mismatch",
+        reason: `Expected ${resolved.paymentConfig.payTo}, got ${toAddress}`
+      });
+    }
+    let paidAmount;
+    try {
+      paidAmount = BigInt(amount);
+    } catch {
+      return res.status(400).json({ error: "Malformed X-PAYMENT payload", reason: "amount must be an integer string" });
+    }
+    if (paidAmount < BigInt(requirement.maxAmountRequired)) {
+      return res.status(402).json({
+        error: "Payment amount insufficient",
+        reason: `Required ${requirement.maxAmountRequired} base units, got ${amount}`
+      });
+    }
+    if (normalizeAddr(asset) !== normalizeAddr(requirement.asset)) {
+      return res.status(402).json({
+        error: "Payment asset mismatch",
+        reason: `Expected USDC, got ${asset}`
+      });
+    }
+    try {
+      const verified = await resolved.facilitator.verify(payment);
+      if (!verified.isValid) {
+        return res.status(402).json({
+          error: "Payment verification failed",
+          reason: verified.invalidReason
+        });
+      }
+      if (!resolved.verifyOnly) {
+        const settled = await resolved.facilitator.settle(payment);
+        if (!settled.success) {
+          return res.status(402).json({
+            error: "Payment settlement failed",
+            reason: settled.errorReason
+          });
+        }
+        req.x402 = {
+          txHash: settled.transactionHash,
+          payment,
+          networkId: settled.networkId
+        };
+      } else {
+        req.x402 = { payment };
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return res.status(500).json({
+        error: "Payment processing error",
+        reason: message
+      });
+    }
+    next();
+  };
+}
 
-export { ChipiBrowserSDK, ChipiClient, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, decryptPrivateKey, encryptPrivateKey };
+export { ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, X402Facilitator, decryptPrivateKey, encryptPrivateKey, signTypedData, x402Middleware };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map