@dalmore/api-contracts 1.0.5 → 1.0.6

package/src/common/types/issuer-payment-method.types.ts

@@ -0,0 +1,341 @@
+import { TypeID } from 'typeid-js';
+import { z } from 'zod';
+import {
+  PaymentMethodProvider,
+  PaymentMethodType,
+} from './payment-methods.types';
+import { issuerIdSchema, IIssuer } from './issuer.types';
+import { IBaseEntity } from './entity.types';
+import { IPaginationMeta, REDACTED } from './common.types';
+import { StateCode } from './states.types';
+import { CountryCode } from './countries.types';
+import { accountIdSchema } from './account.types';
+import { fileIdSchema } from './file.types';
+
+export const issuerPaymentMethodIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'issuer_payment_method';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: `Invalid issuer_payment_method ID format. Must be a valid TypeID with "issuer_payment_method" prefix. Example: issuer_payment_method_01j5y5ghx5fg68d663j1fvy2x7`,
+  },
+);
+
+export const issuerPaymentMethodIntegrationIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'issuer_payment_method_integration';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: `Invalid issuer_payment_method_integration ID format. Must be a valid TypeID with "issuer_payment_method_integration" prefix. Example: issuer_payment_method_integration_01j5y5ghx5fg68d663j1fvy2x7`,
+  },
+);
+
+export enum IssuerPaymentMethodIntegrationStatus {
+  PENDING = 'PENDING',
+  CONNECTED = 'CONNECTED',
+  DISCONNECTED = 'DISCONNECTED',
+}
+
+export const IssuerPaymentMethodIntegration = IBaseEntity.extend({
+  id: issuerPaymentMethodIntegrationIdSchema,
+  integrationStatus: z
+    .nativeEnum(IssuerPaymentMethodIntegrationStatus)
+    .openapi({
+      example: IssuerPaymentMethodIntegrationStatus.PENDING,
+    }),
+  issuerPaymentMethodId: issuerPaymentMethodIdSchema,
+  integrationAccountId: z.string().nullable(),
+  integrationAccountEmail: z.string().nullable(),
+  integrationAccountLink: z.string().nullable(),
+  integrationAccountLinkExpiresAt: z
+    .union([z.number(), z.string().transform((val) => parseInt(val, 10))])
+    .nullable(), // the reason we need to do this is Unix timestamps stored as BIGINT in PostgreSQL. The value 1759727425634 is likely a Unix timestamp in milliseconds, which exceeds JavaScript's safe integer range, so TypeORM returns it as a string to prevent precision loss.
+});
+export type IssuerPaymentMethodIntegration = z.infer<
+  typeof IssuerPaymentMethodIntegration
+>;
+
+export const IPaginatedIssuerPaymentMethodIntegrations = z.object({
+  items: z.array(IssuerPaymentMethodIntegration),
+  meta: IPaginationMeta,
+});
+export type IPaginatedIssuerPaymentMethodIntegrations = z.infer<
+  typeof IPaginatedIssuerPaymentMethodIntegrations
+>;
+
+export const IIssuerPaymentMethod = IBaseEntity.extend({
+  paymentMethodType: z
+    .nativeEnum(PaymentMethodType)
+    .openapi({ example: PaymentMethodType.CREDIT_CARD }),
+  paymentMethodProvider: z.nativeEnum(PaymentMethodProvider).openapi({
+    example: PaymentMethodProvider.STRIPE,
+  }),
+  enabled: z.boolean().openapi({ example: true }),
+  issuerId: issuerIdSchema.openapi({
+    example: 'issuer_01jdq2crwke8xskjd840cj79pw',
+  }),
+  config: z
+    .any()
+    .transform((config) => {
+      if (!config) return null;
+      const configData =
+        typeof config === 'string' ? JSON.parse(config) : config;
+
+      if (configData.stripeSecretKey) {
+        configData.stripeSecretKey = REDACTED;
+      }
+
+      return configData;
+    })
+    .nullable()
+    .optional(),
+  issuer: IIssuer.optional().nullable(),
+  integration: IssuerPaymentMethodIntegration.nullable().optional(),
+});
+export type IIssuerPaymentMethod = z.infer<typeof IIssuerPaymentMethod>;
+
+export const stripeConfigSchema = z.object({
+  stripeAccountId: z.string().nullable(),
+});
+
+export const wireConfigSchema = z.object({
+  usAccountHolderName: z.string().nullable(),
+  usBankName: z.string().nullable(),
+  usRoutingNumber: z
+    .string()
+    .length(9, { message: 'Routing number must be 9 digits' })
+    .regex(/^\d{9}$/, { message: 'Routing number must be numeric digits' })
+    .nullable(),
+  usAccountNumber: z
+    .string()
+    .min(8, { message: 'Account number must be at least 8 digits' })
+    .max(17, { message: 'Account number must be at most 17 digits' })
+    .regex(/^\d+$/, { message: 'Account number must be numeric digits' })
+    .nullable(),
+  reference: z
+    .string()
+    .min(1, { message: 'Reference must be at least 1 character' })
+    .max(255, { message: 'Reference must be at most 255 characters' })
+    .nullable()
+    .optional(),
+  swiftId: z
+    .string()
+    .min(8, { message: 'Swift ID must be at least 8 characters' })
+    .max(11, { message: 'Swift ID must be at most 11 characters' })
+    .nullable()
+    .optional(),
+});
+export type WireConfig = z.infer<typeof wireConfigSchema>;
+
+export const checkConfigSchema = z.object({
+  companyName: z.string().nullable(),
+  address: z.string().nullable(),
+  address2: z.string().optional().nullable(),
+  city: z.string().nullable(),
+  state: z.nativeEnum(StateCode).nullable().openapi({ example: 'CA' }),
+  zip: z
+    .string()
+    .regex(/^\d{5}$/, {
+      message: 'Invalid ZIP code. It must be a 5-digit number.',
+    })
+    .nullable()
+    .openapi({ example: '90015' }),
+  country: z.nativeEnum(CountryCode).nullable().openapi({ example: 'US' }),
+  reference: z
+    .string()
+    .min(1, { message: 'Reference must be at least 1 character' })
+    .max(255, { message: 'Reference must be at most 255 characters' })
+    .nullable()
+    .optional(),
+});
+
+export type CheckConfig = z.infer<typeof checkConfigSchema>;
+
+export const retirementConfigSchema = z.object({
+  custodianInstruction: z.string().min(1).max(1000).nullable().openapi({
+    example: 'This is a test custodian instruction',
+  }),
+  custodianDocument: z
+    .lazy(() => fileIdSchema)
+    .optional()
+    .nullable(),
+});
+
+export const PatchIssuerPaymentMethodZod = z.discriminatedUnion(
+  'paymentMethodType',
+  [
+    z.object({
+      paymentMethodType: z.literal(PaymentMethodType.CREDIT_CARD),
+      config: stripeConfigSchema,
+    }),
+    z.object({
+      paymentMethodType: z.literal(PaymentMethodType.ACH),
+      config: stripeConfigSchema,
+    }),
+    z.object({
+      paymentMethodType: z.literal(PaymentMethodType.BANK_ACCOUNT),
+      config: stripeConfigSchema,
+    }),
+    z.object({
+      paymentMethodType: z.literal(PaymentMethodType.WIRE),
+      config: wireConfigSchema,
+    }),
+    z.object({
+      paymentMethodType: z.literal(PaymentMethodType.CHECK),
+      config: checkConfigSchema,
+    }),
+    z.object({
+      paymentMethodType: z.literal(PaymentMethodType.RETIREMENT),
+      config: retirementConfigSchema,
+    }),
+  ],
+);
+
+export type PatchIssuerPaymentMethodZod = z.infer<
+  typeof PatchIssuerPaymentMethodZod
+>;
+export const CompliancePatchIssuerPaymentMethodZod = z
+  .object({
+    accountId: accountIdSchema,
+  })
+  .and(PatchIssuerPaymentMethodZod);
+
+export type CompliancePatchIssuerPaymentMethodZod = z.infer<
+  typeof CompliancePatchIssuerPaymentMethodZod
+>;
+
+export const IPaginatedIssuerPaymentMethod = z.object({
+  items: z.array(IIssuerPaymentMethod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedIssuerPaymentMethod = z.infer<
+  typeof IPaginatedIssuerPaymentMethod
+>;
+
+export const GetIssuerPaymentMethodZod = z.object({
+  issuerId: issuerIdSchema.openapi({
+    example: 'issuer_01jdq2crwke8xskjd840cj79pw',
+  }),
+});
+export type GetIssuerPaymentMethodZod = z.infer<
+  typeof GetIssuerPaymentMethodZod
+>;
+
+export const ComplianceGetIssuerPaymentMethodZod =
+  GetIssuerPaymentMethodZod.extend({
+    accountId: accountIdSchema,
+  });
+export type ComplianceGetIssuerPaymentMethodZod = z.infer<
+  typeof ComplianceGetIssuerPaymentMethodZod
+>;
+
+export const PaymentMethodConfig = z.discriminatedUnion('paymentMethodType', [
+  z.object({
+    paymentMethodType: z.literal(PaymentMethodType.CREDIT_CARD),
+    config: stripeConfigSchema,
+  }),
+  z.object({
+    paymentMethodType: z.literal(PaymentMethodType.ACH),
+    config: stripeConfigSchema,
+  }),
+  z.object({
+    paymentMethodType: z.literal(PaymentMethodType.WIRE),
+    config: wireConfigSchema,
+  }),
+  z.object({
+    paymentMethodType: z.literal(PaymentMethodType.CHECK),
+    config: checkConfigSchema,
+  }),
+  z.object({
+    paymentMethodType: z.literal(PaymentMethodType.RETIREMENT),
+    config: retirementConfigSchema,
+  }),
+]);
+
+export type PaymentMethodConfig = z.infer<typeof PaymentMethodConfig>;
+
+export const createDefaultIssuerPaymentMethods = (issuerId: string) => {
+  const paymentMethods = [
+    {
+      paymentMethod: PaymentMethodType.CREDIT_CARD,
+      paymentMethodProvider: PaymentMethodProvider.STRIPE,
+      config: stripeConfigSchema.parse({
+        stripeAccountId: null,
+      }),
+    },
+    {
+      paymentMethod: PaymentMethodType.ACH,
+      paymentMethodProvider: PaymentMethodProvider.STRIPE,
+      config: stripeConfigSchema.parse({
+        stripeAccountId: null,
+      }),
+    },
+    {
+      paymentMethod: PaymentMethodType.BANK_ACCOUNT,
+      paymentMethodProvider: PaymentMethodProvider.STRIPE,
+      config: stripeConfigSchema.parse({
+        stripeAccountId: null,
+      }),
+    },
+    {
+      paymentMethod: PaymentMethodType.WIRE,
+      paymentMethodProvider: PaymentMethodProvider.OTHER,
+      config: wireConfigSchema.parse({
+        usAccountHolderName: null,
+        usBankName: null,
+        usRoutingNumber: null,
+        usAccountNumber: null,
+        reference: null,
+        swiftId: null,
+      }),
+    },
+    {
+      paymentMethod: PaymentMethodType.CHECK,
+      paymentMethodProvider: PaymentMethodProvider.OTHER,
+      config: checkConfigSchema.parse({
+        companyName: null,
+        address: null,
+        address2: null,
+        city: null,
+        state: null,
+        zip: null,
+        country: null,
+        reference: null,
+      }),
+    },
+    {
+      paymentMethod: PaymentMethodType.RETIREMENT,
+      paymentMethodProvider: PaymentMethodProvider.OTHER,
+      config: retirementConfigSchema.parse({
+        custodianInstruction: null,
+        custodianDocument: null,
+      }),
+    },
+  ];
+
+  return paymentMethods.map((paymentMethod) => ({
+    issuerId,
+    paymentMethodType: paymentMethod.paymentMethod,
+    paymentMethodProvider: paymentMethod.paymentMethodProvider,
+    enabled: false,
+    config: JSON.stringify(paymentMethod.config),
+  }));
+};
+
+export const ConnectIssuerPaymentMethodZod = z.object({
+  email: z.string().email(),
+  paymentMethodProvider: z.enum([PaymentMethodProvider.STRIPE]), // Only Stripe is supported for now
+});
+export type ConnectIssuerPaymentMethodZod = z.infer<
+  typeof ConnectIssuerPaymentMethodZod
+>;

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

@@ -0,0 +1,312 @@
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { TypeID } from 'typeid-js';
+import { z } from 'zod';
+import { accountIdSchema } from './account.types';
+import {
+  AccountZod,
+  dateSchema,
+  IPaginationMeta,
+  IssuerStatus,
+  SortBy,
+  SortOrder,
+} from './common.types';
+import { IBaseEntity } from './entity.types';
+import { fileIdSchema, FileZod } from './file.types';
+import { AddressSchema } from './address.types';
+
+extendZodWithOpenApi(z);
+export enum IssuerTypes {
+  LLC = 'LLC',
+  S_CORP = 'S_CORP',
+  C_CORP = 'C_CORP',
+}
+export const issuerIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'issuer';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid issuer ID format. Must be a valid TypeID with "issuer" prefix.',
+  },
+);
+
+const issuersInclude = z.enum(['account', 'offerings', 'coveredPersons']);
+
+/**
+ * @description Query parameters for including related entities
+ * @xample in contract us as -> query: z.object({}).merge(IssuerIncludeQuery),
+ */
+export const IssuersIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          issuersInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include option provided. Valid options are: ${issuersInclude.options.join(',')}`,
+      },
+    )
+    .openapi({
+      example: `${issuersInclude.options.join(',')}`,
+    }),
+});
+
+export const PostIssuerZod = z
+  .object({
+    title: z
+      .string()
+      .min(1)
+      .max(150)
+      .nullable()
+      .optional()
+      .openapi({ example: 'Issuer Title' }),
+    description: z
+      .string()
+      .min(1)
+      .max(1000)
+      .nullable()
+      .optional()
+      .openapi({ example: 'Fund Consulting Services' }),
+    legalName: z.string().min(1).max(100).openapi({ example: 'Fund.co LLC' }),
+    dba: z
+      .string()
+      .min(1)
+      .max(100)
+      .nullable()
+      .optional()
+      .openapi({ example: 'Fund Consulting Services' }),
+    doi: dateSchema.nullable().optional().openapi({ example: 'MM/DD/YYYY' }),
+    ein: z
+      .string()
+      .regex(/^\d{9}$/, {
+        message: 'Invalid EIN format. Must be exactly 9 digits',
+      })
+      .nullable()
+      .optional()
+      .openapi({ example: '123456789' }),
+    type: z.nativeEnum(IssuerTypes).openapi({ example: 'LLC' }),
+  })
+  .and(AddressSchema);
+
+export type PostIssuerZod = z.infer<typeof PostIssuerZod>;
+
+export const CompliancePostIssuerZod = z
+  .object({
+    accountId: accountIdSchema.openapi({
+      accountId: 'account_00041061050r3gg28a1c60t3gf',
+    }),
+  })
+  .and(PostIssuerZod);
+
+export type CompliancePostIssuerZod = z.infer<typeof CompliancePostIssuerZod>;
+
+export const PutIssuerZod = z
+  .object({
+    title: z
+      .string()
+      .min(1)
+      .max(150)
+      .nullable()
+      .optional()
+      .openapi({ example: 'Issuer Title' }),
+    description: z
+      .string()
+      .min(1)
+      .max(1000)
+      .nullable()
+      .optional()
+      .openapi({ example: 'Fund Consulting Services' }),
+    legalName: z
+      .string()
+      .min(1)
+      .max(100)
+      .optional()
+      .openapi({ example: 'Fund.co LLC' }),
+    dba: z
+      .string()
+      .min(1)
+      .max(100)
+      .nullable()
+      .optional()
+      .openapi({ example: 'Fund Consulting Services' }),
+    doi: dateSchema.nullable().optional().openapi({ example: 'MM/DD/YYYY' }),
+    ein: z
+      .string()
+      .regex(/^\d{9}$/, {
+        message: 'Invalid EIN format. Must be exactly 9 digits',
+      })
+      .optional()
+      .nullable()
+      .openapi({ example: '123456789' }),
+    type: z.nativeEnum(IssuerTypes).optional().openapi({ example: 'LLC' }),
+    ss4LetterFileId: z
+      .lazy(() => fileIdSchema)
+      .optional()
+      .nullable(),
+    coverArtId: z
+      .lazy(() => fileIdSchema)
+      .optional()
+      .nullable(),
+  })
+  .and(AddressSchema);
+
+export type PutIssuerZod = z.infer<typeof PutIssuerZod>;
+
+export const IIssuer = IBaseEntity.extend({
+  id: issuerIdSchema,
+  legalName: z.string().nullable().openapi({ example: 'Fund.co LLC' }),
+  dba: z.string().nullable().openapi({ example: 'Fund Consulting Services' }),
+  title: z.string().nullable().openapi({ example: 'Issuer Title' }),
+  description: z
+    .string()
+    .nullable()
+    .openapi({ example: 'Fund Consulting Services' }),
+  ein: z
+    .string()
+    .regex(/^\d{9}$/, {
+      message: 'Invalid EIN format. Must be exactly 9 digits',
+    })
+    .transform((val) => val.replace(/(\d{2})(\d{7})/, '$1-$2'))
+    .nullable()
+    .openapi({ example: '123456789' }),
+  type: z.nativeEnum(IssuerTypes).openapi({ example: 'LLC' }),
+  address: z.string().nullable().openapi({ example: '1234 Main St, Apt 101' }),
+  address2: z.string().nullable().openapi({ example: 'Apt 202' }),
+  city: z.string().nullable().openapi({ example: 'Los Angeles' }),
+  state: z.string().nullable().openapi({ example: 'CA' }),
+  zip: z.string().nullable().openapi({ example: '90015' }),
+  country: z.string().nullable().openapi({ example: 'United States' }),
+  accountId: z.string(),
+  account: AccountZod.optional().nullable(),
+  ss4LetterFileId: z.string().nullable(),
+  status: z
+    .nativeEnum(IssuerStatus)
+    .openapi({ example: IssuerStatus.SUBMITTED }),
+  coverArtId: z.string().nullable(),
+  coverArt: z
+    .lazy(() => FileZod)
+    .nullable()
+    .optional(),
+  doi: z.date().nullable(),
+});
+
+export type IIssuer = z.infer<typeof IIssuer>;
+
+export const IPaginatedIssuer = z.object({
+  items: z.array(IIssuer),
+  meta: IPaginationMeta,
+});
+export type IPaginatedIssuer = z.infer<typeof IPaginatedIssuer>;
+
+export const GetIssuersZod = z.object({
+  accountId: accountIdSchema.optional(),
+  ein: z
+    .string()
+    .regex(/^\d{9}$/, {
+      message: 'Invalid EIN format. Must be exactly 9 digits',
+    })
+    .optional()
+    .openapi({ example: '123456789' }),
+  legalName: z.string().optional().openapi({ example: 'Fund.co LLC' }),
+  type: z
+    .nativeEnum(IssuerTypes)
+    .optional()
+    .openapi({ example: IssuerTypes.C_CORP }),
+  status: z
+    .nativeEnum(IssuerStatus)
+    .optional()
+    .openapi({ example: IssuerStatus.SUBMITTED }),
+});
+
+export type GetIssuersZod = z.infer<typeof GetIssuersZod>;
+
+export enum CatalogMode {
+  CATALOG = 'CATALOG',
+  CATEGORY = 'CATEGORY',
+  PRODUCT = 'PRODUCT',
+}
+
+const CatalogModeSchema = z.object({
+  mode: z.nativeEnum(CatalogMode).optional(),
+});
+
+export const IPaginatedCatalog = z.object({
+  items: z.array(IIssuer),
+  meta: IPaginationMeta.merge(CatalogModeSchema),
+});
+
+export const GetIssuersSummaryZod = z.object({
+  accountId: accountIdSchema.optional(),
+  issuerId: issuerIdSchema.optional(),
+  coveredPersons: z.number(),
+  offerings: z.number(),
+  assets: z.number(),
+});
+export type GetIssuersSummaryZod = z.infer<typeof GetIssuersSummaryZod>;
+
+export const IPaginatedIssersSummary = z.object({
+  items: z.array(GetIssuersSummaryZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedIssersSummary = z.infer<typeof IPaginatedIssersSummary>;
+
+export const IssuersSummaryFilterZod = z.object({
+  accountId: accountIdSchema.optional(),
+  issuerId: issuerIdSchema.optional(),
+  search: z.string().optional(),
+});
+export type IssuersSummaryFilterZod = z.infer<typeof IssuersSummaryFilterZod>;
+
+export const IssuersSortZod = z.object({
+  sort: z
+    .enum([SortBy.LEGAL_NAME, SortBy.CREATED_AT, SortBy.UPDATED_AT])
+    .optional(),
+  dir: z.nativeEnum(SortOrder).optional(),
+});
+export type IssuersSortZod = z.infer<typeof IssuersSortZod>;
+
+/**
+ * Schema for transforming EIN (Employer Identification Number) formats.
+ *
+ * This schema validates and transforms a 9-digit EIN by inserting a hyphen after
+ * the first two digits (XX-XXXXXXX format). If the input doesn't match the expected
+ * 9-digit pattern, the original value is returned unchanged.
+ *
+ * The schema uses passthrough to allow additional fields in the object without validation,
+ * making it flexible for use with various data structures that include an EIN.
+ *
+ * @example
+ * // Transforms: { ein: '123456789' } -> { ein: '12-3456789' }
+ * // Keeps as-is: { ein: '12-3456789' } -> { ein: '12-3456789' }
+ */
+export const EinTransformerSchema = z
+  .object({
+    ein: z
+      .string()
+      .nullable()
+      .optional()
+      .transform((val) => {
+        // Only apply transformation if it matches the regex pattern
+        if (val && /^\d{9}$/.test(val)) {
+          return val.replace(/(\d{2})(\d{7})/, '$1-$2');
+        }
+        // Otherwise return the original value
+        return val;
+      })
+      .openapi({ example: '123456789' }),
+  })
+  .passthrough(); // Allow additional fields without validation
+
+export const PaginatedEinTransformerSchema = z.object({
+  items: z.array(EinTransformerSchema),
+  meta: IPaginationMeta,
+});