@qtsurfer/api-client 0.1.0

package/src/generated/schemas.gen.ts

@@ -0,0 +1,296 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export const ResponseErrorSchema = {
+    description: 'General response error',
+    type: 'object',
+    required: ['code', 'message'],
+    properties: {
+        code: {
+            description: 'Status code',
+            type: 'integer',
+            example: 400
+        },
+        message: {
+            description: 'Error description',
+            type: 'string',
+            example: 'Invalid request'
+        }
+    }
+} as const;
+
+export const InstrumentSchema = {
+    description: 'Exchange instrument identifier (e.g. a currency pair)',
+    type: 'string',
+    example: 'BTC/USDT'
+} as const;
+
+export const InstrumentDetailSchema = {
+    description: 'Exchange instrument with data availability and market info',
+    type: 'object',
+    required: ['id', 'base', 'quote'],
+    properties: {
+        id: {
+            type: 'string',
+            description: 'Instrument identifier (e.g. currency pair)',
+            example: 'BTC/USDT'
+        },
+        base: {
+            type: 'string',
+            description: 'Base currency',
+            example: 'BTC'
+        },
+        quote: {
+            type: 'string',
+            description: 'Quote currency',
+            example: 'USDT'
+        },
+        dataFrom: {
+            type: 'string',
+            format: 'date-time',
+            description: 'Earliest timestamp with quality-verified data available for backtesting',
+            example: '2026-03-17T00:00:00Z'
+        },
+        dataTo: {
+            type: 'string',
+            format: 'date-time',
+            description: 'Latest timestamp with quality-verified data available for backtesting',
+            example: '2026-03-31T18:00:00Z'
+        },
+        lastPrice: {
+            type: 'number',
+            format: 'double',
+            description: 'Last traded price',
+            example: 84250.5
+        },
+        volume24h: {
+            type: 'number',
+            format: 'double',
+            description: 'Trading volume in the last 24 hours (in quote currency)',
+            example: 1234567.89
+        }
+    }
+} as const;
+
+export const ExchangeSchema = {
+    description: 'Exchange service provider',
+    type: 'object',
+    required: ['id', 'name'],
+    properties: {
+        id: {
+            description: 'Unique identifier for the exchange',
+            type: 'string',
+            example: 'binance'
+        },
+        name: {
+            description: 'Name of the exchange',
+            type: 'string',
+            example: 'Binance'
+        },
+        description: {
+            description: 'Description of the exchange',
+            type: 'string',
+            example: 'Binance cryptocurrency exchange'
+        }
+    }
+} as const;
+
+export const DataSourceTypeSchema = {
+    type: 'string',
+    description: 'Managed exchange data sources available for backtesting. Currently only ticker is supported; kline and funding rate support is planned.',
+    enum: ['ticker'],
+    example: 'ticker'
+} as const;
+
+export const JobStateSchema = {
+    type: 'object',
+    description: 'Information about a single job',
+    required: ['contextId', 'status', 'size', 'completed'],
+    properties: {
+        contextId: {
+            type: 'string',
+            description: 'Unique context ID for the job',
+            example: 'jctx:ticker:4a627755-7f5a-4297-b647-8dddd8aee416:binance:1rabbrpk5r4kkegs83w6qr:btc/usdt:2o8heaioicr0edvx5ybcap'
+        },
+        status: {
+            type: 'string',
+            description: 'Current status of the job',
+            enum: ['New', 'Started', 'Completed', 'Aborted', 'Failed'],
+            example: 'Completed'
+        },
+        statusDetail: {
+            type: ['string', 'null'],
+            description: 'Detailed status information, if available',
+            example: 'Job completed with error code 5001'
+        },
+        size: {
+            type: 'integer',
+            description: 'Total size of the data being prepared',
+            example: 100
+        },
+        completed: {
+            type: 'integer',
+            description: 'The amount of data processed so far',
+            example: 50
+        },
+        startTime: {
+            type: ['string', 'null'],
+            format: 'date-time',
+            description: 'Timestamp for when the preparation started',
+            example: '2025-01-04T14:00:00Z'
+        },
+        endTime: {
+            type: ['string', 'null'],
+            format: 'date-time',
+            description: 'Timestamp for when the preparation finished',
+            example: '2025-01-04T14:00:20Z'
+        }
+    }
+} as const;
+
+export const AcceptedJobSchema = {
+    type: 'object',
+    description: `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.
+`,
+    required: ['jobId'],
+    properties: {
+        jobId: {
+            type: 'string',
+            description: 'Unique job identifier; use this to poll for completion.',
+            example: '13RBLGQlPnfDjO6wyKSX8i'
+        }
+    },
+    example: {
+        jobId: '13RBLGQlPnfDjO6wyKSX8i'
+    }
+} as const;
+
+export const BacktestJobResultSchema = {
+    type: 'object',
+    description: 'Backtest job result.',
+    required: ['results', 'state'],
+    properties: {
+        results: {
+            '$ref': '#/components/schemas/ResultMap'
+        },
+        state: {
+            '$ref': '#/components/schemas/JobState'
+        }
+    }
+} as const;
+
+export const ResultMapSchema = {
+    type: 'object',
+    description: '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.',
+    required: ['strategyId', 'instrument'],
+    properties: {
+        hostName: {
+            type: 'string',
+            description: 'Hostname of the worker node that executed the strategy',
+            example: 'backtesting-job-worker-84b569dff9-dr4lb'
+        },
+        iops: {
+            type: 'number',
+            format: 'double',
+            description: 'Instrument operations per second throughput during execution',
+            example: 123956.53
+        },
+        strategyId: {
+            type: 'string',
+            description: 'Redis key of the compiled strategy used for execution. Format: strategy:{userId}:ticker:{compilationId}',
+            example: 'strategy:4a627755-7f5a-4297-b647-8dddd8aee416:ticker:2iyvtenlzh9dabqtxn7nbv'
+        },
+        instrument: {
+            type: 'string',
+            description: 'The instrument (currency pair) that was backtested',
+            example: 'BTC/USDT'
+        },
+        pnlTotal: {
+            type: 'number',
+            format: 'double',
+            description: 'Total profit and loss in the output currency',
+            example: 42.75
+        },
+        totalTrades: {
+            type: 'integer',
+            format: 'int64',
+            description: 'Total number of trades executed by the strategy',
+            example: 156
+        },
+        winRate: {
+            type: 'number',
+            format: 'double',
+            description: 'Percentage of profitable trades (0-100)',
+            example: 58.33
+        },
+        sharpeRatio: {
+            type: 'number',
+            format: 'double',
+            description: 'Risk-adjusted return ratio (mean return / standard deviation of returns)',
+            example: 1.245
+        },
+        sortinoRatio: {
+            type: 'number',
+            format: 'double',
+            description: 'Downside risk-adjusted return ratio (mean return / downside deviation)',
+            example: 1.872
+        },
+        cagr: {
+            type: 'number',
+            format: 'double',
+            description: 'Compound Annual Growth Rate',
+            example: 0.1534
+        },
+        maxDrawdown: {
+            type: 'number',
+            format: 'double',
+            description: 'Maximum absolute drawdown in the output currency',
+            example: 12.5
+        },
+        maxDrawdownPercent: {
+            type: 'number',
+            format: 'double',
+            description: 'Maximum percentage drawdown from peak equity',
+            example: 8.75
+        },
+        signalCount: {
+            type: 'integer',
+            description: 'Number of signals emitted during strategy execution',
+            example: 100000
+        },
+        signalsId: {
+            type: 'string',
+            description: 'Storage key for the signal Parquet file. Format: {userId}/exec/{exchange}/{jobId}',
+            example: '4a627755-7f5a-4297-b647-8dddd8aee416/exec/binance/3vsndwikcuaatjmb83fjtl'
+        },
+        signalsUrl: {
+            type: 'string',
+            format: 'uri',
+            description: 'Public HTTPS URL to the Parquet file. Computed at setup time from publicBaseUrl + signalsId + .parquet. Available even before upload completes.',
+            example: 'https://storage.qtsurfer.com/4a627755-7f5a-4297-b647-8dddd8aee416/exec/binance/3vsndwikcuaatjmb83fjtl.parquet'
+        },
+        signalsUpload: {
+            type: 'string',
+            enum: ['Done', 'Failed', 'Skipped'],
+            description: 'Upload status. Done = file uploaded to R2. Failed = upload error (see signalsUploadReason). Skipped = no signals emitted or storage not configured.',
+            example: 'Done'
+        },
+        signalsUploadedAt: {
+            type: 'string',
+            format: 'date-time',
+            description: 'ISO 8601 timestamp of when the upload completed. Only present when signalsUpload is Done.',
+            example: '2026-03-18T13:21:48.170Z'
+        },
+        signalsUploadReason: {
+            type: 'string',
+            description: 'Human-readable reason when signalsUpload is Failed or Skipped.',
+            example: 'parquet file empty or missing after close'
+        }
+    }
+} as const;
+
+export const strategyIdSchema = {
+    description: 'Unique identifier for a compiled strategy',
+    type: 'string',
+    example: '6bsh31ikwkuivhtgcoa6s4'
+} as const;

package/src/generated/sdk.gen.ts

@@ -0,0 +1,202 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import type { Options as ClientOptions, TDataShape, Client } from '@hey-api/client-fetch';
+import type { GetExchangesData, GetExchangesResponse, GetInstrumentsData, GetInstrumentsResponse, GetInstrumentsError, PostStrategyData, PostStrategyResponse, PostStrategyError, GetStrategyStatusData, GetStrategyStatusResponse, GetStrategyStatusError, PrepareBacktestingData, PrepareBacktestingResponse, PrepareBacktestingError, GetPreparationStatusData, GetPreparationStatusResponse, GetPreparationStatusError, ExecuteBacktestingData, ExecuteBacktestingResponse, ExecuteBacktestingError, CancelExecutionData, CancelExecutionResponse, CancelExecutionError, GetExecutionResultData, GetExecutionResultResponse, GetExecutionResultError } from './types.gen';
+import { client as _heyApiClient } from './client.gen';
+
+export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = ClientOptions<TData, ThrowOnError> & {
+    /**
+     * You can provide a client instance returned by `createClient()` instead of
+     * individual options. This might be also useful if you want to implement a
+     * custom client.
+     */
+    client?: Client;
+    /**
+     * You can pass arbitrary values through the `meta` object. This can be
+     * used to access values that aren't defined as part of the SDK function.
+     */
+    meta?: Record<string, unknown>;
+};
+
+/**
+ * Get a list of available exchanges
+ */
+export const getExchanges = <ThrowOnError extends boolean = false>(options?: Options<GetExchangesData, ThrowOnError>) => {
+    return (options?.client ?? _heyApiClient).get<GetExchangesResponse, unknown, ThrowOnError>({
+        url: '/exchanges',
+        ...options
+    });
+};
+
+/**
+ * Get a list of Instruments from a specific exchange
+ */
+export const getInstruments = <ThrowOnError extends boolean = false>(options: Options<GetInstrumentsData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<GetInstrumentsResponse, GetInstrumentsError, ThrowOnError>({
+        url: '/exchange/{exchangeId}/instruments',
+        ...options
+    });
+};
+
+/**
+ * Compile a strategy from source code
+ * Submits raw strategy source for compilation. By default the call is synchronous and returns
+ * the `strategyId` once compilation succeeds. Set the header `X-Compile-Async: true` to enqueue
+ * the compile task and return immediately with a `jobId` — poll
+ * `GET /strategy/{strategyId}` to check status.
+ *
+ * The `strategyId` is deterministic: the same source for the same user always produces the
+ * same id.
+ *
+ */
+export const postStrategy = <ThrowOnError extends boolean = false>(options: Options<PostStrategyData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<PostStrategyResponse, PostStrategyError, ThrowOnError>({
+        bodySerializer: null,
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/strategy',
+        ...options,
+        headers: {
+            'Content-Type': 'text/plain',
+            ...options?.headers
+        }
+    });
+};
+
+/**
+ * Get the status of an async compile task
+ * Polls the status of a strategy compilation. Useful when the strategy was submitted with
+ * `X-Compile-Async: true`. Returns the resolved `strategyId` once compilation completes.
+ *
+ */
+export const getStrategyStatus = <ThrowOnError extends boolean = false>(options: Options<GetStrategyStatusData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<GetStrategyStatusResponse, GetStrategyStatusError, ThrowOnError>({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/strategy/{strategyId}',
+        ...options
+    });
+};
+
+/**
+ * Prepare backtesting data
+ * Enqueues a prepare task over the requested date range. Returns immediately with a `jobId`;
+ * poll `GET /backtest/{exchangeId}/{type}/prepare/{jobId}` for completion.
+ *
+ * The same params always return the same `jobId` (idempotent). Repeated calls with identical
+ * params do not enqueue duplicate work — they reuse the existing job.
+ *
+ */
+export const prepareBacktesting = <ThrowOnError extends boolean = false>(options: Options<PrepareBacktestingData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<PrepareBacktestingResponse, PrepareBacktestingError, ThrowOnError>({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/backtest/{exchangeId}/{type}/prepare',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options?.headers
+        }
+    });
+};
+
+/**
+ * Get the status of a prepare job
+ * Retrieves the current state of the prepare job identified by `jobId`.
+ * Poll until `status` is `Completed`, `Failed`, or `Aborted`.
+ *
+ */
+export const getPreparationStatus = <ThrowOnError extends boolean = false>(options: Options<GetPreparationStatusData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<GetPreparationStatusResponse, GetPreparationStatusError, ThrowOnError>({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/backtest/{exchangeId}/{type}/prepare/{jobId}',
+        ...options
+    });
+};
+
+/**
+ * Execute a compiled strategy against a prepared dataset
+ * Enqueues an execute task that runs the strategy identified by `strategyId` over the data
+ * prepared by the prepare job identified by `prepareJobId`. The instrument and date range are
+ * recovered from the prepare job — they do not need to be sent again.
+ *
+ * Returns immediately with a `jobId`; poll `GET /backtest/{exchangeId}/{type}/execute/{jobId}`
+ * for the result.
+ *
+ * The same params (same `prepareJobId`, `strategyId`, `storeSignals`) always return the same
+ * `jobId` (idempotent).
+ *
+ */
+export const executeBacktesting = <ThrowOnError extends boolean = false>(options: Options<ExecuteBacktestingData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<ExecuteBacktestingResponse, ExecuteBacktestingError, ThrowOnError>({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/backtest/{exchangeId}/{type}/execute',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options?.headers
+        }
+    });
+};
+
+/**
+ * Cancel a running backtest execution
+ * Requests cancellation of the specified execution. The execution
+ * status will transition to `Aborted` once the cancellation is
+ * processed. Cancellation is asynchronous — poll the GET endpoint
+ * to confirm the final status.
+ *
+ */
+export const cancelExecution = <ThrowOnError extends boolean = false>(options: Options<CancelExecutionData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).delete<CancelExecutionResponse, CancelExecutionError, ThrowOnError>({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/backtest/{exchangeId}/{type}/execute/{jobId}',
+        ...options
+    });
+};
+
+/**
+ * Get the result of a backtest execution job
+ * Retrieves the current state and results of the execute job identified by `jobId`.
+ * Poll until `state.status` is `Completed`, `Failed`, or `Aborted`.
+ *
+ */
+export const getExecutionResult = <ThrowOnError extends boolean = false>(options: Options<GetExecutionResultData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<GetExecutionResultResponse, GetExecutionResultError, ThrowOnError>({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/backtest/{exchangeId}/{type}/execute/{jobId}',
+        ...options
+    });
+};