@dalmore/api-contracts 0.0.0-dev.d07da18 → 0.0.0-dev.d29fb02

package/common/types/file.types.ts

@@ -314,8 +314,23 @@ export const reviewFiles = z.object({
 });
 export type reviewFiles = z.infer<typeof reviewFiles>;
 
+/**
+ * Zod preprocessor that trims strings and converts empty/whitespace-only strings to null
+ */
+const trimAndNullifyString = z.preprocess((val) => {
+  if (typeof val === 'string') {
+    const trimmed = val.trim();
+    return trimmed === '' ? null : trimmed;
+  }
+  return val;
+}, z.unknown());
+
 export const PatchFileMetadata = z.object({
-  corrected: z.record(z.string(), z.unknown()),
+  corrected: z.record(z.string(), trimAndNullifyString),
+  expectedCorrected: z
+    .record(z.string(), trimAndNullifyString)
+    .nullable()
+    .optional(),
 });
 export type PatchFileMetadata = z.infer<typeof PatchFileMetadata>;
 
@@ -343,6 +358,7 @@ export const FileMetadataSchema = z.object({
       },
     ),
   corrected: z.record(z.any()).optional(),
+  expectedCorrected: z.record(z.any()).optional(),
 });
 export type FileMetadata = z.infer<typeof FileMetadataSchema>;
 

package/common/types/i-will-do-it-later.types.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { PortalType, TargetTableEnum } from './common.types';
+import { TaskPriority, TaskType } from './task.types';
+
+export enum IWillDoItLaterType {
+  KYC = 'KYC',
+  // Future types can be added here:
+  // AIC = 'AIC',
+  // AML = 'AML',
+}
+
+export const IWillDoItLaterBodySchema = z.object({
+  type: z.nativeEnum(IWillDoItLaterType).default(IWillDoItLaterType.KYC),
+});
+
+export type IWillDoItLaterBodyType = z.infer<typeof IWillDoItLaterBodySchema>;
+
+export const IWillDoItLaterResponseSchema = z.object({
+  message: z.string(),
+});
+
+export type IWillDoItLaterResponseType = z.infer<
+  typeof IWillDoItLaterResponseSchema
+>;
+
+/**
+ * @description Context required for processing "I'll do it later" actions.
+ */
+export interface IWillDoItLaterContext {
+  /** The ID of the target entity */
+  targetId: string;
+  /** The table name of the target entity */
+  targetTable: (typeof TargetTableEnum)[number];
+  /** The account ID associated with the action */
+  accountId: string;
+  /** The user ID who will be assigned the task */
+  assigneeId: string;
+}
+
+/**
+ * @description Configuration for each "I'll do it later" action type.
+ * Maps action types to their corresponding task configuration.
+ */
+export interface IWillDoItLaterTaskConfig {
+  taskType: TaskType;
+  portalType: PortalType;
+  title: string;
+  description: string;
+  priority: TaskPriority;
+}
+
+/**
+ * @description Mapping of "I'll do it later" types to their task configurations.
+ * This allows for easy extension of new action types without modifying the service logic.
+ */
+export const IWillDoItLaterTaskConfigMap: Record<
+  IWillDoItLaterType,
+  IWillDoItLaterTaskConfig
+> = {
+  [IWillDoItLaterType.KYC]: {
+    taskType: TaskType.COMPLETE_KYC,
+    portalType: PortalType.INVESTOR,
+    title: 'Complete KYC',
+    description:
+      'We are unable to verify your KYC information. Please complete your KYC.',
+    priority: TaskPriority.HIGH,
+  },
+};

package/common/types/index.ts

@@ -42,6 +42,8 @@ export * from './domain-filter.types';
 export * from './aic.types';
 export * from './default-theme-config.types';
 export * from './offering-reports.types';
+export * from './i-will-do-it-later.types';
+export * from './payment-methods.types';
 
 export enum Versions {
   V1 = 'v1',

package/common/types/individuals.types.ts

@@ -12,12 +12,11 @@ import {
   InvestorAccountType,
   SetupStatusType,
   SetupStepType,
-  ComplianceReview,
   RetirementAccountType,
-  TradeStatus,
   EmploymentStatus,
   SourceOfIncome,
   AMLProvider,
+  EmailSchema,
 } from './common.types';
 import { IBaseEntity } from './entity.types';
 import { IInvestorAccount } from './investor-account.types';
@@ -60,8 +59,8 @@ export enum aicQuestionnaireQuestionType {
 }
 
 export enum FilterBy {
-  TRADE = 'TRADE',
-  INVESTOR = 'INVESTOR',
+  ALL = 'ALL',
+  PENDING_TRADES = 'PENDING_TRADES',
 }
 
 export const aicQuestionnaireQuestion = z.object({
@@ -243,17 +242,6 @@ export const IndividualFiltersZod = z.object({
 
 export const ComplianceIndividualFiltersZod = IndividualFiltersZod.extend({
   filterBy: z.nativeEnum(FilterBy).optional(),
-  tradeStatus: z.nativeEnum(TradeStatus).optional(),
-  complianceReview: z.nativeEnum(ComplianceReview).optional(),
-  hasPendingTrades: z.preprocess(
-    (val) =>
-      val === 'true' || val === '1'
-        ? true
-        : val === 'false' || val === '0'
-          ? false
-          : val,
-    z.boolean().optional(),
-  ),
 });
 
 /**
@@ -301,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
@@ -400,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/issuer-offering.types.ts

@@ -10,6 +10,7 @@ import {
   ComplianceReview,
   DurationType,
   AssetType,
+  StringToBooleanSchema,
 } from './common.types';
 import { IBaseEntity } from './entity.types';
 import { IIssuer, issuerIdSchema } from './issuer.types';
@@ -168,6 +169,7 @@ export const PostIssuerOffering = z
       .default(AssetTemplateType.STANDARD)
       .openapi({ example: AssetTemplateType.STANDARD }),
     tiers: z.array(z.number().positive()).nullable().optional(),
+    enableBonus: z.boolean().default(false).optional(),
   })
   .superRefine((data, ctx) => {
     // Check if both values are present, and if so, ensure minInvestment is less than maxInvestment
@@ -192,38 +194,39 @@ export const PatchIssuerOffering = z.object({
     .max(100)
     .optional()
     .openapi({ example: 'Airbnb IPO' }),
+  type: z
+    .nativeEnum(OfferingType)
+    .optional()
+    .openapi({ example: OfferingType.REG_D }),
   targetAmount: z
     .number()
     .min(0)
     .max(10000000000)
     .optional()
     .openapi({ example: 120000 }),
-  raiseAmount: z
-    .number()
-    .min(0)
-    .max(10000000000)
-    .optional()
-    .openapi({ example: 200000 }),
   minInvestment: z
     .number()
     .min(0)
     .max(10000000000)
+    .nullable()
     .optional()
     .openapi({ example: 1000 }),
   maxInvestment: z
     .number()
     .min(0)
     .max(10000000000)
+    .nullable()
     .optional()
     .openapi({ example: 20000 }),
   contingencyAmount: z
     .number()
     .min(0)
     .max(10000000000)
+    .nullable()
     .optional()
     .openapi({ example: 5000 }),
-  startAt: dateSchema.optional().openapi({ example: '10/20/2024' }),
-  endAt: dateSchema.optional().openapi({ example: '10/27/2024' }),
+  startAt: dateSchema.nullable().optional().openapi({ example: '10/20/2024' }),
+  endAt: dateSchema.nullable().optional().openapi({ example: '10/27/2024' }),
   cancellationPeriod: z
     .number()
     .min(1)
@@ -299,6 +302,7 @@ export const PatchIssuerOffering = z.object({
     .optional(),
   tiers: z.array(z.number().positive()).nullable().optional(),
   enabled: z.boolean().optional(),
+  enableBonus: z.boolean().optional(),
 });
 export type PatchIssuerOffering = z.infer<typeof PatchIssuerOffering>;
 
@@ -368,15 +372,7 @@ export const IssuerOfferingsFilterZod = 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/issuer-payment-method.types.ts

@@ -222,10 +222,51 @@ export type IPaginatedIssuerPaymentMethod = z.infer<
   typeof IPaginatedIssuerPaymentMethod
 >;
 
+const issuerPaymentMethodsInclude = z.enum(['issuer', 'integration']);
+
+/**
+ * @description Query parameters for including related entities
+ * @example in contract use as -> query: PaginationOptionsZod.merge(GetIssuerPaymentMethodZod).merge(IssuerPaymentMethodsIncludeQuery)
+ */
+export const IssuerPaymentMethodsIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          issuerPaymentMethodsInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include option provided. Valid options are: ${issuerPaymentMethodsInclude.options.join(',')}`,
+      },
+    )
+    .openapi({
+      example: `${issuerPaymentMethodsInclude.options.join(',')}`,
+    }),
+});
+export type IssuerPaymentMethodsIncludeQuery = z.infer<
+  typeof IssuerPaymentMethodsIncludeQuery
+>;
+
 export const GetIssuerPaymentMethodZod = z.object({
   issuerId: issuerIdSchema.openapi({
     example: 'issuer_01jdq2crwke8xskjd840cj79pw',
   }),
+  enabled: z
+    .string()
+    .optional()
+    .refine((v) => !v || v === 'true' || v === 'false', {
+      message: 'enabled must be a boolean string',
+    })
+    .transform((v) => {
+      if (!v) return undefined;
+      return v === 'true';
+    })
+    .openapi({
+      example: 'true',
+    }),
 });
 export type GetIssuerPaymentMethodZod = z.infer<
   typeof GetIssuerPaymentMethodZod

package/common/types/issuer.types.ts

@@ -152,6 +152,10 @@ export const PutIssuerZod = z
       .lazy(() => fileIdSchema)
       .optional()
       .nullable(),
+    formationDocumentFileId: z
+      .lazy(() => fileIdSchema)
+      .optional()
+      .nullable(),
     coverArtId: z
       .lazy(() => fileIdSchema)
       .optional()
@@ -188,6 +192,11 @@ export const IIssuer = IBaseEntity.extend({
   accountId: z.string(),
   account: AccountZod.optional().nullable(),
   ss4LetterFileId: z.string().nullable(),
+  formationDocumentFileId: z.string().nullable(),
+  formationDocument: z
+    .lazy(() => FileZod)
+    .nullable()
+    .optional(),
   status: z
     .nativeEnum(IssuerStatus)
     .openapi({ example: IssuerStatus.SUBMITTED }),

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>;