convex-notifications 1.3.0 → 1.5.1

package/dist/client/index.d.ts

@@ -3,8 +3,34 @@ import type { NotificationsOptions, NotificationDefinition, RunQueryCtx, RunMuta
 import type { PushNotifications } from "@convex-dev/expo-push-notifications";
 import type { Resend } from "@convex-dev/resend";
 import type { Twilio } from "@convex-dev/twilio";
-export type { NotificationsOptions, NotificationDefinition } from "./types.js";
+export type { NotificationsOptions, NotificationDefinition, AuthIdentity } from "./types.js";
 export type { ChannelTemplates, EmailTemplate, InboxTemplate, PushTemplate, SmsTemplate, ChannelConfig, EmailChannelConfig, PushChannelConfig, SmsChannelConfig, DeliveryResult, SendResult, RunQueryCtx, RunMutationCtx, RunActionCtx, } from "./types.js";
+/**
+ * Create a typed notification definition.
+ *
+ * This helper function provides runtime validation and type inference
+ * for notification definitions.
+ *
+ * @example
+ * ```ts
+ * const welcomeNotification = createNotification({
+ *   event: "user.welcome",
+ *   dataValidator: v.object({ userName: v.string() }),
+ *   category: "onboarding",
+ *   channels: {
+ *     inbox: {
+ *       title: (data) => `Welcome, ${data.userName}!`,
+ *       body: () => "Thanks for joining.",
+ *     },
+ *     email: {
+ *       subject: (data) => `Welcome, ${data.userName}!`,
+ *       body: (data) => `Hi ${data.userName}, welcome aboard!`,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function createNotification<T>(definition: NotificationDefinition<T>): NotificationDefinition<T>;
 /**
  * Extended options that include child component clients for delivery.
  */
@@ -37,12 +63,21 @@ export declare class Notifications {
     component: ComponentApi;
     options: NotificationsWithChannelsOptions;
     constructor(component: ComponentApi, options: NotificationsWithChannelsOptions);
-    list(ctx: RunQueryCtx, opts?: {
-        limit?: number;
-        cursor?: number;
+    /**
+     * Resolve the auth identity and return userId + optional tenantId.
+     */
+    private resolveAuth;
+    /**
+     * Resolve channel config, which may be static or a per-tenant function.
+     */
+    private resolveChannelConfig;
+    list(ctx: RunQueryCtx, paginationOpts: {
+        numItems: number;
+        cursor: string | null;
     }): Promise<{
-        cursor: number | null;
-        notifications: any[];
+        page: any[];
+        isDone: boolean;
+        continueCursor: string;
     }>;
     unreadCount(ctx: RunQueryCtx): Promise<number>;
     markRead(ctx: RunMutationCtx, notificationId: string): Promise<null>;
@@ -70,6 +105,7 @@ export declare class Notifications {
     getPushTokens(ctx: RunQueryCtx): Promise<{
         _id: string;
         _creationTime: number;
+        tenantId?: string;
         userId: string;
         token: string;
         platform?: "ios" | "android" | "web";
@@ -79,6 +115,33 @@ export declare class Notifications {
      * Delete a push token.
      */
     deletePushToken(ctx: RunMutationCtx, token: string): Promise<boolean>;
+    /**
+     * Schedule a notification for future delivery.
+     *
+     * @returns The scheduled notification ID
+     */
+    schedule<T>(ctx: RunMutationCtx, definition: NotificationDefinition<T>, args: {
+        userId: string;
+        tenantId?: string;
+        data: T;
+        scheduledFor: number | Date;
+        transactional?: boolean;
+        deduplicationKey?: string;
+    }): Promise<{
+        scheduledNotificationId: string;
+    }>;
+    /**
+     * Cancel a scheduled notification.
+     *
+     * @returns true if cancelled, false if not found or already processed
+     */
+    cancelScheduled(ctx: RunMutationCtx, scheduledNotificationId: string): Promise<boolean>;
+    /**
+     * Get scheduled notifications for the current user.
+     */
+    getScheduledNotifications(ctx: RunQueryCtx, opts?: {
+        status?: "pending" | "processing" | "sent" | "failed" | "cancelled";
+    }): Promise<any[]>;
     /**
      * Send a notification through all enabled channels.
      *
@@ -86,6 +149,7 @@ export declare class Notifications {
      */
     send<T>(ctx: RunMutationCtx | RunActionCtx, definition: NotificationDefinition<T>, args: {
         userId: string;
+        tenantId?: string;
         data: T;
         transactional?: boolean;
         deduplicationKey?: string;
@@ -121,12 +185,20 @@ export declare class Notifications {
         /**
          * List notifications for the current user (paginated)
          */
+        /**
+         * List notifications for the current user (paginated).
+         * Uses standard Convex pagination via convex-helpers paginator.
+         * Compatible with usePaginatedQuery on the client.
+         */
         list: import("convex/server").RegisteredQuery<"public", {
-            limit?: number;
-            cursor?: number;
+            paginationOpts: {
+                numItems: number;
+                cursor: string | null;
+            };
         }, Promise<{
-            cursor: number | null;
-            notifications: any[];
+            page: any[];
+            isDone: boolean;
+            continueCursor: string;
         }>>;
         /**
          * Get unread notification count for the current user
@@ -161,6 +233,38 @@ export declare class Notifications {
             channel: string;
             enabled: boolean;
         }, Promise<string>>;
+        /**
+         * Register a push notification token for the current user
+         */
+        registerPushToken: import("convex/server").RegisteredMutation<"public", {
+            token: string;
+            platform?: "ios" | "android" | "web";
+            deviceId?: string;
+        }, Promise<string>>;
+        /**
+         * Get all push tokens for the current user
+         */
+        getPushTokens: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+            _id: string;
+            _creationTime: number;
+            tenantId?: string;
+            userId: string;
+            token: string;
+            platform?: "ios" | "android" | "web";
+            deviceId?: string;
+        }[]>>;
+        /**
+         * Delete a push token for the current user
+         */
+        deletePushToken: import("convex/server").RegisteredMutation<"public", {
+            token: string;
+        }, Promise<boolean>>;
+        /**
+         * Get delivery logs for a notification
+         */
+        getDeliveryLogs: import("convex/server").RegisteredQuery<"public", {
+            notificationId: string;
+        }, Promise<any[]>>;
     };
 }
 export default Notifications;

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/index.js

@@ -1,6 +1,55 @@
-import { queryGeneric, mutationGeneric } from "convex/server";
+import { queryGeneric, mutationGeneric, paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 import { dispatchEmail, dispatchPush, dispatchSms, isActionContext, } from "./adapters.js";
+/**
+ * Create a typed notification definition.
+ *
+ * This helper function provides runtime validation and type inference
+ * for notification definitions.
+ *
+ * @example
+ * ```ts
+ * const welcomeNotification = createNotification({
+ *   event: "user.welcome",
+ *   dataValidator: v.object({ userName: v.string() }),
+ *   category: "onboarding",
+ *   channels: {
+ *     inbox: {
+ *       title: (data) => `Welcome, ${data.userName}!`,
+ *       body: () => "Thanks for joining.",
+ *     },
+ *     email: {
+ *       subject: (data) => `Welcome, ${data.userName}!`,
+ *       body: (data) => `Hi ${data.userName}, welcome aboard!`,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createNotification(definition) {
+    // Validate required fields
+    if (!definition.event || definition.event.trim() === "") {
+        throw new Error("Notification definition must have a non-empty 'event' name");
+    }
+    if (!definition.channels || Object.keys(definition.channels).length === 0) {
+        throw new Error("Notification definition must have at least one channel template");
+    }
+    // Validate that at least inbox is defined (required for all notifications)
+    if (!definition.channels.inbox) {
+        throw new Error("Notification definition must include an 'inbox' channel template");
+    }
+    return definition;
+}
+/**
+ * Parse an AuthIdentity into userId and optional tenantId.
+ * Supports both string (backwards compat) and { userId, tenantId } forms.
+ */
+function parseIdentity(identity) {
+    if (typeof identity === "string") {
+        return { userId: identity };
+    }
+    return { userId: identity.userId, tenantId: identity.tenantId };
+}
 export class Notifications {
     component;
     options;
@@ -8,52 +57,79 @@ export class Notifications {
         this.component = component;
         this.options = options;
     }
-    async list(ctx, opts) {
-        const userId = await this.options.auth(ctx);
+    /**
+     * Resolve the auth identity and return userId + optional tenantId.
+     */
+    async resolveAuth(ctx) {
+        const identity = await this.options.auth(ctx);
+        return parseIdentity(identity);
+    }
+    /**
+     * Resolve channel config, which may be static or a per-tenant function.
+     */
+    async resolveChannelConfig(tenantId) {
+        const channels = this.options.channels;
+        if (!channels)
+            return undefined;
+        if (typeof channels === "function") {
+            if (!tenantId) {
+                throw new Error("Channel config is a function but no tenantId provided. Use multi-tenant auth or pass tenantId explicitly.");
+            }
+            return await channels(tenantId);
+        }
+        return channels;
+    }
+    async list(ctx, paginationOpts) {
+        const { userId, tenantId } = await this.resolveAuth(ctx);
         return await ctx.runQuery(this.component.inbox.list, {
+            tenantId,
             userId,
-            ...opts,
+            paginationOpts,
         });
     }
     async unreadCount(ctx) {
-        const userId = await this.options.auth(ctx);
-        return await ctx.runQuery(this.component.inbox.unreadCount, { userId });
+        const { userId, tenantId } = await this.resolveAuth(ctx);
+        return await ctx.runQuery(this.component.inbox.unreadCount, { tenantId, userId });
     }
     async markRead(ctx, notificationId) {
-        const userId = await this.options.auth(ctx);
+        const { userId, tenantId } = await this.resolveAuth(ctx);
         return await ctx.runMutation(this.component.inbox.markRead, {
+            tenantId,
             userId,
             notificationId,
         });
     }
     async markAllRead(ctx) {
-        const userId = await this.options.auth(ctx);
+        const { userId, tenantId } = await this.resolveAuth(ctx);
         return await ctx.runMutation(this.component.inbox.markAllRead, {
+            tenantId,
             userId,
         });
     }
     async archive(ctx, notificationId) {
-        const userId = await this.options.auth(ctx);
+        const { userId, tenantId } = await this.resolveAuth(ctx);
         return await ctx.runMutation(this.component.inbox.archive, {
+            tenantId,
             userId,
             notificationId,
         });
     }
     async getPreferences(ctx) {
-        const userId = await this.options.auth(ctx);
-        return await ctx.runQuery(this.component.preferences.getPreferences, { userId });
+        const { userId, tenantId } = await this.resolveAuth(ctx);
+        return await ctx.runQuery(this.component.preferences.getPreferences, { tenantId, userId });
     }
     async updatePreference(ctx, args) {
-        const userId = await this.options.auth(ctx);
-        return await ctx.runMutation(this.component.preferences.updatePreference, { userId, ...args });
+        const { userId, tenantId } = await this.resolveAuth(ctx);
+        return await ctx.runMutation(this.component.preferences.updatePreference, { tenantId, userId, ...args });
     }
     /**
      * Register a push notification token for a user.
      * Uses the component's internal push token storage.
      */
     async registerPushToken(ctx, args) {
-        const userId = await this.options.auth(ctx);
+        const { userId, tenantId } = await this.resolveAuth(ctx);
         return await ctx.runMutation(this.component.pushTokens.registerPushToken, {
+            tenantId,
             userId,
             token: args.token,
             platform: args.platform,
@@ -64,8 +140,9 @@ export class Notifications {
      * Get all push tokens for the current user.
      */
     async getPushTokens(ctx) {
-        const userId = await this.options.auth(ctx);
+        const { userId, tenantId } = await this.resolveAuth(ctx);
         return await ctx.runQuery(this.component.pushTokens.getPushTokens, {
+            tenantId,
             userId,
         });
     }
@@ -73,12 +150,78 @@ export class Notifications {
      * Delete a push token.
      */
     async deletePushToken(ctx, token) {
-        const userId = await this.options.auth(ctx);
+        const { userId, tenantId } = await this.resolveAuth(ctx);
         return await ctx.runMutation(this.component.pushTokens.deletePushToken, {
+            tenantId,
             userId,
             token,
         });
     }
+    /**
+     * Schedule a notification for future delivery.
+     *
+     * @returns The scheduled notification ID
+     */
+    async schedule(ctx, definition, args) {
+        const data = args.data;
+        const scheduledFor = args.scheduledFor instanceof Date
+            ? args.scheduledFor.getTime()
+            : args.scheduledFor;
+        // Validate scheduledFor is in the future
+        if (scheduledFor <= Date.now()) {
+            throw new Error("scheduledFor must be in the future");
+        }
+        // Render inbox template for storage
+        const inboxTemplate = definition.channels.inbox;
+        const title = inboxTemplate
+            ? inboxTemplate.title(data)
+            : definition.event;
+        const body = inboxTemplate ? inboxTemplate.body(data) : "";
+        // Scope deduplication key to tenant (consistent with send())
+        const scopedDeduplicationKey = args.deduplicationKey && args.tenantId
+            ? `${args.tenantId}:${args.deduplicationKey}`
+            : args.deduplicationKey;
+        const scheduledNotificationId = await ctx.runMutation(this.component.scheduled.scheduleNotification, {
+            tenantId: args.tenantId,
+            userId: args.userId,
+            event: definition.event,
+            category: definition.category,
+            title,
+            body,
+            data: args.data,
+            channels: definition.channels,
+            scheduledFor,
+            transactional: args.transactional,
+            deduplicationKey: scopedDeduplicationKey,
+        });
+        return { scheduledNotificationId };
+    }
+    /**
+     * Cancel a scheduled notification.
+     *
+     * @returns true if cancelled, false if not found or already processed
+     */
+    async cancelScheduled(ctx, scheduledNotificationId) {
+        const { userId, tenantId } = await this.resolveAuth(ctx);
+        return await ctx.runMutation(this.component.scheduled.cancelScheduledNotification, {
+            tenantId,
+            // scheduledNotificationId is a string returned by the component;
+            // Convex component IDs are serialized as strings across the boundary.
+            id: scheduledNotificationId,
+            userId,
+        });
+    }
+    /**
+     * Get scheduled notifications for the current user.
+     */
+    async getScheduledNotifications(ctx, opts) {
+        const { userId, tenantId } = await this.resolveAuth(ctx);
+        return await ctx.runQuery(this.component.scheduled.getScheduledNotifications, {
+            tenantId,
+            userId,
+            status: opts?.status,
+        });
+    }
     /**
      * Send a notification through all enabled channels.
      *
@@ -86,10 +229,14 @@ export class Notifications {
      */
     async send(ctx, definition, args) {
         const data = args.data;
+        const tenantId = args.tenantId;
         const deliveries = [];
-        // 1. Check deduplication
+        // 1. Check deduplication atomically (scope key to tenant if provided)
         if (args.deduplicationKey) {
-            const isDuplicate = await ctx.runQuery(this.component.notifications.checkDeduplication, { key: args.deduplicationKey });
+            const scopedKey = tenantId
+                ? `${tenantId}:${args.deduplicationKey}`
+                : args.deduplicationKey;
+            const isDuplicate = await ctx.runMutation(this.component.notifications.checkAndRecordDeduplication, { key: scopedKey, ttlSeconds: args.deduplicationTtlSeconds ?? 86400 });
             if (isDuplicate) {
                 throw new Error("Duplicate notification suppressed by deduplication key");
             }
@@ -101,6 +248,7 @@ export class Notifications {
             : definition.event;
         const body = inboxTemplate ? inboxTemplate.body(data) : "";
         const notificationId = await ctx.runMutation(this.component.notifications.createNotification, {
+            tenantId,
             userId: args.userId,
             event: definition.event,
             title,
@@ -108,13 +256,7 @@ export class Notifications {
             data: args.data,
             transactional: args.transactional,
         });
-        // 3. Record deduplication key
-        if (args.deduplicationKey) {
-            await ctx.runMutation(this.component.notifications.recordDeduplication, {
-                key: args.deduplicationKey,
-                ttlSeconds: args.deduplicationTtlSeconds ?? 86400,
-            });
-        }
+        // 3. Deduplication key already recorded atomically in step 1
         // 4. Resolve enabled channels
         const definedChannels = Object.keys(definition.channels);
         let enabledChannels;
@@ -123,6 +265,7 @@ export class Notifications {
         }
         else {
             enabledChannels = await ctx.runQuery(this.component.preferences.resolvePreferences, {
+                tenantId,
                 userId: args.userId,
                 event: definition.event,
                 category: definition.category,
@@ -133,7 +276,7 @@ export class Notifications {
         for (const channel of enabledChannels) {
             if (channel === "inbox")
                 continue;
-            const deliveryResult = await this.dispatchChannel(ctx, channel, definition, args.userId, data, notificationId);
+            const deliveryResult = await this.dispatchChannel(ctx, channel, definition, args.userId, data, notificationId, tenantId);
             if (deliveryResult) {
                 deliveries.push(deliveryResult);
             }
@@ -143,20 +286,22 @@ export class Notifications {
     /**
      * Dispatch a notification to a specific channel.
      */
-    async dispatchChannel(ctx, channel, definition, userId, data, notificationId) {
+    async dispatchChannel(ctx, channel, definition, userId, data, notificationId, tenantId) {
         let rendered;
         let result;
         try {
+            // Resolve channel config (may be per-tenant)
+            const channelConfig = await this.resolveChannelConfig(tenantId);
             if (channel === "email" && definition.channels.email) {
                 const emailTemplate = definition.channels.email;
-                const emailConfig = this.options.channels?.email;
+                const emailConfig = channelConfig?.email;
                 const resendClient = this.options.clients?.email;
                 // Resolve email address
                 const emailResolver = this.options.resolvers?.email;
                 if (!emailResolver) {
                     throw new Error("Email resolver not configured");
                 }
-                const toEmail = await emailResolver(ctx, userId);
+                const toEmail = await emailResolver(ctx, userId, tenantId);
                 if (!toEmail) {
                     return {
                         channel: "email",
@@ -164,10 +309,15 @@ export class Notifications {
                         error: "No email address for user",
                     };
                 }
+                // Resolve "from" address: sender resolver > template override > channel config default
+                let fromEmail = emailTemplate.from ?? emailConfig?.defaultFrom ?? "";
+                if (tenantId && this.options.senderResolvers?.email) {
+                    fromEmail = await this.options.senderResolvers.email(ctx, tenantId);
+                }
                 // Support async html rendering (e.g., React Email)
                 const html = emailTemplate.html ? await emailTemplate.html(data) : undefined;
                 const renderedEmail = {
-                    from: emailTemplate.from ?? emailConfig?.defaultFrom ?? "",
+                    from: fromEmail,
                     to: toEmail,
                     subject: emailTemplate.subject(data),
                     body: emailTemplate.body(data),
@@ -175,7 +325,7 @@ export class Notifications {
                 };
                 rendered = renderedEmail;
                 if (!renderedEmail.from) {
-                    throw new Error("No 'from' address configured. Set channels.email.defaultFrom or specify 'from' in the email template.");
+                    throw new Error("No 'from' address configured. Set channels.email.defaultFrom, configure a senderResolver, or specify 'from' in the email template.");
                 }
                 // Dispatch via Resend if client is configured
                 if (resendClient) {
@@ -193,7 +343,7 @@ export class Notifications {
             }
             else if (channel === "push" && definition.channels.push) {
                 const pushTemplate = definition.channels.push;
-                const pushConfig = this.options.channels?.push;
+                const pushConfig = channelConfig?.push;
                 const pushClient = this.options.clients?.push;
                 const renderedPush = {
                     userId,
@@ -217,14 +367,14 @@ export class Notifications {
             }
             else if (channel === "sms" && definition.channels.sms) {
                 const smsTemplate = definition.channels.sms;
-                const smsConfig = this.options.channels?.sms;
+                const smsConfig = channelConfig?.sms;
                 const twilioClient = this.options.clients?.sms;
                 // Resolve phone number
                 const phoneResolver = this.options.resolvers?.phone;
                 if (!phoneResolver) {
                     throw new Error("Phone resolver not configured");
                 }
-                const toPhone = await phoneResolver(ctx, userId);
+                const toPhone = await phoneResolver(ctx, userId, tenantId);
                 if (!toPhone) {
                     return {
                         channel: "sms",
@@ -232,14 +382,19 @@ export class Notifications {
                         error: "No phone number for user",
                     };
                 }
+                // Resolve "from" number: sender resolver > template override > channel config default
+                let fromPhone = smsTemplate.from ?? smsConfig?.defaultFrom ?? "";
+                if (tenantId && this.options.senderResolvers?.sms) {
+                    fromPhone = await this.options.senderResolvers.sms(ctx, tenantId);
+                }
                 const renderedSms = {
-                    from: smsTemplate.from ?? smsConfig?.defaultFrom ?? "",
+                    from: fromPhone,
                     to: toPhone,
                     body: smsTemplate.body(data),
                 };
                 rendered = renderedSms;
                 if (!renderedSms.from) {
-                    throw new Error("No 'from' phone number configured. Set channels.sms.defaultFrom or specify 'from' in the SMS template.");
+                    throw new Error("No 'from' phone number configured. Set channels.sms.defaultFrom, configure a senderResolver, or specify 'from' in the SMS template.");
                 }
                 // Dispatch via Twilio if client is configured AND we have action context
                 if (twilioClient) {
@@ -290,6 +445,7 @@ export class Notifications {
                     ? "pending"
                     : "failed";
             await ctx.runMutation(this.component.delivery.createDeliveryLog, {
+                tenantId,
                 notificationId,
                 channel,
                 status,
@@ -307,6 +463,7 @@ export class Notifications {
             console.error(`[notifications] ${channel} dispatch failed:`, error);
             // Create failed delivery log entry
             await ctx.runMutation(this.component.delivery.createDeliveryLog, {
+                tenantId,
                 notificationId,
                 channel,
                 status: "failed",
@@ -357,16 +514,21 @@ export class Notifications {
             /**
              * List notifications for the current user (paginated)
              */
+            /**
+             * List notifications for the current user (paginated).
+             * Uses standard Convex pagination via convex-helpers paginator.
+             * Compatible with usePaginatedQuery on the client.
+             */
             list: queryGeneric({
                 args: {
-                    limit: v.optional(v.number()),
-                    cursor: v.optional(v.number()),
+                    paginationOpts: paginationOptsValidator,
                 },
                 returns: v.object({
-                    notifications: v.array(v.any()),
-                    cursor: v.union(v.number(), v.null()),
+                    page: v.array(v.any()),
+                    isDone: v.boolean(),
+                    continueCursor: v.string(),
                 }),
-                handler: (ctx, args) => self.list(ctx, args),
+                handler: (ctx, args) => self.list(ctx, args.paginationOpts),
             }),
             /**
              * Get unread notification count for the current user
@@ -421,6 +583,42 @@ export class Notifications {
                 returns: v.string(),
                 handler: (ctx, args) => self.updatePreference(ctx, args),
             }),
+            /**
+             * Register a push notification token for the current user
+             */
+            registerPushToken: mutationGeneric({
+                args: {
+                    token: v.string(),
+                    platform: v.optional(v.union(v.literal("ios"), v.literal("android"), v.literal("web"))),
+                    deviceId: v.optional(v.string()),
+                },
+                returns: v.string(),
+                handler: (ctx, args) => self.registerPushToken(ctx, args),
+            }),
+            /**
+             * Get all push tokens for the current user
+             */
+            getPushTokens: queryGeneric({
+                args: {},
+                returns: v.array(v.any()),
+                handler: (ctx) => self.getPushTokens(ctx),
+            }),
+            /**
+             * Delete a push token for the current user
+             */
+            deletePushToken: mutationGeneric({
+                args: { token: v.string() },
+                returns: v.boolean(),
+                handler: (ctx, args) => self.deletePushToken(ctx, args.token),
+            }),
+            /**
+             * Get delivery logs for a notification
+             */
+            getDeliveryLogs: queryGeneric({
+                args: { notificationId: v.string() },
+                returns: v.array(v.any()),
+                handler: (ctx, args) => self.getDeliveryLogs(ctx, args.notificationId),
+            }),
         };
     }
 }