@adpal/shared-lib 1.0.7 → 1.1.0

package/dist/index.d.mts

@@ -841,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 FallbackOptions, type FallbackResult, 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, withFallback, withFallbackInfo, 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

@@ -841,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 FallbackOptions, type FallbackResult, 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, withFallback, withFallbackInfo, 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);
     }
   }
@@ -399,11 +399,11 @@ async function withFallback(fn, options) {
   try {
     const result = await withRetry(fn, { ...retryOptions, logger: logger2 });
     return result.data;
-  } catch (error) {
+  } 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: error instanceof Error ? error.message : String(error),
-        errorType: error instanceof Error ? error.constructor.name : typeof error
+        errorMessage: error2 instanceof Error ? error2.message : String(error2),
+        errorType: error2 instanceof Error ? error2.constructor.name : typeof error2
       });
     }
     return typeof fallback === "function" ? fallback() : fallback;
@@ -417,17 +417,17 @@ async function withFallbackInfo(fn, options) {
       data: result.data,
       usedFallback: false
     };
-  } catch (error) {
+  } 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: error instanceof Error ? error.message : String(error)
+        errorMessage: error2 instanceof Error ? error2.message : String(error2)
       });
     }
     const fallbackValue = typeof fallback === "function" ? fallback() : fallback;
     return {
       data: fallbackValue,
       usedFallback: true,
-      error: error instanceof Error ? error : new Error(String(error))
+      error: error2 instanceof Error ? error2 : new Error(String(error2))
     };
   }
 }
@@ -581,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;
@@ -599,13 +659,17 @@ 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;