@dalmore/api-contracts 1.0.5 → 1.0.6

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

@@ -0,0 +1,461 @@
+import { z } from 'zod';
+import { TypeID } from 'typeid-js';
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { IBaseEntity } from './entity.types';
+import {
+  ComplianceReview,
+  FileLabels,
+  FileLabelsEnum,
+  FileStatus,
+  IPaginationMeta,
+  metadataSchema,
+  TargetTableConfig,
+  TargetTableEnum,
+} from './common.types';
+import { KycZod } from './kyc.types';
+import { KybZod } from './kyb.types';
+import { IIndividualZod, individualIdSchema } from './individuals.types';
+import { LegalEntityZod } from './legal-entity.types';
+import { IInvestorAccount } from './investor-account.types';
+import { TradeZod } from './trade.types';
+
+extendZodWithOpenApi(z);
+
+export const allowedFileExtension = [
+  '.pdf',
+  '.doc',
+  '.docx',
+  '.xls',
+  '.xlsx',
+  '.csv',
+  '.gif',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.txt',
+  '.webp',
+  '.html',
+  '.svg',
+];
+
+export enum ADFFileProcessingPipeline {
+  NONE = 'NONE',
+  SUBDOCS_PHOENIX = 'SUBDOCS_PHOENIX',
+  SUBDOCS_GENERAL = 'SUBDOCS_GENERAL',
+  AIC_TAX_RETURNS = 'AIC_TAX_RETURNS',
+  AIC_ACCOUNT_STATEMENTS = 'AIC_ACCOUNT_STATEMENTS',
+  PAY_STUBS = 'PAY_STUBS',
+}
+
+/**
+ * BoldSign brand logo supported file extensions
+ * @see https://developers.boldsign.com/branding/create-brand/?region=us
+ */
+export const boldSignAllowedFileExtension = ['.jpg', '.jpeg', '.png', '.svg'];
+
+export const maxFileSize = 50 * 1024 * 1024; // 50MB
+
+export const fileIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'file';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid file ID format. Must be a valid TypeID with "file" prefix. Example: file_01j5y5ghx8fvc83dmx3pznq7hv',
+  },
+);
+
+export const FileZod = IBaseEntity.extend({
+  id: fileIdSchema,
+  tid: z.string().nullable(),
+  url: z.string().url().openapi({ example: 'https://file-location.com' }),
+  fileType: z.string().openapi({ example: 'pdf' }),
+  fileName: z.string().openapi({ example: 'test.pdf' }),
+  name: z.string().openapi({ example: 'test' }),
+  category: z.string().openapi({ example: 'application' }),
+  label: z.string().openapi({ example: 'other' }),
+  private: z.boolean(),
+  complianceReview: z.nativeEnum(ComplianceReview),
+  targetTable: z.enum(TargetTableEnum).nullable(),
+  targetId: z.string().nullable(),
+  linkedFrom: z.string().nullable(),
+  accountId: z
+    .string()
+    .openapi({ example: 'account_01j6aqmtfyfwy9spjdcnh7yqk7' }),
+  userId: z.string().openapi({ example: 'user_01j6aqmtfyfwy9spjdcnh7yqk7' }),
+  kycs: z.array(KycZod).optional().nullable(),
+  kybs: z.array(KybZod).optional().nullable(),
+  individuals: z.array(IIndividualZod).optional().nullable(),
+  legalEntities: z.array(LegalEntityZod).optional().nullable(),
+  investorAccounts: z.array(IInvestorAccount).optional().nullable(),
+  trades: z.array(TradeZod).optional().nullable(),
+  metadata: z.string().nullable(),
+  status: z.nativeEnum(FileStatus),
+  reviewLog: z.string().nullable(),
+  pipeline: z.nativeEnum(ADFFileProcessingPipeline),
+  errorMessage: z.string().nullable(),
+});
+export type FileZod = z.infer<typeof FileZod>;
+
+export const LinkFileZod = z.object({
+  targetId: z
+    .string()
+    .refine(
+      (value) => {
+        try {
+          const tid = TypeID.fromString(value);
+          return Object.values(TargetTableConfig).some(
+            (config) => config.idPrefix === tid.getType(),
+          );
+        } catch {
+          return false;
+        }
+      },
+      {
+        message: `Invalid target ID format. Must match the corresponding table's ID prefix. Valid prefix: ${TargetTableEnum.toString().toLowerCase()}. Example: disbursement_01j6aqmtfyfwy9spjdcnh7yqk7`,
+      },
+    )
+    .openapi({ example: 'trades_01j6aqmtfyfwy9spjdcnh7yqk7' }),
+  label: FileLabelsEnum.openapi({ example: FileLabels.OTHER }).optional(),
+  category: z.string().min(1).max(50).optional(),
+});
+export type LinkFileZod = z.infer<typeof LinkFileZod>;
+
+export const IPaginatedFile = z.object({
+  items: z.array(FileZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedFile = z.infer<typeof IPaginatedFile>;
+
+export const PatchFile = z.object({
+  name: z.string().max(50),
+  category: z.string().max(50),
+  label: FileLabelsEnum.openapi({ example: FileLabels.OTHER }),
+  metadata: metadataSchema.nullable().optional(),
+});
+export type PatchFile = z.infer<typeof PatchFile>;
+
+export const PostFileQueryParams = z.object({
+  name: z.string().openapi({ example: 'file_name' }),
+  category: z.string().max(50).openapi({ example: 'application' }),
+  label: FileLabelsEnum.openapi({ example: FileLabels.OTHER }),
+  targetId: z
+    .string()
+    .refine(
+      (value) => {
+        try {
+          const tid = TypeID.fromString(value);
+          return Object.values(TargetTableConfig).some(
+            (config) => config.idPrefix === tid.getType(),
+          );
+        } catch {
+          return false;
+        }
+      },
+      {
+        message: `Invalid target ID format. Must match the corresponding table's ID prefix. Valid prefix: ${TargetTableEnum.toString().toLowerCase()}. Example: disbursement_01j6aqmtfyfwy9spjdcnh7yqk7`,
+      },
+    )
+    .openapi({ example: 'trades_01j6aqmtfyfwy9spjdcnh7yqk7' }),
+  metadata: metadataSchema.nullable().optional(),
+});
+export type PostFileQueryParams = z.infer<typeof PostFileQueryParams>;
+
+/**
+ * CLIENT portal specific schema for file uploads
+ * Only allows INDIVIDUALS as target for file uploads
+ */
+export const ClientPostFileQueryParams = z.object({
+  name: z.string().min(1).max(100).openapi({ example: 'file_name' }),
+  category: z.string().max(50).openapi({ example: 'application' }),
+  label: FileLabelsEnum.openapi({ example: FileLabels.OTHER }),
+  targetId: individualIdSchema.openapi({
+    example: 'individual_01kcrsny60fb9rjc8bbqc3b80c',
+  }),
+  metadata: metadataSchema.nullable().optional(),
+});
+export type ClientPostFileQueryParams = z.infer<
+  typeof ClientPostFileQueryParams
+>;
+
+export const FileFilters = z.object({
+  name: z.string().optional(),
+  category: z.string().optional(),
+  label: z.string().optional(),
+  targetId: z.string().optional(),
+  fileType: z.string().optional(),
+  targetTable: z.enum(TargetTableEnum).optional(),
+  includeLinkedFrom: z
+    .string()
+    .optional()
+    .openapi({
+      description:
+        'if false it only returns files that have linkedFrom=null. Defaults to false',
+    })
+    .refine((v) => !v || v === 'true' || v === 'false', {
+      message: 'includeLinkedFrom must be a boolean string',
+    })
+    .transform((v) => {
+      if (!v) return false;
+      return v === 'true';
+    }),
+});
+export const filesInclude = z.enum(['user', 'account']);
+/**
+ * @description Query parameters for including related entities
+ * @xample in contract us as -> query: z.object({}).merge(AccountsIncludeQuery),
+ */
+export const FilesIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          filesInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include option provided. Valid options are: ${filesInclude.options.join(',')}`,
+      },
+    )
+    .openapi({
+      example: `${filesInclude.options.join(',')}`,
+    }),
+  targetTable: z.enum(TargetTableEnum).optional(),
+  targetId: z
+    .string()
+    .optional()
+    .refine(
+      (value) => {
+        try {
+          if (!value) return true;
+          const tid = TypeID.fromString(value);
+          return Object.values(TargetTableConfig).some(
+            (config) => config.idPrefix === tid.getType(),
+          );
+        } catch {
+          return false;
+        }
+      },
+      {
+        message: `Invalid target ID format. Must match the corresponding table's ID prefix. Valid prefix: ${TargetTableEnum.toString().toLowerCase()}. Example: disbursement_01j6aqmtfyfwy9spjdcnh7yqk7`,
+      },
+    ),
+});
+export interface FilesIncludeQuery extends z.infer<typeof FilesIncludeQuery> {}
+
+export const ComplianceFilesIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          filesInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include option provided. Valid options are: ${filesInclude.options.join(',')}`,
+      },
+    )
+    .openapi({
+      example: `${filesInclude.options.join(',')}`,
+    }),
+  targetTable: z.enum(TargetTableEnum).optional(),
+  targetId: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (tradeIds) => {
+        try {
+          if (!tradeIds.length) return true;
+          return tradeIds.every((tradeId) => {
+            const tid = TypeID.fromString(tradeId);
+            return Object.values(TargetTableConfig).some(
+              (config) => config.idPrefix === tid.getType(),
+            );
+          });
+        } catch {
+          return false;
+        }
+      },
+      {
+        message: `Invalid target ID format. Must match the corresponding table's ID prefix. Valid prefix: ${TargetTableEnum.toString().toLowerCase()}. Example: disbursement_01j6aqmtfyfwy9spjdcnh7yqk7`,
+      },
+    ),
+  status: z.nativeEnum(FileStatus).optional(),
+  label: z.nativeEnum(FileLabels).optional(),
+  accountId: z.string().optional(),
+  complianceReview: z.nativeEnum(ComplianceReview).optional(),
+  pipeline: z.nativeEnum(ADFFileProcessingPipeline).optional(),
+});
+export interface ComplianceFilesIncludeQuery
+  extends z.infer<typeof ComplianceFilesIncludeQuery> {}
+
+export const reviewFiles = z.object({
+  complianceReview: z.nativeEnum(ComplianceReview),
+  data: z
+    .array(fileIdSchema)
+    .min(1, 'At least one file is required')
+    .max(50, 'Maximum of 50 files allowed')
+    .openapi({
+      example: [
+        'file_00041061050r3gg28a1c60t3gf',
+        'file_00041061050r3gg28a1c60t3g',
+      ],
+    }),
+});
+export type reviewFiles = z.infer<typeof reviewFiles>;
+
+export const PatchFileMetadata = z.object({
+  corrected: z.record(z.string(), z.unknown()),
+});
+export type PatchFileMetadata = z.infer<typeof PatchFileMetadata>;
+
+/**
+ * Zod schema for file metadata structure
+ * Used to validate the metadata field in File entity
+ */
+export const FileMetadataSchema = z.object({
+  extracted: z
+    .record(z.any())
+    .refine(
+      (data) =>
+        data && typeof data === 'object' && Object.keys(data).length > 0,
+      {
+        message: 'Extracted data is required and cannot be empty',
+      },
+    ),
+  expected: z
+    .record(z.any())
+    .refine(
+      (data) =>
+        data && typeof data === 'object' && Object.keys(data).length > 0,
+      {
+        message: 'Expected data is required and cannot be empty',
+      },
+    ),
+  corrected: z.record(z.any()).optional(),
+});
+export type FileMetadata = z.infer<typeof FileMetadataSchema>;
+
+export enum FilePipeLineReviewAction {
+  SAVE = 'SAVE',
+  REJECTED = 'REJECTED',
+  ACCEPTED = 'ACCEPTED',
+}
+
+export const FilePipeLineReviewSchemaZod = z.object({
+  action: z
+    .nativeEnum(FilePipeLineReviewAction)
+    .optional()
+    .default(FilePipeLineReviewAction.SAVE),
+});
+export type FilePipeLineReviewSchemaZod = z.infer<
+  typeof FilePipeLineReviewSchemaZod
+>;
+
+export const ADFPipelineResponseZod = z.object({
+  extracted: z.record(z.string(), z.unknown()),
+});
+export type ADFPipelineResponseZod = z.infer<typeof ADFPipelineResponseZod>;
+
+export const ReprocessAllFilesZod = z.object({
+  success: z.boolean().openapi({ example: true }),
+  message: z
+    .string()
+    .openapi({ example: 'All files reprocessed successfully' }),
+});
+export type ReprocessAllFilesZod = z.infer<typeof ReprocessAllFilesZod>;
+
+/**
+ * Shared constants for BoldSign form field names.
+ * These constants ensure consistency between:
+ * - BoldSignService.getAllFormFields() - which generates form fields
+ * - getRequiredFieldPatterns() - which validates required fields
+ *
+ * If field names change, update them here to keep both functions in sync.
+ */
+
+/**
+ * Base form field names that are always present
+ */
+export const BOLDSIGN_BASE_FORM_FIELDS = {
+  LEGAL_NAME: 'LegalName',
+  QUANTITY: 'Quantity',
+  TOTAL: 'Total',
+  INVESTOR_TYPE: 'InvestorType',
+  OFFERING_NAME: 'OfferingName',
+  ASSET_NAME: 'AssetName',
+  PRICE_PER_SHARE: 'PricePerShare',
+  ISSUER_NAME: 'IssuerName',
+} as const;
+
+/**
+ * Entity form field name prefixes and suffixes
+ */
+export const ENTITY_FIELD_PREFIX = 'Entity';
+export const ENTITY_FORM_FIELDS = {
+  NAME: 'EntityName',
+  ADDRESS: 'EntityAddress',
+  ADDRESS2: 'EntityAddress2',
+  CITY: 'EntityCity',
+  STATE: 'EntityState',
+  ZIP: 'EntityZip',
+  COUNTRY: 'EntityCountry',
+  FULL_ADDRESS: 'EntityFullAddress',
+  PHONE: 'EntityPhone',
+  TYPE: 'EntityType',
+  EIN: 'EntityEIN',
+  STATE_OF_INCORPORATION: 'EntityStateOfIncorporation',
+  DATE_OF_INCORPORATION: 'EntityDateOfIncorporation',
+} as const;
+
+/**
+ * Signer form field name prefixes and suffixes
+ */
+export const SIGNER_FIELD_PREFIX = 'Signer';
+export const SIGNER_FIELD_SUFFIXES = {
+  NAME: 'Name',
+  EMAIL: 'Email',
+  PHONE: 'Phone',
+  FULL_ADDRESS: 'FullAddress',
+  ADDRESS: 'Address',
+  ADDRESS2: 'Address2',
+  CITY: 'City',
+  STATE: 'State',
+  ZIP: 'Zip',
+  COUNTRY: 'Country',
+  SSN_LAST_4: 'SSNLast4',
+  CITIZENSHIP: 'Citizenship',
+  ACCREDITATION_TYPE: 'AccreditationType',
+  IS_ACCREDITED: 'IsAccredited',
+  DOB: 'DOB',
+} as const;
+
+/**
+ * Helper function to generate signer field name
+ * @param signerIndex - The signer index (1-based)
+ * @param suffix - The field suffix (e.g., 'Name', 'Email')
+ * @returns The complete field name (e.g., 'Signer1Name', 'Signer2Email')
+ */
+export function getSignerFieldName(
+  signerIndex: number,
+  suffix: string,
+): string {
+  return `${SIGNER_FIELD_PREFIX}${signerIndex}${suffix}`;
+}
+/**
+ * Type for all form field names
+ */
+export type FormFieldName =
+  | (typeof BOLDSIGN_BASE_FORM_FIELDS)[keyof typeof BOLDSIGN_BASE_FORM_FIELDS]
+  | (typeof ENTITY_FORM_FIELDS)[keyof typeof ENTITY_FORM_FIELDS]
+  | ReturnType<typeof getSignerFieldName>;

package/src/common/types/files.types.spec.ts

@@ -0,0 +1,154 @@
+import { typeid } from 'typeid-js';
+import {
+  FileZod,
+  allowedFileExtension,
+  fileIdSchema,
+  PostFileQueryParams,
+  FileFilters,
+  ADFFileProcessingPipeline,
+} from './file.types';
+import { FileLabels, FileStatus } from './common.types';
+
+describe('File Validation', () => {
+  describe('fileIdSchema', () => {
+    it('should validate correct file IDs', () => {
+      const validFileId = typeid('file').toString();
+      const result = fileIdSchema.safeParse(validFileId);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject invalid file IDs', () => {
+      const invalidFileIds = [
+        'user_01j5y5ghx8fvc83dmx3pznq7hv',
+        'file_invalid',
+        '',
+      ];
+
+      invalidFileIds.forEach((id) => {
+        const result = fileIdSchema.safeParse(id);
+        expect(result.success).toBe(false);
+      });
+    });
+  });
+
+  describe('FileZod', () => {
+    it('should validate a correct file object', () => {
+      const validFile = {
+        id: typeid('file').toString(),
+        tid: 'some-tid',
+        url: 'https://example.com/file.pdf',
+        fileType: 'pdf',
+        fileName: 'test.pdf',
+        name: 'test',
+        category: 'application',
+        label: FileLabels.OTHER,
+        metadata: null,
+        private: false,
+        complianceReview: 'PENDING',
+        targetTable: 'TRADES',
+        targetId: null,
+        linkedFrom: null,
+        accountId: typeid('account').toString(),
+        userId: typeid('user').toString(),
+        status: FileStatus.PENDING,
+        pipeline: ADFFileProcessingPipeline.NONE,
+        errorMessage: null,
+        reviewLog: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        deletedAt: null,
+      };
+
+      const result = FileZod.safeParse(validFile);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject invalid file objects', () => {
+      const invalidFile = {
+        id: 'invalid_id',
+        url: 'not-a-url',
+        // missing required fields
+      };
+
+      const result = FileZod.safeParse(invalidFile);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('PostFileQueryParams', () => {
+    it('should validate correct query parameters', () => {
+      const validQuery = {
+        name: 'test_file',
+        category: 'application',
+        label: FileLabels.OTHER,
+        targetId: typeid('trade').toString(),
+      };
+
+      const result = PostFileQueryParams.safeParse(validQuery);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject invalid target IDs', () => {
+      const invalidQuery = {
+        name: 'test_file',
+        category: 'application',
+        label: FileLabels.OTHER,
+        targetId: 'invalid_id',
+      };
+
+      const result = PostFileQueryParams.safeParse(invalidQuery);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('FileFilters', () => {
+    it('should handle optional includeLinkedFrom parameter', () => {
+      const validFilters = [
+        { includeLinkedFrom: 'true' },
+        { includeLinkedFrom: 'false' },
+        { includeLinkedFrom: undefined },
+        {},
+      ];
+
+      validFilters.forEach((filter) => {
+        const result = FileFilters.safeParse(filter);
+        expect(result.success).toBe(true);
+      });
+    });
+
+    it('should reject invalid includeLinkedFrom values', () => {
+      const invalidFilters = [
+        { includeLinkedFrom: 'yes' },
+        { includeLinkedFrom: '1' },
+        { includeLinkedFrom: 'TRUE' },
+      ];
+
+      invalidFilters.forEach((filter) => {
+        const result = FileFilters.safeParse(filter);
+        expect(result.success).toBe(false);
+      });
+    });
+  });
+
+  describe('allowedFileExtension', () => {
+    it('should contain all supported extensions', () => {
+      const expectedExtensions = [
+        '.pdf',
+        '.doc',
+        '.docx',
+        '.xls',
+        '.xlsx',
+        '.csv',
+        '.gif',
+        '.png',
+        '.jpg',
+        '.jpeg',
+        '.txt',
+      ];
+
+      expectedExtensions.forEach((ext) => {
+        expect(allowedFileExtension).toContain(ext);
+      });
+    });
+  });
+});

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

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+export const HealthStatusSchema = z.object({
+  status: z.enum(['up', 'down']),
+  message: z.string().optional(),
+});
+export type HealthStatus = z.infer<typeof HealthStatusSchema>;
+
+export const ServiceHealthSchema = z.record(z.string(), HealthStatusSchema);
+export type ServiceHealth = z.infer<typeof ServiceHealthSchema>;
+
+export const HealthCheckResponseSchema = z.object({
+  status: z.enum(['ok', 'error']),
+  details: z
+    .object({
+      status: z.enum(['error', 'ok', 'shutting_down']),
+      info: z.record(z.string(), HealthStatusSchema).optional(),
+      error: z.record(z.string(), HealthStatusSchema).optional(),
+      details: z.record(z.string(), z.any()).optional(),
+    })
+    .optional(),
+});
+export type HealthCheckResponse = z.infer<typeof HealthCheckResponseSchema>;
+
+export const HealthErrorSchema = z.object({
+  status: z.literal('error'),
+  message: z.string().optional(),
+});
+export type HealthError = z.infer<typeof HealthErrorSchema>;

package/src/common/types/index.ts

@@ -0,0 +1,48 @@
+export * from './account.types';
+export * from './account-contact.types';
+export * from './api-keys.types';
+export * from './api-key-logs.types';
+export * from './auth.types';
+export * from './common.types';
+export * from './entity.types';
+export * from './error-responses.types';
+export * from './file.types';
+export * from './individuals.types';
+export * from './invite.types';
+export * from './jobs.types';
+export * from './kyb.types';
+export * from './kyc.types';
+export * from './legal-entity.types';
+export * from './note.types';
+export * from './offering.types';
+export * from './review.types';
+export * from './sms.types';
+export * from './trade.types';
+export * from './user.types';
+export * from './file.types';
+export * from './review.types';
+export * from './issuer-offering.types';
+export * from './covered-person.types';
+export * from './issuer.types';
+export * from './page.types';
+export * from './page-revision.types';
+export * from './login-history.types';
+export * from './offering-submission.types';
+export * from './task.types';
+export * from './secure-request.types';
+export * from './issuer-payment-method.types';
+export * from './site-settings.types';
+export * from './typography.types';
+export * from './contact-us.types';
+export * from './role.types';
+export * from './site-link.types';
+export * from './email-theme.types';
+export * from './disbursements.types';
+export * from './domain-filter.types';
+export * from './aic.types';
+export * from './default-theme-config.types';
+export * from './offering-reports.types';
+
+export enum Versions {
+  V1 = 'v1',
+}