feat(notifications): add Notifications service foundation + getAll

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: 3 people

package.json

@@ -205,6 +205,16 @@
                 "types": "./dist/governance/index.d.ts",
                 "default": "./dist/governance/index.cjs"
             }
+        },
+        "./notifications": {
+            "import": {
+                "types": "./dist/notifications/index.d.ts",
+                "default": "./dist/notifications/index.mjs"
+            },
+            "require": {
+                "types": "./dist/notifications/index.d.ts",
+                "default": "./dist/notifications/index.cjs"
+            }
         }
     },
     "files": [

rollup.config.js

@@ -223,6 +223,11 @@ const serviceEntries = [
     name: 'governance',
     input: 'src/services/governance/index.ts',
     output: 'governance/index'
+  },
+  {
+    name: 'notifications',
+    input: 'src/services/notification/index.ts',
+    output: 'notifications/index'
   }
 ];
 

src/models/notification/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Notification models barrel export.
+ */
+
+export * from './notifications.types';
+export * from './notifications.models';

src/models/notification/notifications.internal-types.ts

@@ -0,0 +1,37 @@
+/**
+ * Internal-only types for the Notification service.
+ *
+ * NOT exported from the public barrel (`src/models/notification/index.ts`).
+ */
+
+import type { NotificationGetResponse } from './notifications.types';
+
+/**
+ * Raw notification entry shape as returned by `/odata/v1/NotificationEntry` — includes
+ * the internal/transport-layer fields the SDK drops before returning to consumers.
+ */
+export interface RawNotificationEntry extends NotificationGetResponse {
+  entityOrgName?: string | null;
+  entityTenantName?: string | null;
+  serviceRegistryName?: string | null;
+  messageTemplateKey?: string | null;
+  messageVersion?: number;
+  publicationId?: string;
+  correlationId?: string | null;
+  partitionKey?: string;
+}
+
+/**
+ * Fields stripped from each {@link RawNotificationEntry} before it is returned to the
+ * SDK consumer as a {@link NotificationGetResponse}.
+ */
+export const INTERNAL_NOTIFICATION_FIELDS: ReadonlyArray<keyof RawNotificationEntry> = [
+  'entityOrgName',
+  'entityTenantName',
+  'serviceRegistryName',
+  'messageTemplateKey',
+  'messageVersion',
+  'publicationId',
+  'correlationId',
+  'partitionKey',
+];

src/models/notification/notifications.models.ts

@@ -0,0 +1,71 @@
+/**
+ * Notification service model — public response shapes and the ServiceModel interface
+ * that drives generated API documentation.
+ */
+
+import type {
+  HasPaginationOptions,
+  NonPaginatedResponse,
+  PaginatedResponse,
+} from '../../utils/pagination/types';
+
+import type {
+  NotificationGetAllOptions,
+  NotificationGetResponse,
+} from './notifications.types';
+
+/**
+ * Public surface of the Notifications service. JSDoc on this interface drives
+ * the generated API reference documentation.
+ *
+ * Every method takes the tenant GUID as the first argument — the notification
+ * API identifies the acting tenant via the `X-UIPATH-Internal-TenantId` header
+ * and the SDK forwards `tenantId` into that header on each call.
+ */
+export interface NotificationServiceModel {
+  /**
+   * Lists notifications from the current user's inbox.
+   *
+   * Returns the full list when no pagination params are provided, or a paginated cursor result
+   * when any of `pageSize`/`cursor`/`jumpToPage` is supplied. Supports OData `filter` and
+   * `orderby` query options.
+   *
+   * @param tenantId - Tenant GUID (sent via `X-UIPATH-Internal-TenantId`)
+   * @param options - Optional OData query and pagination options
+   * @returns Array of notifications, or a paginated result when pagination params are supplied
+   * {@link NotificationGetResponse}
+   *
+   * @example Basic usage
+   * ```typescript
+   * import { Notifications } from '@uipath/uipath-typescript/notifications';
+   *
+   * const notifications = new Notifications(sdk);
+   * const all = await notifications.getAll('<tenantId>');
+   * ```
+   *
+   * @example Filter unread, most recent first
+   * ```typescript
+   * const unread = await notifications.getAll('<tenantId>', {
+   *   filter: 'isRead eq false',
+   *   orderby: 'publishedOn desc',
+   * });
+   * ```
+   *
+   * @example First page with pagination
+   * ```typescript
+   * const page1 = await notifications.getAll('<tenantId>', { pageSize: 20 });
+   * if (page1.hasNextPage) {
+   *   const page2 = await notifications.getAll('<tenantId>', { cursor: page1.nextCursor });
+   * }
+   * ```
+   * @internal
+   */
+  getAll<T extends NotificationGetAllOptions = NotificationGetAllOptions>(
+    tenantId: string,
+    options?: T
+  ): Promise<
+    T extends HasPaginationOptions<T>
+      ? PaginatedResponse<NotificationGetResponse>
+      : NonPaginatedResponse<NotificationGetResponse>
+  >;
+}

src/models/notification/notifications.types.ts

@@ -0,0 +1,86 @@
+/**
+ * Notification inbox types — raw API shapes and request/response options.
+ */
+
+import type { RequestOptions } from '../common/types';
+import type { PaginationOptions } from '../../utils/pagination/types';
+
+/**
+ * Priority level assigned to a notification by the publisher.
+ */
+export enum NotificationPriority {
+  Low = 'Low',
+  Medium = 'Medium',
+  High = 'High',
+  Critical = 'Critical',
+}
+
+/**
+ * Severity classification of a notification topic.
+ */
+export enum NotificationCategory {
+  /** Informational — no action required. */
+  Info = 'Info',
+  /** Successful operation completed. */
+  Success = 'Success',
+  /** Warning — degraded behaviour or non-fatal issue. */
+  Warn = 'Warn',
+  /** Error — operation failed but the system continues. */
+  Error = 'Error',
+  /** Fatal — unrecoverable failure. */
+  Fatal = 'Fatal',
+}
+
+/**
+ * Notification entry as returned by `GET /odata/v1/NotificationEntry`.
+ *
+ * Field selection: many internal/transport-layer fields (`partitionKey`, `correlationId`,
+ * `publicationId`, `messageVersion`, `messageTemplateKey`, `serviceRegistryName`,
+ * `entityOrgName`, `entityTenantName`) are returned by the API but dropped from the SDK
+ * because they have no use for an application developer.
+ */
+export interface NotificationGetResponse {
+  /** Notification GUID. */
+  id: string;
+  /** Resolved notification message text. */
+  message: string | null;
+  /** Whether the user has read this notification. */
+  isRead: boolean;
+  /** Name of the publisher (e.g. `Orchestrator`, `Actions`). */
+  publisherName: string;
+  /** Publisher GUID. */
+  publisherId: string;
+  /** Human-readable topic name. */
+  topicName: string;
+  /** Stable topic identifier (e.g. `Process.JobExecution.Faulted`). */
+  topicKeyName: string;
+  /** Topic GUID. */
+  topicId: string;
+  /** GUID of the user this notification belongs to (returned uppercase by the API). */
+  userId: string;
+  /** Email of the user. Often `null`. */
+  userEmail: string | null;
+  /** Tenant GUID this notification belongs to. Often `null` for org-scoped notifications. */
+  tenantId: string | null;
+  /** Notification priority. */
+  priority: NotificationPriority;
+  /** Notification severity category. */
+  category: NotificationCategory;
+  /** JSON string of template parameters — parse with `JSON.parse()`. May be `null`. */
+  messageParam: string | null;
+  /** URL to navigate to when the notification is clicked. */
+  redirectionUrl: string | null;
+  /** Unix epoch **seconds** when the notification was published. */
+  publishedOn: number;
+}
+
+/**
+ * Options for `Notifications.getAll()`.
+ *
+ * Supports OData query options (`filter`, `orderby`) and SDK cursor pagination.
+ *
+ * Notes:
+ * - `$select` and `$expand` are not exposed because the API returns 500 on `$select`
+ *   and there are no expandable relationships on this endpoint.
+ */
+export type NotificationGetAllOptions = Omit<RequestOptions, 'expand' | 'select'> & PaginationOptions;

src/services/notification/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Notification Service Module
+ *
+ * Provides access to the UiPath Notification platform from the perspective of an
+ * authenticated user (UserContext):
+ * - `Notifications` — list operations on the user's inbox (further operations land in
+ *   follow-up PRs)
+ *
+ * Publishing (sending) notifications is a first-party service action and is NOT part of this module.
+ *
+ * @example
+ * ```typescript
+ * import { UiPath } from '@uipath/uipath-typescript/core';
+ * import { Notifications } from '@uipath/uipath-typescript/notifications';
+ *
+ * const sdk = new UiPath(config);
+ * await sdk.initialize();
+ *
+ * const notifications = new Notifications(sdk);
+ * const unread = await notifications.getAll('<tenantId>', { filter: 'isRead eq false' });
+ * ```
+ *
+ * @module
+ */
+
+export { NotificationService as Notifications } from './notifications';
+
+// Models (types, enums, response shapes)
+export * from '../../models/notification';

src/services/notification/notifications.ts

@@ -0,0 +1,125 @@
+/**
+ * NotificationService — manages the current user's notification inbox.
+ */
+
+import { track } from '../../core/telemetry';
+import { BaseService } from '../base';
+
+import type {
+  NotificationGetAllOptions,
+  NotificationGetResponse,
+} from '../../models/notification/notifications.types';
+import type {
+  NotificationServiceModel,
+} from '../../models/notification/notifications.models';
+import {
+  INTERNAL_NOTIFICATION_FIELDS,
+  type RawNotificationEntry,
+} from '../../models/notification/notifications.internal-types';
+
+import { ODATA_OFFSET_PARAMS, ODATA_PAGINATION } from '../../utils/constants/common';
+import { NOTIFICATION_ENDPOINTS } from '../../utils/constants/endpoints';
+import { TENANT_ID } from '../../utils/constants/headers';
+import { createHeaders } from '../../utils/http/headers';
+import {
+  HasPaginationOptions,
+  NonPaginatedResponse,
+  PaginatedResponse,
+} from '../../utils/pagination/types';
+import { PaginationHelpers } from '../../utils/pagination/helpers';
+import { PaginationType } from '../../utils/pagination/internal-types';
+
+/**
+ * Service for interacting with the UiPath Notification inbox.
+ *
+ * Provides list operations against the current user's notifications (the
+ * `/odata/v1/NotificationEntry` API). Further inbox operations (mark-read,
+ * delete) land in follow-up PRs.
+ *
+ * Every public method takes the acting tenant GUID as the first argument — the
+ * notification API identifies the tenant via the `X-UIPATH-Internal-TenantId`
+ * header and the SDK forwards `tenantId` into that header on each call.
+ */
+export class NotificationService extends BaseService implements NotificationServiceModel {
+  /**
+   * Lists notifications from the current user's inbox.
+   *
+   * Returns the full list when no pagination params are provided, or a paginated cursor result
+   * when any of `pageSize`/`cursor`/`jumpToPage` is supplied. Supports OData `filter` and
+   * `orderby` query options.
+   *
+   * @param tenantId - Tenant GUID (sent via `X-UIPATH-Internal-TenantId`)
+   * @param options - Optional OData query and pagination options
+   * @returns Array of notifications, or a paginated result when pagination params are supplied
+   * {@link NotificationGetResponse}
+   *
+   * @example Basic usage
+   * ```typescript
+   * import { Notifications } from '@uipath/uipath-typescript/notifications';
+   *
+   * const notifications = new Notifications(sdk);
+   * const all = await notifications.getAll('<tenantId>');
+   * ```
+   *
+   * @example Filter unread, most recent first
+   * ```typescript
+   * const unread = await notifications.getAll('<tenantId>', {
+   *   filter: 'isRead eq false',
+   *   orderby: 'publishedOn desc',
+   * });
+   * ```
+   *
+   * @example First page with pagination
+   * ```typescript
+   * const page1 = await notifications.getAll('<tenantId>', { pageSize: 20 });
+   * if (page1.hasNextPage) {
+   *   const page2 = await notifications.getAll('<tenantId>', { cursor: page1.nextCursor });
+   * }
+   * ```
+   * @internal
+   */
+  @track('Notifications.GetAll')
+  async getAll<T extends NotificationGetAllOptions = NotificationGetAllOptions>(
+    tenantId: string,
+    options?: T
+  ): Promise<
+    T extends HasPaginationOptions<T>
+      ? PaginatedResponse<NotificationGetResponse>
+      : NonPaginatedResponse<NotificationGetResponse>
+  > {
+    return PaginationHelpers.getAll({
+      serviceAccess: this.createPaginationServiceAccess(),
+      getEndpoint: () => NOTIFICATION_ENDPOINTS.GET_ALL,
+      headers: createHeaders({ [TENANT_ID]: tenantId }),
+      transformFn: stripInternalNotificationFields,
+      pagination: {
+        paginationType: PaginationType.OFFSET,
+        itemsField: ODATA_PAGINATION.ITEMS_FIELD,
+        totalCountField: ODATA_PAGINATION.TOTAL_COUNT_FIELD,
+        paginationParams: {
+          pageSizeParam: ODATA_OFFSET_PARAMS.PAGE_SIZE_PARAM,
+          offsetParam: ODATA_OFFSET_PARAMS.OFFSET_PARAM,
+          countParam: ODATA_OFFSET_PARAMS.COUNT_PARAM,
+        },
+      },
+    }, options) as Promise<
+      T extends HasPaginationOptions<T>
+        ? PaginatedResponse<NotificationGetResponse>
+        : NonPaginatedResponse<NotificationGetResponse>
+    >;
+  }
+}
+
+/**
+ * Drops internal/transport-layer fields from a raw notification entry before
+ * returning it to the SDK consumer. Exported as module-level for testability.
+ *
+ * @internal
+ */
+export function stripInternalNotificationFields(item: RawNotificationEntry): NotificationGetResponse {
+  const result: RawNotificationEntry = { ...item };
+  for (const field of INTERNAL_NOTIFICATION_FIELDS) {
+    delete result[field];
+  }
+  return result;
+}