@dalmore/api-contracts 0.0.0-dev.988f3c3 → 0.0.0-dev.9d42e16

package/README.md

@@ -14,32 +14,33 @@ npm install @dalmore/api-contracts@dev
 
 ## Usage
 
-### Import specific contracts (recommended for tree-shaking)
+### Import from main entry
 
 ```typescript
-import { complianceContract } from '@dalmore/api-contracts/compliance';
-import { investorsContract } from '@dalmore/api-contracts/investors';
-import { issuersContract } from '@dalmore/api-contracts/issuers';
-import { clientsContract } from '@dalmore/api-contracts/clients';
+import { clientsContract } from '@dalmore/api-contracts';
+import type { IInvestorAccount } from '@dalmore/api-contracts';
 ```
 
-### Import types
+### Import specific subpaths (recommended for tree-shaking)
 
 ```typescript
-import type { IInvestorAccount } from '@dalmore/api-contracts/types/investor-account.types';
-import type { ITrade } from '@dalmore/api-contracts/types/trade.types';
+// Import clients contract
+import { clientsContract } from '@dalmore/api-contracts/clients';
+
+// Import types
+import type { IInvestorAccount, ITrade } from '@dalmore/api-contracts/types';
 ```
 
 ### Create a typed client
 
 ```typescript
-import { complianceContract } from '@dalmore/api-contracts/compliance';
+import { clientsContract } from '@dalmore/api-contracts/clients';
 import { initClient } from '@ts-rest/core';
 
-const client = initClient(complianceContract, {
+const client = initClient(clientsContract, {
   baseUrl: 'https://platform.dalmoregroup.com',
   baseHeaders: {
-    Authorization: `Bearer ${token}`,
+    'X-API-Key': `${apiKey}`,
   },
 });
 
@@ -53,17 +54,20 @@ const { status, body } = await client.accounts.getAccounts({
 
 This package requires the following peer dependencies:
 
-- `@ts-rest/core` ^3.0.0
-- `zod` ^3.0.0
+- `@anatine/zod-openapi` ^1.14.2
+- `@ts-rest/core` ^3.52.1
+- `typeid-js` ^1.2.0
+- `zod` ^3.24.4
 
-## Available Contracts
+## Available Exports
 
-- `complianceContract` - Compliance portal API
-- `investorsContract` - Investor portal API
-- `issuersContract` - Issuer portal API
 - `clientsContract` - Client API (API key auth)
-- `secondariesContract` - Secondaries API
-- `complianceApiKeyContract` - Compliance API (API key auth)
+
+## Available Subpath Exports
+
+- `@dalmore/api-contracts` - Main entry (clients contract and types)
+- `@dalmore/api-contracts/clients` - Clients contract
+- `@dalmore/api-contracts/types` - All common types
 
 ## TypeScript Configuration
 

package/common/types/account-contact.types.ts

@@ -6,6 +6,7 @@ import { PhoneZodSchema } from './phone.type';
 import {
   AccountContactType,
   AccountZod,
+  EmailSchema,
   IPaginationMeta,
 } from './common.types';
 import { IBaseEntity } from './entity.types';
@@ -60,7 +61,7 @@ export const PatchAccountContactZod = z.object({
     .openapi({ example: 'Mr' }),
   firstName: z.string().min(1).max(150).openapi({ example: 'John' }),
   lastName: z.string().min(1).max(150).openapi({ example: 'Doe' }),
-  email: z.string().email().openapi({ example: 'john.doe@example.com' }),
+  email: EmailSchema.openapi({ example: 'john.doe@example.com' }),
   phone: PhoneZodSchema.nullable()
     .optional()
     .openapi({ example: '+12124567890' }),

package/common/types/account-manager.types.ts

@@ -4,7 +4,7 @@ import { TypeID } from 'typeid-js';
 import { IBaseEntity } from './entity.types';
 import { PhoneNumberData } from './sms.types';
 import { userIdSchema, UserZod } from './user.types';
-import { IPaginationMeta } from './common.types';
+import { EmailSchema, IPaginationMeta } from './common.types';
 import { PhoneZodSchema } from './phone.type';
 
 extendZodWithOpenApi(z);
@@ -68,7 +68,7 @@ export type IAccountManagerZod = z.infer<typeof IAccountManagerZod>;
 export const PostAccountManagerZod = z.object({
   firstName: z.string().min(1).max(255).openapi({ example: 'John' }),
   lastName: z.string().min(1).max(255).openapi({ example: 'Doe' }),
-  email: z.string().email().openapi({ example: 'john.doe@example.com' }),
+  email: EmailSchema,
   phone: PhoneZodSchema.nullable()
     .optional()
     .openapi({ example: '+12124567890' }),
@@ -80,11 +80,7 @@ export type PostAccountManagerZod = z.infer<typeof PostAccountManagerZod>;
 export const PatchAccountManagerZod = z.object({
   firstName: z.string().min(1).max(255).optional().openapi({ example: 'John' }),
   lastName: z.string().min(1).max(255).optional().openapi({ example: 'Doe' }),
-  email: z
-    .string()
-    .email()
-    .optional()
-    .openapi({ example: 'john.doe@example.com' }),
+  email: EmailSchema.optional(),
   phone: PhoneZodSchema.nullable()
     .optional()
     .openapi({ example: '+12124567890' }),

package/common/types/account.types.ts

@@ -101,6 +101,7 @@ const accountsInclude = z.enum([
   'issuers',
   'legalEntities',
   'offerings',
+  'pages',
   'sites',
   'trades',
   'users',

package/common/types/auth.types.ts

@@ -8,6 +8,7 @@ import {
   ManagedByType,
   UserRole,
   createUrlSchema,
+  EmailSchema,
 } from './common.types';
 import { TypeID } from 'typeid-js';
 import { TwoFactorMethod } from './sms.types';
@@ -60,13 +61,7 @@ const BaseAuthBody = z.object({
     .openapi({
       example: 'Armstrong',
     }),
-  email: z
-    .string()
-    .email()
-    .transform((val) => val.toLowerCase())
-    .openapi({
-      example: 'neil@dalmoregroup.com',
-    }),
+  email: EmailSchema,
   password: PasswordSchema,
 });
 
@@ -99,13 +94,7 @@ export const IChangePasswordBodyZod = z
   });
 
 export const LoginBody = z.object({
-  email: z
-    .string()
-    .email()
-    .transform((val) => val.toLowerCase())
-    .openapi({
-      example: 'neil@dalmoregroup.com',
-    }),
+  email: EmailSchema,
   password: z.string().openapi({
     example: 'Secretpassword6#',
   }),
@@ -297,7 +286,7 @@ export const RegisterBodyInvestors = BaseAuthBody.extend({
 });
 
 export const ResetPasswordVerifyBody = z.object({
-  email: z.string().email(),
+  email: EmailSchema,
   code: z.string().length(6, 'code is not 6 characters').openapi({
     example: '123456',
   }),
@@ -315,7 +304,7 @@ export type ResetPasswordVerifyResponseType = z.infer<
 >;
 
 export const ResetPasswordBody = z.object({
-  email: z.string().email(),
+  email: EmailSchema,
   code: z.string().length(6, 'code is not 6 characters').openapi({
     example: '123456',
   }),
@@ -337,7 +326,7 @@ export type ClientAuthSuccessResponse = z.infer<
 >;
 
 export const AdminForgotPasswordRequestZod = z.object({
-  email: z.string().email(),
+  email: EmailSchema,
   portal: z.nativeEnum(PortalType),
 });
 export type AdminForgotPasswordRequestZod = z.infer<
@@ -345,7 +334,7 @@ export type AdminForgotPasswordRequestZod = z.infer<
 >;
 
 export const InvestorForgotPasswordRequestZod = z.object({
-  email: z.string().email(),
+  email: EmailSchema,
   url: createUrlSchema({ strict: true }),
 });
 export type InvestorForgotPasswordRequestZod = z.infer<

package/common/types/common.types.ts

@@ -69,6 +69,10 @@ export enum BaseStatus {
   VOIDED = 'VOIDED',
   JOIN = 'JOIN',
   RESTORE = 'RESTORE',
+  ACTIVE = 'ACTIVE',
+  LOCKED = 'LOCKED',
+  ENABLED = 'ENABLED',
+  DISABLED = 'DISABLED',
 }
 
 export const UserWithoutPasswordAccountZod = IBaseEntity.extend({
@@ -808,6 +812,8 @@ export enum EventField {
   SA_STATUS = 'saStatus',
   ONBOARDING_STATUS = 'onboardingStatus',
   TRANSACTION_STATUS = 'transactionStatus',
+  ACTIVE = 'active',
+  LOCKED = 'locked',
 }
 
 export enum EventName {
@@ -1528,3 +1534,19 @@ export const StringToBooleanSchema = z.preprocess(
   z.boolean(),
 );
 export type StringToBooleanSchema = z.infer<typeof StringToBooleanSchema>;
+
+/**
+ * Reusable email schema that validates email format, transforms to lowercase,
+ * and includes OpenAPI metadata.
+ *
+ * @example
+ * EmailSchema.parse('John.Doe@EXAMPLE.COM'); // returns 'john.doe@example.com'
+ * EmailSchema.optional().parse(undefined); // returns undefined
+ */
+export const EmailSchema = z
+  .string()
+  .email()
+  .transform((val) => val.toLowerCase())
+  .openapi({
+    example: 'neil@dalmoregroup.com',
+  });

package/common/types/comply-advantage-api.types.ts

@@ -30,7 +30,7 @@ export const CreateSearchRequestSchema = z.object({
         .optional(),
     })
     .optional(),
-  tags: z.record(z.string()).optional(),
+  tags: z.union([z.record(z.string()), z.array(z.any())]).optional(),
   share_url: z.union([z.literal(0), z.literal(1)]).optional(),
   exact_match: z.boolean().optional(),
 });
@@ -268,7 +268,7 @@ export const GetSearchDetailsResponseSchema = z.object({
       total_matches: z.number(),
       updated_at: z.string(),
       created_at: z.string(),
-      tags: z.record(z.string()).optional(),
+      tags: z.union([z.record(z.string()), z.array(z.any())]).optional(),
       labels: z
         .array(
           z.object({
@@ -310,7 +310,7 @@ export const UpdateSearchRequestSchema = z.object({
   risk_level: z.enum(['low', 'medium', 'high', 'unknown']).optional(),
   assignee_id: z.number().optional(),
   limit: z.number().int().max(100).optional(),
-  tags: z.record(z.string()).optional(),
+  tags: z.union([z.record(z.string()), z.array(z.any())]).optional(),
 });
 
 export type UpdateSearchRequest = z.infer<typeof UpdateSearchRequestSchema>;

package/common/types/contact-us.types.ts

@@ -1,7 +1,11 @@
 import { z } from 'zod';
 import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { TypeID } from 'typeid-js';
-import { BaseContactUsOptions, createUrlSchema } from './common.types';
+import {
+  BaseContactUsOptions,
+  createUrlSchema,
+  EmailSchema,
+} from './common.types';
 extendZodWithOpenApi(z);
 
 export const contactUsIdSchema = z.string().refine(
@@ -55,7 +59,7 @@ export const InvestorPostContactUsZod = PostContactUsZod.extend({
 export type InvestorPostContactUsZod = z.infer<typeof InvestorPostContactUsZod>;
 
 export const PublicInvestorContactUsZod = PostContactUsZod.extend({
-  email: z.string().email().openapi({ example: 'email@example.com' }),
+  email: EmailSchema,
   firstName: z.string().min(1).max(100).openapi({ example: 'John' }),
   lastName: z.string().min(1).max(100).openapi({ example: 'Doe' }),
   contactOption: z.nativeEnum(InvestorContactOptions).openapi({

package/common/types/covered-person.types.ts

@@ -6,6 +6,7 @@ import {
   ComplianceReview,
   CoveredPersonsRoleType,
   CoveredPersonsStatus,
+  EmailSchema,
   IDType,
   IPaginationMeta,
 } from './common.types';
@@ -137,7 +138,7 @@ export const PatchCoveredPersonsZod = z
       .openapi({ example: CoveredPersonsRoleType.ACCOUNTING }),
 
     ownership: z.number().min(0).max(100).openapi({ example: 15 }).optional(),
-    email: z.string().nullable().optional(),
+    email: EmailSchema.nullable().optional(),
     idType: z
       .nativeEnum(IDType)
       .optional()

package/common/types/escrow-account.types.ts

@@ -1,6 +1,6 @@
 import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { z } from 'zod';
-import { AccountZod, IPaginationMeta } from './common.types';
+import { AccountZod, EmailSchema, IPaginationMeta } from './common.types';
 import { IBaseEntity } from './entity.types';
 import { TypeID } from 'typeid-js';
 import { accountIdSchema } from './account.types';
@@ -43,7 +43,7 @@ export const PostEscrowAccount = z.object({
   accountNumber: z.string().optional().nullable(),
   routingNumber: z.string().min(9).max(9).optional().nullable(),
   agentName: z.string().min(2).max(50),
-  agentEmail: z.string().email(),
+  agentEmail: EmailSchema,
 });
 
 export type PostEscrowAccount = z.infer<typeof PostEscrowAccount>;
@@ -65,7 +65,7 @@ export const PatchEscrowAccount = z.object({
   accountNumber: z.string().min(10).max(18).optional().nullable().optional(),
   routingNumber: z.string().min(9).max(9).optional().nullable().optional(),
   agentName: z.string().min(2).max(50).optional(),
-  agentEmail: z.string().email().optional(),
+  agentEmail: EmailSchema.optional(),
 });
 
 export type PatchEscrowAccount = z.infer<typeof PatchEscrowAccount>;

package/common/types/individuals.types.ts

@@ -16,6 +16,7 @@ import {
   EmploymentStatus,
   SourceOfIncome,
   AMLProvider,
+  EmailSchema,
 } from './common.types';
 import { IBaseEntity } from './entity.types';
 import { IInvestorAccount } from './investor-account.types';
@@ -288,7 +289,7 @@ export const PostIndividualBodySchema = z
       .string()
       .length(3, 'currencyCode must be 3 digits')
       .optional(),
-    email: z.string().email().optional(),
+    email: EmailSchema.optional(),
     role: z.nativeEnum(IndividualRole),
     phone: PhoneZodSchema.openapi({ example: '+12124567890' }).optional(),
     ownership: z.coerce
@@ -387,7 +388,7 @@ export const UpdateIndividualBodySchema = z
       .length(3, 'currencyCode must be 3 digits')
       .optional(),
     phone: PhoneZodSchema.openapi({ example: '+12124567890' }).optional(),
-    email: z.string().email().optional(),
+    email: EmailSchema.optional(),
     ownership: z.coerce
       .number()
       .min(0, 'Ownership is less than 0')

package/common/types/investor-account.types.ts

@@ -24,6 +24,7 @@ import {
   SortBy,
   SortOrder,
   AMLProvider,
+  EmailSchema,
 } from './common.types';
 import { accountIdSchema } from './account.types';
 import { SaStatus, tradeIdSchema, TradeZod } from './trade.types';
@@ -131,7 +132,7 @@ export type PostClientInvestorAccountBody = z.infer<
 
 export const UpdateInvestorAccountBodySchema = z.object({
   name: z.string().optional(),
-  email: z.string().email().optional(),
+  email: EmailSchema.optional(),
 });
 export type UpdateInvestorAccountBody = z.infer<
   typeof UpdateInvestorAccountBodySchema

package/common/types/invite.types.ts

@@ -3,7 +3,9 @@ import {
   AccountZod,
   IPaginationMeta,
   IssuerRole,
+  PortalType,
   UserRole,
+  EmailSchema,
 } from './common.types';
 import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { TypeID } from 'typeid-js';
@@ -48,7 +50,7 @@ export const InviteWithUrl = InviteWithoutSecretZod.extend({
 export type InviteWithUrl = z.infer<typeof InviteWithUrl>;
 
 export const PostIssuerInviteZod = z.object({
-  email: z.string().email(),
+  email: EmailSchema,
   role: z.nativeEnum(IssuerRole),
 });
 
@@ -131,3 +133,27 @@ export const PatchInviteForComplianceZod = PatchInviteRoleZod.extend({
 export type PatchInviteForComplianceZod = z.infer<
   typeof PatchInviteForComplianceZod
 >;
+
+export const PostInviteZod = z.object({
+  email: EmailSchema,
+  role: z.nativeEnum(UserRole).openapi({
+    example: UserRole.ADMIN,
+  }),
+  accountId: z.string().optional().openapi({
+    example: 'account_01j5y5ghx5fg68d663j1fvy2x7',
+  }),
+  portalType: z.nativeEnum(PortalType).optional().openapi({
+    example: PortalType.ISSUER,
+  }),
+});
+
+export type PostInviteZod = z.infer<typeof PostInviteZod>;
+
+export const CompliancePostInviteZod = z.object({
+  email: EmailSchema,
+  role: z.nativeEnum(UserRole).openapi({
+    example: UserRole.ADMIN,
+  }),
+});
+
+export type CompliancePostInviteZod = z.infer<typeof CompliancePostInviteZod>;

package/common/types/legal-entity.types.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { IBaseEntity } from './entity.types';
 import {
   dateSchema,
+  EmailSchema,
   IPaginationMeta,
   KYBStatus,
   SanctionsStatus,
@@ -138,7 +139,7 @@ export const PostLegalEntitySchema = z
     investorAccountId: investorAccountIdSchema,
     name: CompanyNameSchema,
     ein: EINSchema,
-    email: z.string().email().optional(),
+    email: EmailSchema.optional(),
     companyType: CompanyTypeSchema.optional(),
     phone: PhoneZodSchema.openapi({ example: '+12124567890' }).optional(),
     dateOfIncorporation: z.lazy(() => dateSchema).optional(),
@@ -153,7 +154,7 @@ export const UpdateLegalEntitySchema = z
     id: legalEntityIdSchema.optional(),
     name: CompanyNameSchema.optional(),
     ein: EINSchema,
-    email: z.string().email().optional(),
+    email: EmailSchema.optional(),
     companyType: CompanyTypeSchema.optional(),
     phone: PhoneZodSchema.openapi({ example: '+12124567890' }).optional(),
     dateOfIncorporation: z.lazy(() => dateSchema).optional(),

package/common/types/mail-template.types.ts

@@ -434,3 +434,37 @@ export type EmailThemeSetting = z.infer<typeof EmailThemeSettingZod>;
 
 export const EmailThemeSettingsZod = z.array(EmailThemeSettingZod);
 export type EmailThemeSettingsZod = z.infer<typeof EmailThemeSettingsZod>;
+
+/**
+ * Response from a successful email send operation.
+ * Based on SendGrid SDK's ClientResponse structure.
+ */
+export const EmailSendResponseSchema = z.object({
+  /** HTTP status code from SendGrid (e.g., 202 for accepted) */
+  statusCode: z.number(),
+  /** SendGrid's x-message-id header for tracking emails in their dashboard */
+  messageId: z.string().optional(),
+  /** Full response headers, available for debugging if needed */
+  headers: z.record(z.string(), z.unknown()).optional(),
+});
+export type EmailSendResponse = z.infer<typeof EmailSendResponseSchema>;
+
+/**
+ * Error from a failed email send operation.
+ * Fields are optional because error shapes vary depending on failure type
+ * (network errors vs SendGrid API errors).
+ */
+export const EmailSendErrorSchema = z.object({
+  /** Human-readable error message */
+  message: z.string(),
+  /** Network-level error code (e.g., 'ECONNREFUSED', 'ETIMEDOUT') */
+  code: z.string().optional(),
+  /** HTTP status code if request reached SendGrid (e.g., 400, 401, 403, 413, 500) */
+  statusCode: z.number().optional(),
+  /**
+   * SendGrid's error response body. Structure: { errors: [{ message, field, help, id }] }
+   * @see https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send#responses
+   */
+  response: z.unknown().optional(),
+});
+export type EmailSendError = z.infer<typeof EmailSendErrorSchema>;

package/common/types/note.types.ts

@@ -79,7 +79,7 @@ export const PostNoteBody = z.object({
 export type PostNoteBody = z.infer<typeof PostNoteBody>;
 
 export const CompliancePostNoteBody = PostNoteBody.extend({
-  accountId: accountIdSchema,
+  accountId: accountIdSchema.nullable().default(null),
 });
 
 export type CompliancePostNoteBody = z.infer<typeof CompliancePostNoteBody>;

package/common/types/notification.types.ts

@@ -208,6 +208,16 @@ 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(),

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/trade.types.ts

@@ -21,13 +21,15 @@ import {
   createDateSchema,
   AccountStatus,
   SavedQuery,
+  AccountZod,
 } from './common.types';
-import { offeringIdSchema } from './offering.types';
+import { IOffering, offeringIdSchema } from './offering.types';
 import { IBaseEntity } from './entity.types';
 import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { TypeID } from 'typeid-js';
 import {
   paymentMethodIdSchema,
+  PaymentMethodResponse,
   PaymentMethodType,
 } from './payment-methods.types';
 import {
@@ -35,6 +37,7 @@ import {
   InvestorAccountExportFilters,
   ComplianceInvestorAccountExportFilters,
   RegisteredInvestorUserRawZod,
+  IInvestorAccount,
 } from './investor-account.types';
 import {
   tradeLineItemIdSchema,
@@ -132,6 +135,7 @@ export const CheckResultsSchema = z.object({
 export type CheckResults = z.infer<typeof CheckResultsSchema>;
 
 export const TradeIdPrefix = 'trade';
+export const TradeSnapshotIdPrefix = 'trade_snapshot';
 
 export const tradeIdSchema = z.string().refine(
   (value) => {
@@ -170,6 +174,21 @@ export const tradeIdOrTidSchema = z.union([
     .openapi({ example: 'tid_00041061050r3gg28a1c60t3gf' }),
 ]);
 
+export const tradeSnapshotIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === TradeSnapshotIdPrefix;
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid trade snapshot ID format. Must be a valid TypeID with "trade_snapshot" prefix. ex: trade_snapshot_00041061050r3gg28a1c60t3gf',
+  },
+);
+
 export enum SaStatus {
   PENDING = BaseStatus.PENDING,
   SIGNED = BaseStatus.SIGNED,
@@ -274,9 +293,22 @@ export type TradeBalanceResultZod = z.infer<typeof TradeBalanceResultZod>;
 
 export const TradeZod = IBaseEntity.extend({
   investorAccountId: z.lazy(() => investorAccountIdSchema.nullable()),
+  investorAccount: z
+    .lazy(() => IInvestorAccount)
+    .optional()
+    .nullable(),
+  offering: z
+    .lazy(() => IOffering)
+    .optional()
+    .nullable(),
   accountId: accountIdSchema.nullable(),
+  account: z.lazy(() => AccountZod).nullable(),
   offeringId: z.lazy(() => offeringIdSchema.nullable()),
   paymentMethodId: z.lazy(() => paymentMethodIdSchema).nullable(),
+  paymentMethod: z
+    .lazy(() => PaymentMethodResponse)
+    .optional()
+    .nullable(),
   userId: z.lazy(() => userIdSchema.nullable()),
   tradeNumber: z.string(),
   ip: z.string().nullable(),
@@ -342,6 +374,21 @@ export const TradeZod = IBaseEntity.extend({
 });
 export type TradeZod = z.infer<typeof TradeZod>;
 
+export enum SnapshotEvent {
+  COMPLIANCE_APPROVED = 'COMPLIANCE_APPROVED',
+  COMPLIANCE_REJECTED = 'COMPLIANCE_REJECTED',
+  CANCELLED = 'CANCELLED',
+  PLACED = 'PLACED',
+  SETTLED = 'SETTLED',
+}
+
+export const GetTradeSnapshotEventsResponse = z.object({
+  events: z.array(z.nativeEnum(SnapshotEvent)),
+});
+export type GetTradeSnapshotEventsResponse = z.infer<
+  typeof GetTradeSnapshotEventsResponse
+>;
+
 export const IPaginatedTrade = z.object({
   items: z.array(TradeZod),
   meta: IPaginationMeta,
@@ -424,6 +471,7 @@ export const TradeFiltersZod = z.object({
     .openapi({
       example: 'issuer_01jfw4q6qef30s6fpqtsxw94ya',
     }),
+  snapshotEvent: z.nativeEnum(SnapshotEvent).optional(),
   offeringType: z.nativeEnum(OfferingType).optional(),
   managedBy: z.nativeEnum(ManagedByType).optional(),
   platform: z.nativeEnum(Platforms).optional(),