@qtsurfer/api-client 0.1.0

package/src/generated/types.gen.ts

@@ -0,0 +1,588 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+/**
+ * General response error
+ */
+export type ResponseError = {
+    /**
+     * Status code
+     */
+    code: number;
+    /**
+     * Error description
+     */
+    message: string;
+};
+
+/**
+ * Exchange instrument identifier (e.g. a currency pair)
+ */
+export type Instrument = string;
+
+/**
+ * Exchange instrument with data availability and market info
+ */
+export type InstrumentDetail = {
+    /**
+     * Instrument identifier (e.g. currency pair)
+     */
+    id: string;
+    /**
+     * Base currency
+     */
+    base: string;
+    /**
+     * Quote currency
+     */
+    quote: string;
+    /**
+     * Earliest timestamp with quality-verified data available for backtesting
+     */
+    dataFrom?: string;
+    /**
+     * Latest timestamp with quality-verified data available for backtesting
+     */
+    dataTo?: string;
+    /**
+     * Last traded price
+     */
+    lastPrice?: number;
+    /**
+     * Trading volume in the last 24 hours (in quote currency)
+     */
+    volume24h?: number;
+};
+
+/**
+ * Exchange service provider
+ */
+export type Exchange = {
+    /**
+     * Unique identifier for the exchange
+     */
+    id: string;
+    /**
+     * Name of the exchange
+     */
+    name: string;
+    /**
+     * Description of the exchange
+     */
+    description?: string;
+};
+
+/**
+ * Managed exchange data sources available for backtesting. Currently only ticker is supported; kline and funding rate support is planned.
+ */
+export type DataSourceType = 'ticker';
+
+/**
+ * Information about a single job
+ */
+export type JobState = {
+    /**
+     * Unique context ID for the job
+     */
+    contextId: string;
+    /**
+     * Current status of the job
+     */
+    status: 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
+    /**
+     * Detailed status information, if available
+     */
+    statusDetail?: string | null;
+    /**
+     * Total size of the data being prepared
+     */
+    size: number;
+    /**
+     * The amount of data processed so far
+     */
+    completed: number;
+    /**
+     * Timestamp for when the preparation started
+     */
+    startTime?: string | null;
+    /**
+     * Timestamp for when the preparation finished
+     */
+    endTime?: string | null;
+};
+
+/**
+ * Response returned by async endpoints (`202 Accepted`). The `jobId` is deterministic for the
+ * same input parameters — repeated calls with identical params return the same id.
+ *
+ */
+export type AcceptedJob = {
+    /**
+     * Unique job identifier; use this to poll for completion.
+     */
+    jobId: string;
+};
+
+/**
+ * Backtest job result.
+ */
+export type BacktestJobResult = {
+    results: ResultMap;
+    state: JobState;
+};
+
+/**
+ * Execution result map. Always includes core fields (hostName, iops, strategyId, instrument). Yield metrics (pnlTotal, totalTrades, winRate, etc.) are present when the strategy emitted at least one trade. When signal storage is enabled, includes signal fields described below.
+ */
+export type ResultMap = {
+    /**
+     * Hostname of the worker node that executed the strategy
+     */
+    hostName?: string;
+    /**
+     * Instrument operations per second throughput during execution
+     */
+    iops?: number;
+    /**
+     * Redis key of the compiled strategy used for execution. Format: strategy:{userId}:ticker:{compilationId}
+     */
+    strategyId: string;
+    /**
+     * The instrument (currency pair) that was backtested
+     */
+    instrument: string;
+    /**
+     * Total profit and loss in the output currency
+     */
+    pnlTotal?: number;
+    /**
+     * Total number of trades executed by the strategy
+     */
+    totalTrades?: number;
+    /**
+     * Percentage of profitable trades (0-100)
+     */
+    winRate?: number;
+    /**
+     * Risk-adjusted return ratio (mean return / standard deviation of returns)
+     */
+    sharpeRatio?: number;
+    /**
+     * Downside risk-adjusted return ratio (mean return / downside deviation)
+     */
+    sortinoRatio?: number;
+    /**
+     * Compound Annual Growth Rate
+     */
+    cagr?: number;
+    /**
+     * Maximum absolute drawdown in the output currency
+     */
+    maxDrawdown?: number;
+    /**
+     * Maximum percentage drawdown from peak equity
+     */
+    maxDrawdownPercent?: number;
+    /**
+     * Number of signals emitted during strategy execution
+     */
+    signalCount?: number;
+    /**
+     * Storage key for the signal Parquet file. Format: {userId}/exec/{exchange}/{jobId}
+     */
+    signalsId?: string;
+    /**
+     * Public HTTPS URL to the Parquet file. Computed at setup time from publicBaseUrl + signalsId + .parquet. Available even before upload completes.
+     */
+    signalsUrl?: string;
+    /**
+     * Upload status. Done = file uploaded to R2. Failed = upload error (see signalsUploadReason). Skipped = no signals emitted or storage not configured.
+     */
+    signalsUpload?: 'Done' | 'Failed' | 'Skipped';
+    /**
+     * ISO 8601 timestamp of when the upload completed. Only present when signalsUpload is Done.
+     */
+    signalsUploadedAt?: string;
+    /**
+     * Human-readable reason when signalsUpload is Failed or Skipped.
+     */
+    signalsUploadReason?: string;
+};
+
+/**
+ * Unique identifier for a compiled strategy
+ */
+export type StrategyId = string;
+
+export type GetExchangesData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/exchanges';
+};
+
+export type GetExchangesResponses = {
+    /**
+     * A JSON array of Exchanges
+     */
+    200: Array<Exchange>;
+};
+
+export type GetExchangesResponse = GetExchangesResponses[keyof GetExchangesResponses];
+
+export type GetInstrumentsData = {
+    body?: never;
+    path: {
+        /**
+         * ID of the exchange to retrieve instruments for
+         */
+        exchangeId: string;
+    };
+    query?: never;
+    url: '/exchange/{exchangeId}/instruments';
+};
+
+export type GetInstrumentsErrors = {
+    /**
+     * Exchange not found or instrument catalog not available
+     */
+    404: ResponseError;
+};
+
+export type GetInstrumentsError = GetInstrumentsErrors[keyof GetInstrumentsErrors];
+
+export type GetInstrumentsResponses = {
+    /**
+     * A JSON array of Instrument details with data availability
+     */
+    200: Array<InstrumentDetail>;
+};
+
+export type GetInstrumentsResponse = GetInstrumentsResponses[keyof GetInstrumentsResponses];
+
+export type PostStrategyData = {
+    /**
+     * Raw strategy Java source code
+     */
+    body: string;
+    headers?: {
+        /**
+         * When `true`, compile asynchronously and return `202` with a `jobId`.
+         */
+        'X-Compile-Async'?: boolean;
+    };
+    path?: never;
+    query?: never;
+    url: '/strategy';
+};
+
+export type PostStrategyErrors = {
+    /**
+     * Invalid strategy (compilation error)
+     */
+    400: ResponseError;
+};
+
+export type PostStrategyError = PostStrategyErrors[keyof PostStrategyErrors];
+
+export type PostStrategyResponses = {
+    /**
+     * Strategy compiled successfully (sync mode)
+     */
+    200: {
+        strategyId: StrategyId;
+    };
+    /**
+     * Compile task accepted (async mode — set `X-Compile-Async: true`)
+     */
+    202: AcceptedJob;
+};
+
+export type PostStrategyResponse = PostStrategyResponses[keyof PostStrategyResponses];
+
+export type GetStrategyStatusData = {
+    body?: never;
+    path: {
+        /**
+         * The id returned by `POST /strategy` (sync) or the `jobId` returned in async mode
+         */
+        strategyId: string;
+    };
+    query?: never;
+    url: '/strategy/{strategyId}';
+};
+
+export type GetStrategyStatusErrors = {
+    /**
+     * Strategy compile job not found
+     */
+    404: ResponseError;
+};
+
+export type GetStrategyStatusError = GetStrategyStatusErrors[keyof GetStrategyStatusErrors];
+
+export type GetStrategyStatusResponses = {
+    /**
+     * Strategy compile state
+     */
+    200: {
+        /**
+         * Compile job id (only set in async mode)
+         */
+        jobId?: string;
+        status: 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
+        strategyId?: StrategyId;
+        /**
+         * Compilation error messages when `status` is `Failed`
+         */
+        statusDetail?: string | null;
+    };
+};
+
+export type GetStrategyStatusResponse = GetStrategyStatusResponses[keyof GetStrategyStatusResponses];
+
+export type PrepareBacktestingData = {
+    /**
+     * The required data to prepare a backtesting
+     */
+    body: {
+        instrument: Instrument;
+        /**
+         * Start date for the preparation process. Supports the following formats:
+         * - ISO-8601 (e.g. 2024-12-14T23:59:59Z)
+         * - ISO DATE (e.g. 2024-12-14)
+         * - BASIC ISO DATE (e.g., 20241214)
+         *
+         */
+        from: string;
+        /**
+         * End date for the preparation process. Supports the following formats:
+         * - ISO-8601 (e.g. 2024-12-14T23:59:59Z)
+         * - ISO DATE (e.g. 2024-12-14)
+         * - BASIC ISO DATE (e.g., 20241214)
+         *
+         */
+        to: string;
+    };
+    path: {
+        /**
+         * ID of the exchange to prepare the backtesting for
+         */
+        exchangeId: string;
+        /**
+         * The type of data source to prepare from
+         */
+        type: DataSourceType;
+    };
+    query?: never;
+    url: '/backtest/{exchangeId}/{type}/prepare';
+};
+
+export type PrepareBacktestingErrors = {
+    /**
+     * Invalid request or parameters. Also returned when `from` is older than the configured
+     * lookback window or `to` is in the future.
+     *
+     */
+    400: ResponseError;
+    /**
+     * Exchange or data source type not found
+     */
+    404: ResponseError;
+    /**
+     * Rate limited. Returned when the global queue exceeds capacity or the user has too many
+     * active backtests.
+     *
+     */
+    429: ResponseError;
+};
+
+export type PrepareBacktestingError = PrepareBacktestingErrors[keyof PrepareBacktestingErrors];
+
+export type PrepareBacktestingResponses = {
+    /**
+     * Prepare task accepted (queued for processing)
+     */
+    202: AcceptedJob;
+};
+
+export type PrepareBacktestingResponse = PrepareBacktestingResponses[keyof PrepareBacktestingResponses];
+
+export type GetPreparationStatusData = {
+    body?: never;
+    path: {
+        /**
+         * ID of the exchange for the backtesting process
+         */
+        exchangeId: string;
+        /**
+         * The type of data source to prepare from
+         */
+        type: DataSourceType;
+        /**
+         * Job ID returned by `POST /prepare`
+         */
+        jobId: string;
+    };
+    query?: never;
+    url: '/backtest/{exchangeId}/{type}/prepare/{jobId}';
+};
+
+export type GetPreparationStatusErrors = {
+    /**
+     * Invalid request or parameters
+     */
+    400: ResponseError;
+    /**
+     * Prepare job not found or expired
+     */
+    404: ResponseError;
+};
+
+export type GetPreparationStatusError = GetPreparationStatusErrors[keyof GetPreparationStatusErrors];
+
+export type GetPreparationStatusResponses = {
+    /**
+     * Current prepare job state
+     */
+    200: JobState;
+};
+
+export type GetPreparationStatusResponse = GetPreparationStatusResponses[keyof GetPreparationStatusResponses];
+
+export type ExecuteBacktestingData = {
+    /**
+     * Execute task parameters
+     */
+    body: {
+        /**
+         * Job ID returned by `POST /prepare` (must be in `Completed` state)
+         */
+        prepareJobId: string;
+        strategyId: StrategyId;
+        /**
+         * When true, the worker uploads emitted signals to object storage and the
+         * response includes `signalsUrl` / `signalsId` fields. Defaults to false.
+         *
+         */
+        storeSignals?: boolean;
+    };
+    path: {
+        /**
+         * ID of the exchange for the backtesting process
+         */
+        exchangeId: string;
+        /**
+         * The type of data source to execute from
+         */
+        type: DataSourceType;
+    };
+    query?: never;
+    url: '/backtest/{exchangeId}/{type}/execute';
+};
+
+export type ExecuteBacktestingErrors = {
+    /**
+     * Invalid request or parameters
+     */
+    400: ResponseError;
+    /**
+     * Prepare job not found or expired
+     */
+    404: ResponseError;
+    /**
+     * Rate limited (global queue at capacity or per-user limit reached)
+     */
+    429: ResponseError;
+};
+
+export type ExecuteBacktestingError = ExecuteBacktestingErrors[keyof ExecuteBacktestingErrors];
+
+export type ExecuteBacktestingResponses = {
+    /**
+     * Execute task accepted (queued for processing)
+     */
+    202: AcceptedJob;
+};
+
+export type ExecuteBacktestingResponse = ExecuteBacktestingResponses[keyof ExecuteBacktestingResponses];
+
+export type CancelExecutionData = {
+    body?: never;
+    path: {
+        exchangeId: string;
+        type: DataSourceType;
+        /**
+         * Job ID returned by `POST /execute`
+         */
+        jobId: string;
+    };
+    query?: never;
+    url: '/backtest/{exchangeId}/{type}/execute/{jobId}';
+};
+
+export type CancelExecutionErrors = {
+    /**
+     * Execution not found
+     */
+    404: ResponseError;
+};
+
+export type CancelExecutionError = CancelExecutionErrors[keyof CancelExecutionErrors];
+
+export type CancelExecutionResponses = {
+    /**
+     * Cancellation request accepted
+     */
+    200: {
+        status?: 'cancelling';
+        jobId?: string;
+    };
+};
+
+export type CancelExecutionResponse = CancelExecutionResponses[keyof CancelExecutionResponses];
+
+export type GetExecutionResultData = {
+    body?: never;
+    path: {
+        /**
+         * ID of the exchange for the backtesting process
+         */
+        exchangeId: string;
+        /**
+         * The type of data source to execute from
+         */
+        type: DataSourceType;
+        /**
+         * Job ID returned by `POST /execute`
+         */
+        jobId: string;
+    };
+    query?: never;
+    url: '/backtest/{exchangeId}/{type}/execute/{jobId}';
+};
+
+export type GetExecutionResultErrors = {
+    /**
+     * Invalid request or parameters
+     */
+    400: ResponseError;
+    /**
+     * Execution job not found
+     */
+    404: ResponseError;
+};
+
+export type GetExecutionResultError = GetExecutionResultErrors[keyof GetExecutionResultErrors];
+
+export type GetExecutionResultResponses = {
+    /**
+     * Backtesting execution result
+     */
+    200: BacktestJobResult;
+};
+
+export type GetExecutionResultResponse = GetExecutionResultResponses[keyof GetExecutionResultResponses];
+
+export type ClientOptions = {
+    baseUrl: 'https://api.staging.qtsurfer.com/v1' | 'https://api.qtsurfer.com/v1' | (string & {});
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './generated';
+export { client } from './generated/client.gen';