@solana/kora 0.2.1 → 0.3.0-beta.2

package/dist/src/client.d.ts

@@ -1,10 +1,21 @@
-import { Config, EstimateTransactionFeeRequest, EstimateTransactionFeeResponse, GetBlockhashResponse, GetPayerSignerResponse, GetPaymentInstructionRequest, GetPaymentInstructionResponse, GetSupportedTokensResponse, KoraClientOptions, SignAndSendTransactionRequest, SignAndSendTransactionResponse, SignTransactionRequest, SignTransactionResponse, TransferTransactionRequest, TransferTransactionResponse } from './types/index.js';
+import { Config, EstimateBundleFeeRequest, EstimateBundleFeeResponse, EstimateTransactionFeeRequest, EstimateTransactionFeeResponse, GetBlockhashResponse, GetPayerSignerResponse, GetPaymentInstructionRequest, GetPaymentInstructionResponse, GetSupportedTokensResponse, GetVersionResponse, KoraClientOptions, SignAndSendBundleRequest, SignAndSendBundleResponse, SignAndSendTransactionRequest, SignAndSendTransactionResponse, SignBundleRequest, SignBundleResponse, SignTransactionRequest, SignTransactionResponse } from './types/index.js';
 /**
  * Kora RPC client for interacting with the Kora paymaster service.
  *
- * @example
+ * Provides methods to estimate fees, sign transactions, and perform gasless transfers
+ * on Solana as specified by the Kora paymaster operator.
+ *
+ * @example Kora Initialization
  * ```typescript
- * const client = new KoraClient({ rpcUrl: 'http://localhost:8080' });
+ * const client = new KoraClient({
+ *   rpcUrl: 'http://localhost:8080',
+ *   // apiKey may be required by some operators
+ *   // apiKey: 'your-api-key',
+ *   // hmacSecret may be required by some operators
+ *   // hmacSecret: 'your-hmac-secret'
+ * });
+ *
+ * // Sample usage: Get config
  * const config = await client.getConfig();
  * ```
  */
@@ -12,21 +23,215 @@ export declare class KoraClient {
     private rpcUrl;
     private apiKey?;
     private hmacSecret?;
-    constructor({ rpcUrl, apiKey, hmacSecret }: KoraClientOptions);
+    private getRecaptchaToken?;
+    /**
+     * Creates a new Kora client instance.
+     * @param options - Client configuration options
+     * @param options.rpcUrl - The Kora RPC server URL
+     * @param options.apiKey - Optional API key for authentication
+     * @param options.hmacSecret - Optional HMAC secret for signature-based authentication
+     * @param options.getRecaptchaToken - Optional callback to get reCAPTCHA token for bot protection
+     */
+    constructor({ rpcUrl, apiKey, hmacSecret, getRecaptchaToken }: KoraClientOptions);
     private getHmacSignature;
     private getHeaders;
     private rpcRequest;
+    /**
+     * Retrieves the current Kora server configuration.
+     * @returns The server configuration including fee payer address and validation rules
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     * ```typescript
+     * const config = await client.getConfig();
+     * console.log('Fee payer:', config.fee_payer);
+     * console.log('Validation config:', JSON.stringify(config.validation_config, null, 2));
+     * ```
+     */
     getConfig(): Promise<Config>;
+    /**
+     * Retrieves the payer signer and payment destination from the Kora server.
+     * @returns Object containing the payer signer and payment destination
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     */
     getPayerSigner(): Promise<GetPayerSignerResponse>;
+    /**
+     * Gets the latest blockhash from the Solana RPC that the Kora server is connected to.
+     * @returns Object containing the current blockhash
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     * ```typescript
+     * const { blockhash } = await client.getBlockhash();
+     * console.log('Current blockhash:', blockhash);
+     * ```
+     */
     getBlockhash(): Promise<GetBlockhashResponse>;
+    /**
+     * Gets the version of the Kora server.
+     * @returns Object containing the server version
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     * ```typescript
+     * const { version } = await client.getVersion();
+     * console.log('Server version:', version);
+     * ```
+     */
+    getVersion(): Promise<GetVersionResponse>;
+    /**
+     * Retrieves the list of tokens supported for fee payment.
+     * @returns Object containing an array of supported token mint addresses
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     * ```typescript
+     * const { tokens } = await client.getSupportedTokens();
+     * console.log('Supported tokens:', tokens);
+     * // Output: ['EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', ...]
+     * ```
+     */
     getSupportedTokens(): Promise<GetSupportedTokensResponse>;
+    /**
+     * Estimates the transaction fee in both lamports and the specified token.
+     * @param request - Fee estimation request parameters
+     * @param request.transaction - Base64-encoded transaction to estimate fees for
+     * @param request.fee_token - Mint address of the token to calculate fees in
+     * @returns Fee amounts in both lamports and the specified token
+     * @throws {Error} When the RPC call fails, the transaction is invalid, or the token is not supported
+     *
+     * @example
+     * ```typescript
+     * const fees = await client.estimateTransactionFee({
+     *   transaction: 'base64EncodedTransaction',
+     *   fee_token: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC
+     * });
+     * console.log('Fee in lamports:', fees.fee_in_lamports);
+     * console.log('Fee in USDC:', fees.fee_in_token);
+     * ```
+     */
     estimateTransactionFee(request: EstimateTransactionFeeRequest): Promise<EstimateTransactionFeeResponse>;
+    /**
+     * Estimates the bundle fee in both lamports and the specified token.
+     * @param request - Bundle fee estimation request parameters
+     * @param request.transactions - Array of base64-encoded transactions to estimate fees for
+     * @param request.fee_token - Mint address of the token to calculate fees in
+     * @returns Total fee amounts across all transactions in both lamports and the specified token
+     * @throws {Error} When the RPC call fails, the bundle is invalid, or the token is not supported
+     *
+     * @example
+     * ```typescript
+     * const fees = await client.estimateBundleFee({
+     *   transactions: ['base64EncodedTransaction1', 'base64EncodedTransaction2'],
+     *   fee_token: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC
+     * });
+     * console.log('Total fee in lamports:', fees.fee_in_lamports);
+     * console.log('Total fee in USDC:', fees.fee_in_token);
+     * ```
+     */
+    estimateBundleFee(request: EstimateBundleFeeRequest): Promise<EstimateBundleFeeResponse>;
+    /**
+     * Signs a transaction with the Kora fee payer without broadcasting it.
+     * @param request - Sign request parameters
+     * @param request.transaction - Base64-encoded transaction to sign
+     * @returns Signature and the signed transaction
+     * @throws {Error} When the RPC call fails or transaction validation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.signTransaction({
+     *   transaction: 'base64EncodedTransaction'
+     * });
+     * console.log('Signature:', result.signature);
+     * console.log('Signed tx:', result.signed_transaction);
+     * ```
+     */
     signTransaction(request: SignTransactionRequest): Promise<SignTransactionResponse>;
+    /**
+     * Signs a transaction and immediately broadcasts it to the Solana network.
+     * @param request - Sign and send request parameters
+     * @param request.transaction - Base64-encoded transaction to sign and send
+     * @param request.respond_after - The lifecycle milestone to wait for before
+     * responding (defaults to `'confirmed'`): `'confirmed'` waits for on-chain confirmation,
+     * `'sent'` returns once the RPC node accepts the transaction, `'signed'` returns as soon
+     * as signing completes and broadcasts in the background (broadcast failures are logged
+     * server-side; rebroadcast the returned signed transaction if it never lands)
+     * @returns Signature and the signed transaction
+     * @throws {Error} When the RPC call fails, validation fails, or broadcast fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.signAndSendTransaction({
+     *   transaction: 'base64EncodedTransaction'
+     * });
+     * console.log('Transaction signature:', result.signature);
+     *
+     * // Lowest latency: return as soon as signing completes
+     * const fast = await client.signAndSendTransaction({
+     *   transaction: 'base64EncodedTransaction',
+     *   respond_after: 'signed'
+     * });
+     * ```
+     */
     signAndSendTransaction(request: SignAndSendTransactionRequest): Promise<SignAndSendTransactionResponse>;
-    transferTransaction(request: TransferTransactionRequest): Promise<TransferTransactionResponse>;
     /**
-     * Estimates the fee and builds a payment transfer instruction from the source wallet
-     * to the Kora payment address. The server handles decimal conversion internally.
+     * Signs a bundle of transactions with the Kora fee payer without broadcasting.
+     * @param request - Sign bundle request parameters
+     * @param request.transactions - Array of base64-encoded transactions to sign
+     * @param request.signer_key - Optional signer address for the transactions
+     * @param request.sig_verify - Optional signature verification (defaults to false)
+     * @param request.sign_only_indices - Optional indices of transactions to sign (defaults to all)
+     * @returns Array of signed transactions and signer public key
+     * @throws {Error} When the RPC call fails or validation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.signBundle({
+     *   transactions: ['base64Tx1', 'base64Tx2']
+     * });
+     * console.log('Signed transactions:', result.signed_transactions);
+     * console.log('Signer:', result.signer_pubkey);
+     * ```
+     */
+    signBundle(request: SignBundleRequest): Promise<SignBundleResponse>;
+    /**
+     * Signs a bundle of transactions and sends them to Jito block engine.
+     * @param request - Sign and send bundle request parameters
+     * @param request.transactions - Array of base64-encoded transactions to sign and send
+     * @param request.signer_key - Optional signer address for the transactions
+     * @param request.sig_verify - Optional signature verification (defaults to false)
+     * @param request.sign_only_indices - Optional indices of transactions to sign (defaults to all)
+     * @returns Array of signed transactions, signer public key, and Jito bundle UUID
+     * @throws {Error} When the RPC call fails, validation fails, or Jito submission fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.signAndSendBundle({
+     *   transactions: ['base64Tx1', 'base64Tx2']
+     * });
+     * console.log('Bundle UUID:', result.bundle_uuid);
+     * console.log('Signed transactions:', result.signed_transactions);
+     * ```
+     */
+    signAndSendBundle(request: SignAndSendBundleRequest): Promise<SignAndSendBundleResponse>;
+    /**
+     * Creates a payment instruction to append to a transaction for fee payment to the Kora paymaster.
+     *
+     * This method estimates the required fee and generates a token transfer instruction
+     * from the source wallet to the Kora payment address. The server handles decimal
+     * conversion internally, so the raw token amount is used directly.
+     *
+     * @param request - Payment instruction request parameters
+     * @param request.transaction - Base64-encoded transaction to estimate fees for
+     * @param request.fee_token - Mint address of the token to use for payment
+     * @param request.source_wallet - Public key of the wallet paying the fees
+     * @param request.token_program_id - Optional token program ID (defaults to TOKEN_PROGRAM_ADDRESS)
+     * @param request.signer_key - Optional signer address for the transaction
+     * @param request.sig_verify - Optional signer verification during transaction simulation (defaults to false)
+     * @returns Payment instruction details including the instruction, amount, and addresses
+     * @throws {Error} When the token is not supported, payment is not required, or invalid addresses are provided
      *
      * @example
      * ```typescript

package/dist/src/client.js

@@ -1,13 +1,24 @@
 import { assertIsAddress, isTransactionSigner } from '@solana/kit';
 import { findAssociatedTokenPda, getTransferInstruction, TOKEN_PROGRAM_ADDRESS } from '@solana-program/token';
 import crypto from 'crypto';
-import { getInstructionsFromBase64Message } from './utils/transaction.js';
+import { KoraError } from './error.js';
 /**
  * Kora RPC client for interacting with the Kora paymaster service.
  *
- * @example
+ * Provides methods to estimate fees, sign transactions, and perform gasless transfers
+ * on Solana as specified by the Kora paymaster operator.
+ *
+ * @example Kora Initialization
  * ```typescript
- * const client = new KoraClient({ rpcUrl: 'http://localhost:8080' });
+ * const client = new KoraClient({
+ *   rpcUrl: 'http://localhost:8080',
+ *   // apiKey may be required by some operators
+ *   // apiKey: 'your-api-key',
+ *   // hmacSecret may be required by some operators
+ *   // hmacSecret: 'your-hmac-secret'
+ * });
+ *
+ * // Sample usage: Get config
  * const config = await client.getConfig();
  * ```
  */
@@ -15,10 +26,20 @@ export class KoraClient {
     rpcUrl;
     apiKey;
     hmacSecret;
-    constructor({ rpcUrl, apiKey, hmacSecret }) {
+    getRecaptchaToken;
+    /**
+     * Creates a new Kora client instance.
+     * @param options - Client configuration options
+     * @param options.rpcUrl - The Kora RPC server URL
+     * @param options.apiKey - Optional API key for authentication
+     * @param options.hmacSecret - Optional HMAC secret for signature-based authentication
+     * @param options.getRecaptchaToken - Optional callback to get reCAPTCHA token for bot protection
+     */
+    constructor({ rpcUrl, apiKey, hmacSecret, getRecaptchaToken }) {
         this.rpcUrl = rpcUrl;
         this.apiKey = apiKey;
         this.hmacSecret = hmacSecret;
+        this.getRecaptchaToken = getRecaptchaToken;
     }
     getHmacSignature({ timestamp, body }) {
         if (!this.hmacSecret) {
@@ -27,7 +48,7 @@ export class KoraClient {
         const message = timestamp + body;
         return crypto.createHmac('sha256', this.hmacSecret).update(message).digest('hex');
     }
-    getHeaders({ body }) {
+    async getHeaders({ body }) {
         const headers = {};
         if (this.apiKey) {
             headers['x-api-key'] = this.apiKey;
@@ -38,6 +59,10 @@ export class KoraClient {
             headers['x-timestamp'] = timestamp;
             headers['x-hmac-signature'] = signature;
         }
+        if (this.getRecaptchaToken) {
+            const token = await Promise.resolve(this.getRecaptchaToken());
+            headers['x-recaptcha-token'] = token;
+        }
         return headers;
     }
     async rpcRequest(method, params) {
@@ -47,7 +72,7 @@ export class KoraClient {
             method,
             params,
         });
-        const headers = this.getHeaders({ body });
+        const headers = await this.getHeaders({ body });
         const response = await fetch(this.rpcUrl, {
             body,
             headers: { ...headers, 'Content-Type': 'application/json' },
@@ -55,40 +80,229 @@ export class KoraClient {
         });
         const json = (await response.json());
         if (json.error) {
-            const error = json.error;
-            throw new Error(`RPC Error ${error.code}: ${error.message}`);
+            const { code, message, data } = json.error;
+            throw new KoraError(code, message, data);
         }
         return json.result;
     }
+    /**
+     * Retrieves the current Kora server configuration.
+     * @returns The server configuration including fee payer address and validation rules
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     * ```typescript
+     * const config = await client.getConfig();
+     * console.log('Fee payer:', config.fee_payer);
+     * console.log('Validation config:', JSON.stringify(config.validation_config, null, 2));
+     * ```
+     */
     async getConfig() {
         return await this.rpcRequest('getConfig', undefined);
     }
+    /**
+     * Retrieves the payer signer and payment destination from the Kora server.
+     * @returns Object containing the payer signer and payment destination
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     */
     async getPayerSigner() {
         return await this.rpcRequest('getPayerSigner', undefined);
     }
+    /**
+     * Gets the latest blockhash from the Solana RPC that the Kora server is connected to.
+     * @returns Object containing the current blockhash
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     * ```typescript
+     * const { blockhash } = await client.getBlockhash();
+     * console.log('Current blockhash:', blockhash);
+     * ```
+     */
     async getBlockhash() {
         return await this.rpcRequest('getBlockhash', undefined);
     }
+    /**
+     * Gets the version of the Kora server.
+     * @returns Object containing the server version
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     * ```typescript
+     * const { version } = await client.getVersion();
+     * console.log('Server version:', version);
+     * ```
+     */
+    async getVersion() {
+        return await this.rpcRequest('getVersion', undefined);
+    }
+    /**
+     * Retrieves the list of tokens supported for fee payment.
+     * @returns Object containing an array of supported token mint addresses
+     * @throws {Error} When the RPC call fails
+     *
+     * @example
+     * ```typescript
+     * const { tokens } = await client.getSupportedTokens();
+     * console.log('Supported tokens:', tokens);
+     * // Output: ['EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', ...]
+     * ```
+     */
     async getSupportedTokens() {
         return await this.rpcRequest('getSupportedTokens', undefined);
     }
+    /**
+     * Estimates the transaction fee in both lamports and the specified token.
+     * @param request - Fee estimation request parameters
+     * @param request.transaction - Base64-encoded transaction to estimate fees for
+     * @param request.fee_token - Mint address of the token to calculate fees in
+     * @returns Fee amounts in both lamports and the specified token
+     * @throws {Error} When the RPC call fails, the transaction is invalid, or the token is not supported
+     *
+     * @example
+     * ```typescript
+     * const fees = await client.estimateTransactionFee({
+     *   transaction: 'base64EncodedTransaction',
+     *   fee_token: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC
+     * });
+     * console.log('Fee in lamports:', fees.fee_in_lamports);
+     * console.log('Fee in USDC:', fees.fee_in_token);
+     * ```
+     */
     async estimateTransactionFee(request) {
         return await this.rpcRequest('estimateTransactionFee', request);
     }
+    /**
+     * Estimates the bundle fee in both lamports and the specified token.
+     * @param request - Bundle fee estimation request parameters
+     * @param request.transactions - Array of base64-encoded transactions to estimate fees for
+     * @param request.fee_token - Mint address of the token to calculate fees in
+     * @returns Total fee amounts across all transactions in both lamports and the specified token
+     * @throws {Error} When the RPC call fails, the bundle is invalid, or the token is not supported
+     *
+     * @example
+     * ```typescript
+     * const fees = await client.estimateBundleFee({
+     *   transactions: ['base64EncodedTransaction1', 'base64EncodedTransaction2'],
+     *   fee_token: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC
+     * });
+     * console.log('Total fee in lamports:', fees.fee_in_lamports);
+     * console.log('Total fee in USDC:', fees.fee_in_token);
+     * ```
+     */
+    async estimateBundleFee(request) {
+        return await this.rpcRequest('estimateBundleFee', request);
+    }
+    /**
+     * Signs a transaction with the Kora fee payer without broadcasting it.
+     * @param request - Sign request parameters
+     * @param request.transaction - Base64-encoded transaction to sign
+     * @returns Signature and the signed transaction
+     * @throws {Error} When the RPC call fails or transaction validation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.signTransaction({
+     *   transaction: 'base64EncodedTransaction'
+     * });
+     * console.log('Signature:', result.signature);
+     * console.log('Signed tx:', result.signed_transaction);
+     * ```
+     */
     async signTransaction(request) {
         return await this.rpcRequest('signTransaction', request);
     }
+    /**
+     * Signs a transaction and immediately broadcasts it to the Solana network.
+     * @param request - Sign and send request parameters
+     * @param request.transaction - Base64-encoded transaction to sign and send
+     * @param request.respond_after - The lifecycle milestone to wait for before
+     * responding (defaults to `'confirmed'`): `'confirmed'` waits for on-chain confirmation,
+     * `'sent'` returns once the RPC node accepts the transaction, `'signed'` returns as soon
+     * as signing completes and broadcasts in the background (broadcast failures are logged
+     * server-side; rebroadcast the returned signed transaction if it never lands)
+     * @returns Signature and the signed transaction
+     * @throws {Error} When the RPC call fails, validation fails, or broadcast fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.signAndSendTransaction({
+     *   transaction: 'base64EncodedTransaction'
+     * });
+     * console.log('Transaction signature:', result.signature);
+     *
+     * // Lowest latency: return as soon as signing completes
+     * const fast = await client.signAndSendTransaction({
+     *   transaction: 'base64EncodedTransaction',
+     *   respond_after: 'signed'
+     * });
+     * ```
+     */
     async signAndSendTransaction(request) {
         return await this.rpcRequest('signAndSendTransaction', request);
     }
-    async transferTransaction(request) {
-        const response = await this.rpcRequest('transferTransaction', request);
-        response.instructions = getInstructionsFromBase64Message(response.message || '');
-        return response;
+    /**
+     * Signs a bundle of transactions with the Kora fee payer without broadcasting.
+     * @param request - Sign bundle request parameters
+     * @param request.transactions - Array of base64-encoded transactions to sign
+     * @param request.signer_key - Optional signer address for the transactions
+     * @param request.sig_verify - Optional signature verification (defaults to false)
+     * @param request.sign_only_indices - Optional indices of transactions to sign (defaults to all)
+     * @returns Array of signed transactions and signer public key
+     * @throws {Error} When the RPC call fails or validation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.signBundle({
+     *   transactions: ['base64Tx1', 'base64Tx2']
+     * });
+     * console.log('Signed transactions:', result.signed_transactions);
+     * console.log('Signer:', result.signer_pubkey);
+     * ```
+     */
+    async signBundle(request) {
+        return await this.rpcRequest('signBundle', request);
     }
     /**
-     * Estimates the fee and builds a payment transfer instruction from the source wallet
-     * to the Kora payment address. The server handles decimal conversion internally.
+     * Signs a bundle of transactions and sends them to Jito block engine.
+     * @param request - Sign and send bundle request parameters
+     * @param request.transactions - Array of base64-encoded transactions to sign and send
+     * @param request.signer_key - Optional signer address for the transactions
+     * @param request.sig_verify - Optional signature verification (defaults to false)
+     * @param request.sign_only_indices - Optional indices of transactions to sign (defaults to all)
+     * @returns Array of signed transactions, signer public key, and Jito bundle UUID
+     * @throws {Error} When the RPC call fails, validation fails, or Jito submission fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.signAndSendBundle({
+     *   transactions: ['base64Tx1', 'base64Tx2']
+     * });
+     * console.log('Bundle UUID:', result.bundle_uuid);
+     * console.log('Signed transactions:', result.signed_transactions);
+     * ```
+     */
+    async signAndSendBundle(request) {
+        return await this.rpcRequest('signAndSendBundle', request);
+    }
+    /**
+     * Creates a payment instruction to append to a transaction for fee payment to the Kora paymaster.
+     *
+     * This method estimates the required fee and generates a token transfer instruction
+     * from the source wallet to the Kora payment address. The server handles decimal
+     * conversion internally, so the raw token amount is used directly.
+     *
+     * @param request - Payment instruction request parameters
+     * @param request.transaction - Base64-encoded transaction to estimate fees for
+     * @param request.fee_token - Mint address of the token to use for payment
+     * @param request.source_wallet - Public key of the wallet paying the fees
+     * @param request.token_program_id - Optional token program ID (defaults to TOKEN_PROGRAM_ADDRESS)
+     * @param request.signer_key - Optional signer address for the transaction
+     * @param request.sig_verify - Optional signer verification during transaction simulation (defaults to false)
+     * @returns Payment instruction details including the instruction, amount, and addresses
+     * @throws {Error} When the token is not supported, payment is not required, or invalid addresses are provided
      *
      * @example
      * ```typescript
@@ -101,8 +315,8 @@ export class KoraClient {
      * ```
      */
     async getPaymentInstruction({ transaction, fee_token, source_wallet, token_program_id = TOKEN_PROGRAM_ADDRESS, signer_key, sig_verify, }) {
-        const sourceIsSigner = typeof source_wallet !== 'string' && isTransactionSigner(source_wallet);
-        const walletAddress = sourceIsSigner ? source_wallet.address : source_wallet;
+        const isSigner = typeof source_wallet !== 'string' && isTransactionSigner(source_wallet);
+        const walletAddress = isSigner ? source_wallet.address : source_wallet;
         assertIsAddress(walletAddress);
         assertIsAddress(fee_token);
         assertIsAddress(token_program_id);
@@ -123,9 +337,12 @@ export class KoraClient {
             owner: payment_address,
             tokenProgram: token_program_id,
         });
+        if (fee_in_token === undefined) {
+            throw new Error('Fee token was specified but fee_in_token was not returned from server');
+        }
         const paymentInstruction = getTransferInstruction({
             amount: fee_in_token,
-            authority: sourceIsSigner ? source_wallet : walletAddress,
+            authority: isSigner ? source_wallet : walletAddress,
             destination: destinationTokenAccount,
             source: sourceTokenAccount,
         });

package/dist/src/error.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Stable numeric error codes for RPC responses following JSON-RPC 2.0 spec (-32000 to -32099 for server errors).
+ */
+export declare enum KoraErrorCode {
+    InvalidTransaction = -32000,
+    ValidationError = -32001,
+    UnsupportedFeeToken = -32002,
+    InsufficientFunds = -32003,
+    InvalidRequest = -32004,
+    FeeEstimationFailed = -32005,
+    TransactionExecutionFailed = -32006,
+    SigningError = -32020,
+    RateLimitExceeded = -32030,
+    UsageLimitExceeded = -32031,
+    Unauthorized = -32032,
+    SwapError = -32040,
+    TokenOperationError = -32041,
+    AccountNotFound = -32050,
+    JitoError = -32060,
+    RecaptchaError = -32061,
+    InternalServerError = -32090,
+    ConfigError = -32091,
+    SerializationError = -32092,
+    RpcError = -32093
+}
+/**
+ * Structured data returned in the JSON-RPC error object's `data` field.
+ */
+export interface KoraErrorData {
+    error_type: string;
+}
+/**
+ * Represents a structured error returned by the Kora paymaster service.
+ */
+export declare class KoraError extends Error {
+    /** The stable numeric error code */
+    readonly code: KoraErrorCode;
+    /** Optional structured data about the error */
+    readonly data?: KoraErrorData;
+    constructor(code?: number, message?: string, data?: KoraErrorData);
+}