@chipi-stack/backend 11.21.0 → 12.0.0

package/dist/index.js

@@ -19,6 +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";
   }
   /**
    * Get the API public key (for internal SDK use)
@@ -27,10 +28,19 @@ var ChipiClient = class {
     return this.apiPublicKey;
   }
   getBaseUrl() {
+    const version = `v${shared.API_VERSIONING.VERSION}`;
     if (this.customAlphaUrl) {
-      return this.customAlphaUrl.endsWith("/v1") ? this.customAlphaUrl : `${this.customAlphaUrl.replace(/\/$/, "")}/v1`;
+      const cleanUrl = this.customAlphaUrl.replace(/\/v\d+$/, "").replace(/\/$/, "");
+      return `${cleanUrl}/${version}`;
     }
-    return "https://celebrated-vision-production-66a5.up.railway.app/v1";
+    return `https://celebrated-vision-production-66a5.up.railway.app/${version}`;
+  }
+  /**
+   * Add API version query parameters to track the API version being used
+   * This helps the backend handle versioning and track which SDK versions are in use
+   */
+  addVersionParams(url) {
+    url.searchParams.append("__chipi_api_version", shared.API_VERSIONING.VERSION_DATE);
   }
   getHeaders(bearerToken) {
     const headers = {
@@ -49,6 +59,7 @@ var ChipiClient = class {
   }) {
     try {
       const url = new URL(`${this.baseUrl}${endpoint}`);
+      this.addVersionParams(url);
       if (params) {
         Object.entries(params).forEach(([key, value]) => {
           if (value !== void 0 && value !== null) {
@@ -80,14 +91,16 @@ var ChipiClient = class {
     body
   }) {
     try {
-      const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      const url = new URL(`${this.baseUrl}${endpoint}`);
+      this.addVersionParams(url);
+      const response = await fetch(url.toString(), {
         method: "POST",
         headers: this.getHeaders(bearerToken),
         body: body ? JSON.stringify(body) : void 0
       });
       const data = await response.json();
       if (!response.ok) {
-        console.log("there was an error", data);
+        console.error("there was an error", data);
         const errorData = shared.validateErrorResponse(data);
         throw new shared.ChipiApiError(
           errorData.message,
@@ -106,7 +119,9 @@ var ChipiClient = class {
     body
   }) {
     try {
-      const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      const url = new URL(`${this.baseUrl}${endpoint}`);
+      this.addVersionParams(url);
+      const response = await fetch(url.toString(), {
         method: "PUT",
         headers: this.getHeaders(bearerToken),
         body: body ? JSON.stringify(body) : void 0
@@ -130,7 +145,9 @@ var ChipiClient = class {
     bearerToken
   }) {
     try {
-      const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      const url = new URL(`${this.baseUrl}${endpoint}`);
+      this.addVersionParams(url);
+      const response = await fetch(url.toString(), {
         method: "DELETE",
         headers: this.getHeaders(bearerToken)
       });
@@ -181,23 +198,27 @@ var ChipiWallets = class {
   }
   async createWallet(params) {
     try {
-      const { encryptKey, externalUserId, bearerToken, userId } = params;
-      const provider = new starknet.RpcProvider({ nodeUrl: this.client.nodeUrl });
+      const {
+        encryptKey,
+        externalUserId,
+        bearerToken,
+        userId,
+        walletType = "CHIPI"
+        // Default to CHIPI wallet
+      } = params;
+      const rpcUrl = walletType === "READY" ? shared.WALLET_RPC_ENDPOINTS.READY : shared.WALLET_RPC_ENDPOINTS.CHIPI;
+      const provider = new starknet.RpcProvider({ nodeUrl: rpcUrl });
       const privateKeyAX = this.getPrivateKeyAX();
       const starkKeyPubAX = starknet.ec.starkCurve.getStarkKey(privateKeyAX);
-      const accountClassHash = "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f";
-      const axSigner = new starknet.CairoCustomEnum({
-        Starknet: { pubkey: starkKeyPubAX }
-      });
-      const axGuardian = new starknet.CairoOption(starknet.CairoOptionVariant.None);
-      const AXConstructorCallData = starknet.CallData.compile({
-        owner: axSigner,
-        guardian: axGuardian
-      });
+      const accountClassHash = walletType === "READY" ? shared.WALLET_CLASS_HASHES.READY : shared.WALLET_CLASS_HASHES.CHIPI;
+      const constructorCallData = this.buildConstructorCallData(
+        walletType,
+        starkKeyPubAX
+      );
       const publicKey = starknet.hash.calculateContractAddressFromHash(
         starkKeyPubAX,
         accountClassHash,
-        AXConstructorCallData,
+        constructorCallData,
         0
       );
       const account = new starknet.Account(provider, publicKey, privateKeyAX);
@@ -205,7 +226,10 @@ var ChipiWallets = class {
         endpoint: `${shared.API_ENDPOINTS.CHIPI_WALLETS}/prepare-creation`,
         bearerToken,
         body: {
-          publicKey
+          publicKey,
+          walletType,
+          starkKeyPubAX
+          // Needed for backend to build deployment data
         }
       });
       const { typeData, accountClassHash: accountClassHashResponse } = typeDataResponse;
@@ -214,7 +238,7 @@ var ChipiWallets = class {
         class_hash: accountClassHashResponse,
         salt: starkKeyPubAX,
         unique: `${starknet.num.toHex(0)}`,
-        calldata: AXConstructorCallData.map((value) => starknet.num.toHex(value))
+        calldata: constructorCallData.map((value) => starknet.num.toHex(value))
       };
       const encryptedPrivateKey = encryptPrivateKey(privateKeyAX, encryptKey);
       const executeTransactionResponse = await this.client.post({
@@ -224,6 +248,7 @@ var ChipiWallets = class {
           externalUserId,
           userId,
           publicKey,
+          walletType,
           userSignature: {
             r: userSignature.r.toString(),
             s: userSignature.s.toString(),
@@ -244,7 +269,7 @@ var ChipiWallets = class {
         wallet: executeTransactionResponse.wallet
       };
     } catch (error) {
-      console.error("Error detallado:", error);
+      console.error("Detailed error:", error);
       if (error instanceof Error && error.message.includes("SSL")) {
         throw new Error(
           "SSL connection error. Try using NODE_TLS_REJECT_UNAUTHORIZED=0 or verify the RPC URL"
@@ -256,6 +281,26 @@ var ChipiWallets = class {
       );
     }
   }
+  /**
+   * Build constructor calldata based on wallet type
+   * - CHIPI: Simple OpenZeppelin account with just public_key
+   * - ARGENT: Argent X Account with owner/guardian structure
+   */
+  buildConstructorCallData(walletType, starkKeyPubAX) {
+    if (walletType === "READY") {
+      const axSigner = new starknet.CairoCustomEnum({
+        Starknet: { pubkey: starkKeyPubAX }
+      });
+      const axGuardian = new starknet.CairoOption(starknet.CairoOptionVariant.None);
+      return starknet.CallData.compile({
+        owner: axSigner,
+        guardian: axGuardian
+      });
+    }
+    return starknet.CallData.compile({
+      public_key: starkKeyPubAX
+    });
+  }
   /**
    * Create a custodial merchant wallet
    */
@@ -301,11 +346,18 @@ var ChipiWallets = class {
 var executePaymasterTransaction = async ({
   params,
   bearerToken,
-  apiPublicKey,
-  backendUrl
+  client
 }) => {
   try {
     const { encryptKey, wallet, calls, saveToDatabase } = params;
+    if (!wallet.walletType) {
+      console.warn(
+        `[ChipiSDK] Wallet ${wallet.publicKey.slice(0, 10)}... has no walletType - defaulting to ARGENT for backward compatibility`
+      );
+    }
+    const walletType = wallet.walletType ?? "READY";
+    const rpcUrl = walletType === "READY" ? shared.WALLET_RPC_ENDPOINTS.READY : shared.WALLET_RPC_ENDPOINTS.CHIPI;
+    const accountClassHash = walletType === "READY" ? shared.WALLET_CLASS_HASHES.READY : shared.WALLET_CLASS_HASHES.CHIPI;
     const privateKeyDecrypted = decryptPrivateKey(
       wallet.encryptedPrivateKey,
       encryptKey
@@ -313,68 +365,164 @@ var executePaymasterTransaction = async ({
     if (!privateKeyDecrypted) {
       throw new Error("Failed to decrypt private key");
     }
-    const provider = new starknet.RpcProvider({
-      nodeUrl: "https://cloud.argent-api.com/v1/starknet/mainnet/rpc/v0.7"
-    });
+    const provider = new starknet.RpcProvider({ nodeUrl: rpcUrl });
     const account = new starknet.Account(
       provider,
       wallet.publicKey,
       privateKeyDecrypted
     );
-    const typeDataResponse = await fetch(
-      `${backendUrl}/transactions/prepare-typed-data`,
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${bearerToken}`,
-          "X-API-Key": apiPublicKey
+    const typeData = await client.post({
+      endpoint: "/transactions/prepare-typed-data",
+      bearerToken,
+      body: {
+        publicKey: wallet.publicKey,
+        walletType,
+        calls,
+        accountClassHash
+      }
+    });
+    const userSignature = await account.signMessage(typeData);
+    const result = await client.post({
+      endpoint: "/transactions/execute-sponsored-transaction",
+      bearerToken,
+      body: {
+        publicKey: wallet.publicKey,
+        typeData,
+        userSignature: {
+          r: userSignature.r.toString(),
+          s: userSignature.s.toString(),
+          recovery: userSignature.recovery
         },
-        body: JSON.stringify({
-          publicKey: wallet.publicKey,
-          calls,
-          accountClassHash: "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f"
-        })
+        saveToDatabase,
+        walletType
       }
-    );
-    if (!typeDataResponse.ok) {
-      const errorText = await typeDataResponse.text();
-      throw new Error(`Error in API: ${errorText}`);
+    });
+    if (!result.transactionHash) {
+      throw new Error("The response does not contain the transaction hash");
     }
-    const typeData = await typeDataResponse.json();
-    const userSignature = await account.signMessage(typeData);
-    const executeTransaction = await fetch(
-      `${backendUrl}/transactions/execute-sponsored-transaction`,
+    return result.transactionHash;
+  } catch (error) {
+    console.error("Error sending transaction with paymaster", error);
+    throw error;
+  }
+};
+var executePaymasterTransactionWithSession = async ({
+  params,
+  bearerToken,
+  client
+}) => {
+  const { encryptKey, wallet, session, calls, saveToDatabase } = params;
+  if (wallet.walletType !== "CHIPI") {
+    console.error(
+      "[ChipiSDK:Session:Execute] Invalid wallet type for session execution",
       {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${bearerToken}`,
-          "X-API-Key": apiPublicKey
-        },
-        body: JSON.stringify({
-          publicKey: wallet.publicKey,
-          typeData,
-          userSignature: {
-            r: userSignature.r.toString(),
-            s: userSignature.s.toString(),
-            recovery: userSignature.recovery
-          },
-          saveToDatabase
-        })
+        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)"
       }
     );
-    if (!executeTransaction.ok) {
-      const errorText = await executeTransaction.text();
-      throw new Error(`Error executing sponsored transaction: ${errorText}`);
+    throw new shared.ChipiSessionError(
+      `Session execution requires CHIPI wallet type. Got: "${wallet.walletType || "undefined"}"`,
+      shared.SESSION_ERRORS.INVALID_WALLET_TYPE_FOR_SESSION
+    );
+  }
+  const nowSeconds = Math.floor(Date.now() / 1e3);
+  if (session.validUntil < nowSeconds) {
+    console.error("[ChipiSDK:Session:Execute] Session has expired", {
+      sessionExpiry: new Date(session.validUntil * 1e3).toISOString(),
+      currentTime: new Date(nowSeconds * 1e3).toISOString(),
+      expiredAgo: `${nowSeconds - session.validUntil} seconds`
+    });
+    throw new shared.ChipiSessionError(
+      `Session expired at ${new Date(session.validUntil * 1e3).toISOString()}. Create a new session key.`,
+      shared.SESSION_ERRORS.SESSION_EXPIRED
+    );
+  }
+  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"
+        }
+      );
+      throw new shared.ChipiSessionError(
+        "Failed to decrypt session private key. Verify the encryptKey is correct.",
+        shared.SESSION_ERRORS.SESSION_DECRYPTION_FAILED
+      );
+    }
+    const derivedPubKey = starknet.ec.starkCurve.getStarkKey(sessionPrivateKey);
+    if (derivedPubKey.toLowerCase() !== session.publicKey.toLowerCase()) {
+      console.error("[ChipiSDK:Session:Execute] Session key mismatch", {
+        expected: session.publicKey.slice(0, 15) + "...",
+        derived: derivedPubKey.slice(0, 15) + "...",
+        hint: "The encrypted private key does not match the stored public key"
+      });
+      throw new shared.ChipiSessionError(
+        "Session key mismatch: decrypted private key does not match the public key",
+        shared.SESSION_ERRORS.SESSION_DECRYPTION_FAILED
+      );
     }
-    const result = await executeTransaction.json();
+    const accountClassHash = shared.WALLET_CLASS_HASHES.CHIPI;
+    const typeDataResult = await client.post({
+      endpoint: "/transactions/prepare-typed-data",
+      bearerToken,
+      body: {
+        publicKey: wallet.publicKey,
+        calls,
+        accountClassHash,
+        walletType: "CHIPI"
+      }
+    });
+    const msgHash = starknet.typedData.getMessageHash(typeDataResult, wallet.publicKey);
+    const { r, s } = starknet.ec.starkCurve.sign(msgHash, sessionPrivateKey);
+    const sessionSignature = [
+      session.publicKey,
+      starknet.num.toHex(r),
+      starknet.num.toHex(s),
+      starknet.num.toHex(session.validUntil)
+    ];
+    const result = await client.post({
+      endpoint: "/transactions/execute-sponsored-transaction",
+      bearerToken,
+      body: {
+        publicKey: wallet.publicKey,
+        typeData: typeDataResult,
+        // Session signature format - array of 4 hex strings
+        userSignature: sessionSignature,
+        saveToDatabase,
+        walletType: "CHIPI",
+        isSessionSignature: true
+        // Flag to indicate session signature format
+      }
+    });
     if (!result.transactionHash) {
-      throw new Error("The response does not contain the transaction hash");
+      console.error(
+        "[ChipiSDK:Session:Execute] No transaction hash in response",
+        {
+          result
+        }
+      );
+      throw new Error("Response does not contain transaction hash");
     }
     return result.transactionHash;
   } catch (error) {
-    console.error("Error sending transaction with paymaster", error);
+    const err = error instanceof Error ? error : new Error(String(error));
+    if (error instanceof shared.ChipiSessionError) {
+      throw error;
+    }
+    console.error("[ChipiSDK:Session:Execute] Unexpected error", {
+      error: err.message,
+      walletAddress: wallet.publicKey?.slice(0, 15) + "...",
+      sessionPubKey: session.publicKey?.slice(0, 15) + "..."
+    });
     throw error;
   }
 };
@@ -400,8 +548,7 @@ var ChipiTransactions = class {
         saveToDatabase
       },
       bearerToken,
-      backendUrl: this.client.baseUrl,
-      apiPublicKey: this.client.getApiPublicKey()
+      client: this.client
     });
   }
   /**
@@ -534,16 +681,16 @@ var ChipiSkuTransactions = class {
       },
       {
         contractAddress: shared.SKU_CONTRACTS.RECHARGER_WITH_STRK_MAINNET,
-        entrypoint: "newRecharge",
+        entrypoint: "process_recharge",
         calldata: starknet.CallData.compile({
-          token_address: tokenAddress,
+          token: tokenAddress,
           amount: starknet.cairo.uint256(parsedAmount),
-          rechargeId: CryptoES__default.default.SHA256(
+          recharge_id: CryptoES__default.default.SHA256(
             CryptoES__default.default.lib.WordArray.random(32)
             // 32 bytes = 256 bits entropy
           ).toString().slice(0, 20),
-          productId: skuId,
-          carrierId: shared.CARRIER_IDS.CHIPI_PAY
+          product_code: skuId,
+          merchant_slug: shared.CARRIER_IDS.CHIPI_PAY
         })
       },
       {
@@ -670,6 +817,382 @@ var Users = class {
     });
   }
 };
+var ChipiSessions = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Validate that the wallet is a CHIPI wallet (required for session operations).
+   * Throws ChipiSessionError if wallet type is not CHIPI.
+   */
+  validateChipiWallet(walletType, operation, walletPublicKey) {
+    if (walletType !== "CHIPI") {
+      console.error(`[ChipiSDK:Session:${operation}] Invalid wallet type`, {
+        provided: walletType,
+        required: "CHIPI",
+        expectedClassHash: shared.WALLET_CLASS_HASHES["CHIPI"],
+        walletAddress: walletPublicKey ? walletPublicKey.slice(0, 15) + "..." : "(not provided)",
+        hint: "Session keys only work with CHIPI wallets (SNIP-9 compatible)"
+      });
+      throw new shared.ChipiSessionError(
+        `Session keys require CHIPI wallet type. Got: "${walletType || "undefined"}". Session keys are only supported for CHIPI wallets with class hash ${shared.WALLET_CLASS_HASHES["CHIPI"]}`,
+        shared.SESSION_ERRORS.INVALID_WALLET_TYPE_FOR_SESSION
+      );
+    }
+  }
+  /**
+   * Convert a Uint8Array to hex string with 0x prefix.
+   */
+  toHex(uint8) {
+    return "0x" + Array.from(uint8).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  /**
+   * Generate a new session keypair locally.
+   *
+   * This method generates the session keys but does NOT register them on-chain.
+   * The returned SessionKeyData should be stored by the developer externally
+   * (e.g., in Clerk metadata, database, etc.) - the SDK does NOT persist this.
+   *
+   * After generating, call `addSessionKeyToContract()` to register the session on-chain.
+   *
+   * @param params - Session creation parameters
+   * @returns SessionKeyData for external storage
+   *
+   * @example
+   * ```typescript
+   * const session = sdk.sessions.createSessionKey({
+   *   encryptKey: userEncryptKey,
+   *   durationSeconds: 21600 // 6 hours
+   * });
+   * // Store session externally (e.g., in Clerk metadata)
+   * await saveToClerk(session);
+   * ```
+   */
+  createSessionKey(params) {
+    const { encryptKey, durationSeconds = shared.SESSION_DEFAULTS.DURATION_SECONDS } = params;
+    try {
+      const rawPrivateKey = starknet.ec.starkCurve.utils.randomPrivateKey();
+      const privateKeyHex = this.toHex(rawPrivateKey);
+      const publicKey = starknet.ec.starkCurve.getStarkKey(privateKeyHex);
+      const validUntil = Math.floor(Date.now() / 1e3) + durationSeconds;
+      const encryptedPrivateKey = encryptPrivateKey(privateKeyHex, encryptKey);
+      return {
+        publicKey,
+        encryptedPrivateKey,
+        validUntil
+      };
+    } 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
+        }
+      );
+      throw new shared.ChipiSessionError(
+        `Failed to create session key: ${err.message}`,
+        shared.SESSION_ERRORS.SESSION_CREATION_FAILED
+      );
+    }
+  }
+  /**
+   * Register a session key on the smart contract.
+   *
+   * This executes a sponsored transaction (using owner signature) to call
+   * `add_or_update_session_key` on the CHIPI wallet contract.
+   *
+   * The session must be registered before it can be used for transactions.
+   *
+   * @param params - Session registration parameters
+   * @param bearerToken - Authentication token
+   * @returns Transaction hash
+   *
+   * @example
+   * ```typescript
+   * const txHash = await sdk.sessions.addSessionKeyToContract({
+   *   encryptKey: userEncryptKey,
+   *   wallet: userWallet,
+   *   sessionConfig: {
+   *     sessionPublicKey: session.publicKey,
+   *     validUntil: session.validUntil,
+   *     maxCalls: 1000,
+   *     allowedEntrypoints: [] // empty = all allowed
+   *   }
+   * }, bearerToken);
+   * ```
+   */
+  async addSessionKeyToContract(params, bearerToken) {
+    const { encryptKey, wallet, sessionConfig } = params;
+    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
+        }
+      );
+      const calldata = [
+        sessionConfig.sessionPublicKey,
+        starknet.num.toHex(sessionConfig.validUntil),
+        starknet.num.toHex(sessionConfig.maxCalls),
+        // Array: first element is length, then elements
+        starknet.num.toHex(sessionConfig.allowedEntrypoints.length),
+        ...sessionConfig.allowedEntrypoints
+      ];
+      const txHash = await executePaymasterTransaction({
+        params: {
+          encryptKey,
+          wallet: { ...wallet, walletType: "CHIPI" },
+          calls: [
+            {
+              contractAddress: wallet.publicKey,
+              entrypoint: shared.SESSION_ENTRYPOINTS.ADD_OR_UPDATE,
+              calldata
+            }
+          ],
+          saveToDatabase: false
+          // Don't record session management txs
+        },
+        bearerToken,
+        client: this.client
+      });
+      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));
+      console.error("[ChipiSDK:Session:AddToContract] Registration failed", {
+        error: err.message,
+        walletAddress: wallet.publicKey?.slice(0, 15) + "...",
+        sessionPubKey: sessionConfig.sessionPublicKey?.slice(0, 15) + "...",
+        validUntil: new Date(sessionConfig.validUntil * 1e3).toISOString(),
+        maxCalls: sessionConfig.maxCalls
+      });
+      throw error;
+    }
+  }
+  /**
+   * Revoke a session key from the smart contract.
+   *
+   * This executes a sponsored transaction (using owner signature) to call
+   * `revoke_session_key` on the CHIPI wallet contract.
+   *
+   * After revocation, the session key can no longer be used for transactions.
+   *
+   * @param params - Session revocation parameters
+   * @param bearerToken - Authentication token
+   * @returns Transaction hash
+   *
+   * @example
+   * ```typescript
+   * const txHash = await sdk.sessions.revokeSessionKey({
+   *   encryptKey: userEncryptKey,
+   *   wallet: userWallet,
+   *   sessionPublicKey: session.publicKey
+   * }, bearerToken);
+   * ```
+   */
+  async revokeSessionKey(params, bearerToken) {
+    const { encryptKey, wallet, sessionPublicKey } = params;
+    this.validateChipiWallet(wallet.walletType, "Revoke", wallet.publicKey);
+    try {
+      console.log("[ChipiSDK:Session:Revoke] Revoking session from contract", {
+        walletAddress: wallet.publicKey.slice(0, 15) + "...",
+        sessionToRevoke: sessionPublicKey.slice(0, 15) + "..."
+      });
+      const txHash = await executePaymasterTransaction({
+        params: {
+          encryptKey,
+          wallet: { ...wallet, walletType: "CHIPI" },
+          calls: [
+            {
+              contractAddress: wallet.publicKey,
+              entrypoint: shared.SESSION_ENTRYPOINTS.REVOKE,
+              calldata: [sessionPublicKey]
+            }
+          ],
+          saveToDatabase: false
+          // Don't record session management txs
+        },
+        bearerToken,
+        client: this.client
+      });
+      console.log("[ChipiSDK:Session:Revoke] Session revoked successfully", {
+        txHash,
+        sessionRevoked: sessionPublicKey.slice(0, 15) + "..."
+      });
+      return txHash;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      console.error("[ChipiSDK:Session:Revoke] Revocation failed", {
+        error: err.message,
+        walletAddress: wallet.publicKey?.slice(0, 15) + "...",
+        sessionToRevoke: sessionPublicKey?.slice(0, 15) + "..."
+      });
+      throw error;
+    }
+  }
+  /**
+   * Query session data from the smart contract.
+   *
+   * This is a read-only call that does not require signing or gas.
+   *
+   * @param params - Query parameters
+   * @returns Session data including status, remaining calls, and allowed entrypoints
+   *
+   * @example
+   * ```typescript
+   * const sessionData = await sdk.sessions.getSessionData({
+   *   walletAddress: userWallet.publicKey,
+   *   sessionPublicKey: session.publicKey
+   * });
+   * if (sessionData.isActive) {
+   *   console.log(`Session has ${sessionData.remainingCalls} calls remaining`);
+   * }
+   * ```
+   *
+   * NOTE: This method intentionally does NOT validate walletType because:
+   * 1. It's a read-only query - no state change or risk
+   * 2. Non-CHIPI wallets will simply return isActive=false (graceful failure)
+   * 3. It doesn't require walletType parameter at all - only walletAddress
+   * Adding validation would require changing the interface for no functional benefit.
+   */
+  async getSessionData(params) {
+    const { walletAddress, sessionPublicKey } = params;
+    try {
+      const provider = new starknet.RpcProvider({
+        nodeUrl: shared.WALLET_RPC_ENDPOINTS["CHIPI"]
+      });
+      console.log("[ChipiSDK:Session:GetData] Querying session data", {
+        walletAddress: walletAddress.slice(0, 15) + "...",
+        sessionPubKey: sessionPublicKey.slice(0, 15) + "..."
+      });
+      const result = await provider.callContract({
+        contractAddress: walletAddress,
+        entrypoint: shared.SESSION_ENTRYPOINTS.GET_DATA,
+        calldata: [sessionPublicKey]
+      });
+      const resultArray = Array.isArray(result) ? result : result.result || [];
+      if (resultArray.length < 4) {
+        console.warn("[ChipiSDK:Session:GetData] Unexpected response format", {
+          resultLength: resultArray.length,
+          result: resultArray
+        });
+        return {
+          isActive: false,
+          validUntil: 0,
+          remainingCalls: 0,
+          allowedEntrypoints: []
+        };
+      }
+      const isActive = resultArray[0] === "0x1";
+      const validUntil = Number(BigInt(resultArray[1]));
+      const remainingCalls = Number(BigInt(resultArray[2]));
+      const entrypointsLen = Number(BigInt(resultArray[3]));
+      const allowedEntrypoints = resultArray.slice(4, 4 + entrypointsLen);
+      const sessionData = {
+        isActive,
+        validUntil,
+        remainingCalls,
+        allowedEntrypoints
+      };
+      console.log("[ChipiSDK:Session:GetData] Session data retrieved", {
+        isActive,
+        validUntil: new Date(validUntil * 1e3).toISOString(),
+        remainingCalls,
+        allowedEntrypointsCount: allowedEntrypoints.length
+      });
+      return sessionData;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      console.error("[ChipiSDK:Session:GetData] Query failed", {
+        error: err.message,
+        walletAddress: walletAddress?.slice(0, 15) + "...",
+        sessionPubKey: sessionPublicKey?.slice(0, 15) + "..."
+      });
+      return {
+        isActive: false,
+        validUntil: 0,
+        remainingCalls: 0,
+        allowedEntrypoints: []
+      };
+    }
+  }
+  /**
+   * Execute a gasless transaction using a session key.
+   *
+   * This uses the 4-element session signature format instead of owner signature.
+   * The session must be:
+   * 1. Generated via `createSessionKey()`
+   * 2. Registered on-chain via `addSessionKeyToContract()`
+   *
+   * CHIPI wallets only - will throw if wallet type is not CHIPI.
+   *
+   * @param params - Session execution parameters
+   * @param bearerToken - Authentication token
+   * @returns Transaction hash
+   *
+   * @example
+   * ```typescript
+   * // 1. Create session key (store externally)
+   * const session = sdk.sessions.createSessionKey({ encryptKey });
+   *
+   * // 2. Register on contract (one-time)
+   * await sdk.sessions.addSessionKeyToContract({
+   *   encryptKey,
+   *   wallet,
+   *   sessionConfig: {
+   *     sessionPublicKey: session.publicKey,
+   *     validUntil: session.validUntil,
+   *     maxCalls: 1000,
+   *     allowedEntrypoints: []
+   *   }
+   * }, bearerToken);
+   *
+   * // 3. Execute transactions with session (no owner key needed)
+   * const txHash = await sdk.sessions.executeTransactionWithSession({
+   *   encryptKey,
+   *   wallet,
+   *   session,
+   *   calls
+   * }, bearerToken);
+   * ```
+   */
+  async executeTransactionWithSession(params, bearerToken) {
+    const { encryptKey, wallet, session, calls } = params;
+    if (wallet.walletType && wallet.walletType !== "CHIPI") {
+      throw new shared.ChipiSessionError(
+        `Session execution only supports CHIPI wallets. Got: ${wallet.walletType}`,
+        shared.SESSION_ERRORS.INVALID_WALLET_TYPE_FOR_SESSION
+      );
+    }
+    return executePaymasterTransactionWithSession({
+      params: {
+        encryptKey,
+        wallet: { ...wallet, walletType: "CHIPI" },
+        session,
+        calls,
+        saveToDatabase: true
+      },
+      bearerToken,
+      client: this.client
+    });
+  }
+};
 
 // src/chipi-sdk.ts
 var ChipiSDK = class {
@@ -682,7 +1205,9 @@ var ChipiSDK = class {
     this.skuTransactions = new ChipiSkuTransactions(this.client);
     this.skus = new ChipiSkus(this.client);
     this.users = new Users(this.client);
+    this.sessions = new ChipiSessions(this.client);
     this.executeTransaction = this.executeTransaction.bind(this);
+    this.executeTransactionWithSession = this.executeTransactionWithSession.bind(this);
     this.transfer = this.transfer.bind(this);
     this.approve = this.approve.bind(this);
     this.stakeVesuUsdc = this.stakeVesuUsdc.bind(this);
@@ -716,6 +1241,49 @@ var ChipiSDK = class {
       bearerToken: this.resolveBearerToken(bearerToken)
     });
   }
+  /**
+   * Execute a gasless transaction using a session key.
+   *
+   * This uses the 4-element session signature format instead of owner signature.
+   * The session must be:
+   * 1. Generated via `sessions.createSessionKey()`
+   * 2. Registered on-chain via `sessions.addSessionKeyToContract()`
+   *
+   * CHIPI wallets only - will throw if wallet type is not CHIPI.
+   *
+   * @example
+   * ```typescript
+   * // 1. Create session key (store externally)
+   * const session = sdk.sessions.createSessionKey({ encryptKey });
+   *
+   * // 2. Register on contract (one-time)
+   * await sdk.sessions.addSessionKeyToContract({
+   *   encryptKey,
+   *   wallet,
+   *   sessionConfig: {
+   *     sessionPublicKey: session.publicKey,
+   *     validUntil: session.validUntil,
+   *     maxCalls: 1000,
+   *     allowedEntrypoints: []
+   *   }
+   * }, bearerToken);
+   *
+   * // 3. Execute transactions with session (no owner key needed)
+   * const txHash = await sdk.executeTransactionWithSession({
+   *   params: { encryptKey, wallet, session, calls },
+   *   bearerToken
+   * });
+   * ```
+   */
+  async executeTransactionWithSession({
+    params,
+    bearerToken
+  }) {
+    return this.sessions.executeTransactionWithSession(
+      params,
+      this.resolveBearerToken(bearerToken)
+    );
+  }
   /**
    * Transfer tokens
    */
@@ -916,6 +1484,7 @@ exports.ChipiBrowserSDK = ChipiBrowserSDK;
 exports.ChipiClient = ChipiClient;
 exports.ChipiSDK = ChipiSDK;
 exports.ChipiServerSDK = ChipiServerSDK;
+exports.ChipiSessions = ChipiSessions;
 exports.ChipiSkuTransactions = ChipiSkuTransactions;
 exports.ChipiSkus = ChipiSkus;
 exports.ChipiTransactions = ChipiTransactions;