@algolia/client-common 5.56.0 → 5.59.0

package/dist/common.d.ts

@@ -261,6 +261,10 @@ type Logger = {
      * Logs info messages.
      */
     info: (message: string, args?: any | undefined) => Promise<void>;
+    /**
+     * Logs warning messages. When not implemented, warnings fall back to `console.warn` so they stay visible with the default no-op logger.
+     */
+    warn?: (message: string, args?: any | undefined) => Promise<void>;
     /**
      * Logs error messages.
      */
@@ -373,6 +377,12 @@ type TransporterOptions = {
      * retry strategy.
      */
     timeouts: Timeouts;
+    /**
+     * How many times to wait and retry on the same host after HTTP 429.
+     * Default is 3. `0` fails on the first 429 (no wait).
+     * Wait time is `Retry-After` in whole seconds, or 1 second if the header is missing or invalid.
+     */
+    maxRateLimitRetries?: number | undefined;
     /**
      * The hosts used by the requester.
      */
@@ -401,6 +411,12 @@ type TransporterOptions = {
      */
     compress?: (data: string) => Promise<Uint8Array>;
     compression?: 'gzip';
+    /**
+     * Where the generated Request-ID is sent: as the `Request-ID` header, or as the
+     * `x-algolia-request-id` query parameter. When undefined, no Request-ID is sent.
+     * A caller-supplied Request-ID is never overwritten.
+     */
+    requestIdChannel?: 'headers' | 'queryParameters' | undefined;
 };
 type Transporter = TransporterOptions & {
     /**
@@ -513,11 +529,16 @@ declare function getAlgoliaAgent({ algoliaAgents, client, version }: GetAlgoliaA
 
 declare function createNullLogger(): Logger;
 
+/**
+ * Prefers the logger's optional `warn` method and falls back to `console.warn`, so warnings stay visible with the default no-op logger.
+ */
+declare function logWarning(logger: Logger, message: string): void;
+
 declare const COMPRESSION_THRESHOLD = 750;
 
 declare function createStatefulHost(host: Host, status?: StatefulHost['status']): StatefulHost;
 
-declare function createTransporter({ hosts, hostsCache, baseHeaders, logger, baseQueryParameters, algoliaAgent, timeouts, requester, requestsCache, responsesCache, compress, compression, }: TransporterOptions): TransporterWithHttpInfo;
+declare function createTransporter({ hosts, hostsCache, baseHeaders, logger, baseQueryParameters, algoliaAgent, timeouts, requester, requestsCache, responsesCache, compress, compression, requestIdChannel, maxRateLimitRetries, }: TransporterOptions): TransporterWithHttpInfo;
 
 declare class AlgoliaError extends Error {
     name: string;
@@ -534,18 +555,29 @@ declare class IndexAlreadyExistsError extends AlgoliaError {
 }
 declare class ErrorWithStackTrace extends AlgoliaError {
     stackTrace: StackFrame[];
-    constructor(message: string, stackTrace: StackFrame[], name: string);
+    correlationId?: string | undefined;
+    constructor(message: string, stackTrace: StackFrame[], name: string, correlationId?: string | undefined);
 }
 declare class RetryError extends ErrorWithStackTrace {
-    constructor(stackTrace: StackFrame[]);
+    constructor(stackTrace: StackFrame[], correlationId?: string | undefined);
 }
 declare class ApiError extends ErrorWithStackTrace {
     status: number;
-    constructor(message: string, status: number, stackTrace: StackFrame[], name?: string);
+    constructor(message: string, status: number, stackTrace: StackFrame[], name?: string, correlationId?: string | undefined);
+}
+/**
+ * Thrown by `sendStream` when the HTTP status is not 2xx, so `requestStream` can
+ * wait and retry on 429 using `Retry-After` without parsing the error message.
+ */
+declare class StreamRequestError extends AlgoliaError {
+    status: number;
+    headers?: Headers | undefined;
+    constructor(status: number, body: string, headers?: Headers | undefined);
 }
 declare class DeserializationError extends AlgoliaError {
     response: Response;
-    constructor(message: string, response: Response);
+    correlationId?: string | undefined;
+    constructor(message: string, response: Response, correlationId?: string | undefined);
 }
 type DetailedErrorWithMessage = {
     message: string;
@@ -562,7 +594,7 @@ type DetailedError = {
 };
 declare class DetailedApiError extends ApiError {
     error: DetailedError;
-    constructor(message: string, status: number, error: DetailedError, stackTrace: StackFrame[]);
+    constructor(message: string, status: number, error: DetailedError, stackTrace: StackFrame[], correlationId?: string | undefined);
 }
 
 declare function shuffle<TData>(array: TData[]): TData[];
@@ -572,15 +604,37 @@ declare function serializeData(request: Request, requestOptions: RequestOptions)
 declare function serializeHeaders(baseHeaders: Headers, requestHeaders: Headers, requestOptionsHeaders?: Headers | undefined): Headers;
 declare function deserializeSuccess<TObject>(response: Response): TObject;
 declare function deserializeSuccessWithHttpInfo<TData>(response: Response): AlgoliaHttpResponse<TData>;
-declare function deserializeFailure({ content, status }: Response, stackFrame: StackFrame[]): Error;
+declare function getCorrelationId(headers: Headers | undefined): string | undefined;
+declare function getLastCorrelationId(stackTrace: StackFrame[]): string | undefined;
+declare function deserializeFailure(response: Response, stackFrame: StackFrame[]): Error;
+
+declare function generateRequestId(): string;
+/**
+ * Returns request options carrying a Request-ID on the transporter's channel, so that every
+ * request a multi-request helper performs shares the same ID. Returns the options unchanged
+ * when the channel is off or when a Request-ID is already supplied. Never apply ahead of a
+ * cacheable operation: the ID enters the cache key and defeats caching and deduplication.
+ */
+declare function withRequestId(transporter: Pick<Transporter, 'requestIdChannel' | 'baseHeaders' | 'baseQueryParameters'>, requestOptions?: RequestOptions | undefined): RequestOptions | undefined;
 
 declare function isNetworkError({ isTimedOut, status }: Omit<Response, 'content'>): boolean;
 declare function isRetryable({ isTimedOut, status }: Omit<Response, 'content'>): boolean;
 declare function isSuccess({ status }: Pick<Response, 'status'>): boolean;
+declare function isRateLimited({ status }: Pick<Response, 'status'>): boolean;
+/**
+ * 429 from `sendStream`: a status-bearing error, or the `HTTP 429:` string requesters used to throw.
+ */
+declare function isRateLimitedError(error: unknown): boolean;
+declare function headersFromError(error: unknown): Headers | undefined;
+/**
+ * `Retry-After` as a wait in milliseconds.
+ * Only a positive whole-number-of-seconds string is honored; anything else (missing, `0`, HTTP-date, junk) waits 1s.
+ */
+declare function parseRetryAfterMs(headers: Headers | undefined): number;
 
 declare function stackTraceWithoutCredentials(stackTrace: StackFrame[]): StackFrame[];
 declare function stackFrameWithoutCredentials(stackFrame: StackFrame): StackFrame;
 
 declare function validateRequired(field: string, method: string, value: unknown): void;
 
-export { type AlgoliaAgent, type AlgoliaAgentOptions, AlgoliaError, type AlgoliaHttpResponse, ApiError, type AuthMode, type BrowserLocalStorageCacheItem, type BrowserLocalStorageOptions, COMPRESSION_THRESHOLD, type Cache, type CacheEvents, type ChunkedHelperOptions, type ClientOptions, type CreateClientOptions, type CreateIterablePromise, DEFAULT_CONNECT_TIMEOUT_BROWSER, DEFAULT_CONNECT_TIMEOUT_NODE, DEFAULT_READ_TIMEOUT_BROWSER, DEFAULT_READ_TIMEOUT_NODE, DEFAULT_REPLACE_ALL_OBJECTS_MAX_RETRIES, DEFAULT_WRITE_TIMEOUT_BROWSER, DEFAULT_WRITE_TIMEOUT_NODE, DeserializationError, DetailedApiError, type DetailedError, type DetailedErrorWithMessage, type DetailedErrorWithTypeID, type EndRequest, ErrorWithStackTrace, type FallbackableCacheOptions, type GetAlgoliaAgent, type Headers, type Host, IndexAlreadyExistsError, IndexNotFoundError, IndicesInSameAppError, type IterableOptions, LogLevelEnum, type LogLevelType, type Logger, type MemoryCacheOptions, type Method, type QueryParameters, type Request, type RequestOptions, type Requester, type Response, RetryError, type ServerSentEvent, type StackFrame, type StatefulHost, type StreamEvent, type Timeouts, type Transporter, type TransporterOptions, type TransporterWithHttpInfo, createAlgoliaAgent, createAuth, createBrowserLocalStorageCache, createFallbackableCache, createIterablePromise, createMemoryCache, createNullCache, createNullLogger, createStatefulHost, createTransporter, deserializeFailure, deserializeSuccess, deserializeSuccessWithHttpInfo, getAlgoliaAgent, isNetworkError, isRetryable, isSuccess, iterSSEEvents, serializeData, serializeHeaders, serializeQueryParameters, serializeUrl, shuffle, stackFrameWithoutCredentials, stackTraceWithoutCredentials, validateRequired };
+export { type AlgoliaAgent, type AlgoliaAgentOptions, AlgoliaError, type AlgoliaHttpResponse, ApiError, type AuthMode, type BrowserLocalStorageCacheItem, type BrowserLocalStorageOptions, COMPRESSION_THRESHOLD, type Cache, type CacheEvents, type ChunkedHelperOptions, type ClientOptions, type CreateClientOptions, type CreateIterablePromise, DEFAULT_CONNECT_TIMEOUT_BROWSER, DEFAULT_CONNECT_TIMEOUT_NODE, DEFAULT_READ_TIMEOUT_BROWSER, DEFAULT_READ_TIMEOUT_NODE, DEFAULT_REPLACE_ALL_OBJECTS_MAX_RETRIES, DEFAULT_WRITE_TIMEOUT_BROWSER, DEFAULT_WRITE_TIMEOUT_NODE, DeserializationError, DetailedApiError, type DetailedError, type DetailedErrorWithMessage, type DetailedErrorWithTypeID, type EndRequest, ErrorWithStackTrace, type FallbackableCacheOptions, type GetAlgoliaAgent, type Headers, type Host, IndexAlreadyExistsError, IndexNotFoundError, IndicesInSameAppError, type IterableOptions, LogLevelEnum, type LogLevelType, type Logger, type MemoryCacheOptions, type Method, type QueryParameters, type Request, type RequestOptions, type Requester, type Response, RetryError, type ServerSentEvent, type StackFrame, type StatefulHost, type StreamEvent, StreamRequestError, type Timeouts, type Transporter, type TransporterOptions, type TransporterWithHttpInfo, createAlgoliaAgent, createAuth, createBrowserLocalStorageCache, createFallbackableCache, createIterablePromise, createMemoryCache, createNullCache, createNullLogger, createStatefulHost, createTransporter, deserializeFailure, deserializeSuccess, deserializeSuccessWithHttpInfo, generateRequestId, getAlgoliaAgent, getCorrelationId, getLastCorrelationId, headersFromError, isNetworkError, isRateLimited, isRateLimitedError, isRetryable, isSuccess, iterSSEEvents, logWarning, parseRetryAfterMs, serializeData, serializeHeaders, serializeQueryParameters, serializeUrl, shuffle, stackFrameWithoutCredentials, stackTraceWithoutCredentials, validateRequired, withRequestId };

package/dist/common.js

@@ -264,6 +264,16 @@ function createNullLogger() {
   };
 }
 
+// src/logger/logWarning.ts
+function logWarning(logger, message) {
+  if (logger.warn) {
+    void Promise.resolve(logger.warn(message)).catch(() => {
+    });
+  } else {
+    console.warn(message);
+  }
+}
+
 // src/sse.ts
 var MAX_LINE_BUFFER_SIZE = 10 * 1024 * 1024;
 async function* readableStreamToAsyncIterable(stream) {
@@ -466,38 +476,52 @@ var IndexAlreadyExistsError = class extends AlgoliaError {
 };
 var ErrorWithStackTrace = class extends AlgoliaError {
   stackTrace;
-  constructor(message, stackTrace, name) {
-    super(message, name);
+  correlationId;
+  constructor(message, stackTrace, name, correlationId) {
+    super(correlationId ? `${message} (Correlation-ID: ${correlationId})` : message, name);
     this.stackTrace = stackTrace;
+    this.correlationId = correlationId;
   }
 };
 var RetryError = class extends ErrorWithStackTrace {
-  constructor(stackTrace) {
+  constructor(stackTrace, correlationId) {
     super(
       "Unreachable hosts - your application id may be incorrect. If the error persists, please visit our help center https://alg.li/support-unreachable-hosts or reach out to the Algolia Support team: https://alg.li/support",
       stackTrace,
-      "RetryError"
+      "RetryError",
+      correlationId
     );
   }
 };
 var ApiError = class extends ErrorWithStackTrace {
   status;
-  constructor(message, status, stackTrace, name = "ApiError") {
-    super(message, stackTrace, name);
+  constructor(message, status, stackTrace, name = "ApiError", correlationId) {
+    super(message, stackTrace, name, correlationId);
+    this.status = status;
+  }
+};
+var StreamRequestError = class extends AlgoliaError {
+  status;
+  headers;
+  constructor(status, body, headers) {
+    super(`HTTP ${status}: ${body}`, "StreamRequestError");
     this.status = status;
+    this.headers = headers;
   }
 };
 var DeserializationError = class extends AlgoliaError {
   response;
-  constructor(message, response) {
-    super(message, "DeserializationError");
+  correlationId;
+  constructor(message, response, correlationId) {
+    super(correlationId ? `${message} (Correlation-ID: ${correlationId})` : message, "DeserializationError");
     this.response = response;
+    this.correlationId = correlationId;
   }
 };
 var DetailedApiError = class extends ApiError {
   error;
-  constructor(message, status, error, stackTrace) {
-    super(message, status, stackTrace, "DetailedApiError");
+  constructor(message, status, error, stackTrace, correlationId) {
+    super(message, status, stackTrace, "DetailedApiError", correlationId);
     this.error = error;
   }
 };
@@ -556,7 +580,7 @@ function deserializeSuccess(response) {
   try {
     return JSON.parse(response.content);
   } catch (e) {
-    throw new DeserializationError(e.message, response);
+    throw new DeserializationError(e.message, response, getCorrelationId(response.headers));
   }
 }
 function deserializeSuccessWithHttpInfo(response) {
@@ -567,19 +591,76 @@ function deserializeSuccessWithHttpInfo(response) {
     data: deserializeSuccess(response)
   };
 }
-function deserializeFailure({ content, status }, stackFrame) {
+function getCorrelationId(headers) {
+  if (!headers) {
+    return void 0;
+  }
+  if (headers["correlation-id"] !== void 0) {
+    return headers["correlation-id"];
+  }
+  const header = Object.keys(headers).find((key) => key.toLowerCase() === "correlation-id");
+  return header === void 0 ? void 0 : headers[header];
+}
+function getLastCorrelationId(stackTrace) {
+  for (let i = stackTrace.length - 1; i >= 0; i--) {
+    const correlationId = getCorrelationId(stackTrace[i].response.headers);
+    if (correlationId !== void 0) {
+      return correlationId;
+    }
+  }
+  return void 0;
+}
+function deserializeFailure(response, stackFrame) {
+  const { content, status } = response;
+  const correlationId = getCorrelationId(response.headers);
   try {
     const parsed = JSON.parse(content);
     if ("error" in parsed) {
-      return new DetailedApiError(parsed.message, status, parsed.error, stackFrame);
+      return new DetailedApiError(parsed.message, status, parsed.error, stackFrame, correlationId);
     }
-    return new ApiError(parsed.message, status, stackFrame);
+    return new ApiError(parsed.message, status, stackFrame, "ApiError", correlationId);
   } catch {
   }
-  return new ApiError(content, status, stackFrame);
+  return new ApiError(content, status, stackFrame, "ApiError", correlationId);
+}
+
+// src/transporter/requestId.ts
+var BASE62_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+var REQUEST_ID_LENGTH = 11;
+function generateRequestId() {
+  var _a;
+  let requestId = "";
+  if (typeof ((_a = globalThis.crypto) == null ? void 0 : _a.getRandomValues) === "function") {
+    const bytes = new Uint8Array(REQUEST_ID_LENGTH);
+    globalThis.crypto.getRandomValues(bytes);
+    for (const byte of bytes) {
+      requestId += BASE62_CHARS[byte % BASE62_CHARS.length];
+    }
+    return requestId;
+  }
+  for (let i = 0; i < REQUEST_ID_LENGTH; i++) {
+    requestId += BASE62_CHARS[Math.floor(Math.random() * BASE62_CHARS.length)];
+  }
+  return requestId;
+}
+function hasRequestId(headers, queryParameters) {
+  return headers !== void 0 && Object.keys(headers).some((header) => header.toLowerCase() === "request-id") || queryParameters !== void 0 && Object.keys(queryParameters).some((parameter) => parameter.toLowerCase() === "x-algolia-request-id");
+}
+function withRequestId(transporter, requestOptions) {
+  if (transporter.requestIdChannel === void 0 || hasRequestId(transporter.baseHeaders, transporter.baseQueryParameters) || hasRequestId(requestOptions == null ? void 0 : requestOptions.headers, requestOptions == null ? void 0 : requestOptions.queryParameters)) {
+    return requestOptions;
+  }
+  if (transporter.requestIdChannel === "headers") {
+    return { ...requestOptions, headers: { ...requestOptions == null ? void 0 : requestOptions.headers, "request-id": generateRequestId() } };
+  }
+  return {
+    ...requestOptions,
+    queryParameters: { ...requestOptions == null ? void 0 : requestOptions.queryParameters, "x-algolia-request-id": generateRequestId() }
+  };
 }
 
 // src/transporter/responses.ts
+var DEFAULT_RATE_LIMIT_WAIT_MS = 1e3;
 function isNetworkError({ isTimedOut, status }) {
   return !isTimedOut && ~~status === 0;
 }
@@ -589,6 +670,37 @@ function isRetryable({ isTimedOut, status }) {
 function isSuccess({ status }) {
   return ~~(status / 100) === 2;
 }
+function isRateLimited({ status }) {
+  return ~~status === 429;
+}
+var HTTP_429_MESSAGE = /^HTTP 429(?:\D|$)/;
+function isRateLimitedError(error) {
+  if (typeof error === "object" && error !== null && "status" in error) {
+    return isRateLimited(error);
+  }
+  return error instanceof Error && HTTP_429_MESSAGE.test(error.message);
+}
+function headersFromError(error) {
+  if (typeof error === "object" && error !== null && "headers" in error) {
+    return error.headers;
+  }
+  return void 0;
+}
+function parseRetryAfterMs(headers) {
+  var _a;
+  const raw = (_a = headers == null ? void 0 : headers["retry-after"]) == null ? void 0 : _a.trim();
+  if (raw === void 0 || raw.length === 0) {
+    return DEFAULT_RATE_LIMIT_WAIT_MS;
+  }
+  if (!/^\d+$/.test(raw)) {
+    return DEFAULT_RATE_LIMIT_WAIT_MS;
+  }
+  const seconds = Number.parseInt(raw, 10);
+  if (seconds <= 0) {
+    return DEFAULT_RATE_LIMIT_WAIT_MS;
+  }
+  return seconds * 1e3;
+}
 
 // src/transporter/stackTrace.ts
 function stackTraceWithoutCredentials(stackTrace) {
@@ -621,8 +733,23 @@ function createTransporter({
   requestsCache,
   responsesCache,
   compress,
-  compression
+  compression,
+  requestIdChannel,
+  maxRateLimitRetries = 3
 }) {
+  function injectRequestId(headers, queryParameters) {
+    if (requestIdChannel === void 0 || headers["request-id"] !== void 0 || Object.keys(queryParameters).some((parameter) => parameter.toLowerCase() === "x-algolia-request-id")) {
+      return;
+    }
+    if (requestIdChannel === "headers") {
+      headers["request-id"] = generateRequestId();
+    } else {
+      queryParameters["x-algolia-request-id"] = generateRequestId();
+    }
+  }
+  const wait = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
   async function createRetryableOptions(compatibleHosts) {
     const statefulHosts = await Promise.all(
       compatibleHosts.map((compatibleHost) => {
@@ -677,11 +804,13 @@ function createTransporter({
         }
       }
     }
+    injectRequestId(headers, queryParameters);
     let timeoutsCount = 0;
+    let rateLimitRetriesLeft = maxRateLimitRetries;
     const retry = async (retryableHosts, getTimeout) => {
       const host = retryableHosts.pop();
       if (host === void 0) {
-        throw new RetryError(stackTraceWithoutCredentials(stackTrace));
+        throw new RetryError(stackTraceWithoutCredentials(stackTrace), getLastCorrelationId(stackTrace));
       }
       const timeout = { ...timeouts, ...requestOptions.timeouts };
       const payload = {
@@ -703,6 +832,19 @@ function createTransporter({
         return stackFrame;
       };
       const response = await requester.send(payload);
+      if (isRateLimited(response) && rateLimitRetriesLeft > 0) {
+        rateLimitRetriesLeft--;
+        retryableHosts.push(host);
+        const stackFrame = pushToStackTrace(response);
+        const waitMs = parseRetryAfterMs(response.headers);
+        logger.info("Retryable failure", {
+          ...stackFrameWithoutCredentials(stackFrame),
+          wait: waitMs,
+          rateLimitRetriesLeft
+        });
+        await wait(waitMs);
+        return retry(retryableHosts, getTimeout);
+      }
       if (isRetryable(response)) {
         const stackFrame = pushToStackTrace(response);
         if (response.isTimedOut) {
@@ -805,6 +947,7 @@ function createTransporter({
         }
       }
     }
+    injectRequestId(headers, queryParameters);
     const isRead = request.useReadTransporter || request.method === "GET";
     const compatibleHosts = hosts.filter(
       (host2) => host2.accept === "readWrite" || (isRead ? host2.accept === "read" : host2.accept === "write")
@@ -823,8 +966,28 @@ function createTransporter({
       connectTimeout: timeout.connect,
       responseTimeout: isRead ? timeout.read : timeout.write
     };
-    const stream = await requester.sendStream(payload);
-    yield* iterSSEEvents(stream);
+    let rateLimitRetriesLeft = maxRateLimitRetries;
+    while (true) {
+      let stream;
+      try {
+        stream = await requester.sendStream(payload);
+      } catch (error) {
+        if (isRateLimitedError(error) && rateLimitRetriesLeft > 0) {
+          rateLimitRetriesLeft--;
+          const waitMs = parseRetryAfterMs(headersFromError(error));
+          logger.info("Retryable failure", {
+            wait: waitMs,
+            rateLimitRetriesLeft,
+            host
+          });
+          await wait(waitMs);
+          continue;
+        }
+        throw error;
+      }
+      yield* iterSSEEvents(stream);
+      return;
+    }
   }
   return {
     hostsCache,
@@ -834,7 +997,9 @@ function createTransporter({
     algoliaAgent,
     baseHeaders,
     baseQueryParameters,
+    requestIdChannel,
     hosts,
+    maxRateLimitRetries,
     request: createRequest,
     requestWithHttpInfo: createRequestWithHttpInfo,
     requestStream,
@@ -875,6 +1040,7 @@ export {
   IndicesInSameAppError,
   LogLevelEnum,
   RetryError,
+  StreamRequestError,
   createAlgoliaAgent,
   createAuth,
   createBrowserLocalStorageCache,
@@ -888,11 +1054,19 @@ export {
   deserializeFailure,
   deserializeSuccess,
   deserializeSuccessWithHttpInfo,
+  generateRequestId,
   getAlgoliaAgent,
+  getCorrelationId,
+  getLastCorrelationId,
+  headersFromError,
   isNetworkError,
+  isRateLimited,
+  isRateLimitedError,
   isRetryable,
   isSuccess,
   iterSSEEvents,
+  logWarning,
+  parseRetryAfterMs,
   serializeData,
   serializeHeaders,
   serializeQueryParameters,
@@ -900,6 +1074,7 @@ export {
   shuffle,
   stackFrameWithoutCredentials,
   stackTraceWithoutCredentials,
-  validateRequired
+  validateRequired,
+  withRequestId
 };
 //# sourceMappingURL=common.js.map