import { FetchOptions } from 'ofetch';
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, and authentication structures.
 */

/**
 * Configuration options for initializing the {@link Quasar} SDK client.
 *
 * @public
 */
interface QuasarConfig {
    /** Your secret API key starting with `sk_live_`. */
    secretKey: string;
    /** Optional internal secret for system-to-system communication. */
    internalSecret?: string;
    /** The base URL of the Quasar Cloud API. Defaults to 'https://api.tuwa.io'. */
    baseUrl?: string;
    /** Request timeout in milliseconds. Defaults to 10000. */
    timeout?: number;
}
/**
 * Query parameters for filtering and paginating transaction history.
 *
 * @public
 */
interface HistoryQuery {
    /** Page number for pagination (1-indexed). */
    page?: number;
    /** Maximum number of results to return per page. */
    limit?: number;
    /** Filter by blockchain chain ID (e.g., 1, 'solana'). */
    chainId?: string | number;
    /** Filter by transaction status (e.g., 'Success', 'Failed'). */
    status?: string;
    /** Filter by a specific Quasar transaction key. */
    txKey?: string;
    /** Filter by the application name. */
    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
 */
interface PaginatedResult<T> {
    /** Array of documents for the current page. */
    docs: T[];
    /** Total number of documents matching the query. */
    totalDocs: number;
    /** Total number of available pages. */
    totalPages: number;
    /** The current page number (1-indexed). */
    page: number;
    /** Indicates if a subsequent page is available. */
    hasNextPage: boolean;
    /** Indicates if a preceding page is available. */
    hasPrevPage: boolean;
}

/**
 * @module core/client
 * @description Core HTTP client for the Quasar SDK.
 * Handles authenticated requests through the Iron Dome security perimeter
 * and provides structured error handling for all API interactions.
 */

/**
 * Custom error class for all Quasar SDK API failures.
 *
 * Wraps the underlying HTTP error with a structured format including
 * status code, human-readable message, and the original error reference.
 *
 * @example
 * ```typescript
 * try {
 *   await quasar.pulsar.getHistory();
 * } catch (err) {
 *   if (err instanceof QuasarSDKError) {
 *     console.error(err.status);        // e.g. 401
 *     console.error(err.message);       // "[Quasar SDK] Request Failed (401): Unauthorized"
 *     console.error(err.originalError); // Raw FetchError from ofetch
 *   }
 * }
 * ```
 */
declare class QuasarSDKError extends Error {
    /** HTTP status code returned by the API, if available. */
    readonly status: number | undefined;
    /** The original error thrown by the HTTP client. */
    readonly originalError: Error;
    /**
     * Creates a new QuasarSDKError instance.
     *
     * @param message - Formatted error message with SDK prefix and status.
     * @param status - HTTP status code, or `undefined` if unavailable.
     * @param originalError - The raw error from the HTTP layer.
     */
    constructor(message: string, status: number | undefined, originalError: Error);
}
/**
 * Internal HTTP client for the Quasar Cloud API.
 *
 * Manages authenticated requests by injecting the `x-tuwa-secret-key` header
 * into every outgoing request. Optionally injects `x-internal-secret`
 * when it is provided in the SDK config. Uses `ofetch` as the transport layer.
 *
 * @remarks
 * This class is not exported from the public API surface.
 * Consumers interact with it indirectly through the {@link Quasar} entry point.
 *
 * @internal
 */
declare class QuasarClient {
    /** The secret API key used for authentication. */
    private readonly secretKey;
    /** Optional internal secret sent as `x-internal-secret` when provided. */
    private readonly internalSecret?;
    /** The base URL for all API requests. */
    private readonly baseUrl;
    /** Request timeout in milliseconds. */
    private readonly timeout;
    /**
     * Creates a new QuasarClient instance.
     *
     * @param config - SDK configuration containing the secret key and optional overrides.
     * @throws {Error} If `config.secretKey` is missing or empty.
     */
    constructor(config: QuasarConfig);
    /**
     * Sends an authenticated request to the Quasar Cloud API.
     *
     * Automatically injects Iron Dome headers (`x-tuwa-secret-key`, `Content-Type`)
     * and optionally injects `x-internal-secret` when the SDK was configured with it.
     * Wraps all transport errors into {@link QuasarSDKError}.
     *
     * @typeParam T - Expected response body type.
     * @param path - API endpoint path (e.g. `/api/v1/engine/tx-sync`).
     * @param options - Fetch options (method, body, query, headers, etc.).
     *                  `baseURL` and `timeout` are managed internally and cannot be overridden.
     * @returns The parsed JSON response body typed as `T`.
     * @throws {QuasarSDKError} On any HTTP or network error.
     */
    request<T>(path: string, options?: Omit<FetchOptions<'json'>, 'baseURL' | 'timeout'>): Promise<T>;
    /**
     * Transforms a raw fetch error into a structured {@link QuasarSDKError}.
     *
     * Extracts status code and error message from the response body or fallback fields.
     * Logs a console warning for authentication failures (401/403).
     *
     * @param error - The raw error caught from `ofetch`.
     * @returns A formatted QuasarSDKError instance.
     */
    private buildError;
}

/**
 * @module modules/pulsar
 * @description Pulsar Transaction Engine module.
 * Provides methods for syncing transaction states to the Quasar Cloud
 * and retrieving paginated transaction history.
 */

/**
 * Pulsar module — the transaction engine interface for Quasar Cloud.
 *
 * 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 {@link Quasar} SDK.
 * All methods are authenticated automatically using the configured secret key.
 *
 * @example
 * ```typescript
 * const quasar = new Quasar({ secretKey: 'sk_live_...' });
 *
 * // Sync a new transaction to start tracking
 * const { txKey } = await quasar.pulsar.syncCreate(transaction);
 *
 * // Retrieve transaction history with filters
 * const history = await quasar.pulsar.getHistory({
 *   chainId: 1,
 *   status: 'Success',
 * });
 * ```
 */
declare class PulsarModule {
    private readonly client;
    /**
     * Creates a new PulsarModule instance.
     *
     * @param client - The internal {@link QuasarClient} instance for making authenticated API calls.
     * @internal
     */
    constructor(client: QuasarClient);
    /**
     * Syncs a newly created or pending transaction to the Quasar Cloud.
     *
     * 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. 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 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<{
        success: true;
        txKey: string;
    }>;
    /**
     * Retrieves a paginated list of transactions from the Quasar Cloud.
     *
     * 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. 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,
     *   walletAddress: '6x...',
     * });
     *
     * result.docs.forEach(tx => console.log(tx.txKey, tx.status));
     * ```
     */
    getHistory(query?: HistoryQuery): Promise<PaginatedResult<Transaction>>;
}

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";

/**
 * @module @tuwaio/quasar-sdk
 * The official server-side Node.js & Edge SDK for the TUWA Quasar Cloud.
 *
 * Provides a type-safe client for interacting with the Quasar API,
 * including transaction syncing, status tracking, and history retrieval
 * through the Iron Dome security perimeter.
 *
 * @example
 * ```typescript
 * import { Quasar } from '@tuwaio/quasar-sdk';
 *
 * const quasar = new Quasar({ secretKey: 'sk_live_...' });
 * const history = await quasar.pulsar.getHistory({ chainId: 1 });
 * ```
 *
 * @packageDocumentation
 */

/**
 * Pre-flight check before initiating a transaction.
 * Ensures the local SIWX Session is valid and verifies Quasar Engine health.
 *
 * @param customApiUrl - Optional custom API URL to override the default.
 * @throws {Error} If the session check fails or Quasar is unreachable.
 *
 * @public
 */
declare function preFlightTxCheck(customApiUrl?: string): Promise<void>;
/**
 * Main entry point for the Quasar SDK.
 *
 * 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', // Optional
 *   timeout: 10000,                // Optional, default is 10s
 * });
 *
 * // Access domain-specific modules
 * const history = await quasar.pulsar.getHistory({ chainId: 1 });
 * ```
 *
 * @public
 */
declare class Quasar {
    /**
     * The internal HTTP client used for authenticated requests.
     * @internal
     */
    private readonly client;
    /**
     * The Pulsar Transaction Engine module.
     *
     * 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 instance of the Quasar SDK.
     *
     * @param config - Configuration options for the SDK.
     * @throws {Error} If the `secretKey` is missing or invalid.
     *
     * @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, preFlightTxCheck };