nxus-qbd 0.7.2 → 1.0.0

package/dist/transport.d.ts

@@ -4,6 +4,7 @@
  * Handles authentication, base URL resolution, JSON serialization,
  * and error mapping for all SDK requests.
  */
+import type { TransportResponse } from "./helpers/response.js";
 export declare const DEFAULT_TIMEOUT_MS = 100000;
 export declare const DEFAULT_MAX_RETRIES = 2;
 /**
@@ -22,6 +23,8 @@ export interface TransportOptions {
     baseUrl: string;
     /** API key for authentication. */
     apiKey: string;
+    /** Default connection ID for request scoping (sets X-Connection-Id). */
+    connectionId?: string;
     /** Default headers merged into every request. */
     headers?: Record<string, string>;
     /** Default request timeout in milliseconds. */
@@ -56,8 +59,8 @@ export interface TransportOptions {
      * without `x-should-retry` to disambiguate the safe default is to surface
      * the error to the caller.
      *
-     * The local timeout abort (`timeout`) is treated as a non-retryable
-     * cancellation.
+     * Local timeout aborts are retried only for generic Create calls carrying an
+     * idempotency key. Other calls treat a local timeout as cancellation.
      */
     maxRetries?: number;
     /**
@@ -90,6 +93,15 @@ export interface TransportOptions {
 export interface RequestOptions {
     /** Connection ID for per-request scoping (sets X-Connection-Id header). */
     connectionId?: string;
+    /**
+     * Idempotency key for a logical Create operation (sets Idempotency-Key).
+     *
+     * Generic resource Create methods generate a cryptographically random key
+     * when this is omitted, then retain it for every transport retry. Supply a
+     * durable, application-owned key when a workflow can resume in a later
+     * process.
+     */
+    idempotencyKey?: string;
     /** Extra headers for this request. */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds (overrides the default). */
@@ -114,10 +126,22 @@ export interface RequestOptions {
      * Merged on top of {@link TransportOptions.fetchOptions}.
      */
     fetchOptions?: Record<string, unknown>;
+    /**
+     * Retain the undecoded response body on `NxusResponse.rawBody`.
+     *
+     * Off by default: keeping the raw text for every call would hold a second
+     * full copy of every payload alive for as long as the wrapper lives, which
+     * is pure waste when the caller only wants a status code or a request id.
+     * Has no effect on plain (unwrapped) calls, which discard the snapshot.
+     */
+    includeRawBody?: boolean;
 }
+/** @internal Marks only SDK-owned generic Create options as timeout-retryable. */
+export declare function enableIdempotentCreateTimeoutRetry(options: RequestOptions): RequestOptions;
 export declare class NxusHttpTransport {
     private readonly baseUrl;
     private readonly apiKey;
+    private readonly defaultConnectionId?;
     private readonly defaultHeaders;
     private readonly defaultTimeout;
     private readonly defaultServerTimeoutSeconds?;
@@ -131,21 +155,48 @@ export declare class NxusHttpTransport {
     get<T>(path: string, query?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
     post<T>(path: string, body?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
     delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** @internal */
+    deleteWithBody<T>(path: string, body: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Snapshot-returning counterparts of `get`/`post`/`delete`.
+     *
+     * These are the real implementations; the three above are thin wrappers that
+     * discard the metadata. Both paths therefore share one retry loop, one error
+     * translation, and one parse — metadata-aware calls cannot drift from plain
+     * ones.
+     *
+     * @internal
+     */
+    sendGet<T>(path: string, query?: Record<string, unknown>, options?: RequestOptions): Promise<TransportResponse<T>>;
+    /** @internal */
+    sendPost<T>(path: string, body?: Record<string, unknown>, options?: RequestOptions): Promise<TransportResponse<T>>;
+    /** @internal */
+    sendDelete<T>(path: string, options?: RequestOptions): Promise<TransportResponse<T>>;
+    /** @internal */
+    sendDeleteWithBody<T>(path: string, body: Record<string, unknown>, options?: RequestOptions): Promise<TransportResponse<T>>;
     /**
      * Issue a raw HTTP request and return the unparsed `Response`.
      *
-     * Use this when you need direct access to status, headers, or the response
-     * body as a stream/blob/text. Bypasses JSON parsing and the typed error
-     * mapping, but still applies authentication, the default headers, the
-     * timeout, and retries. Non-2xx responses are returned, not thrown — the
-     * caller is responsible for `response.ok` handling.
+     * Gives direct access to status, headers, and the response body as a
+     * stream/blob/text. Bypasses JSON parsing and the typed error mapping, but
+     * still applies authentication, the default headers, the timeout, and
+     * retries. Non-2xx responses are returned, not thrown — the caller is
+     * responsible for `response.ok` handling.
+     *
+     * **SDK-internal.** `NxusClient.transport` is private, so this is not
+     * reachable from consumer code. The previous `@example` here showed
+     * `client.transport.raw(...)`, which does not compile. Consumers needing
+     * status/headers/request-id should not reach for the transport — that is
+     * what the planned public response wrapper is for.
      *
      * @example
      * ```ts
-     * const res = await client.transport.raw('/api/v1/vendors', { method: 'GET' });
-     * console.log(res.status, res.headers.get('x-request-id'));
-     * const blob = await res.blob();
+     * // Internal use only — see resources/custom-fields.ts `deleteWithBody`,
+     * // which needs a JSON body on DELETE and maps non-2xx onto NxusApiError.
+     * const res = await this.transport.raw(path, { method: 'DELETE', body });
      * ```
+     *
+     * @internal
      */
     raw(path: string, init?: RequestInit & {
         query?: Record<string, unknown>;

package/dist/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}