feat(subscriptions): add topic-level updates (updateTopic, updateCategory)

Adds the two topic/category-scoped subscription writes. Each entry in
the payload sets the subscription state for a single (topic, mode) or
(category, mode) pair.

UPDATE_TOPIC reuses the same URL as GET_ALL — POST vs GET differentiates.

Adds TopicSubscriptionUpdate and CategorySubscriptionUpdate types,
response types, oauth-scopes entries, and unit + integration tests
(updateTopic round-trip; updateCategory unit-only because it needs
richer tenant fixtures).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarthak688

docs/oauth-scopes.md

@@ -227,6 +227,8 @@ The `ConversationalAgents` scope is required for real-time WebSocket sessions (`
 | `getAll()` | `NotificationService` |
 | `getPublishers()` | `NotificationService` |
 | `getSupportedChannels()` | `NotificationService` |
+| `updateTopic()` | `NotificationService` |
+| `updateCategory()` | `NotificationService` |
 
 ## Processes
 

src/models/notification/subscriptions.models.ts

@@ -3,11 +3,15 @@
  * that drives generated API documentation.
  */
 
+import type { OperationResponse } from '../common/types';
+
 import type {
+  CategorySubscriptionUpdate,
   SubscriptionGetAllOptions,
   SubscriptionGetPublishersOptions,
   SubscriptionPublisher,
   SupportedChannel,
+  TopicSubscriptionUpdate,
 } from './subscriptions.types';
 
 /**
@@ -30,6 +34,16 @@ export interface SubscriptionGetSupportedChannelsResponse {
   channels: SupportedChannel[];
 }
 
+/** Response from `updateTopic()`. */
+export type SubscriptionUpdateTopicResponse = OperationResponse<{
+  subscriptions: TopicSubscriptionUpdate[];
+}>;
+
+/** Response from `updateCategory()`. */
+export type SubscriptionUpdateCategoryResponse = OperationResponse<{
+  subscriptions: CategorySubscriptionUpdate[];
+}>;
+
 /**
  * Public surface of the Subscriptions service. JSDoc on this interface drives
  * the generated API reference documentation.
@@ -116,4 +130,49 @@ export interface SubscriptionServiceModel {
    * ```
    */
   getSupportedChannels(tenantId: string): Promise<SubscriptionGetSupportedChannelsResponse>;
+
+  /**
+   * Updates topic-level subscription preferences. Each entry sets the subscription state
+   * (`isSubscribed`) for a single (topic, mode) pair.
+   *
+   * @param tenantId - Tenant GUID (sent via `X-UIPATH-Internal-TenantId`)
+   * @param subscriptions - Topic subscription updates
+   * @returns Operation result echoing the submitted updates
+   * {@link SubscriptionUpdateTopicResponse}
+   *
+   * @example Unsubscribe a topic from a single channel
+   * ```typescript
+   * import { NotificationMode } from '@uipath/uipath-typescript/notifications';
+   *
+   * await subscriptions.updateTopic('<tenantId>', [
+   *   { topicId: '<topicId>', isSubscribed: false, notificationMode: NotificationMode.Email },
+   * ]);
+   * ```
+   */
+  updateTopic(tenantId: string, subscriptions: TopicSubscriptionUpdate[]): Promise<SubscriptionUpdateTopicResponse>;
+
+  /**
+   * Updates category-level subscription preferences for a publisher. Each entry sets
+   * the subscription state for all topics of a given category via a given mode.
+   *
+   * @param tenantId - Tenant GUID (sent via `X-UIPATH-Internal-TenantId`)
+   * @param subscriptions - Category subscription updates
+   * @returns Operation result echoing the submitted updates
+   * {@link SubscriptionUpdateCategoryResponse}
+   *
+   * @example Unsubscribe from all `Error` topics via email for one publisher
+   * ```typescript
+   * import { NotificationCategory, NotificationMode } from '@uipath/uipath-typescript/notifications';
+   *
+   * await subscriptions.updateCategory('<tenantId>', [
+   *   {
+   *     publisherId: '<publisherId>',
+   *     category: NotificationCategory.Error,
+   *     isSubscribed: false,
+   *     notificationMode: NotificationMode.Email,
+   *   },
+   * ]);
+   * ```
+   */
+  updateCategory(tenantId: string, subscriptions: CategorySubscriptionUpdate[]): Promise<SubscriptionUpdateCategoryResponse>;
 }

src/models/notification/subscriptions.types.ts

@@ -153,6 +153,32 @@ export interface SupportedChannel {
   isEnabled: boolean;
 }
 
+/**
+ * Update payload for a topic-level subscription change.
+ */
+export interface TopicSubscriptionUpdate {
+  /** Topic GUID. */
+  topicId: string;
+  /** Whether the user should be subscribed to this topic via the chosen mode. */
+  isSubscribed: boolean;
+  /** Notification channel this update applies to. */
+  notificationMode: NotificationMode;
+}
+
+/**
+ * Update payload for a category-level subscription change.
+ */
+export interface CategorySubscriptionUpdate {
+  /** Publisher GUID. */
+  publisherId: string;
+  /** Category to update. */
+  category: NotificationCategory;
+  /** Whether the user should be subscribed to topics of this category via the chosen mode. */
+  isSubscribed: boolean;
+  /** Notification channel this update applies to. */
+  notificationMode: NotificationMode;
+}
+
 /**
  * Options for `Subscriptions.getAll()`.
  */

src/services/notification/subscriptions.ts

@@ -6,13 +6,17 @@ import { track } from '../../core/telemetry';
 import { BaseService } from '../base';
 
 import type {
+  CategorySubscriptionUpdate,
   SubscriptionGetAllOptions,
   SubscriptionGetPublishersOptions,
+  TopicSubscriptionUpdate,
 } from '../../models/notification/subscriptions.types';
 import type {
   SubscriptionGetResponse,
   SubscriptionGetSupportedChannelsResponse,
   SubscriptionServiceModel,
+  SubscriptionUpdateCategoryResponse,
+  SubscriptionUpdateTopicResponse,
 } from '../../models/notification/subscriptions.models';
 
 import { SUBSCRIPTION_ENDPOINTS } from '../../utils/constants/endpoints';
@@ -138,4 +142,61 @@ export class SubscriptionService extends BaseService implements SubscriptionServ
     );
     return response.data;
   }
+
+  /**
+   * Updates topic-level subscription preferences. Each entry sets the subscription state
+   * (`isSubscribed`) for a single (topic, mode) pair.
+   *
+   * @param tenantId - Tenant GUID (sent via `X-UIPATH-Internal-TenantId`)
+   * @param subscriptions - Topic subscription updates
+   * @returns Operation result echoing the submitted updates
+   * {@link SubscriptionUpdateTopicResponse}
+   *
+   * @example Unsubscribe a topic from a single channel
+   * ```typescript
+   * import { NotificationMode } from '@uipath/uipath-typescript/notifications';
+   *
+   * await subscriptions.updateTopic('<tenantId>', [
+   *   { topicId: '<topicId>', isSubscribed: false, notificationMode: NotificationMode.Email },
+   * ]);
+   * ```
+   */
+  @track('Subscriptions.UpdateTopic')
+  async updateTopic(tenantId: string, subscriptions: TopicSubscriptionUpdate[]): Promise<SubscriptionUpdateTopicResponse> {
+    await this.post(SUBSCRIPTION_ENDPOINTS.UPDATE_TOPIC, {
+      userSubscriptions: subscriptions,
+    }, { headers: createHeaders({ [TENANT_ID]: tenantId }) });
+    return { success: true, data: { subscriptions } };
+  }
+
+  /**
+   * Updates category-level subscription preferences for a publisher. Each entry sets
+   * the subscription state for all topics of a given category via a given mode.
+   *
+   * @param tenantId - Tenant GUID (sent via `X-UIPATH-Internal-TenantId`)
+   * @param subscriptions - Category subscription updates
+   * @returns Operation result echoing the submitted updates
+   * {@link SubscriptionUpdateCategoryResponse}
+   *
+   * @example Unsubscribe from all `Error` topics via email for one publisher
+   * ```typescript
+   * import { NotificationCategory, NotificationMode } from '@uipath/uipath-typescript/notifications';
+   *
+   * await subscriptions.updateCategory('<tenantId>', [
+   *   {
+   *     publisherId: '<publisherId>',
+   *     category: NotificationCategory.Error,
+   *     isSubscribed: false,
+   *     notificationMode: NotificationMode.Email,
+   *   },
+   * ]);
+   * ```
+   */
+  @track('Subscriptions.UpdateCategory')
+  async updateCategory(tenantId: string, subscriptions: CategorySubscriptionUpdate[]): Promise<SubscriptionUpdateCategoryResponse> {
+    await this.post(SUBSCRIPTION_ENDPOINTS.UPDATE_CATEGORY, {
+      categorySubscriptions: subscriptions,
+    }, { headers: createHeaders({ [TENANT_ID]: tenantId }) });
+    return { success: true, data: { subscriptions } };
+  }
 }

src/utils/constants/endpoints/notification.ts

@@ -29,4 +29,7 @@ export const SUBSCRIPTION_ENDPOINTS = {
   GET_ALL: `${SUBSCRIPTION_API_BASE}/api/v1/UserSubscription`,
   GET_PUBLISHERS: `${SUBSCRIPTION_API_BASE}/api/v1/UserSubscription/GetPublishers`,
   GET_SUPPORTED_CHANNELS: `${SUBSCRIPTION_API_BASE}/api/v1/UserSubscription/GetSupportedChannelStatus`,
+  // Intentional duplicate URL of GET_ALL: same path, POST vs GET differentiates the operation.
+  UPDATE_TOPIC: `${SUBSCRIPTION_API_BASE}/api/v1/UserSubscription`,
+  UPDATE_CATEGORY: `${SUBSCRIPTION_API_BASE}/api/v1/UserSubscription/CategorySubscription`,
 } as const;

tests/integration/shared/notification/subscriptions.integration.test.ts

@@ -85,4 +85,31 @@ describe.each(modes)('Subscriptions - Integration Tests [%s]', (mode) => {
       }
     });
   });
+
+  describe('updateTopic', () => {
+    it('should round-trip a topic subscription change', async () => {
+      // Find a non-mandatory topic with at least one mode we can toggle
+      const topic = firstPublisher.topics.find((t) => t.isMandatory === false && (t.modes?.length ?? 0) > 0);
+      if (!topic) {
+        throw new Error('No non-mandatory topics with toggleable modes — cannot run updateTopic round-trip.');
+      }
+      const mode = topic.modes![0];
+      const originalState = mode.isSubscribed;
+
+      // Flip the state
+      const flip = await subscriptions.updateTopic(tenantId, [
+        { topicId: topic.id, isSubscribed: !originalState, notificationMode: mode.name },
+      ]);
+      expect(flip.success).toBe(true);
+
+      // Restore — leave the tenant in its original state
+      const restore = await subscriptions.updateTopic(tenantId, [
+        { topicId: topic.id, isSubscribed: originalState, notificationMode: mode.name },
+      ]);
+      expect(restore.success).toBe(true);
+    });
+  });
+
+  // Note: no updateCategory integration test — needs richer tenant fixtures (multi-topic
+  // category coverage). Covered by unit tests for SDK shape.
 });

tests/unit/services/notification/subscriptions.test.ts

@@ -12,6 +12,12 @@ import {
 import { createServiceTestDependencies, createMockApiClient } from '../../../utils/setup';
 import { SUBSCRIPTION_ENDPOINTS } from '../../../../src/utils/constants/endpoints';
 import { TENANT_ID } from '../../../../src/utils/constants/headers';
+import {
+  NotificationCategory,
+  NotificationMode,
+  type CategorySubscriptionUpdate,
+  type TopicSubscriptionUpdate,
+} from '../../../../src/models/notification';
 
 // ===== MOCKING =====
 vi.mock('../../../../src/core/http/api-client');
@@ -142,4 +148,78 @@ describe('SubscriptionService Unit Tests', () => {
       ).rejects.toThrow(TEST_CONSTANTS.ERROR_MESSAGE);
     });
   });
+
+  describe('updateTopic', () => {
+    it('should POST userSubscriptions with tenant header and echo input', async () => {
+      mockApiClient.post.mockResolvedValue(undefined);
+      const subscriptions: TopicSubscriptionUpdate[] = [
+        {
+          topicId: NOTIFICATION_TEST_CONSTANTS.TOPIC_ID,
+          isSubscribed: false,
+          notificationMode: NotificationMode.Email,
+        },
+      ];
+
+      const result = await subscriptionService.updateTopic(NOTIFICATION_TEST_CONSTANTS.TENANT_ID, subscriptions);
+
+      expect(mockApiClient.post).toHaveBeenCalledWith(
+        SUBSCRIPTION_ENDPOINTS.UPDATE_TOPIC,
+        { userSubscriptions: subscriptions },
+        { headers: TENANT_HEADER }
+      );
+      expect(result).toEqual({ success: true, data: { subscriptions } });
+    });
+
+    it('should propagate errors', async () => {
+      mockApiClient.post.mockRejectedValue(createMockError(NOTIFICATION_TEST_CONSTANTS.ERROR_SUBSCRIPTION_INVALID));
+
+      await expect(
+        subscriptionService.updateTopic(NOTIFICATION_TEST_CONSTANTS.TENANT_ID, [
+          {
+            topicId: NOTIFICATION_TEST_CONSTANTS.TOPIC_ID,
+            isSubscribed: true,
+            notificationMode: NotificationMode.InApp,
+          },
+        ])
+      ).rejects.toThrow(NOTIFICATION_TEST_CONSTANTS.ERROR_SUBSCRIPTION_INVALID);
+    });
+  });
+
+  describe('updateCategory', () => {
+    it('should POST categorySubscriptions with tenant header and echo input', async () => {
+      mockApiClient.post.mockResolvedValue(undefined);
+      const subscriptions: CategorySubscriptionUpdate[] = [
+        {
+          publisherId: NOTIFICATION_TEST_CONSTANTS.PUBLISHER_ID,
+          category: NotificationCategory.Error,
+          isSubscribed: false,
+          notificationMode: NotificationMode.Email,
+        },
+      ];
+
+      const result = await subscriptionService.updateCategory(NOTIFICATION_TEST_CONSTANTS.TENANT_ID, subscriptions);
+
+      expect(mockApiClient.post).toHaveBeenCalledWith(
+        SUBSCRIPTION_ENDPOINTS.UPDATE_CATEGORY,
+        { categorySubscriptions: subscriptions },
+        { headers: TENANT_HEADER }
+      );
+      expect(result).toEqual({ success: true, data: { subscriptions } });
+    });
+
+    it('should propagate errors', async () => {
+      mockApiClient.post.mockRejectedValue(createMockError(TEST_CONSTANTS.ERROR_MESSAGE));
+
+      await expect(
+        subscriptionService.updateCategory(NOTIFICATION_TEST_CONSTANTS.TENANT_ID, [
+          {
+            publisherId: NOTIFICATION_TEST_CONSTANTS.PUBLISHER_ID,
+            category: NotificationCategory.Info,
+            isSubscribed: true,
+            notificationMode: NotificationMode.InApp,
+          },
+        ])
+      ).rejects.toThrow(TEST_CONSTANTS.ERROR_MESSAGE);
+    });
+  });
 });

tests/utils/constants/notification.ts

@@ -36,4 +36,5 @@ export const NOTIFICATION_TEST_CONSTANTS = {
   // Error messages
   ERROR_NOTIFICATION_NOT_FOUND: 'Notification not found',
   ERROR_PUBLISHER_NOT_FOUND: 'Publisher not found',
+  ERROR_SUBSCRIPTION_INVALID: 'Subscription request is invalid',
 } as const;