captify 0.1.15

package/dist/chat/services/chat-usage.service.js

@@ -0,0 +1,182 @@
+import { getLLMService } from "../../llm-providers/services";
+import { BaseAwsService } from "../../shared/services/base-aws-service";
+// Import errors
+import { SessionNotFoundError } from "../chat.errors";
+// Import schemas
+import { getUsageParamsSchema } from "../chat.schemas";
+// Import utilities
+import { aggregateTokenUsage } from "../chat.utilities";
+/**
+ * Service responsible for tracking and reporting token usage and costs.
+ * Handles usage aggregation, calculation, and reporting across sessions and messages.
+ *
+ * Responsibilities:
+ * - Calculate aggregated usage from messages
+ * - Generate usage reports with provider/model names
+ * - Track token consumption and costs
+ * - Provide per-message and per-session usage breakdowns
+ *
+ * Does NOT handle:
+ * - Message operations (see ChatMessageService)
+ * - Session operations (see ChatSessionService)
+ * - Direct database access (receives data from other services)
+ */
+export class ChatUsageService extends BaseAwsService {
+    constructor(deps) {
+        super({ logger: deps.logger });
+    }
+    /**
+     * Get usage statistics for a session.
+     * Returns both aggregated session usage and per-message breakdown.
+     *
+     * @param tenantId Tenant ID to scope the session
+     * @param userId User ID who owns the session
+     * @param sessionId Session ID to get usage for
+     * @param session Complete session data with messages
+     * @param options Optional service options including user credentials
+     * @returns Usage statistics with session and message-level details
+     * @throws ValidationError if userId or sessionId is invalid
+     * @throws SessionNotFoundError if session doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const session = await chatService.getById(tenantId, userId, sessionId);
+     * const usage = await usageService.getUsage(tenantId, userId, sessionId, session, { userCredentials });
+     * console.log(`Total cost: $${usage.sessionUsage.totalCost.toFixed(4)}`);
+     * console.log(`Total tokens: ${usage.sessionUsage.totalTokens}`);
+     * ```
+     */
+    async getUsage(tenantId, userId, sessionId, session, options) {
+        const validated = getUsageParamsSchema.parse({
+            tenantId,
+            userId,
+            sessionId,
+        });
+        if (!session) {
+            throw new SessionNotFoundError();
+        }
+        // Get LLM service to fetch provider/model names
+        const llmService = getLLMService();
+        // Extract messages with usage and resolve names
+        const messagesWithUsage = (session.messages || []).filter((msg) => msg.usage);
+        // Batch fetch all unique providers and models to minimize queries
+        const uniqueProviderIds = new Set(messagesWithUsage.map((msg) => msg.providerId));
+        const uniqueModelPairs = new Map(messagesWithUsage.map((msg) => [
+            `${msg.providerId}#${msg.modelId}`,
+            { providerId: msg.providerId, modelId: msg.modelId },
+        ]));
+        // Fetch all providers in parallel
+        const providersMap = new Map();
+        await Promise.all(Array.from(uniqueProviderIds).map(async (providerId) => {
+            try {
+                const provider = await llmService.getProviderById(validated.tenantId, providerId, options);
+                if (provider) {
+                    providersMap.set(providerId, provider.name);
+                }
+            }
+            catch (_a) {
+                providersMap.set(providerId, "Unknown Provider");
+            }
+        }));
+        // Fetch all models in parallel
+        const modelsMap = new Map();
+        await Promise.all(Array.from(uniqueModelPairs.values()).map(async ({ providerId, modelId }) => {
+            const key = `${providerId}#${modelId}`;
+            try {
+                const model = await llmService.getModel(validated.tenantId, providerId, modelId, options);
+                if (model) {
+                    modelsMap.set(key, model.name);
+                }
+            }
+            catch (_a) {
+                // Use modelId as fallback since it's usually readable (e.g., "gpt-4")
+                modelsMap.set(key, modelId);
+            }
+        }));
+        // Extract message-level usage details
+        const messageUsages = messagesWithUsage
+            .filter((msg) => msg.usage !== undefined)
+            .map((msg) => {
+            var _a;
+            const modelKey = `${msg.providerId}#${msg.modelId}`;
+            return {
+                messageId: msg.id,
+                timestamp: msg.timestamp,
+                role: msg.role,
+                promptTokens: msg.usage.promptTokens,
+                completionTokens: msg.usage.completionTokens,
+                reasoningTokens: msg.usage.reasoningTokens,
+                totalTokens: msg.usage.totalTokens,
+                cost: msg.usage.estimatedCost,
+                model: {
+                    id: msg.modelId,
+                    name: modelsMap.get(modelKey) || msg.modelId,
+                },
+                provider: {
+                    id: msg.providerId,
+                    name: (_a = providersMap.get(msg.providerId)) !== null && _a !== void 0 ? _a : "Unknown Provider",
+                },
+            };
+        });
+        // Use cached aggregated usage if available, otherwise calculate from messages
+        let aggregated = session.aggregatedUsage;
+        if (!aggregated) {
+            // Compute from messages
+            const messagesWithUsageData = (session.messages || []).filter((msg) => msg.usage !== undefined);
+            if (messagesWithUsageData.length > 0) {
+                const computed = aggregateTokenUsage(messagesWithUsageData.map((msg) => msg.usage));
+                aggregated = Object.assign(Object.assign({}, computed), { lastCalculated: Date.now() });
+            }
+            else {
+                // No usage data at all - use zeros
+                aggregated = {
+                    totalPromptTokens: 0,
+                    totalCompletionTokens: 0,
+                    totalReasoningTokens: 0,
+                    totalTokens: 0,
+                    totalCost: 0,
+                    messageCount: 0,
+                    lastCalculated: Date.now(),
+                };
+            }
+        }
+        return {
+            sessionUsage: {
+                sessionId: session.id,
+                sessionTitle: session.title,
+                totalPromptTokens: aggregated.totalPromptTokens,
+                totalCompletionTokens: aggregated.totalCompletionTokens,
+                totalReasoningTokens: aggregated.totalReasoningTokens,
+                totalTokens: aggregated.totalTokens,
+                totalCost: aggregated.totalCost,
+                messageCount: aggregated.messageCount,
+                lastUpdated: aggregated.lastCalculated,
+            },
+            messageUsages,
+        };
+    }
+    /**
+     * Calculate aggregated usage from messages.
+     * Returns aggregated statistics ready to be stored in session metadata.
+     *
+     * @param messages Array of messages with usage data
+     * @returns Aggregated usage statistics
+     *
+     * @example
+     * ```typescript
+     * const aggregated = usageService.calculateAggregatedUsage(messages);
+     * await sessionService.updateAggregatedUsage(tenantId, userId, sessionId, aggregated);
+     * ```
+     */
+    calculateAggregatedUsage(messages) {
+        // Filter messages that have usage data
+        const messagesWithUsage = messages.filter((msg) => msg.usage !== undefined);
+        if (messagesWithUsage.length === 0) {
+            return undefined;
+        }
+        // Aggregate all usage data
+        const aggregated = aggregateTokenUsage(messagesWithUsage.map((msg) => msg.usage));
+        return Object.assign(Object.assign({}, aggregated), { lastCalculated: Date.now() });
+    }
+}
+//# sourceMappingURL=chat-usage.service.js.map

package/dist/chat/services/chat-usage.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-usage.service.js","sourceRoot":"","sources":["../../../lib/chat/services/chat-usage.service.ts"],"names":[],"mappings":"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"}

package/dist/chat/services/chat.service.d.ts

@@ -0,0 +1,211 @@
+import type { FileUIPart } from "ai";
+import type { ChatGetParams, ChatGetResponse, ChatMessage, ChatMessagesResponse, ChatServiceDeps, ChatServiceOptions, ChatSession, MessageAttachment, StreamMessageParams, UsageQueryResponse } from "../chat.interfaces";
+import { BaseAwsService } from "../../shared/services/base-aws-service";
+import { type AddMessageParams } from "../chat.schemas";
+/**
+ * This service acts as a FACADE for all chat-related operations.
+ * It delegates to specialized services while maintaining backwards compatibility
+ * with existing code that uses the original ChatService API.
+ *
+ * Service Delegation:
+ * - Session operations → ChatSessionService
+ * - Message operations → ChatMessageService
+ * - Usage tracking → ChatUsageService
+ * - Attachment management → ChatAttachmentService
+ *
+ * Orchestration Responsibilities:
+ * - Cross-service operations (e.g., getById combines session + messages)
+ * - Transaction coordination (e.g., addMessage updates both message and session)
+ * - Backwards compatibility with existing API surface
+ */
+export declare class ChatService extends BaseAwsService {
+    private sessionsDb;
+    private messagesDb;
+    private s3Service;
+    private sessionService;
+    private messageService;
+    private usageService;
+    private attachmentService;
+    constructor(deps: ChatServiceDeps);
+    /**
+     * Get all chat sessions metadata for a user sorted by lastUpdated in descending order.
+     * Delegates to ChatSessionService.
+     */
+    get(tenantId: string, userId: string, opts: ChatGetParams, options?: ChatServiceOptions): Promise<ChatGetResponse>;
+    /**
+     * Get a specific chat session by its ID for a user.
+     * Orchestrates: session metadata (ChatSessionService) + messages (ChatMessageService).
+     */
+    getById(tenantId: string, userId: string, id: string, options?: ChatServiceOptions): Promise<(ChatSession & {
+        messages?: ChatMessage[];
+    }) | null>;
+    /**
+     * Create a new chat session for a user.
+     * Delegates to ChatSessionService.
+     */
+    create(tenantId: string, userId: string, title?: string, options?: ChatServiceOptions): Promise<ChatSession>;
+    /**
+     * Update an existing session.
+     * Delegates to ChatSessionService.
+     */
+    update(tenantId: string, userId: string, id: string, updates: Partial<ChatSession>, options?: ChatServiceOptions): Promise<ChatSession>;
+    /**
+     * Delete a chat session and all its messages.
+     * Orchestrates: messages deletion (ChatMessageService) + attachments cleanup (ChatAttachmentService) + session deletion (ChatSessionService).
+     */
+    delete(tenantId: string, userId: string, id: string, options?: ChatServiceOptions): Promise<void>;
+    /**
+     * Delete all chat sessions for a user.
+     * Orchestrates: session IDs retrieval → bounded parallel message/attachment deletion → session deletion.
+     * Uses configurable concurrency to avoid overwhelming DynamoDB/S3.
+     *
+     * @param tenantId Tenant ID for multi-tenant isolation
+     * @param userId User ID for access control
+     * @param options Service options including user credentials and optional concurrency settings
+     * @returns Number of sessions deleted
+     */
+    deleteAll(tenantId: string, userId: string, options?: ChatServiceOptions & {
+        concurrency?: number;
+    }): Promise<number>;
+    /**
+     * Get messages for a chat session sorted by timestamp with optional pagination.
+     * Orchestrates: session check (ChatSessionService) + messages retrieval (ChatMessageService).
+     */
+    getMessages(tenantId: string, userId: string, sessionId: string, params?: {
+        limit?: number;
+        lastEvaluatedKey?: Record<string, unknown>;
+    }, options?: ChatServiceOptions): Promise<ChatMessagesResponse>;
+    /**
+     * Add a new message to a chat session.
+     * Orchestrates: validation → message creation (ChatMessageService) → session updates (ChatSessionService).
+     */
+    addMessage(params: AddMessageParams, options?: ChatServiceOptions): Promise<ChatMessage>;
+    /**
+     * Update aggregated usage statistics for a session.
+     * This should be called after adding a new message to keep usage in sync.
+     * Orchestrates: message retrieval (ChatMessageService) → usage calculation (ChatUsageService) → session update (ChatSessionService).
+     */
+    updateSessionUsage(tenantId: string, userId: string, sessionId: string, options?: ChatServiceOptions): Promise<void>;
+    /**
+     * Get usage statistics for a session.
+     * Orchestrates: session+messages retrieval → usage report generation (ChatUsageService).
+     */
+    getUsage(tenantId: string, userId: string, sessionId: string, options?: ChatServiceOptions): Promise<UsageQueryResponse>;
+    /**
+     * Delete a message and its attachments.
+     * Orchestrates: message retrieval → attachment cleanup (ChatAttachmentService) → message deletion → session updates.
+     */
+    deleteMessage(tenantId: string, userId: string, sessionId: string, messageId: string, options?: ChatServiceOptions): Promise<void>;
+    /**
+     * Validate and create attachment metadata for files already uploaded to S3.
+     * Files must be uploaded to S3 via presigned URLs before calling this method.
+     * Delegates to ChatAttachmentService.
+     */
+    uploadMessageAttachments(userId: string, sessionId: string, files: (FileUIPart & {
+        size?: number;
+    })[]): MessageAttachment[];
+    /**
+     * Get all file attachments for a session.
+     * Orchestrates: session retrieval → file metadata extraction.
+     */
+    getSessionFiles(tenantId: string, userId: string, sessionId: string, options?: ChatServiceOptions): Promise<Array<{
+        messageId: string;
+        filename?: string;
+        mediaType: string;
+        url: string;
+        size: number;
+        timestamp: number;
+    }>>;
+    /**
+     * Generate a presigned download URL for a file in a session.
+     * Orchestrates: session validation → presigned URL generation (ChatAttachmentService).
+     */
+    getFileDownloadUrl(tenantId: string, userId: string, sessionId: string, fileUrl: string, options?: ChatServiceOptions): Promise<string>;
+    /**
+     * Delete a temporary file (not yet attached to a message).
+     * Orchestrates: session validation → file deletion (ChatAttachmentService).
+     */
+    deleteTempFile(tenantId: string, userId: string, sessionId: string, messageId: string, fileUrl: string, options?: ChatServiceOptions): Promise<void>;
+    /**
+     * Get a presigned URL for uploading a small file (≤5MB).
+     * Orchestrates: session validation → presigned URL generation (ChatAttachmentService).
+     */
+    getPresignedUploadUrl(tenantId: string, userId: string, sessionId: string, fileName: string, fileSize: number, contentType: string, options: ChatServiceOptions): Promise<{
+        fileId: string;
+        key: string;
+        bucket: string;
+        url: string;
+        objectUrl: string;
+        expiresIn: number;
+    }>;
+    /**
+     * Initiate a multipart upload for large files (>5MB).
+     * Orchestrates: session validation → multipart initiation (ChatAttachmentService).
+     */
+    initiateMultipartUpload(tenantId: string, userId: string, sessionId: string, fileName: string, fileSize: number, contentType: string, options: ChatServiceOptions): Promise<{
+        fileId: string;
+        key: string;
+        bucket: string;
+        uploadId: string;
+        partSize: number;
+        totalParts: number;
+    }>;
+    /**
+     * Get a presigned URL for uploading a specific part.
+     * Orchestrates: session validation → part URL generation (ChatAttachmentService).
+     */
+    getMultipartPartUrl(tenantId: string, userId: string, sessionId: string, key: string, uploadId: string, partNumber: number, options: ChatServiceOptions): Promise<{
+        url: string;
+        partNumber: number;
+        expiresIn: number;
+    }>;
+    /**
+     * Complete a multipart upload after all parts are uploaded.
+     * Orchestrates: session validation → multipart completion (ChatAttachmentService).
+     */
+    completeMultipartUpload(tenantId: string, userId: string, sessionId: string, key: string, uploadId: string, fileName: string, fileSize: number, contentType: string, parts: Array<{
+        partNumber: number;
+        etag: string;
+    }>, options: ChatServiceOptions): Promise<MessageAttachment & {
+        messageId: string;
+    }>;
+    /**
+     * Abort a multipart upload (cleanup).
+     * Orchestrates: session validation → multipart abort (ChatAttachmentService).
+     */
+    abortMultipartUpload(tenantId: string, userId: string, sessionId: string, key: string, uploadId: string, options: ChatServiceOptions): Promise<void>;
+    /**
+     * Stream a message response from the LLM.
+     * Orchestrates: session validation → file attachments → user message → LLM streaming → assistant message → title generation.
+     *
+     * @param params Stream message parameters
+     * @param options Service options including user credentials
+     * @returns UI message stream response
+     */
+    streamMessage(params: StreamMessageParams, options: ChatServiceOptions): Promise<Response>;
+    /**
+     * Handle the completion of a streamed message response.
+     * Persists the assistant message and auto-generates title if needed.
+     * @internal
+     */
+    private handleStreamFinish;
+    /**
+     * Auto-generate a title for a new conversation if conditions are met.
+     * @internal
+     */
+    private maybeGenerateTitle;
+}
+/**
+ * Get the singleton ChatService instance.
+ * Lazily initializes the instance on first call.
+ *
+ * @returns ChatService instance
+ *
+ * @example
+ * ```typescript
+ * const chatService = getChatService();
+ * await chatService.create(tenantId, userId, "My Chat");
+ * ```
+ */
+export declare function getChatService(): ChatService;
+//# sourceMappingURL=chat.service.d.ts.map

package/dist/chat/services/chat.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.service.d.ts","sourceRoot":"","sources":["../../../lib/chat/services/chat.service.ts"],"names":[],"mappings":"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"}