@dalmore/api-contracts 0.0.0-dev.0c67bc1

package/common/types/offering.types.ts

@@ -0,0 +1,681 @@
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { TypeID } from 'typeid-js';
+import { z } from 'zod';
+import { accountIdSchema } from './account.types';
+import {
+  AccountZod,
+  ComplianceReview,
+  dateSchema,
+  IPaginationMeta,
+  OfferingType,
+  ManagedByType,
+  PaginationOptionsZod,
+  UrlSchema,
+  SortOrder,
+  SortBy,
+  OfferingVersioningType,
+  OfferingOnboardingStatus,
+  AssetType,
+  DurationType,
+} from './common.types';
+import { IBaseEntity } from './entity.types';
+import { fileIdSchema, FileZod } from './file.types';
+import { IIssuer, issuerIdSchema } from './issuer.types';
+import {
+  InvestorsOfferingFiltersZod,
+  InvestorsOfferingsIncludeQuery,
+} from './investors-offering.types';
+import { OfferingStatus } from './issuer-offering.types';
+import { postAssetRefinement, AssetTemplateType } from './asset.types';
+
+export enum OfferingFeeType {
+  FIXED = 'FIXED',
+  PERCENTAGE = 'PERCENTAGE',
+}
+
+extendZodWithOpenApi(z);
+
+export const offeringIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'offering';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: `Invalid offering ID format. Must be a valid TypeID with "offering" prefix. Example: offering_01j5y5ghx5fg68d663j1fvy2x7`,
+  },
+);
+export const offeringRevisionIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'offering_revision';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: `Invalid offering revision ID format. Must be a valid TypeID with "offering_revision" prefix. Example: offering_revision_01j5y5ghx5fg68d663j1fvy2x7`,
+  },
+);
+
+export const OfferingPlatformSettings = z.object({
+  backOfficePortal: z.string(),
+  username: z.string().nullable(),
+  password: z.string().nullable(),
+  apiKey: z.string().nullable(),
+});
+export type OfferingPlatformSettings = z.infer<typeof OfferingPlatformSettings>;
+
+export const IOffering = IBaseEntity.extend({
+  name: z.string(),
+  tid: z.string().nullable(),
+  type: z.nativeEnum(OfferingType).nullable(),
+  description: z.string().nullable(),
+  raiseAmount: z.number().nullable(),
+  targetAmount: z.number().nullable(),
+  minInvestment: z.number().nullable(),
+  maxInvestment: z.number().nullable(),
+  contingencyAmount: z.number().nullable(),
+  startAt: z.date().nullable(),
+  endAt: z.date().nullable(),
+  platform: z.string(),
+  platformSettings: z.string().nullable(),
+  enabled: z.boolean(),
+  accountId: z.string().nullable(),
+  account: AccountZod.optional().nullable(),
+  issuer: z
+    .lazy(() => IIssuer)
+    .optional()
+    .nullable(), // Use z.lazy here
+  issuerId: z.string().nullable(),
+  coverArtId: z
+    .lazy(() => fileIdSchema)
+    .nullable()
+    .optional(),
+  coverArt: z.lazy(() => FileZod).nullable(),
+  cancellationPeriod: z.number().nullable(),
+  memorandumId: z
+    .lazy(() => fileIdSchema)
+    .nullable()
+    .optional(),
+  subscriptionAgreementId: z
+    .lazy(() => fileIdSchema)
+    .nullable()
+    .optional(),
+  managedBy: z.nativeEnum(ManagedByType).nullable(),
+  valuationCap: z.number().nullable(),
+  showTotalRaised: z.boolean().optional(),
+});
+export type IOffering = z.infer<typeof IOffering>;
+
+export const IPaginatedOffering = z.object({
+  items: z.array(IOffering),
+  meta: IPaginationMeta,
+});
+export type IPaginatedOffering = z.infer<typeof IPaginatedOffering>;
+
+export const PatchOfferingBase = z.object({
+  name: z.string().optional(),
+  description: z.string().nullable().optional(),
+  tid: z.string().optional(),
+  type: z.nativeEnum(OfferingType).optional(),
+  targetAmount: z.number().min(0.01).max(10000000000).optional(),
+  raiseAmount: z
+    .number()
+    .min(0.01)
+    .max(10000000000)
+    .openapi({ example: 5000 })
+    .optional(),
+  minInvestment: z
+    .number()
+    .min(0.01)
+    .max(10000000000)
+    .openapi({ example: 5000 })
+    .optional()
+    .nullable(),
+  maxInvestment: z
+    .number()
+    .min(0.01)
+    .max(10000000000)
+    .openapi({ example: 5000 })
+    .optional()
+    .nullable(),
+  contingencyAmount: z
+    .number()
+    .min(0.0)
+    .max(10000000000)
+    .openapi({ example: 5000 })
+    .optional()
+    .nullable(),
+  startAt: dateSchema.optional().openapi({ example: '10/20/2024' }),
+  endAt: dateSchema.optional().openapi({ example: '10/27/2024' }),
+  platform: z.string().optional(),
+  coverArtId: z
+    .lazy(() => fileIdSchema)
+    .nullable()
+    .optional(),
+  platformSettings: OfferingPlatformSettings.optional().transform((val) =>
+    val ? JSON.stringify(val) : null,
+  ),
+  enabled: z.boolean().optional(),
+  entitySubscriptionAgreementTemplateId: z.string().optional().nullable(),
+  managedBy: z.nativeEnum(ManagedByType).optional(),
+  subscriptionAgreementTemplateId: z.string().optional().nullable(),
+  memorandumId: z
+    .lazy(() => fileIdSchema)
+    .nullable()
+    .optional(),
+  subscriptionAgreementId: z
+    .lazy(() => fileIdSchema)
+    .nullable()
+    .optional(),
+  jointSubscriptionAgreementTemplateId: z.string().optional().nullable(),
+  cancellationPeriod: z.number().min(2).max(5).optional().nullable(),
+  showTotalRaised: z.boolean().optional(),
+  issuerId: issuerIdSchema.optional(),
+});
+export const PatchOffering = PatchOfferingBase.merge(
+  z.object({
+    assetName: z
+      .string()
+      .min(2)
+      .max(50)
+      .optional()
+      .openapi({ example: 'Asset name' }),
+    assetType: z
+      .nativeEnum(AssetType)
+      .optional()
+      .openapi({ example: AssetType.STOCK }),
+    pricePerUnit: z
+      .number()
+      .min(0.01)
+      .max(10000000000)
+      .nullable()
+      .optional()
+      .openapi({ example: 2000 }),
+    totalUnits: z
+      .number()
+      .min(1)
+      .max(10000000000)
+      .nullable()
+      .optional()
+      .openapi({ example: 5200 }),
+    yield: z
+      .number()
+      .min(0.01)
+      .max(10000000000)
+      .nullable()
+      .optional()
+      .openapi({ example: 1200 }),
+    duration: z
+      .number()
+      .min(1)
+      .max(1000)
+      .nullable()
+      .optional()
+      .openapi({ example: 1 }),
+    durationType: z
+      .nativeEnum(DurationType)
+      .nullable()
+      .optional()
+      .openapi({ example: DurationType.DAY }),
+    template: z
+      .nativeEnum(AssetTemplateType)
+      .default(AssetTemplateType.STANDARD)
+      .openapi({ example: AssetTemplateType.STANDARD })
+      .nullable()
+      .optional(),
+    tiers: z.array(z.number().positive()).nullable().optional(),
+  }),
+);
+export type PatchOffering = z.infer<typeof PatchOffering>;
+
+export const PostComplianceOffering = PatchOfferingBase.merge(
+  z.object({
+    accountId: accountIdSchema,
+    managedBy: z.nativeEnum(ManagedByType).optional(),
+    assetName: z.string().min(2).max(50).openapi({ example: 'Asset name' }),
+    assetType: z.nativeEnum(AssetType).openapi({ example: AssetType.STOCK }),
+    pricePerUnit: z
+      .number()
+      .min(0.01)
+      .max(10000000000)
+      .nullable()
+      .openapi({ example: 2000 }),
+    totalUnits: z
+      .number()
+      .min(1)
+      .max(10000000000)
+      .nullable()
+      .openapi({ example: 5200 }),
+    yield: z
+      .number()
+      .min(0.01)
+      .max(10000000000)
+      .nullable()
+      .optional()
+      .openapi({ example: 1200 }),
+    duration: z
+      .number()
+      .min(1)
+      .max(1000)
+      .nullable()
+      .optional()
+      .openapi({ example: 1 }),
+    durationType: z
+      .nativeEnum(DurationType)
+      .nullable()
+      .optional()
+      .openapi({ example: DurationType.DAY }),
+    template: z
+      .nativeEnum(AssetTemplateType)
+      .default(AssetTemplateType.STANDARD)
+      .openapi({ example: AssetTemplateType.STANDARD }),
+    tiers: z.array(z.number().positive()).nullable().optional(),
+  }),
+).superRefine(postAssetRefinement);
+export type PostComplianceOffering = z.infer<typeof PostComplianceOffering>;
+
+export const offeringsInclude = z.enum([
+  'account',
+  'issuer',
+  'trades',
+  'assets',
+  'disbursements',
+  'draftVersion',
+  'publishedVersion',
+  'revisions',
+  'onboardingReviewedBy',
+]);
+
+/**
+ * @description Query parameters for including related entities
+ * @xample in contract us as -> query: z.object({}).merge(UsersIncludeQuery),
+ */
+export const OfferingsIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          offeringsInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include option provided. Valid options are: ${offeringsInclude.options.join(',')}`,
+      },
+    )
+    .openapi({
+      example: `${offeringsInclude.options.join(',')}`,
+    }),
+});
+
+export interface OfferingsIncludeQuery
+  extends z.infer<typeof OfferingsIncludeQuery> {}
+
+/**
+ * @description
+ * Filters for querying offerings.
+ *
+ * The "combinedStatus" filter provides a unified status that combines three separate fields:
+ * - complianceReview: The compliance review status of the offering
+ * - onboardingStatus: The onboarding completion status
+ * - enabled: Whether the offering is currently enabled/active
+ *
+ * The combinedStatus is calculated using the following priority rules:
+ * 1. If onboardingStatus is "IN_REVIEW" → combinedStatus = "ONBOARDING"
+ * 2. Else if complianceReview is not "APPROVED" → combinedStatus = "IN_COMPLIANCE_REVIEW"
+ * 3. Else if onboardingStatus is "COMPLETE" and complianceReview is "APPROVED" →
+ *    - If enabled is true → combinedStatus = "ACTIVE"
+ *    - If enabled is false → combinedStatus = "PAUSED"
+ *
+ * This allows for filtering offerings by a single summary state that reflects the overall user-facing status,
+ * rather than requiring separate filters for each individual field.
+ */
+export const OfferingFiltersZod = z.object({
+  issuerName: z.string().optional(),
+  name: z.string().optional(),
+  accountId: accountIdSchema.optional(),
+  issuerId: z.lazy(() => issuerIdSchema).optional(),
+  type: z.nativeEnum(OfferingType).optional(),
+  status: z.nativeEnum(ComplianceReview).optional(),
+  enabled: z.preprocess(
+    (val) =>
+      val === 'true' || val === '1'
+        ? true
+        : val === 'false' || val === '0'
+          ? false
+          : val,
+    z.boolean().optional(),
+  ),
+  managedBy: z.nativeEnum(ManagedByType).optional(),
+  versioningType: z.nativeEnum(OfferingVersioningType).optional(),
+  combinedStatus: z.nativeEnum(OfferingStatus).optional(),
+  onboardingStatus: z.nativeEnum(OfferingOnboardingStatus).optional(),
+});
+export type OfferingFiltersZod = z.infer<typeof OfferingFiltersZod>;
+
+export const OfferingSortZod = z.object({
+  sort: z.enum([SortBy.NAME, SortBy.CREATED_AT, SortBy.UPDATED_AT]).optional(),
+  dir: z.nativeEnum(SortOrder).optional(),
+});
+export type OfferingSortZod = z.infer<typeof OfferingSortZod>;
+
+export const OfferingSummaryFiltersZod = z.object({
+  accountId: accountIdSchema.optional(),
+  hasPendingTrades: z.coerce.boolean().optional(),
+});
+export type OfferingSummaryFiltersZod = z.infer<
+  typeof OfferingSummaryFiltersZod
+>;
+
+export const OfferingSummaryResponseZod = z.object({
+  id: offeringIdSchema,
+  name: z.string(),
+  account: z.object({ id: accountIdSchema, name: z.string() }),
+  trades: z.object({
+    total: z.number(),
+    tradeReview: z.number(),
+    readyForDisbursement: z.number(),
+  }),
+});
+export type OfferingSummaryResponse = z.infer<
+  typeof OfferingSummaryResponseZod
+>;
+
+export const PaginatedOfferingSummaryResponseZod = z.object({
+  items: z.array(OfferingSummaryResponseZod),
+  meta: IPaginationMeta,
+});
+export type PaginatedOfferingSummaryResponse = z.infer<
+  typeof PaginatedOfferingSummaryResponseZod
+>;
+
+const BaseOfferingSettings = z.object({
+  settingsBrokerageFeeValue: z.number().nonnegative().nullable().optional(),
+  settingsBrokerageFeeType: z.nativeEnum(OfferingFeeType).nullable().optional(),
+  settingsCardFeeValue: z.number().nonnegative().nullable().optional(),
+  settingsCardFeeType: z.nativeEnum(OfferingFeeType).nullable().optional(),
+  settingsDisbursementFeeValue: z.number().nonnegative().nullable().optional(),
+  settingsDisbursementFeeType: z
+    .nativeEnum(OfferingFeeType)
+    .nullable()
+    .optional(),
+  settingsRefundPoolFeeValue: z.number().nonnegative().nullable().optional(),
+  settingsRefundPoolFeeType: z
+    .nativeEnum(OfferingFeeType)
+    .nullable()
+    .optional(),
+  serviceChargesType: z.nativeEnum(OfferingFeeType).nullable().optional(),
+  serviceCharges: z.number().nonnegative().nullable().optional(),
+});
+
+export const OfferingSettings = BaseOfferingSettings.refine(
+  (data) =>
+    (data.settingsBrokerageFeeType === null &&
+      data.settingsBrokerageFeeValue === null) ||
+    (data.settingsBrokerageFeeType !== null &&
+      data.settingsBrokerageFeeValue !== null),
+  {
+    message:
+      'settingsBrokerageFeeType and settingsBrokerageFeeValue must both be either null or not-null',
+  },
+)
+  .refine(
+    (data) =>
+      (data.serviceChargesType === null && data.serviceCharges === null) ||
+      (data.serviceChargesType !== null && data.serviceCharges !== null),
+    {
+      message:
+        'serviceChargesType and serviceCharges must both be either null or not-null',
+    },
+  )
+  .refine(
+    (data) =>
+      (data.settingsCardFeeType === null &&
+        data.settingsCardFeeValue === null) ||
+      (data.settingsCardFeeType !== null && data.settingsCardFeeValue !== null),
+    {
+      message:
+        'settingsCardFeeType and settingsCardFeeValue must both be either null or not-null',
+    },
+  )
+  .refine(
+    (data) =>
+      (data.settingsDisbursementFeeType === null &&
+        data.settingsDisbursementFeeValue === null) ||
+      (data.settingsDisbursementFeeType !== null &&
+        data.settingsDisbursementFeeValue !== null),
+    {
+      message:
+        'settingsDisbursementFeeType and settingsDisbursementFeeValue must both be either null or not-null',
+    },
+  )
+  .refine(
+    (data) =>
+      (data.settingsRefundPoolFeeType === null &&
+        data.settingsRefundPoolFeeValue === null) ||
+      (data.settingsRefundPoolFeeType !== null &&
+        data.settingsRefundPoolFeeValue !== null),
+    {
+      message:
+        'settingsRefundPoolFeeType and settingsRefundPoolFeeValue must both be either null or not-null',
+    },
+  )
+  .refine(
+    (data) =>
+      data.settingsBrokerageFeeType !== OfferingFeeType.PERCENTAGE ||
+      (data.settingsBrokerageFeeValue !== null &&
+        data.settingsBrokerageFeeValue! <= 100),
+    {
+      message: 'settingsBrokerageFeeValue must be less than or equal to 100',
+    },
+  )
+  .refine(
+    (data) =>
+      data.settingsRefundPoolFeeType !== OfferingFeeType.PERCENTAGE ||
+      (data.settingsRefundPoolFeeValue !== null &&
+        data.settingsRefundPoolFeeValue! <= 100),
+    {
+      message: 'settingsRefundPoolFeeValue must be less than or equal to 100',
+    },
+  )
+  .refine(
+    (data) =>
+      data.settingsCardFeeType !== OfferingFeeType.PERCENTAGE ||
+      (data.settingsCardFeeValue !== null && data.settingsCardFeeValue! <= 100),
+    {
+      message: 'settingsCardFeeValue must be less than or equal to 100',
+    },
+  )
+  .refine(
+    (data) =>
+      data.settingsDisbursementFeeType !== OfferingFeeType.PERCENTAGE ||
+      (data.settingsDisbursementFeeValue !== null &&
+        data.settingsDisbursementFeeValue! <= 100),
+    {
+      message: 'settingsDisbursementFeeValue must be less than 100',
+    },
+  );
+
+export type OfferingSettings = z.infer<typeof OfferingSettings>;
+
+export const PatchComplianceOffering = z
+  .intersection(PatchOffering, OfferingSettings)
+  .refine(
+    (data) => {
+      // Check if both values are present, and if so, ensure minInvestment is less than maxInvestment
+      if (data.minInvestment && data.maxInvestment) {
+        return data.minInvestment < data.maxInvestment;
+      }
+      return true; // If one or both values are undefined, skip this check
+    },
+    {
+      message: 'Minimum investment must be less than maximum investment.',
+      path: ['minInvestment'],
+    },
+  );
+export type PatchComplianceOffering = z.infer<typeof PatchComplianceOffering>;
+
+export const IComplianceOffering = z.intersection(IOffering, OfferingSettings);
+export type IComplianceOffering = z.infer<typeof IComplianceOffering>;
+
+export const IPaginatedComplianceOffering = z.object({
+  items: z.array(IComplianceOffering),
+  meta: IPaginationMeta,
+});
+export type IPaginatedComplianceOffering = z.infer<
+  typeof IPaginatedComplianceOffering
+>;
+
+export const ReviewOfferings = z.object({
+  complianceReview: z.enum([
+    ComplianceReview.APPROVED,
+    ComplianceReview.REJECTED,
+  ]),
+  offerings: z
+    .array(offeringIdSchema)
+    .min(1, 'At least one offering is required')
+    .max(50, 'Maximum of 50 offerings allowed')
+    .openapi({
+      example: [
+        'offering_01jjsdrx1seqfse7z4z47sgdp5',
+        'offering_01jjsdrx27enkszq5cnc3hdhrf',
+      ],
+    }),
+});
+export type ReviewOfferings = z.infer<typeof ReviewOfferings>;
+
+export const OfferingDetailsResponseZod = z.object({
+  raisedAmount: z.number(),
+  investors: z.number().int(),
+  minInvestment: z.number(),
+  maxInvestment: z.number(),
+  valuationCap: z.number(),
+  targetAmount: z.number(),
+});
+
+export type OfferingDetailsResponseZod = z.infer<
+  typeof OfferingDetailsResponseZod
+>;
+
+export const OfferingsArrayQueryZod = z.object({
+  offerings: z
+    .string()
+    .optional()
+    .transform((val) => {
+      if (!val) return undefined;
+      return val.split(',').map((id) => id.trim());
+    })
+    .pipe(
+      z
+        .array(z.string())
+        .optional()
+        .refine(
+          (val) => {
+            if (!val) return true;
+            return val.every((id) => {
+              try {
+                const tid = TypeID.fromString(id);
+                return tid.getType() === 'offering';
+              } catch {
+                return false;
+              }
+            });
+          },
+          {
+            message:
+              'Invalid offering IDs format. Must be a valid TypeID with "offering" prefix.',
+          },
+        ),
+    ),
+});
+
+export const OfferingRaiseAmountResponseZod = z.object({
+  offeringId: offeringIdSchema,
+  totalRaisedAmount: z.number(),
+});
+export type OfferingRaiseAmountResponseZod = z.infer<
+  typeof OfferingRaiseAmountResponseZod
+>;
+
+export const PublicOfferingFiltersZod = PaginationOptionsZod.merge(
+  InvestorsOfferingsIncludeQuery,
+)
+  .merge(InvestorsOfferingFiltersZod)
+  .extend({
+    url: UrlSchema,
+  });
+
+export type PublicOfferingFiltersZod = z.infer<typeof PublicOfferingFiltersZod>;
+
+export const PendingOfferingSummaryResponseZod = z.object({
+  id: offeringIdSchema,
+  name: z.string(),
+  assets: z.number(),
+  issuerName: z.string(),
+  issuerId: z.string(),
+  accountName: z.string(),
+  accountId: z.string(),
+  targetAmount: z.number().nullable(),
+  startAt: z.date().nullable(),
+  offeringType: z.nativeEnum(OfferingType),
+});
+export type PendingOfferingSummaryResponse = z.infer<
+  typeof PendingOfferingSummaryResponseZod
+>;
+
+export const PaginatedPendingOfferingSummaryResponseZod = z.object({
+  items: z.array(PendingOfferingSummaryResponseZod),
+  meta: IPaginationMeta,
+});
+export type PaginatedPendingOfferingSummaryResponse = z.infer<
+  typeof PaginatedPendingOfferingSummaryResponseZod
+>;
+
+export type OfferingUpdateFields = {
+  managedBy?: ManagedByType | null;
+  showTotalRaised?: boolean;
+  enabled?: boolean;
+};
+
+export const ReviewOfferingOnboarding = z.object({
+  onboardingStatus: z.nativeEnum(OfferingOnboardingStatus),
+});
+export type ReviewOfferingOnboarding = z.infer<typeof ReviewOfferingOnboarding>;
+
+export const OnboardingOfferingSummaryZod = z.object({
+  accountId: accountIdSchema,
+  accountName: z.string(),
+  offeringName: z.string(),
+  offeringId: z.string(),
+  memorandumId: z.string().nullable(),
+  subscriptionAgreementId: z.string().nullable(),
+  subscriptionAgreementTemplateId: z.string().nullable(),
+  jointSubscriptionAgreementTemplateId: z.string().nullable(),
+  entitySubscriptionAgreementTemplateId: z.string().nullable(),
+});
+export type OnboardingOfferingSummaryZod = z.infer<
+  typeof OnboardingOfferingSummaryZod
+>;
+
+export const OnboardingOfferingSummaryFilterZod = z.object({
+  search: z.string().optional(),
+  offeringId: offeringIdSchema.optional(),
+});
+export type OnboardingOfferingSummaryFilterZod = z.infer<
+  typeof OnboardingOfferingSummaryFilterZod
+>;
+
+export const IPaginatedOnboardingOfferingSummaryResponse = z.object({
+  items: z.array(OnboardingOfferingSummaryZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedOnboardingOfferingSummaryResponse = z.infer<
+  typeof IPaginatedOnboardingOfferingSummaryResponse
+>;