@adpal/shared-lib 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,776 @@
+import { z } from 'zod';
+
+/**
+ * Кастомные классы ошибок
+ *
+ * Иерархия ошибок для структурированной обработки исключений.
+ * Каждый класс содержит дополнительный контекст для отладки.
+ *
+ * @module errors
+ */
+/**
+ * Базовый класс для всех ошибок приложения
+ *
+ * Расширяет стандартный Error с дополнительными полями:
+ * - code: машиночитаемый код ошибки
+ * - context: дополнительные данные для отладки
+ * - retryable: можно ли повторить операцию
+ */
+declare class AppError extends Error {
+    /** Машиночитаемый код ошибки */
+    readonly code: string;
+    /** Дополнительный контекст для отладки */
+    readonly context?: Record<string, unknown>;
+    /** Можно ли повторить операцию */
+    readonly retryable: boolean;
+    /** Временная метка создания ошибки */
+    readonly timestamp: Date;
+    constructor(message: string, options?: {
+        code?: string;
+        context?: Record<string, unknown>;
+        retryable?: boolean;
+        cause?: Error;
+    });
+    /**
+     * Преобразовать в JSON для логирования
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Ошибка при вызове внешнего API
+ *
+ * Используется для Voyage AI, Anthropic, Turbopuffer.
+ */
+declare class ApiError extends AppError {
+    /** HTTP статус код */
+    readonly statusCode: number;
+    /** Имя сервиса */
+    readonly service: string;
+    constructor(message: string, options: {
+        statusCode: number;
+        service: string;
+        context?: Record<string, unknown>;
+        retryable?: boolean;
+        cause?: Error;
+    });
+}
+/**
+ * Ошибка Voyage AI API
+ */
+declare class VoyageApiError extends ApiError {
+    constructor(message: string, statusCode: number, context?: Record<string, unknown>);
+}
+/**
+ * Ошибка Anthropic API
+ */
+declare class AnthropicApiError extends ApiError {
+    constructor(message: string, statusCode: number, context?: Record<string, unknown>);
+}
+/**
+ * Ошибка Turbopuffer API
+ */
+declare class TurbopufferApiError extends ApiError {
+    constructor(message: string, statusCode: number, context?: Record<string, unknown>);
+}
+/**
+ * Ошибка валидации данных
+ *
+ * Используется при невалидных входных данных или ответах API.
+ */
+declare class ValidationError extends AppError {
+    /** Поле, в котором обнаружена ошибка */
+    readonly field?: string;
+    /** Ожидаемое значение или тип */
+    readonly expected?: string;
+    /** Полученное значение */
+    readonly received?: unknown;
+    constructor(message: string, options?: {
+        field?: string;
+        expected?: string;
+        received?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Ошибка отсутствующей конфигурации
+ *
+ * Используется при отсутствии обязательных переменных окружения.
+ */
+declare class ConfigError extends AppError {
+    /** Имя отсутствующей переменной */
+    readonly variableName: string;
+    constructor(variableName: string);
+}
+/**
+ * Проверить, является ли ошибка экземпляром AppError
+ */
+declare function isAppError(error: unknown): error is AppError;
+/**
+ * Обернуть неизвестную ошибку в AppError
+ */
+declare function wrapError(error: unknown, defaultMessage?: string): AppError;
+
+/**
+ * Структурированное логирование
+ *
+ * Централизованный логгер с уровнями и форматированием.
+ * В продакшене выводит JSON для парсинга CloudWatch/Datadog.
+ * В dev режиме — читаемый формат с цветами.
+ *
+ * @module logger
+ */
+/** Уровни логирования */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Метаданные для структурированного логирования */
+interface LogMeta {
+    /** Имя модуля/компонента */
+    module?: string;
+    /** ID операции для трейсинга */
+    operationId?: string;
+    /** ID пользователя */
+    userId?: string;
+    /** Длительность операции в мс */
+    durationMs?: number;
+    /** Дополнительные поля */
+    [key: string]: unknown;
+}
+/**
+ * Класс логгера
+ *
+ * Создаёт экземпляр с привязкой к модулю.
+ *
+ * @example
+ * const log = new Logger('voyage');
+ * log.info('Запрос отправлен', { tokens: 1500 });
+ * log.error('Ошибка API', new Error('timeout'));
+ */
+declare class Logger {
+    private readonly module;
+    private readonly minLevel;
+    constructor(module: string);
+    /**
+     * Проверить, включён ли данный уровень
+     */
+    private isEnabled;
+    /**
+     * Записать лог
+     */
+    private log;
+    /**
+     * Debug уровень — детальная информация для отладки
+     */
+    debug(message: string, meta?: LogMeta): void;
+    /**
+     * Info уровень — информационные сообщения
+     */
+    info(message: string, meta?: LogMeta): void;
+    /**
+     * Warn уровень — предупреждения
+     */
+    warn(message: string, meta?: LogMeta): void;
+    /**
+     * Error уровень — ошибки
+     */
+    error(message: string, error?: Error | unknown, meta?: LogMeta): void;
+    /**
+     * Создать child logger с дополнительным контекстом
+     */
+    child(context: LogMeta): ChildLogger;
+}
+/**
+ * Child logger с привязанным контекстом
+ */
+declare class ChildLogger {
+    private readonly parent;
+    private readonly context;
+    constructor(parent: Logger, context: LogMeta);
+    debug(message: string, meta?: LogMeta): void;
+    info(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    error(message: string, error?: Error | unknown, meta?: LogMeta): void;
+}
+/** Логгер для Voyage AI */
+declare const voyageLogger: Logger;
+/** Логгер для Turbopuffer */
+declare const turbopufferLogger: Logger;
+/** Логгер для Anthropic */
+declare const anthropicLogger: Logger;
+/** Логгер для API запросов */
+declare const apiLogger: Logger;
+/** Логгер общего назначения */
+declare const logger: Logger;
+/**
+ * Создать таймер для измерения длительности операции
+ *
+ * @example
+ * const timer = createTimer();
+ * await doSomething();
+ * log.info('Операция завершена', { durationMs: timer() });
+ */
+declare function createTimer(): () => number;
+
+/**
+ * Retry логика с exponential backoff
+ *
+ * Утилиты для повторения неудачных операций с экспоненциальной
+ * задержкой и джиттером для предотвращения thundering herd.
+ *
+ * @module retry
+ */
+
+/**
+ * Опции для retry
+ */
+interface RetryOptions {
+    /** Максимальное количество попыток (включая первую) */
+    maxAttempts?: number;
+    /** Базовая задержка в мс (удваивается с каждой попыткой) */
+    baseDelayMs?: number;
+    /** Максимальная задержка в мс */
+    maxDelayMs?: number;
+    /** Добавлять случайный джиттер (0-1, доля от задержки) */
+    jitter?: number;
+    /** Функция для определения, нужно ли повторять */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Callback при каждой неудачной попытке */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** Логгер для записи попыток */
+    logger?: Logger;
+}
+/**
+ * Результат выполнения с retry
+ */
+interface RetryResult<T> {
+    /** Результат успешного выполнения */
+    data: T;
+    /** Количество попыток (1 = успех с первого раза) */
+    attempts: number;
+    /** Общее время выполнения в мс */
+    totalTimeMs: number;
+}
+/**
+ * Ожидать указанное количество миллисекунд
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Выполнить функцию с retry и exponential backoff
+ *
+ * @param fn - Асинхронная функция для выполнения
+ * @param options - Опции retry
+ * @returns Результат выполнения с метаданными
+ * @throws Последняя ошибка, если все попытки исчерпаны
+ *
+ * @example
+ * const result = await withRetry(
+ *   () => fetch('https://api.example.com/data'),
+ *   { maxAttempts: 3, baseDelayMs: 1000 }
+ * );
+ * console.log(`Успех за ${result.attempts} попыток`);
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+/**
+ * Retry для API запросов с предустановленными параметрами
+ *
+ * Оптимизировано для внешних API (Voyage, Anthropic, Turbopuffer).
+ *
+ * @example
+ * const response = await retryApiCall(
+ *   () => fetch(VOYAGE_API_URL, { method: 'POST', body }),
+ *   { logger: voyageLogger }
+ * );
+ */
+declare function retryApiCall<T>(fn: () => Promise<T>, options?: Pick<RetryOptions, 'logger' | 'onRetry' | 'maxAttempts'>): Promise<T>;
+/**
+ * Retry для критичных операций с более агрессивными параметрами
+ *
+ * Используется для операций, которые обязательно должны выполниться.
+ *
+ * @example
+ * await retryCritical(
+ *   () => saveToDatabase(data),
+ *   { logger }
+ * );
+ */
+declare function retryCritical<T>(fn: () => Promise<T>, options?: Pick<RetryOptions, 'logger' | 'onRetry'>): Promise<T>;
+
+/**
+ * Zod схемы для валидации API ответов
+ *
+ * Типобезопасная валидация ответов от внешних API.
+ * Гарантирует соответствие данных ожидаемой структуре.
+ *
+ * @module schemas
+ */
+
+/**
+ * Схема ответа Voyage Embeddings API
+ *
+ * @see https://docs.voyageai.com/docs/embeddings
+ */
+declare const VoyageEmbeddingResponseSchema: z.ZodObject<{
+    /** Массив эмбеддингов */
+    data: z.ZodArray<z.ZodObject<{
+        /** Вектор эмбеддинга */
+        embedding: z.ZodArray<z.ZodNumber, "many">;
+        /** Индекс в исходном массиве */
+        index: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        embedding: number[];
+        index?: number | undefined;
+    }, {
+        embedding: number[];
+        index?: number | undefined;
+    }>, "many">;
+    /** Статистика использования */
+    usage: z.ZodObject<{
+        /** Общее количество токенов */
+        total_tokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        total_tokens: number;
+    }, {
+        total_tokens: number;
+    }>;
+    /** Модель, использованная для генерации */
+    model: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    data: {
+        embedding: number[];
+        index?: number | undefined;
+    }[];
+    usage: {
+        total_tokens: number;
+    };
+    model?: string | undefined;
+}, {
+    data: {
+        embedding: number[];
+        index?: number | undefined;
+    }[];
+    usage: {
+        total_tokens: number;
+    };
+    model?: string | undefined;
+}>;
+type VoyageEmbeddingResponse = z.infer<typeof VoyageEmbeddingResponseSchema>;
+/**
+ * Схема ответа Voyage Rerank API
+ *
+ * @see https://docs.voyageai.com/docs/reranker
+ */
+declare const VoyageRerankResponseSchema: z.ZodObject<{
+    /** Массив результатов реранкинга */
+    data: z.ZodArray<z.ZodObject<{
+        /** Индекс документа в исходном массиве */
+        index: z.ZodNumber;
+        /** Оценка релевантности (0-1) */
+        relevance_score: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        index: number;
+        relevance_score: number;
+    }, {
+        index: number;
+        relevance_score: number;
+    }>, "many">;
+    /** Статистика использования */
+    usage: z.ZodObject<{
+        /** Общее количество токенов */
+        total_tokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        total_tokens: number;
+    }, {
+        total_tokens: number;
+    }>;
+    /** Модель, использованная для реранкинга */
+    model: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    data: {
+        index: number;
+        relevance_score: number;
+    }[];
+    usage: {
+        total_tokens: number;
+    };
+    model?: string | undefined;
+}, {
+    data: {
+        index: number;
+        relevance_score: number;
+    }[];
+    usage: {
+        total_tokens: number;
+    };
+    model?: string | undefined;
+}>;
+type VoyageRerankResponse = z.infer<typeof VoyageRerankResponseSchema>;
+/**
+ * Базовая схема атрибутов вектора
+ */
+declare const VectorAttributesSchema: z.ZodObject<{
+    /** ID записи в Supabase */
+    supabase_id: z.ZodNumber;
+    /** Уникальный ID сообщения/документа */
+    message_id: z.ZodString;
+    /** Тип источника */
+    source_type: z.ZodEnum<["email", "pdf", "website"]>;
+    /** Тип чанка */
+    chunk_type: z.ZodString;
+    /** Email отправителя */
+    sender: z.ZodOptional<z.ZodString>;
+    /** Email получателя */
+    recipient: z.ZodOptional<z.ZodString>;
+    /** Дата источника */
+    source_date: z.ZodOptional<z.ZodString>;
+    /** ID цепочки писем */
+    thread_id: z.ZodOptional<z.ZodString>;
+    /** ID клиента */
+    client_id: z.ZodOptional<z.ZodString>;
+    /** URL источника */
+    source_url: z.ZodOptional<z.ZodString>;
+    /** Номер страницы */
+    page_number: z.ZodOptional<z.ZodNumber>;
+    /** Заголовок секции */
+    section_title: z.ZodOptional<z.ZodString>;
+    /** ID в content_sources */
+    content_source_id: z.ZodOptional<z.ZodNumber>;
+    /** Тема письма */
+    subject: z.ZodOptional<z.ZodString>;
+    /** Превью контента */
+    content_preview: z.ZodOptional<z.ZodString>;
+    /** Заголовок документа */
+    title: z.ZodOptional<z.ZodString>;
+    /** Полный контент */
+    content: z.ZodOptional<z.ZodString>;
+    /** Категория */
+    category: z.ZodOptional<z.ZodString>;
+    /** Тональность */
+    sentiment: z.ZodOptional<z.ZodEnum<["positive", "negative", "neutral"]>>;
+    /** Дата создания */
+    created_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    supabase_id: number;
+    message_id: string;
+    source_type: "email" | "pdf" | "website";
+    chunk_type: string;
+    sender?: string | undefined;
+    recipient?: string | undefined;
+    source_date?: string | undefined;
+    thread_id?: string | undefined;
+    client_id?: string | undefined;
+    source_url?: string | undefined;
+    page_number?: number | undefined;
+    section_title?: string | undefined;
+    content_source_id?: number | undefined;
+    subject?: string | undefined;
+    content_preview?: string | undefined;
+    title?: string | undefined;
+    content?: string | undefined;
+    category?: string | undefined;
+    sentiment?: "positive" | "negative" | "neutral" | undefined;
+    created_at?: string | undefined;
+}, {
+    supabase_id: number;
+    message_id: string;
+    source_type: "email" | "pdf" | "website";
+    chunk_type: string;
+    sender?: string | undefined;
+    recipient?: string | undefined;
+    source_date?: string | undefined;
+    thread_id?: string | undefined;
+    client_id?: string | undefined;
+    source_url?: string | undefined;
+    page_number?: number | undefined;
+    section_title?: string | undefined;
+    content_source_id?: number | undefined;
+    subject?: string | undefined;
+    content_preview?: string | undefined;
+    title?: string | undefined;
+    content?: string | undefined;
+    category?: string | undefined;
+    sentiment?: "positive" | "negative" | "neutral" | undefined;
+    created_at?: string | undefined;
+}>;
+type VectorAttributes = z.infer<typeof VectorAttributesSchema>;
+/**
+ * Схема результата поиска Turbopuffer
+ */
+declare const TurbopufferSearchResultSchema: z.ZodObject<{
+    /** ID вектора */
+    id: z.ZodString;
+    /** Расстояние до запроса */
+    dist: z.ZodNumber;
+    /** Атрибуты вектора */
+    attributes: z.ZodObject<{
+        supabase_id: z.ZodOptional<z.ZodNumber>;
+        message_id: z.ZodOptional<z.ZodString>;
+        source_type: z.ZodOptional<z.ZodEnum<["email", "pdf", "website"]>>;
+        chunk_type: z.ZodOptional<z.ZodString>;
+        sender: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        recipient: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        source_date: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        thread_id: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        client_id: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        source_url: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        page_number: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        section_title: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        content_source_id: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        subject: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        content_preview: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        title: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        content: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        category: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        sentiment: z.ZodOptional<z.ZodOptional<z.ZodEnum<["positive", "negative", "neutral"]>>>;
+        created_at: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        supabase_id?: number | undefined;
+        message_id?: string | undefined;
+        source_type?: "email" | "pdf" | "website" | undefined;
+        chunk_type?: string | undefined;
+        sender?: string | undefined;
+        recipient?: string | undefined;
+        source_date?: string | undefined;
+        thread_id?: string | undefined;
+        client_id?: string | undefined;
+        source_url?: string | undefined;
+        page_number?: number | undefined;
+        section_title?: string | undefined;
+        content_source_id?: number | undefined;
+        subject?: string | undefined;
+        content_preview?: string | undefined;
+        title?: string | undefined;
+        content?: string | undefined;
+        category?: string | undefined;
+        sentiment?: "positive" | "negative" | "neutral" | undefined;
+        created_at?: string | undefined;
+    }, {
+        supabase_id?: number | undefined;
+        message_id?: string | undefined;
+        source_type?: "email" | "pdf" | "website" | undefined;
+        chunk_type?: string | undefined;
+        sender?: string | undefined;
+        recipient?: string | undefined;
+        source_date?: string | undefined;
+        thread_id?: string | undefined;
+        client_id?: string | undefined;
+        source_url?: string | undefined;
+        page_number?: number | undefined;
+        section_title?: string | undefined;
+        content_source_id?: number | undefined;
+        subject?: string | undefined;
+        content_preview?: string | undefined;
+        title?: string | undefined;
+        content?: string | undefined;
+        category?: string | undefined;
+        sentiment?: "positive" | "negative" | "neutral" | undefined;
+        created_at?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    dist: number;
+    attributes: {
+        supabase_id?: number | undefined;
+        message_id?: string | undefined;
+        source_type?: "email" | "pdf" | "website" | undefined;
+        chunk_type?: string | undefined;
+        sender?: string | undefined;
+        recipient?: string | undefined;
+        source_date?: string | undefined;
+        thread_id?: string | undefined;
+        client_id?: string | undefined;
+        source_url?: string | undefined;
+        page_number?: number | undefined;
+        section_title?: string | undefined;
+        content_source_id?: number | undefined;
+        subject?: string | undefined;
+        content_preview?: string | undefined;
+        title?: string | undefined;
+        content?: string | undefined;
+        category?: string | undefined;
+        sentiment?: "positive" | "negative" | "neutral" | undefined;
+        created_at?: string | undefined;
+    };
+}, {
+    id: string;
+    dist: number;
+    attributes: {
+        supabase_id?: number | undefined;
+        message_id?: string | undefined;
+        source_type?: "email" | "pdf" | "website" | undefined;
+        chunk_type?: string | undefined;
+        sender?: string | undefined;
+        recipient?: string | undefined;
+        source_date?: string | undefined;
+        thread_id?: string | undefined;
+        client_id?: string | undefined;
+        source_url?: string | undefined;
+        page_number?: number | undefined;
+        section_title?: string | undefined;
+        content_source_id?: number | undefined;
+        subject?: string | undefined;
+        content_preview?: string | undefined;
+        title?: string | undefined;
+        content?: string | undefined;
+        category?: string | undefined;
+        sentiment?: "positive" | "negative" | "neutral" | undefined;
+        created_at?: string | undefined;
+    };
+}>;
+type TurbopufferSearchResult = z.infer<typeof TurbopufferSearchResultSchema>;
+/**
+ * Схема сообщения в ответе Claude
+ */
+declare const ClaudeMessageSchema: z.ZodObject<{
+    /** ID сообщения */
+    id: z.ZodString;
+    /** Тип объекта */
+    type: z.ZodLiteral<"message">;
+    /** Роль */
+    role: z.ZodEnum<["assistant", "user"]>;
+    /** Контент */
+    content: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<["text", "tool_use"]>;
+        text: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "text" | "tool_use";
+        text?: string | undefined;
+    }, {
+        type: "text" | "tool_use";
+        text?: string | undefined;
+    }>, "many">;
+    /** Модель */
+    model: z.ZodString;
+    /** Причина остановки */
+    stop_reason: z.ZodNullable<z.ZodEnum<["end_turn", "max_tokens", "stop_sequence", "tool_use"]>>;
+    /** Использование токенов */
+    usage: z.ZodObject<{
+        input_tokens: z.ZodNumber;
+        output_tokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        input_tokens: number;
+        output_tokens: number;
+    }, {
+        input_tokens: number;
+        output_tokens: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "message";
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    model: string;
+    content: {
+        type: "text" | "tool_use";
+        text?: string | undefined;
+    }[];
+    id: string;
+    role: "assistant" | "user";
+    stop_reason: "tool_use" | "end_turn" | "max_tokens" | "stop_sequence" | null;
+}, {
+    type: "message";
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    model: string;
+    content: {
+        type: "text" | "tool_use";
+        text?: string | undefined;
+    }[];
+    id: string;
+    role: "assistant" | "user";
+    stop_reason: "tool_use" | "end_turn" | "max_tokens" | "stop_sequence" | null;
+}>;
+type ClaudeMessage = z.infer<typeof ClaudeMessageSchema>;
+/**
+ * Схема входящего запроса к Chat API
+ */
+declare const ChatRequestSchema: z.ZodObject<{
+    /** Сообщение пользователя */
+    message: z.ZodString;
+    /** История сообщений */
+    history: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant"]>;
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        role: "assistant" | "user";
+    }, {
+        content: string;
+        role: "assistant" | "user";
+    }>, "many">>>;
+    /** ID сессии */
+    sessionId: z.ZodOptional<z.ZodString>;
+    /** Режим (customer/internal) */
+    mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["customer", "internal"]>>>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    history: {
+        content: string;
+        role: "assistant" | "user";
+    }[];
+    mode: "customer" | "internal";
+    sessionId?: string | undefined;
+}, {
+    message: string;
+    history?: {
+        content: string;
+        role: "assistant" | "user";
+    }[] | undefined;
+    sessionId?: string | undefined;
+    mode?: "customer" | "internal" | undefined;
+}>;
+type ChatRequest = z.infer<typeof ChatRequestSchema>;
+/**
+ * Схема источника в ответе
+ */
+declare const SourceSchema: z.ZodObject<{
+    /** Тип источника */
+    type: z.ZodEnum<["email", "pdf", "website"]>;
+    /** Заголовок */
+    title: z.ZodString;
+    /** URL или идентификатор */
+    url: z.ZodOptional<z.ZodString>;
+    /** Превью контента */
+    preview: z.ZodOptional<z.ZodString>;
+    /** Оценка релевантности */
+    relevance: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "email" | "pdf" | "website";
+    title: string;
+    url?: string | undefined;
+    preview?: string | undefined;
+    relevance?: number | undefined;
+}, {
+    type: "email" | "pdf" | "website";
+    title: string;
+    url?: string | undefined;
+    preview?: string | undefined;
+    relevance?: number | undefined;
+}>;
+type Source = z.infer<typeof SourceSchema>;
+/**
+ * Безопасно распарсить данные по схеме
+ *
+ * @param schema - Zod схема
+ * @param data - Данные для валидации
+ * @returns Результат парсинга или null при ошибке
+ *
+ * @example
+ * const response = await fetch(url);
+ * const data = await response.json();
+ * const parsed = safeParse(VoyageEmbeddingResponseSchema, data);
+ * if (!parsed) throw new ValidationError('Invalid API response');
+ */
+declare function safeParse<T>(schema: z.ZodType<T>, data: unknown): T | null;
+/**
+ * Распарсить данные по схеме с выбросом ошибки
+ *
+ * @param schema - Zod схема
+ * @param data - Данные для валидации
+ * @param errorMessage - Сообщение об ошибке
+ * @returns Валидные данные
+ * @throws Error при невалидных данных
+ */
+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 };