@chipi-stack/backend 11.21.0 → 12.0.0

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

@@ -8,12 +8,18 @@ declare class ChipiClient {
     baseUrl: string;
     nodeUrl: string;
     private customAlphaUrl?;
+    private sdkVersion;
     constructor(config: ChipiSDKConfig);
     /**
      * Get the API public key (for internal SDK use)
      */
     getApiPublicKey(): string;
     private getBaseUrl;
+    /**
+     * 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
+     */
+    private addVersionParams;
     private getHeaders;
     get<T>({ endpoint, params, bearerToken, }: {
         endpoint: string;

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

@@ -8,12 +8,18 @@ declare class ChipiClient {
     baseUrl: string;
     nodeUrl: string;
     private customAlphaUrl?;
+    private sdkVersion;
     constructor(config: ChipiSDKConfig);
     /**
      * Get the API public key (for internal SDK use)
      */
     getApiPublicKey(): string;
     private getBaseUrl;
+    /**
+     * 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
+     */
+    private addVersionParams;
     private getHeaders;
     get<T>({ endpoint, params, bearerToken, }: {
         endpoint: string;

package/dist/index.d.mts

@@ -1,11 +1,11 @@
 import * as _chipi_stack_types from '@chipi-stack/types';
-import { GetUserParams, User, WalletData, CreateUserParams, ChipiSDKConfig, ExecuteTransactionParams, TransferParams, ApproveParams, StakeVesuUsdcParams, WithdrawVesuUsdcParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuTransactionParams, SkuTransaction, GetSkuListQuery, Sku, ChipiServerSDKConfig, ChipiBrowserSDKConfig } from '@chipi-stack/types';
+import { GetUserParams, User, WalletData, CreateUserParams, CreateSessionKeyParams, SessionKeyData, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, SessionDataResponse, ExecuteWithSessionParams, ChipiSDKConfig, ExecuteTransactionParams, TransferParams, ApproveParams, StakeVesuUsdcParams, WithdrawVesuUsdcParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuTransactionParams, SkuTransaction, GetSkuListQuery, Sku, ChipiServerSDKConfig, ChipiBrowserSDKConfig } from '@chipi-stack/types';
 export * from '@chipi-stack/types';
 import { ChipiWallets } from './wallets.mjs';
 import { ChipiTransactions } from './transactions.mjs';
 import { ChipiSkuTransactions } from './skuTransactions.mjs';
 import { ChipiSkus } from './skus.mjs';
-import { C as ChipiClient } from './client-E8WQVssY.mjs';
+import { C as ChipiClient } from './client-43S3tkH3.mjs';
 
 /**
  * User management
@@ -31,6 +31,167 @@ declare class Users {
     createUser(params: CreateUserParams, bearerToken: string): Promise<User>;
 }
 
+/**
+ * Session key management for CHIPI wallets (SNIP-9 compatible).
+ *
+ * Session keys enable temporary, delegated access to execute transactions
+ * without requiring the owner's private key for each operation.
+ *
+ * @see https://github.com/chipi-pay/sessions-smart-contract
+ */
+declare class ChipiSessions {
+    private client;
+    constructor(client: ChipiClient);
+    /**
+     * Validate that the wallet is a CHIPI wallet (required for session operations).
+     * Throws ChipiSessionError if wallet type is not CHIPI.
+     */
+    private validateChipiWallet;
+    /**
+     * Convert a Uint8Array to hex string with 0x prefix.
+     */
+    private toHex;
+    /**
+     * 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: CreateSessionKeyParams): SessionKeyData;
+    /**
+     * 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);
+     * ```
+     */
+    addSessionKeyToContract(params: AddSessionKeyParams, bearerToken: string): Promise<string>;
+    /**
+     * 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);
+     * ```
+     */
+    revokeSessionKey(params: RevokeSessionKeyParams, bearerToken: string): Promise<string>;
+    /**
+     * 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.
+     */
+    getSessionData(params: GetSessionDataParams): Promise<SessionDataResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    executeTransactionWithSession(params: ExecuteWithSessionParams, bearerToken: string): Promise<string>;
+}
+
 /**
  * Main Chipi SDK class
  */
@@ -43,6 +204,7 @@ declare class ChipiSDK {
     readonly skuTransactions: ChipiSkuTransactions;
     readonly skus: ChipiSkus;
     readonly users: Users;
+    readonly sessions: ChipiSessions;
     constructor(config: ChipiSDKConfig);
     /**
      * Resolve bearer token - uses provided token or falls back to apiSecretKey
@@ -55,6 +217,44 @@ declare class ChipiSDK {
         params: ExecuteTransactionParams;
         bearerToken?: string;
     }): Promise<string>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    executeTransactionWithSession({ params, bearerToken, }: {
+        params: ExecuteWithSessionParams;
+        bearerToken?: string;
+    }): Promise<string>;
     /**
      * Transfer tokens
      */
@@ -102,9 +302,7 @@ declare class ChipiSDK {
         bearerToken?: string;
     }): Promise<Transaction>;
     getTransactionList(query: GetTransactionListQuery, bearerToken?: string): Promise<PaginatedResponse<Transaction>>;
-    getWallet(params: GetWalletParams, bearerToken?: string): Promise<(_chipi_stack_types.GetWalletResponse & {
-        normalizedPublicKey: string;
-    }) | null>;
+    getWallet(params: GetWalletParams, bearerToken?: string): Promise<_chipi_stack_types.GetWalletResponse | null>;
     getTokenBalance(params: GetTokenBalanceParams, bearerToken?: string): Promise<GetTokenBalanceResponse>;
     /**
      * Create a SKU transaction
@@ -195,4 +393,4 @@ declare class ChipiBrowserSDK extends ChipiSDK {
 declare const encryptPrivateKey: (privateKey: string, password: string) => string;
 declare const decryptPrivateKey: (encryptedPrivateKey: string, password: string) => string;
 
-export { ChipiBrowserSDK, ChipiClient, ChipiSDK, ChipiServerSDK, ChipiSkuTransactions, ChipiSkus, ChipiTransactions, ChipiWallets, decryptPrivateKey, encryptPrivateKey };
+export { ChipiBrowserSDK, ChipiClient, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuTransactions, ChipiSkus, ChipiTransactions, ChipiWallets, decryptPrivateKey, encryptPrivateKey };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import * as _chipi_stack_types from '@chipi-stack/types';
-import { GetUserParams, User, WalletData, CreateUserParams, ChipiSDKConfig, ExecuteTransactionParams, TransferParams, ApproveParams, StakeVesuUsdcParams, WithdrawVesuUsdcParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuTransactionParams, SkuTransaction, GetSkuListQuery, Sku, ChipiServerSDKConfig, ChipiBrowserSDKConfig } from '@chipi-stack/types';
+import { GetUserParams, User, WalletData, CreateUserParams, CreateSessionKeyParams, SessionKeyData, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, SessionDataResponse, ExecuteWithSessionParams, ChipiSDKConfig, ExecuteTransactionParams, TransferParams, ApproveParams, StakeVesuUsdcParams, WithdrawVesuUsdcParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuTransactionParams, SkuTransaction, GetSkuListQuery, Sku, ChipiServerSDKConfig, ChipiBrowserSDKConfig } from '@chipi-stack/types';
 export * from '@chipi-stack/types';
 import { ChipiWallets } from './wallets.js';
 import { ChipiTransactions } from './transactions.js';
 import { ChipiSkuTransactions } from './skuTransactions.js';
 import { ChipiSkus } from './skus.js';
-import { C as ChipiClient } from './client-E8WQVssY.js';
+import { C as ChipiClient } from './client-43S3tkH3.js';
 
 /**
  * User management
@@ -31,6 +31,167 @@ declare class Users {
     createUser(params: CreateUserParams, bearerToken: string): Promise<User>;
 }
 
+/**
+ * Session key management for CHIPI wallets (SNIP-9 compatible).
+ *
+ * Session keys enable temporary, delegated access to execute transactions
+ * without requiring the owner's private key for each operation.
+ *
+ * @see https://github.com/chipi-pay/sessions-smart-contract
+ */
+declare class ChipiSessions {
+    private client;
+    constructor(client: ChipiClient);
+    /**
+     * Validate that the wallet is a CHIPI wallet (required for session operations).
+     * Throws ChipiSessionError if wallet type is not CHIPI.
+     */
+    private validateChipiWallet;
+    /**
+     * Convert a Uint8Array to hex string with 0x prefix.
+     */
+    private toHex;
+    /**
+     * 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: CreateSessionKeyParams): SessionKeyData;
+    /**
+     * 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);
+     * ```
+     */
+    addSessionKeyToContract(params: AddSessionKeyParams, bearerToken: string): Promise<string>;
+    /**
+     * 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);
+     * ```
+     */
+    revokeSessionKey(params: RevokeSessionKeyParams, bearerToken: string): Promise<string>;
+    /**
+     * 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.
+     */
+    getSessionData(params: GetSessionDataParams): Promise<SessionDataResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    executeTransactionWithSession(params: ExecuteWithSessionParams, bearerToken: string): Promise<string>;
+}
+
 /**
  * Main Chipi SDK class
  */
@@ -43,6 +204,7 @@ declare class ChipiSDK {
     readonly skuTransactions: ChipiSkuTransactions;
     readonly skus: ChipiSkus;
     readonly users: Users;
+    readonly sessions: ChipiSessions;
     constructor(config: ChipiSDKConfig);
     /**
      * Resolve bearer token - uses provided token or falls back to apiSecretKey
@@ -55,6 +217,44 @@ declare class ChipiSDK {
         params: ExecuteTransactionParams;
         bearerToken?: string;
     }): Promise<string>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    executeTransactionWithSession({ params, bearerToken, }: {
+        params: ExecuteWithSessionParams;
+        bearerToken?: string;
+    }): Promise<string>;
     /**
      * Transfer tokens
      */
@@ -102,9 +302,7 @@ declare class ChipiSDK {
         bearerToken?: string;
     }): Promise<Transaction>;
     getTransactionList(query: GetTransactionListQuery, bearerToken?: string): Promise<PaginatedResponse<Transaction>>;
-    getWallet(params: GetWalletParams, bearerToken?: string): Promise<(_chipi_stack_types.GetWalletResponse & {
-        normalizedPublicKey: string;
-    }) | null>;
+    getWallet(params: GetWalletParams, bearerToken?: string): Promise<_chipi_stack_types.GetWalletResponse | null>;
     getTokenBalance(params: GetTokenBalanceParams, bearerToken?: string): Promise<GetTokenBalanceResponse>;
     /**
      * Create a SKU transaction
@@ -195,4 +393,4 @@ declare class ChipiBrowserSDK extends ChipiSDK {
 declare const encryptPrivateKey: (privateKey: string, password: string) => string;
 declare const decryptPrivateKey: (encryptedPrivateKey: string, password: string) => string;
 
-export { ChipiBrowserSDK, ChipiClient, ChipiSDK, ChipiServerSDK, ChipiSkuTransactions, ChipiSkus, ChipiTransactions, ChipiWallets, decryptPrivateKey, encryptPrivateKey };
+export { ChipiBrowserSDK, ChipiClient, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuTransactions, ChipiSkus, ChipiTransactions, ChipiWallets, decryptPrivateKey, encryptPrivateKey };