fix(sdk): request timeout, network-error normalization, idempotent-only retries, Retry-After, bounded iterate

docs/sdk/reference/client/classes/NetworkError.mdx

@@ -0,0 +1,136 @@
+---
+title: "Class: NetworkError"
+---
+
+# Class: NetworkError
+
+Thrown when a transport-level failure occurs before a response is received —
+a DNS failure, a refused/reset connection, or an otherwise failed `fetch`.
+Has no HTTP status because no response was produced.
+
+## Extends
+
+- [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error)
+
+## Constructors
+
+### Constructor
+
+> **new NetworkError**(`message`, `details?`): `NetworkError`
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `details?` | `unknown` |
+
+#### Returns
+
+`NetworkError`
+
+#### Overrides
+
+[`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`constructor`](/sdk/reference/client/classes/Terminal49Error#constructor)
+
+## Properties
+
+| Property | Modifier | Type | Description | Inherited from |
+| ------ | ------ | ------ | ------ | ------ |
+| <a id="property-cause"></a> `cause?` | `public` | `unknown` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`cause`](/sdk/reference/client/classes/Terminal49Error#property-cause) |
+| <a id="property-details"></a> `details?` | `public` | `unknown` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`details`](/sdk/reference/client/classes/Terminal49Error#property-details) |
+| <a id="property-message"></a> `message` | `public` | `string` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`message`](/sdk/reference/client/classes/Terminal49Error#property-message) |
+| <a id="property-name"></a> `name` | `public` | `string` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`name`](/sdk/reference/client/classes/Terminal49Error#property-name) |
+| <a id="property-stack"></a> `stack?` | `public` | `string` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`stack`](/sdk/reference/client/classes/Terminal49Error#property-stack) |
+| <a id="property-status"></a> `status?` | `public` | `number` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`status`](/sdk/reference/client/classes/Terminal49Error#property-status) |
+| <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`stackTraceLimit`](/sdk/reference/client/classes/Terminal49Error#property-stacktracelimit) |
+
+## Methods
+
+### captureStackTrace()
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `targetObject` | `object` |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`captureStackTrace`](/sdk/reference/client/classes/Terminal49Error#capturestacktrace)
+
+***
+
+### prepareStackTrace()
+
+> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `err` | `Error` |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`prepareStackTrace`](/sdk/reference/client/classes/Terminal49Error#preparestacktrace)

docs/sdk/reference/client/classes/Terminal49Error.mdx

@@ -15,8 +15,10 @@ Base error for all Terminal49 API errors. Subclassed by status-specific errors.
 
 - [`AuthenticationError`](/sdk/reference/client/classes/AuthenticationError)
 - [`AuthorizationError`](/sdk/reference/client/classes/AuthorizationError)
+- [`NetworkError`](/sdk/reference/client/classes/NetworkError)
 - [`NotFoundError`](/sdk/reference/client/classes/NotFoundError)
 - [`RateLimitError`](/sdk/reference/client/classes/RateLimitError)
+- [`TimeoutError`](/sdk/reference/client/classes/TimeoutError)
 - [`UpstreamError`](/sdk/reference/client/classes/UpstreamError)
 - [`ValidationError`](/sdk/reference/client/classes/ValidationError)
 

docs/sdk/reference/client/classes/TimeoutError.mdx

@@ -0,0 +1,135 @@
+---
+title: "Class: TimeoutError"
+---
+
+# Class: TimeoutError
+
+Thrown when a request exceeds the configured request timeout and is aborted
+by the SDK. Has no HTTP status because no response was produced.
+
+## Extends
+
+- [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error)
+
+## Constructors
+
+### Constructor
+
+> **new TimeoutError**(`message?`, `details?`): `TimeoutError`
+
+#### Parameters
+
+| Parameter | Type | Default value |
+| ------ | ------ | ------ |
+| `message` | `string` | `'Request timed out'` |
+| `details?` | `unknown` | `undefined` |
+
+#### Returns
+
+`TimeoutError`
+
+#### Overrides
+
+[`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`constructor`](/sdk/reference/client/classes/Terminal49Error#constructor)
+
+## Properties
+
+| Property | Modifier | Type | Description | Inherited from |
+| ------ | ------ | ------ | ------ | ------ |
+| <a id="property-cause"></a> `cause?` | `public` | `unknown` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`cause`](/sdk/reference/client/classes/Terminal49Error#property-cause) |
+| <a id="property-details"></a> `details?` | `public` | `unknown` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`details`](/sdk/reference/client/classes/Terminal49Error#property-details) |
+| <a id="property-message"></a> `message` | `public` | `string` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`message`](/sdk/reference/client/classes/Terminal49Error#property-message) |
+| <a id="property-name"></a> `name` | `public` | `string` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`name`](/sdk/reference/client/classes/Terminal49Error#property-name) |
+| <a id="property-stack"></a> `stack?` | `public` | `string` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`stack`](/sdk/reference/client/classes/Terminal49Error#property-stack) |
+| <a id="property-status"></a> `status?` | `public` | `number` | - | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`status`](/sdk/reference/client/classes/Terminal49Error#property-status) |
+| <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`stackTraceLimit`](/sdk/reference/client/classes/Terminal49Error#property-stacktracelimit) |
+
+## Methods
+
+### captureStackTrace()
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `targetObject` | `object` |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`captureStackTrace`](/sdk/reference/client/classes/Terminal49Error#capturestacktrace)
+
+***
+
+### prepareStackTrace()
+
+> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `err` | `Error` |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`Terminal49Error`](/sdk/reference/client/classes/Terminal49Error).[`prepareStackTrace`](/sdk/reference/client/classes/Terminal49Error#preparestacktrace)

docs/sdk/reference/client/index.mdx

@@ -12,10 +12,12 @@ description: "Reference index for the Terminal49 TypeScript SDK client module, l
 | [AuthenticationError](/sdk/reference/client/classes/AuthenticationError) | Thrown when the API token is invalid or missing (HTTP 401). |
 | [AuthorizationError](/sdk/reference/client/classes/AuthorizationError) | Thrown when the API token is valid but lacks permission for the request (HTTP 403). |
 | [FeatureNotEnabledError](/sdk/reference/client/classes/FeatureNotEnabledError) | Thrown when the requested feature requires a plan upgrade (HTTP 403). |
+| [NetworkError](/sdk/reference/client/classes/NetworkError) | Thrown when a transport-level failure occurs before a response is received — a DNS failure, a refused/reset connection, or an otherwise failed `fetch`. Has no HTTP status because no response was produced. |
 | [NotFoundError](/sdk/reference/client/classes/NotFoundError) | Thrown when the requested resource does not exist (HTTP 404). |
 | [RateLimitError](/sdk/reference/client/classes/RateLimitError) | Thrown when the API rate limit has been exceeded (HTTP 429). The SDK retries automatically. |
 | [Terminal49Client](/sdk/reference/client/classes/Terminal49Client) | Server-side TypeScript client for the Terminal49 JSON:API. |
 | [Terminal49Error](/sdk/reference/client/classes/Terminal49Error) | Base error for all Terminal49 API errors. Subclassed by status-specific errors. |
+| [TimeoutError](/sdk/reference/client/classes/TimeoutError) | Thrown when a request exceeds the configured request timeout and is aborted by the SDK. Has no HTTP status because no response was produced. |
 | [UpstreamError](/sdk/reference/client/classes/UpstreamError) | Thrown when the carrier or terminal upstream API is unavailable (HTTP 5xx). |
 | [ValidationError](/sdk/reference/client/classes/ValidationError) | Thrown when the request payload fails server-side validation (HTTP 400/422). |
 

docs/sdk/reference/client/interceptors/classes/RetryInterceptor.mdx

@@ -5,6 +5,16 @@ description: "RetryInterceptor class in the Terminal49 TypeScript SDK, automatic
 
 # Class: RetryInterceptor
 
+Retries transient failures with backoff. Two kinds of failure are handled:
+
+ - A response with a retryable status (429 / 5xx), handled in `onResponse`.
+ - A thrown transport error (DNS/connection/"fetch failed"), handled in
+   `onError` — these never reach `onResponse` because `fetch` rejected.
+
+Retries are gated by shouldRetryRequest: idempotent methods are always
+eligible, but non-idempotent writes are only retried when the caller supplied
+an `Idempotency-Key` header. 429 backoff honors the server's `Retry-After`.
+
 ## Constructors
 
 ### Constructor
@@ -26,7 +36,12 @@ description: "RetryInterceptor class in the Terminal49 TypeScript SDK, automatic
 
 ### onError()
 
-> **onError**(`__namedParameters`): `void`
+> **onError**(`__namedParameters`): `Promise`\<`Error` \| `Response`\>
+
+Recover from a thrown transport error by retrying eligible requests. If a
+retry produces a response we return it (openapi-fetch then runs the normal
+`onResponse` chain on it); otherwise we surface a normalized
+NetworkError so error mapping is consistent with the response path.
 
 #### Parameters
 
@@ -36,7 +51,7 @@ description: "RetryInterceptor class in the Terminal49 TypeScript SDK, automatic
 
 #### Returns
 
-`void`
+`Promise`\<`Error` \| `Response`\>
 
 ***
 

docs/sdk/reference/client/interceptors/index.mdx

@@ -11,7 +11,7 @@ description: "Reference for the Terminal49 TypeScript SDK interceptors module, c
 | ------ | ------ |
 | [AuthInterceptor](/sdk/reference/client/interceptors/classes/AuthInterceptor) | - |
 | [ErrorMappingInterceptor](/sdk/reference/client/interceptors/classes/ErrorMappingInterceptor) | - |
-| [RetryInterceptor](/sdk/reference/client/interceptors/classes/RetryInterceptor) | - |
+| [RetryInterceptor](/sdk/reference/client/interceptors/classes/RetryInterceptor) | Retries transient failures with backoff. Two kinds of failure are handled: |
 
 ## Type Aliases
 

docs/sdk/reference/client/interfaces/Terminal49ClientConfig.mdx

@@ -17,3 +17,4 @@ Configuration for [Terminal49Client](/sdk/reference/client/classes/Terminal49Cli
 | <a id="property-defaultformat"></a> `defaultFormat?` | [`ResponseFormat`](/sdk/reference/types/options/type-aliases/ResponseFormat) | Default response format for methods that support mapped responses. Defaults to `raw`. |
 | <a id="property-fetchimpl"></a> `fetchImpl?` | (`input`, `init?`) => `Promise`\<`Response`\> | Optional fetch implementation, useful for tests or custom runtimes. |
 | <a id="property-maxretries"></a> `maxRetries?` | `number` | Number of retry attempts for rate-limit and server errors. Defaults to `2`. |
+| <a id="property-timeoutms"></a> `timeoutMs?` | `number` | Per-request timeout in milliseconds. A hung request is aborted once it elapses and rejected with a `TimeoutError`. Defaults to `30000`. Set to `0` to disable the timeout. |

docs/sdk/reference/client/managers/index.mdx

@@ -20,10 +20,18 @@ description: "Reference for the Terminal49 TypeScript SDK managers module: conta
 | Interface | Description |
 | ------ | ------ |
 | [CreateTrackingRequestFromInferOptions](/sdk/reference/client/managers/interfaces/CreateTrackingRequestFromInferOptions) | - |
+| [IterateOptions](/sdk/reference/client/managers/interfaces/IterateOptions) | Options accepted by BaseManager.createIterator. |
 | [TrackingRequestListFilters](/sdk/reference/client/managers/interfaces/TrackingRequestListFilters) | - |
 
 ## Type Aliases
 
 | Type Alias | Description |
 | ------ | ------ |
 | [TrackingRequestType](/sdk/reference/client/managers/type-aliases/TrackingRequestType) | - |
+
+## Variables
+
+| Variable | Description |
+| ------ | ------ |
+| [DEFAULT\_ITERATE\_MAX\_PAGES](/sdk/reference/client/managers/variables/DEFAULT_ITERATE_MAX_PAGES) | Hard safety caps for BaseManager.createIterator. They exist so a no-op or mistakenly broad filter cannot silently walk the entire dataset (and make thousands of requests). They are deliberately large enough not to interfere with realistic pagination, and can be raised per call via `maxPages` / `maxRows` when a caller genuinely needs more. |
+| [DEFAULT\_ITERATE\_MAX\_ROWS](/sdk/reference/client/managers/variables/DEFAULT_ITERATE_MAX_ROWS) | - |

docs/sdk/reference/client/managers/interfaces/IterateOptions.mdx

@@ -0,0 +1,15 @@
+---
+title: "Interface: IterateOptions"
+---
+
+# Interface: IterateOptions
+
+Options accepted by BaseManager.createIterator.
+
+## Properties
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="property-maxpages"></a> `maxPages?` | `number` | Maximum number of pages to fetch. Defaults to [DEFAULT\_ITERATE\_MAX\_PAGES](/sdk/reference/client/managers/variables/DEFAULT_ITERATE_MAX_PAGES). |
+| <a id="property-maxrows"></a> `maxRows?` | `number` | Maximum number of rows to yield. Defaults to [DEFAULT\_ITERATE\_MAX\_ROWS](/sdk/reference/client/managers/variables/DEFAULT_ITERATE_MAX_ROWS). |
+| <a id="property-pagesize"></a> `pageSize?` | `number` | Records per page passed to the underlying list call. |

docs/sdk/reference/client/managers/variables/DEFAULT_ITERATE_MAX_PAGES.mdx

@@ -0,0 +1,13 @@
+---
+title: "Variable: DEFAULT\\_ITERATE\\_MAX\\_PAGES"
+---
+
+# Variable: DEFAULT\_ITERATE\_MAX\_PAGES
+
+> `const` **DEFAULT\_ITERATE\_MAX\_PAGES**: `1000` = `1000`
+
+Hard safety caps for BaseManager.createIterator. They exist so a no-op
+or mistakenly broad filter cannot silently walk the entire dataset (and make
+thousands of requests). They are deliberately large enough not to interfere
+with realistic pagination, and can be raised per call via
+`maxPages` / `maxRows` when a caller genuinely needs more.