@tuwaio/quasar-sdk 0.0.3 → 0.0.5

package/README.md

@@ -4,21 +4,28 @@
 [![License](https://img.shields.io/npm/l/@tuwaio/quasar-sdk.svg)](./LICENSE)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/TuwaIO/sdk/release.yml?branch=main)](https://github.com/TuwaIO/sdk/actions)
 
-> The official server-side Node.js & Edge SDK for the **TUWA Quasar Cloud**.
+> The official server-side Node.js & Edge SDK for the **TUWA Quasar Cloud**, featuring built-in React authentication bridges.
 
 ## Installation
 
 ```bash
-# Using pnpm (recommended), but you can use npm, yarn or bun as well
+# Using pnpm (recommended)
 pnpm add @tuwaio/quasar-sdk ofetch
 ```
 
 ### Peer Dependencies
 
-| Package               | Version   |
-| --------------------- | --------- |
-| `@tuwaio/pulsar-core` | `>=0.6.0` |
-| `ofetch`              | `>=1.5.1` |
+| Package                    | Version    | Requirement                                |
+| -------------------------- | ---------- | ------------------------------------------ |
+| `@tuwaio/pulsar-core`      | `>=0.6.0`  | **Required** (Core types)                  |
+| `ofetch`                   | `>=1.5.1`  | **Required** (Transport)                   |
+| `react`                    | `>=18.0.0` | Optional (React Bridge support)            |
+| `@solana/react`            | `>=6.9.0`  | Optional (Solana signing)                  |
+| `@wallet-standard/react`   | `>=1.0.2`  | Optional (Wallet Standard)                 |
+| `@wagmi/core`              | `>=3.0.0`  | Optional (EVM signing)                     |
+| `viem`                     | `^2.0.0`   | Optional (EVM Auth primitives)             |
+| `gill`                     | `^0.14.0`  | Optional (Solana Auth primitives)          |
+| `zustand`                  | `^5.0.0`   | Optional (Session state management)        |
 
 ## Quick Start
 
@@ -27,25 +34,65 @@ import { Quasar } from '@tuwaio/quasar-sdk';
 
 const quasar = new Quasar({ secretKey: 'sk_live_your_secret_key' });
 
-// Sync a pending transaction
-const { txKey } = await quasar.pulsar.syncCreate(tx, 'My Application');
+// Sync a pending transaction to the cloud
+const { txKey } = await quasar.pulsar.syncCreate(transaction, 'My Application');
 
-// Update status
-await quasar.pulsar.syncUpdate(txKey, { status: 'confirmed' });
-
-// Query history
+// Query transaction history
 const history = await quasar.pulsar.getHistory({ chainId: 1 });
 ```
 
+## React Authentication Bridge
+
+The SDK provides a unified component to handle multi-chain authentication (EVM & Solana) with zero boilerplate.
+
+```tsx
+import { QuasarAuthBridge } from '@tuwaio/quasar-sdk/react';
+
+function MyApp() {
+  return (
+    <QuasarAuthBridge
+      activeConnection={activeConnection} // Structural interface for wallet state
+      store={store}                      // Zustand store API
+      wagmiConfig={config}               // Wagmi config
+      session={miniSession}              // Current session state
+      setSession={setMiniSession}        // Session setter
+    />
+  );
+}
+```
+
 ## Modules
 
 ### Pulsar — `quasar.pulsar`
 
-| Method                       | Description                                       |
-| ---------------------------- | ------------------------------------------------- |
-| `syncCreate(tx, appName?)`   | Sync a new pending transaction to the cloud       |
-| `syncUpdate(txKey, patches)` | Update an existing transaction's status or fields |
-| `getHistory(query?)`         | Retrieve paginated transaction history            |
+| Method                     | Description                                         |
+| -------------------------- | --------------------------------------------------- |
+| `syncCreate(tx, appName?)` | Sync a new pending transaction to the cloud         |
+| `getHistory(query?)`       | Retrieve paginated transaction history with filters |
+
+### Utils — `utils`
+
+Security and authentication utilities for signature verification and session management.
+
+```typescript
+import { utils, ChainType } from '@tuwaio/quasar-sdk';
+
+// Verify a Mini-Session signature on the server
+const isValid = await utils.verifyMiniSession({
+  walletAddress: '0x...',
+  signature,
+  timestamp,
+  chainType: ChainType.EVM
+});
+```
+
+| Method                         | Description                                            |
+| ------------------------------ | ------------------------------------------------------ |
+| `createMiniSessionMessage(ts)` | Format a standard login message for signing            |
+| `signMiniSession(params)`      | Trigger signature request in the connected wallet      |
+| `verifyMiniSession(params)`    | Verify an EVM or Solana signature with expiration check |
+| `createMiniSessionStore(name)` | Create a persistent Zustand store for session caching  |
+| `getMiniSessionAuth(conn, st)` | Core logic for signing and caching a mini-session      |
 
 ## Error Handling
 
@@ -58,7 +105,6 @@ try {
   if (err instanceof QuasarSDKError) {
     console.error(err.status); // HTTP status code
     console.error(err.message); // Formatted error message
-    console.error(err.originalError); // Raw fetch error
   }
 }
 ```

package/dist/chunk-A52BVTJ6.js

@@ -0,0 +1 @@
+'use strict';var zustand=require('zustand'),middleware=require('zustand/middleware');var d=(a=>(a.EVM="EVM",a.SOLANA="SOLANA",a))(d||{});var S=300*1e3,f=60*1e3;function m(e){return `Mini-Session Login: ${e}`}async function y(e){let t=new Date().toISOString(),a=m(t);if(e.chainType==="EVM"){let n=e.signer;try{return {signature:await n.signMessage({account:e.walletAddress,message:a}),timestamp:t}}catch(s){throw new Error(`[SDK] EVM signing failed: ${s.message}`,{cause:s})}}if(e.chainType==="SOLANA"){let n=e.signer,s;try{s=await import('gill');}catch(r){throw new Error('[SDK] Peer dependency "gill" is required for Solana signing.',{cause:r})}try{let i=s.getUtf8Encoder().encode(a),g;if(n.modifyAndSignMessages){let o=s.createSignableMessage(i),[l]=await n.modifyAndSignMessages([o]),u=l.signatures[n.address];if(!u)throw new Error(`[SDK] Signature missing for address: ${n.address}`);g=u;}else if(n.signMessages){let[o]=await n.signMessages([i]);if(!o?.signature)throw new Error("[SDK] Wallet returned invalid signMessages output.");g=o.signature;}else if(n.signMessage)g=await n.signMessage(i);else throw new Error("[SDK] Signer lacks message signing capabilities.");return {signature:s.getSignatureFromBytes(g),timestamp:t}}catch(r){throw new Error(`[SDK] Solana signing failed: ${r.message}`,{cause:r})}}throw new Error(`[SDK] Unsupported chain type: ${e.chainType}`)}async function P(e){let t=new Date(e.timestamp).getTime(),a=Date.now();if(isNaN(t))throw new Error("[SDK] Invalid timestamp format. Use ISO string.");let n=e.maxAge??S;if(a-t>n)throw new Error("[SDK] Signature expired. Please sign a fresh message.");if(t>a+f)throw new Error("[SDK] Timestamp is in the future. Check your system clock.");let s=m(e.timestamp);if(e.chainType==="EVM"){let r;try{r=await import('viem');}catch(i){throw new Error('[SDK] Peer dependency "viem" is required for EVM verification.',{cause:i})}return await r.verifyMessage({address:e.walletAddress,message:s,signature:e.signature})}if(e.chainType==="SOLANA"){let r;try{r=await import('gill');}catch(i){throw new Error('[SDK] Peer dependency "gill" is required for Solana verification.',{cause:i})}try{let i=r.address(e.walletAddress);return await r.verifySignatureForAddress(i,e.signature,s)}catch{return  false}}return  false}function k(e="mini-session-storage"){return zustand.create()(middleware.persist(t=>({miniSession:null,setMiniSession:a=>t({miniSession:a}),clearSession:()=>t({miniSession:null})}),{name:e}))}async function C(e,t){let{isConnected:a,address:n,chainType:s,signer:r}=e;if(!a||!n)throw new Error("[SDK] Wallet not connected. Please connect your wallet first.");let i=t.miniSession;if(i&&i.walletAddress===n&&i.chainType===s){let o=Date.now(),l=new Date(i.timestamp).getTime();if(o-l<S)return i}let c={...await y({signer:r,walletAddress:n,chainType:s}),chainType:s,walletAddress:n};return t.setMiniSession(c),c}exports.a=d;exports.b=S;exports.c=m;exports.d=y;exports.e=P;exports.f=k;exports.g=C;

package/dist/chunk-DK4D3PU5.mjs

@@ -0,0 +1 @@
+import {create}from'zustand';import {persist}from'zustand/middleware';var d=(a=>(a.EVM="EVM",a.SOLANA="SOLANA",a))(d||{});var S=300*1e3,f=60*1e3;function m(e){return `Mini-Session Login: ${e}`}async function y(e){let t=new Date().toISOString(),a=m(t);if(e.chainType==="EVM"){let n=e.signer;try{return {signature:await n.signMessage({account:e.walletAddress,message:a}),timestamp:t}}catch(s){throw new Error(`[SDK] EVM signing failed: ${s.message}`,{cause:s})}}if(e.chainType==="SOLANA"){let n=e.signer,s;try{s=await import('gill');}catch(r){throw new Error('[SDK] Peer dependency "gill" is required for Solana signing.',{cause:r})}try{let i=s.getUtf8Encoder().encode(a),g;if(n.modifyAndSignMessages){let o=s.createSignableMessage(i),[l]=await n.modifyAndSignMessages([o]),u=l.signatures[n.address];if(!u)throw new Error(`[SDK] Signature missing for address: ${n.address}`);g=u;}else if(n.signMessages){let[o]=await n.signMessages([i]);if(!o?.signature)throw new Error("[SDK] Wallet returned invalid signMessages output.");g=o.signature;}else if(n.signMessage)g=await n.signMessage(i);else throw new Error("[SDK] Signer lacks message signing capabilities.");return {signature:s.getSignatureFromBytes(g),timestamp:t}}catch(r){throw new Error(`[SDK] Solana signing failed: ${r.message}`,{cause:r})}}throw new Error(`[SDK] Unsupported chain type: ${e.chainType}`)}async function P(e){let t=new Date(e.timestamp).getTime(),a=Date.now();if(isNaN(t))throw new Error("[SDK] Invalid timestamp format. Use ISO string.");let n=e.maxAge??S;if(a-t>n)throw new Error("[SDK] Signature expired. Please sign a fresh message.");if(t>a+f)throw new Error("[SDK] Timestamp is in the future. Check your system clock.");let s=m(e.timestamp);if(e.chainType==="EVM"){let r;try{r=await import('viem');}catch(i){throw new Error('[SDK] Peer dependency "viem" is required for EVM verification.',{cause:i})}return await r.verifyMessage({address:e.walletAddress,message:s,signature:e.signature})}if(e.chainType==="SOLANA"){let r;try{r=await import('gill');}catch(i){throw new Error('[SDK] Peer dependency "gill" is required for Solana verification.',{cause:i})}try{let i=r.address(e.walletAddress);return await r.verifySignatureForAddress(i,e.signature,s)}catch{return  false}}return  false}function k(e="mini-session-storage"){return create()(persist(t=>({miniSession:null,setMiniSession:a=>t({miniSession:a}),clearSession:()=>t({miniSession:null})}),{name:e}))}async function C(e,t){let{isConnected:a,address:n,chainType:s,signer:r}=e;if(!a||!n)throw new Error("[SDK] Wallet not connected. Please connect your wallet first.");let i=t.miniSession;if(i&&i.walletAddress===n&&i.chainType===s){let o=Date.now(),l=new Date(i.timestamp).getTime();if(o-l<S)return i}let c={...await y({signer:r,walletAddress:n,chainType:s}),chainType:s,walletAddress:n};return t.setMiniSession(c),c}export{d as a,S as b,m as c,y as d,P as e,k as f,C as g};

package/dist/index.d.mts

@@ -1,133 +1,10 @@
 import { FetchOptions } from 'ofetch';
+import { Q as QuasarConfig, H as HistoryQuery, P as PaginatedResult, V as VerifySessionParams, S as SignSessionParams, a as SignSessionResult, M as MiniSessionStore, C as ConnectionData, b as MiniSessionAuth } from './types-Ctaain6g.mjs';
+export { c as ChainType, E as EvmSigner, d as SolanaSignedMessage, e as SolanaSigner } from './types-Ctaain6g.mjs';
 import { Transaction } from '@tuwaio/pulsar-core';
 export { Transaction, UpdatableTransactionFields } from '@tuwaio/pulsar-core';
-
-/**
- * @module types
- * @description Shared type definitions for the Quasar SDK.
- * Contains configuration interfaces, query parameters, paginated result structure,
- * and re-exports from `@tuwaio/pulsar-core`.
- */
-
-/**
- * Configuration options for initializing the {@link Quasar} SDK client.
- *
- * @example
- * ```typescript
- * const config: QuasarConfig = {
- *   secretKey: 'sk_live_abc123...',
- *   internalSecret: 'int_secret_abc123...',
- *   baseUrl: 'https://api.tuwa.io',
- *   timeout: 15000,
- * };
- * ```
- */
-interface QuasarConfig {
-    /**
-     * Your secret API key starting with `sk_live_`.
-     *
-     * @remarks
-     * This key authenticates every request through the Iron Dome security perimeter.
-     * It **MUST** be kept secure on the server side — never expose it in client bundles.
-     */
-    secretKey: string;
-    /**
-     * Optional internal secret sent as `x-internal-secret` header on every request.
-     *
-     * @remarks
-     * If provided, the SDK automatically includes it in outgoing requests.
-     * If omitted, the header is not added.
-     */
-    internalSecret?: string;
-    /**
-     * The base URL of the Quasar Cloud API.
-     *
-     * @defaultValue `'https://api.tuwa.io'`
-     */
-    baseUrl?: string;
-    /**
-     * Request timeout in milliseconds.
-     *
-     * @defaultValue `10000`
-     */
-    timeout?: number;
-}
-/**
- * Query parameters for filtering transaction history.
- *
- * All fields are optional — omitted fields apply no filter.
- *
- * @example
- * ```typescript
- * const query: HistoryQuery = {
- *   page: 2,
- *   limit: 25,
- *   chainId: 1,
- *   status: 'confirmed',
- * };
- * ```
- */
-interface HistoryQuery {
-    /**
-     * Page number for pagination (1-indexed).
-     *
-     * @defaultValue `1`
-     */
-    page?: number;
-    /**
-     * Maximum number of results per page.
-     *
-     * @defaultValue `10`
-     */
-    limit?: number;
-    /**
-     * Filter by blockchain chain ID (e.g. `1` for Ethereum Mainnet, `'solana'` for Solana).
-     */
-    chainId?: string | number;
-    /**
-     * Filter by transaction status (e.g. `'pending'`, `'confirmed'`, `'failed'`).
-     */
-    status?: string;
-    /**
-     * Filter by a specific transaction key (unique identifier assigned by Quasar).
-     */
-    txKey?: string;
-    /**
-     * Filter by a specific app name.
-     */
-    appName?: string;
-    /**
-     * Filter by a specific wallet address.
-     */
-    walletAddress?: string;
-}
-/**
- * Generic wrapper for paginated API responses.
- *
- * @typeParam T - The type of each document in the result set.
- *
- * @example
- * ```typescript
- * const result: PaginatedResult<Transaction> = await quasar.pulsar.getHistory();
- * console.log(result.docs);       // Transaction[]
- * console.log(result.totalPages);  // number
- * console.log(result.hasNextPage); // boolean
- * ```
- */
-interface PaginatedResult<T> {
-    /** Array of documents for the current page. */
-    docs: T[];
-    /** Total number of documents matching the query across all pages. */
-    totalDocs: number;
-    /** Total number of available pages. */
-    totalPages: number;
-    /** Current page number (1-indexed). */
-    page: number;
-    /** Whether a subsequent page exists. */
-    hasNextPage: boolean;
-    /** Whether a previous page exists. */
-    hasPrevPage: boolean;
-}
+import * as zustand_middleware from 'zustand/middleware';
+import * as zustand from 'zustand';
 
 /**
  * @module core/client
@@ -235,25 +112,26 @@ declare class QuasarClient {
 /**
  * Pulsar module — the transaction engine interface for Quasar Cloud.
  *
- * Handles all operations related to blockchain transaction lifecycle:
- * creating, updating, and querying transactions through the API.
+ * The `PulsarModule` handles the lifecycle of blockchain transactions within the Quasar ecosystem.
+ * It allows developers to sync transaction states (EVM, Solana, Starknet) to the cloud for
+ * persistent tracking and to retrieve comprehensive transaction histories.
  *
  * @remarks
- * Access this module via `quasar.pulsar` after initializing the SDK.
- * All methods authenticate automatically using the configured secret key.
+ * Access this module via `quasar.pulsar` after initializing the {@link Quasar} SDK.
+ * All methods are authenticated automatically using the configured secret key.
  *
  * @example
  * ```typescript
  * const quasar = new Quasar({ secretKey: 'sk_live_...' });
  *
- * // Create
+ * // Sync a new transaction to start tracking
  * const { txKey } = await quasar.pulsar.syncCreate(transaction);
  *
- * // Update
- * await quasar.pulsar.syncUpdate(txKey, { status: 'confirmed' });
- *
- * // Read
- * const history = await quasar.pulsar.getHistory({ chainId: 1 });
+ * // Retrieve transaction history with filters
+ * const history = await quasar.pulsar.getHistory({
+ *   chainId: 1,
+ *   status: 'Success',
+ * });
  * ```
  */
 declare class PulsarModule {
@@ -266,25 +144,28 @@ declare class PulsarModule {
      */
     constructor(client: QuasarClient);
     /**
-     * Syncs a newly created pending transaction to the Quasar Cloud.
+     * Syncs a newly created or pending transaction to the Quasar Cloud.
      *
-     * Sends the full transaction object to the `tx-sync` endpoint via POST.
-     * The server assigns a unique `txKey` that can be used for subsequent updates.
+     * This method sends the full transaction object to the Pulsar sync engine.
+     * Once synced, the transaction is indexed and tracked through the Iron Dome infrastructure.
      *
-     * @param tx - The complete transaction object to sync.
-     * @param appName - The application name for filtering by.
-     * @returns An object containing `success: true` and the assigned `txKey`.
-     * @throws {QuasarSDKError} On authentication failure, validation error, or network issue.
+     * @param tx - The complete transaction object to sync. Must conform to the {@link Transaction} type.
+     * @param appName - Optional application name to associate with this transaction for filtering purposes.
+     * @returns A promise that resolves to an object containing the assigned `txKey`.
+     * @throws {QuasarSDKError} If the request fails due to authentication, validation, or network issues.
      *
      * @example
      * ```typescript
-     * const { txKey } = await quasar.pulsar.syncCreate({
+     * const result = await quasar.pulsar.syncCreate({
      *   hash: '0xabc...',
      *   chainId: 1,
      *   status: 'pending',
      *   from: '0x123...',
      *   to: '0x456...',
-     * });
+     *   // ... other transaction fields
+     * }, 'My Dashboard');
+     *
+     * console.log(result.txKey); // The unique key for this transaction
      * ```
      */
     syncCreate(tx: Transaction, appName?: string): Promise<{
@@ -292,32 +173,122 @@ declare class PulsarModule {
         txKey: string;
     }>;
     /**
-     * Retrieves paginated transaction history from the Quasar Cloud.
+     * Retrieves a paginated list of transactions from the Quasar Cloud.
      *
-     * Supports filtering by chain ID, status, and specific transaction key.
-     * Returns a typed {@link PaginatedResult} with navigation metadata.
+     * Supports advanced filtering by chain, status, wallet address, and more.
+     * Results are returned in a typed {@link PaginatedResult} wrapper.
      *
-     * @param query - Optional query parameters for filtering and pagination.
-     * @returns A paginated result containing an array of {@link Transaction} documents.
-     * @throws {QuasarSDKError} On authentication failure or network issue.
+     * @param query - Optional query parameters for filtering and pagination. See {@link HistoryQuery}.
+     * @returns A promise that resolves to a {@link PaginatedResult} containing an array of {@link Transaction} documents.
+     * @throws {QuasarSDKError} If the request fails (e.g., 401 Unauthorized, 404 Not Found).
      *
      * @example
      * ```typescript
      * const result = await quasar.pulsar.getHistory({
      *   page: 1,
      *   limit: 20,
-     *   chainId: 1,
-     *   status: 'confirmed',
+     *   walletAddress: '6x...',
      * });
      *
-     * for (const tx of result.docs) {
-     *   console.log(tx.hash, tx.status);
-     * }
+     * result.docs.forEach(tx => console.log(tx.txKey, tx.status));
      * ```
      */
     getHistory(query?: HistoryQuery): Promise<PaginatedResult<Transaction>>;
 }
 
+/**
+ * @module utils/auth
+ * @description Security utilities for Mini-Session signature creation and verification.
+ * Supports dual-ecosystem (EVM & Solana) authentication flows with strict type safety.
+ */
+
+/**
+ * Default maximum allowed age for a signature (5 minutes).
+ * Prevents replay attacks using stale signatures.
+ * @internal
+ */
+declare const DEFAULT_MAX_AGE: number;
+/**
+ * Standardizes the message format for Mini-Session authentication.
+ * Both frontend and backend MUST use this exact template for verification to pass.
+ *
+ * @param timestamp - ISO string timestamp (e.g., `new Date().toISOString()`).
+ * @returns The formatted message string to be signed.
+ *
+ * @example
+ * ```typescript
+ * const msg = createMiniSessionMessage(new Date().toISOString());
+ * // msg -> "Mini-Session Login: 2026-05-13T10:00:00.000Z"
+ * ```
+ */
+declare function createMiniSessionMessage(timestamp: string): string;
+/**
+ * Triggers a signature request in the connected wallet to create a Mini-Session.
+ *
+ * This function detects the signer's capabilities and uses the most appropriate
+ * signing method available (e.g., Web3 v2, Standard, or Legacy).
+ *
+ * @param params - Parameters containing the signer and target ecosystem.
+ * @returns A promise resolving to the signature and timestamp.
+ * @throws {Error} If signing fails or the signer lacks required methods.
+ *
+ * @public
+ */
+declare function signMiniSession(params: SignSessionParams): Promise<SignSessionResult>;
+/**
+ * Verifies a Mini-Session signature for authenticity and freshness.
+ *
+ * Performs cryptographic verification against the provided wallet address and
+ * ensures the signature hasn't expired according to the `maxAge` parameter.
+ *
+ * @param params - Verification data including signature and timestamp.
+ * @returns A promise resolving to true if the session is valid.
+ *
+ * @public
+ */
+declare function verifyMiniSession(params: VerifySessionParams): Promise<boolean>;
+
+/**
+ * Creates a persistent Zustand store to cache Mini-Session signatures.
+ * This is the recommended way to manage sessions in React applications.
+ *
+ * @param storageName - The localStorage key for persistence. Defaults to 'mini-session-storage'.
+ * @returns A Zustand store instance initialized with MiniSessionStore interface.
+ *
+ * @public
+ */
+declare function createMiniSessionStore(storageName?: string): zustand.UseBoundStore<Omit<zustand.StoreApi<MiniSessionStore>, "setState" | "persist"> & {
+    setState(partial: MiniSessionStore | Partial<MiniSessionStore> | ((state: MiniSessionStore) => MiniSessionStore | Partial<MiniSessionStore>), replace?: false | undefined): unknown;
+    setState(state: MiniSessionStore | ((state: MiniSessionStore) => MiniSessionStore), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<zustand_middleware.PersistOptions<MiniSessionStore, MiniSessionStore, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: MiniSessionStore) => void) => () => void;
+        onFinishHydration: (fn: (state: MiniSessionStore) => void) => () => void;
+        getOptions: () => Partial<zustand_middleware.PersistOptions<MiniSessionStore, MiniSessionStore, unknown>>;
+    };
+}>;
+/**
+ * High-level orchestrator to retrieve an existing Mini-Session or trigger a new signature.
+ *
+ * This function checks the provided store for a valid, non-expired session matching
+ * the current wallet connection. If no session is found or it has expired, it
+ * triggers a signature request through the wallet.
+ *
+ * @param connection - The current active wallet connection data (address, signer, etc).
+ * @param store - A store implementation (Zustand or compatible) for session persistence.
+ * @returns A promise resolving to a valid MiniSessionAuth object.
+ * @throws {Error} If the wallet is disconnected or signing fails.
+ *
+ * @public
+ */
+declare function getMiniSessionAuth(connection: ConnectionData, store: {
+    miniSession: MiniSessionAuth | null;
+    setMiniSession: (session: MiniSessionAuth | null) => void;
+}): Promise<MiniSessionAuth>;
+
 declare const BASE_API_URL = "https://api.tuwa.io";
 declare const PULSAR_SYNC_ENDPOINT = "/v1/engine/pulsar/sync";
 declare const PULSAR_HISTORY_ENDPOINT = "/v1/engine/pulsar/history";
@@ -341,45 +312,123 @@ declare const PULSAR_HISTORY_ENDPOINT = "/v1/engine/pulsar/history";
  * @packageDocumentation
  */
 
+/**
+ * Security and authentication utilities.
+ *
+ * Includes methods for creating, signing, and verifying Mini-Session signatures
+ * to protect your API quota. These can be used without initializing the Quasar class.
+ *
+ * @public
+ */
+declare const utils: {
+    /**
+     * Standardizes the message format for Quasar Mini-Session login.
+     * @see {@link createMiniSessionMessage}
+     */
+    createMiniSessionMessage: typeof createMiniSessionMessage;
+    /**
+     * Verifies a Mini-Session signature (EVM or Solana).
+     * @see {@link verifyMiniSession}
+     */
+    verifyMiniSession: typeof verifyMiniSession;
+    /**
+     * Triggers a signature request in the connected wallet.
+     * @see {@link signMiniSession}
+     */
+    signMiniSession: typeof signMiniSession;
+    /**
+     * Creates a persistent Zustand store for session management.
+     * @see {@link createMiniSessionStore}
+     */
+    createMiniSessionStore: typeof createMiniSessionStore;
+    /**
+     * Reusable helper to manage signing and session caching.
+     * @see {@link getMiniSessionAuth}
+     */
+    getMiniSessionAuth: typeof getMiniSessionAuth;
+};
 /**
  * Main entry point for the Quasar SDK.
  *
- * Initializes the internal HTTP client with your secret key
- * and exposes domain-specific modules for interacting with the Quasar Cloud API.
+ * The `Quasar` class provides a unified interface for interacting with the Quasar Cloud API.
+ * It handles authentication, base URL configuration, and exposes domain-specific modules
+ * like {@link PulsarModule} for transaction management.
  *
  * @example
  * ```typescript
  * import { Quasar } from '@tuwaio/quasar-sdk';
  *
+ * // Initialize with your secret API key
  * const quasar = new Quasar({
  *   secretKey: 'sk_live_your_secret_key',
- *   baseUrl: 'https://api.tuwa.io',
- *   timeout: 15000,
+ *   baseUrl: 'https://api.tuwa.io', // Optional
+ *   timeout: 10000,                // Optional, default is 10s
  * });
  *
- * // Access the Pulsar transaction engine
- * const { txKey } = await quasar.pulsar.syncCreate(tx);
+ * // Access domain-specific modules
+ * const history = await quasar.pulsar.getHistory({ chainId: 1 });
  * ```
+ *
+ * @public
  */
 declare class Quasar {
-    /** @internal */
+    /**
+     * Security and authentication utilities.
+     * Shared across all instances and available statically.
+     */
+    static readonly utils: {
+        /**
+         * Standardizes the message format for Quasar Mini-Session login.
+         * @see {@link createMiniSessionMessage}
+         */
+        createMiniSessionMessage: typeof createMiniSessionMessage;
+        /**
+         * Verifies a Mini-Session signature (EVM or Solana).
+         * @see {@link verifyMiniSession}
+         */
+        verifyMiniSession: typeof verifyMiniSession;
+        /**
+         * Triggers a signature request in the connected wallet.
+         * @see {@link signMiniSession}
+         */
+        signMiniSession: typeof signMiniSession;
+        /**
+         * Creates a persistent Zustand store for session management.
+         * @see {@link createMiniSessionStore}
+         */
+        createMiniSessionStore: typeof createMiniSessionStore;
+        /**
+         * Reusable helper to manage signing and session caching.
+         * @see {@link getMiniSessionAuth}
+         */
+        getMiniSessionAuth: typeof getMiniSessionAuth;
+    };
+    /**
+     * The internal HTTP client used for authenticated requests.
+     * @internal
+     */
     private readonly client;
     /**
      * The Pulsar Transaction Engine module.
      *
-     * Use this to sync transaction states to the Quasar Cloud
-     * and retrieve paginated transaction history.
+     * This module provides methods to sync transaction states to the Quasar Cloud
+     * and retrieve indexed transaction history across multiple blockchain networks.
      *
      * @see {@link PulsarModule}
      */
     readonly pulsar: PulsarModule;
     /**
-     * Creates a new Quasar SDK instance.
+     * Creates a new instance of the Quasar SDK.
+     *
+     * @param config - Configuration options for the SDK.
+     * @throws {Error} If the `secretKey` is missing or invalid.
      *
-     * @param config - SDK configuration. See {@link QuasarConfig} for available options.
-     * @throws {Error} If `config.secretKey` is missing.
+     * @example
+     * ```typescript
+     * const quasar = new Quasar({ secretKey: process.env.QUASAR_SECRET_KEY! });
+     * ```
      */
     constructor(config: QuasarConfig);
 }
 
-export { BASE_API_URL, type HistoryQuery, PULSAR_HISTORY_ENDPOINT, PULSAR_SYNC_ENDPOINT, type PaginatedResult, PulsarModule, Quasar, type QuasarConfig, QuasarSDKError };
+export { BASE_API_URL, ConnectionData, DEFAULT_MAX_AGE, HistoryQuery, MiniSessionAuth, MiniSessionStore, PULSAR_HISTORY_ENDPOINT, PULSAR_SYNC_ENDPOINT, PaginatedResult, PulsarModule, Quasar, QuasarConfig, QuasarSDKError, SignSessionParams, SignSessionResult, VerifySessionParams, createMiniSessionMessage, createMiniSessionStore, getMiniSessionAuth, signMiniSession, utils, verifyMiniSession };