@dalmore/api-contracts 1.0.0 → 1.0.2

package/common/helpers/index.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 '../types/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/account-manager.types.ts

@@ -112,3 +112,13 @@ export const SetDefaultAccountManagerForAllAccountsResponse = z.object({
 export type SetDefaultAccountManagerForAllAccountsResponse = z.infer<
   typeof SetDefaultAccountManagerForAllAccountsResponse
 >;
+
+export const AccountManagerDeleteQuery = z.object({
+  reassignTo: accountManagerIdSchema
+    .nullable()
+    .optional()
+    .openapi({ example: 'account_manager_01j5y5ghx5fg68d663j1fvy2x7' }),
+});
+export type AccountManagerDeleteQuery = z.infer<
+  typeof AccountManagerDeleteQuery
+>;

package/common/types/account.types.ts

@@ -47,7 +47,7 @@ export const UpdateAccountZod = z.object({
 export type UpdateAccountZod = z.infer<typeof UpdateAccountZod>;
 
 export const CreateAccountZod = z.object({
-  name: z.string().min(1).max(100),
+  name: z.string().min(1).max(100).openapi({ example: 'Name' }),
   platform: z
     .nativeEnum(Platform)
     .optional()
@@ -56,7 +56,14 @@ export const CreateAccountZod = z.object({
     .nativeEnum(ManagedByType)
     .optional()
     .openapi({ example: ManagedByType.DALMORE }),
-  approversCount: z.number().min(1).max(5).optional(),
+  approversCount: z.number().min(1).max(5).optional().openapi({ example: 2 }),
+  hubspotCompany: z
+    .string()
+    .url()
+    .max(2048)
+    .nullable()
+    .optional()
+    .openapi({ example: 'https://www.google.com' }),
 });
 export type CreateAccountZod = z.infer<typeof CreateAccountZod>;
 
@@ -135,6 +142,19 @@ export const PatchAccountZod = z.object({
 });
 export type PatchAccountZod = z.infer<typeof PatchAccountZod>;
 
+export const CompliancePatchAccountZod = PatchAccountZod.extend({
+  hubspotCompany: z
+    .string()
+    .url()
+    .max(2048)
+    .nullable()
+    .optional()
+    .openapi({ example: 'https://www.google.com' }),
+});
+export type CompliancePatchAccountZod = z.infer<
+  typeof CompliancePatchAccountZod
+>;
+
 export const PostAccountResponse = z.object({
   id: z.string(),
 });
@@ -166,6 +186,41 @@ export const AccountsSummaryFilterZod = z.object({
   status: z.nativeEnum(AccountStatus).optional(),
   from: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
   to: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
+  accountManagerIds: z
+    .string()
+    .optional()
+    .transform((val) => {
+      if (!val || typeof val !== 'string') return undefined;
+
+      const ids = val
+        .split(',')
+        .map((id: string) => id.trim())
+        .filter((id: string) => id.length > 0);
+
+      // Remove duplicates using Set
+      const uniqueIds = [...new Set(ids)];
+
+      return uniqueIds.length > 0 ? uniqueIds : undefined;
+    })
+    .pipe(
+      z
+        .array(
+          z.string().refine(
+            (value) => {
+              try {
+                const tid = TypeID.fromString(value);
+                return tid.getType() === 'account_manager';
+              } catch {
+                return false;
+              }
+            },
+            {
+              message: `Invalid account manager ID format. Must be a valid TypeID with "account_manager" prefix. Example: account_manager_01j5y5ghx5fg68d663j1fvy2x7`,
+            },
+          ),
+        )
+        .optional(),
+    ),
 });
 export type AccountsSummaryFilterZod = z.infer<typeof AccountsSummaryFilterZod>;
 
@@ -182,6 +237,8 @@ export const AccountsSummaryZod = z.object({
   offerings: z.number().int(),
   assets: z.number().int(),
   users: z.number().int(),
+  trades: z.number().int(),
+  accountManagerName: z.string(),
   createdOn: z.string(),
   status: z.string(),
 });

package/common/types/activity.types.ts

@@ -134,6 +134,8 @@ export enum ActivityTypeAction {
   RE_PROCESS = BaseStatus.RE_PROCESS,
   SAVE = BaseStatus.SAVE,
   ACCEPTED = BaseStatus.ACCEPTED,
+  JOIN = BaseStatus.JOIN,
+  RESTORE = BaseStatus.RESTORE,
 }
 
 export const MethodMap: { [key: string]: ActivityTypeAction } = {
@@ -215,6 +217,9 @@ export const ActivitiesFilters = z.object({
   targetId: z
     .string()
     .optional()
+    .openapi({
+      example: 'disbursement_01j6aqmtfyfwy9spjdcnh7yqk7',
+    })
     .refine(
       (value) => {
         try {
@@ -232,5 +237,38 @@ export const ActivitiesFilters = z.object({
       },
     ),
   search: z.string().max(50).optional(),
+  targetIds: z
+    .string()
+    .optional()
+    .openapi({
+      example:
+        'disbursement_01j6aqmtfyfwy9spjdcnh7yqk7,disbursement_01j6aqmtfyfwy9spjdcnh7yqk8',
+    })
+    .transform((str) => {
+      if (!str) return [];
+      // Split by comma, trim whitespace, and remove duplicates using Set
+      const ids = str.split(',').map((id) => id.trim());
+      return Array.from(new Set(ids));
+    })
+    .refine(
+      (value) => {
+        if (!value || value.length === 0) return true;
+
+        // Validate each ID
+        return value.every((id) => {
+          try {
+            const tid = TypeID.fromString(id);
+            return Object.values(TargetTableConfig).some(
+              (config) => config.idPrefix === tid.getType(),
+            );
+          } catch {
+            return false;
+          }
+        });
+      },
+      {
+        message: `Invalid target IDs. All IDs must match the corresponding table's ID prefix. Valid prefix: ${TargetTableEnum.toString().toLowerCase()}. Example: disbursement_01j6aqmtfyfwy9spjdcnh7yqk7`,
+      },
+    ),
 });
 export type ActivitiesFilters = z.infer<typeof ActivitiesFilters>;

package/common/types/asset.types.ts

@@ -53,6 +53,7 @@ export const IAsset = IBaseEntity.extend({
     .nullable(), // Use z.lazy here
   template: z.nativeEnum(TemplateType),
   tiers: z.array(z.number().positive()).nullable(),
+  enableBonus: z.boolean(),
 });
 
 export type IAsset = z.infer<typeof IAsset>;
@@ -105,6 +106,7 @@ const PostAssetBase = z.object({
     .default(TemplateType.STANDARD)
     .openapi({ example: TemplateType.STANDARD }),
   tiers: z.array(z.number().positive()).nullable().optional(),
+  enableBonus: z.boolean().default(false).openapi({ example: false }),
 });
 
 const postAssetRefinement = (data: any, ctx: any) => {
@@ -237,6 +239,7 @@ export const PutAsset = z.object({
     .nullable()
     .optional(),
   tiers: z.array(z.number().positive()).nullable().optional(),
+  enableBonus: z.boolean().optional().openapi({ example: false }),
 });
 
 export type PutAsset = z.infer<typeof PutAsset>;

package/common/types/auth.types.ts

@@ -49,14 +49,14 @@ const BaseAuthBody = z.object({
   firstName: z
     .string()
     .min(2, 'firstName is less than 2 characters')
-    .max(20, 'firstName is more than 2 characters')
+    .max(20, 'firstName is more than 20 characters')
     .openapi({
       example: 'Neil',
     }),
   lastName: z
     .string()
     .min(2, 'lastName is less than 2 characters')
-    .max(20, 'lastName is more than 2 characters')
+    .max(20, 'lastName is more than 20 characters')
     .openapi({
       example: 'Armstrong',
     }),
@@ -201,7 +201,8 @@ export const AccessTokenResponse = z.object({
 });
 export type AccessTokenResponse = z.infer<typeof AccessTokenResponse>;
 
-export const IRegisterIssuerBodyZod = BaseAuthBody.extend({
+// Base schema for issuer registration (shared fields without refinements)
+const BaseRegisterIssuerFields = BaseAuthBody.extend({
   confirmPassword: PasswordSchema,
   accountName: z
     .string()
@@ -212,6 +213,17 @@ export const IRegisterIssuerBodyZod = BaseAuthBody.extend({
     })
     .nullable()
     .optional(),
+  accountType: z
+    .nativeEnum(ManagedByType)
+    .optional()
+    .default(ManagedByType.DALMORE)
+    .openapi({
+      example: ManagedByType.DALMORE,
+    }),
+});
+
+// Full issuer registration schema with code (for invite-based registration)
+export const IRegisterIssuerBodyZod = BaseRegisterIssuerFields.extend({
   code: z
     .string()
     .refine(isBase64, {
@@ -221,13 +233,6 @@ export const IRegisterIssuerBodyZod = BaseAuthBody.extend({
     .openapi({
       example: 'eyJpdiI6InhhTFIyVG9ETnhnUzQ1QzUyNzRJenc9PSIsI',
     }),
-  accountType: z
-    .nativeEnum(ManagedByType)
-    .optional()
-    .default(ManagedByType.DALMORE)
-    .openapi({
-      example: ManagedByType.DALMORE,
-    }),
 })
   .refine((data) => data.password === data.confirmPassword, {
     message: 'Passwords do not match',
@@ -252,6 +257,28 @@ export const IRegisterIssuerBodyZod = BaseAuthBody.extend({
     },
   );
 
+// Client issuer registration schema without code (for API key registration)
+export const IRegisterClientIssuerBodyZod = BaseRegisterIssuerFields.refine(
+  (data) => data.password === data.confirmPassword,
+  {
+    message: 'Passwords do not match',
+    path: ['confirmPassword'],
+  },
+).refine(
+  (data) => {
+    // For client registration, accountName is always required
+    return (
+      data.accountName !== null &&
+      data.accountName !== undefined &&
+      data.accountName !== ''
+    );
+  },
+  {
+    message: 'Account name is required',
+    path: ['accountName'],
+  },
+);
+
 // Investors are a special case in which they require phone number at the time of registration
 // The phone number provided here is NOT validated and will still need to go thru the regular 2FA setup process
 export const RegisterBodyInvestors = BaseAuthBody.extend({

package/common/types/batch-jobs.types.ts

@@ -5,7 +5,6 @@ import { dateSchema, IPaginationMeta, UserRole } from './common.types';
 import { userIdSchema } from './user.types';
 import { accountIdSchema } from './account.types';
 import { IBaseEntity } from './entity.types';
-import { JobsOptions } from 'bullmq';
 
 extendZodWithOpenApi(z);
 

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

@@ -66,6 +66,9 @@ export const IBonusTier = IBaseEntity.extend({
   endAmount: z.number().nullable(),
 });
 
+export const IBonusTierList = z.array(IBonusTier);
+export type IBonusTierList = z.infer<typeof IBonusTierList>;
+
 export const EstimateBonusTierCalculationZod = z
   .object({
     assetId: assetIdSchema
@@ -113,3 +116,32 @@ export const EstimateBonusTierCalculationResponseZod = z.object({
 export type EstimateBonusTierCalculationResponseZod = z.infer<
   typeof EstimateBonusTierCalculationResponseZod
 >;
+export type IBonusTier = z.infer<typeof IBonusTier>;
+export const BonusTierListZod = z
+  .array(
+    z.object({
+      type: z.nativeEnum(BonusType).openapi({ example: BonusType.PERCENTAGE }),
+      value: z.number().positive().int().max(1000000).openapi({ example: 50 }),
+      startAmount: z.number().max(999999999).openapi({ example: 100 }),
+      endAmount: z.number().max(999999999).openapi({ example: 200 }),
+    }),
+  )
+  .min(1, { message: 'At least one bonus tier is required' });
+export type BonusTierListZod = z.infer<typeof BonusTierListZod>;
+
+export const PostBonusTierZod = z.object({
+  assetId: assetIdSchema.openapi({
+    example: 'asset_00041061050r3gg28a1c60t3gf',
+  }),
+  bonusTiers: BonusTierListZod,
+});
+
+export type PostBonusTierZod = z.infer<typeof PostBonusTierZod>;
+
+export const CompliancePostBonusTierZod = PostBonusTierZod.extend({
+  accountId: accountIdSchema,
+});
+
+export type CompliancePostBonusTierZod = z.infer<
+  typeof CompliancePostBonusTierZod
+>;

package/common/types/common.types.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { TypeID } from 'typeid-js';
 import { ErrorHttpStatusCode } from '@ts-rest/core';
 import { TwoFactorMethod } from './sms.types';
-import { normalizeShortDate } from '../helpers';
+import { normalizeShortDate } from './contract-helpers';
 import { HttpStatus } from '@nestjs/common';
 
 extendZodWithOpenApi(z);
@@ -67,6 +67,8 @@ export enum BaseStatus {
   INACTIVE = 'INACTIVE',
   PARTIALLY_REFUNDED = 'PARTIALLY_REFUNDED',
   VOIDED = 'VOIDED',
+  JOIN = 'JOIN',
+  RESTORE = 'RESTORE',
 }
 
 export const UserWithoutPasswordAccountZod = IBaseEntity.extend({
@@ -809,6 +811,15 @@ export enum EventField {
   TRANSACTION_STATUS = 'transactionStatus',
 }
 
+export enum EventName {
+  STATUS_CHANGED = 'status.changed',
+  UPDATE_FIELD = 'update.field',
+  ACTION_PERFORMED = 'action.performed',
+  PENDING_OVERDUE_TRADES_ALERT = 'pending_overdue.trades.alert',
+  IN_REVIEW_TRADES_ALERT = 'trade.inreview.alert',
+  INDIVIDUAL_AML_STATUS_CHANGED = 'individual.aml_status.changed',
+}
+
 // pending charged settled refunded cancelled
 export enum TransactionStatus {
   PENDING = BaseStatus.PENDING,
@@ -1499,3 +1510,11 @@ export enum JobState {
   PRIORITIZED = 'prioritized',
   WAITING_CHILDREN = 'waiting-children',
 }
+
+export const SUBJECT_TYPE_MAP: Record<BulkExportType, string> = {
+  [BulkExportType.INVESTOR_ACCOUNTS]: 'Investor Accounts',
+  [BulkExportType.TRADES]: 'Trades',
+  [BulkExportType.COMPLIANCE_TRADES]: 'Compliance Trades',
+  [BulkExportType.SECONDARY_CUSTOMERS]: 'Secondary Customers',
+  [BulkExportType.SECONDARY_TRADES]: 'Secondary Trades',
+};