@dalmore/api-contracts 1.0.0

package/common/types/individuals.types.ts

@@ -0,0 +1,554 @@
+import { z } from 'zod';
+import {
+  AccountZod,
+  IPaginationMeta,
+  KYCStatus,
+  SanctionsStatus,
+  AMLStatus,
+  IraCheck,
+  AicAccreditationType,
+  KYCDocumentType,
+  AicStatus,
+  InvestorAccountType,
+  SetupStatusType,
+  SetupStepType,
+  ComplianceReview,
+  RetirementAccountType,
+  TradeStatus,
+  EmploymentStatus,
+  SourceOfIncome,
+  AMLProvider,
+} from './common.types';
+import { IBaseEntity } from './entity.types';
+import { IInvestorAccount } from './investor-account.types';
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { TypeID } from 'typeid-js';
+import { KycZod } from './kyc.types';
+import { AmlZod } from './aml.types';
+import { AddressSchema } from './address.types';
+import { CountryEnumSchema } from './countries.types';
+import { PhoneZodSchema } from './phone.type';
+import { AicZod } from './aic.types';
+extendZodWithOpenApi(z);
+
+export const individualIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'individual';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid individual ID format. Must be a valid TypeID with "individual" prefix.',
+  },
+);
+
+export enum IndividualRole {
+  PRIMARY = 'PRIMARY',
+  JOINT = 'JOINT',
+}
+
+export enum aicQuestionnaireQuestionType {
+  BOOLEAN = 'BOOLEAN',
+  SELECT_ONE = 'SELECT_ONE',
+  SELECT_MULTIPLE = 'SELECT_MULTIPLE',
+  NUMBER = 'NUMBER',
+  TEXT = 'TEXT',
+}
+
+export enum FilterBy {
+  TRADE = 'TRADE',
+  INVESTOR = 'INVESTOR',
+}
+
+export const aicQuestionnaireQuestion = z.object({
+  id: z.string(),
+  question: z.string(),
+  choices: z.array(z.string()),
+  type: z.nativeEnum(aicQuestionnaireQuestionType),
+  key: z.string(),
+  answer: z.string(),
+});
+export type aicQuestionnaireQuestion = z.infer<typeof aicQuestionnaireQuestion>;
+
+export const aicQuestionnaire = z.object({
+  AIC_Questionnaire: z.object({
+    investment_objective: z.string().min(1).max(255).optional(),
+    investment_experience: z.string().min(1).max(255).optional(),
+    risk_willingness: z.string().min(1).max(255).optional(),
+    equities_allocation: z.string().min(1).max(255).optional(),
+    bonds_allocation: z.string().min(1).max(255).optional(),
+    other_investments_allocation: z.string().min(1).max(255).optional(),
+    overall_portfolio_percentage: z.string().min(1).max(255).optional(),
+    annual_living_expenses: z.string().min(1).max(255).optional(),
+    marginal_tax_rate: z.string().min(1).max(255).optional(),
+    significant_liquid_net_worth: z.string().min(1).max(255).optional(),
+    risky_investment_understanding: z.string().min(1).max(255).optional(),
+    investment_time_horizon: z.string().min(1).max(255).optional(),
+  }),
+});
+export type aicQuestionnaire = z.infer<typeof aicQuestionnaire>;
+
+export const iraQuestionnaireQuestion = z.object({
+  id: z.string(),
+  hasIraAccounts: z.boolean(),
+  inSelfDirectedIra: z.boolean(),
+  custodian: z.string(),
+  hasOtherQualifiedFunds: z.boolean(),
+});
+export type iraQuestionnaireQuestion = z.infer<typeof iraQuestionnaireQuestion>;
+
+export const iraQuestionnaire = z.array(iraQuestionnaireQuestion);
+export type iraQuestionnaire = z.infer<typeof iraQuestionnaire>;
+
+export const IIndividualZod = IBaseEntity.extend({
+  tid: z.string().nullable(),
+  accountId: z.string(),
+  account: z.lazy(() => AccountZod).optional(),
+  investorAccountId: z.string(),
+  investorAccount: z.lazy(() => IInvestorAccount).optional(), // circular dependency requires lazy
+  role: z.nativeEnum(IndividualRole),
+  kycStatus: z.nativeEnum(KYCStatus),
+  kycFirstName: z.string().nullable(),
+  kycLastName: z.string().nullable(),
+  kycDocumentType: z.nativeEnum(KYCDocumentType),
+  kycDocumentIssuer: z.string().nullable(),
+  kycDocumentNumber: z.string().nullable(),
+  kycIssuerDate: z.string().nullable(),
+  kycExpirationDate: z.string().nullable(),
+  kycCheck: z.nativeEnum(KYCStatus),
+  kycCheckedAt: z.date().nullable(),
+  kycLog: z.string().nullable(),
+  kycReviewedById: z.string().nullable(),
+  kycReviewedAt: z.date().nullable(),
+  sanctionsStatus: z.nativeEnum(SanctionsStatus),
+  amlStatus: z.nativeEnum(AMLStatus),
+  amlProvider: z.nativeEnum(AMLProvider).nullable(),
+  amlTid: z.string().nullable(),
+  amlUrl: z.string().nullable(),
+  amlCheckedAt: z.date().nullable(),
+  amlLog: z.string().nullable(),
+  amlLogData: z.string().nullable(),
+  amlReviewedById: z.string().nullable(),
+  amlReviewedAt: z.date().nullable(),
+  liquidNetWorth: z.coerce.number().multipleOf(0.01).nullable(),
+  liquidSecurities: z.coerce.number().multipleOf(0.01).nullable(),
+  illiquidSecurities: z.coerce.number().multipleOf(0.01).nullable(),
+  privateSecurities: z.coerce.number().multipleOf(0.01).nullable(),
+  aicAccreditationType: z.nativeEnum(AicAccreditationType),
+  aicExpirationDate: z.date().nullable(),
+  aicQuestionnaire: z.string().nullable(),
+  aicStatus: z.nativeEnum(AicStatus),
+  aicCheckedAt: z.date().nullable(),
+  aicLog: z.string().nullable(),
+  aicReviewedById: z.string().nullable(),
+  aicReviewedAt: z.date().nullable(),
+  iraQuestionnaire: iraQuestionnaire.nullable(),
+  iraCheck: z.nativeEnum(IraCheck),
+  iraCheckedAt: z.date().nullable(),
+  iraLog: z.string().nullable(),
+  iraReviewedById: z.string().nullable(),
+  iraReviewedAt: z.date().nullable(),
+  firstName: z.string(),
+  lastName: z.string().nullable(),
+  dob: z.date().nullable(),
+  isUsCitizenOrGreenCardHolder: z.boolean(),
+  citizenship: CountryEnumSchema.optional(),
+  ssn: z.string().nullable(),
+  lastFour: z.string().nullable(),
+  address: z.string().nullable(),
+  address2: z.string().nullable(),
+  email: z.string().email().nullable(),
+  phone: z.string().nullable(),
+  city: z.string().nullable(),
+  state: z.string().nullable(),
+  zip: z.string().nullable(),
+  country: z.string().nullable(),
+  kycTid: z.string().nullable(),
+  currencyCode: z.string().length(3).nullable(),
+  investedInCrowdfunding: z.coerce.number().nullable(),
+  currentAnnualIncome: z.coerce.number().nullable(),
+  averageAnnualIncome: z.coerce.number().nullable(),
+  averageHouseholdIncome: z.coerce.number().nullable(),
+  currentHouseholdIncome: z.coerce.number().nullable(),
+  householdNetWorth: z.coerce.number().nullable(),
+  isSolicited: z.boolean(),
+  isRealEstate: z.boolean(),
+  iliquidSecurities: z.coerce.number().multipleOf(0.01).nullable().optional(),
+  timeHorizon: z.string().nullable(),
+  riskTolerance: z.string().nullable(),
+  investmentObjective: z.string().nullable(),
+  investmentExperience: z.string().nullable(),
+  experienceInPrivate: z.string().nullable(),
+  levelOfEducation: z.string().nullable(),
+  financialAdvisor: z.boolean(),
+  occupation: z.string().nullable(),
+  employmentStatus: z.nativeEnum(EmploymentStatus),
+  employerName: z.string().nullable(),
+  employerAddressLine1: z.string().nullable(),
+  employerAddressLine2: z.string().nullable(),
+  employerCity: z.string().nullable(),
+  employerState: z.string().nullable(),
+  employerZip: z.string().nullable(),
+  employerCountry: z.string().nullable(),
+  notes: z.string().nullable(),
+  kycs: z.array(KycZod).nullable().optional(),
+  amls: z.array(AmlZod).nullable().optional(),
+  aics: z.array(AicZod).nullable().optional(),
+  setupStatus: z.nativeEnum(SetupStatusType),
+  setupStep: z.nativeEnum(SetupStepType),
+  sourceOfIncome: z.nativeEnum(SourceOfIncome).nullable(),
+  ownership: z.coerce.number().nullable(),
+  kycProvider: z.string().nullable(),
+  retirementAccountType: z
+    .nativeEnum(RetirementAccountType)
+    .nullable()
+    .optional(),
+  custodianName: z.string().nullable().optional(),
+  custodianAccountNumber: z.string().nullable().optional(),
+  custodianRepresentativeName: z.string().nullable().optional(),
+  custodianEmail: z.string().email().nullable().optional(),
+  accredited: z.boolean(),
+});
+export type IIndividualZod = z.infer<typeof IIndividualZod>;
+
+export const IPaginatedIndividual = z.object({
+  items: z.array(IIndividualZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedIndividual = z.infer<typeof IPaginatedIndividual>;
+
+export const individualsInclude = z.enum([
+  'account',
+  'investorAccount',
+  'kycs',
+  'amls',
+  'kycReviewedBy',
+  'amlReviewedBy',
+  'aicReviewedBy',
+  'iraReviewedBy',
+]);
+
+export const IndividualFiltersZod = z.object({
+  kycStatus: z.nativeEnum(KYCStatus).optional(),
+  amlStatus: z.nativeEnum(AMLStatus).optional(),
+  aicStatus: z.nativeEnum(AicStatus).optional(),
+  accountId: z.string().optional(),
+  search: z.string().max(50).optional(),
+  investorAccountType: z.nativeEnum(InvestorAccountType).optional(),
+});
+
+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(),
+  ),
+});
+
+/**
+ * @description Query parameters for including related entities
+ * @example in contract us as -> query: z.object({}).merge(UsersIncludeQuery),
+ */
+export const IndividualsIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          individualsInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include option provided. Valid options are: ${individualsInclude.options.join(',')}`,
+      },
+    )
+    .openapi({
+      example: `${individualsInclude.options.join(',')}`,
+    }),
+});
+export interface IndividualsIncludeQuery
+  extends z.infer<typeof IndividualsIncludeQuery> {}
+
+export const PostIndividualBodySchema = z
+  .object({
+    lastName: z.string().optional(),
+    investorAccountId: z.string(),
+    firstName: z.string().optional(),
+    dob: z.coerce.date().optional(), // should be optional
+    isUsCitizenOrGreenCardHolder: z.boolean().optional(),
+    citizenship: CountryEnumSchema.optional(),
+    ssn: z
+      .string()
+      .length(9, 'ssn must be 9 digits')
+      .refine((v) => !isNaN(Number(v)), {
+        message: `ssn can only consist of numbers`,
+      })
+      .nullable()
+      .optional(),
+    currencyCode: z
+      .string()
+      .length(3, 'currencyCode must be 3 digits')
+      .optional(),
+    email: z.string().email().optional(),
+    role: z.nativeEnum(IndividualRole),
+    phone: PhoneZodSchema.openapi({ example: '+12124567890' }).optional(),
+    ownership: z.coerce
+      .number()
+      .min(0, 'Ownership is less than 0')
+      .max(100, 'Ownership is more than 100')
+      .optional(),
+    setupStep: z.nativeEnum(SetupStepType).optional(),
+    liquidNetWorth: z.coerce
+      .number()
+      .multipleOf(0.01)
+      .min(0, 'Liquid Net Worth is less than 0')
+      .max(10000000, 'Liquid Net Worth is more than 10 Million')
+      .optional(),
+    currentAnnualIncome: z.coerce
+      .number()
+      .min(0, 'Current Annual Income is less than 0')
+      .max(10000000, 'Current Annual Income is more than 10 Million')
+      .optional(),
+    sourceOfIncome: z.nativeEnum(SourceOfIncome).nullable().optional(),
+    employerName: z.string().min(1).max(255).nullable().optional(),
+    investedInCrowdfunding: z.coerce
+      .number()
+      .min(0, 'Investments in crowdfunding is less than 0')
+      .max(10000000, 'Investments in crowdfunding is more than 10 Million')
+      .optional(),
+    retirementAccountType: z
+      .nativeEnum(RetirementAccountType)
+      .nullable()
+      .optional(),
+    custodianName: z.string().nullable().optional(),
+    custodianAccountNumber: z.string().nullable().optional(),
+    custodianRepresentativeName: z.string().nullable().optional(),
+    custodianEmail: z.string().email().nullable().optional(),
+    tid: z.string().optional(),
+  })
+  .and(AddressSchema)
+  .superRefine((data, ctx) => {
+    if (
+      data.retirementAccountType === RetirementAccountType.CUSTODIAN_MANAGED
+    ) {
+      if (!data.custodianName) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Custodian name is required',
+        });
+      }
+      if (!data.custodianAccountNumber) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Custodian account number is required',
+        });
+      }
+      if (!data.custodianRepresentativeName) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Custodian representative name is required',
+        });
+      }
+      if (!data.custodianEmail) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Custodian email is required',
+        });
+      }
+    }
+  });
+
+export type PostIndividualBodyType = z.infer<typeof PostIndividualBodySchema>;
+
+export const UpdateIndividualBodySchema = z
+  .object({
+    lastName: z
+      .string()
+      .min(2, 'lastName is less than 2 characters')
+      .max(20, 'lastName is more than 20 characters')
+      .optional(),
+    firstName: z
+      .string()
+      .min(2, 'firstName is less than 2 characters')
+      .max(20, 'firstName is more than 20 characters')
+      .optional(),
+    kycFirstName: z
+      .string()
+      .min(2, 'kycFirstName is less than 2 characters')
+      .max(20, 'kycFirstName is more than 20 characters')
+      .optional(),
+    kycLastName: z
+      .string()
+      .min(2, 'kycLastName is less than 2 characters')
+      .max(20, 'kycLastName is more than 20 characters')
+      .optional(),
+    dob: z.coerce.date().optional(),
+    currencyCode: z
+      .string()
+      .length(3, 'currencyCode must be 3 digits')
+      .optional(),
+    phone: PhoneZodSchema.openapi({ example: '+12124567890' }).optional(),
+    email: z.string().email().optional(),
+    ownership: z.coerce
+      .number()
+      .min(0, 'Ownership is less than 0')
+      .max(100, 'Ownership is more than 100')
+      .optional(),
+    isUsCitizenOrGreenCardHolder: z.boolean().optional(),
+    citizenship: CountryEnumSchema.optional(),
+    ssn: z
+      .string()
+      .length(9, 'ssn must be 9 digits')
+      .refine((v) => !isNaN(Number(v)), {
+        message: `ssn can only consist of numbers`,
+      })
+      .nullable()
+      .optional(),
+    kycDocumentType: z.nativeEnum(KYCDocumentType).optional(),
+    kycDocumentIssuer: z
+      .string()
+      .min(2, 'kycDocumentIssuer is less than 2 characters ')
+      .max(100, 'kycDocumentIssuer is more than 100 characters ')
+      .optional(),
+    kycExpirationDate: z.coerce
+      .date()
+      .transform((v) => v.toISOString())
+      .optional(),
+    kycIssuerDate: z.coerce
+      .date()
+      .transform((v) => v.toISOString())
+      .optional(),
+    kycDocumentNumber: z.string().optional(),
+    householdNetWorth: z.coerce
+      .number()
+      .min(0, 'Household Net Worth is less than 0')
+      .max(10000000, 'Household Net Worth is more than 10 Million')
+      .optional(),
+    liquidNetWorth: z.coerce
+      .number()
+      .multipleOf(0.01)
+      .min(0, 'Liquid Net Worth is less than 0')
+      .max(10000000, 'Liquid Net Worth is more than 10 Million')
+      .optional(),
+    currentHouseholdIncome: z.coerce
+      .number()
+      .min(0, 'Current Household Income is less than 0')
+      .max(10000000, 'Current Household Income is more than 10 Million')
+      .optional(),
+    currentAnnualIncome: z.coerce
+      .number()
+      .min(0, 'Current Annual Income is less than 0')
+      .max(10000000, 'Current Annual Income is more than 10 Million')
+      .optional(),
+    investedInCrowdfunding: z.coerce
+      .number()
+      .min(0, 'Investments in crowdfunding is less than 0')
+      .max(10000000, 'Investments in crowdfunding is more than 10 Million')
+      .optional(),
+    setupStep: z.nativeEnum(SetupStepType).optional(),
+    employerName: z.string().min(1).max(255).nullable().optional(),
+    sourceOfIncome: z.nativeEnum(SourceOfIncome).nullable().optional(),
+    aicQuestionnaire: z
+      .string()
+      .refine((value) => {
+        try {
+          const validation = aicQuestionnaire.safeParse(JSON.parse(value));
+          return validation.success;
+        } catch (e) {
+          return false;
+        }
+      })
+      .optional(),
+    kycProvider: z.string().min(1).max(255).optional(),
+    aicAccreditationType: z.nativeEnum(AicAccreditationType).optional(),
+    accredited: z.boolean().optional(),
+    retirementAccountType: z
+      .nativeEnum(RetirementAccountType)
+      .nullable()
+      .optional(),
+    custodianName: z.string().nullable().optional(),
+    custodianAccountNumber: z.string().nullable().optional(),
+    custodianRepresentativeName: z.string().nullable().optional(),
+    custodianEmail: z.string().email().nullable().optional(),
+  })
+  .and(AddressSchema);
+
+export type UpdateIndividualBodyType = z.infer<
+  typeof UpdateIndividualBodySchema
+>;
+
+export const IndividualResponseSchema = IBaseEntity.extend({
+  tid: z.string().nullable(),
+  accountId: z.string(),
+  account: z.lazy(() => AccountZod).optional(),
+  investorAccountId: z.string(),
+  investorAccount: z.lazy(() => IInvestorAccount).optional(),
+  role: z.nativeEnum(IndividualRole),
+  firstName: z.string(),
+  lastName: z.string().nullable(),
+  dob: z.date().nullable(),
+  isUsCitizenOrGreenCardHolder: z.boolean(),
+  ssn: z.string().nullable(),
+  lastFour: z.string().nullable(),
+  address: z.string().nullable(),
+  address2: z.string().nullable(),
+  email: z.string().email().nullable(),
+  phone: z.string().nullable(),
+  city: z.string().nullable(),
+  country: z.string().nullable(),
+  citizenship: z.string().nullable(),
+  state: z.string().nullable(),
+  zip: z.string().nullable(),
+  currencyCode: z.string().length(3).nullable(),
+  financialAdvisor: z.boolean(),
+  occupation: z.string().nullable(),
+  employmentStatus: z.nativeEnum(EmploymentStatus),
+  employerName: z.string().nullable(),
+  employerAddressLine1: z.string().nullable(),
+  employerAddressLine2: z.string().nullable(),
+  employerCity: z.string().nullable(),
+  employerState: z.string().nullable(),
+  employerZip: z.string().nullable(),
+  employerCountry: z.string().nullable(),
+  kycDocumentType: z.nativeEnum(KYCDocumentType).nullable(),
+  kycDocumentIssuer: z.string().nullable(),
+  kycExpirationDate: z.string().nullable(),
+  kycIssuerDate: z.string().nullable(),
+  kycDocumentNumber: z.string().nullable(),
+  kycFirstName: z.string().nullable(),
+  kycLastName: z.string().nullable(),
+  ownership: z.coerce.number().nullable(),
+  householdNetWorth: z.coerce.number().nullable(),
+  liquidNetWorth: z.coerce.number().multipleOf(0.01).nullable(),
+  currentHouseholdIncome: z.coerce.number().nullable(),
+  currentAnnualIncome: z.coerce.number().nullable(),
+  investedInCrowdfunding: z.coerce.number().nullable(),
+  setupStatus: z.nativeEnum(SetupStatusType),
+  setupStep: z.nativeEnum(SetupStepType),
+  sourceOfIncome: z.nativeEnum(SourceOfIncome).nullable(),
+  aicQuestionnaire: z.string().nullable(),
+  kycStatus: z.nativeEnum(KYCStatus),
+  kycProvider: z.string().nullable(),
+  kycTid: z.string().nullable(),
+  aicAccreditationType: z.nativeEnum(AicAccreditationType),
+  accredited: z.boolean(),
+  retirementAccountType: z.nativeEnum(RetirementAccountType).nullable(),
+  custodianName: z.string().nullable(),
+  custodianAccountNumber: z.string().nullable(),
+  custodianRepresentativeName: z.string().nullable(),
+  custodianEmail: z.string().email().nullable(),
+});
+
+export type IndividualResponseType = z.infer<typeof IndividualResponseSchema>;