vintasend 0.5.2 → 0.6.0

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export type { LocalFileAttachmentManagerConfig } from './services/attachment-man
 export { LocalFileAttachmentManager } from './services/attachment-manager/local-file-attachment-manager';
 export { BaseNotificationAdapter, isOneOffNotification, } from './services/notification-adapters/base-notification-adapter';
 export type { BaseNotificationBackend } from './services/notification-backends/base-notification-backend';
-export { supportsAttachments } from './services/notification-backends/base-notification-backend';
+export { supportsAttachments, isFieldFilter } from './services/notification-backends/base-notification-backend';
+export type { NotificationFilter, NotificationFilterFields, DateRange, NotificationFilterCapabilities } from './services/notification-backends/base-notification-backend';
 export type { BaseNotificationQueueService } from './services/notification-queue-service/base-notification-queue-service';
 export type { VintaSend } from './services/notification-service';
 export { VintaSendFactory } from './services/notification-service';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isAttachmentReference = exports.VintaSendFactory = exports.supportsAttachments = exports.isOneOffNotification = exports.BaseNotificationAdapter = exports.LocalFileAttachmentManager = exports.BaseAttachmentManager = void 0;
+exports.isAttachmentReference = exports.VintaSendFactory = exports.isFieldFilter = exports.supportsAttachments = exports.isOneOffNotification = exports.BaseNotificationAdapter = exports.LocalFileAttachmentManager = exports.BaseAttachmentManager = void 0;
 // Attachment Manager
 var base_attachment_manager_1 = require("./services/attachment-manager/base-attachment-manager");
 Object.defineProperty(exports, "BaseAttachmentManager", { enumerable: true, get: function () { return base_attachment_manager_1.BaseAttachmentManager; } });
@@ -11,6 +11,7 @@ Object.defineProperty(exports, "BaseNotificationAdapter", { enumerable: true, ge
 Object.defineProperty(exports, "isOneOffNotification", { enumerable: true, get: function () { return base_notification_adapter_1.isOneOffNotification; } });
 var base_notification_backend_1 = require("./services/notification-backends/base-notification-backend");
 Object.defineProperty(exports, "supportsAttachments", { enumerable: true, get: function () { return base_notification_backend_1.supportsAttachments; } });
+Object.defineProperty(exports, "isFieldFilter", { enumerable: true, get: function () { return base_notification_backend_1.isFieldFilter; } });
 var notification_service_1 = require("./services/notification-service");
 Object.defineProperty(exports, "VintaSendFactory", { enumerable: true, get: function () { return notification_service_1.VintaSendFactory; } });
 var attachment_1 = require("./types/attachment");

package/dist/services/notification-backends/base-notification-backend.d.ts

@@ -1,8 +1,62 @@
 import type { AttachmentFileRecord, StoredAttachment } from '../../types/attachment';
 import type { InputJsonValue } from '../../types/json-values';
+import type { NotificationStatus } from '../../types/notification-status';
+import type { NotificationType } from '../../types/notification-type';
 import type { AnyDatabaseNotification, AnyNotification, DatabaseNotification, DatabaseOneOffNotification, Notification, OneOffNotificationInput } from '../../types/notification';
 import type { BaseNotificationTypeConfig } from '../../types/notification-type-config';
 import type { BaseLogger } from '../loggers/base-logger';
+/**
+ * Date range filter with optional lower and upper bounds.
+ */
+export type DateRange = {
+    from?: Date;
+    to?: Date;
+};
+/**
+ * Flat dotted key capability map describing which filter features a backend supports.
+ * Use flat dotted keys for logical operators, fields, and negations:
+ * - `logical.*`: Operator support (and, or, not, notNested)
+ * - `fields.*`: Field filtering support
+ * - `negation.*`: Negation support for specific fields
+ *
+ * When a backend implements getFilterCapabilities(), missing keys default to true (supported),
+ * ensuring forward compatibility when new capabilities are added.
+ * Backends that don't implement getFilterCapabilities() are treated as supporting all features.
+ */
+export type NotificationFilterCapabilities = {
+    [key: string]: boolean;
+};
+/**
+ * Leaf-level filter conditions for notification fields.
+ * All specified fields are combined with implicit AND.
+ */
+export type NotificationFilterFields<Config extends BaseNotificationTypeConfig> = {
+    status?: NotificationStatus | NotificationStatus[];
+    notificationType?: NotificationType | NotificationType[];
+    adapterUsed?: string | string[];
+    userId?: Config['UserIdType'];
+    bodyTemplate?: string;
+    subjectTemplate?: string;
+    contextName?: string;
+    sendAfterRange?: DateRange;
+    createdAtRange?: DateRange;
+    sentAtRange?: DateRange;
+};
+/**
+ * Composable notification filter supporting logical operators.
+ *
+ * - A plain field filter applies all conditions with implicit AND.
+ * - `{ and: [...] }` requires all sub-filters to match.
+ * - `{ or: [...] }` requires at least one sub-filter to match.
+ * - `{ not: filter }` inverts the sub-filter.
+ */
+export type NotificationFilter<Config extends BaseNotificationTypeConfig> = NotificationFilterFields<Config> | {
+    and: NotificationFilter<Config>[];
+} | {
+    or: NotificationFilter<Config>[];
+} | {
+    not: NotificationFilter<Config>;
+};
 export interface BaseNotificationBackend<Config extends BaseNotificationTypeConfig> {
     getAllPendingNotifications(): Promise<AnyDatabaseNotification<Config>[]>;
     getPendingNotifications(page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
@@ -23,12 +77,40 @@ export interface BaseNotificationBackend<Config extends BaseNotificationTypeConf
     filterAllInAppUnreadNotifications(userId: Config['UserIdType']): Promise<DatabaseNotification<Config>[]>;
     filterInAppUnreadNotifications(userId: Config['UserIdType'], page: number, pageSize: number): Promise<DatabaseNotification<Config>[]>;
     getUserEmailFromNotification(notificationId: Config['NotificationIdType']): Promise<string | undefined>;
-    storeContextUsed(notificationId: Config['NotificationIdType'], context: InputJsonValue): Promise<void>;
+    storeAdapterAndContextUsed(notificationId: Config['NotificationIdType'], adapterKey: string, context: InputJsonValue): Promise<void>;
     persistOneOffNotification(notification: Omit<OneOffNotificationInput<Config>, 'id'>): Promise<DatabaseOneOffNotification<Config>>;
     persistOneOffNotificationUpdate(notificationId: Config['NotificationIdType'], notification: Partial<Omit<OneOffNotificationInput<Config>, 'id'>>): Promise<DatabaseOneOffNotification<Config>>;
     getOneOffNotification(notificationId: Config['NotificationIdType'], forUpdate: boolean): Promise<DatabaseOneOffNotification<Config> | null>;
     getAllOneOffNotifications(): Promise<DatabaseOneOffNotification<Config>[]>;
     getOneOffNotifications(page: number, pageSize: number): Promise<DatabaseOneOffNotification<Config>[]>;
+    /**
+     * Filter notifications using composable query filters.
+     * Supports filtering by status, notification type, adapter, recipient,
+      * body/subject templates, context, and date ranges (sendAfter, created, sent).
+     * Filters can be combined with logical operators (and, or, not).
+     *
+     * @param filter - Composable filter expression
+     * @param page - Page number (1-indexed) for pagination
+     * @param pageSize - Number of results per page
+     * @returns Matching notifications
+     */
+    filterNotifications(filter: NotificationFilter<Config>, page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
+    /**
+     * Get the filter capabilities supported by this backend.
+     * Returns an object with flat dotted keys indicating which filtering features are supported.
+     *
+     * Example capability names:
+     * - `logical.and`, `logical.or`, `logical.not`, `logical.notNested`
+     * - `fields.status`, `fields.notificationType`, `fields.adapterUsed`, `fields.userId`,
+     *   `fields.bodyTemplate`, `fields.subjectTemplate`, `fields.contextName`,
+    *   `fields.sendAfterRange`, `fields.createdAtRange`, `fields.sentAtRange`
+    * - `negation.sendAfterRange`, `negation.createdAtRange`, `negation.sentAtRange`
+     *
+     * If this method is not implemented, all features are assumed to be supported.
+     * If this method is implemented, missing keys default to true (supported) for forward compatibility.
+     * Only explicitly set keys to false to indicate unsupported features.
+     */
+    getFilterCapabilities?(): NotificationFilterCapabilities;
     /**
      * Inject logger into backend for debugging and monitoring
      */
@@ -73,6 +155,10 @@ export interface BaseNotificationBackend<Config extends BaseNotificationTypeConf
      */
     deleteNotificationAttachment?(notificationId: Config['NotificationIdType'], attachmentId: string): Promise<void>;
 }
+/**
+ * Type guard to check if a filter is a field filter (leaf node).
+ */
+export declare function isFieldFilter<Config extends BaseNotificationTypeConfig>(filter: NotificationFilter<Config>): filter is NotificationFilterFields<Config>;
 /**
  * Type guard to check if backend supports attachment operations
  */

package/dist/services/notification-backends/base-notification-backend.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFieldFilter = isFieldFilter;
 exports.supportsAttachments = supportsAttachments;
+/**
+ * Type guard to check if a filter is a field filter (leaf node).
+ */
+function isFieldFilter(filter) {
+    return !('and' in filter) && !('or' in filter) && !('not' in filter);
+}
 /**
  * Type guard to check if backend supports attachment operations
  */

package/dist/services/notification-service.js

@@ -77,6 +77,7 @@ class VintaSend {
         this.queueService = queueService;
     }
     async send(notification) {
+        var _a;
         const adaptersOfType = this.adapters.filter((adapter) => adapter.notificationType === notification.notificationType);
         if (adaptersOfType.length === 0) {
             this.logger.error(`No adapter found for notification type ${notification.notificationType}`);
@@ -144,10 +145,10 @@ class VintaSend {
                 this.logger.error(`Error marking notification ${notification.id} as sent: ${markSentError}`);
             }
             try {
-                await this.backend.storeContextUsed(notification.id, context !== null && context !== void 0 ? context : {});
+                await this.backend.storeAdapterAndContextUsed(notification.id, (_a = adapter.key) !== null && _a !== void 0 ? _a : 'unknown', context !== null && context !== void 0 ? context : {});
             }
             catch (storeContextError) {
-                this.logger.error(`Error storing context for notification ${notification.id}: ${storeContextError}`);
+                this.logger.error(`Error storing adapter and context for notification ${notification.id}: ${storeContextError}`);
             }
         }
     }
@@ -347,6 +348,7 @@ class VintaSend {
         return createdNotification;
     }
     async delayedSend(notificationId) {
+        var _a;
         const notification = await this.getNotification(notificationId, false);
         if (!notification) {
             this.logger.error(`Notification ${notificationId} not found`);
@@ -364,7 +366,9 @@ class VintaSend {
             return;
         }
         const context = await this.getNotificationContext(notification.contextName, notification.contextParameters);
+        let lastAdapterKey = 'unknown';
         for (const adapter of enqueueNotificationsAdapters) {
+            lastAdapterKey = (_a = adapter.key) !== null && _a !== void 0 ? _a : 'unknown';
             try {
                 await adapter.send(notification, context);
             }
@@ -385,10 +389,10 @@ class VintaSend {
             }
         }
         try {
-            await this.backend.storeContextUsed(notification.id, context);
+            await this.backend.storeAdapterAndContextUsed(notification.id, lastAdapterKey, context);
         }
         catch (storeContextError) {
-            this.logger.error(`Error storing context for notification ${notification.id}: ${storeContextError}`);
+            this.logger.error(`Error storing adapter and context for notification ${notification.id}: ${storeContextError}`);
         }
     }
     async bulkPersistNotifications(notifications) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vintasend",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "main": "dist/index.js",
   "files": [
     "dist"
@@ -16,6 +16,7 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "test:implementations:local": "node scripts/test-implementations-local.js",
     "release:bump": "node scripts/release-bump.js",
     "release:bump:patch": "node scripts/release-bump.js --bump=patch",
     "release:bump:minor": "node scripts/release-bump.js --bump=minor",