@dalmore/api-contracts 0.0.0-dev.2dc8e92 → 0.0.0-dev.3af7603

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

@@ -0,0 +1,31 @@
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { z } from 'zod';
+import { TypeID } from 'typeid-js';
+import { IBaseEntity } from './entity.types';
+
+extendZodWithOpenApi(z);
+
+export const accountSettingIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'account_setting';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid account setting ID format. Must be a valid TypeID with "account_setting" prefix.',
+  },
+);
+
+export const IAccountSettingZod = IBaseEntity.extend({
+  id: accountSettingIdSchema.openapi({
+    example: 'account_setting_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+  accountId: z.string().openapi({
+    example: 'account_01j5y5ghx8fvc83dmx3pznq7hv',
+  }),
+});
+export type IAccountSettingZod = z.infer<typeof IAccountSettingZod>;

package/common/types/activity.types.ts

@@ -199,7 +199,7 @@ export const ActivityZod = IBaseEntity.extend({
   userId: z.string().nullable(),
   activityTypeId: z.string(),
   accountId: z.string().nullable(),
-  user: UserForActivityZod,
+  user: UserForActivityZod.nullable(),
   activityType: ActivityTypeZod,
   targetObject: z.string().nullable().optional(),
   __entity: z.string().optional(),

package/common/types/api-key-logs.types.ts

@@ -12,7 +12,7 @@ export const ApiLogsFiltersZod = z.object({
   endpoint: z.string().optional(),
   apiKeyId: apiKeyIdSchema.optional(),
   method: z.nativeEnum(HttpMethod).optional(),
-  status: z.nativeEnum(HttpStatus).optional(),
+  status: z.preprocess(Number, z.nativeEnum(HttpStatus)).optional(),
   from: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
   to: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
 });

package/common/types/asset.types.ts

@@ -29,7 +29,7 @@ export const assetIdSchema = z.string().refine(
     message: `Invalid asset ID format. Must be a valid TypeID with "asset" prefix. Example: asset_01j5y5ghx5fg68d663j1fvy2x7`,
   },
 );
-export enum TemplateType {
+export enum AssetTemplateType {
   STANDARD = 'STANDARD',
   TIERED = 'TIERED',
 }
@@ -51,7 +51,7 @@ export const IAsset = IBaseEntity.extend({
     .lazy(() => IOffering)
     .optional()
     .nullable(), // Use z.lazy here
-  template: z.nativeEnum(TemplateType),
+  template: z.nativeEnum(AssetTemplateType),
   tiers: z.array(z.number().positive()).nullable(),
   enableBonus: z.boolean(),
 });
@@ -102,16 +102,16 @@ const PostAssetBase = z.object({
     .optional()
     .openapi({ example: DurationType.DAY }),
   template: z
-    .nativeEnum(TemplateType)
-    .default(TemplateType.STANDARD)
-    .openapi({ example: TemplateType.STANDARD }),
+    .nativeEnum(AssetTemplateType)
+    .default(AssetTemplateType.STANDARD)
+    .openapi({ example: AssetTemplateType.STANDARD }),
   tiers: z.array(z.number().positive()).nullable().optional(),
   enableBonus: z.boolean().default(false).openapi({ example: false }),
 });
 
-const postAssetRefinement = (data: any, ctx: any) => {
+export const postAssetRefinement = (data: any, ctx: any) => {
   // If type is bond, yield and duration must be provided (cannot be null or undefined)
-  if (data.type === AssetType.BOND) {
+  if (data.assetType === AssetType.BOND || data.type === AssetType.BOND) {
     if (data.yield === null || data.yield === undefined) {
       ctx.addIssue({
         path: ['yield'],
@@ -139,7 +139,7 @@ const postAssetRefinement = (data: any, ctx: any) => {
   }
 
   // If type is stock, yield and duration must be either null or undefined
-  if (data.type === AssetType.STOCK) {
+  if (data.assetType === AssetType.STOCK || data.type === AssetType.STOCK) {
     if (data.yield !== null && data.yield !== undefined) {
       ctx.addIssue({
         path: ['yield'],
@@ -162,7 +162,7 @@ const postAssetRefinement = (data: any, ctx: any) => {
       });
     }
   }
-  if (data.template === TemplateType.TIERED) {
+  if (data.template === AssetTemplateType.TIERED) {
     if (data.tiers === null || data.tiers === undefined) {
       ctx.addIssue({
         path: ['tiers'],
@@ -172,7 +172,7 @@ const postAssetRefinement = (data: any, ctx: any) => {
     }
   }
   // If template is STANDARD, tiers must be null or undefined
-  if (data.template === TemplateType.STANDARD) {
+  if (data.template === AssetTemplateType.STANDARD) {
     if (data.tiers !== null && data.tiers !== undefined) {
       ctx.addIssue({
         path: ['tiers'],
@@ -233,9 +233,9 @@ export const PutAsset = z.object({
     .optional()
     .openapi({ example: DurationType.DAY }),
   template: z
-    .nativeEnum(TemplateType)
-    .default(TemplateType.STANDARD)
-    .openapi({ example: TemplateType.STANDARD })
+    .nativeEnum(AssetTemplateType)
+    .default(AssetTemplateType.STANDARD)
+    .openapi({ example: AssetTemplateType.STANDARD })
     .nullable()
     .optional(),
   tiers: z.array(z.number().positive()).nullable().optional(),
@@ -262,7 +262,7 @@ export const AssetsIncludeQuery = z.object({
           assetsInclude.options.includes(include as any),
         ),
       {
-        message: `Invalid include option provided. Valid options are: ${assetsInclude.options.join(', ')}`,
+        message: `Invalid include option provided. Valid options are: ${assetsInclude.options.join(',')}`,
       },
     )
     .openapi({

package/common/types/bonus-tier.types.ts

@@ -98,6 +98,15 @@ export type EstimateBonusTierCalculationZod = z.infer<
   typeof EstimateBonusTierCalculationZod
 >;
 
+export const ComplianceEstimateBonusTierCalculationZod =
+  EstimateBonusTierCalculationZod.and(
+    z.object({
+      accountId: accountIdSchema,
+    }),
+  );
+export type ComplianceEstimateBonusTierCalculationZod = z.infer<
+  typeof ComplianceEstimateBonusTierCalculationZod
+>;
 export const EstimateBonusTierCalculationResponseZod = z.object({
   bonusTierId: bonusTierIdSchema
     .nullable()
@@ -145,3 +154,27 @@ export const CompliancePostBonusTierZod = PostBonusTierZod.extend({
 export type CompliancePostBonusTierZod = z.infer<
   typeof CompliancePostBonusTierZod
 >;
+export const PurchaseCalculationZod = z.object({
+  assetId: assetIdSchema,
+  totalAmount: z.number().positive().openapi({ example: 1000 }),
+  purchasedShares: z.number().positive().int().openapi({ example: 100 }),
+});
+export type PurchaseCalculationZod = z.infer<typeof PurchaseCalculationZod>;
+
+export const PurchaseCalculationResponseZod = z.object({
+  bonusTierId: bonusTierIdSchema
+    .nullable()
+    .openapi({ example: 'bonus_tier_01j5y5ghx5fg68d663j1fvy2x7' }),
+  assetId: assetIdSchema.openapi({
+    example: 'asset_00041061050r3gg28a1c60t3gf',
+  }),
+  type: z
+    .nativeEnum(BonusType)
+    .nullable()
+    .openapi({ example: BonusType.PERCENTAGE }),
+  bonusShares: z.number().int().openapi({ example: 100 }),
+});
+
+export type PurchaseCalculationResponseZod = z.infer<
+  typeof PurchaseCalculationResponseZod
+>;

package/common/types/cart.types.ts

@@ -3,6 +3,7 @@ import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { TradeStatus } from './common.types';
 import { investorAccountIdSchema } from './investor-account.types';
 import { paymentMethodIdSchema } from './payment-methods.types';
+import { userIdSchema } from './user.types';
 
 extendZodWithOpenApi(z);
 
@@ -10,7 +11,9 @@ export const PlaceTradeResponse = z.object({
   tradeStatus: z.nativeEnum(TradeStatus).optional(),
 });
 export const PlaceTradeBody = z.object({});
-
+export const ClientPlacetradeBody = z.object({
+  userId: userIdSchema,
+});
 export const PatchCartBody = z.object({
   investorAccountId: investorAccountIdSchema.optional(),
   paymentMethodId: paymentMethodIdSchema.optional(),

package/common/types/common.types.ts

@@ -111,6 +111,10 @@ export enum HttpMethod {
   OPTIONS = 'OPTIONS',
 }
 
+export enum UserStatus {
+  ACTIVE = 'ACTIVE',
+  LOCKED = 'LOCKED',
+}
 export const SENSITIVE_PATTERNS = [
   /password/i,
   /credit.*card/i,
@@ -200,11 +204,6 @@ export enum UserType {
   DEMO = 'DEMO',
 }
 
-export enum UserStatus {
-  ACTIVE = 'ACTIVE',
-  LOCKED = 'LOCKED',
-}
-
 export enum UserRole {
   API_KEY = 'API_KEY',
   IMPORT = 'IMPORT',
@@ -306,7 +305,7 @@ export const AuthUserReq = BaseAuthReq.extend({
   lastName: z.string(),
   email: z.string().email(),
   provider: z.string(),
-  status: z.lazy(() => z.nativeEnum(UserStatus)),
+  locked: z.boolean(),
   lastLoginAt: z.date().nullable(),
   loginCount: z.number(),
   requiresTwoFactorSetup: z.boolean().optional(),
@@ -1518,3 +1517,14 @@ export const SUBJECT_TYPE_MAP: Record<BulkExportType, string> = {
   [BulkExportType.SECONDARY_CUSTOMERS]: 'Secondary Customers',
   [BulkExportType.SECONDARY_TRADES]: 'Secondary Trades',
 };
+
+export const StringToBooleanSchema = z.preprocess(
+  (val) =>
+    val === 'true' || val === '1'
+      ? true
+      : val === 'false' || val === '0'
+        ? false
+        : val,
+  z.boolean(),
+);
+export type StringToBooleanSchema = z.infer<typeof StringToBooleanSchema>;

package/common/types/dashboard.types.ts

@@ -7,6 +7,7 @@ import {
   FileLabels,
   IPaginationMeta,
   OfferingType,
+  StringToBooleanSchema,
 } from './common.types';
 import { accountIdSchema } from './account.types';
 
@@ -330,15 +331,7 @@ export const GetInvestmentDashboardQueryZod = z.object({
   offerings: OfferingsArrayQueryZod.optional(),
   offeringTypes: OfferingTypesQueryZod.optional(),
   timeFilteringType: z.nativeEnum(DashboardTimeFilteringType),
-  debug: z.preprocess(
-    (val) =>
-      val === 'true' || val === '1'
-        ? true
-        : val === 'false' || val === '0'
-          ? false
-          : val,
-    z.boolean().optional(),
-  ),
+  debug: StringToBooleanSchema.optional(),
 });
 export type GetInvestmentDashboardQueryZod = z.infer<
   typeof GetInvestmentDashboardQueryZod

package/common/types/disbursements.types.ts

@@ -11,14 +11,17 @@ import {
 import { tradeIdSchema } from './trade.types';
 import { accountIdSchema } from './account.types';
 import { TypeID } from 'typeid-js';
-import { issuerIdSchema } from './issuer.types';
-import { issuerBankAccountIdSchema } from './issuer-bank-account.types';
+import { IIssuer, issuerIdSchema } from './issuer.types';
+import {
+  IIssuerBankAccount,
+  issuerBankAccountIdSchema,
+} from './issuer-bank-account.types';
 import { userIdSchema, UserZod } from './user.types';
 import {
   PostDisbursementAdjustmentZod,
   DisbursementAdjustmentType,
 } from './disbursement-adjustment.types';
-import { escrowAccountIdSchema } from './escrow-account.types';
+import { IEscrowAccount, escrowAccountIdSchema } from './escrow-account.types';
 
 export const disbursementIdSchema = z.string().refine(
   (value) => {
@@ -308,3 +311,116 @@ export const DisbursementSummaryZod = z.object({
   amountToBeTransferred: z.number(),
 });
 export type DisbursementSummaryZod = z.infer<typeof DisbursementSummaryZod>;
+
+// GET /disbursements/preview query parameters
+export const GetDisbursementPreviewQueryZod = z.object({
+  offeringId: offeringIdSchema,
+  selectedTrades: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (ids) =>
+        ids.every((id) => {
+          try {
+            const tid = TypeID.fromString(id);
+            return tid.getType() === 'trade';
+          } catch {
+            return false;
+          }
+        }),
+      {
+        message: 'All selected trades must be valid trade IDs',
+      },
+    )
+    .openapi({
+      example: 'trade_01abc123,trade_01def456',
+    }),
+});
+export type GetDisbursementPreviewQueryZod = z.infer<
+  typeof GetDisbursementPreviewQueryZod
+>;
+
+// Context fields for disbursement preview
+export const DisbursementPreviewContextZod = z.object({
+  issuer: z.lazy(() => IIssuer).nullable(),
+  offering: z.lazy(() => IOffering).nullable(),
+  escrowAccount: z.lazy(() => IEscrowAccount).nullable(),
+  destinationBank: z.lazy(() => IIssuerBankAccount).nullable(),
+});
+export type DisbursementPreviewContextZod = z.infer<
+  typeof DisbursementPreviewContextZod
+>;
+
+// Balance values for disbursement preview
+export const DisbursementPreviewBalanceZod = z.object({
+  totalRaised: z.number(),
+  totalDisbursed: z.number(),
+  pending: z.number(),
+  refundPool: z.number(),
+  availableForDisbursement: z.number(),
+});
+export type DisbursementPreviewBalanceZod = z.infer<
+  typeof DisbursementPreviewBalanceZod
+>;
+
+// Trade summary for disbursement preview
+export const DisbursementPreviewTradeSummaryZod = z.object({
+  selectedTradesCount: z.number(),
+  selectedTradesTotalAmount: z.number(),
+});
+export type DisbursementPreviewTradeSummaryZod = z.infer<
+  typeof DisbursementPreviewTradeSummaryZod
+>;
+
+// Contingency validation result
+export const DisbursementPreviewContingencyZod = z.object({
+  contingencyPassed: z.boolean(),
+  contingencyMessage: z.string().nullable(),
+  contingencyAmount: z.number(),
+});
+export type DisbursementPreviewContingencyZod = z.infer<
+  typeof DisbursementPreviewContingencyZod
+>;
+
+// Amount defaults and constraints
+export const DisbursementPreviewAmountZod = z.object({
+  defaultAmount: z.number(),
+  minAmount: z.number(),
+  maxAmount: z.number(),
+});
+export type DisbursementPreviewAmountZod = z.infer<
+  typeof DisbursementPreviewAmountZod
+>;
+
+// Complete response for GET /disbursements/preview
+export const DisbursementPreviewZod = z.object({
+  context: DisbursementPreviewContextZod,
+  balance: DisbursementPreviewBalanceZod,
+  tradeSummary: DisbursementPreviewTradeSummaryZod,
+  contingency: DisbursementPreviewContingencyZod,
+  amount: DisbursementPreviewAmountZod,
+});
+export type DisbursementPreviewZod = z.infer<typeof DisbursementPreviewZod>;
+
+export const EligibleOfferingZod = z.object({
+  offeringId: offeringIdSchema,
+  offeringName: z.string(),
+  availableAmount: z.number(),
+});
+export type EligibleOfferingZod = z.infer<typeof EligibleOfferingZod>;
+
+export const IPaginatedEligibleOffering = z.object({
+  items: z.array(EligibleOfferingZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedEligibleOffering = z.infer<
+  typeof IPaginatedEligibleOffering
+>;
+
+export const EligibleOfferingsFiltersZod = z.object({
+  search: z.string().optional(),
+});
+export type EligibleOfferingsFiltersZod = z.infer<
+  typeof EligibleOfferingsFiltersZod
+>;

package/common/types/file.types.ts

@@ -17,7 +17,7 @@ import { KybZod } from './kyb.types';
 import { IIndividualZod, individualIdSchema } from './individuals.types';
 import { LegalEntityZod } from './legal-entity.types';
 import { IInvestorAccount } from './investor-account.types';
-import { TradeZod } from './trade.types';
+import { tradeIdSchema, TradeZod } from './trade.types';
 
 extendZodWithOpenApi(z);
 
@@ -168,13 +168,13 @@ export type PostFileQueryParams = z.infer<typeof PostFileQueryParams>;
 
 /**
  * CLIENT portal specific schema for file uploads
- * Only allows INDIVIDUALS as target for file uploads
+ * Only allows INDIVIDUALS and TRADES as target for file uploads
  */
 export const ClientPostFileQueryParams = z.object({
   name: z.string().min(1).max(100).openapi({ example: 'file_name' }),
   category: z.string().max(50).openapi({ example: 'application' }),
   label: FileLabelsEnum.openapi({ example: FileLabels.OTHER }),
-  targetId: individualIdSchema.openapi({
+  targetId: z.union([individualIdSchema, tradeIdSchema]).openapi({
     example: 'individual_01kcrsny60fb9rjc8bbqc3b80c',
   }),
   metadata: metadataSchema.nullable().optional(),
@@ -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,9 +12,7 @@ import {
   InvestorAccountType,
   SetupStatusType,
   SetupStepType,
-  ComplianceReview,
   RetirementAccountType,
-  TradeStatus,
   EmploymentStatus,
   SourceOfIncome,
   AMLProvider,
@@ -60,8 +58,8 @@ export enum aicQuestionnaireQuestionType {
 }
 
 export enum FilterBy {
-  TRADE = 'TRADE',
-  INVESTOR = 'INVESTOR',
+  ALL = 'ALL',
+  PENDING_TRADES = 'PENDING_TRADES',
 }
 
 export const aicQuestionnaireQuestion = z.object({
@@ -243,17 +241,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(),
-  ),
 });
 
 /**