@adaptic/utils 0.0.1010 → 0.0.1012
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +776 -370
- package/dist/index.cjs.map +1 -1
- package/dist/index.mjs +776 -370
- package/dist/index.mjs.map +1 -1
- package/dist/test.js +45 -45
- package/dist/test.js.map +1 -1
- package/dist/types/__tests__/alpaca-order-idempotency.test.d.ts +2 -0
- package/dist/types/__tests__/alpaca-order-idempotency.test.d.ts.map +1 -0
- package/dist/types/__tests__/retry-classification.test.d.ts +2 -0
- package/dist/types/__tests__/retry-classification.test.d.ts.map +1 -0
- package/dist/types/alpaca/index.d.ts +4 -1
- package/dist/types/alpaca/index.d.ts.map +1 -1
- package/dist/types/alpaca/trading/orders.d.ts +106 -9
- package/dist/types/alpaca/trading/orders.d.ts.map +1 -1
- package/dist/types/index.d.ts +8 -2
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/utils/retry.d.ts +65 -0
- package/dist/types/utils/retry.d.ts.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"alpaca-order-idempotency.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/alpaca-order-idempotency.test.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"retry-classification.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/retry-classification.test.ts"],"names":[],"mappings":""}
|
|
@@ -112,7 +112,9 @@ export declare const alpaca: {
|
|
|
112
112
|
filterOrdersByDateRange: typeof orderUtils.filterOrdersByDateRange;
|
|
113
113
|
sortOrdersByDate: typeof orderUtils.sortOrdersByDate;
|
|
114
114
|
};
|
|
115
|
-
|
|
115
|
+
deriveClientOrderId(idempotencyKey: string): string;
|
|
116
|
+
getOrderByClientOrderId(client: AlpacaClient, clientOrderId: string): Promise<import("..").AlpacaOrder | null>;
|
|
117
|
+
createOrder(client: AlpacaClient, params: trading.OptionallyIdempotentCreateOrderParams): Promise<import("..").AlpacaOrder>;
|
|
116
118
|
getOrder(client: AlpacaClient, orderId: string): Promise<import("..").AlpacaOrder>;
|
|
117
119
|
getOrders(client: AlpacaClient, params?: import("..").GetOrdersParams): Promise<import("..").AlpacaOrder[]>;
|
|
118
120
|
cancelOrder(client: AlpacaClient, orderId: string): Promise<void>;
|
|
@@ -120,6 +122,7 @@ export declare const alpaca: {
|
|
|
120
122
|
replaceOrder(client: AlpacaClient, orderId: string, params: import("..").ReplaceOrderParams): Promise<import("..").AlpacaOrder>;
|
|
121
123
|
isOrderCancelable(status: import("..").OrderStatus): boolean;
|
|
122
124
|
getOrderByClientId(client: AlpacaClient, clientOrderId: string): Promise<import("..").AlpacaOrder>;
|
|
125
|
+
MAX_CLIENT_ORDER_ID_LENGTH: 128;
|
|
123
126
|
};
|
|
124
127
|
smartOrders: {
|
|
125
128
|
bracket: typeof bracketOrders;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/alpaca/index.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/alpaca/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,7 +1,3 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Alpaca Order Management Module
|
|
3
|
-
* Provides functions for creating, managing, and canceling orders using the official SDK
|
|
4
|
-
*/
|
|
5
1
|
import { AlpacaClient } from "../client";
|
|
6
2
|
import { AlpacaOrder, CreateOrderParams, GetOrdersParams, ReplaceOrderParams, OrderStatus } from "../../types/alpaca-types";
|
|
7
3
|
/**
|
|
@@ -13,23 +9,123 @@ export interface CancelAllOrdersResponse {
|
|
|
13
9
|
/** Order IDs that failed to cancel */
|
|
14
10
|
failed: string[];
|
|
15
11
|
}
|
|
12
|
+
/**
|
|
13
|
+
* Maximum length Alpaca accepts for a `client_order_id`.
|
|
14
|
+
*/
|
|
15
|
+
export declare const MAX_CLIENT_ORDER_ID_LENGTH = 128;
|
|
16
|
+
/**
|
|
17
|
+
* The idempotency contract every order submission should satisfy.
|
|
18
|
+
*
|
|
19
|
+
* Without it, `AlpacaClient.executeWithRateLimit`'s automatic retry re-sends a
|
|
20
|
+
* POST that may already have landed broker-side — an ECONNRESET after the order
|
|
21
|
+
* was accepted doubles a live position (F-0035). The key makes the submission
|
|
22
|
+
* idempotent at the broker: the same key always produces the same
|
|
23
|
+
* `client_order_id`, and Alpaca rejects the second POST instead of filling it.
|
|
24
|
+
*
|
|
25
|
+
* A caller-supplied key is the only thing that makes a *caller-level* retry
|
|
26
|
+
* (a fresh `createOrder` call for the same logical order) safe. The
|
|
27
|
+
* transitional overload that accepts no key buys transport-retry idempotency
|
|
28
|
+
* only — see {@link createOrder}.
|
|
29
|
+
*/
|
|
30
|
+
export interface OrderIdempotency {
|
|
31
|
+
/**
|
|
32
|
+
* Identity of the **logical** order, supplied by the caller. Two submissions
|
|
33
|
+
* carrying the same key are the same order and must never both fill; a
|
|
34
|
+
* genuinely new order needs a new key. The engine's convention is the
|
|
35
|
+
* originating `trade.id` (`client_order_id === trade.id`), which
|
|
36
|
+
* {@link deriveClientOrderId} preserves verbatim.
|
|
37
|
+
*/
|
|
38
|
+
idempotencyKey: string;
|
|
39
|
+
}
|
|
40
|
+
/** {@link CreateOrderParams} plus the mandatory idempotency key. */
|
|
41
|
+
export type IdempotentCreateOrderParams = CreateOrderParams & OrderIdempotency;
|
|
42
|
+
/**
|
|
43
|
+
* {@link CreateOrderParams} with the idempotency key **optional** — the shape
|
|
44
|
+
* the transitional (deprecated) `createOrder` overload accepts.
|
|
45
|
+
*
|
|
46
|
+
* This exists only because `createOrder` is published public API with callers
|
|
47
|
+
* that supply no order identity (`options/strategies.ts` in this package, owned
|
|
48
|
+
* by B-0061; `tool-execution-engine.ts` in the engine). Requiring the key
|
|
49
|
+
* outright broke their compilation. Every such caller is expected to migrate to
|
|
50
|
+
* {@link IdempotentCreateOrderParams}; see {@link createOrder} for exactly what
|
|
51
|
+
* an omitted key does and does not guarantee.
|
|
52
|
+
*/
|
|
53
|
+
export type OptionallyIdempotentCreateOrderParams = CreateOrderParams & Partial<OrderIdempotency>;
|
|
54
|
+
/**
|
|
55
|
+
* Derives the broker-side `client_order_id` from a caller-supplied idempotency
|
|
56
|
+
* key. Deterministic: the same key always yields the same id, so a retry of the
|
|
57
|
+
* same logical order collides broker-side instead of creating a second order.
|
|
58
|
+
*
|
|
59
|
+
* A key that is already broker-safe is used **verbatim**, which preserves the
|
|
60
|
+
* engine's `client_order_id === trade.id` convention (and keeps every
|
|
61
|
+
* reconciliation path that joins on `trade.id` working). A key needing
|
|
62
|
+
* sanitisation or truncation is rewritten and tagged with a SHA-256 digest of
|
|
63
|
+
* the original, so two distinct keys can never collapse onto one id.
|
|
64
|
+
*
|
|
65
|
+
* @param idempotencyKey - Identity of the logical order.
|
|
66
|
+
* @returns An Alpaca-safe, length-bounded `client_order_id`.
|
|
67
|
+
* @throws Error when the key is empty or whitespace-only.
|
|
68
|
+
*/
|
|
69
|
+
export declare function deriveClientOrderId(idempotencyKey: string): string;
|
|
70
|
+
/**
|
|
71
|
+
* Looks up an order by its `client_order_id`.
|
|
72
|
+
*
|
|
73
|
+
* @param client - The AlpacaClient instance
|
|
74
|
+
* @param clientOrderId - The idempotency key the order was submitted with
|
|
75
|
+
* @returns The order, or null when the broker holds no order for that id
|
|
76
|
+
* @throws The underlying error when the lookup fails for any reason other than
|
|
77
|
+
* "not found" — an unverifiable lookup must never be read as "no order".
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* const existing = await getOrderByClientOrderId(client, trade.id);
|
|
81
|
+
*/
|
|
82
|
+
export declare function getOrderByClientOrderId(client: AlpacaClient, clientOrderId: string): Promise<AlpacaOrder | null>;
|
|
16
83
|
/**
|
|
17
84
|
* Creates a new order using the Alpaca SDK.
|
|
18
85
|
* Supports market, limit, stop, and stop_limit order types.
|
|
19
86
|
*
|
|
87
|
+
* Every submission carries a `client_order_id`, so the retry the underlying
|
|
88
|
+
* client performs on transient network failure can never fill the same order
|
|
89
|
+
* twice: the re-sent POST is refused broker-side and the order that landed is
|
|
90
|
+
* returned (F-0035).
|
|
91
|
+
*
|
|
92
|
+
* Where that id comes from, in precedence order:
|
|
93
|
+
*
|
|
94
|
+
* 1. an explicit `params.client_order_id` — validated (non-empty, length- and
|
|
95
|
+
* charset-safe) and used verbatim, never blanked, never silently rewritten;
|
|
96
|
+
* 2. `params.idempotencyKey` — the identity of the **logical** order, from
|
|
97
|
+
* which {@link deriveClientOrderId} derives the id deterministically, so a
|
|
98
|
+
* resubmission of the same logical order collides at the broker instead of
|
|
99
|
+
* creating a second position;
|
|
100
|
+
* 3. neither — a key is minted for this submission alone. **This is the
|
|
101
|
+
* deprecated path.** It closes the transport-retry double-fill and nothing
|
|
102
|
+
* more: two `createOrder` calls for the same logical order are two distinct
|
|
103
|
+
* ids and therefore two live orders. It exists because published callers
|
|
104
|
+
* that carry no order identity would otherwise fail to compile, it logs a
|
|
105
|
+
* warning with `outcome: "generated_idempotency_key"` on every submission,
|
|
106
|
+
* and it is removed once those callers pass their own identity.
|
|
107
|
+
*
|
|
20
108
|
* @param client - The AlpacaClient instance
|
|
21
|
-
* @param params - Order parameters
|
|
22
|
-
*
|
|
23
|
-
*
|
|
109
|
+
* @param params - Order parameters (symbol, qty, side, type, time_in_force);
|
|
110
|
+
* supply `idempotencyKey` (or an explicit `client_order_id`) to get
|
|
111
|
+
* caller-level idempotency rather than transport-level only
|
|
112
|
+
* @returns The created order, or the already-submitted order when the broker
|
|
113
|
+
* refused the submission as a duplicate of a live/filled order
|
|
114
|
+
* @throws DuplicateClientOrderIdError when the id collides with an order that
|
|
115
|
+
* cannot be treated as this submission's success
|
|
116
|
+
* @throws Error when a supplied idempotency key is blank, when an explicitly
|
|
117
|
+
* supplied `client_order_id` is blank/over-length/unsafe, or if order
|
|
118
|
+
* creation fails
|
|
24
119
|
*
|
|
25
120
|
* @example
|
|
26
|
-
* // Create a market order
|
|
121
|
+
* // Create a market order, keyed on the originating trade
|
|
27
122
|
* const order = await createOrder(client, {
|
|
28
123
|
* symbol: 'AAPL',
|
|
29
124
|
* qty: '10',
|
|
30
125
|
* side: 'buy',
|
|
31
126
|
* type: 'market',
|
|
32
127
|
* time_in_force: 'day',
|
|
128
|
+
* idempotencyKey: trade.id,
|
|
33
129
|
* });
|
|
34
130
|
*
|
|
35
131
|
* @example
|
|
@@ -41,9 +137,10 @@ export interface CancelAllOrdersResponse {
|
|
|
41
137
|
* type: 'limit',
|
|
42
138
|
* limit_price: '150.00',
|
|
43
139
|
* time_in_force: 'gtc',
|
|
140
|
+
* idempotencyKey: `${trade.id}-limit`,
|
|
44
141
|
* });
|
|
45
142
|
*/
|
|
46
|
-
export declare function createOrder(client: AlpacaClient, params:
|
|
143
|
+
export declare function createOrder(client: AlpacaClient, params: OptionallyIdempotentCreateOrderParams): Promise<AlpacaOrder>;
|
|
47
144
|
/**
|
|
48
145
|
* Retrieves a specific order by its ID.
|
|
49
146
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../../src/alpaca/trading/orders.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../../src/alpaca/trading/orders.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAKzC,OAAO,EACL,WAAW,EAEX,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,WAAW,EAEZ,MAAM,0BAA0B,CAAC;AAWlC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AA8C9C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,MAAM,2BAA2B,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qCAAqC,GAAG,iBAAiB,GACnE,OAAO,CAAC,gBAAgB,CAAC,CAAC;AA8C5B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAkBlE;AA8ED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,YAAY,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAa7B;AAqED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,qCAAqC,GAC5C,OAAO,CAAC,WAAW,CAAC,CAgFtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAAC,WAAW,EAAE,CAAC,CAqCxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,uBAAuB,CAAC,CAsClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC,CAgDtB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,WAAW,EAAE,CAAC,CAExB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAQ5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAQ9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,YAAY,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CA6BtB"}
|
package/dist/types/index.d.ts
CHANGED
|
@@ -170,7 +170,9 @@ export declare const adaptic: {
|
|
|
170
170
|
filterOrdersByDateRange: typeof import("./alpaca").filterOrdersByDateRange;
|
|
171
171
|
sortOrdersByDate: typeof import("./alpaca").sortOrdersByDate;
|
|
172
172
|
};
|
|
173
|
-
|
|
173
|
+
deriveClientOrderId(idempotencyKey: string): string;
|
|
174
|
+
getOrderByClientOrderId(client: import("./alpaca").AlpacaClient, clientOrderId: string): Promise<Types.AlpacaOrder | null>;
|
|
175
|
+
createOrder(client: import("./alpaca").AlpacaClient, params: import("./alpaca/trading/orders").OptionallyIdempotentCreateOrderParams): Promise<Types.AlpacaOrder>;
|
|
174
176
|
getOrder(client: import("./alpaca").AlpacaClient, orderId: string): Promise<Types.AlpacaOrder>;
|
|
175
177
|
getOrders(client: import("./alpaca").AlpacaClient, params?: Types.GetOrdersParams): Promise<Types.AlpacaOrder[]>;
|
|
176
178
|
cancelOrder(client: import("./alpaca").AlpacaClient, orderId: string): Promise<void>;
|
|
@@ -178,6 +180,7 @@ export declare const adaptic: {
|
|
|
178
180
|
replaceOrder(client: import("./alpaca").AlpacaClient, orderId: string, params: Types.ReplaceOrderParams): Promise<Types.AlpacaOrder>;
|
|
179
181
|
isOrderCancelable(status: Types.OrderStatus): boolean;
|
|
180
182
|
getOrderByClientId(client: import("./alpaca").AlpacaClient, clientOrderId: string): Promise<Types.AlpacaOrder>;
|
|
183
|
+
MAX_CLIENT_ORDER_ID_LENGTH: 128;
|
|
181
184
|
};
|
|
182
185
|
/** @description Position management - SDK-based (requires AlpacaClient) */
|
|
183
186
|
sdkPositions: typeof import("./alpaca/trading/positions");
|
|
@@ -567,7 +570,9 @@ export declare const adptc: {
|
|
|
567
570
|
filterOrdersByDateRange: typeof import("./alpaca").filterOrdersByDateRange;
|
|
568
571
|
sortOrdersByDate: typeof import("./alpaca").sortOrdersByDate;
|
|
569
572
|
};
|
|
570
|
-
|
|
573
|
+
deriveClientOrderId(idempotencyKey: string): string;
|
|
574
|
+
getOrderByClientOrderId(client: import("./alpaca").AlpacaClient, clientOrderId: string): Promise<Types.AlpacaOrder | null>;
|
|
575
|
+
createOrder(client: import("./alpaca").AlpacaClient, params: import("./alpaca/trading/orders").OptionallyIdempotentCreateOrderParams): Promise<Types.AlpacaOrder>;
|
|
571
576
|
getOrder(client: import("./alpaca").AlpacaClient, orderId: string): Promise<Types.AlpacaOrder>;
|
|
572
577
|
getOrders(client: import("./alpaca").AlpacaClient, params?: Types.GetOrdersParams): Promise<Types.AlpacaOrder[]>;
|
|
573
578
|
cancelOrder(client: import("./alpaca").AlpacaClient, orderId: string): Promise<void>;
|
|
@@ -575,6 +580,7 @@ export declare const adptc: {
|
|
|
575
580
|
replaceOrder(client: import("./alpaca").AlpacaClient, orderId: string, params: Types.ReplaceOrderParams): Promise<Types.AlpacaOrder>;
|
|
576
581
|
isOrderCancelable(status: Types.OrderStatus): boolean;
|
|
577
582
|
getOrderByClientId(client: import("./alpaca").AlpacaClient, clientOrderId: string): Promise<Types.AlpacaOrder>;
|
|
583
|
+
MAX_CLIENT_ORDER_ID_LENGTH: 128;
|
|
578
584
|
};
|
|
579
585
|
/** @description Position management - SDK-based (requires AlpacaClient) */
|
|
580
586
|
sdkPositions: typeof import("./alpaca/trading/positions");
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
* - Respects Retry-After headers for rate limiting (429)
|
|
8
8
|
* - Fail-fast for non-retryable errors (4xx client errors)
|
|
9
9
|
* - Detailed error logging with context
|
|
10
|
+
* - Retryability is decided from a **typed** HTTP status or a typed error
|
|
11
|
+
* class only; an error message is never parsed for a status (F-0035)
|
|
10
12
|
*/
|
|
11
13
|
export interface RetryConfig {
|
|
12
14
|
/** Maximum number of retry attempts (default: 3) */
|
|
@@ -22,6 +24,29 @@ export interface RetryConfig {
|
|
|
22
24
|
/** Optional callback invoked on each retry attempt */
|
|
23
25
|
onRetry?: (attempt: number, error: unknown) => void;
|
|
24
26
|
}
|
|
27
|
+
/**
|
|
28
|
+
* Typed taxonomy of retry outcomes. Every classification decision resolves to
|
|
29
|
+
* exactly one member; the union is exhaustive by construction so a new class
|
|
30
|
+
* cannot be added without every consumer switch failing to compile.
|
|
31
|
+
*/
|
|
32
|
+
export type RetryErrorType = "RATE_LIMIT" | "SERVER_ERROR" | "CLIENT_ERROR" | "AUTH_ERROR" | "NETWORK_ERROR" | "UNKNOWN";
|
|
33
|
+
/**
|
|
34
|
+
* The verdict produced by {@link classifyRetryError}: what kind of failure this
|
|
35
|
+
* is, the HTTP status it was decided from (null when the failure carried no
|
|
36
|
+
* status), and whether the call may be re-issued.
|
|
37
|
+
*/
|
|
38
|
+
export interface RetryErrorDetails {
|
|
39
|
+
/** Typed failure class. */
|
|
40
|
+
type: RetryErrorType;
|
|
41
|
+
/** Human-readable reason, for logs only — never used to decide anything. */
|
|
42
|
+
reason: string;
|
|
43
|
+
/** HTTP status the verdict was derived from, or null for status-less failures. */
|
|
44
|
+
status: number | null;
|
|
45
|
+
/** Delay (ms) mandated by the upstream `Retry-After` header. */
|
|
46
|
+
retryAfter?: number;
|
|
47
|
+
/** Whether the operation may be re-issued. */
|
|
48
|
+
isRetryable: boolean;
|
|
49
|
+
}
|
|
25
50
|
/**
|
|
26
51
|
* Walks the `error.cause` chain (capped to avoid cycles) and tests whether
|
|
27
52
|
* any link along the chain looks like a transient network error. Modern APIs
|
|
@@ -50,6 +75,46 @@ export declare function isTransientNetworkError(error: unknown): boolean;
|
|
|
50
75
|
* @returns true when the fault is a client deadline/abort expiry.
|
|
51
76
|
*/
|
|
52
77
|
export declare function isClientDeadlineExpiry(error: unknown): boolean;
|
|
78
|
+
/**
|
|
79
|
+
* Classifies a failure into the typed {@link RetryErrorDetails} taxonomy.
|
|
80
|
+
*
|
|
81
|
+
* **An HTTP status is only ever read from a typed carrier.** There is no path
|
|
82
|
+
* from the characters of an error message to a status, and therefore none to a
|
|
83
|
+
* retry decision derived from a status (F-0035). A throw site that wants its
|
|
84
|
+
* status honoured must attach it: throw the `Response`, set `response.status`
|
|
85
|
+
* (axios / the Alpaca SDK do this), set a numeric `status` / `statusCode`, or
|
|
86
|
+
* raise an {@link AdapticUtilsError}. A plain `Error` whose text mentions
|
|
87
|
+
* "429", "503" or "CLIENT_ERROR: 422" is `UNKNOWN` and is **not** retried.
|
|
88
|
+
*
|
|
89
|
+
* Precedence, strongest evidence first:
|
|
90
|
+
*
|
|
91
|
+
* 1. an explicit `Response`, or a thrown `Response`;
|
|
92
|
+
* 2. a **typed** carrier — {@link AdapticUtilsError} (status, else its declared
|
|
93
|
+
* `isRetryable`), `error.response.status` (axios / Alpaca SDK), or a numeric
|
|
94
|
+
* `error.status` / `error.statusCode`;
|
|
95
|
+
* 3. transient network conditions — {@link isTransientNetworkError}, which
|
|
96
|
+
* reads `error.code` / `error.name` / the `cause` chain. This decides
|
|
97
|
+
* *transience*, never a status, so it can never turn a broker rejection into
|
|
98
|
+
* a 5xx; a rejection that carries a typed status is already resolved above;
|
|
99
|
+
* 4. otherwise `UNKNOWN`, which is **not** retryable.
|
|
100
|
+
*
|
|
101
|
+
* @param error - The thrown value.
|
|
102
|
+
* @param response - Optional Response already in hand for this failure.
|
|
103
|
+
* @param config - Optional retry-configuration overrides.
|
|
104
|
+
* @returns The typed classification.
|
|
105
|
+
*/
|
|
106
|
+
export declare function classifyRetryError(error: unknown, response?: Response | null, config?: Partial<RetryConfig>): RetryErrorDetails;
|
|
107
|
+
/**
|
|
108
|
+
* Calculates the delay before the next retry attempt using exponential backoff
|
|
109
|
+
* with jitter, capped at `maxDelay`. Exported so the backoff contract (growth,
|
|
110
|
+
* cap, jitter) is directly testable rather than only observable through timers.
|
|
111
|
+
*
|
|
112
|
+
* @param attempt - Current attempt number (1-indexed)
|
|
113
|
+
* @param baseDelay - Base delay in milliseconds
|
|
114
|
+
* @param maxDelay - Maximum delay in milliseconds (before jitter)
|
|
115
|
+
* @returns Delay in milliseconds
|
|
116
|
+
*/
|
|
117
|
+
export declare function calculateRetryBackoff(attempt: number, baseDelay: number, maxDelay: number): number;
|
|
53
118
|
/**
|
|
54
119
|
* Wraps an async function with retry logic and exponential backoff.
|
|
55
120
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/retry.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/retry.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,yDAAyD;IACzD,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,YAAY,GACZ,cAAc,GACd,cAAc,GACd,YAAY,GACZ,eAAe,GACf,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;CACtB;AAwED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA+B/D;AAqCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAqC9D;AAmMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,QAAQ,GAAG,IAAW,EAChC,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAChC,iBAAiB,CAmDnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAWR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,EACjC,KAAK,GAAE,MAAkB,GACxB,OAAO,CAAC,CAAC,CAAC,CA0HZ;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAoClE,CAAC"}
|