captify 0.1.18 → 1.1.0

package/dist/model-budget/services/usage-tracking.service.js

@@ -0,0 +1,203 @@
+/**
+ * Usage Tracking Service
+ *
+ * Centralized service for tracking LLM usage across all operations
+ * (chat, agents, config generation, etc.). Provides a unified interface
+ * for checking limits before requests and recording usage after completion.
+ */
+import { LoggerFactory } from "../../shared/services/logger";
+import { getModelBudgetService, } from "./model-budget.service";
+import { BudgetExceededError, TokenLimitExceededError, } from "../model-budget.errors";
+import { calculateTokenUsage } from "../../chat/chat.utilities";
+import { USER_CONTEXT } from "../../shared/shared.constants";
+// ============================================================================
+// Service Implementation
+// ============================================================================
+/**
+ * Service for tracking LLM usage across all operations.
+ *
+ * Provides methods to:
+ * - Check limits before making LLM calls
+ * - Record usage after LLM calls complete
+ * - Handle streaming responses with async usage tracking
+ *
+ * @example
+ * ```typescript
+ * const tracker = getUsageTrackingService();
+ *
+ * // Before making an LLM call
+ * await tracker.checkLimitsOrThrow({ tenantId, providerId, modelId, userCredentials });
+ *
+ * // After LLM call completes
+ * await tracker.recordUsage(
+ *   { tenantId, providerId, modelId, userCredentials },
+ *   model,
+ *   result.usage,
+ * );
+ * ```
+ */
+export class UsageTrackingService {
+    constructor(deps) {
+        var _a, _b;
+        this.logger =
+            (_a = deps === null || deps === void 0 ? void 0 : deps.logger) !== null && _a !== void 0 ? _a : LoggerFactory.createLogger({
+                serviceName: "UsageTrackingService",
+                userContext: USER_CONTEXT,
+            });
+        this.budgetService = (_b = deps === null || deps === void 0 ? void 0 : deps.budgetService) !== null && _b !== void 0 ? _b : getModelBudgetService();
+    }
+    /**
+     * Check budget and rate limits before making an LLM call.
+     * Uses atomic rate limit check to prevent race conditions.
+     * Throws appropriate error if limits are exceeded.
+     *
+     * @param params - Tracking parameters
+     * @throws BudgetExceededError if budget limit is exceeded
+     * @throws RateLimitExceededError if rate limit is exceeded
+     * @throws TokenLimitExceededError if token limit is exceeded
+     */
+    async checkLimitsOrThrow(params) {
+        var _a, _b, _c, _d, _e, _f;
+        // First, atomically check and record rate limit
+        // This throws RateLimitExceededError if limit is exceeded
+        await this.budgetService.recordRequest({
+            tenantId: params.tenantId,
+            providerId: params.providerId,
+            modelId: params.modelId,
+            userCredentials: params.userCredentials,
+        });
+        // Then check budget limits (these don't have race condition issues)
+        const limitCheck = await this.budgetService.checkLimits({
+            tenantId: params.tenantId,
+            providerId: params.providerId,
+            modelId: params.modelId,
+            userCredentials: params.userCredentials,
+        });
+        if (!limitCheck.allowed) {
+            if (limitCheck.reason === "budget_exceeded" && limitCheck.budget) {
+                throw new BudgetExceededError({
+                    modelId: params.modelId,
+                    providerId: params.providerId,
+                    spent: (_a = limitCheck.budget.spent) !== null && _a !== void 0 ? _a : 0,
+                    limit: (_b = limitCheck.budget.limit) !== null && _b !== void 0 ? _b : 0,
+                    periodEnds: (_c = limitCheck.budget.periodEnd) !== null && _c !== void 0 ? _c : Date.now(),
+                });
+            }
+            if (limitCheck.reason === "token_limit_exceeded" && limitCheck.budget) {
+                throw new TokenLimitExceededError({
+                    modelId: params.modelId,
+                    providerId: params.providerId,
+                    used: (_d = limitCheck.budget.tokenSpent) !== null && _d !== void 0 ? _d : 0,
+                    limit: (_e = limitCheck.budget.tokenLimit) !== null && _e !== void 0 ? _e : 0,
+                    periodEnds: (_f = limitCheck.budget.periodEnd) !== null && _f !== void 0 ? _f : Date.now(),
+                });
+            }
+        }
+    }
+    /**
+     * Record usage after an LLM call completes.
+     * Only records the spend (request count is recorded in checkLimitsOrThrow).
+     *
+     * @param params - Tracking parameters
+     * @param model - Model configuration (for pricing)
+     * @param usage - Usage data from AI SDK
+     * @returns Result with tokens and cost recorded
+     */
+    async recordUsage(params, model, usage) {
+        var _a, _b, _c;
+        if (!usage) {
+            this.logger.debug("No usage data to record", {
+                tenantId: params.tenantId,
+                modelId: params.modelId,
+            });
+            return { tokens: 0, cost: 0, recorded: false };
+        }
+        const normalizedUsage = {
+            inputTokens: (_a = usage.inputTokens) !== null && _a !== void 0 ? _a : 0,
+            outputTokens: (_b = usage.outputTokens) !== null && _b !== void 0 ? _b : 0,
+            totalTokens: (_c = usage.totalTokens) !== null && _c !== void 0 ? _c : 0,
+        };
+        const tokenUsage = calculateTokenUsage(normalizedUsage, model);
+        // Record spend for budget tracking
+        // Note: Request count is already recorded in checkLimitsOrThrow (before the call)
+        await this.budgetService.recordSpend({
+            tenantId: params.tenantId,
+            providerId: params.providerId,
+            modelId: params.modelId,
+            amount: tokenUsage.estimatedCost,
+            tokens: tokenUsage.totalTokens,
+            userCredentials: params.userCredentials,
+        });
+        this.logger.debug("Recorded usage", {
+            tenantId: params.tenantId,
+            providerId: params.providerId,
+            modelId: params.modelId,
+            tokens: tokenUsage.totalTokens,
+            cost: tokenUsage.estimatedCost,
+        });
+        return {
+            tokens: tokenUsage.totalTokens,
+            cost: tokenUsage.estimatedCost,
+            recorded: true,
+        };
+    }
+    /**
+     * Record usage from a streaming response.
+     * This is a fire-and-forget operation that handles the async usage promise.
+     *
+     * @param params - Tracking parameters
+     * @param model - Model configuration (for pricing)
+     * @param usagePromise - Promise that resolves to usage data when stream completes
+     */
+    recordStreamUsage(params, model, usagePromise) {
+        usagePromise
+            .then(async (usage) => {
+            if (usage) {
+                await this.recordUsage(params, model, usage);
+            }
+        })
+            .catch((error) => {
+            this.logger.error("Failed to record stream usage", {
+                tenantId: params.tenantId,
+                providerId: params.providerId,
+                modelId: params.modelId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    }
+    /**
+     * Wrapper for executing an LLM operation with automatic usage tracking.
+     * Checks limits before, executes the operation, and records usage after.
+     *
+     * @param params - Tracking parameters
+     * @param model - Model configuration (for pricing)
+     * @param operation - The LLM operation to execute
+     * @returns The result of the operation
+     */
+    async withTracking(params, model, operation) {
+        // Check limits before operation
+        await this.checkLimitsOrThrow(params);
+        // Execute the operation
+        const result = await operation();
+        // Record usage after operation
+        await this.recordUsage(params, model, result.usage);
+        return result;
+    }
+}
+// ============================================================================
+// Singleton
+// ============================================================================
+let usageTrackingServiceInstance = null;
+/**
+ * Get or create the singleton UsageTrackingService instance.
+ */
+export function getUsageTrackingService(deps) {
+    if ((deps === null || deps === void 0 ? void 0 : deps.logger) || (deps === null || deps === void 0 ? void 0 : deps.budgetService)) {
+        return new UsageTrackingService(deps);
+    }
+    if (!usageTrackingServiceInstance) {
+        usageTrackingServiceInstance = new UsageTrackingService();
+    }
+    return usageTrackingServiceInstance;
+}
+//# sourceMappingURL=usage-tracking.service.js.map

package/dist/model-budget/services/usage-tracking.service.js.map

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

package/dist/notifications/api/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Notifications API
+ */
+export { dismissAllNotifications, dismissNotification, getUnreadCount, listNotifications, markAllAsRead, markAsRead, } from "./notifications.handlers";
+export { dismissAllRequest, dismissNotificationRequest, fetchNotifications, fetchUnreadCount, markAllAsReadRequest, markAsReadRequest, } from "./notifications.client";
+export type { DismissAllResponse, DismissNotificationResponse, MarkAllAsReadResponse, MarkAsReadResponse, NotificationsListResponse, UnreadCountResponse, } from "./notifications.client";
+//# sourceMappingURL=index.d.ts.map

package/dist/notifications/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/notifications/api/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,UAAU,GACX,MAAM,gDAAgD,CAAC;AAGxD,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,8CAA8C,CAAC;AACtD,YAAY,EACV,kBAAkB,EAClB,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,8CAA8C,CAAC"}

package/dist/notifications/api/index.js

@@ -0,0 +1,8 @@
+/**
+ * Notifications API
+ */
+// Handlers (server-side)
+export { dismissAllNotifications, dismissNotification, getUnreadCount, listNotifications, markAllAsRead, markAsRead, } from "./notifications.handlers";
+// Client API (client-side)
+export { dismissAllRequest, dismissNotificationRequest, fetchNotifications, fetchUnreadCount, markAllAsReadRequest, markAsReadRequest, } from "./notifications.client";
+//# sourceMappingURL=index.js.map

package/dist/notifications/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/notifications/api/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,yBAAyB;AACzB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,UAAU,GACX,MAAM,gDAAgD,CAAC;AAExD,2BAA2B;AAC3B,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,8CAA8C,CAAC"}

package/dist/notifications/api/notifications.client.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Notifications Client API
+ *
+ * Client-side functions for making requests to the notifications API.
+ */
+import type { notificationHandlers } from "./notifications.handlers";
+import type { FetchNotificationsParams } from "../notifications.interfaces";
+import type { ApiRouteResponse } from "../../shared/shared.interfaces";
+export type NotificationsListResponse = ApiRouteResponse<typeof notificationHandlers.list>;
+export type UnreadCountResponse = ApiRouteResponse<typeof notificationHandlers.getUnreadCount>;
+export type MarkAsReadResponse = ApiRouteResponse<typeof notificationHandlers.markAsRead>;
+export type MarkAllAsReadResponse = ApiRouteResponse<typeof notificationHandlers.markAllAsRead>;
+export type DismissNotificationResponse = ApiRouteResponse<typeof notificationHandlers.dismiss>;
+export type DismissAllResponse = ApiRouteResponse<typeof notificationHandlers.dismissAll>;
+/**
+ * Fetch notifications for the current user
+ *
+ * @param params - Query parameters for listing notifications
+ * @param endpoint - API endpoint (defaults to /api/notifications)
+ * @returns Promise resolving to notifications and pagination info
+ *
+ * @example
+ * const { notifications, nextCursor } = await fetchNotifications({
+ *   limit: 20,
+ *   unreadOnly: true,
+ * });
+ */
+export declare function fetchNotifications(params?: FetchNotificationsParams, endpoint?: string): Promise<NotificationsListResponse>;
+/**
+ * Fetch unread notification count for the current user
+ *
+ * @param endpoint - API endpoint (defaults to /api/notifications/unread-count)
+ * @returns Promise resolving to the unread count object
+ *
+ * @example
+ * const { count } = await fetchUnreadCount();
+ * console.log(`You have ${count} unread notifications`);
+ */
+export declare function fetchUnreadCount(endpoint?: string): Promise<UnreadCountResponse>;
+/**
+ * Mark a notification as read
+ *
+ * @param notificationId - ID of the notification to mark as read
+ * @param endpoint - API endpoint base (defaults to /api/notifications)
+ * @returns Promise resolving to the updated notification status
+ *
+ * @example
+ * const result = await markAsReadRequest('notif-123');
+ * console.log(`Notification ${result.notificationId} is now read: ${result.read}`);
+ */
+export declare function markAsReadRequest(notificationId: string, endpoint?: string): Promise<MarkAsReadResponse>;
+/**
+ * Mark all notifications as read for the current user
+ *
+ * @param endpoint - API endpoint (defaults to /api/notifications/mark-all-read)
+ * @returns Promise resolving to the number of updated notifications
+ *
+ * @example
+ * const result = await markAllAsReadRequest();
+ * console.log(`Marked ${result.updatedCount} notifications as read`);
+ */
+export declare function markAllAsReadRequest(endpoint?: string): Promise<MarkAllAsReadResponse>;
+/**
+ * Dismiss (soft delete) a notification
+ *
+ * @param notificationId - ID of the notification to dismiss
+ * @param endpoint - API endpoint base (defaults to /api/notifications)
+ * @returns Promise resolving to the updated notification status
+ *
+ * @example
+ * const result = await dismissNotificationRequest('notif-123');
+ * console.log(`Notification ${result.notificationId} dismissed: ${result.isDismissed}`);
+ */
+export declare function dismissNotificationRequest(notificationId: string, endpoint?: string): Promise<DismissNotificationResponse>;
+/**
+ * Dismiss (soft delete) all notifications for the current user
+ *
+ * @param endpoint - API endpoint (defaults to /api/notifications/dismiss-all)
+ * @returns Promise resolving to the number of dismissed notifications
+ *
+ * @example
+ * const result = await dismissAllRequest();
+ * console.log(`Dismissed ${result.dismissedCount} notifications`);
+ */
+export declare function dismissAllRequest(endpoint?: string): Promise<DismissAllResponse>;
+//# sourceMappingURL=notifications.client.d.ts.map

package/dist/notifications/api/notifications.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.client.d.ts","sourceRoot":"","sources":["../../../lib/notifications/api/notifications.client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gDAAgD,CAAC;AAC3F,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8CAA8C,CAAC;AAE7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAIvE,MAAM,MAAM,yBAAyB,GAAG,gBAAgB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC;AAC3F,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,OAAO,oBAAoB,CAAC,cAAc,CAAC,CAAC;AAC/F,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC,OAAO,oBAAoB,CAAC,UAAU,CAAC,CAAC;AAC1F,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,CAAC,OAAO,oBAAoB,CAAC,aAAa,CAAC,CAAC;AAChG,MAAM,MAAM,2BAA2B,GAAG,gBAAgB,CAAC,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAChG,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC,OAAO,oBAAoB,CAAC,UAAU,CAAC,CAAC;AAM1F;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,GAAE,wBAA6B,EACrC,QAAQ,SAA6B,GACpC,OAAO,CAAC,yBAAyB,CAAC,CAapC;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,SAA+C,GACtD,OAAO,CAAC,mBAAmB,CAAC,CAE9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,MAAM,EACtB,QAAQ,SAA6B,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,SAAgD,GACvD,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,cAAc,EAAE,MAAM,EACtB,QAAQ,SAA6B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAItC;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,SAA8C,GACrD,OAAO,CAAC,kBAAkB,CAAC,CAE7B"}

package/dist/notifications/api/notifications.client.js

@@ -0,0 +1,102 @@
+import { NOTIFICATIONS_API_ENDPOINT } from "../notifications.constants";
+import { fetchJson } from "../../shared/utilities/fetch";
+// ============================================================================
+// Client Functions
+// ============================================================================
+/**
+ * Fetch notifications for the current user
+ *
+ * @param params - Query parameters for listing notifications
+ * @param endpoint - API endpoint (defaults to /api/notifications)
+ * @returns Promise resolving to notifications and pagination info
+ *
+ * @example
+ * const { notifications, nextCursor } = await fetchNotifications({
+ *   limit: 20,
+ *   unreadOnly: true,
+ * });
+ */
+export async function fetchNotifications(params = {}, endpoint = NOTIFICATIONS_API_ENDPOINT) {
+    const searchParams = new URLSearchParams();
+    if (params.limit)
+        searchParams.set("limit", params.limit.toString());
+    if (params.cursor)
+        searchParams.set("cursor", params.cursor);
+    if (params.unreadOnly !== undefined)
+        searchParams.set("unreadOnly", params.unreadOnly.toString());
+    if (params.includeDismissed !== undefined) {
+        searchParams.set("includeDismissed", params.includeDismissed.toString());
+    }
+    const url = searchParams.toString().length > 0 ? `${endpoint}?${searchParams}` : endpoint;
+    return fetchJson(url);
+}
+/**
+ * Fetch unread notification count for the current user
+ *
+ * @param endpoint - API endpoint (defaults to /api/notifications/unread-count)
+ * @returns Promise resolving to the unread count object
+ *
+ * @example
+ * const { count } = await fetchUnreadCount();
+ * console.log(`You have ${count} unread notifications`);
+ */
+export async function fetchUnreadCount(endpoint = `${NOTIFICATIONS_API_ENDPOINT}/unread-count`) {
+    return fetchJson(endpoint);
+}
+/**
+ * Mark a notification as read
+ *
+ * @param notificationId - ID of the notification to mark as read
+ * @param endpoint - API endpoint base (defaults to /api/notifications)
+ * @returns Promise resolving to the updated notification status
+ *
+ * @example
+ * const result = await markAsReadRequest('notif-123');
+ * console.log(`Notification ${result.notificationId} is now read: ${result.read}`);
+ */
+export async function markAsReadRequest(notificationId, endpoint = NOTIFICATIONS_API_ENDPOINT) {
+    return fetchJson(`${endpoint}/${notificationId}/read`, { method: "POST" });
+}
+/**
+ * Mark all notifications as read for the current user
+ *
+ * @param endpoint - API endpoint (defaults to /api/notifications/mark-all-read)
+ * @returns Promise resolving to the number of updated notifications
+ *
+ * @example
+ * const result = await markAllAsReadRequest();
+ * console.log(`Marked ${result.updatedCount} notifications as read`);
+ */
+export async function markAllAsReadRequest(endpoint = `${NOTIFICATIONS_API_ENDPOINT}/mark-all-read`) {
+    return fetchJson(endpoint, { method: "POST" });
+}
+/**
+ * Dismiss (soft delete) a notification
+ *
+ * @param notificationId - ID of the notification to dismiss
+ * @param endpoint - API endpoint base (defaults to /api/notifications)
+ * @returns Promise resolving to the updated notification status
+ *
+ * @example
+ * const result = await dismissNotificationRequest('notif-123');
+ * console.log(`Notification ${result.notificationId} dismissed: ${result.isDismissed}`);
+ */
+export async function dismissNotificationRequest(notificationId, endpoint = NOTIFICATIONS_API_ENDPOINT) {
+    return fetchJson(`${endpoint}/${notificationId}`, {
+        method: "DELETE",
+    });
+}
+/**
+ * Dismiss (soft delete) all notifications for the current user
+ *
+ * @param endpoint - API endpoint (defaults to /api/notifications/dismiss-all)
+ * @returns Promise resolving to the number of dismissed notifications
+ *
+ * @example
+ * const result = await dismissAllRequest();
+ * console.log(`Dismissed ${result.dismissedCount} notifications`);
+ */
+export async function dismissAllRequest(endpoint = `${NOTIFICATIONS_API_ENDPOINT}/dismiss-all`) {
+    return fetchJson(endpoint, { method: "DELETE" });
+}
+//# sourceMappingURL=notifications.client.js.map

package/dist/notifications/api/notifications.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.client.js","sourceRoot":"","sources":["../../../lib/notifications/api/notifications.client.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,0BAA0B,EAAE,MAAM,6CAA6C,CAAC;AAEzF,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAUzD,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAmC,EAAE,EACrC,QAAQ,GAAG,0BAA0B;IAErC,MAAM,YAAY,GAAG,IAAI,eAAe,EAAE,CAAC;IAE3C,IAAI,MAAM,CAAC,KAAK;QAAE,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrE,IAAI,MAAM,CAAC,MAAM;QAAE,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7D,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,YAAY,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClG,IAAI,MAAM,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QAC1C,YAAY,CAAC,GAAG,CAAC,kBAAkB,EAAE,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,YAAY,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IAE1F,OAAO,SAAS,CAA4B,GAAG,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAQ,GAAG,GAAG,0BAA0B,eAAe;IAEvD,OAAO,SAAS,CAAsB,QAAQ,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,cAAsB,EACtB,QAAQ,GAAG,0BAA0B;IAErC,OAAO,SAAS,CAAqB,GAAG,QAAQ,IAAI,cAAc,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AACjG,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAQ,GAAG,GAAG,0BAA0B,gBAAgB;IAExD,OAAO,SAAS,CAAwB,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,cAAsB,EACtB,QAAQ,GAAG,0BAA0B;IAErC,OAAO,SAAS,CAA8B,GAAG,QAAQ,IAAI,cAAc,EAAE,EAAE;QAC7E,MAAM,EAAE,QAAQ;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAQ,GAAG,GAAG,0BAA0B,cAAc;IAEtD,OAAO,SAAS,CAAqB,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;AACvE,CAAC"}

package/dist/notifications/api/notifications.handlers.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Notifications API Handlers
+ *
+ * Route handlers for notifications API endpoints.
+ */
+/**
+ * GET /api/notifications
+ *
+ * Lists notifications for the authenticated user with pagination support.
+ *
+ * Query parameters:
+ * - limit: Number of notifications to return (optional, defaults to 20)
+ * - cursor: Pagination cursor for next page (optional)
+ * - unreadOnly: Only return unread notifications (optional, defaults to false)
+ * - includeDismissed: Include dismissed notifications (optional, defaults to false)
+ *
+ * @returns Object containing:
+ *   - notifications: Array of Notification objects
+ *   - nextCursor: Pagination cursor for next page (if more exist)
+ */
+export declare const listNotifications: (request: import("next/server").NextRequest, context: {
+    params: Promise<Record<string, unknown>>;
+}) => Promise<import("next/server").NextResponse<import("..").PaginatedNotifications | {
+    error: string;
+}>>;
+/**
+ * GET /api/notifications/unread-count
+ *
+ * Gets the count of unread notifications for the authenticated user.
+ *
+ * @returns Object containing:
+ *   - count: Number of unread notifications
+ */
+export declare const getUnreadCount: (request: import("next/server").NextRequest, context: {
+    params: Promise<Record<string, unknown>>;
+}) => Promise<import("next/server").NextResponse<{
+    error: string;
+} | {
+    count: number;
+}>>;
+/**
+ * POST /api/notifications/:id/read
+ *
+ * Marks a specific notification as read.
+ *
+ * URL parameters:
+ * - id: Notification ID to mark as read (required)
+ *
+ * @returns Object containing:
+ *   - notificationId: ID of the notification
+ *   - read: Updated read status (true)
+ */
+export declare const markAsRead: (request: import("next/server").NextRequest, context: {
+    params: Promise<{
+        id: string;
+    }>;
+}) => Promise<import("next/server").NextResponse<{
+    error: string;
+} | {
+    notificationId: string;
+    read: boolean;
+}>>;
+/**
+ * POST /api/notifications/mark-all-read
+ *
+ * Marks all notifications as read for the authenticated user.
+ *
+ * @returns Object containing:
+ *   - updatedCount: Number of notifications marked as read
+ */
+export declare const markAllAsRead: (request: import("next/server").NextRequest, context: {
+    params: Promise<Record<string, unknown>>;
+}) => Promise<import("next/server").NextResponse<{
+    error: string;
+} | {
+    updatedCount: number;
+}>>;
+/**
+ * DELETE /api/notifications/:id
+ *
+ * Dismisses (soft deletes) a notification.
+ *
+ * URL parameters:
+ * - id: Notification ID to dismiss (required)
+ *
+ * @returns Object containing:
+ *   - notificationId: ID of the notification
+ *   - isDismissed: Updated dismissed status (true)
+ */
+export declare const dismissNotification: (request: import("next/server").NextRequest, context: {
+    params: Promise<{
+        id: string;
+    }>;
+}) => Promise<import("next/server").NextResponse<{
+    error: string;
+} | {
+    notificationId: string;
+    isDismissed: boolean;
+}>>;
+/**
+ * DELETE /api/notifications/dismiss-all
+ *
+ * Dismisses (soft deletes) all notifications for the authenticated user.
+ *
+ * @returns Object containing:
+ *   - dismissedCount: Number of notifications dismissed
+ */
+export declare const dismissAllNotifications: (request: import("next/server").NextRequest, context: {
+    params: Promise<Record<string, unknown>>;
+}) => Promise<import("next/server").NextResponse<{
+    error: string;
+} | {
+    dismissedCount: number;
+}>>;
+/**
+ * Export all handlers as a single object for type inference
+ */
+export declare const notificationHandlers: {
+    list: (request: import("next/server").NextRequest, context: {
+        params: Promise<Record<string, unknown>>;
+    }) => Promise<import("next/server").NextResponse<import("..").PaginatedNotifications | {
+        error: string;
+    }>>;
+    getUnreadCount: (request: import("next/server").NextRequest, context: {
+        params: Promise<Record<string, unknown>>;
+    }) => Promise<import("next/server").NextResponse<{
+        error: string;
+    } | {
+        count: number;
+    }>>;
+    markAsRead: (request: import("next/server").NextRequest, context: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<import("next/server").NextResponse<{
+        error: string;
+    } | {
+        notificationId: string;
+        read: boolean;
+    }>>;
+    markAllAsRead: (request: import("next/server").NextRequest, context: {
+        params: Promise<Record<string, unknown>>;
+    }) => Promise<import("next/server").NextResponse<{
+        error: string;
+    } | {
+        updatedCount: number;
+    }>>;
+    dismiss: (request: import("next/server").NextRequest, context: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<import("next/server").NextResponse<{
+        error: string;
+    } | {
+        notificationId: string;
+        isDismissed: boolean;
+    }>>;
+    dismissAll: (request: import("next/server").NextRequest, context: {
+        params: Promise<Record<string, unknown>>;
+    }) => Promise<import("next/server").NextResponse<{
+        error: string;
+    } | {
+        dismissedCount: number;
+    }>>;
+};
+//# sourceMappingURL=notifications.handlers.d.ts.map

package/dist/notifications/api/notifications.handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.handlers.d.ts","sourceRoot":"","sources":["../../../lib/notifications/api/notifications.handlers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB;;;;GA2B7B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;GAoB1B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU;;YAIiB,MAAM;;;;;;;GA4B7C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;GAqBzB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB;;YAIQ,MAAM;;;;;;;GA4B7C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;;;;GAsBnC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;gBA9IO,MAAM;;;;;;;;;;;;;;;;;gBA6EN,MAAM;;;;;;;;;;;;;;;CAwE7C,CAAC"}