@discover-cloud/shared 1.2.9 → 1.3.0

package/dist/errors/app-error.js

@@ -1,34 +1,28 @@
 "use strict";
+/**
+ * @file app-error.ts
+ * @description Base class for operational errors throughout the application ecosystem.
+ * Structured to support clean serialization in global error boundaries.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppError = void 0;
 /**
- * APP ERROR  (@discover-cloud/shared)
- * ─────────────────────────────────────
- * Base class for all known operational errors across every service.
- * Subclasses (see http-errors.ts) map to specific HTTP status codes and
- * error codes that the global error handler serialises into responses.
- *
- * Design decisions:
- *   - GlobalErrorHandler catches `instanceof AppError` — no duck-typing,
- *     no accidental matches on arbitrary thrown objects.
- *   - details?: unknown (not any) — TypeScript's type checking is preserved
- *     on the most variable field. Callers that need a specific details shape
- *     should cast after an instanceof guard.
- *   - Object.freeze(this) — prevents accidental post-construction mutation of
- *     a thrown error. Freeze is shallow: if details is an object, its contents
- *     remain mutable. This is acceptable — details is for logging/response
- *     context, not program logic.
- *   - captureStackTrace — strips the AppError constructor frame from the stack
- *     so the trace points to the throw site, not the base class constructor.
+ * Base operational error class. Extends standard Error with application-specific
+ * machine codes and HTTP status mapping.
  */
 class AppError extends Error {
+    /**
+     * @param {string} code       - Machine-readable stable error code identifier.
+     * @param {number} statusCode - Target HTTP status code mapping (e.g. 404, 409).
+     * @param {string} message    - Human-readable error message.
+     * @param {unknown} [details]  - Optional structured context context data.
+     */
     constructor(code, statusCode, message, details) {
         super(message);
         this.code = code;
         this.statusCode = statusCode;
         this.details = details;
-        this.name = this.constructor.name; // "NotFoundError", "ConflictError", etc.
-        // Available in V8 (Node.js / Chrome) — no-ops gracefully in other engines.
+        this.name = this.constructor.name;
         if (typeof Error.captureStackTrace === "function") {
             Error.captureStackTrace(this, this.constructor);
         }

package/dist/errors/http-errors.d.ts

@@ -1,47 +1,135 @@
+/**
+ * @file http-errors.ts
+ * @description Operational error subclasses mapping common HTTP status codes to AppError types.
+ */
 import { AppError } from "./app-error";
 /**
- * HTTP ERRORS  (@discover-cloud/shared)
- * ───────────────────────────────────────
- * Typed subclasses of AppError for every common HTTP error status.
- *
- * GlobalErrorHandler catches these via `instanceof AppError` and maps
- * statusCode + code directly to the response — no additional switch/if needed.
- *
- * Usage:
- *   throw new NotFoundError("Account not found");
- *   throw new ConflictError("Email already in use");
- *   throw new BadRequestError("Validation failed", { field: "email" });
- *
- * Adding a new error type:
- *   1. Add a subclass here following the existing pattern.
- *   2. Pick the correct HTTP status code.
- *   3. Choose a SCREAMING_SNAKE_CASE code that is stable across versions
- *      (clients may key on it for error handling).
+ * 400 Bad Request error.
  */
 export declare class BadRequestError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 401 Unauthorized error.
+ */
 export declare class UnauthorizedError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 403 Forbidden error.
+ */
 export declare class ForbiddenError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 404 Not Found error.
+ */
 export declare class NotFoundError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 410 Gone error.
+ */
+export declare class GoneError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 409 Conflict error.
+ */
 export declare class ConflictError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 422 Unprocessable Entity error.
+ */
 export declare class UnprocessableEntityError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 429 Too Many Requests error.
+ */
 export declare class TooManyRequestsError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 500 Internal Server Error.
+ */
 export declare class InternalServerError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 503 Service Unavailable error.
+ */
 export declare class ServiceUnavailableError extends AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 403 Account Pending Deletion error.
+ *
+ * Thrown when a soft-deleted user account is accessed in a context that does
+ * not allow implicit restore (e.g. login). The client should present a recovery
+ * prompt rather than treating this as a generic auth failure.
+ */
+export declare class AccountPendingDeletionError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 403 Organization Pending Deletion error.
+ *
+ * Thrown when a soft-deleted organization is accessed in a context that does
+ * not allow implicit restore (e.g. slug conflict on create). The client should
+ * prompt the user to restore the organization instead.
+ */
+export declare class OrganizationPendingDeletionError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 403 Workspace Pending Deletion error.
+ *
+ * Thrown when a soft-deleted workspace is accessed in a context that does
+ * not allow implicit restore (e.g. slug conflict on create). The client should
+ * prompt the user to restore the workspace instead.
+ */
+export declare class WorkspacePendingDeletionError extends AppError {
     constructor(message?: string, details?: unknown);
 }

package/dist/errors/http-errors.js

@@ -1,92 +1,177 @@
 "use strict";
+/**
+ * @file http-errors.ts
+ * @description Operational error subclasses mapping common HTTP status codes to AppError types.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServiceUnavailableError = exports.InternalServerError = exports.TooManyRequestsError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = void 0;
+exports.WorkspacePendingDeletionError = exports.OrganizationPendingDeletionError = exports.AccountPendingDeletionError = exports.ServiceUnavailableError = exports.InternalServerError = exports.TooManyRequestsError = exports.UnprocessableEntityError = exports.ConflictError = exports.GoneError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = void 0;
 const app_error_1 = require("./app-error");
 /**
- * HTTP ERRORS  (@discover-cloud/shared)
- * ───────────────────────────────────────
- * Typed subclasses of AppError for every common HTTP error status.
- *
- * GlobalErrorHandler catches these via `instanceof AppError` and maps
- * statusCode + code directly to the response — no additional switch/if needed.
- *
- * Usage:
- *   throw new NotFoundError("Account not found");
- *   throw new ConflictError("Email already in use");
- *   throw new BadRequestError("Validation failed", { field: "email" });
- *
- * Adding a new error type:
- *   1. Add a subclass here following the existing pattern.
- *   2. Pick the correct HTTP status code.
- *   3. Choose a SCREAMING_SNAKE_CASE code that is stable across versions
- *      (clients may key on it for error handling).
+ * 400 Bad Request error.
  */
-// 400 — The request is malformed or contains invalid input.
 class BadRequestError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Bad Request", details) {
         super("BAD_REQUEST", 400, message, details);
     }
 }
 exports.BadRequestError = BadRequestError;
-// 401 — No valid credentials were supplied (missing or expired token).
-//        Distinct from 403: the client may retry after authenticating.
+/**
+ * 401 Unauthorized error.
+ */
 class UnauthorizedError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Unauthorized", details) {
         super("UNAUTHORIZED", 401, message, details);
     }
 }
 exports.UnauthorizedError = UnauthorizedError;
-// 403 — Valid credentials were supplied but the caller lacks permission.
-//        Retrying with the same credentials will not help.
+/**
+ * 403 Forbidden error.
+ */
 class ForbiddenError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Forbidden", details) {
         super("FORBIDDEN", 403, message, details);
     }
 }
 exports.ForbiddenError = ForbiddenError;
-// 404 — The requested resource does not exist.
+/**
+ * 404 Not Found error.
+ */
 class NotFoundError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Not Found", details) {
         super("NOT_FOUND", 404, message, details);
     }
 }
 exports.NotFoundError = NotFoundError;
-// 409 — The request conflicts with the current state of the resource
-//        (e.g. duplicate email, concurrent edit conflict).
+/**
+ * 410 Gone error.
+ */
+class GoneError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
+    constructor(message = "Gone", details) {
+        super("GONE", 410, message, details);
+    }
+}
+exports.GoneError = GoneError;
+/**
+ * 409 Conflict error.
+ */
 class ConflictError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Conflict", details) {
         super("CONFLICT", 409, message, details);
     }
 }
 exports.ConflictError = ConflictError;
-// 422 — The request is well-formed but semantically invalid
-//        (e.g. Zod validation passed structurally but business rules failed).
+/**
+ * 422 Unprocessable Entity error.
+ */
 class UnprocessableEntityError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Unprocessable Entity", details) {
         super("UNPROCESSABLE_ENTITY", 422, message, details);
     }
 }
 exports.UnprocessableEntityError = UnprocessableEntityError;
-// 429 — The caller has exceeded the rate limit. Clients should back off.
+/**
+ * 429 Too Many Requests error.
+ */
 class TooManyRequestsError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Too Many Requests", details) {
         super("TOO_MANY_REQUESTS", 429, message, details);
     }
 }
 exports.TooManyRequestsError = TooManyRequestsError;
-// 500 — An unexpected internal error occurred. Should never be thrown
-//        intentionally — use more specific errors wherever possible.
+/**
+ * 500 Internal Server Error.
+ */
 class InternalServerError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Internal Server Error", details) {
         super("INTERNAL_SERVER_ERROR", 500, message, details);
     }
 }
 exports.InternalServerError = InternalServerError;
-// 503 — The service (or a dependency) is temporarily unavailable.
-//        Clients may retry after the indicated delay.
+/**
+ * 503 Service Unavailable error.
+ */
 class ServiceUnavailableError extends app_error_1.AppError {
+    /**
+     * @param {string}  [message] - Error explanation message.
+     * @param {unknown} [details] - Detailed error context.
+     */
     constructor(message = "Service Unavailable", details) {
         super("SERVICE_UNAVAILABLE", 503, message, details);
     }
 }
 exports.ServiceUnavailableError = ServiceUnavailableError;
+/**
+ * 403 Account Pending Deletion error.
+ *
+ * Thrown when a soft-deleted user account is accessed in a context that does
+ * not allow implicit restore (e.g. login). The client should present a recovery
+ * prompt rather than treating this as a generic auth failure.
+ */
+class AccountPendingDeletionError extends app_error_1.AppError {
+    constructor(message = "This account is scheduled for deletion. Recover it within the 30-day window.", details) {
+        super("ACCOUNT_PENDING_DELETION", 403, message, details);
+    }
+}
+exports.AccountPendingDeletionError = AccountPendingDeletionError;
+/**
+ * 403 Organization Pending Deletion error.
+ *
+ * Thrown when a soft-deleted organization is accessed in a context that does
+ * not allow implicit restore (e.g. slug conflict on create). The client should
+ * prompt the user to restore the organization instead.
+ */
+class OrganizationPendingDeletionError extends app_error_1.AppError {
+    constructor(message = "This organization is scheduled for deletion. Restore it within the 30-day window.", details) {
+        super("ORGANIZATION_PENDING_DELETION", 403, message, details);
+    }
+}
+exports.OrganizationPendingDeletionError = OrganizationPendingDeletionError;
+/**
+ * 403 Workspace Pending Deletion error.
+ *
+ * Thrown when a soft-deleted workspace is accessed in a context that does
+ * not allow implicit restore (e.g. slug conflict on create). The client should
+ * prompt the user to restore the workspace instead.
+ */
+class WorkspacePendingDeletionError extends app_error_1.AppError {
+    constructor(message = "This workspace is scheduled for deletion. Restore it within the 30-day window.", details) {
+        super("WORKSPACE_PENDING_DELETION", 403, message, details);
+    }
+}
+exports.WorkspacePendingDeletionError = WorkspacePendingDeletionError;

package/dist/http/index.d.ts

@@ -1 +1,2 @@
 export * from "./service-client";
+export * from "./request-context";

package/dist/http/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./service-client"), exports);
+__exportStar(require("./request-context"), exports);

package/dist/http/request-context.d.ts

@@ -0,0 +1,8 @@
+import { Request } from "express";
+import { UserContext, MachineContext, RequestMetadataContext } from "../types";
+export declare function getUserContext(req: Request): UserContext;
+export declare function getMachineContext(req: Request): MachineContext;
+export declare function getRequestContext(req: Request): RequestMetadataContext;
+export declare function getValidatedBody<T>(req: Request): T;
+export declare function getValidatedParams<T>(req: Request): T;
+export declare function getValidatedQuery<T>(req: Request): T;

package/dist/http/request-context.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUserContext = getUserContext;
+exports.getMachineContext = getMachineContext;
+exports.getRequestContext = getRequestContext;
+exports.getValidatedBody = getValidatedBody;
+exports.getValidatedParams = getValidatedParams;
+exports.getValidatedQuery = getValidatedQuery;
+function getUserContext(req) {
+    const ctx = req.authContext;
+    if (!ctx || ctx.type !== "user") {
+        throw new Error("User context missing. Did you forget requireUser?");
+    }
+    return ctx;
+}
+function getMachineContext(req) {
+    const ctx = req.authContext;
+    if (!ctx || ctx.type !== "machine") {
+        throw new Error("Machine context missing. Did you forget requireMachine?");
+    }
+    return ctx;
+}
+function getRequestContext(req) {
+    if (!req.requestContext) {
+        throw new Error("Request context missing. Did you forget requestContext middleware?");
+    }
+    return req.requestContext;
+}
+function getValidatedBody(req) {
+    return req.validated?.body;
+}
+function getValidatedParams(req) {
+    return req.validated?.params;
+}
+function getValidatedQuery(req) {
+    return req.validated?.query;
+}

package/dist/http/service-client.d.ts

@@ -1,61 +1,114 @@
+/**
+ * @file service-client.ts
+ * @description HTTP client wrapper for service-to-service communication.
+ * Handles automatic JWT forwarding, request correlation tracking via header propagation,
+ * and automatic retry behaviors on transient failures.
+ */
 import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
 import { Request } from "express";
 /**
- * SERVICE CLIENT  (@discover-cloud/shared)
- * ─────────────────────────────────────────
- * HTTP client for service-to-service communication.
- *
- * Two call patterns:
- *
- * Pattern 1 — JWT-forwarding (user-initiated requests)
- *   Pass the current Express Request — Authorization + x-request-id are
- *   forwarded automatically. Used when the downstream service needs to
- *   act on behalf of the authenticated user.
- *   Methods: getWithAuth, postWithAuth, patchWithAuth, deleteWithAuth
- *
- * Pattern 2 — Internal calls (service-initiated, no incoming request)
- *   Pass explicit headers — used when calls originate from service logic
- *   rather than from an HTTP handler (e.g. auth service → user service
- *   during account creation). Caller is responsible for providing the
- *   X-Internal-Secret header.
- *   Methods: get, post, patch, delete
- *
- * Retry strategy:
- *   - Retries on network errors and 5xx responses only (up to 3 attempts,
- *     exponential backoff). 4xx responses are never retried — they are
- *     deterministic caller errors that won't resolve on retry.
- *
- * Timeout:
- *   - 8 seconds per request (covers retry delays separately via axiosRetry).
- *     Adjust per-call via config.timeout if a specific route needs more.
+ * ServiceClient encapsulates an AxiosInstance configured for service-to-service HTTP requests.
+ * Supports token forwarding (Pattern 1) and secure internal calls (Pattern 2).
  */
 export declare class ServiceClient {
     readonly http: AxiosInstance;
+    /**
+     * Initializes the Axios instance with a base URL, timeout, and retry rules.
+     *
+     * @param {string} baseURL - Downstream service base URL.
+     */
     constructor(baseURL: string);
+    /**
+     * Performs an HTTP GET request while forwarding authorization and request headers.
+     *
+     * @param {string}             url    - Request target endpoint relative path.
+     * @param {Request}            req    - The current Express request object.
+     * @param {AxiosRequestConfig} [config] - Optional request configuration parameters.
+     * @returns {Promise<AxiosResponse<T>>} Axios response promise.
+     */
     getWithAuth<T = unknown>(url: string, req: Request, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Performs an HTTP POST request while forwarding authorization and request headers.
+     *
+     * @param {string}             url    - Request target endpoint relative path.
+     * @param {unknown}            data   - JSON request body data payload.
+     * @param {Request}            req    - The current Express request object.
+     * @param {AxiosRequestConfig} [config] - Optional request configuration parameters.
+     * @returns {Promise<AxiosResponse<T>>} Axios response promise.
+     */
     postWithAuth<T = unknown>(url: string, data: unknown, req: Request, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Performs an HTTP PATCH request while forwarding authorization and request headers.
+     *
+     * @param {string}             url    - Request target endpoint relative path.
+     * @param {unknown}            data   - JSON request body data payload.
+     * @param {Request}            req    - The current Express request object.
+     * @param {AxiosRequestConfig} [config] - Optional request configuration parameters.
+     * @returns {Promise<AxiosResponse<T>>} Axios response promise.
+     */
     patchWithAuth<T = unknown>(url: string, data: unknown, req: Request, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Performs an HTTP DELETE request while forwarding authorization and request headers.
+     *
+     * @param {string}             url    - Request target endpoint relative path.
+     * @param {Request}            req    - The current Express request object.
+     * @param {AxiosRequestConfig} [config] - Optional request configuration parameters.
+     * @returns {Promise<AxiosResponse<T>>} Axios response promise.
+     */
     deleteWithAuth<T = unknown>(url: string, req: Request, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Performs an HTTP GET request with explicit header configurations.
+     *
+     * @param {string}             url     - Request target endpoint relative path.
+     * @param {Record<string, string>} headers - Header keys and values to attach.
+     * @param {AxiosRequestConfig} [config]  - Optional request configuration parameters.
+     * @returns {Promise<AxiosResponse<T>>} Axios response promise.
+     */
     get<T = unknown>(url: string, headers: Record<string, string>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Performs an HTTP POST request with explicit header configurations.
+     *
+     * @param {string}             url     - Request target endpoint relative path.
+     * @param {unknown}            data    - JSON request body data payload.
+     * @param {Record<string, string>} headers - Header keys and values to attach.
+     * @param {AxiosRequestConfig} [config]  - Optional request configuration parameters.
+     * @returns {Promise<AxiosResponse<T>>} Axios response promise.
+     */
     post<T = unknown>(url: string, data: unknown, headers: Record<string, string>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Performs an HTTP PATCH request with explicit header configurations.
+     *
+     * @param {string}             url     - Request target endpoint relative path.
+     * @param {unknown}            data    - JSON request body data payload.
+     * @param {Record<string, string>} headers - Header keys and values to attach.
+     * @param {AxiosRequestConfig} [config]  - Optional request configuration parameters.
+     * @returns {Promise<AxiosResponse<T>>} Axios response promise.
+     */
     patch<T = unknown>(url: string, data: unknown, headers: Record<string, string>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * Performs an HTTP DELETE request with explicit header configurations.
+     *
+     * @param {string}             url     - Request target endpoint relative path.
+     * @param {Record<string, string>} headers - Header keys and values to attach.
+     * @param {AxiosRequestConfig} [config]  - Optional request configuration parameters.
+     * @returns {Promise<AxiosResponse<T>>} Axios response promise.
+     */
     delete<T = unknown>(url: string, headers: Record<string, string>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
     /**
-     * mergeAuth
-     * Extracts Authorization and x-request-id from the Express request
-     * and merges them into the Axios config headers.
+     * Extracts authorization credentials and tracing identifiers from Express requests
+     * and merges them into Axios config header values.
      *
-     * x-request-id precedence:
-     *   1. req.id — set by express-request-id or equivalent middleware
-     *   2. x-request-id header forwarded from the upstream caller
-     *   3. Synthetic fallback (timestamp) — should not appear in production
-     *      if request-id middleware is wired correctly in the gateway
+     * @param {Request}            req    - The current Express request.
+     * @param {AxiosRequestConfig} [config] - The existing Axios request configuration.
+     * @returns {AxiosRequestConfig} The merged Axios request configuration.
      */
     private mergeAuth;
     /**
-     * mergeHeaders
-     * Merges caller-supplied headers into the Axios config.
-     * Caller-supplied headers take precedence over config.headers.
+     * Integrates user-supplied headers into the request configuration object.
+     *
+     * @param {Record<string, string>} headers - The headers to merge.
+     * @param {AxiosRequestConfig} [config]  - The existing Axios request configuration.
+     * @returns {AxiosRequestConfig} The merged Axios request configuration.
      */
     private mergeHeaders;
 }