@aligent/microservice-util-lib 1.4.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/microservice-util-lib",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A set of utility functions for Aligent Microservices",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -2,11 +2,11 @@ import chunkBy from './chunk-by/chunk-by';
 import fetchSsmParams from './fetch-ssm-params/fetch-ssm-params';
 import getAwsIdFromArn from './get-aws-id-from-arn/get-aws-id-from-arn';
 import hasDefinedProperties from './has-properties-defined/has-properties-defined';
-import { ApiKey, Basic, OAuth10a, OAuth20, apiKeyAuthMiddleware, basicAuthMiddleware, oAuth10aAuthMiddleware, oAuth20AuthMiddleware } from './openapi-fetch-middlewares/authentications';
+import { ApiKey, Basic, OAuth10a, OAuth20, apiKeyAuthMiddleware, basicAuthMiddleware, oAuth10aAuthMiddleware, oAuth20AuthMiddleware, resignOauth10aRequest } from './openapi-fetch-middlewares/authentications';
 import { LogLevel, Logger, logMiddleware } from './openapi-fetch-middlewares/log';
 import { RetryConfig as RetryMiddlewareConfig, retryMiddleware } from './openapi-fetch-middlewares/retry';
 import remap, { ObjectMap, Remap } from './remap/remap';
 import retryWrapper, { RetryConfig } from './retry-wrapper/retry-wrapper';
 import S3Dao from './s3/s3';
 export type { ApiKey, Basic, LogLevel, Logger, OAuth10a, OAuth20, ObjectMap, Remap, RetryConfig, RetryMiddlewareConfig, S3Dao, };
-export { apiKeyAuthMiddleware, basicAuthMiddleware, chunkBy, fetchSsmParams, getAwsIdFromArn, hasDefinedProperties, logMiddleware, oAuth10aAuthMiddleware, oAuth20AuthMiddleware, remap, retryMiddleware, retryWrapper, };
+export { apiKeyAuthMiddleware, basicAuthMiddleware, chunkBy, fetchSsmParams, getAwsIdFromArn, hasDefinedProperties, logMiddleware, oAuth10aAuthMiddleware, oAuth20AuthMiddleware, remap, resignOauth10aRequest, retryMiddleware, retryWrapper, };

package/src/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.retryWrapper = exports.retryMiddleware = exports.remap = exports.oAuth20AuthMiddleware = exports.oAuth10aAuthMiddleware = exports.logMiddleware = exports.hasDefinedProperties = exports.getAwsIdFromArn = exports.fetchSsmParams = exports.chunkBy = exports.basicAuthMiddleware = exports.apiKeyAuthMiddleware = void 0;
+exports.retryWrapper = exports.retryMiddleware = exports.resignOauth10aRequest = exports.remap = exports.oAuth20AuthMiddleware = exports.oAuth10aAuthMiddleware = exports.logMiddleware = exports.hasDefinedProperties = exports.getAwsIdFromArn = exports.fetchSsmParams = exports.chunkBy = exports.basicAuthMiddleware = exports.apiKeyAuthMiddleware = void 0;
 /* v8 ignore start */
 const chunk_by_1 = __importDefault(require("./chunk-by/chunk-by"));
 exports.chunkBy = chunk_by_1.default;
@@ -18,6 +18,7 @@ Object.defineProperty(exports, "apiKeyAuthMiddleware", { enumerable: true, get:
 Object.defineProperty(exports, "basicAuthMiddleware", { enumerable: true, get: function () { return authentications_1.basicAuthMiddleware; } });
 Object.defineProperty(exports, "oAuth10aAuthMiddleware", { enumerable: true, get: function () { return authentications_1.oAuth10aAuthMiddleware; } });
 Object.defineProperty(exports, "oAuth20AuthMiddleware", { enumerable: true, get: function () { return authentications_1.oAuth20AuthMiddleware; } });
+Object.defineProperty(exports, "resignOauth10aRequest", { enumerable: true, get: function () { return authentications_1.resignOauth10aRequest; } });
 const log_1 = require("./openapi-fetch-middlewares/log");
 Object.defineProperty(exports, "logMiddleware", { enumerable: true, get: function () { return log_1.logMiddleware; } });
 const retry_1 = require("./openapi-fetch-middlewares/retry");

package/src/openapi-fetch-middlewares/authentications.d.ts

@@ -1,5 +1,14 @@
 import type { Middleware } from 'openapi-fetch';
-import type { ApiKey, Basic, OAuth10a, OAuth20 } from './types/authentications';
+import { resignOauth10aRequest } from './oauth10a/oauth10a';
+import type { ApiKey, Basic, OAuth10a, OAuth20, Resolvable } from './types/authentications';
+/**
+ * Resolves a `Resolvable<T>` value to its underlying type.
+ * If the value is a function, it is called and awaited; otherwise, it is returned as-is.
+ *
+ * @param {Resolvable<T>} value - The resolvable value.
+ * @returns {Promise<T>} The resolved value.
+ */
+declare function resolve<T>(value: Resolvable<T>): Promise<T>;
 /**
  * Creates an openapi-fetch middleware for API key authentication.
  * This middleware sets the API key in the specified header for each request.
@@ -8,9 +17,17 @@ import type { ApiKey, Basic, OAuth10a, OAuth20 } from './types/authentications';
  * @returns {Middleware} The middleware for API key authentication.
  *
  * @example
+ * // Static value
  * const middleware = apiKeyAuthMiddleware({
  *     header: 'x-api-key',
- *     value: async () => 'your-api-key',
+ *     value: 'your-api-key',
+ * });
+ *
+ * @example
+ * // Dynamic value (async function)
+ * const middleware = apiKeyAuthMiddleware({
+ *     header: 'x-api-key',
+ *     value: async () => fetchApiKey(),
  * });
  */
 declare function apiKeyAuthMiddleware(config: ApiKey): Middleware;
@@ -23,8 +40,15 @@ declare function apiKeyAuthMiddleware(config: ApiKey): Middleware;
  * @returns {Middleware} The middleware for Basic authentication.
  *
  * @example
+ * // Static credentials
+ * const middleware = basicAuthMiddleware({
+ *     credentials: { username: 'user', password: 'pass' },
+ * });
+ *
+ * @example
+ * // Dynamic credentials (async function)
  * const middleware = basicAuthMiddleware({
- *     credentials: async () => ({ username: 'user', password: 'pass' }),
+ *     credentials: async () => fetchCredentials(),
  * });
  */
 declare function basicAuthMiddleware(config: Basic): Middleware;
@@ -37,14 +61,22 @@ declare function basicAuthMiddleware(config: Basic): Middleware;
  * @returns {Middleware} The middleware for OAuth 1.0a authentication.
  *
  * @example
+ * // Static credentials
  * const middleware = oAuth10aAuthMiddleware({
  *     algorithm: 'HMAC-SHA256',
- *     credentials: async () => ({
+ *     credentials: {
  *         consumerKey: 'key',
  *         consumerSecret: 'secret',
  *         token: 'token',
  *         tokenSecret: 'tokenSecret',
- *     }),
+ *     },
+ * });
+ *
+ * @example
+ * // Dynamic credentials (async function)
+ * const middleware = oAuth10aAuthMiddleware({
+ *     algorithm: 'HMAC-SHA256',
+ *     credentials: async () => fetchOAuthCredentials(),
  * });
  */
 declare function oAuth10aAuthMiddleware(config: OAuth10a): Middleware;
@@ -56,11 +88,20 @@ declare function oAuth10aAuthMiddleware(config: OAuth10a): Middleware;
  * @returns {Middleware} The middleware for OAuth 2.0 authentication.
  *
  * @example
+ * // Static token
+ * const middleware = oAuth20AuthMiddleware({
+ *     token: 'your-access-token',
+ *     tokenType: 'Bearer',
+ * });
+ *
+ * @example
+ * // Dynamic token (async function)
  * const middleware = oAuth20AuthMiddleware({
- *     token: async () => 'your-access-token',
+ *     token: async () => fetchAccessToken(),
  *     tokenType: 'Bearer',
  * });
  */
 declare function oAuth20AuthMiddleware(options: OAuth20): Middleware;
-export type { ApiKey, Basic, OAuth10a, OAuth20 };
-export { apiKeyAuthMiddleware, basicAuthMiddleware, oAuth10aAuthMiddleware, oAuth20AuthMiddleware };
+export { resolve };
+export type { ApiKey, Basic, OAuth10a, OAuth20, Resolvable };
+export { apiKeyAuthMiddleware, basicAuthMiddleware, oAuth10aAuthMiddleware, oAuth20AuthMiddleware, resignOauth10aRequest, };

package/src/openapi-fetch-middlewares/authentications.js

@@ -1,10 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resignOauth10aRequest = void 0;
+exports.resolve = resolve;
 exports.apiKeyAuthMiddleware = apiKeyAuthMiddleware;
 exports.basicAuthMiddleware = basicAuthMiddleware;
 exports.oAuth10aAuthMiddleware = oAuth10aAuthMiddleware;
 exports.oAuth20AuthMiddleware = oAuth20AuthMiddleware;
 const oauth10a_1 = require("./oauth10a/oauth10a");
+Object.defineProperty(exports, "resignOauth10aRequest", { enumerable: true, get: function () { return oauth10a_1.resignOauth10aRequest; } });
+/**
+ * Resolves a `Resolvable<T>` value to its underlying type.
+ * If the value is a function, it is called and awaited; otherwise, it is returned as-is.
+ *
+ * @param {Resolvable<T>} value - The resolvable value.
+ * @returns {Promise<T>} The resolved value.
+ */
+async function resolve(value) {
+    return typeof value === 'function' ? await value() : value;
+}
 /**
  * Creates an openapi-fetch middleware for API key authentication.
  * This middleware sets the API key in the specified header for each request.
@@ -13,15 +26,23 @@ const oauth10a_1 = require("./oauth10a/oauth10a");
  * @returns {Middleware} The middleware for API key authentication.
  *
  * @example
+ * // Static value
+ * const middleware = apiKeyAuthMiddleware({
+ *     header: 'x-api-key',
+ *     value: 'your-api-key',
+ * });
+ *
+ * @example
+ * // Dynamic value (async function)
  * const middleware = apiKeyAuthMiddleware({
  *     header: 'x-api-key',
- *     value: async () => 'your-api-key',
+ *     value: async () => fetchApiKey(),
  * });
  */
 function apiKeyAuthMiddleware(config) {
     return {
         onRequest: async ({ request }) => {
-            request.headers.set(config.header, await config.value());
+            request.headers.set(config.header, await resolve(config.value));
         },
     };
 }
@@ -34,14 +55,21 @@ function apiKeyAuthMiddleware(config) {
  * @returns {Middleware} The middleware for Basic authentication.
  *
  * @example
+ * // Static credentials
  * const middleware = basicAuthMiddleware({
- *     credentials: async () => ({ username: 'user', password: 'pass' }),
+ *     credentials: { username: 'user', password: 'pass' },
+ * });
+ *
+ * @example
+ * // Dynamic credentials (async function)
+ * const middleware = basicAuthMiddleware({
+ *     credentials: async () => fetchCredentials(),
  * });
  */
 function basicAuthMiddleware(config) {
     return {
         onRequest: async ({ request }) => {
-            const { username, password } = await config.credentials();
+            const { username, password } = await resolve(config.credentials);
             request.headers.set('Authorization', `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`);
         },
     };
@@ -55,14 +83,22 @@ function basicAuthMiddleware(config) {
  * @returns {Middleware} The middleware for OAuth 1.0a authentication.
  *
  * @example
+ * // Static credentials
  * const middleware = oAuth10aAuthMiddleware({
  *     algorithm: 'HMAC-SHA256',
- *     credentials: async () => ({
+ *     credentials: {
  *         consumerKey: 'key',
  *         consumerSecret: 'secret',
  *         token: 'token',
  *         tokenSecret: 'tokenSecret',
- *     }),
+ *     },
+ * });
+ *
+ * @example
+ * // Dynamic credentials (async function)
+ * const middleware = oAuth10aAuthMiddleware({
+ *     algorithm: 'HMAC-SHA256',
+ *     credentials: async () => fetchOAuthCredentials(),
  * });
  */
 function oAuth10aAuthMiddleware(config) {
@@ -81,8 +117,16 @@ function oAuth10aAuthMiddleware(config) {
  * @returns {Middleware} The middleware for OAuth 2.0 authentication.
  *
  * @example
+ * // Static token
+ * const middleware = oAuth20AuthMiddleware({
+ *     token: 'your-access-token',
+ *     tokenType: 'Bearer',
+ * });
+ *
+ * @example
+ * // Dynamic token (async function)
  * const middleware = oAuth20AuthMiddleware({
- *     token: async () => 'your-access-token',
+ *     token: async () => fetchAccessToken(),
  *     tokenType: 'Bearer',
  * });
  */
@@ -90,7 +134,7 @@ function oAuth20AuthMiddleware(options) {
     return {
         onRequest: async ({ request }) => {
             const { tokenType = 'Bearer' } = options;
-            request.headers.set('Authorization', `${tokenType} ${await options.token()}`);
+            request.headers.set('Authorization', `${tokenType} ${await resolve(options.token)}`);
         },
     };
 }

package/src/openapi-fetch-middlewares/oauth10a/oauth10a.d.ts

@@ -10,3 +10,21 @@ import { OAuth10a } from '../authentications';
  * @returns {Promise<string>} The generated OAuth 1.0a Authorization header.
  */
 export declare function generateOauthParams(request: MiddlewareCallbackParams['request'], options: MiddlewareCallbackParams['options'], params: MiddlewareCallbackParams['params'], config: OAuth10a): Promise<string>;
+/**
+ * Standalone function that re-signs a `Request` with fresh OAuth 1.0a credentials.
+ * This function derives all information (URL, method, query params, body)
+ * directly from the `Request` object, without requiring openapi-fetch middleware context.
+ *
+ * Designed for use with the retry middleware's `onRetry` hook to regenerate
+ * OAuth 1.0a signatures on retried requests.
+ *
+ * @param {Request} request - The request to re-sign.
+ * @param {OAuth10a} config - The OAuth 1.0a configuration.
+ * @returns {Promise<Request>} The request with a fresh `Authorization` header.
+ *
+ * @example
+ * client.use(retryMiddleware({
+ *     onRetry: ({ request }) => resignOauth10aRequest(request, config),
+ * }));
+ */
+export declare function resignOauth10aRequest(request: Request, config: OAuth10a): Promise<Request>;

package/src/openapi-fetch-middlewares/oauth10a/oauth10a.js

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateOauthParams = generateOauthParams;
+exports.resignOauth10aRequest = resignOauth10aRequest;
 const crypto_1 = __importDefault(require("crypto"));
 const oauth_sign_1 = require("oauth-sign");
+const authentications_1 = require("../authentications");
 /**
  * Determines whether a given URL is absolute.
  *
@@ -129,25 +131,16 @@ function shouldGenerateBodyHash(body, method, includeBodyHash) {
     return includeBodyHash === true;
 }
 /**
- * Generates OAuth 1.0a parameters for signing a request.
+ * Core signing logic shared by both the middleware path and the standalone re-sign path.
  *
- * @param {MiddlewareCallbackParams['request']} request - The request object.
- * @param {MiddlewareCallbackParams['options']} options - The options object.
- * @param {MiddlewareCallbackParams['params']} params - The parameters object.
- * @param {OAuth10a} config - The OAuth 1.0a configuration.
- * @returns {Promise<string>} The generated OAuth 1.0a Authorization header.
+ * @param input - The request details needed for signing.
+ * @param config - The OAuth 1.0a configuration.
+ * @returns The OAuth 1.0a Authorization header value (without the "OAuth " prefix).
  */
-async function generateOauthParams(request, options, params, config) {
+async function signOauth10a(input, config) {
     const { algorithm, includeBodyHash = 'auto', realm, callback, verifier } = config;
-    const { consumerKey, consumerSecret, token, tokenSecret } = await config.credentials();
-    // Due to the way that openapi-fetch & fetch API are implemented in NodeJS (undici),
-    // each request only can be used ONCE. We have to clone the request like this to extract information
-    // Otherwise, undici will not be able to create & send the request.
-    const clonedRequest = request.clone();
-    const method = (clonedRequest.method || 'GET').toUpperCase();
-    const url = combineUrlAndPathParams(clonedRequest.url, params.path);
-    const contentType = clonedRequest.headers.get('Content-Type');
-    const body = await clonedRequest.text();
+    const { method, oauthUrl, body, contentType, query } = input;
+    const { consumerKey, consumerSecret, token, tokenSecret } = await (0, authentications_1.resolve)(config.credentials);
     const oauthParams = {
         oauth_consumer_key: consumerKey,
         oauth_nonce: crypto_1.default.randomUUID(),
@@ -168,8 +161,8 @@ async function generateOauthParams(request, options, params, config) {
     }
     const paramsToSign = {};
     addParamsToSign(paramsToSign, oauthParams);
-    if (params.query) {
-        addParamsToSign(paramsToSign, params.query);
+    if (query) {
+        addParamsToSign(paramsToSign, query);
     }
     // If user submit a form, then include form parameters in the
     // signature as parameters rather than the body hash
@@ -184,7 +177,6 @@ async function generateOauthParams(request, options, params, config) {
         oauthParams.oauth_body_hash = bodyHash;
         addParamToSign(paramsToSign, 'oauth_body_hash', bodyHash);
     }
-    const oauthUrl = getOAuthUrl(options.baseUrl, url);
     oauthParams.oauth_signature = (0, oauth_sign_1.sign)(algorithm, method, oauthUrl, paramsToSign, consumerSecret, tokenSecret);
     // realm should not be included in the signature calculation
     // but is optional in the OAuth 1.0 Authorization header
@@ -197,3 +189,55 @@ async function generateOauthParams(request, options, params, config) {
         .map(e => [e[0], '="', (0, oauth_sign_1.rfc3986)(e[1]), '"'].join(''))
         .join(',');
 }
+/**
+ * Generates OAuth 1.0a parameters for signing a request.
+ *
+ * @param {MiddlewareCallbackParams['request']} request - The request object.
+ * @param {MiddlewareCallbackParams['options']} options - The options object.
+ * @param {MiddlewareCallbackParams['params']} params - The parameters object.
+ * @param {OAuth10a} config - The OAuth 1.0a configuration.
+ * @returns {Promise<string>} The generated OAuth 1.0a Authorization header.
+ */
+async function generateOauthParams(request, options, params, config) {
+    const clonedRequest = request.clone();
+    const method = (clonedRequest.method || 'GET').toUpperCase();
+    const url = combineUrlAndPathParams(clonedRequest.url, params.path);
+    return signOauth10a({
+        method,
+        oauthUrl: getOAuthUrl(options.baseUrl, url),
+        contentType: clonedRequest.headers.get('Content-Type'),
+        body: await clonedRequest.text(),
+        query: params.query,
+    }, config);
+}
+/**
+ * Standalone function that re-signs a `Request` with fresh OAuth 1.0a credentials.
+ * This function derives all information (URL, method, query params, body)
+ * directly from the `Request` object, without requiring openapi-fetch middleware context.
+ *
+ * Designed for use with the retry middleware's `onRetry` hook to regenerate
+ * OAuth 1.0a signatures on retried requests.
+ *
+ * @param {Request} request - The request to re-sign.
+ * @param {OAuth10a} config - The OAuth 1.0a configuration.
+ * @returns {Promise<Request>} The request with a fresh `Authorization` header.
+ *
+ * @example
+ * client.use(retryMiddleware({
+ *     onRetry: ({ request }) => resignOauth10aRequest(request, config),
+ * }));
+ */
+async function resignOauth10aRequest(request, config) {
+    const clonedRequest = request.clone();
+    const method = (clonedRequest.method || 'GET').toUpperCase();
+    const parsedUrl = new URL(clonedRequest.url);
+    const oauthParams = await signOauth10a({
+        method,
+        oauthUrl: getOAuthUrl(parsedUrl.origin, parsedUrl.pathname),
+        contentType: clonedRequest.headers.get('Content-Type'),
+        body: await clonedRequest.text(),
+        query: parsedUrl.search ? parsedUrl.searchParams : undefined,
+    }, config);
+    request.headers.set('Authorization', `OAuth ${oauthParams}`);
+    return request;
+}

package/src/openapi-fetch-middlewares/retry.d.ts

@@ -18,14 +18,31 @@ export type { HttpRequestData, HttpResponseData } from './utils/http-response-er
  * const middleware = retryMiddleware();
  *
  * @example
- * // Custom configuration
+ * // Custom configuration with logging
  * const middleware = retryMiddleware({
  *     retries: 5,
  *     retryDelay: 'linear',
  *     baseDelay: 200,
  *     retryOn: [500, 502, 503, 504],
  *     onRetry: (context) => {
- *         console.log(`Retrying request (attempt ${context.attemptNumber})`);
+ *         console.log(`Retrying request (attempt ${context.attempt})`);
+ *     },
+ * });
+ *
+ * @example
+ * // Re-sign OAuth 1.0a requests on retry (returns a Request to replace the original)
+ * const middleware = retryMiddleware({
+ *     retries: 3,
+ *     onRetry: (context) => resignOauth10aRequest(context.request, oauthConfig),
+ * });
+ *
+ * @example
+ * // Combine logging and request transformation in onRetry
+ * const middleware = retryMiddleware({
+ *     retries: 3,
+ *     onRetry: async (context) => {
+ *         console.log(`Retrying request (attempt ${context.attempt})`);
+ *         return resignOauth10aRequest(context.request, oauthConfig);
  *     },
  * });
  *
@@ -35,7 +52,7 @@ export type { HttpRequestData, HttpResponseData } from './utils/http-response-er
  *     retries: 3,
  *     retryCondition: async (context) => {
  *         // Only retry on 503 Service Unavailable
- *         return context.response.status === 503;
+ *         return context.response?.status === 503;
  *     },
  * });
  *

package/src/openapi-fetch-middlewares/retry.js

@@ -118,14 +118,31 @@ async function throwErrorIfNotOkResponse(response, request, throwOnNotOk) {
  * const middleware = retryMiddleware();
  *
  * @example
- * // Custom configuration
+ * // Custom configuration with logging
  * const middleware = retryMiddleware({
  *     retries: 5,
  *     retryDelay: 'linear',
  *     baseDelay: 200,
  *     retryOn: [500, 502, 503, 504],
  *     onRetry: (context) => {
- *         console.log(`Retrying request (attempt ${context.attemptNumber})`);
+ *         console.log(`Retrying request (attempt ${context.attempt})`);
+ *     },
+ * });
+ *
+ * @example
+ * // Re-sign OAuth 1.0a requests on retry (returns a Request to replace the original)
+ * const middleware = retryMiddleware({
+ *     retries: 3,
+ *     onRetry: (context) => resignOauth10aRequest(context.request, oauthConfig),
+ * });
+ *
+ * @example
+ * // Combine logging and request transformation in onRetry
+ * const middleware = retryMiddleware({
+ *     retries: 3,
+ *     onRetry: async (context) => {
+ *         console.log(`Retrying request (attempt ${context.attempt})`);
+ *         return resignOauth10aRequest(context.request, oauthConfig);
  *     },
  * });
  *
@@ -135,7 +152,7 @@ async function throwErrorIfNotOkResponse(response, request, throwOnNotOk) {
  *     retries: 3,
  *     retryCondition: async (context) => {
  *         // Only retry on 503 Service Unavailable
- *         return context.response.status === 503;
+ *         return context.response?.status === 503;
  *     },
  * });
  *
@@ -204,7 +221,10 @@ async function performRetries(config, context) {
         const delay = await config.retryDelay(attempt, { ...context, attempt, response });
         await new Promise(resolve => setTimeout(resolve, delay));
         if (config.onRetry) {
-            await config.onRetry({ ...context, attempt, response });
+            const mutatedReq = await config.onRetry({ ...context, attempt, response });
+            if (mutatedReq instanceof Request) {
+                context = { ...context, attempt, request: mutatedReq };
+            }
         }
         try {
             const clonedRequest = context.request.clone();

package/src/openapi-fetch-middlewares/types/authentications.d.ts

@@ -1,28 +1,44 @@
+/**
+ * A value that can be provided either statically or as a function (sync or async).
+ * Used by authentication config interfaces to allow both static credentials
+ * and dynamic credential retrieval (e.g., from a secrets manager).
+ *
+ * @example
+ * // Static value
+ * const value: Resolvable<string> = 'my-api-key';
+ *
+ * // Sync function
+ * const value: Resolvable<string> = () => getKey();
+ *
+ * // Async function
+ * const value: Resolvable<string> = async () => await fetchKey();
+ */
+export type Resolvable<T> = T | (() => T | Promise<T>);
 /**
  * Represents an API key authentication method.
  *
  * This interface is used for API key-based authentication, where the key is sent
- * in a specific header. The value of the API key is retrieved asynchronously.
+ * in a specific header. The value can be a static string or a function that returns one.
  *
  * @interface ApiKey
  * @property {string} header - The header name where the API key will be set.
- * @property {() => Promise<string>} value - A function that returns a promise resolving to the API key value.
+ * @property {Resolvable<string>} value - The API key value, or a function returning it.
  */
 export interface ApiKey {
     header: string;
-    value: () => Promise<string>;
+    value: Resolvable<string>;
 }
 /**
  * Represents basic authentication credentials.
  *
  * This interface is used for basic authentication, where the username and password
- * are retrieved asynchronously.
+ * can be provided statically or retrieved dynamically via a function.
  *
  * @interface Basic
- * @property {() => Promise<{ username: string; password: string }>} credentials - A function that returns a promise resolving to the username and password.
+ * @property {Resolvable<{ username: string; password: string }>} credentials - The credentials, or a function returning them.
  */
 export interface Basic {
-    credentials: () => Promise<{
+    credentials: Resolvable<{
         username: string;
         password: string;
     }>;
@@ -31,12 +47,12 @@ export interface Basic {
  * Represents OAuth 1.0a authentication credentials.
  *
  * This interface is used for OAuth 1.0a authentication, where the consumer key, consumer secret,
- * token, and token secret are retrieved asynchronously. It also supports optional parameters
- * like body hash inclusion, realm, callback, and verifier.
+ * token, and token secret can be provided statically or retrieved dynamically via a function.
+ * It also supports optional parameters like body hash inclusion, realm, callback, and verifier.
  *
  * @interface OAuth10a
  * @property {'HMAC-SHA1' | 'HMAC-SHA256'} algorithm - The signing algorithm to use.
- * @property {() => Promise<{ consumerKey: string; consumerSecret: string; token?: string; tokenSecret: string }>} credentials - A function that returns a promise resolving to the OAuth 1.0a credentials.
+ * @property {Resolvable<{ consumerKey: string; consumerSecret: string; token?: string; tokenSecret: string }>} credentials - The OAuth 1.0a credentials, or a function returning them.
  * @property {boolean | 'auto'} [includeBodyHash] - Whether to include a body hash in the signature. Defaults to 'auto'.
  * @property {string} [realm] - The realm parameter for the Authorization header.
  * @property {string} [callback] - The callback URL for OAuth 1.0a.
@@ -44,7 +60,7 @@ export interface Basic {
  */
 export interface OAuth10a {
     algorithm: 'HMAC-SHA1' | 'HMAC-SHA256';
-    credentials: () => Promise<{
+    credentials: Resolvable<{
         consumerKey: string;
         consumerSecret: string;
         token?: string;
@@ -58,14 +74,15 @@ export interface OAuth10a {
 /**
  * Represents OAuth 2.0 authentication credentials.
  *
- * This interface is used for OAuth 2.0 authentication, where an access token is retrieved
- * asynchronously. It also supports an optional token type (e.g., 'Bearer').
+ * This interface is used for OAuth 2.0 authentication, where an access token can be
+ * provided statically or retrieved dynamically via a function.
+ * It also supports an optional token type (e.g., 'Bearer').
  *
  * @interface OAuth20
- * @property {() => Promise<string>} token - A function that returns a promise resolving to the access token.
+ * @property {Resolvable<string>} token - The access token, or a function returning it.
  * @property {string} [tokenType] - The type of the token (e.g., 'Bearer'). Defaults to 'Bearer' if not specified.
  */
 export interface OAuth20 {
-    token: () => Promise<string>;
+    token: Resolvable<string>;
     tokenType?: string;
 }

package/src/openapi-fetch-middlewares/types/retry.d.ts

@@ -35,10 +35,15 @@ export type RetryDelayFn = (attempt: number, context: RetryContext) => number |
  * Function type for the onRetry callback.
  * Called before each retry attempt.
  *
+ * - If the function returns a `Request` (or `Promise<Request>`), that request replaces
+ *   the current one for the retry attempt. This is useful for regenerating authentication
+ *   headers (e.g., OAuth 1.0a re-signing).
+ * - If the function returns `void`, the original request is used as-is.
+ *
  * @param {RetryContext} context - The retry context containing attempt information.
- * @returns {void | Promise<void>}
+ * @returns {Request | void | Promise<Request | void>}
  */
-export type OnRetryFn = (context: RetryContext) => void | Promise<void>;
+export type OnRetryFn = (context: RetryContext) => Request | void | Promise<Request | void>;
 /**
  * Configuration for the retry middleware.
  *
@@ -61,7 +66,11 @@ export type OnRetryFn = (context: RetryContext) => void | Promise<void>;
  * @property {number} [baseDelay=100] - Base delay in milliseconds for built-in delay strategies.
  * @property {number} [maxDelay=30000] - Maximum delay in milliseconds between retry attempts.
  * @property {boolean} [shouldResetTimeout=false] - Whether to reset the timeout between retries.
- * @property {OnRetryFn} [onRetry] - Callback function executed before each retry attempt.
+ * @property {OnRetryFn} [onRetry]
+ * - Callback executed before each retry attempt (not the initial request).
+ * - If it returns a `Request`, that request replaces the current one for the retry.
+ *   Useful for regenerating authentication headers (e.g., OAuth 1.0a re-signing).
+ * - If it returns `void`, the original request is used as-is.
  * @property {number[]} [retryOn]
  * - Array of HTTP status codes that should trigger a retry.
  * - Defaults to 5xx, 429, and 408 errors.