@tuwaio/quasar-sdk 1.0.0-fix-docs-alpha.7.481db45 → 1.0.0-fix-docs-alpha.9.40e8658

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,219 +1,11 @@
 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';
 import * as zustand_middleware from 'zustand/middleware';
 import * as zustand from 'zustand';
 
-/**
- * @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.
- *
- * @public
- * @example
- * ```typescript
- * const config: QuasarConfig = {
- *   secretKey: 'sk_live_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-side bundles
-     * as it grants full access to your organization's Quasar data.
-     */
-    secretKey: string;
-    /**
-     * Optional internal secret sent as `x-internal-secret` header on every request.
-     *
-     * @remarks
-     * This is used for system-to-system communication between TUWA internal services.
-     * Most third-party developers do not need to provide this.
-     */
-    internalSecret?: string;
-    /**
-     * The base URL of the Quasar Cloud API.
-     *
-     * @defaultValue `'https://api.tuwa.io'`
-     */
-    baseUrl?: string;
-    /**
-     * Request timeout in milliseconds for all API calls.
-     *
-     * @defaultValue `10000` (10 seconds)
-     */
-    timeout?: number;
-}
-/**
- * Query parameters for filtering and paginating transaction history.
- *
- * All fields are optional. When omitted, no filtering is applied to that field.
- *
- * @public
- * @example
- * ```typescript
- * const query: HistoryQuery = {
- *   page: 1,
- *   limit: 10,
- *   chainId: 1,           // Ethereum Mainnet
- *   status: 'Success',    // Only successful transactions
- *   appName: 'Tuwa App',  // Filter by application
- * };
- * ```
- */
-interface HistoryQuery {
-    /**
-     * Page number for pagination (1-indexed).
-     *
-     * @defaultValue `1`
-     */
-    page?: number;
-    /**
-     * Maximum number of results to return per page.
-     *
-     * @defaultValue `10`
-     */
-    limit?: number;
-    /**
-     * Filter by blockchain chain ID.
-     *
-     * @example `1` (Ethereum), `'solana'`, `'SN_MAIN'` (Starknet)
-     */
-    chainId?: string | number;
-    /**
-     * Filter by transaction status.
-     *
-     * @example `'pending'`, `'Success'`, `'Failed'`, `'Replaced'`
-     */
-    status?: string;
-    /**
-     * Filter by a specific unique transaction key assigned by Quasar.
-     */
-    txKey?: string;
-    /**
-     * Filter by the application name that synced the transaction.
-     */
-    appName?: string;
-    /**
-     * Filter by the sender's wallet address.
-     */
-    walletAddress?: string;
-}
-/**
- * Generic wrapper for paginated API responses.
- *
- * @typeParam T - The type of the documents contained in the result set.
- *
- * @public
- * @example
- * ```typescript
- * const result: PaginatedResult<Transaction> = await quasar.pulsar.getHistory();
- *
- * console.log(`Showing page ${result.page} of ${result.totalPages}`);
- * console.log(`Total transactions found: ${result.totalDocs}`);
- * ```
- */
-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 based on the limit. */
-    totalPages: number;
-    /** The current page number (1-indexed). */
-    page: number;
-    /** Indicates if a subsequent page of results is available. */
-    hasNextPage: boolean;
-    /** Indicates if a preceding page of results is available. */
-    hasPrevPage: boolean;
-}
-
-/**
- * Supported blockchain ecosystems for authentication.
- * @public
- */
-declare enum ChainType {
-    EVM = "EVM",
-    SOLANA = "SOLANA"
-}
-/**
- * Result of the Mini-Session signing process.
- * Used for both frontend-side caching and backend-side verification.
- * @public
- */
-interface MiniSessionAuth {
-    /** The cryptographic signature (hex for EVM, base58 for Solana). */
-    signature: string;
-    /** ISO string timestamp used in the signed message. */
-    timestamp: string;
-    /** The blockchain ecosystem type. */
-    chainType: ChainType;
-    /** The wallet address that signed the message. */
-    walletAddress: string;
-}
-/**
- * Parameters for verifying a mini-session signature.
- * @public
- */
-interface VerifySessionParams extends Omit<MiniSessionAuth, 'walletAddress'> {
-    /** The wallet address that allegedly signed the message. */
-    walletAddress: string;
-    /**
-     * Maximum allowed age for the signature in milliseconds.
-     * Default: 5 minutes (300,000ms).
-     */
-    maxAge?: number;
-}
-/**
- * Parameters for signing a mini-session message.
- * @public
- */
-interface SignSessionParams {
-    /** The signer object. For EVM, a `WalletClient`. For Solana, a `KeyPairSigner` or `TransactionSendingSigner`. */
-    signer: any;
-    /** The wallet address to sign with (required for EVM). */
-    walletAddress?: string;
-    /** The blockchain ecosystem type. */
-    chainType: ChainType;
-}
-/**
- * Zustand store interface for managing Mini-Sessions.
- * @public
- */
-interface MiniSessionStore {
-    /** Current active session or null. */
-    miniSession: MiniSessionAuth | null;
-    /** Sets the active session. */
-    setMiniSession: (session: MiniSessionAuth | null) => void;
-    /** Clears the current session. */
-    clearSession: () => void;
-}
-/**
- * Minimum connection data required for Mini-Session signing.
- * @public
- */
-interface ConnectionData {
-    /** Whether a wallet is currently connected. */
-    isConnected: boolean;
-    /** The active wallet address. */
-    address: string;
-    /** The blockchain ecosystem type. */
-    chainType: ChainType;
-    /** The wallet signer object (WalletClient for EVM, TransactionSendingSigner for Solana). */
-    signer: any;
-}
-
 /**
  * @module core/client
  * @description Core HTTP client for the Quasar SDK.
@@ -406,12 +198,19 @@ declare class PulsarModule {
 
 /**
  * @module utils/auth
- * @description Security utilities for Mini-Session signature verification.
+ * @description Security utilities for Mini-Session signature creation and verification.
+ * Supports dual-ecosystem (EVM & Solana) authentication flows with strict type safety.
  */
 
 /**
- * Standardizes the message format for Mini-Session login.
- * Both frontend and backend must use this exact template.
+ * 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.
@@ -423,50 +222,40 @@ declare class PulsarModule {
  * ```
  */
 declare function createMiniSessionMessage(timestamp: string): string;
-/**
- * Result of a mini-session signing operation.
- */
-interface SignSessionResult {
-    /** The cryptographic signature. */
-    signature: string;
-    /** The ISO timestamp used to generate the message. */
-    timestamp: string;
-}
 /**
  * Triggers a signature request in the connected wallet to create a Mini-Session.
  *
- * This is a frontend-friendly helper that:
- * 1. Generates a fresh ISO timestamp.
- * 2. Formats the standard login message.
- * 3. Triggers the wallet's signMessage method.
- * 4. Returns the signature and timestamp for verification on the backend.
+ * This function detects the signer's capabilities and uses the most appropriate
+ * signing method available (e.g., Web3 v2, Standard, or Legacy).
  *
- * @param params - The signing parameters including the signer and ecosystem type.
- * @returns A promise that resolves to the signature and timestamp.
- * @throws {Error} If the required peer dependencies are missing or signing fails.
+ * @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 to protect API quota from unauthorized access.
+ * 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.
  *
- * This utility performs three checks:
- * 1. Timestamp freshness (rejects if older than 5 minutes or in the future).
- * 2. Cryptographic validity (checks if the signature matches the wallet address and message).
- * 3. Ecosystem-specific logic (EVM via `viem`, Solana via `gill`).
+ * @param params - Verification data including signature and timestamp.
+ * @returns A promise resolving to true if the session is valid.
  *
- * @param params - The verification parameters including address, signature, and timestamp.
- * @returns A promise that resolves to `true` if the signature is valid and fresh.
- * @throws {Error} If the required peer dependencies (`viem` or `gill`) are missing.
- * @throws {Error} If the timestamp is invalid or expired.
+ * @public
  */
 declare function verifyMiniSession(params: VerifySessionParams): Promise<boolean>;
 
 /**
  * Creates a persistent Zustand store to cache Mini-Session signatures.
- * Requires `zustand` to be installed as a peer dependency.
+ * 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.
  *
- * @param storageName - Key name for localStorage persistence.
- * @returns A Zustand store instance.
+ * @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;
@@ -482,19 +271,22 @@ declare function createMiniSessionStore(storageName?: string): zustand.UseBoundS
     };
 }>;
 /**
- * Generic helper to manage Mini-Session signing and caching.
+ * High-level orchestrator to retrieve an existing Mini-Session or trigger a new signature.
  *
- * Checks the provided store for an existing session matching the current connection.
- * If no session is found, it triggers a signature request using the provided signer.
+ * 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 - Current active connection state.
- * @param store - An object compatible with MiniSessionStore to read/write the session.
- * @returns A promise resolving to the authenticated session.
- * @throws {Error} If no wallet is connected or signing fails.
+ * @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: (s: MiniSessionAuth) => void;
+    setMiniSession: (session: MiniSessionAuth | null) => void;
 }): Promise<MiniSessionAuth>;
 
 declare const BASE_API_URL = "https://api.tuwa.io";
@@ -639,4 +431,4 @@ declare class Quasar {
     constructor(config: QuasarConfig);
 }
 
-export { BASE_API_URL, ChainType, type ConnectionData, type HistoryQuery, type MiniSessionAuth, type MiniSessionStore, PULSAR_HISTORY_ENDPOINT, PULSAR_SYNC_ENDPOINT, type PaginatedResult, PulsarModule, Quasar, type QuasarConfig, QuasarSDKError, type SignSessionParams, type SignSessionResult, type VerifySessionParams, createMiniSessionMessage, createMiniSessionStore, getMiniSessionAuth, signMiniSession, utils, verifyMiniSession };
+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 };