@adpal/shared-lib 1.0.1 → 1.1.0

package/dist/index.d.mts

@@ -292,6 +292,74 @@ declare function retryApiCall<T>(fn: () => Promise<T>, options?: Pick<RetryOptio
  * );
  */
 declare function retryCritical<T>(fn: () => Promise<T>, options?: Pick<RetryOptions, 'logger' | 'onRetry'>): Promise<T>;
+/**
+ * Опции для withFallback
+ */
+interface FallbackOptions<T> extends RetryOptions {
+    /** Значение по умолчанию при неудаче */
+    fallback: T | (() => T);
+    /** Не логировать ошибку (используется когда fallback ожидаем) */
+    silent?: boolean;
+}
+/**
+ * Выполнить функцию с retry и fallback значением при неудаче
+ *
+ * Используется для graceful degradation — когда операция может упасть,
+ * но мы хотим продолжить работу с дефолтным значением.
+ *
+ * @param fn - Асинхронная функция для выполнения
+ * @param options - Опции с обязательным fallback
+ * @returns Результат выполнения или fallback значение
+ *
+ * @example
+ * // Rerank с fallback на исходные результаты
+ * const reranked = await withFallback(
+ *   () => rerankResults(query, results),
+ *   {
+ *     fallback: results,
+ *     maxAttempts: 2,
+ *     logger: voyageLogger,
+ *   }
+ * );
+ *
+ * @example
+ * // Получить настройки с fallback на defaults
+ * const settings = await withFallback(
+ *   () => fetchUserSettings(userId),
+ *   {
+ *     fallback: () => DEFAULT_SETTINGS,
+ *     silent: true, // Не логировать, если настройки не найдены
+ *   }
+ * );
+ */
+declare function withFallback<T>(fn: () => Promise<T>, options: FallbackOptions<T>): Promise<T>;
+/**
+ * Результат операции с информацией об использовании fallback
+ */
+interface FallbackResult<T> {
+    /** Результат (данные или fallback) */
+    data: T;
+    /** true если использован fallback */
+    usedFallback: boolean;
+    /** Ошибка, если была */
+    error?: Error;
+}
+/**
+ * Версия withFallback, которая возвращает информацию об использовании fallback
+ *
+ * Полезно когда нужно знать, пришли ли данные из источника или из fallback.
+ *
+ * @example
+ * const { data, usedFallback } = await withFallbackInfo(
+ *   () => fetchLiveData(),
+ *   { fallback: cachedData }
+ * );
+ *
+ * if (usedFallback) {
+ *   console.log('Показываем кэшированные данные');
+ * }
+ */
+declare function withFallbackInfo<T>(fn: () => Promise<T>, options: FallbackOptions<T>): Promise<FallbackResult<T>>;
 
 /**
  * Zod схемы для валидации API ответов
@@ -773,4 +841,103 @@ declare function safeParse<T>(schema: z.ZodType<T>, data: unknown): T | null;
  */
 declare function parseOrThrow<T>(schema: z.ZodType<T>, data: unknown, errorMessage?: string): T;
 
-export { AnthropicApiError, ApiError, AppError, type ChatRequest, ChatRequestSchema, type ClaudeMessage, ClaudeMessageSchema, ConfigError, type LogLevel, type LogMeta, Logger, type RetryOptions, type RetryResult, type Source, SourceSchema, TurbopufferApiError, type TurbopufferSearchResult, TurbopufferSearchResultSchema, ValidationError, type VectorAttributes, VectorAttributesSchema, VoyageApiError, type VoyageEmbeddingResponse, VoyageEmbeddingResponseSchema, type VoyageRerankResponse, VoyageRerankResponseSchema, anthropicLogger, apiLogger, createTimer, isAppError, logger, parseOrThrow, retryApiCall, retryCritical, safeParse, sleep, turbopufferLogger, voyageLogger, withRetry, wrapError };
+/**
+ * Стандартизированные типы API ответов
+ *
+ * Обеспечивает единый формат для всех API endpoints.
+ *
+ * @module api-response
+ */
+/**
+ * Успешный ответ API
+ */
+interface ApiSuccessResponse<T> {
+    success: true;
+    data: T;
+    meta?: {
+        requestId?: string;
+        timestamp?: string;
+        duration_ms?: number;
+        pagination?: PaginationMeta;
+    };
+}
+/**
+ * Ответ API с ошибкой
+ */
+interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    meta?: {
+        requestId?: string;
+        timestamp?: string;
+    };
+}
+/**
+ * Объединённый тип ответа API
+ */
+type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+/**
+ * Метаданные пагинации
+ */
+interface PaginationMeta {
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+/**
+ * Создать успешный ответ
+ *
+ * @example
+ * return Response.json(success(users, { pagination }));
+ */
+declare function success<T>(data: T, meta?: ApiSuccessResponse<T>['meta']): ApiSuccessResponse<T>;
+/**
+ * Создать ответ с ошибкой
+ *
+ * @example
+ * return Response.json(error('NOT_FOUND', 'User not found'), { status: 404 });
+ */
+declare function error(code: string, message: string, details?: unknown, requestId?: string): ApiErrorResponse;
+/**
+ * Создать метаданные пагинации
+ *
+ * @example
+ * const pagination = paginate(1, 20, 100);
+ * // { page: 1, pageSize: 20, totalItems: 100, totalPages: 5, hasMore: true }
+ */
+declare function paginate(page: number, pageSize: number, totalItems: number): PaginationMeta;
+/**
+ * Ответ со списком и пагинацией
+ */
+interface ListResponse<T> {
+    items: T[];
+    pagination: PaginationMeta;
+}
+/**
+ * Создать ответ со списком
+ *
+ * @example
+ * return Response.json(success(list(users, 1, 20, 100)));
+ */
+declare function list<T>(items: T[], page: number, pageSize: number, totalItems: number): ListResponse<T>;
+declare const ErrorCodes: {
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly EXTERNAL_API_ERROR: "EXTERNAL_API_ERROR";
+    readonly DATABASE_ERROR: "DATABASE_ERROR";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export { AnthropicApiError, ApiError, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, AppError, type ChatRequest, ChatRequestSchema, type ClaudeMessage, ClaudeMessageSchema, ConfigError, type ErrorCode, ErrorCodes, type FallbackOptions, type FallbackResult, type ListResponse, type LogLevel, type LogMeta, Logger, type PaginationMeta, type RetryOptions, type RetryResult, type Source, SourceSchema, TurbopufferApiError, type TurbopufferSearchResult, TurbopufferSearchResultSchema, ValidationError, type VectorAttributes, VectorAttributesSchema, VoyageApiError, type VoyageEmbeddingResponse, VoyageEmbeddingResponseSchema, type VoyageRerankResponse, VoyageRerankResponseSchema, anthropicLogger, apiLogger, createTimer, error, isAppError, list, logger, paginate, parseOrThrow, retryApiCall, retryCritical, safeParse, sleep, success, turbopufferLogger, voyageLogger, withFallback, withFallbackInfo, withRetry, wrapError };

package/dist/index.d.ts

@@ -292,6 +292,74 @@ declare function retryApiCall<T>(fn: () => Promise<T>, options?: Pick<RetryOptio
  * );
  */
 declare function retryCritical<T>(fn: () => Promise<T>, options?: Pick<RetryOptions, 'logger' | 'onRetry'>): Promise<T>;
+/**
+ * Опции для withFallback
+ */
+interface FallbackOptions<T> extends RetryOptions {
+    /** Значение по умолчанию при неудаче */
+    fallback: T | (() => T);
+    /** Не логировать ошибку (используется когда fallback ожидаем) */
+    silent?: boolean;
+}
+/**
+ * Выполнить функцию с retry и fallback значением при неудаче
+ *
+ * Используется для graceful degradation — когда операция может упасть,
+ * но мы хотим продолжить работу с дефолтным значением.
+ *
+ * @param fn - Асинхронная функция для выполнения
+ * @param options - Опции с обязательным fallback
+ * @returns Результат выполнения или fallback значение
+ *
+ * @example
+ * // Rerank с fallback на исходные результаты
+ * const reranked = await withFallback(
+ *   () => rerankResults(query, results),
+ *   {
+ *     fallback: results,
+ *     maxAttempts: 2,
+ *     logger: voyageLogger,
+ *   }
+ * );
+ *
+ * @example
+ * // Получить настройки с fallback на defaults
+ * const settings = await withFallback(
+ *   () => fetchUserSettings(userId),
+ *   {
+ *     fallback: () => DEFAULT_SETTINGS,
+ *     silent: true, // Не логировать, если настройки не найдены
+ *   }
+ * );
+ */
+declare function withFallback<T>(fn: () => Promise<T>, options: FallbackOptions<T>): Promise<T>;
+/**
+ * Результат операции с информацией об использовании fallback
+ */
+interface FallbackResult<T> {
+    /** Результат (данные или fallback) */
+    data: T;
+    /** true если использован fallback */
+    usedFallback: boolean;
+    /** Ошибка, если была */
+    error?: Error;
+}
+/**
+ * Версия withFallback, которая возвращает информацию об использовании fallback
+ *
+ * Полезно когда нужно знать, пришли ли данные из источника или из fallback.
+ *
+ * @example
+ * const { data, usedFallback } = await withFallbackInfo(
+ *   () => fetchLiveData(),
+ *   { fallback: cachedData }
+ * );
+ *
+ * if (usedFallback) {
+ *   console.log('Показываем кэшированные данные');
+ * }
+ */
+declare function withFallbackInfo<T>(fn: () => Promise<T>, options: FallbackOptions<T>): Promise<FallbackResult<T>>;
 
 /**
  * Zod схемы для валидации API ответов
@@ -773,4 +841,103 @@ declare function safeParse<T>(schema: z.ZodType<T>, data: unknown): T | null;
  */
 declare function parseOrThrow<T>(schema: z.ZodType<T>, data: unknown, errorMessage?: string): T;
 
-export { AnthropicApiError, ApiError, AppError, type ChatRequest, ChatRequestSchema, type ClaudeMessage, ClaudeMessageSchema, ConfigError, type LogLevel, type LogMeta, Logger, type RetryOptions, type RetryResult, type Source, SourceSchema, TurbopufferApiError, type TurbopufferSearchResult, TurbopufferSearchResultSchema, ValidationError, type VectorAttributes, VectorAttributesSchema, VoyageApiError, type VoyageEmbeddingResponse, VoyageEmbeddingResponseSchema, type VoyageRerankResponse, VoyageRerankResponseSchema, anthropicLogger, apiLogger, createTimer, isAppError, logger, parseOrThrow, retryApiCall, retryCritical, safeParse, sleep, turbopufferLogger, voyageLogger, withRetry, wrapError };
+/**
+ * Стандартизированные типы API ответов
+ *
+ * Обеспечивает единый формат для всех API endpoints.
+ *
+ * @module api-response
+ */
+/**
+ * Успешный ответ API
+ */
+interface ApiSuccessResponse<T> {
+    success: true;
+    data: T;
+    meta?: {
+        requestId?: string;
+        timestamp?: string;
+        duration_ms?: number;
+        pagination?: PaginationMeta;
+    };
+}
+/**
+ * Ответ API с ошибкой
+ */
+interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    meta?: {
+        requestId?: string;
+        timestamp?: string;
+    };
+}
+/**
+ * Объединённый тип ответа API
+ */
+type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+/**
+ * Метаданные пагинации
+ */
+interface PaginationMeta {
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+/**
+ * Создать успешный ответ
+ *
+ * @example
+ * return Response.json(success(users, { pagination }));
+ */
+declare function success<T>(data: T, meta?: ApiSuccessResponse<T>['meta']): ApiSuccessResponse<T>;
+/**
+ * Создать ответ с ошибкой
+ *
+ * @example
+ * return Response.json(error('NOT_FOUND', 'User not found'), { status: 404 });
+ */
+declare function error(code: string, message: string, details?: unknown, requestId?: string): ApiErrorResponse;
+/**
+ * Создать метаданные пагинации
+ *
+ * @example
+ * const pagination = paginate(1, 20, 100);
+ * // { page: 1, pageSize: 20, totalItems: 100, totalPages: 5, hasMore: true }
+ */
+declare function paginate(page: number, pageSize: number, totalItems: number): PaginationMeta;
+/**
+ * Ответ со списком и пагинацией
+ */
+interface ListResponse<T> {
+    items: T[];
+    pagination: PaginationMeta;
+}
+/**
+ * Создать ответ со списком
+ *
+ * @example
+ * return Response.json(success(list(users, 1, 20, 100)));
+ */
+declare function list<T>(items: T[], page: number, pageSize: number, totalItems: number): ListResponse<T>;
+declare const ErrorCodes: {
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly EXTERNAL_API_ERROR: "EXTERNAL_API_ERROR";
+    readonly DATABASE_ERROR: "DATABASE_ERROR";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export { AnthropicApiError, ApiError, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, AppError, type ChatRequest, ChatRequestSchema, type ClaudeMessage, ClaudeMessageSchema, ConfigError, type ErrorCode, ErrorCodes, type FallbackOptions, type FallbackResult, type ListResponse, type LogLevel, type LogMeta, Logger, type PaginationMeta, type RetryOptions, type RetryResult, type Source, SourceSchema, TurbopufferApiError, type TurbopufferSearchResult, TurbopufferSearchResultSchema, ValidationError, type VectorAttributes, VectorAttributesSchema, VoyageApiError, type VoyageEmbeddingResponse, VoyageEmbeddingResponseSchema, type VoyageRerankResponse, VoyageRerankResponseSchema, anthropicLogger, apiLogger, createTimer, error, isAppError, list, logger, paginate, parseOrThrow, retryApiCall, retryCritical, safeParse, sleep, success, turbopufferLogger, voyageLogger, withFallback, withFallbackInfo, withRetry, wrapError };

package/dist/index.js

@@ -122,21 +122,21 @@ var ConfigError = class extends AppError {
 function isRetryableStatus(statusCode) {
   return [408, 429, 500, 502, 503, 504].includes(statusCode);
 }
-function isAppError(error) {
-  return error instanceof AppError;
+function isAppError(error2) {
+  return error2 instanceof AppError;
 }
-function wrapError(error, defaultMessage = "\u041D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u0430\u044F \u043E\u0448\u0438\u0431\u043A\u0430") {
-  if (error instanceof AppError) {
-    return error;
-  }
-  if (error instanceof Error) {
-    return new AppError(error.message || defaultMessage, {
-      cause: error,
-      context: { originalName: error.name }
+function wrapError(error2, defaultMessage = "\u041D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u0430\u044F \u043E\u0448\u0438\u0431\u043A\u0430") {
+  if (error2 instanceof AppError) {
+    return error2;
+  }
+  if (error2 instanceof Error) {
+    return new AppError(error2.message || defaultMessage, {
+      cause: error2,
+      context: { originalName: error2.name }
     });
   }
   return new AppError(defaultMessage, {
-    context: { originalError: error }
+    context: { originalError: error2 }
   });
 }
 
@@ -189,11 +189,11 @@ function formatLogEntry(entry) {
   }
   return JSON.stringify(entry);
 }
-function serializeError(error) {
+function serializeError(error2) {
   return {
-    name: error.name,
-    message: error.message,
-    stack: error.stack
+    name: error2.name,
+    message: error2.message,
+    stack: error2.stack
   };
 }
 var Logger = class {
@@ -212,7 +212,7 @@ var Logger = class {
   /**
    * Записать лог
    */
-  log(level, message, meta, error) {
+  log(level, message, meta, error2) {
     if (!this.isEnabled(level)) return;
     const entry = {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -220,8 +220,8 @@ var Logger = class {
       message,
       meta: { module: this.module, ...meta }
     };
-    if (error) {
-      entry.error = serializeError(error);
+    if (error2) {
+      entry.error = serializeError(error2);
     }
     const formatted = formatLogEntry(entry);
     switch (level) {
@@ -256,8 +256,8 @@ var Logger = class {
   /**
    * Error уровень — ошибки
    */
-  error(message, error, meta) {
-    const err = error instanceof Error ? error : void 0;
+  error(message, error2, meta) {
+    const err = error2 instanceof Error ? error2 : void 0;
     this.log("error", message, meta, err);
   }
   /**
@@ -281,8 +281,8 @@ var ChildLogger = class {
   warn(message, meta) {
     this.parent.warn(message, { ...this.context, ...meta });
   }
-  error(message, error, meta) {
-    this.parent.error(message, error, { ...this.context, ...meta });
+  error(message, error2, meta) {
+    this.parent.error(message, error2, { ...this.context, ...meta });
   }
 };
 var voyageLogger = new Logger("voyage");
@@ -309,12 +309,12 @@ function calculateDelay(attempt, baseDelayMs, maxDelayMs, jitter) {
   const jitterAmount = cappedDelay * jitter * Math.random();
   return Math.round(cappedDelay + jitterAmount);
 }
-function defaultShouldRetry(error) {
-  if (isAppError(error) && error.retryable) {
+function defaultShouldRetry(error2) {
+  if (isAppError(error2) && error2.retryable) {
     return true;
   }
-  if (error instanceof Error) {
-    const message = error.message.toLowerCase();
+  if (error2 instanceof Error) {
+    const message = error2.message.toLowerCase();
     const networkErrors = [
       "fetch failed",
       "network error",
@@ -347,24 +347,24 @@ async function withRetry(fn, options = {}) {
         attempts: attempt,
         totalTimeMs: Math.round(performance.now() - startTime)
       };
-    } catch (error) {
-      lastError = error;
+    } catch (error2) {
+      lastError = error2;
       if (attempt >= maxAttempts) {
-        logger2?.error(`\u0412\u0441\u0435 ${maxAttempts} \u043F\u043E\u043F\u044B\u0442\u043E\u043A \u0438\u0441\u0447\u0435\u0440\u043F\u0430\u043D\u044B`, error);
+        logger2?.error(`\u0412\u0441\u0435 ${maxAttempts} \u043F\u043E\u043F\u044B\u0442\u043E\u043A \u0438\u0441\u0447\u0435\u0440\u043F\u0430\u043D\u044B`, error2);
         break;
       }
-      if (!shouldRetry(error, attempt)) {
+      if (!shouldRetry(error2, attempt)) {
         logger2?.warn(`\u041E\u0448\u0438\u0431\u043A\u0430 \u043D\u0435 \u043F\u043E\u0434\u043B\u0435\u0436\u0438\u0442 \u043F\u043E\u0432\u0442\u043E\u0440\u0435\u043D\u0438\u044E \u043D\u0430 \u043F\u043E\u043F\u044B\u0442\u043A\u0435 ${attempt}`, {
-          errorMessage: error instanceof Error ? error.message : String(error)
+          errorMessage: error2 instanceof Error ? error2.message : String(error2)
         });
         break;
       }
       const delayMs = calculateDelay(attempt, baseDelayMs, maxDelayMs, jitter);
       logger2?.info(`\u041F\u043E\u043F\u044B\u0442\u043A\u0430 ${attempt}/${maxAttempts} \u043D\u0435 \u0443\u0434\u0430\u043B\u0430\u0441\u044C, \u043F\u043E\u0432\u0442\u043E\u0440 \u0447\u0435\u0440\u0435\u0437 ${delayMs}\u043C\u0441`, {
-        errorMessage: error instanceof Error ? error.message : String(error),
+        errorMessage: error2 instanceof Error ? error2.message : String(error2),
         delayMs
       });
-      onRetry?.(error, attempt, delayMs);
+      onRetry?.(error2, attempt, delayMs);
       await sleep(delayMs);
     }
   }
@@ -394,6 +394,43 @@ async function retryCritical(fn, options = {}) {
   });
   return result.data;
 }
+async function withFallback(fn, options) {
+  const { fallback, silent = false, logger: logger2, ...retryOptions } = options;
+  try {
+    const result = await withRetry(fn, { ...retryOptions, logger: logger2 });
+    return result.data;
+  } catch (error2) {
+    if (!silent && logger2) {
+      logger2.warn("\u041E\u043F\u0435\u0440\u0430\u0446\u0438\u044F \u043D\u0435 \u0443\u0434\u0430\u043B\u0430\u0441\u044C, \u0438\u0441\u043F\u043E\u043B\u044C\u0437\u0443\u0435\u043C fallback", {
+        errorMessage: error2 instanceof Error ? error2.message : String(error2),
+        errorType: error2 instanceof Error ? error2.constructor.name : typeof error2
+      });
+    }
+    return typeof fallback === "function" ? fallback() : fallback;
+  }
+}
+async function withFallbackInfo(fn, options) {
+  const { fallback, silent = false, logger: logger2, ...retryOptions } = options;
+  try {
+    const result = await withRetry(fn, { ...retryOptions, logger: logger2 });
+    return {
+      data: result.data,
+      usedFallback: false
+    };
+  } catch (error2) {
+    if (!silent && logger2) {
+      logger2.warn("\u041E\u043F\u0435\u0440\u0430\u0446\u0438\u044F \u043D\u0435 \u0443\u0434\u0430\u043B\u0430\u0441\u044C, \u0438\u0441\u043F\u043E\u043B\u044C\u0437\u0443\u0435\u043C fallback", {
+        errorMessage: error2 instanceof Error ? error2.message : String(error2)
+      });
+    }
+    const fallbackValue = typeof fallback === "function" ? fallback() : fallback;
+    return {
+      data: fallbackValue,
+      usedFallback: true,
+      error: error2 instanceof Error ? error2 : new Error(String(error2))
+    };
+  }
+}
 var VoyageEmbeddingResponseSchema = zod.z.object({
   /** Массив эмбеддингов */
   data: zod.z.array(
@@ -544,12 +581,72 @@ function parseOrThrow(schema, data, errorMessage = "Validation failed") {
   return result.data;
 }
 
+// src/api-response.ts
+function success(data, meta) {
+  return {
+    success: true,
+    data,
+    meta: {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...meta
+    }
+  };
+}
+function error(code, message, details, requestId) {
+  const errorObj = { code, message };
+  if (details !== void 0) {
+    errorObj.details = details;
+  }
+  const meta = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (requestId) {
+    meta.requestId = requestId;
+  }
+  return {
+    success: false,
+    error: errorObj,
+    meta
+  };
+}
+function paginate(page, pageSize, totalItems) {
+  const totalPages = Math.ceil(totalItems / pageSize);
+  return {
+    page,
+    pageSize,
+    totalItems,
+    totalPages,
+    hasMore: page < totalPages
+  };
+}
+function list(items, page, pageSize, totalItems) {
+  return {
+    items,
+    pagination: paginate(page, pageSize, totalItems)
+  };
+}
+var ErrorCodes = {
+  // Client errors (4xx)
+  BAD_REQUEST: "BAD_REQUEST",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  FORBIDDEN: "FORBIDDEN",
+  NOT_FOUND: "NOT_FOUND",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  RATE_LIMITED: "RATE_LIMITED",
+  // Server errors (5xx)
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  EXTERNAL_API_ERROR: "EXTERNAL_API_ERROR",
+  DATABASE_ERROR: "DATABASE_ERROR"
+};
+
 exports.AnthropicApiError = AnthropicApiError;
 exports.ApiError = ApiError;
 exports.AppError = AppError;
 exports.ChatRequestSchema = ChatRequestSchema;
 exports.ClaudeMessageSchema = ClaudeMessageSchema;
 exports.ConfigError = ConfigError;
+exports.ErrorCodes = ErrorCodes;
 exports.Logger = Logger;
 exports.SourceSchema = SourceSchema;
 exports.TurbopufferApiError = TurbopufferApiError;
@@ -562,15 +659,21 @@ exports.VoyageRerankResponseSchema = VoyageRerankResponseSchema;
 exports.anthropicLogger = anthropicLogger;
 exports.apiLogger = apiLogger;
 exports.createTimer = createTimer;
+exports.error = error;
 exports.isAppError = isAppError;
+exports.list = list;
 exports.logger = logger;
+exports.paginate = paginate;
 exports.parseOrThrow = parseOrThrow;
 exports.retryApiCall = retryApiCall;
 exports.retryCritical = retryCritical;
 exports.safeParse = safeParse;
 exports.sleep = sleep;
+exports.success = success;
 exports.turbopufferLogger = turbopufferLogger;
 exports.voyageLogger = voyageLogger;
+exports.withFallback = withFallback;
+exports.withFallbackInfo = withFallbackInfo;
 exports.withRetry = withRetry;
 exports.wrapError = wrapError;
 //# sourceMappingURL=index.js.map