@qtsurfer/api-client 0.3.0 → 0.4.0

package/README.md

@@ -82,7 +82,7 @@ All operations are exported as standalone functions; every operation accepts an
 | `cancelExecution` | POST | `/backtesting/execute/{jobId}/cancel` | Cancel a running execution |
 | `getExecutionResult` | GET | `/backtesting/execute/{jobId}` | Poll or fetch execution results |
 
-All generated types (`Exchange`, `InstrumentDetail`, `BacktestJobResult`, `ResultMap`, etc.) are re-exported from the root.
+All generated types (`Exchange`, `InstrumentDetail`, `BacktestJobResult`, `PrepareJobState`, `ResultMap`, etc.) are re-exported from the root.
 
 ## Configuring the client
 

package/dist/index.d.ts

@@ -162,13 +162,13 @@ type JobState = {
      */
     contextId: string;
     /**
-     * Current status of the job. `Partial` (prepare only) means some
-     * hours are still being produced asynchronously — keep polling.
-     * Treat `Completed | Aborted | Failed` as terminal; anything else
-     * means keep polling.
+     * Current status of the job. Treat `Completed | Aborted | Failed` as
+     * terminal; `New | Started` mean keep polling. A single-instrument prepare
+     * is always terminal (`Completed`) — decide from
+     * `PrepareJobState.coverageRatio`, not by polling.
      *
      */
-    status: 'New' | 'Started' | 'Partial' | 'Completed' | 'Aborted' | 'Failed';
+    status: 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
     /**
      * Detailed status information, if available
      */
@@ -190,6 +190,61 @@ type JobState = {
      */
     endTime?: string | null;
 };
+/**
+ * State of a single-instrument prepare job — the `JobState` shape plus a per-hour
+ * data-coverage summary. A single-instrument prepare is always terminal
+ * (`status: Completed`): the client decides what to do from `coverageRatio` (e.g.
+ * execute if it is at or above a chosen threshold) rather than polling for missing
+ * hours that may never arrive — a missing hour for one instrument usually means low
+ * activity, not missing data.
+ *
+ */
+type PrepareJobState = JobState & {
+    /**
+     * Start of the available data range for the prepared instrument.
+     */
+    dataFrom?: string | null;
+    /**
+     * End of the available data range for the prepared instrument.
+     */
+    dataTo?: string | null;
+    /**
+     * `hoursWithData / totalHours` in `[0,1]` (`1.0` when `totalHours` is 0) — the
+     * fraction of hours in the requested range that have served data.
+     *
+     */
+    coverageRatio?: number;
+    /**
+     * Number of whole hours in the requested prepare range.
+     */
+    totalHours?: number;
+    /**
+     * Number of hours in the range that have data.
+     */
+    hoursWithData?: number;
+    /**
+     * One entry per hour in the range that has no data, with a rationale.
+     */
+    hoursWithoutData?: Array<{
+        /**
+         * The hour (UTC, hour-aligned) that has no data.
+         */
+        hour?: string;
+        /**
+         * Expected row count for the hour (currently always 0; reserved for
+         * future use). The rationale never depends on it.
+         *
+         */
+        expected?: number;
+        /**
+         * Why the hour has no data. `pending_conversion`: data for this hour is
+         * still being produced — a re-poll may fill it. `low_activity`: the
+         * instrument did not trade that hour. `unknown`: no data to classify by.
+         *
+         */
+        rationale?: 'pending_conversion' | 'low_activity' | 'unknown';
+    }>;
+};
 /**
  * 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.
@@ -728,7 +783,7 @@ type GetPreparationStatusResponses = {
     /**
      * Current prepare job state
      */
-    200: JobState;
+    200: PrepareJobState;
 };
 type GetPreparationStatusResponse = GetPreparationStatusResponses[keyof GetPreparationStatusResponses];
 type ExecuteBacktestingData = {
@@ -988,7 +1043,7 @@ declare const prepareBacktesting: <ThrowOnError extends boolean = false>(options
  * Poll until `status` is `Completed`, `Failed`, or `Aborted`.
  *
  */
-declare const getPreparationStatus: <ThrowOnError extends boolean = false>(options: Options<GetPreparationStatusData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<JobState, ResponseError, ThrowOnError>;
+declare const getPreparationStatus: <ThrowOnError extends boolean = false>(options: Options<GetPreparationStatusData, ThrowOnError>) => _hey_api_client_fetch.RequestResult<PrepareJobState, ResponseError, ThrowOnError>;
 /**
  * Execute a compiled strategy against a prepared dataset
  * Enqueues an execute task that runs the strategy identified by `strategyId` over the data
@@ -1025,4 +1080,4 @@ declare const getExecutionResult: <ThrowOnError extends boolean = false>(options
 
 declare const client: _hey_api_client_fetch.Client;
 
-export { type AcceptedJob, type AuthData, type AuthError, type AuthErrors, type AuthResponse, type AuthResponses, type AuthTokenError, type AuthTokenResponse, type BacktestJobResult, type CancelExecutionData, type CancelExecutionError, type CancelExecutionErrors, type CancelExecutionResponse, type CancelExecutionResponses, type ClientOptions, type CoverageWindow, type DataSourceType, type EquityPoint, type Exchange, type ExecuteBacktestingData, type ExecuteBacktestingError, type ExecuteBacktestingErrors, type ExecuteBacktestingResponse, type ExecuteBacktestingResponses, type GetExchangeKlinesHourData, type GetExchangeKlinesHourError, type GetExchangeKlinesHourErrors, type GetExchangeKlinesHourResponse, type GetExchangeKlinesHourResponses, type GetExchangeTickersHourData, type GetExchangeTickersHourError, type GetExchangeTickersHourErrors, type GetExchangeTickersHourResponse, type GetExchangeTickersHourResponses, type GetExchangesData, type GetExchangesResponse, type GetExchangesResponses, type GetExecutionResultData, type GetExecutionResultError, type GetExecutionResultErrors, type GetExecutionResultResponse, type GetExecutionResultResponses, type GetInstrumentsData, type GetInstrumentsError, type GetInstrumentsErrors, type GetInstrumentsResponse, type GetInstrumentsResponses, type GetPreparationStatusData, type GetPreparationStatusError, type GetPreparationStatusErrors, type GetPreparationStatusResponse, type GetPreparationStatusResponses, type GetSegmentInstrumentsData, type GetSegmentInstrumentsError, type GetSegmentInstrumentsErrors, type GetSegmentInstrumentsResponse, type GetSegmentInstrumentsResponses, type GetStrategyStatusData, type GetStrategyStatusError, type GetStrategyStatusErrors, type GetStrategyStatusResponse, type GetStrategyStatusResponses, type HalLink, type Instrument, type InstrumentCoverage, type InstrumentDetail, type InstrumentLinks, type InstrumentListMeta, type InstrumentListResponse, type JobState, type Options, type PostStrategyData, type PostStrategyError, type PostStrategyErrors, type PostStrategyResponse, type PostStrategyResponses, type PrepareBacktestingData, type PrepareBacktestingError, type PrepareBacktestingErrors, type PrepareBacktestingResponse, type PrepareBacktestingResponses, type ResponseError, type ResultMap, type StrategyId, auth, cancelExecution, client, executeBacktesting, getExchangeKlinesHour, getExchangeTickersHour, getExchanges, getExecutionResult, getInstruments, getPreparationStatus, getSegmentInstruments, getStrategyStatus, postStrategy, prepareBacktesting };
+export { type AcceptedJob, type AuthData, type AuthError, type AuthErrors, type AuthResponse, type AuthResponses, type AuthTokenError, type AuthTokenResponse, type BacktestJobResult, type CancelExecutionData, type CancelExecutionError, type CancelExecutionErrors, type CancelExecutionResponse, type CancelExecutionResponses, type ClientOptions, type CoverageWindow, type DataSourceType, type EquityPoint, type Exchange, type ExecuteBacktestingData, type ExecuteBacktestingError, type ExecuteBacktestingErrors, type ExecuteBacktestingResponse, type ExecuteBacktestingResponses, type GetExchangeKlinesHourData, type GetExchangeKlinesHourError, type GetExchangeKlinesHourErrors, type GetExchangeKlinesHourResponse, type GetExchangeKlinesHourResponses, type GetExchangeTickersHourData, type GetExchangeTickersHourError, type GetExchangeTickersHourErrors, type GetExchangeTickersHourResponse, type GetExchangeTickersHourResponses, type GetExchangesData, type GetExchangesResponse, type GetExchangesResponses, type GetExecutionResultData, type GetExecutionResultError, type GetExecutionResultErrors, type GetExecutionResultResponse, type GetExecutionResultResponses, type GetInstrumentsData, type GetInstrumentsError, type GetInstrumentsErrors, type GetInstrumentsResponse, type GetInstrumentsResponses, type GetPreparationStatusData, type GetPreparationStatusError, type GetPreparationStatusErrors, type GetPreparationStatusResponse, type GetPreparationStatusResponses, type GetSegmentInstrumentsData, type GetSegmentInstrumentsError, type GetSegmentInstrumentsErrors, type GetSegmentInstrumentsResponse, type GetSegmentInstrumentsResponses, type GetStrategyStatusData, type GetStrategyStatusError, type GetStrategyStatusErrors, type GetStrategyStatusResponse, type GetStrategyStatusResponses, type HalLink, type Instrument, type InstrumentCoverage, type InstrumentDetail, type InstrumentLinks, type InstrumentListMeta, type InstrumentListResponse, type JobState, type Options, type PostStrategyData, type PostStrategyError, type PostStrategyErrors, type PostStrategyResponse, type PostStrategyResponses, type PrepareBacktestingData, type PrepareBacktestingError, type PrepareBacktestingErrors, type PrepareBacktestingResponse, type PrepareBacktestingResponses, type PrepareJobState, type ResponseError, type ResultMap, type StrategyId, auth, cancelExecution, client, executeBacktesting, getExchangeKlinesHour, getExchangeTickersHour, getExchanges, getExecutionResult, getInstruments, getPreparationStatus, getSegmentInstruments, getStrategyStatus, postStrategy, prepareBacktesting };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qtsurfer/api-client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Auto-generated TypeScript API client for the QTSurfer API (from OpenAPI 3.1 spec)",
   "type": "module",
   "main": "./dist/index.js",

package/src/generated/schemas.gen.ts

@@ -249,12 +249,12 @@ export const JobStateSchema = {
         },
         status: {
             type: 'string',
-            description: `Current status of the job. \`Partial\` (prepare only) means some
-hours are still being produced asynchronously — keep polling.
-Treat \`Completed | Aborted | Failed\` as terminal; anything else
-means keep polling.
+            description: `Current status of the job. Treat \`Completed | Aborted | Failed\` as
+terminal; \`New | Started\` mean keep polling. A single-instrument prepare
+is always terminal (\`Completed\`) — decide from
+\`PrepareJobState.coverageRatio\`, not by polling.
 `,
-            enum: ['New', 'Started', 'Partial', 'Completed', 'Aborted', 'Failed'],
+            enum: ['New', 'Started', 'Completed', 'Aborted', 'Failed'],
             example: 'Completed'
         },
         statusDetail: {
@@ -287,6 +287,89 @@ means keep polling.
     }
 } as const;
 
+export const PrepareJobStateSchema = {
+    description: `State of a single-instrument prepare job — the \`JobState\` shape plus a per-hour
+data-coverage summary. A single-instrument prepare is always terminal
+(\`status: Completed\`): the client decides what to do from \`coverageRatio\` (e.g.
+execute if it is at or above a chosen threshold) rather than polling for missing
+hours that may never arrive — a missing hour for one instrument usually means low
+activity, not missing data.
+`,
+    allOf: [
+        {
+            '$ref': '#/components/schemas/JobState'
+        },
+        {
+            type: 'object',
+            properties: {
+                dataFrom: {
+                    type: ['string', 'null'],
+                    format: 'date-time',
+                    description: 'Start of the available data range for the prepared instrument.',
+                    example: '2026-04-14T13:00:00Z'
+                },
+                dataTo: {
+                    type: ['string', 'null'],
+                    format: 'date-time',
+                    description: 'End of the available data range for the prepared instrument.',
+                    example: '2026-04-14T15:30:05Z'
+                },
+                coverageRatio: {
+                    type: 'number',
+                    format: 'double',
+                    minimum: 0,
+                    maximum: 1,
+                    description: `\`hoursWithData / totalHours\` in \`[0,1]\` (\`1.0\` when \`totalHours\` is 0) — the
+fraction of hours in the requested range that have served data.
+`,
+                    example: 0.994
+                },
+                totalHours: {
+                    type: 'integer',
+                    description: 'Number of whole hours in the requested prepare range.',
+                    example: 168
+                },
+                hoursWithData: {
+                    type: 'integer',
+                    description: 'Number of hours in the range that have data.',
+                    example: 167
+                },
+                hoursWithoutData: {
+                    type: 'array',
+                    description: 'One entry per hour in the range that has no data, with a rationale.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            hour: {
+                                type: 'string',
+                                format: 'date-time',
+                                description: 'The hour (UTC, hour-aligned) that has no data.',
+                                example: '2026-04-14T02:00:00Z'
+                            },
+                            expected: {
+                                type: 'integer',
+                                description: `Expected row count for the hour (currently always 0; reserved for
+future use). The rationale never depends on it.
+`,
+                                example: 0
+                            },
+                            rationale: {
+                                type: 'string',
+                                description: `Why the hour has no data. \`pending_conversion\`: data for this hour is
+still being produced — a re-poll may fill it. \`low_activity\`: the
+instrument did not trade that hour. \`unknown\`: no data to classify by.
+`,
+                                enum: ['pending_conversion', 'low_activity', 'unknown'],
+                                example: 'low_activity'
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    ]
+} as const;
+
 export const AcceptedJobSchema = {
     type: 'object',
     description: `Response returned by async endpoints (\`202 Accepted\`). The \`jobId\` is deterministic for the

package/src/generated/types.gen.ts

@@ -172,13 +172,13 @@ export type JobState = {
      */
     contextId: string;
     /**
-     * Current status of the job. `Partial` (prepare only) means some
-     * hours are still being produced asynchronously — keep polling.
-     * Treat `Completed | Aborted | Failed` as terminal; anything else
-     * means keep polling.
+     * Current status of the job. Treat `Completed | Aborted | Failed` as
+     * terminal; `New | Started` mean keep polling. A single-instrument prepare
+     * is always terminal (`Completed`) — decide from
+     * `PrepareJobState.coverageRatio`, not by polling.
      *
      */
-    status: 'New' | 'Started' | 'Partial' | 'Completed' | 'Aborted' | 'Failed';
+    status: 'New' | 'Started' | 'Completed' | 'Aborted' | 'Failed';
     /**
      * Detailed status information, if available
      */
@@ -201,6 +201,62 @@ export type JobState = {
     endTime?: string | null;
 };
 
+/**
+ * State of a single-instrument prepare job — the `JobState` shape plus a per-hour
+ * data-coverage summary. A single-instrument prepare is always terminal
+ * (`status: Completed`): the client decides what to do from `coverageRatio` (e.g.
+ * execute if it is at or above a chosen threshold) rather than polling for missing
+ * hours that may never arrive — a missing hour for one instrument usually means low
+ * activity, not missing data.
+ *
+ */
+export type PrepareJobState = JobState & {
+    /**
+     * Start of the available data range for the prepared instrument.
+     */
+    dataFrom?: string | null;
+    /**
+     * End of the available data range for the prepared instrument.
+     */
+    dataTo?: string | null;
+    /**
+     * `hoursWithData / totalHours` in `[0,1]` (`1.0` when `totalHours` is 0) — the
+     * fraction of hours in the requested range that have served data.
+     *
+     */
+    coverageRatio?: number;
+    /**
+     * Number of whole hours in the requested prepare range.
+     */
+    totalHours?: number;
+    /**
+     * Number of hours in the range that have data.
+     */
+    hoursWithData?: number;
+    /**
+     * One entry per hour in the range that has no data, with a rationale.
+     */
+    hoursWithoutData?: Array<{
+        /**
+         * The hour (UTC, hour-aligned) that has no data.
+         */
+        hour?: string;
+        /**
+         * Expected row count for the hour (currently always 0; reserved for
+         * future use). The rationale never depends on it.
+         *
+         */
+        expected?: number;
+        /**
+         * Why the hour has no data. `pending_conversion`: data for this hour is
+         * still being produced — a re-poll may fill it. `low_activity`: the
+         * instrument did not trade that hour. `unknown`: no data to classify by.
+         *
+         */
+        rationale?: 'pending_conversion' | 'low_activity' | 'unknown';
+    }>;
+};
+
 /**
  * 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.
@@ -792,7 +848,7 @@ export type GetPreparationStatusResponses = {
     /**
      * Current prepare job state
      */
-    200: JobState;
+    200: PrepareJobState;
 };
 
 export type GetPreparationStatusResponse = GetPreparationStatusResponses[keyof GetPreparationStatusResponses];