vintasend 0.8.0 → 0.8.2

package/README.md

@@ -159,6 +159,57 @@ const backendStats = await vintasend.getBackendSyncStats();
 - Additional backend replication failures are logged and do not fail the primary operation.
 - This keeps primary workflows available while still enabling redundancy.
 
+## Filtering and Ordering Notifications
+
+Use `filterNotifications` to query notifications with pagination and optional ordering.
+
+```typescript
+const notifications = await vintasend.filterNotifications(
+  {
+    status: 'PENDING_SEND',
+  },
+  1,
+  25,
+  {
+    field: 'createdAt',
+    direction: 'desc',
+  },
+);
+```
+
+### `orderBy` shape
+
+```typescript
+type NotificationOrderBy = {
+  field: 'sendAfter' | 'sentAt' | 'readAt' | 'createdAt' | 'updatedAt';
+  direction: 'asc' | 'desc';
+};
+```
+
+Examples:
+- `{ field: 'createdAt', direction: 'desc' }`
+- `{ field: 'sendAfter', direction: 'asc' }`
+
+### Checking backend support
+
+Use `getBackendSupportedFilterCapabilities()` to detect support gaps per backend.
+
+```typescript
+const capabilities = await vintasend.getBackendSupportedFilterCapabilities();
+
+if (!capabilities['orderBy.readAt']) {
+  // Fallback to another ordering field
+}
+```
+
+When using multiple backends, you can check capabilities for a specific backend identifier:
+
+```typescript
+const replicaCapabilities = await vintasend.getBackendSupportedFilterCapabilities('replica-backend');
+```
+
+`vintasend-medplum` currently does not support `orderBy.readAt`, and reports `orderBy.readAt: false`.
+
 ## Attachment Support
 
 VintaSend supports file attachments for notifications with an extensible architecture that allows you to choose your preferred storage backend.

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

@@ -18,6 +18,12 @@ export type StringFilterLookup = {
     caseSensitive?: boolean;
 };
 export type StringFieldFilter = string | StringFilterLookup;
+export type NotificationOrderByField = 'sendAfter' | 'sentAt' | 'readAt' | 'createdAt' | 'updatedAt';
+export type NotificationOrderDirection = 'asc' | 'desc';
+export type NotificationOrderBy = {
+    field: NotificationOrderByField;
+    direction: NotificationOrderDirection;
+};
 /**
  * Flat dotted key capability map describing which filter features a backend supports.
  * Use flat dotted keys for logical operators, fields, and negations:
@@ -85,6 +91,11 @@ export declare const DEFAULT_BACKEND_FILTER_CAPABILITIES: {
     'stringLookups.endsWith': boolean;
     'stringLookups.includes': boolean;
     'stringLookups.caseInsensitive': boolean;
+    'orderBy.sendAfter': boolean;
+    'orderBy.sentAt': boolean;
+    'orderBy.readAt': boolean;
+    'orderBy.createdAt': boolean;
+    'orderBy.updatedAt': boolean;
 };
 export interface BaseNotificationBackend<Config extends BaseNotificationTypeConfig> {
     /**
@@ -134,7 +145,7 @@ export interface BaseNotificationBackend<Config extends BaseNotificationTypeConf
      * @param pageSize - Number of results per page
      * @returns Matching notifications
      */
-    filterNotifications(filter: NotificationFilter<Config>, page: number, pageSize: number): Promise<AnyDatabaseNotification<Config>[]>;
+    filterNotifications(filter: NotificationFilter<Config>, page: number, pageSize: number, orderBy?: NotificationOrderBy): Promise<AnyDatabaseNotification<Config>[]>;
     /**
      * Get the filter capabilities supported by this backend.
      * Returns an object with flat dotted keys indicating which filtering features are supported.

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

@@ -26,6 +26,11 @@ exports.DEFAULT_BACKEND_FILTER_CAPABILITIES = {
     'stringLookups.endsWith': true,
     'stringLookups.includes': true,
     'stringLookups.caseInsensitive': true,
+    'orderBy.sendAfter': true,
+    'orderBy.sentAt': true,
+    'orderBy.readAt': true,
+    'orderBy.createdAt': true,
+    'orderBy.updatedAt': true,
 };
 /**
  * Type guard to check if a filter is a field filter (leaf node).

package/dist/services/notification-service.d.ts

@@ -6,7 +6,7 @@ import type { BaseAttachmentManager } from './attachment-manager/base-attachment
 import type { BaseGitCommitShaProvider } from './git-commit-sha/base-git-commit-sha-provider';
 import type { BaseLogger } from './loggers/base-logger';
 import { type BaseNotificationAdapter } from './notification-adapters/base-notification-adapter';
-import { type BaseNotificationBackend, type NotificationFilterFields } from './notification-backends/base-notification-backend';
+import { type BaseNotificationBackend, type NotificationFilterFields, type NotificationOrderBy } from './notification-backends/base-notification-backend';
 import type { BaseNotificationQueueService } from './notification-queue-service/base-notification-queue-service';
 import type { EmailTemplate, EmailTemplateContent } from './notification-template-renderers/base-email-template-renderer';
 import type { BaseNotificationTemplateRenderer } from './notification-template-renderers/base-notification-template-renderer';
@@ -145,7 +145,7 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
     /**
      * Filters notifications in the primary backend by default or in a specific backend.
      */
-    filterNotifications(filter: NotificationFilterFields<Config>, page: number, pageSize: number, backendIdentifier?: string): Promise<AnyDatabaseNotification<Config>[]>;
+    filterNotifications(filter: NotificationFilterFields<Config>, page: number, pageSize: number, orderBy?: NotificationOrderBy, backendIdentifier?: string): Promise<AnyDatabaseNotification<Config>[]>;
     /**
      * Returns the effective filter capabilities for the primary backend by default or for a specific backend.
      */
@@ -171,6 +171,11 @@ export declare class VintaSend<Config extends BaseNotificationTypeConfig, Adapte
         'stringLookups.endsWith': boolean;
         'stringLookups.includes': boolean;
         'stringLookups.caseInsensitive': boolean;
+        'orderBy.sendAfter': boolean;
+        'orderBy.sentAt': boolean;
+        'orderBy.readAt': boolean;
+        'orderBy.createdAt': boolean;
+        'orderBy.updatedAt': boolean;
     }>;
     /**
      * Gets a one-off notification by ID.

package/dist/services/notification-service.js

@@ -428,8 +428,8 @@ class VintaSend {
     /**
      * Filters notifications in the primary backend by default or in a specific backend.
      */
-    async filterNotifications(filter, page, pageSize, backendIdentifier) {
-        return this.getBackend(backendIdentifier).filterNotifications(filter, page, pageSize);
+    async filterNotifications(filter, page, pageSize, orderBy, backendIdentifier) {
+        return this.getBackend(backendIdentifier).filterNotifications(filter, page, pageSize, orderBy);
     }
     /**
      * Returns the effective filter capabilities for the primary backend by default or for a specific backend.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vintasend",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "main": "dist/index.js",
   "files": [
     "dist"