@dalmore/api-contracts 1.0.0 → 1.0.2

package/common/types/contract-helpers.ts

@@ -0,0 +1,205 @@
+/**
+ * Contract helpers - minimal subset for API contracts package
+ * This file is copied directly to @dalmore/api-contracts
+ */
+import { HttpStatus } from '@nestjs/common';
+import parsePhoneNumberFromString, {
+  CountryCode,
+  PhoneNumber,
+} from 'libphonenumber-js';
+import { err, ok, Result } from 'neverthrow';
+import { ErrorResult } from './common.types';
+
+/**
+ * Validates a US zip code format (12345 or 12345-6789)
+ */
+export const validateUSZipCode = (zipCode: string): boolean => {
+  const regex = /^[0-9]{5}(?:-[0-9]{4})?$/;
+  return regex.test(zipCode);
+};
+
+/**
+ * Validates a Canadian postal code format (A1A 1A1)
+ */
+export const validateCanadaZipCode = (zipCode: string): boolean => {
+  const regex = /^[A-Za-z]\d[A-Za-z] \d[A-Za-z]\d$/;
+  return regex.test(zipCode);
+};
+
+/**
+ * Normalizes a short date string (M/D/YY or M/D/YYYY) to MM/DD/YYYY format
+ */
+export function normalizeShortDate(input: string): string {
+  const [month, day, year] = input.split('/');
+
+  if (!month || !day || !year) {
+    throw new Error('Invalid date format');
+  }
+
+  const paddedMonth = month.padStart(2, '0');
+  const paddedDay = day.padStart(2, '0');
+  const fullYear = year.length === 2 ? `20${year}` : year;
+
+  return `${paddedMonth}/${paddedDay}/${fullYear}`;
+}
+
+/**
+ * Converts a string into a URL-safe slug
+ */
+export function slugify(input: string, exclude: boolean = false): string {
+  if (exclude) {
+    const excludeWords = ['llc', 'inc', 'corp', 'co'];
+    const negativeWordsList = [
+      'www',
+      'api',
+      'admin',
+      'dashboard',
+      'auth',
+      'cdn',
+      'static',
+      'blog',
+      'support',
+      'status',
+      'mail',
+      'smtp',
+      'ftp',
+      'ssh',
+      'login',
+      'register',
+      'signup',
+      'account',
+      'accounts',
+      'user',
+      'users',
+      'profile',
+      'settings',
+      'help',
+      'docs',
+      'documentation',
+      'developer',
+      'developers',
+      'app',
+      'apps',
+      'test',
+      'demo',
+      'staging',
+      'dev',
+      'prod',
+      'production',
+      'beta',
+      'alpha',
+      'portal',
+      'portals',
+      'client',
+      'clients',
+      'investor',
+      'investors',
+      'issuer',
+      'issuers',
+      'compliance',
+      'offering',
+      'offerings',
+      'trade',
+      'trades',
+    ];
+
+    let slug = input
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, '')
+      .replace(/[\s_-]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+
+    excludeWords.forEach((word) => {
+      slug = slug.replace(new RegExp(`-${word}$`, 'i'), '');
+    });
+
+    if (negativeWordsList.includes(slug)) {
+      return 'new-account';
+    }
+
+    return slug;
+  }
+
+  return input
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+type CurlOptions = {
+  query?: Record<string, string>;
+  headers?: Record<string, string>;
+  body?: Record<string, unknown>;
+  formData?: Record<string, string>;
+};
+
+export const authHeader: CurlOptions['headers'] = {
+  Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
+};
+
+const generateCurlExample = (
+  method: string,
+  path: string,
+  options: CurlOptions,
+) => {
+  const baseUrl = 'https://dalmore-client-portal-api-prod.onrender.com/api/v1';
+  let curl = `curl -X ${method.toUpperCase()} '${baseUrl}${path}`;
+  if (options.query) {
+    const queryString = new URLSearchParams(options.query).toString();
+    curl += `?${queryString}`;
+  }
+  curl += "'";
+  if (options.headers) {
+    Object.entries(options.headers).forEach(([key, value]) => {
+      curl += ` \\\n  --header '${key}: ${value}'`;
+    });
+  }
+  if (options.body) {
+    curl += ` \\\n  --header 'Content-Type: application/json'`;
+    curl += ` \\\n  --data '${JSON.stringify(options.body)}'`;
+  }
+  if (options.formData) {
+    Object.entries(options.formData).forEach(([key, value]) => {
+      curl += ` \\\n  --form '${key}=${value}'`;
+    });
+  }
+  return curl;
+};
+
+export const generateApiDescription = (
+  summary: string,
+  method: string,
+  path: string,
+  options: CurlOptions,
+) => {
+  const curlExample = generateCurlExample(method, path, options);
+  return `${summary}
+
+### Example curl request
+
+\`\`\`bash
+${curlExample}
+\`\`\``;
+};
+
+/**
+ * Normalizes a phone number to E.164 format
+ */
+export function normalizePhoneNumber(
+  phoneNumber: string,
+  countryCode: CountryCode,
+): Result<PhoneNumber, ErrorResult> {
+  const parsedPhoneNumber = parsePhoneNumberFromString(
+    phoneNumber,
+    countryCode,
+  );
+
+  if (!parsedPhoneNumber || !parsedPhoneNumber.isValid()) {
+    return err({
+      status: HttpStatus.BAD_REQUEST,
+      message: 'Invalid phone number. Only numbers',
+    });
+  }
+  return ok(parsedPhoneNumber);
+}

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

@@ -27,7 +27,7 @@ import {
 } from './common.types';
 import { accountIdSchema } from './account.types';
 import { SaStatus, tradeIdSchema, TradeZod } from './trade.types';
-import { LegalEntityZod } from './legal-entity.types';
+import { legalEntityIdSchema, LegalEntityZod } from './legal-entity.types';
 import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { offeringIdSchema } from './offering.types';
 import { userIdSchema, UserZod } from './user.types';
@@ -97,6 +97,7 @@ export const IInvestorAccountSummary = z.object({
   totalPending: z.number(),
   concentrationLiquidNetWorth: z.number(),
   concentrationTotalNetWorth: z.number(),
+  postTradeConcentration: z.number().optional(),
 });
 
 export type IInvestorAccountSummary = z.infer<typeof IInvestorAccountSummary>;
@@ -159,24 +160,33 @@ export const InvestorAccountsFiltersZod = z.object({
   amlStatus: z.nativeEnum(AMLStatus).optional(),
   aicStatus: z.nativeEnum(AicStatus).optional(),
   offeringId: z.lazy(() => offeringIdSchema).optional(),
-  regAQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regAQualified must be a boolean string',
-    }),
-  regCfQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regCfQualified must be a boolean string',
-    }),
-  regDQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regDQualified must be a boolean string',
-    }),
+  regAQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
+  regCfQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
+  regDQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
   email: z.string().optional(),
   accountId: accountIdSchema.optional(),
   userType: z.nativeEnum(UserType).optional(),
@@ -222,24 +232,33 @@ export const IssuerInvestorAccountsFiltersZod = z.object({
   amlStatus: z.nativeEnum(AMLStatus).optional(),
   aicStatus: z.nativeEnum(AicStatus).optional(),
   offeringId: z.lazy(() => offeringIdSchema).optional(),
-  regAQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regAQualified must be a boolean string',
-    }),
-  regCfQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regCfQualified must be a boolean string',
-    }),
-  regDQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regDQualified must be a boolean string',
-    }),
+  regAQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
+  regCfQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
+  regDQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
   email: z.string().optional(),
   startDate: dateSchema.optional(),
   endDate: dateSchema.optional(),
@@ -248,37 +267,42 @@ export const IssuerInvestorAccountsFiltersZod = z.object({
 
 export const InvestorAccountsFilters = z.object({
   investorAccountType: z.nativeEnum(InvestorAccountType).optional(),
-  regAQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regAQualified must be a boolean string',
-    }),
-  regCfQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regCfQualified must be a boolean string',
-    }),
-  regDQualified: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'regDQualified must be a boolean string',
-    }),
-  withPortfolio: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'withPortfolio should be boolean',
-    })
-    .transform((withPortfolio) =>
-      withPortfolio === 'true'
+  regAQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
         ? true
-        : withPortfolio === 'false'
+        : val === 'false' || val === '0'
           ? false
-          : undefined,
-    ),
+          : val,
+    z.boolean().optional(),
+  ),
+  regCfQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
+  regDQualified: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
+  withPortfolio: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
 });
 
 export const InvestorAccountExportFilters =
@@ -373,6 +397,42 @@ export type IPaginatedRegisteredInvestorUserZod = z.infer<
   typeof IPaginatedRegisteredInvestorUserZod
 >;
 
+/**
+ * Schema for raw query result from queryRegisteredInvestorUsers
+ * Matches the structure returned by getRawMany() with JSON aggregations.
+ * PostgreSQL/TypeORM automatically parses JSON fields, so they come as arrays.
+ */
+const IndividualAggregationZod = z.object({
+  id: z.lazy(() => individualIdSchema),
+  phone: z.lazy(() => PhoneZodSchema),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+});
+
+const LegalEntityAggregationZod = z.object({
+  id: z.lazy(() => legalEntityIdSchema),
+  phone: z.lazy(() => PhoneZodSchema),
+  name: z.string().nullable(),
+});
+
+export const RegisteredInvestorUserRawZod = z.object({
+  id: z.lazy(() => userIdSchema),
+  name: z.string(),
+  email: z.string().email(),
+  investorAccountType: z.nativeEnum(InvestorAccountType).nullable(),
+  numberOfTrades: z.coerce.number().default(0),
+  invested: z.coerce.number().default(0),
+  createdAt: z.coerce.date(),
+  type: z.nativeEnum(UserType).nullable(),
+  investorAccountId: z.string().nullable(),
+  individuals: z.array(IndividualAggregationZod),
+  legalEntities: z.array(LegalEntityAggregationZod),
+});
+
+export type RegisteredInvestorUserRawZod = z.infer<
+  typeof RegisteredInvestorUserRawZod
+>;
+
 export const RegisteredInvestorUserFiltersZod = z.object({
   search: z.string().optional().openapi({ example: 'John Doe' }),
   startDate: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
@@ -1166,3 +1226,14 @@ export const INVESTOR_ACCOUNT_FIELDS_MAP = {
     ],
   },
 };
+
+export const ExportRegisteredInvestorUsersFiltersZod = z.object({
+  search: z.string().optional(),
+  startDate: dateSchema.optional(),
+  endDate: dateSchema.optional(),
+  userType: z.nativeEnum(UserType).optional(),
+});
+
+export type ExportRegisteredInvestorUsersFiltersZod = z.infer<
+  typeof ExportRegisteredInvestorUsersFiltersZod
+>;

package/common/types/page.types.ts

@@ -14,7 +14,7 @@ import {
   UrlSchema,
 } from './common.types';
 import { accountIdSchema } from './account.types';
-import { slugify } from '../helpers';
+import { slugify } from './contract-helpers';
 import { fileIdSchema } from './file.types';
 
 extendZodWithOpenApi(z);

package/common/types/phone.type.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { normalizePhoneNumber } from '../helpers';
+import { normalizePhoneNumber } from './contract-helpers';
 import { CountryCodes } from './countries.types';
 import { CountryCode } from 'libphonenumber-js';
 import { ok } from 'neverthrow';

package/common/types/queue.types.ts

@@ -1,4 +1,3 @@
-import { JobsOptions } from 'bullmq';
 import { typeid } from 'typeid-js';
 
 export enum QueueFrequency {

package/common/types/secondary-trade.types.ts

@@ -56,6 +56,7 @@ export const SecondaryTradeFiltersZod = z.object({
   complianceReview: z.nativeEnum(ComplianceReview).optional(),
 });
 
+export type SecondaryTradeFiltersZod = z.infer<typeof SecondaryTradeFiltersZod>;
 export const ExportSecondaryTradesResponse = z.object({
   message: z.string(),
 });
@@ -85,3 +86,10 @@ export const IPaginatedSecondaryTradeSummaryResponse = z.object({
 export type IPaginatedSecondaryTradeSummaryResponse = z.infer<
   typeof IPaginatedSecondaryTradeSummaryResponse
 >;
+
+export const CountResultZod = z.array(
+  z.object({
+    count: z.string(),
+  }),
+);
+export type CountResultZod = z.infer<typeof CountResultZod>;

package/common/types/trade.types.ts

@@ -30,7 +30,12 @@ import {
   paymentMethodIdSchema,
   PaymentMethodType,
 } from './payment-methods.types';
-import { investorAccountIdSchema } from './investor-account.types';
+import {
+  investorAccountIdSchema,
+  InvestorAccountExportFilters,
+  ComplianceInvestorAccountExportFilters,
+  RegisteredInvestorUserRawZod,
+} from './investor-account.types';
 import {
   tradeLineItemIdSchema,
   TradeLineItemZod,
@@ -40,6 +45,18 @@ import { TransactionZod } from './transaction.types';
 import { accountIdSchema } from './account.types';
 import { userIdSchema } from './user.types';
 import { issuerIdSchema } from './issuer.types';
+import {
+  GetSecondaryCustomerFiltersZod,
+  SecondaryCustomer,
+} from './secondary-customer.types';
+import {
+  SecondaryTrade,
+  SecondaryTradeFiltersZod,
+} from './secondary-trade.types';
+
+// Stub types for backend entities (not included in contracts package)
+type InvestorAccount = Record<string, unknown>;
+type Trade = Record<string, unknown>;
 
 extendZodWithOpenApi(z);
 export const CheckResultsSchema = z.object({
@@ -107,6 +124,12 @@ export enum TradeSystemLogType {
   KYC_CHECK = 'KYC Check',
   AML_CHECK = 'AML Check',
   AIC_CHECK = 'AIC Check',
+  USER_AGE_CHECK = 'User Age Check',
+  KYC_NAME_CHECK = 'KYC Name Check',
+  AML_NAME_CHECK = 'AML Name Check',
+  AIC_NAME_CHECK = 'AIC Name Check',
+  KYC_DOB_CHECK = 'KYC DOB Check',
+  AIC_SSN_CHECK = 'AIC SSN Check',
   // Data Integrity Checks For Imported Trades
   SHARES_CHECK = 'Shares Check',
   PRICE_PER_UNIT_CHECK = 'Price Per Unit Check',
@@ -447,6 +470,7 @@ export const ExportTradesQuery = PaginationOptionsZod.merge(TradeFiltersZod)
       .optional()
       .default(TradeExportType.PAGE),
   });
+export type ExportTradesQuery = z.infer<typeof ExportTradesQuery>;
 
 const tradesColumn = z.enum([
   'id',
@@ -847,3 +871,61 @@ export const NON_CANCELABLE_COMPLIANCE_REVIEW_STATUSES = [
   ComplianceReview.REJECTED,
   ComplianceReview.CANCELLED,
 ];
+
+/**
+ * Filter type for Investor Account exports in workers
+ * Extends the base InvestorAccountExportFilters with additional optional fields needed for bulk exports
+ */
+export type WorkerInvestorAccountExportFilters = Partial<
+  (InvestorAccountExportFilters | ComplianceInvestorAccountExportFilters) & {
+    isRegisteredUsersExport: boolean | null;
+    search: string | null;
+    startDate: Date | null;
+    endDate: Date | null;
+    userType: string | null;
+    accountId: string | null;
+  }
+>;
+/**
+ * Filter type for Trade exports
+ * Extends IssuersTradeFiltersZod with accountId
+ */
+export type TradeExportFilters = Partial<
+  IssuersTradeFiltersZod & {
+    accountId: string | null;
+  }
+>;
+
+/**
+ * Filter type for Compliance Trade exports
+ */
+export type ComplianceTradeExportFilters = Partial<ExportTradesQuery>;
+
+/**
+ * Filter type for Secondary Customer exports
+ */
+export type SecondaryCustomerExportFilters =
+  Partial<GetSecondaryCustomerFiltersZod>;
+
+/**
+ * Filter type for Secondary Trade exports
+ */
+export type SecondaryTradeExportFilters = Partial<SecondaryTradeFiltersZod>;
+
+/**
+ * Combined filter type for all bulk export types
+ * Used in the ExportBulkDataDto
+ */
+export type BulkExportFilters =
+  | WorkerInvestorAccountExportFilters
+  | TradeExportFilters
+  | ComplianceTradeExportFilters
+  | SecondaryCustomerExportFilters
+  | SecondaryTradeExportFilters;
+
+export type BulkExportResponse =
+  | InvestorAccount[]
+  | RegisteredInvestorUserRawZod[]
+  | Trade[]
+  | SecondaryCustomer[]
+  | SecondaryTrade[];

package/common/types/user.types.ts

@@ -157,6 +157,7 @@ export const UserZod = IBaseEntity.extend({
   onboarding: z.string().nullable(),
   account: AccountWithoutUsersZod.optional(),
   active: z.boolean(),
+  status: z.nativeEnum(UserStatus),
   userLogin: IBaseEntity.extend({
     firstName: z.string(),
     lastName: z.string(),
@@ -284,6 +285,7 @@ export const UsersSummaryFilterZod = z.object({
   portalType: z.nativeEnum(PortalType).optional(),
   search: z.string().trim().max(50).optional(),
   selectRole: z.nativeEnum(UserRole).optional(),
+  status: z.nativeEnum(UserStatus).optional(),
 });
 export type UsersSummaryFilterZod = z.infer<typeof UsersSummaryFilterZod>;
 

package/common/types/zip.type.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { validateCanadaZipCode, validateUSZipCode } from '../helpers';
+import { validateCanadaZipCode, validateUSZipCode } from './contract-helpers';
 import { CountryCode, CountryEnumSchema } from './countries.types';
 
 export function refineAddressZip(

package/contracts/clients/accounts/index.ts

@@ -9,6 +9,7 @@ import {
   AccountsIncludeQuery,
   AccountZod,
   accountIdSchema,
+  InternalError,
 } from '../../../common/types';
 import { z } from 'zod';
 
@@ -32,6 +33,7 @@ export const accountsContract = c.router(
         401: UnauthorizedError,
         403: ForbiddenError,
         404: NotFoundError,
+        500: InternalError,
       },
     },
     getAccounts: {
@@ -49,6 +51,7 @@ export const accountsContract = c.router(
         200: IPaginatedAccount,
         401: UnauthorizedError,
         403: ForbiddenError,
+        500: InternalError,
       },
     },
   },