@chipi-stack/backend 13.12.0 → 14.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Chipi Pay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
 # @chipi-stack/backend
 
-Utilities for Chipi SDKs
+Server-side SDK for Chipi Pay. Handles wallet creation, transactions, SKU purchases, and exchanges.
+
+## Install
+
+```bash
+npm install @chipi-stack/backend
+```
+
+## Quick Start
+
+```typescript
+import { ChipiSDK } from "@chipi-stack/backend";
+
+const sdk = new ChipiSDK({
+  apiPublicKey: process.env.CHIPI_API_PUBLIC_KEY!,
+  apiSecretKey: process.env.CHIPI_API_SECRET_KEY!,
+});
+
+const bearerToken = "your-bearer-token"; // From your auth provider (e.g., Clerk)
+
+// Create a wallet
+const wallet = await sdk.createWallet({
+  params: {
+    externalUserId: "user-123",
+    chain: "STARKNET",
+    encryptKey: "user-pin-or-passkey",
+  },
+  bearerToken,
+});
+
+// Transfer USDC
+const tx = await sdk.transfer({
+  params: {
+    wallet: wallet.wallet,
+    token: "USDC",
+    recipient: "0x...",
+    amount: 10,
+    encryptKey: "user-pin-or-passkey",
+  },
+  bearerToken,
+});
+```
+
+## Documentation
+
+Full docs at [docs.chipipay.com](https://docs.chipipay.com)
+
+## License
+
+MIT

package/dist/{client-43S3tkH3.d.mts → client-CqD_yGH0.d.mts}

@@ -36,6 +36,11 @@ declare class ChipiClient {
         bearerToken: string;
         body?: Record<string, any>;
     }): Promise<T>;
+    patch<T>({ endpoint, bearerToken, body, }: {
+        endpoint: string;
+        bearerToken: string;
+        body?: Record<string, any>;
+    }): Promise<T>;
     delete<T>({ endpoint, bearerToken, }: {
         endpoint: string;
         bearerToken: string;

package/dist/{client-43S3tkH3.d.ts → client-CqD_yGH0.d.ts}

@@ -36,6 +36,11 @@ declare class ChipiClient {
         bearerToken: string;
         body?: Record<string, any>;
     }): Promise<T>;
+    patch<T>({ endpoint, bearerToken, body, }: {
+        endpoint: string;
+        bearerToken: string;
+        body?: Record<string, any>;
+    }): Promise<T>;
     delete<T>({ endpoint, bearerToken, }: {
         endpoint: string;
         bearerToken: string;

package/dist/index.d.mts

@@ -6,7 +6,7 @@ import { ChipiWallets } from './wallets.mjs';
 import { ChipiTransactions } from './transactions.mjs';
 import { ChipiSkuPurchases } from './skuPurchases.mjs';
 import { ChipiSkus } from './skus.mjs';
-import { C as ChipiClient } from './client-43S3tkH3.mjs';
+import { C as ChipiClient } from './client-CqD_yGH0.mjs';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { ChipiWallets } from './wallets.js';
 import { ChipiTransactions } from './transactions.js';
 import { ChipiSkuPurchases } from './skuPurchases.js';
 import { ChipiSkus } from './skus.js';
-import { C as ChipiClient } from './client-43S3tkH3.js';
+import { C as ChipiClient } from './client-CqD_yGH0.js';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).

package/dist/index.js

@@ -19,7 +19,7 @@ var ChipiClient = class {
     this.customAlphaUrl = config.alphaUrl;
     this.baseUrl = this.getBaseUrl();
     this.nodeUrl = config.nodeUrl || shared.STARKNET_NETWORKS.MAINNET;
-    this.sdkVersion = "11.21.0";
+    this.sdkVersion = "14.0.0";
   }
   /**
    * Get the API public key (for internal SDK use)
@@ -30,7 +30,7 @@ var ChipiClient = class {
   getBaseUrl() {
     const version = `v${shared.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}`;
@@ -100,7 +100,6 @@ var ChipiClient = class {
       });
       const data = await response.json();
       if (!response.ok) {
-        console.error("there was an error", data);
         const errorData = shared.validateErrorResponse(data);
         throw new shared.ChipiApiError(
           errorData.message,
@@ -140,6 +139,33 @@ var ChipiClient = class {
       throw shared.handleApiError(error);
     }
   }
+  async patch({
+    endpoint,
+    bearerToken,
+    body
+  }) {
+    try {
+      const url = new URL(`${this.baseUrl}${endpoint}`);
+      this.addVersionParams(url);
+      const response = await fetch(url.toString(), {
+        method: "PATCH",
+        headers: this.getHeaders(bearerToken),
+        body: body ? JSON.stringify(body) : void 0
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        const errorData = shared.validateErrorResponse(data);
+        throw new shared.ChipiApiError(
+          errorData.message,
+          errorData.code || `HTTP_${response.status}`,
+          response.status
+        );
+      }
+      return data;
+    } catch (error) {
+      throw shared.handleApiError(error);
+    }
+  }
   async delete({
     endpoint,
     bearerToken
@@ -167,16 +193,26 @@ var ChipiClient = class {
   }
 };
 var encryptPrivateKey = (privateKey, password) => {
+  if (!privateKey || !password) {
+    throw new Error("Private key and password are required");
+  }
   return CryptoES__default.default.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__default.default.AES.decrypt(encryptedPrivateKey, password);
     const decrypted = bytes.toString(CryptoES__default.default.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}`);
   }
 };
@@ -221,10 +257,7 @@ var ChipiWallets = class {
       const privateKeyAX = this.getPrivateKeyAX();
       const starkKeyPubAX = starknet.ec.starkCurve.getStarkKey(privateKeyAX);
       const accountClassHash = walletType === "READY" ? shared.WALLET_CLASS_HASHES.READY : shared.WALLET_CLASS_HASHES.CHIPI;
-      const constructorCallData = this.buildConstructorCallData(
-        walletType,
-        starkKeyPubAX
-      );
+      const constructorCallData = this.buildConstructorCallData(walletType, starkKeyPubAX);
       const publicKey = starknet.hash.calculateContractAddressFromHash(
         starkKeyPubAX,
         accountClassHash,
@@ -336,8 +369,22 @@ var ChipiWallets = class {
       if (err instanceof shared.ChipiApiError && err.status === 404) {
         return null;
       }
-      throw new Error(`getWallet error: ${String(err)}`);
+      throw err;
+    }
+  }
+  async updateWalletEncryption(params, bearerToken) {
+    const body = {
+      externalUserId: params.externalUserId,
+      newEncryptedPrivateKey: params.newEncryptedPrivateKey
+    };
+    if (params.publicKey != null) {
+      body.publicKey = params.publicKey;
     }
+    return this.client.patch({
+      endpoint: `${shared.API_ENDPOINTS.CHIPI_WALLETS}/update-encryption-details`,
+      bearerToken,
+      body
+    });
   }
   async getTokenBalance({
     params,
@@ -365,12 +412,11 @@ var executePaymasterTransaction = async ({
     }
     const rpcUrl = shared.WALLET_RPC_ENDPOINTS.READY;
     const accountClassHash = shared.WALLET_CLASS_HASHES.READY;
-    const privateKeyDecrypted = decryptPrivateKey(
-      wallet.encryptedPrivateKey,
-      encryptKey
-    );
-    if (!privateKeyDecrypted) {
-      throw new Error("Failed to decrypt private key");
+    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 starknet.RpcProvider({ nodeUrl: rpcUrl });
     const account = new starknet.Account({
@@ -443,16 +489,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: shared.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: shared.WALLET_CLASS_HASHES.CHIPI,
+      walletAddress: wallet.publicKey?.slice(0, 15) + "...",
+      hint: "Session keys only work with CHIPI wallets (SNIP-9 compatible)"
+    });
     throw new shared.ChipiSessionError(
       `Session execution requires CHIPI wallet type. Got: "${wallet.walletType || "undefined"}"`,
       shared.SESSION_ERRORS.INVALID_WALLET_TYPE_FOR_SESSION
@@ -471,18 +514,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 shared.ChipiSessionError(
         "Failed to decrypt session private key. Verify the encryptKey is correct.",
         shared.SESSION_ERRORS.SESSION_DECRYPTION_FAILED
@@ -534,12 +573,9 @@ var executePaymasterTransactionWithSession = async ({
       }
     });
     if (!result.transactionHash) {
-      console.error(
-        "[ChipiSDK:Session:Execute] No transaction hash in response",
-        {
-          result
-        }
-      );
+      console.error("[ChipiSDK:Session:Execute] No transaction hash in response", {
+        result
+      });
       throw new Error("Response does not contain transaction hash");
     }
     return result.transactionHash;
@@ -706,32 +742,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 = types.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 !== types.Chain.STARKNET) {
+      throw new Error(`Unsupported chain for SKU purchases: ${chain}`);
+    }
+    const tokenConfig = types.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 = shared.formatAmount(
-      minUsdAmount.toString(),
-      types.STARKNET_CONTRACTS[token].decimals
-    );
+    const parsedAmount = shared.formatAmount(minUsdAmount.toString(), tokenConfig.decimals);
     const calls = [
       {
         contractAddress: tokenAddress,
@@ -893,6 +918,12 @@ var ChipiSessions = class {
    */
   createSessionKey(params) {
     const { encryptKey, durationSeconds = shared.SESSION_DEFAULTS.DURATION_SECONDS } = params;
+    if (typeof durationSeconds !== "number" || !Number.isFinite(durationSeconds) || !Number.isInteger(durationSeconds) || durationSeconds <= 0) {
+      throw new shared.ChipiSessionError(
+        `Invalid session duration: ${durationSeconds}. Must be a positive integer.`,
+        shared.SESSION_ERRORS.SESSION_CREATION_FAILED
+      );
+    }
     try {
       const rawPrivateKey = starknet.ec.starkCurve.utils.randomPrivateKey();
       const privateKeyHex = this.toHex(rawPrivateKey);
@@ -906,13 +937,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 shared.ChipiSessionError(
         `Failed to create session key: ${err.message}`,
         shared.SESSION_ERRORS.SESSION_CREATION_FAILED
@@ -947,22 +975,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,
         starknet.num.toHex(sessionConfig.validUntil),
@@ -988,13 +1009,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));
@@ -1142,17 +1160,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;
     }
   }
   /**
@@ -1365,7 +1399,6 @@ var ChipiSDK = class {
     params,
     bearerToken
   }) {
-    console.log("createWallet params:", params);
     return this.wallets.createWallet({
       ...params,
       bearerToken: this.resolveBearerToken(bearerToken)
@@ -1381,10 +1414,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));
@@ -1402,19 +1432,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) {