@dalmore/api-contracts 1.0.7 → 1.0.8

package/src/common/types/common.types.ts

@@ -0,0 +1,1520 @@
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { IBaseEntity } from './entity.types';
+import { z } from 'zod';
+import { TypeID } from 'typeid-js';
+import { ErrorHttpStatusCode } from '@ts-rest/core';
+import { TwoFactorMethod } from './sms.types';
+import { normalizeShortDate } from './contract-helpers';
+import { HttpStatus } from '@nestjs/common';
+
+extendZodWithOpenApi(z);
+
+// All possible statuses for the system
+export enum BaseStatus {
+  NEEDS_REVIEW = 'NEEDS_REVIEW',
+  PENDING = 'PENDING',
+  APPROVED = 'APPROVED',
+  REJECTED = 'REJECTED',
+  IN_REVIEW = 'IN_REVIEW',
+  ADDITIONAL_INFO = 'ADDITIONAL_INFO',
+  SUBMITTED = 'SUBMITTED',
+  IN_PROGRESS = 'IN_PROGRESS',
+  CANCELLED = 'CANCELLED',
+  SETTLED = 'SETTLED',
+  REFUNDED = 'REFUNDED',
+  RESUBMIT = 'RESUBMIT',
+  FUNDED = 'FUNDED',
+  COMPLETED = 'COMPLETED',
+  SIGNED = 'SIGNED',
+  DECLINED = 'DECLINED',
+  CART = 'CART',
+  PLACED = 'PLACED',
+  NEEDS_INFO = 'NEEDS_INFO',
+  NEEDS_PAYMENT_INFO = 'NEEDS_PAYMENT_INFO',
+  FUNDING = 'FUNDING',
+  CHARGED = 'CHARGED',
+  NEW = 'NEW',
+  IMPORT_ERROR = 'IMPORT_ERROR',
+  ERROR = 'ERROR',
+  UPDATE_PAYMENT_METHOD = 'UPDATE_PAYMENT_METHOD',
+  RE_SIGN = 'RE_SIGN',
+  RESET_2FA = 'RESET_2FA',
+  FORGOT_PASSWORD = 'FORGOT_PASSWORD',
+  RESET_PASSWORD = 'RESET_PASSWORD',
+  TWO_FACTOR_LOGIN = 'TWO_FACTOR_LOGIN',
+  LOGIN = 'LOGIN',
+  FAILED = 'FAILED',
+  AUTHORIZING = 'AUTHORIZING',
+  VALID = 'VALID',
+  DELETED = 'DELETED',
+  REVOKED = 'REVOKED',
+  WARNING = 'WARNING',
+  READY_TO_APPROVE = 'READY_TO_APPROVE',
+  INCOMPLETE = 'INCOMPLETE',
+  RE_PROCESS = 'RE_PROCESS',
+  INVALID = 'INVALID',
+  NOT_PROCESSED = 'NOT_PROCESSED',
+  PROCESSING = 'PROCESSING',
+  PROCESSING_ERROR = 'PROCESSING_ERROR',
+  REVIEW_ERROR = 'REVIEW_ERROR',
+  PROCESSED = 'PROCESSED',
+  SAVE = 'SAVE',
+  ACCEPTED = 'ACCEPTED',
+  ONBOARDING = 'ONBOARDING',
+  LIVE = 'LIVE',
+  OVERDUE = 'OVERDUE',
+  SUSPENDED = 'SUSPENDED',
+  INACTIVE = 'INACTIVE',
+  PARTIALLY_REFUNDED = 'PARTIALLY_REFUNDED',
+  VOIDED = 'VOIDED',
+  JOIN = 'JOIN',
+  RESTORE = 'RESTORE',
+}
+
+export const UserWithoutPasswordAccountZod = IBaseEntity.extend({
+  firstName: z.string().openapi({ example: 'Daniel' }),
+  lastName: z.string().openapi({ example: 'Ice' }),
+  email: z.string().email().openapi({ example: 'test@test.com' }),
+  provider: z.string().openapi({ example: 'email' }),
+  active: z.boolean().openapi({ example: true }),
+  lastLoginAt: z.date().nullable().openapi({ example: new Date() }),
+  loginCount: z.number().openapi({ example: 1 }),
+  inviteId: z
+    .string()
+    .nullable()
+    .openapi({ example: 'invite_01j1xgme5mfrasd02hmfwsy13a' }),
+  accountId: z
+    .string()
+    .nullable()
+    .openapi({ example: 'account_01j1xgme5mfrasd02hmfwsy13a' }),
+});
+export type UserWithoutPasswordAccountZod = z.infer<
+  typeof UserWithoutPasswordAccountZod
+>;
+export enum ManagedByType {
+  DALMORE = 'DALMORE',
+  ISSUER = 'ISSUER',
+}
+
+export enum Platform {
+  DALMORE = 'DALMORE',
+  INTEGRATION = 'INTEGRATION',
+}
+
+export enum HttpMethod {
+  GET = 'GET',
+  POST = 'POST',
+  PUT = 'PUT',
+  PATCH = 'PATCH',
+  DELETE = 'DELETE',
+  HEAD = 'HEAD',
+  OPTIONS = 'OPTIONS',
+}
+
+export const SENSITIVE_PATTERNS = [
+  /password/i,
+  /credit.*card/i,
+  /ssn/i,
+  /social.*security/i,
+  /token/i,
+  /access.*token/i,
+  /code/i,
+  /apiKey/i,
+  /key/i,
+  /stripeSecretKey/i,
+  /usAccountNumber/i,
+  /recoveryCodes/i,
+  /totpSecret/i,
+  /totpTemporarySecret/i,
+  /smsVerificationCode/i,
+];
+
+export enum AccountStatus {
+  ONBOARDING = BaseStatus.ONBOARDING,
+  LIVE = BaseStatus.LIVE,
+  OVERDUE = BaseStatus.OVERDUE,
+  SUSPENDED = BaseStatus.SUSPENDED,
+  INACTIVE = BaseStatus.INACTIVE,
+}
+// CHANGES TO THIS WILL REQUIRE:
+// - Migrations to update the database
+// - Update to createDefaultIssuerPaymentMethods
+// - Update to existing issuers payment methods, see UpdateIssuerPaymentMethod1755035846643
+// - Updates to TradeFundingTransitionWorker
+export enum PaymentMethodType {
+  CREDIT_CARD = 'CREDIT_CARD',
+  WIRE = 'WIRE',
+  ACH = 'ACH',
+  BANK_ACCOUNT = 'BANK_ACCOUNT',
+  CHECK = 'CHECK',
+  RETIREMENT = 'RETIREMENT',
+}
+
+export const AccountZod = IBaseEntity.extend({
+  name: z.string().openapi({ example: 'Dalmore' }),
+  status: z.nativeEnum(AccountStatus).openapi({ example: AccountStatus.LIVE }),
+  managedBy: z
+    .nativeEnum(ManagedByType)
+    .nullable()
+    .openapi({ example: ManagedByType.DALMORE }),
+  platform: z.nativeEnum(Platform).openapi({ example: Platform.INTEGRATION }),
+  onboardingReviewerId: z
+    .string()
+    .nullable()
+    .openapi({ example: 'user_01j1xgme5mfrasd02hmfwsy13a' }),
+  onboardingReviewAt: z.date().nullable(),
+  allowPendingComplianceReview: z.boolean().openapi({ example: false }),
+});
+export type AccountZod = z.infer<typeof AccountZod>;
+
+export const AccountWithoutUsersZod = IBaseEntity.extend({
+  name: z.string().openapi({ example: 'Dalmore' }),
+  status: z.nativeEnum(AccountStatus).openapi({ example: AccountStatus.LIVE }),
+  managedBy: z
+    .nativeEnum(ManagedByType)
+    .nullable()
+    .openapi({ example: ManagedByType.DALMORE }),
+  platform: z.nativeEnum(Platform).openapi({ example: Platform.INTEGRATION }),
+  onboardingReviewerId: z
+    .string()
+    .nullable()
+    .openapi({ example: 'user_01j1xgme5mfrasd02hmfwsy13a' }),
+  onboardingReviewAt: z.date().nullable(),
+  allowPendingComplianceReview: z.boolean().openapi({ example: false }),
+});
+export type AccountWithoutUsersZod = z.infer<typeof AccountWithoutUsersZod>;
+
+export enum PortalType {
+  COMPLIANCE = 'COMPLIANCE',
+  ISSUER = 'ISSUER',
+  INVESTOR = 'INVESTOR',
+  CLIENT = 'CLIENT',
+  SECONDARIES = 'SECONDARIES',
+  COMPLIANCE_APIKEY = 'COMPLIANCE_APIKEY',
+}
+
+export enum UserType {
+  USER = 'USER',
+  LEAD = 'LEAD',
+  INVESTOR = 'INVESTOR',
+  DEMO = 'DEMO',
+}
+
+export enum UserStatus {
+  ACTIVE = 'ACTIVE',
+  LOCKED = 'LOCKED',
+}
+
+export enum UserRole {
+  API_KEY = 'API_KEY',
+  IMPORT = 'IMPORT',
+  VIEWER = 'VIEWER',
+  SUPPORT = 'SUPPORT',
+  COMPLIANCE = 'COMPLIANCE',
+  ADMIN = 'ADMIN',
+  MARKETER = 'MARKETER',
+  OWNER = 'OWNER',
+  LEGAL = 'LEGAL',
+  COMMUNITY_MANAGER = 'COMMUNITY_MANAGER',
+  ESCROW_AGENT = 'ESCROW_AGENT',
+  AGENT = 'AGENT',
+  ONBOARDING = 'ONBOARDING',
+}
+export enum IssuerRole {
+  VIEWER = 'VIEWER',
+  OWNER = 'OWNER',
+  MARKETER = 'MARKETER',
+  LEGAL = 'LEGAL',
+  COMMUNITY_MANAGER = 'COMMUNITY_MANAGER',
+  COMPLIANCE = 'COMPLIANCE',
+  ADMIN = 'ADMIN',
+  SUPPORT = 'SUPPORT',
+}
+
+export enum FileContainerType {
+  SITE = 'SITE',
+  PRIVATE = 'PRIVATE',
+  PUBLIC = 'PUBLIC',
+  ASSET = 'ASSET',
+}
+export enum UserDataType {
+  LIVE = 'LIVE',
+  TEST = 'TEST',
+}
+// Base interface for role hierarchies
+interface RoleHierarchy {
+  type: PortalType;
+  roles: string[];
+}
+
+export enum AccountContactType {
+  GENERAL = 'GENERAL',
+  INVESTOR = 'INVESTOR',
+  ISSUER = 'ISSUER',
+}
+
+// Configuration for portals and their roles - in order of hierarchy
+export const PortalConfig: Record<PortalType, RoleHierarchy> = {
+  // JWT AUTH
+  [PortalType.COMPLIANCE]: {
+    type: PortalType.COMPLIANCE,
+    roles: [
+      UserRole.IMPORT,
+      UserRole.VIEWER,
+      UserRole.SUPPORT,
+      UserRole.COMPLIANCE,
+      UserRole.ADMIN,
+    ],
+  },
+  [PortalType.ISSUER]: {
+    type: PortalType.ISSUER,
+    roles: [UserRole.MARKETER, UserRole.OWNER],
+  },
+  [PortalType.INVESTOR]: {
+    type: PortalType.INVESTOR,
+    roles: [UserRole.VIEWER, UserRole.OWNER],
+  },
+  // API KEY AUTH
+  [PortalType.CLIENT]: {
+    type: PortalType.CLIENT,
+    roles: [UserRole.API_KEY],
+  },
+  [PortalType.SECONDARIES]: {
+    type: PortalType.SECONDARIES,
+    roles: [UserRole.API_KEY],
+  },
+  [PortalType.COMPLIANCE_APIKEY]: {
+    type: PortalType.COMPLIANCE_APIKEY,
+    roles: [UserRole.API_KEY],
+  },
+};
+
+export const BaseAuthReq = z.object({
+  id: z.string(),
+  accountId: z.string(),
+  isInactiveAccount: z.boolean(),
+  active: z.boolean(),
+  role: z.nativeEnum(UserRole),
+  type: z.nativeEnum(PortalType),
+  roleId: z.string(),
+});
+
+// Regular user type extending base
+export const AuthUserReq = BaseAuthReq.extend({
+  userLoginId: z.string(),
+  firstName: z.string(),
+  lastName: z.string(),
+  email: z.string().email(),
+  provider: z.string(),
+  status: z.lazy(() => z.nativeEnum(UserStatus)),
+  lastLoginAt: z.date().nullable(),
+  loginCount: z.number(),
+  requiresTwoFactorSetup: z.boolean().optional(),
+  twoFactorEnabled: z.boolean().optional(),
+  twoFactorMethod: z.nativeEnum(TwoFactorMethod).optional(),
+  managedBy: z.nativeEnum(ManagedByType).optional(),
+  userType: z.nativeEnum(UserType).optional(),
+});
+
+// API key type extending base
+export const AuthApiKeyReq = BaseAuthReq.extend({
+  name: z.string(),
+  description: z.string().nullable(),
+  lastUsedAt: z.date().nullable(),
+});
+
+export type BaseAuthReq = z.infer<typeof BaseAuthReq>;
+export type AuthUserReq = z.infer<typeof AuthUserReq>;
+export type AuthApiKeyReq = z.infer<typeof AuthApiKeyReq>;
+
+export const UserWithoutPasswordZod = IBaseEntity.extend({
+  firstName: z.string().openapi({ example: 'Daniel' }),
+  lastName: z.string().openapi({ example: 'Ice' }),
+  email: z.string().email().openapi({ example: 'test@test.com' }),
+  provider: z.string().openapi({ example: 'email' }),
+  active: z.boolean().openapi({ example: true }),
+  lastLoginAt: z.date().nullable().openapi({ example: new Date() }),
+  loginCount: z.number().openapi({ example: 1 }),
+  inviteId: z
+    .string()
+    .nullable()
+    .openapi({ example: 'invite_01j1xgme5mfrasd02hmfwsy13a' }),
+  accountId: z
+    .string()
+    .nullable()
+    .openapi({ example: 'account_01j1xgme5mfrasd02hmfwsy13a' }),
+  account: AccountWithoutUsersZod.optional(),
+});
+export type UserWithoutPasswordZod = z.infer<typeof UserWithoutPasswordZod>;
+
+export type ErrorResult = {
+  status: ErrorHttpStatusCode;
+  message: string;
+};
+
+export type ExtendedErrorResult = ErrorResult & {
+  errors?: ErrorResponseZod;
+};
+
+export const IPaginationMeta = z.object({
+  itemCount: z.number().openapi({ example: 1 }),
+  totalItems: z.number().optional().openapi({ example: 10 }),
+  itemsPerPage: z.number().openapi({ example: 1 }),
+  totalPages: z.number().optional().openapi({ example: 10 }),
+  currentPage: z.number().openapi({ example: 1 }),
+});
+export type IPaginationMeta = z.infer<typeof IPaginationMeta>;
+
+export const PaginationOptionsZod = z.object({
+  page: z.coerce
+    .number()
+    .transform((val) => (val === 0 ? 1 : val))
+    .optional()
+    .default(1),
+  limit: z.coerce
+    .number()
+    .transform((val) => (val === 0 ? 10 : val))
+    .optional()
+    .default(10),
+});
+export type PaginationOptionsZod = z.infer<typeof PaginationOptionsZod>;
+
+export interface IPaginationOptions
+  extends z.infer<typeof PaginationOptionsZod> {}
+
+// The base action types for the system
+export enum BaseAction {
+  CREATE = 'CREATE',
+  READ = 'READ',
+  UPDATE = 'UPDATE',
+  DELETE = 'DELETE',
+  IMPORT = 'IMPORT',
+}
+
+export enum KYCStatus {
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  PENDING = BaseStatus.PENDING,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+  CANCELLED = BaseStatus.CANCELLED,
+  RESUBMIT = BaseStatus.RESUBMIT,
+  ERROR = BaseStatus.ERROR,
+}
+export enum AMLStatus {
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  PENDING = BaseStatus.PENDING,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+  ERROR = BaseStatus.ERROR,
+}
+
+export enum AicStatus {
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  PENDING = BaseStatus.PENDING,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+  PROCESSED = BaseStatus.PROCESSED,
+}
+export enum IssuerStatus {
+  REJECTED = BaseStatus.REJECTED,
+  IN_REVIEW = BaseStatus.IN_REVIEW,
+  ADDITIONAL_INFO = BaseStatus.ADDITIONAL_INFO,
+  SUBMITTED = BaseStatus.SUBMITTED,
+  IN_PROGRESS = BaseStatus.IN_PROGRESS,
+  APPROVED = BaseStatus.APPROVED,
+}
+
+export enum KYBStatus {
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  PENDING = BaseStatus.PENDING,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+}
+
+export enum SanctionsStatus {
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  PENDING = BaseStatus.PENDING,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+}
+
+export enum FundingStatus {
+  PENDING = BaseStatus.PENDING,
+  CANCELLED = BaseStatus.CANCELLED,
+  SETTLED = BaseStatus.SETTLED,
+  REFUNDED = BaseStatus.REFUNDED,
+  DECLINED = BaseStatus.DECLINED,
+  FUNDING = BaseStatus.FUNDING,
+  AUTHORIZING = BaseStatus.AUTHORIZING,
+  FAILED = BaseStatus.FAILED,
+}
+
+export enum TxnCheck {
+  PENDING = BaseStatus.PENDING,
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+}
+
+export enum ApprovalStatus {
+  PENDING = BaseStatus.PENDING,
+  FUNDED = BaseStatus.FUNDED,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+  REFUNDED = BaseStatus.REFUNDED,
+}
+
+export enum IraCheck {
+  PENDING = BaseStatus.PENDING,
+  APPROVED = BaseStatus.APPROVED,
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  REJECTED = BaseStatus.REJECTED,
+}
+
+export enum CoveredPersonsStatus {
+  REJECTED = BaseStatus.REJECTED,
+  IN_REVIEW = BaseStatus.IN_REVIEW,
+  IN_PROGRESS = BaseStatus.IN_PROGRESS,
+  COMPLETED = BaseStatus.COMPLETED,
+}
+
+export enum ComplianceReview {
+  PENDING = BaseStatus.PENDING,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  CANCELLED = BaseStatus.CANCELLED,
+  READY_TO_APPROVE = BaseStatus.READY_TO_APPROVE,
+}
+
+export enum KYCDocumentType {
+  PASSPORT = 'PASSPORT',
+  DRIVER_LICENSE = 'DRIVER_LICENSE',
+  STATE_ID = 'STATE_ID',
+}
+
+export enum InvestmentType {
+  INDIVIDUAL = 'INDIVIDUAL',
+  JOINT = 'JOINT',
+  ENTITY = 'ENTITY',
+}
+
+export enum AicAccreditationType {
+  PENDING = 'PENDING',
+  INCOME = 'INCOME',
+  NET_WORTH = 'NET_WORTH',
+  PROFESSIONAL_CERTIFICATION = 'PROFESSIONAL_CERTIFICATION',
+  KNOWLEDGEABLE_EMPLOYEE = 'KNOWLEDGEABLE_EMPLOYEE',
+}
+
+export enum InvestorAccountType {
+  INDIVIDUAL = 'INDIVIDUAL',
+  JOINT = 'JOINT',
+  RETIREMENT = 'RETIREMENT',
+  LEGAL_ENTITY = 'LEGAL_ENTITY',
+}
+
+export enum SetupStatusType {
+  IN_PROGRESS = 'IN_PROGRESS',
+  COMPLETE = 'COMPLETE',
+}
+
+export enum SetupStepType {
+  NEW = 'NEW',
+  PERSONAL_INFO = 'PERSONAL_INFO',
+  ADDRESS = 'ADDRESS',
+  KYC = 'KYC',
+  INCOME = 'INCOME',
+  AIC_QUESTIONS = 'AIC_QUESTIONS',
+  AIC_FILES = 'AIC_FILES',
+}
+
+export enum OfferingType {
+  REG_A = 'REG_A',
+  REG_CF = 'REG_CF',
+  REG_D = 'REG_D',
+  S1 = 'S1',
+  EXCHANGE_NOTE = 'EXCHANGE_NOTE',
+}
+
+export enum AssetType {
+  BOND = 'BOND',
+  STOCK = 'STOCK',
+}
+
+export enum AdjustmentType {
+  CREDIT_CARD_FEES = 'CREDIT_CARD_FEES',
+  SERVICE_CHARGES = 'SERVICE_CHARGES',
+  SUBSCRIPTION_DISCOUNT = 'SUBSCRIPTION_DISCOUNT',
+}
+
+export enum SignatureStatus {
+  PENDING = BaseStatus.PENDING,
+  SIGNED = BaseStatus.SIGNED,
+  DECLINED = BaseStatus.DECLINED,
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  RE_SIGN = BaseStatus.RE_SIGN,
+}
+
+export enum TemplateType {
+  INDIVIDUAL = 'INDIVIDUAL',
+  JOINT = 'JOINT',
+  ENTITY = 'ENTITY',
+  RETIREMENT = 'RETIREMENT',
+  GENERAL = 'GENERAL',
+}
+
+export enum TemplateStatus {
+  PENDING = BaseStatus.PENDING,
+  VALID = BaseStatus.VALID,
+  ERROR = BaseStatus.ERROR,
+}
+
+export enum SenderIdentityStatus {
+  PENDING = BaseStatus.PENDING,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.DECLINED,
+  DELETED = BaseStatus.DELETED,
+  REVOKED = BaseStatus.REVOKED,
+}
+
+export enum DurationType {
+  DAY = 'DAYS',
+  WEEK = 'WEEKS',
+  MONTH = 'MONTHS',
+  YEAR = 'YEARS',
+}
+export enum CoveredPersonsRoleType {
+  ENTITY = 'ENTITY',
+  BOARD_MEMBER = 'BOARD_MEMBER',
+  ADVISOR = 'ADVISOR',
+  CEO = 'CEO',
+  CFO = 'CFO',
+  ACCOUNTING = 'ACCOUNTING',
+  CPA = 'CPA',
+  LEGAL = 'LEGAL',
+  EXECUTIVE = 'EXECUTIVE',
+  EMPLOYEE = 'EMPLOYEE',
+  INVESTOR = 'INVESTOR',
+  PROMOTER = 'PROMOTER',
+  OWNER = 'OWNER',
+  AFFILIATED = 'AFFILIATED',
+}
+export enum IDType {
+  PASSPORT = 'PASSPORT',
+  DRIVERS_LICENSE = 'DRIVERS_LICENSE',
+}
+export enum CoveredPersonType {
+  CHILD = 'CHILD',
+  PARENT = 'PARENT',
+}
+
+export enum CoveredPersonFileLabels {
+  IDENTITY_FRONT = 'IDENTITY_FRONT',
+  IDENTITY_BACK = 'IDENTITY_BACK',
+  BAD_ACTOR_REPORT_FILE = 'BAD_ACTOR_REPORT_FILE',
+}
+
+export enum IdentityFileLabels {
+  IDENTITY_FRONT = 'IDENTITY_FRONT',
+  IDENTITY_BACK = 'IDENTITY_BACK',
+  PASSPORT = 'PASSPORT',
+}
+
+export enum IssuerFileLabels {
+  SS4_LETTER = 'SS4_LETTER',
+  FORMATION_DOCUMENT = 'FORMATION_DOCUMENT',
+  COVER_ART = 'COVER_ART',
+}
+
+export enum OfferingFileLabels {
+  MEMORANDUM = 'MEMORANDUM',
+  SUBSCRIPTION_AGREEMENT = 'SUBSCRIPTION_AGREEMENT',
+  COVER_ART = 'COVER_ART',
+}
+export enum SiteBrandingFileLabels {
+  LOGO = 'LOGO',
+  FAVICON = 'FAVICON',
+  BACKGROUND_IMAGE = 'BACKGROUND_IMAGE',
+}
+
+export enum TradeFileLables {
+  TRADE_DOCUMENT = 'TRADE_DOCUMENT',
+}
+
+export enum RetirementFileLabels {
+  CUSTODIAN_INSTRUCTION_DOCUMENT = 'CUSTODIAN_INSTRUCTION_DOCUMENT',
+}
+export enum AccreditationFileLabels {
+  PROOF_OF_INCOME = 'PROOF_OF_INCOME',
+  PROOF_OF_NET_WORTH = 'PROOF_OF_NET_WORTH',
+  EMPLOYEE = 'EMPLOYEE',
+  TAX_RETURNS = 'TAX_RETURNS',
+  ACCOUNT_STATEMENT = 'ACCOUNT_STATEMENT',
+  ACCREDITATION_LETTER = 'ACCREDITATION_LETTER',
+  LICENSE = 'LICENSE',
+}
+
+export enum OtherFileLabels {
+  OTHER = 'OTHER',
+  COMPLIANCE_REQUEST = 'COMPLIANCE_REQUEST',
+  SUB_DOC = 'SUB_DOC',
+}
+
+export const FileLabels = {
+  ...AccreditationFileLabels,
+  ...CoveredPersonFileLabels,
+  ...OtherFileLabels,
+  ...RetirementFileLabels,
+  ...SiteBrandingFileLabels,
+  ...OfferingFileLabels,
+  ...IssuerFileLabels,
+  ...IdentityFileLabels,
+  ...TradeFileLables,
+} as const;
+
+export type FileLabels = (typeof FileLabels)[keyof typeof FileLabels];
+export const FileLabelsEnum = z.enum(
+  Object.values(FileLabels) as [string, ...string[]],
+);
+
+export enum TradeType {
+  PURCHASE = 'PURCHASE',
+  CONVERSION = 'CONVERSION',
+  TRANSFER = 'TRANSFER',
+}
+export enum TradeStatus {
+  CART = BaseStatus.CART,
+  PLACED = BaseStatus.PLACED,
+  IN_REVIEW = BaseStatus.IN_REVIEW,
+  NEEDS_INFO = BaseStatus.NEEDS_INFO,
+  NEEDS_PAYMENT_INFO = BaseStatus.NEEDS_PAYMENT_INFO,
+  FUNDING = BaseStatus.FUNDING,
+  CANCELLED = BaseStatus.CANCELLED,
+  SETTLED = BaseStatus.SETTLED,
+  IMPORT_ERROR = BaseStatus.IMPORT_ERROR,
+  ERROR = BaseStatus.ERROR,
+  UPDATE_PAYMENT_METHOD = BaseStatus.UPDATE_PAYMENT_METHOD,
+}
+
+export enum SavedQuery {
+  ERROR_REPORT = 'ERROR_REPORT',
+  STUCK_TRADES = 'STUCK_TRADES',
+}
+
+export enum SystemReviewLogTrigger {
+  AML_STATUS_UPDATE = 'AML_STATUS_UPDATE',
+  AIC_STATUS_UPDATE = 'AIC_STATUS_UPDATE',
+  INDIVIDUAL_UPDATE = 'INDIVIDUAL_UPDATE',
+  TRADE_STATUS_UPDATE = 'TRADE_STATUS_UPDATE',
+  KYC_STATUS_UPDATE = 'KYC_STATUS_UPDATE',
+  SUBDOC_STATUS_UPDATE = 'SUBDOC_STATUS_UPDATE',
+  VALIDATE_PLACED_TRADES_WORKER = 'VALIDATE_PLACED_TRADES_WORKER',
+}
+
+export enum OfferingOnboardingStatus {
+  IN_REVIEW = BaseStatus.IN_REVIEW,
+  COMPLETE = BaseStatus.COMPLETED,
+}
+
+export enum ExchangeProvider {
+  PPEX = 'PPEX',
+  PHOENIX = 'PHOENIX',
+  NORTHCAP = 'NORTHCAP',
+}
+
+export enum RunnerType {
+  WORKER = 'WORKER',
+  PIPELINE = 'PIPELINE',
+}
+export enum PublicDataType {
+  DATA_ROOM = 'DATA_ROOM',
+  PAGE = 'PAGE',
+  OFFERING = 'OFFERING',
+}
+
+export enum TrustedContactRelationship {
+  SIBLING = 'SIBLING',
+  GUARDIAN = 'GUARDIAN',
+  CHILD = 'CHILD',
+  FRIEND = 'FRIEND',
+  OTHER = 'OTHER',
+}
+export enum FileStatus {
+  PENDING = BaseStatus.PENDING,
+  ERROR = BaseStatus.ERROR,
+  VALID = BaseStatus.VALID,
+  INVALID = BaseStatus.INVALID,
+  NOT_PROCESSED = BaseStatus.NOT_PROCESSED,
+  PROCESSING = BaseStatus.PROCESSING,
+  PROCESSING_ERROR = BaseStatus.PROCESSING_ERROR,
+  REVIEW_ERROR = BaseStatus.REVIEW_ERROR,
+  PROCESSED = BaseStatus.PROCESSED,
+}
+export enum SystemReviewStatus {
+  PENDING = BaseStatus.PENDING,
+  NEEDS_INFO = BaseStatus.NEEDS_INFO,
+  READY_TO_APPROVE = BaseStatus.READY_TO_APPROVE,
+  NEEDS_REVIEW = BaseStatus.NEEDS_REVIEW,
+  APPROVED = BaseStatus.APPROVED,
+  REJECTED = BaseStatus.REJECTED,
+}
+
+export enum FilingStatus {
+  SINGLE = 'SINGLE',
+  JOINT = 'JOINT',
+}
+export enum AccountType {
+  CHECKING = 'CHECKING',
+  SAVINGS = 'SAVINGS',
+  BROKERAGE = 'BROKERAGE',
+  REAL_ESTATE = 'REAL_ESTATE',
+  OTHER = 'OTHER',
+}
+export enum SourceOfIncome {
+  EMPLOYED = 'EMPLOYED',
+  SELF_EMPLOYED = 'SELF_EMPLOYED',
+  UNEMPLOYED = 'UNEMPLOYED',
+  RETIREMENT = 'RETIREMENT',
+  STUDENT = 'STUDENT',
+}
+
+export enum DateField {
+  RAW_ORDER_CREATED_DATE = 'rawOrder.createdDate',
+  RAW_TRADE_CREATED_DATE = 'rawTrade.createdDate',
+  CREATED_AT = 'createdAt',
+}
+
+export const DateFieldMap = {
+  [DateField.RAW_ORDER_CREATED_DATE]: "raw_order_data->>'createdDate'",
+  [DateField.RAW_TRADE_CREATED_DATE]: "raw_trade_data->>'createdDate'",
+  [DateField.CREATED_AT]: 'entity.createdAt',
+};
+
+/**
+ * Event fields represent database entity columns that can be changed using status.changed events.
+ * These enum values correspond to actual column names in various database entities
+ * and are used to track field-level changes in the system's activity logging.
+ */
+export enum EventField {
+  STATUS = 'status',
+  TRADE_STATUS = 'tradeStatus',
+  FUNDING_STATUS = 'fundingStatus',
+  COMPLIANCE_REVIEW = 'complianceReview',
+  SYSTEM_REVIEW_CHECK = 'systemReviewCheck',
+  SYSTEM_REVIEW = 'systemReview',
+  KYC_STATUS = 'kycStatus',
+  AML_STATUS = 'amlStatus',
+  AIC_STATUS = 'aicStatus',
+  SA_STATUS = 'saStatus',
+  ONBOARDING_STATUS = 'onboardingStatus',
+  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,
+  CHARGED = BaseStatus.CHARGED,
+  APPROVED = BaseStatus.APPROVED,
+  SETTLED = BaseStatus.SETTLED,
+  REFUNDED = BaseStatus.REFUNDED,
+  CANCELLED = BaseStatus.CANCELLED,
+  DECLINED = BaseStatus.DECLINED,
+  FAILED = BaseStatus.FAILED,
+  AUTHORIZING = BaseStatus.AUTHORIZING,
+  FUNDING = BaseStatus.FUNDING,
+  PARTIALLY_REFUNDED = BaseStatus.PARTIALLY_REFUNDED,
+  VOIDED = BaseStatus.VOIDED,
+}
+
+//charge, refund, adjustment
+export enum TransactionType {
+  CHARGE = 'CHARGE',
+  REFUND = 'REFUND',
+  ADJUSTMENT = 'ADJUSTMENT',
+}
+
+const parseDate = (str: string | null): Date | null => {
+  if (!str) return null;
+  const [monthStr, dayStr, yearStr] = str.split('/');
+  const month = Number(monthStr);
+  const day = Number(dayStr);
+  const year = Number(yearStr);
+  if (isNaN(month) || isNaN(day) || isNaN(year)) {
+    return null;
+  }
+  return new Date(year, month - 1, day);
+};
+
+export const dateSchema = z
+  .string()
+  .nullable()
+  .refine(
+    (val) => {
+      if (!val) return true;
+      const regex = /^(0[1-9]|1[0-2])\/(0[1-9]|[12][0-9]|3[01])\/\d{4}$/;
+      return regex.test(val);
+    },
+    { message: 'Date must be in MM/DD/YYYY format' },
+  )
+  .transform((val) => (val ? parseDate(val) : null));
+
+/**
+ * Creates a Zod schema for parsing and transforming date strings in MM/DD/YYYY format.
+ * The schema accepts a parameter to determine if the date should be formatted as the start or end of the day.
+ * - If param is 'START', the time is set to 00:00:00.000 (local, no timezone effect).
+ * - If param is 'END', the time is set to 23:59:59.999 (local, no timezone effect).
+ * - Otherwise, the time is set to 00:00:00.000.
+ * The returned value is a Date object or null.
+ */
+export const createDateSchema = (param?: 'START' | 'END') =>
+  z
+    .string()
+    .nullable()
+    .refine(
+      (val) => {
+        if (!val) return true;
+        const regex = /^(0[1-9]|1[0-2])\/(0[1-9]|[12][0-9]|3[01])\/\d{4}$/;
+        return regex.test(val);
+      },
+      { message: 'Date must be in MM/DD/YYYY format' },
+    )
+    .transform((val) => {
+      if (!val) return null;
+      const [monthStr, dayStr, yearStr] = val.split('/');
+      const month = Number(monthStr);
+      const day = Number(dayStr);
+      const year = Number(yearStr);
+      if (isNaN(month) || isNaN(day) || isNaN(year)) {
+        return null;
+      }
+      let date: Date;
+      if (param === 'END') {
+        // Set to 23:59:59.999 local, then force to end of day in UTC
+        date = new Date(Date.UTC(year, month - 1, day, 23, 59, 59, 999));
+      } else {
+        // Default to START or normal, set to 00:00:00.000 UTC
+        date = new Date(Date.UTC(year, month - 1, day, 0, 0, 0, 0));
+      }
+      return date;
+    });
+
+/**
+ * Default dateSchema (no param) for backward compatibility.
+ */
+export const dateSchemaWithParam = createDateSchema();
+
+export enum IssuerOnboardingSetupType {
+  OFFERING = 'OFFERING',
+  INVESTOR_PORTAL = 'INVESTOR_PORTAL',
+  PAYMENT_METHOD = 'PAYMENT_METHOD',
+  ACCOUNT_CONTACTS = 'ACCOUNT_CONTACTS',
+}
+
+export enum ThemeScope {
+  ACCOUNT = 'ACCOUNT',
+  SYSTEM = 'SYSTEM',
+}
+
+/**
+ * The configuration for the target tables. Used in Notes, Files, and Activities
+ * All tables that need to be targeted should be added here.
+ * to determine the target table from the target ID.
+ * TODO: UPDATE WITH MORE TABLES
+ * CHANGES HERE WILL REQUIRE A MIGRATION
+ */
+export const TargetTableConfig = {
+  KYCS: { table: 'kycs', idPrefix: 'kyc' },
+  AMLS: { table: 'amls', idPrefix: 'aml' },
+  AICS: { table: 'aics', idPrefix: 'aic' },
+  KYBS: { table: 'kybs', idPrefix: 'kyb' },
+  INDIVIDUALS: { table: 'individuals', idPrefix: 'individual' },
+  LEGAL_ENTITIES: { table: 'legal_entities', idPrefix: 'legal_entity' },
+  INVESTOR_ACCOUNTS: {
+    table: 'investor_accounts',
+    idPrefix: 'investor_account',
+  },
+  TRADES: { table: 'trades', idPrefix: 'trade' },
+  OFFERINGS: { table: 'offerings', idPrefix: 'offering' },
+  ISSUERS: { table: 'issuers', idPrefix: 'issuer' },
+  COVERED_PERSONS: { table: 'covered_persons', idPrefix: 'covered_person' },
+  PAYMENT_METHODS: { table: 'payment_methods', idPrefix: 'payment_method' },
+  NOTES: { table: 'notes', idPrefix: 'note' },
+  USERS: { table: 'users', idPrefix: 'user' },
+  ACCOUNTS: { table: 'accounts', idPrefix: 'account' },
+  PAGES: { table: 'pages', idPrefix: 'page' },
+  TASKS: { table: 'tasks', idPrefix: 'task' },
+  FILES: { table: 'files', idPrefix: 'file' },
+  DATA_RECORD_FILES: {
+    table: 'data_record_files',
+    idPrefix: 'data_record_file',
+  },
+  ASSETS: { table: 'assets', idPrefix: 'asset' },
+  SITES: { table: 'sites', idPrefix: 'site' },
+  PAGE_REVISIONS: { table: 'page_revisions', idPrefix: 'page_revision' },
+  TRADE_LINE_ITEMS: { table: 'trade_line_items', idPrefix: 'trade_line_item' },
+  TRANSACTIONS: { table: 'transactions', idPrefix: 'transaction' },
+  DISBURSEMENTS: { table: 'disbursements', idPrefix: 'disbursement' },
+  DISBURSEMENT_REVIEWS: {
+    table: 'disbursement_reviews',
+    idPrefix: 'disbursement_review',
+  },
+  ISSUER_PAYMENT_METHODS: {
+    table: 'issuer_payment_methods',
+    idPrefix: 'issuer_payment_method',
+  },
+  SIGNER_BRANDS: { table: 'signer_brands', idPrefix: 'signer_brand' },
+  THEMES: { table: 'themes', idPrefix: 'theme' },
+  THEME_SETTINGS: { table: 'theme_settings', idPrefix: 'theme_setting' },
+} as const;
+
+export type TargetTableType = keyof typeof TargetTableConfig;
+export const TargetTableEnum = Object.keys(TargetTableConfig) as [
+  TargetTableType,
+  ...TargetTableType[],
+];
+
+/**
+ * Get the target table name from a target ID.
+ * @param targetId - The target ID to get the table name for.
+ * @returns The target table name or null if the target ID is invalid.
+ */
+export function getTargetTableFromId(targetId: string): string | null {
+  try {
+    const tid = TypeID.fromString(targetId);
+    const prefix = tid.getType();
+
+    for (const config of Object.values(TargetTableConfig)) {
+      if (config.idPrefix === prefix) {
+        return config.table;
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+export enum UrlClassification {
+  BASE64 = 'BASE64',
+  REGULAR = 'REGULAR',
+  INVALID = 'INVALID',
+}
+
+export enum OfferingVersioningType {
+  PUBLISHED = 'PUBLISHED',
+  DRAFT = 'DRAFT',
+}
+/**
+ * Get the target table type from a target ID.
+ * @param targetId - The target ID to get the table type for.
+ * @returns The target table type or null if the target ID is invalid.
+ */
+export function getTargetTableTypeFromId(
+  targetId: string,
+): TargetTableType | null {
+  try {
+    const tid = TypeID.fromString(targetId);
+    const prefix = tid.getType();
+
+    for (const [tableType, config] of Object.entries(TargetTableConfig)) {
+      if (config.idPrefix === prefix) {
+        return tableType as TargetTableType;
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+export const REDACTED = '[REDACTED]';
+
+/**
+ * Zod schema for validating and normalizing URLs.
+ *
+ * This schema ensures that the URL is valid and normalizes it by removing the protocol (http/https)
+ * and any path after the main domain.
+ *
+ * @example
+ * UrlSchema.parse('https://www.example.com'); // Valid URL, normalized to 'www.example.com'
+ * UrlSchema.parse('abc.example.org'); // Valid URL, normalized to 'abc.example.org'
+ * UrlSchema.parse('https://subdomain.example.co.uk/path'); // Valid URL, normalized to 'subdomain.example.co.uk'
+ * UrlSchema.parse('ftp://example.com'); // Throws validation error
+ * UrlSchema.parse('invalid-url'); // Throws validation error
+ */
+export const createUrlSchema = (options?: { strict?: boolean }) => {
+  return z
+    .string()
+    .refine(
+      (value) => {
+        try {
+          // If strict mode is enabled, require abc.def.com format (at least one subdomain)
+          const urlPattern = options?.strict
+            ? /^(https?:\/\/)?([a-zA-Z0-9-]+\.[a-zA-Z0-9-]+\.[a-zA-Z]{2,})(\/.*)?$/
+            : /^(https?:\/\/)?(www\.)?([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(\/.*)?$/;
+          return urlPattern.test(value);
+        } catch {
+          return false;
+        }
+      },
+      {
+        message: options?.strict
+          ? 'Invalid URL. Must be in format abc.def.com'
+          : 'Invalid URL',
+      },
+    )
+    .transform((value) => {
+      try {
+        const url = new URL(
+          value.startsWith('http') || value.startsWith('https')
+            ? value
+            : `http://${value}`,
+        );
+        return url.hostname.toLowerCase();
+      } catch {
+        return value.toLowerCase();
+      }
+    })
+    .openapi({
+      example: options?.strict ? 'subdomain.example.com' : 'www.example.com',
+    });
+};
+
+export const UrlSchema = createUrlSchema();
+
+/**
+ * Zod schema for validating subdomains.
+ *
+ * This schema ensures that the subdomain contains only alphanumeric characters and hyphens,
+ * does not start or end with a hyphen, and follows standard subdomain naming conventions.
+ *
+ * @example
+ * SubdomainSchema.parse('my-site'); // Valid subdomain
+ * SubdomainSchema.parse('123test'); // Valid subdomain
+ * SubdomainSchema.parse('my_site'); // Throws validation error (underscore not allowed)
+ * SubdomainSchema.parse('-mysite'); // Throws validation error (cannot start with hyphen)
+ * SubdomainSchema.parse('mysite-'); // Throws validation error (cannot end with hyphen)
+ */
+export const SubdomainSchema = z
+  .string()
+  .min(1, { message: 'Subdomain cannot be empty' })
+  .max(63, { message: 'Subdomain cannot exceed 63 characters' })
+  .refine(
+    (value) => {
+      // Subdomain can only contain alphanumeric characters and hyphens
+      // Cannot start or end with a hyphen
+      const subdomainPattern = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+      return subdomainPattern.test(value);
+    },
+    {
+      message:
+        'Subdomain can only contain letters, numbers, and hyphens, and cannot start or end with a hyphen',
+    },
+  )
+  .transform((value) => value.toLowerCase())
+  .openapi({ example: 'my-site' });
+
+/**
+ * Zod schema for validating domain names without subdomains.
+ *
+ * This schema ensures the domain is in a valid format (example.com) without subdomains.
+ *
+ * @example
+ * DomainSchema.parse('example.com'); // Valid domain
+ * DomainSchema.parse('subdomain.example.com'); // Throws validation error
+ */
+export const DomainSchema = z
+  .string()
+  .refine(
+    (value) => {
+      // Only allow a single dot to prevent subdomains
+      const parts = value.split('.');
+      if (parts.length !== 2) return false;
+
+      // Basic domain format validation
+      const domainPattern = /^[a-zA-Z0-9-]+\.[a-zA-Z]{2,}$/;
+      return domainPattern.test(value);
+    },
+    {
+      message:
+        'Invalid domain format. Must be a domain without subdomains (e.g., example.com)',
+    },
+  )
+  .openapi({ example: 'example.com' });
+
+/**
+ * Zod schema for validating hex color codes (with optional alpha/transparency).
+ *
+ * This schema allows hex codes with or without a leading '#', and accepts 3, 4, 6, 7, or 8 hex digits (e.g., #RRGGBB, #RRGGBBA, #RRGGBBAA, #RGB, #RGBA, #XXXXXXX).
+ * The 7-digit form (e.g., #RRGGBBA) is supported to allow for transparency/alpha values at the end.
+ * It also trims whitespace and lowercases the value.
+ *
+ * @example
+ * HexCodeColorSchema.parse('#FF0000'); // Valid hex code
+ * HexCodeColorSchema.parse('FF0000'); // Valid hex code
+ * HexCodeColorSchema.parse('#F00'); // Valid hex code
+ * HexCodeColorSchema.parse('F00'); // Valid hex code
+ * HexCodeColorSchema.parse('#FF000080'); // Valid hex code (with alpha)
+ * HexCodeColorSchema.parse('#D9D9D14'); // Valid hex code (7 digits, with transparency)
+ * HexCodeColorSchema.parse(' #abc '); // Valid hex code, returns '#abc'
+ * HexCodeColorSchema.parse('#XYZ'); // Throws validation error
+ */
+export const HexCodeColorSchema = z
+  .string()
+  .trim()
+  .transform((val) => (val.startsWith('#') ? val : `#${val}`))
+  .refine(
+    (val) =>
+      /^#[A-Fa-f0-9]{3}$/.test(val) || // #RGB
+      /^#[A-Fa-f0-9]{4}$/.test(val) || // #RGBA
+      /^#[A-Fa-f0-9]{6}$/.test(val) || // #RRGGBB
+      /^#[A-Fa-f0-9]{7}$/.test(val) || // #RRGGBBA (7 digits, e.g., with transparency)
+      /^#[A-Fa-f0-9]{8}$/.test(val), // #RRGGBBAA
+    {
+      message:
+        'Invalid color hex code. It should be 3, 4, 6, 7, or 8 hex digits, with or without a leading "#".',
+    },
+  )
+  .openapi({ example: '#FFA500' });
+
+export const WithCoverArtUrl = z.object({
+  coverArtUrl: z.string().nullable().optional(),
+});
+
+export const UNKNOWN = 'unknown';
+
+export enum UserManualType {
+  FAQ = 'FAQ',
+  USER_MANUAL = 'USER_MANUAL',
+}
+export enum BulkExportType {
+  INVESTOR_ACCOUNTS = 'INVESTOR_ACCOUNTS',
+  TRADES = 'TRADES',
+  COMPLIANCE_TRADES = 'COMPLIANCE_TRADES',
+  SECONDARY_CUSTOMERS = 'SECONDARY_CUSTOMERS',
+  SECONDARY_TRADES = 'SECONDARY_TRADES',
+}
+export const SubmitIssuerOfferingError = z.object({
+  field: z.string(),
+  message: z.string(),
+  id: z.string().optional(),
+});
+export type SubmitIssuerOfferingError = z.infer<
+  typeof SubmitIssuerOfferingError
+>;
+export const ErrorResponseZod = z.object({
+  valid: z.boolean(),
+  errors: z.array(SubmitIssuerOfferingError),
+});
+export type ErrorResponseZod = z.infer<typeof ErrorResponseZod>;
+
+/**
+ * A Zod schema that preprocesses a value to convert it to a number if it is a string.
+ * If the value is a string, it attempts to parse it as a float. If parsing fails, it returns `undefined`.
+ * If the value is already a number, it is returned as is.
+ *
+ * @example
+ * numberFromStringOrNumber.parse("123.45"); // returns 123.45
+ * numberFromStringOrNumber.parse(123.45); // returns 123.45
+ * numberFromStringOrNumber.parse("abc"); // throws a ZodError
+ *
+ * @type {ZodSchema<number>}
+ */
+export const numberFromStringOrNumber = (fieldName: string) =>
+  z.preprocess(
+    (val) => {
+      if (typeof val === 'string') {
+        const parsed = parseFloat(val);
+        return isNaN(parsed) ? undefined : parsed;
+      }
+      return val;
+    },
+    z.number({
+      required_error: `${fieldName} field is required.`,
+      invalid_type_error: `${fieldName} field is required.`,
+    }),
+  );
+
+/**
+ * Creates a Zod schema for transforming number values to a specified decimal precision.
+ * Transforms the number to exactly the specified decimal places without validation.
+ * Accepts a base number schema with constraints (e.g., .positive(), .max()) and applies precision transformation.
+ *
+ * @param precision - The number of decimal places to enforce. Defaults to 2.
+ * @param baseSchema - Optional base number schema with constraints. Defaults to z.number().
+ * @returns A Zod schema that transforms numbers to the specified decimal precision.
+ *
+ * @example
+ * numberPrecisionSchema(2).parse(123.456); // returns 123.46 (transformed)
+ * numberPrecisionSchema(2).parse(123.45); // returns 123.45
+ * numberPrecisionSchema(2).parse(123.4); // returns 123.40 (transformed)
+ * numberPrecisionSchema(3, z.number().positive().max(1000)).parse(500.9999); // returns 501.000 (transformed)
+ * numberPrecisionSchema(2, z.number().positive().max(1000)).parse(500.99); // returns 500.99
+ */
+export const numberPrecisionSchema = (
+  precision: number = 2,
+  baseSchema: z.ZodNumber = z.number(),
+) =>
+  baseSchema.transform((value) => {
+    if (!isFinite(value)) {
+      return value; // Return Infinity or -Infinity as-is
+    }
+
+    if (precision === 0) {
+      return Math.round(value);
+    }
+
+    // Round in two steps to reduce floating-point drift:
+    // 1) trim the value with extra precision
+    // 2) round the trimmed value at the target precision
+    const factor = Math.pow(10, precision);
+
+    // Trim with extra precision (precision + 5) to keep enough significant digits
+    const trimmed = parseFloat(value.toFixed(Math.min(precision + 5, 20)));
+
+    // Round at target precision
+    const rounded = Math.round(trimmed * factor) / factor;
+
+    // Ensure the returned number has exact decimal places
+    return parseFloat(rounded.toFixed(precision));
+  });
+
+/**
+ * Convenience function for 2 decimal precision (backward compatibility).
+ * @deprecated Use numberPrecisionSchema(2) instead.
+ */
+export const amountPrecision2Schema = (baseSchema: z.ZodNumber = z.number()) =>
+  numberPrecisionSchema(2, baseSchema);
+
+export enum RetirementAccountType {
+  SELF_DIRECTED = 'SELF_DIRECTED',
+  CUSTODIAN_MANAGED = 'CUSTODIAN_MANAGED',
+}
+export enum EmploymentStatus {
+  EMPLOYED = 'EMPLOYED',
+  UNEMPLOYED = 'UNEMPLOYED',
+  SELF_EMPLOYED = 'SELF_EMPLOYED',
+  RETIRED = 'RETIRED',
+  STUDENT = 'STUDENT',
+  OTHER = 'OTHER',
+}
+
+export const dateSchemaWithNormalization = z
+  .string()
+  .nullable()
+  .transform((val) => (val ? normalizeShortDate(val) : null))
+  .refine(
+    (val) => {
+      if (!val) return true;
+      const regex = /^(0[1-9]|1[0-2])\/(0[1-9]|[12][0-9]|3[01])\/\d{4}$/;
+      return regex.test(val);
+    },
+    { message: 'Date must be in MM/DD/YYYY format' },
+  )
+  .transform((val) => (val ? parseDate(val) : null));
+
+export const DateRangeFiltersZod = z.object({
+  from: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
+  to: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
+});
+
+export const metadataSchema = z
+  .string()
+  .min(2)
+  .max(600000)
+  .refine(
+    (data) => {
+      try {
+        if (!data) return true;
+        const parsedData = JSON.parse(data);
+        if (typeof parsedData !== 'object' || parsedData === null) return false;
+        return true;
+      } catch (error) {
+        return false;
+      }
+    },
+    {
+      message: 'must be a valid JSON object.',
+      path: [],
+    },
+  )
+  .transform((data) =>
+    data
+      ? { user_defined_data: JSON.parse(data), expected: JSON.parse(data) }
+      : null,
+  );
+
+export const LogContextZod = z.object({
+  queueName: z.string(),
+  jobId: z.string(),
+  jobName: z.string(),
+  shouldAlert: z.boolean().optional(),
+});
+
+export type LogContext = z.infer<typeof LogContextZod>;
+
+/**
+ * Maps all documented Cloudflare Turnstile error codes to their corresponding HTTP status and user-friendly message.
+ *
+ * @see {@link https://developers.cloudflare.com/turnstile/get-started/server-side-validation/ Cloudflare Turnstile Server-side Validation}
+ */
+export const errorMap: Record<string, { status: HttpStatus; message: string }> =
+  {
+    'missing-input-secret': {
+      status: HttpStatus.INTERNAL_SERVER_ERROR,
+      message:
+        'Captcha server configuration is missing the secret key. Please ensure the secret key is included.',
+    },
+    'invalid-input-secret': {
+      status: HttpStatus.INTERNAL_SERVER_ERROR,
+      message:
+        'Captcha server secret key is invalid or expired. Please check your secret key in the Cloudflare dashboard.',
+    },
+    'missing-input-response': {
+      status: HttpStatus.BAD_REQUEST,
+      message:
+        'Captcha response is missing. Please ensure the token is included and try again.',
+    },
+    'invalid-input-response': {
+      status: HttpStatus.BAD_REQUEST,
+      message:
+        'Captcha response is invalid, malformed, or expired. Please retry the challenge.',
+    },
+    'bad-request': {
+      status: HttpStatus.BAD_REQUEST,
+      message:
+        'The captcha verification request was malformed. Please check the request format and parameters.',
+    },
+    'timeout-or-duplicate': {
+      status: HttpStatus.CONFLICT,
+      message:
+        'Captcha token has already been validated or expired. Each token can only be used once. Please refresh and try again.',
+    },
+    'internal-error': {
+      status: HttpStatus.INTERNAL_SERVER_ERROR,
+      message:
+        'An internal error occurred during captcha verification. Please retry the request.',
+    },
+  };
+
+export enum BaseContactUsOptions {
+  ISSUER = 'ISSUER',
+  TECHNICAL_SUPPORT = 'TECHNICAL_SUPPORT',
+  SALES = 'SALES',
+  ACCOUNT_MANAGER = 'ACCOUNT_MANAGER',
+}
+
+export enum SortOrder {
+  ASC = 'ASC',
+  DESC = 'DESC',
+}
+
+export enum SortBy {
+  CREATED_AT = 'created_at',
+  UPDATED_AT = 'updated_at',
+  PLACEDAT = 'placedAt',
+  NAME = 'name',
+  TITLE = 'title',
+  LEGAL_NAME = 'legal_name',
+}
+
+export enum PersonaStatus {
+  APPROVED = 'approved',
+  ACTIVE = 'active',
+  CREATED = 'created',
+  COMPLETED = 'completed',
+  DRAFT = 'draft',
+  DECLINED = 'declined',
+  EXPIRED = 'expired',
+  FAILED = 'failed',
+  NEEDS_REVIEW = 'needs_review',
+  PUBLISHED = 'published',
+  PENDING = 'pending',
+  REDACTED = 'redacted',
+}
+
+export enum AMLProvider {
+  COMPLY_ADVANTAGE = 'ComplyAdvantage',
+}
+
+export enum ThemeFileType {
+  LIGHT = 'light',
+  DARK = 'dark',
+}
+
+/**
+ * Common timezone identifiers using IANA timezone database format.
+ * These are the most commonly used timezones in business applications.
+ */
+export enum TimeZone {
+  // UTC
+  UTC = 'UTC',
+
+  // North America
+  PACIFIC = 'America/Los_Angeles',
+  MOUNTAIN = 'America/Denver',
+  CENTRAL = 'America/Chicago',
+  EASTERN = 'America/New_York',
+
+  // Europe
+  LONDON = 'Europe/London',
+  PARIS = 'Europe/Paris',
+  BERLIN = 'Europe/Berlin',
+  ROME = 'Europe/Rome',
+  MADRID = 'Europe/Madrid',
+  AMSTERDAM = 'Europe/Amsterdam',
+  ZURICH = 'Europe/Zurich',
+
+  // Asia
+  TOKYO = 'Asia/Tokyo',
+  SHANGHAI = 'Asia/Shanghai',
+  HONG_KONG = 'Asia/Hong_Kong',
+  SINGAPORE = 'Asia/Singapore',
+  MUMBAI = 'Asia/Kolkata',
+  DUBAI = 'Asia/Dubai',
+
+  // Australia
+  SYDNEY = 'Australia/Sydney',
+  MELBOURNE = 'Australia/Melbourne',
+
+  // Other major business centers
+  SAO_PAULO = 'America/Sao_Paulo',
+  TORONTO = 'America/Toronto',
+  VANCOUVER = 'America/Vancouver',
+}
+
+export const SenderDataZod = z.object({
+  senderName: z.string().nullable(),
+  senderEmail: z.string().nullable(),
+});
+
+export type SenderDataZod = z.infer<typeof SenderDataZod>;
+
+export enum JobState {
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+  WAITING = 'waiting',
+  ACTIVE = 'active',
+  DELAYED = 'delayed',
+  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',
+};