@dalmore/api-contracts 0.0.0-dev.582cb9c → 0.0.0-dev.5e42638

package/common/types/notification.types.ts

@@ -1,58 +1,554 @@
 import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { z } from 'zod';
 import { TypeID } from 'typeid-js';
-import { accountIdSchema } from './account.types';
+import { IBaseEntity } from './entity.types';
+import { IPaginationMeta, StringToBooleanSchema } from './common.types';
+import {
+  ActivityTypeAction,
+  ActivityTypeCategory,
+  ActivityTypeResource,
+} from './activity.types';
 
 extendZodWithOpenApi(z);
-export enum NotificationChannel {
+
+export enum NotificationChannelType {
   EMAIL = 'EMAIL',
   SLACK = 'SLACK',
+  WEBHOOK = 'WEBHOOK',
 }
-export enum NotificationType {
-  COMPLIANCE_TRADE_ALERT = 'COMPLIANCE_TRADE_ALERT',
-  TRADE_ALERT = 'TRADE_ALERT',
+
+export enum NotificationRecordStatus {
+  PENDING = 'PENDING',
+  SENT = 'SENT',
+  FAILED = 'FAILED',
 }
 
-export const notificationIdSchema = z.string().refine(
+export type TriggerExclusion = {
+  category?: ActivityTypeCategory;
+  resource?: ActivityTypeResource;
+  action?: ActivityTypeAction;
+};
+
+// Excluded notifications
+export const EXCLUDED_NOTIFICATION_TRIGGERS: TriggerExclusion[] = [
+  // { action: ActivityTypeAction.RE_SIGN },
+  // { action: ActivityTypeAction.RESET_2FA },
+  // { action: ActivityTypeAction.LOGIN },
+  // { action: ActivityTypeAction.RESET_PASSWORD },
+  // { action: ActivityTypeAction.TWO_FACTOR_LOGIN },
+  // { action: ActivityTypeAction.FORGOT_PASSWORD },
+  // { resource: ActivityTypeResource.USERS },
+  // { resource: ActivityTypeResource.THEME_SETTINGS },
+];
+
+export const ISSUER_ALLOWED_CATEGORIES: ActivityTypeCategory[] = [
+  ActivityTypeCategory.ISSUER,
+];
+
+/**
+ * Checks if an activity type should be excluded from notifications.
+ *
+ * Each exclusion pattern can specify any combination of category, resource, and action.
+ * Omitted fields act as wildcards (match any value).
+ *
+ * @example
+ * // Excludes ALL activities with action RE_SIGN (any category, any resource)
+ * { action: ActivityTypeAction.RE_SIGN }
+ *
+ * @example
+ * // Excludes ALL USERS activities (any category, any action)
+ * { resource: ActivityTypeResource.USERS }
+ *
+ * @example
+ * // Excludes only COMPLIANCE + TRADES + CREATE (all three must match)
+ * { category: ActivityTypeCategory.COMPLIANCE, resource: ActivityTypeResource.TRADES, action: ActivityTypeAction.CREATE }
+ *
+ * @param category - The activity type category to check
+ * @param resource - The activity type resource to check
+ * @param action - The activity type action to check
+ * @param exclusions - Array of exclusion patterns (defaults to EXCLUDED_NOTIFICATION_TRIGGERS)
+ * @returns true if the activity type matches any exclusion pattern
+ */
+export function isTriggerExcluded(
+  category: string,
+  resource: string,
+  action: string,
+  exclusions: TriggerExclusion[] = EXCLUDED_NOTIFICATION_TRIGGERS,
+): boolean {
+  return exclusions.some((exclusion) => {
+    const categoryMatch =
+      !exclusion.category || exclusion.category === category;
+    const resourceMatch =
+      !exclusion.resource || exclusion.resource === resource;
+    const actionMatch = !exclusion.action || exclusion.action === action;
+    return categoryMatch && resourceMatch && actionMatch;
+  });
+}
+
+/**
+ * Checks if a category is allowed for notification triggers.
+ *
+ * Used to restrict which activity type categories a user can subscribe to.
+ * For example, issuers can only subscribe to ISSUER category triggers.
+ *
+ * @param category - The activity type category to check
+ * @param allowedCategories - Optional array of allowed categories. If empty or undefined, all categories are allowed.
+ * @returns true if the category is allowed (or if no restrictions are set)
+ */
+export function isCategoryAllowed(
+  category: string,
+  allowedCategories?: ActivityTypeCategory[],
+): boolean {
+  if (!allowedCategories || allowedCategories.length === 0) {
+    return true;
+  }
+  return allowedCategories.includes(category as ActivityTypeCategory);
+}
+
+export const notificationChannelIdSchema = z.string().refine(
   (value) => {
     try {
       const tid = TypeID.fromString(value);
-      return tid.getType() === 'notification';
+      return tid.getType() === 'notification_channel';
     } catch {
       return false;
     }
   },
   {
     message:
-      'Invalid notification ID format. Must be a valid TypeID with "notification" prefix.',
+      'Invalid notification channel ID format. Must be a valid TypeID with "notification_channel" prefix.',
   },
 );
 
-export const SendNotificationZod = z.object({
-  message: z.string(),
+export const notificationChannelTriggerIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'notification_channel_trigger';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid notification channel trigger ID format. Must be a valid TypeID with "notification_channel_trigger" prefix.',
+  },
+);
+
+export const notificationRecordIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'notification_record';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid notification record ID format. Must be a valid TypeID with "notification_record" prefix.',
+  },
+);
+
+export const EmailChannelSettingsSchema = z.object({
+  recipients: z
+    .array(z.string().email())
+    .min(1)
+    .max(100, 'At most 100 recipients are allowed'),
+  subjectTemplate: z.string().optional(),
+});
+export type EmailChannelSettings = z.infer<typeof EmailChannelSettingsSchema>;
+
+export const SlackChannelSettingsSchema = z
+  .object({
+    webhookUrl: z.string().url().optional(),
+    channelEmail: z.string().email().optional(),
+  })
+  .refine((data) => data.webhookUrl || data.channelEmail, {
+    message: 'Either webhookUrl or channelEmail is required',
+  });
+export type SlackChannelSettings = z.infer<typeof SlackChannelSettingsSchema>;
+
+export const WebhookChannelSettingsSchema = z.object({
+  url: z.string().url(),
+  method: z.enum(['POST', 'PUT']),
+  headers: z.record(z.string()).optional(),
+  authType: z.enum(['none', 'bearer', 'basic', 'api_key']).default('none'),
+  authValue: z.string().optional(),
+});
+export type WebhookChannelSettings = z.infer<
+  typeof WebhookChannelSettingsSchema
+>;
+
+export const NotificationChannelSettingsSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal(NotificationChannelType.EMAIL),
+    config: EmailChannelSettingsSchema,
+  }),
+  z.object({
+    type: z.literal(NotificationChannelType.SLACK),
+    config: SlackChannelSettingsSchema,
+  }),
+  z.object({
+    type: z.literal(NotificationChannelType.WEBHOOK),
+    config: WebhookChannelSettingsSchema,
+  }),
+]);
+export type NotificationChannelSettings = z.infer<
+  typeof NotificationChannelSettingsSchema
+>;
+
+export const EmailNotificationPayloadSchema = z.object({
+  to: z.array(z.string().email()),
   subject: z.string(),
-  buttonText: z.string(),
-  link: z.string(),
-  debug: z.boolean().default(false),
-  notificationChannel: z.nativeEnum(NotificationChannel),
-  channelName: z.string(),
-  channelEmail: z.string().email(),
-  notificationType: z.nativeEnum(NotificationType),
+  body: z.string(),
+  html: z.string().optional(),
+});
+export type EmailNotificationPayload = z.infer<
+  typeof EmailNotificationPayloadSchema
+>;
+
+/**
+ * Payload for Slack notifications sent via Incoming Webhooks.
+ *
+ * @property webhookUrl - Slack Incoming Webhook URL
+ * @property channelEmail - Slack channel email integration (alternative delivery method)
+ * @property message - Plain text message (also serves as fallback for notifications)
+ * @property blocks - Optional Slack Block Kit elements for rich message formatting.
+ *   Blocks allow structured layouts with headers, sections, images, buttons, etc.
+ *   @see https://docs.slack.dev/messaging/creating-interactive-messages
+ */
+export const SlackNotificationPayloadSchema = z.object({
+  webhookUrl: z.string().url().optional(),
+  channelEmail: z.string().email().optional(),
+  message: z.string(),
+  blocks: z.array(z.record(z.unknown())).optional(),
+});
+export type SlackNotificationPayload = z.infer<
+  typeof SlackNotificationPayloadSchema
+>;
+
+export const WebhookNotificationPayloadSchema = z.object({
+  url: z.string().url(),
+  method: z.enum(['POST', 'PUT']),
+  headers: z.record(z.string()),
+  body: z.record(z.unknown()),
 });
-export type SendNotificationZod = z.infer<typeof SendNotificationZod>;
+export type WebhookNotificationPayload = z.infer<
+  typeof WebhookNotificationPayloadSchema
+>;
+
+export const NotificationPayloadSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal(NotificationChannelType.EMAIL),
+    data: EmailNotificationPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(NotificationChannelType.SLACK),
+    data: SlackNotificationPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(NotificationChannelType.WEBHOOK),
+    data: WebhookNotificationPayloadSchema,
+  }),
+]);
+export type NotificationPayload = z.infer<typeof NotificationPayloadSchema>;
 
-const SlackSettingsSchema = z.object({
-  channelName: z.string().min(1).max(50),
-  channelEmail: z.string().email(),
+export const EmailNotificationResponseSchema = z.object({
+  messageId: z.string().optional(),
+  accepted: z.array(z.string()).optional(),
+  rejected: z.array(z.string()).optional(),
 });
+export type EmailNotificationResponse = z.infer<
+  typeof EmailNotificationResponseSchema
+>;
 
-export const PostNotificationZod = z.object({
-  accountId: accountIdSchema,
-  notificationChannel: z.literal(NotificationChannel.SLACK), // Only Slack for now
-  notificationType: z.nativeEnum(NotificationType),
-  enabled: z.boolean().default(true),
-  debug: z.boolean().default(false),
-  settings: SlackSettingsSchema,
+export const SlackNotificationResponseSchema = z.object({
+  ok: z.boolean().optional(),
+  error: z.string().optional(),
+  responseBody: z.string().optional(),
 });
+export type SlackNotificationResponse = z.infer<
+  typeof SlackNotificationResponseSchema
+>;
 
-export type PostNotificationZod = z.infer<typeof PostNotificationZod>;
+export const WebhookNotificationResponseSchema = z.object({
+  statusCode: z.number(),
+  headers: z.record(z.string()).optional(),
+  body: z.unknown().optional(),
+});
+export type WebhookNotificationResponse = z.infer<
+  typeof WebhookNotificationResponseSchema
+>;
+
+export const NotificationResponseSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal(NotificationChannelType.EMAIL),
+    data: EmailNotificationResponseSchema,
+  }),
+  z.object({
+    type: z.literal(NotificationChannelType.SLACK),
+    data: SlackNotificationResponseSchema,
+  }),
+  z.object({
+    type: z.literal(NotificationChannelType.WEBHOOK),
+    data: WebhookNotificationResponseSchema,
+  }),
+]);
+export type NotificationResponse = z.infer<typeof NotificationResponseSchema>;
+
+export const INotificationChannelZod = IBaseEntity.extend({
+  id: notificationChannelIdSchema.openapi({
+    example: 'notification_channel_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  accountSettingsId: z.string().openapi({
+    example: 'account_setting_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  channelType: z.nativeEnum(NotificationChannelType).openapi({
+    example: NotificationChannelType.SLACK,
+  }),
+  name: z.string().openapi({
+    example: 'Compliance Alerts',
+  }),
+  enabled: z.boolean().openapi({
+    example: true,
+  }),
+  settings: NotificationChannelSettingsSchema.openapi({
+    example: {
+      type: NotificationChannelType.SLACK,
+      config: {
+        webhookUrl: 'https://hooks.slack.com/test',
+      },
+    },
+  }),
+});
+export type INotificationChannelZod = z.infer<typeof INotificationChannelZod>;
+
+export const INotificationChannelTriggerZod = IBaseEntity.extend({
+  id: notificationChannelTriggerIdSchema.openapi({
+    example: 'notification_channel_trigger_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  notificationChannelId: notificationChannelIdSchema.openapi({
+    example: 'notification_channel_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  activityTypeId: z.string().openapi({
+    example: 'activity_type_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  enabled: z.boolean().openapi({
+    example: true,
+  }),
+});
+export type INotificationChannelTriggerZod = z.infer<
+  typeof INotificationChannelTriggerZod
+>;
+
+export const IAvailableTriggerZod = z.object({
+  activityTypeId: z.string().openapi({
+    example: 'activity_type_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  category: z.string().openapi({
+    example: 'COMPLIANCE',
+  }),
+  resource: z.string().openapi({
+    example: 'TRADES',
+  }),
+  action: z.string().openapi({
+    example: 'CREATE',
+  }),
+  enabled: z.boolean().openapi({
+    description: 'Whether the trigger is enabled for this activity type',
+    example: false,
+  }),
+  trigger: INotificationChannelTriggerZod.nullable().openapi({
+    description: 'The configured trigger, or null if not configured',
+  }),
+});
+export type IAvailableTriggerZod = z.infer<typeof IAvailableTriggerZod>;
+
+export const IAvailableTriggersResponse = z.object({
+  items: z.array(IAvailableTriggerZod),
+});
+export type IAvailableTriggersResponse = z.infer<
+  typeof IAvailableTriggersResponse
+>;
+
+export const INotificationRecordZod = IBaseEntity.extend({
+  id: notificationRecordIdSchema.openapi({
+    example: 'notification_record_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  notificationChannelId: notificationChannelIdSchema.openapi({
+    example: 'notification_channel_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  activityId: z.string().nullable().openapi({
+    example: 'activity_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  targetTable: z.string().openapi({
+    example: 'trades',
+  }),
+  targetId: z.string().openapi({
+    example: 'trade_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  status: z.nativeEnum(NotificationRecordStatus).openapi({
+    example: NotificationRecordStatus.SENT,
+  }),
+  payload: NotificationPayloadSchema,
+  response: NotificationResponseSchema.nullable(),
+  errorMessage: z.string().nullable().openapi({
+    example: null,
+  }),
+  retryCount: z.number().openapi({
+    example: 0,
+  }),
+  sentAt: z.date().nullable().openapi({
+    example: new Date(),
+  }),
+});
+export type INotificationRecordZod = z.infer<typeof INotificationRecordZod>;
+
+export const CreateChannelInputSchema = z
+  .object({
+    accountSettingsId: z.string(),
+    channelType: z.nativeEnum(NotificationChannelType),
+    name: z
+      .string()
+      .min(1, 'Name is required')
+      .max(255, 'Name must be less than 255 characters'),
+    enabled: z.boolean().optional(),
+    settings: NotificationChannelSettingsSchema,
+  })
+  .refine((data) => data.channelType === data.settings.type, {
+    message: 'Channel type must match settings type',
+    path: ['settings', 'type'],
+  });
+export type CreateChannelInput = z.infer<typeof CreateChannelInputSchema>;
+
+export const IssuerCreateChannelInputSchema = z
+  .object({
+    channelType: z.nativeEnum(NotificationChannelType),
+    name: z
+      .string()
+      .min(1, 'Name is required')
+      .max(255, 'Name must be less than 255 characters'),
+    enabled: z.boolean().optional(),
+    settings: NotificationChannelSettingsSchema,
+  })
+  .refine((data) => data.channelType === data.settings.type, {
+    message: 'Channel type must match settings type',
+    path: ['settings', 'type'],
+  });
+export type IssuerCreateChannelInput = z.infer<
+  typeof IssuerCreateChannelInputSchema
+>;
+
+export const UpdateChannelInputSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  settings: NotificationChannelSettingsSchema.optional(),
+});
+export type UpdateChannelInput = z.infer<typeof UpdateChannelInputSchema>;
+
+export const CreateTriggerInputSchema = z.object({
+  notificationChannelId: notificationChannelIdSchema,
+  activityTypeId: z.string(),
+  enabled: z.boolean().optional(),
+});
+export type CreateTriggerInput = z.infer<typeof CreateTriggerInputSchema>;
+
+export const IPaginatedNotificationChannel = z.object({
+  items: z.array(INotificationChannelZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedNotificationChannel = z.infer<
+  typeof IPaginatedNotificationChannel
+>;
+
+export const IPaginatedNotificationChannelTrigger = z.object({
+  items: z.array(INotificationChannelTriggerZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedNotificationChannelTrigger = z.infer<
+  typeof IPaginatedNotificationChannelTrigger
+>;
+
+export const IPaginatedNotificationRecord = z.object({
+  items: z.array(INotificationRecordZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedNotificationRecord = z.infer<
+  typeof IPaginatedNotificationRecord
+>;
+
+export const NotificationChannelFilters = z.object({
+  accountSettingsId: z.string().optional(),
+  channelType: z.nativeEnum(NotificationChannelType).optional(),
+  enabled: StringToBooleanSchema.optional(),
+});
+export type NotificationChannelFilters = z.infer<
+  typeof NotificationChannelFilters
+>;
+
+export const NotificationChannelTriggerFilters = z.object({
+  notificationChannelId: notificationChannelIdSchema.optional(),
+  activityTypeId: z.string().optional(),
+  enabled: StringToBooleanSchema.optional(),
+});
+export type NotificationChannelTriggerFilters = z.infer<
+  typeof NotificationChannelTriggerFilters
+>;
+
+export const NotificationRecordFilters = z.object({
+  notificationChannelId: notificationChannelIdSchema.optional(),
+  status: z.nativeEnum(NotificationRecordStatus).optional(),
+});
+export type NotificationRecordFilters = z.infer<
+  typeof NotificationRecordFilters
+>;
+
+export const notificationChannelsInclude = z.enum([
+  'triggers',
+  'accountSettings',
+  'notificationRecords',
+]);
+
+export const NotificationChannelsIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          notificationChannelsInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include value. Valid values are: ${notificationChannelsInclude.options.join(', ')}`,
+      },
+    ),
+});
+export type NotificationChannelsIncludeQuery = z.infer<
+  typeof NotificationChannelsIncludeQuery
+>;
+
+export const notificationRecordsInclude = z.enum([
+  'notificationChannel',
+  'activity',
+]);
+
+export const NotificationRecordsIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          notificationRecordsInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include value. Valid values are: ${notificationRecordsInclude.options.join(', ')}`,
+      },
+    ),
+});
+export type NotificationRecordsIncludeQuery = z.infer<
+  typeof NotificationRecordsIncludeQuery
+>;

package/common/types/offering.types.ts

@@ -17,6 +17,7 @@ import {
   OfferingOnboardingStatus,
   AssetType,
   DurationType,
+  StringToBooleanSchema,
 } from './common.types';
 import { IBaseEntity } from './entity.types';
 import { fileIdSchema, FileZod } from './file.types';
@@ -346,15 +347,7 @@ export const OfferingFiltersZod = z.object({
   issuerId: z.lazy(() => issuerIdSchema).optional(),
   type: z.nativeEnum(OfferingType).optional(),
   status: z.nativeEnum(ComplianceReview).optional(),
-  enabled: z.preprocess(
-    (val) =>
-      val === 'true' || val === '1'
-        ? true
-        : val === 'false' || val === '0'
-          ? false
-          : val,
-    z.boolean().optional(),
-  ),
+  enabled: StringToBooleanSchema.optional(),
   managedBy: z.nativeEnum(ManagedByType).optional(),
   versioningType: z.nativeEnum(OfferingVersioningType).optional(),
   combinedStatus: z.nativeEnum(OfferingStatus).optional(),

package/common/types/site-settings.types.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { fileIdSchema } from './file.types';
 import {
   AccountZod,
+  EmailSchema,
   HexCodeColorSchema,
   IPaginationMeta,
   SubdomainSchema,
@@ -462,7 +463,7 @@ export const GetSenderEmailZod = z.object({
 export type GetSenderEmailZod = z.infer<typeof GetSenderEmailZod>;
 
 export const PatchSenderEmailZod = z.object({
-  senderEmail: z.string().email().openapi({ example: 'example@example.com' }),
+  senderEmail: EmailSchema,
 });
 export type PatchSenderEmailZod = z.infer<typeof PatchSenderEmailZod>;
 

package/common/types/site.types.ts

@@ -5,6 +5,7 @@ import {
   AccountStatus,
   AccountZod,
   IPaginationMeta,
+  StringToBooleanSchema,
   UrlSchema,
 } from './common.types';
 import { accountIdSchema } from './account.types';
@@ -73,15 +74,7 @@ export const SitesParamSchema = z.object({
 export const SitesFiltersZod = z.object({
   url: z.string().optional(),
   accountId: accountIdSchema.optional(),
-  enabled: z.preprocess(
-    (val) =>
-      val === 'true' || val === '1'
-        ? true
-        : val === 'false' || val === '0'
-          ? false
-          : val,
-    z.boolean().optional(),
-  ),
+  enabled: StringToBooleanSchema.optional(),
 });
 
 const sitesInclude = z.enum(['account']);

package/common/types/{trade-line-item.type.ts → trade-line-item.types.ts}

@@ -8,6 +8,7 @@ import {
   IPaginationMeta,
   OfferingType,
   SignatureStatus,
+  StringToBooleanSchema,
 } from './common.types';
 import { fileIdSchema } from './file.types';
 import { accountIdSchema } from './account.types';
@@ -107,15 +108,7 @@ export type TradeLineItemQuery = z.infer<typeof TradeLineItemQuery>;
 
 export const TradeLineItemFiltersQuery = z.object({
   accountId: accountIdSchema.optional(),
-  hasSubdoc: z.preprocess(
-    (val) =>
-      val === 'true' || val === '1'
-        ? true
-        : val === 'false' || val === '0'
-          ? false
-          : val,
-    z.boolean().optional(),
-  ),
+  hasSubdoc: StringToBooleanSchema.optional(),
   saStatus: z.nativeEnum(SignatureStatus).optional(),
   offeringId: z.lazy(() => offeringIdSchema).optional(),
   search: z.string().max(50).optional(),