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

package/common/types/cart.types.ts

@@ -3,6 +3,7 @@ import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { TradeStatus } from './common.types';
 import { investorAccountIdSchema } from './investor-account.types';
 import { paymentMethodIdSchema } from './payment-methods.types';
+import { userIdSchema } from './user.types';
 
 extendZodWithOpenApi(z);
 
@@ -10,7 +11,9 @@ export const PlaceTradeResponse = z.object({
   tradeStatus: z.nativeEnum(TradeStatus).optional(),
 });
 export const PlaceTradeBody = z.object({});
-
+export const ClientPlacetradeBody = z.object({
+  userId: userIdSchema,
+});
 export const PatchCartBody = z.object({
   investorAccountId: investorAccountIdSchema.optional(),
   paymentMethodId: paymentMethodIdSchema.optional(),

package/common/types/disbursements.types.ts

@@ -11,14 +11,17 @@ import {
 import { tradeIdSchema } from './trade.types';
 import { accountIdSchema } from './account.types';
 import { TypeID } from 'typeid-js';
-import { issuerIdSchema } from './issuer.types';
-import { issuerBankAccountIdSchema } from './issuer-bank-account.types';
+import { IIssuer, issuerIdSchema } from './issuer.types';
+import {
+  IIssuerBankAccount,
+  issuerBankAccountIdSchema,
+} from './issuer-bank-account.types';
 import { userIdSchema, UserZod } from './user.types';
 import {
   PostDisbursementAdjustmentZod,
   DisbursementAdjustmentType,
 } from './disbursement-adjustment.types';
-import { escrowAccountIdSchema } from './escrow-account.types';
+import { IEscrowAccount, escrowAccountIdSchema } from './escrow-account.types';
 
 export const disbursementIdSchema = z.string().refine(
   (value) => {
@@ -309,6 +312,97 @@ export const DisbursementSummaryZod = z.object({
 });
 export type DisbursementSummaryZod = z.infer<typeof DisbursementSummaryZod>;
 
+// GET /disbursements/preview query parameters
+export const GetDisbursementPreviewQueryZod = z.object({
+  offeringId: offeringIdSchema,
+  selectedTrades: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (ids) =>
+        ids.every((id) => {
+          try {
+            const tid = TypeID.fromString(id);
+            return tid.getType() === 'trade';
+          } catch {
+            return false;
+          }
+        }),
+      {
+        message: 'All selected trades must be valid trade IDs',
+      },
+    )
+    .openapi({
+      example: 'trade_01abc123,trade_01def456',
+    }),
+});
+export type GetDisbursementPreviewQueryZod = z.infer<
+  typeof GetDisbursementPreviewQueryZod
+>;
+
+// Context fields for disbursement preview
+export const DisbursementPreviewContextZod = z.object({
+  issuer: z.lazy(() => IIssuer).nullable(),
+  offering: z.lazy(() => IOffering).nullable(),
+  escrowAccount: z.lazy(() => IEscrowAccount).nullable(),
+  destinationBank: z.lazy(() => IIssuerBankAccount).nullable(),
+});
+export type DisbursementPreviewContextZod = z.infer<
+  typeof DisbursementPreviewContextZod
+>;
+
+// Balance values for disbursement preview
+export const DisbursementPreviewBalanceZod = z.object({
+  totalRaised: z.number(),
+  totalDisbursed: z.number(),
+  pending: z.number(),
+  refundPool: z.number(),
+  availableForDisbursement: z.number(),
+});
+export type DisbursementPreviewBalanceZod = z.infer<
+  typeof DisbursementPreviewBalanceZod
+>;
+
+// Trade summary for disbursement preview
+export const DisbursementPreviewTradeSummaryZod = z.object({
+  selectedTradesCount: z.number(),
+  selectedTradesTotalAmount: z.number(),
+});
+export type DisbursementPreviewTradeSummaryZod = z.infer<
+  typeof DisbursementPreviewTradeSummaryZod
+>;
+
+// Contingency validation result
+export const DisbursementPreviewContingencyZod = z.object({
+  contingencyPassed: z.boolean(),
+  contingencyMessage: z.string().nullable(),
+  contingencyAmount: z.number(),
+});
+export type DisbursementPreviewContingencyZod = z.infer<
+  typeof DisbursementPreviewContingencyZod
+>;
+
+// Amount defaults and constraints
+export const DisbursementPreviewAmountZod = z.object({
+  defaultAmount: z.number(),
+  minAmount: z.number(),
+  maxAmount: z.number(),
+});
+export type DisbursementPreviewAmountZod = z.infer<
+  typeof DisbursementPreviewAmountZod
+>;
+
+// Complete response for GET /disbursements/preview
+export const DisbursementPreviewZod = z.object({
+  context: DisbursementPreviewContextZod,
+  balance: DisbursementPreviewBalanceZod,
+  tradeSummary: DisbursementPreviewTradeSummaryZod,
+  contingency: DisbursementPreviewContingencyZod,
+  amount: DisbursementPreviewAmountZod,
+});
+export type DisbursementPreviewZod = z.infer<typeof DisbursementPreviewZod>;
+
 export const EligibleOfferingZod = z.object({
   offeringId: offeringIdSchema,
   offeringName: z.string(),

package/common/types/file.types.ts

@@ -314,8 +314,23 @@ export const reviewFiles = z.object({
 });
 export type reviewFiles = z.infer<typeof reviewFiles>;
 
+/**
+ * Zod preprocessor that trims strings and converts empty/whitespace-only strings to null
+ */
+const trimAndNullifyString = z.preprocess((val) => {
+  if (typeof val === 'string') {
+    const trimmed = val.trim();
+    return trimmed === '' ? null : trimmed;
+  }
+  return val;
+}, z.unknown());
+
 export const PatchFileMetadata = z.object({
-  corrected: z.record(z.string(), z.unknown()),
+  corrected: z.record(z.string(), trimAndNullifyString),
+  expectedCorrected: z
+    .record(z.string(), trimAndNullifyString)
+    .nullable()
+    .optional(),
 });
 export type PatchFileMetadata = z.infer<typeof PatchFileMetadata>;
 
@@ -343,6 +358,7 @@ export const FileMetadataSchema = z.object({
       },
     ),
   corrected: z.record(z.any()).optional(),
+  expectedCorrected: z.record(z.any()).optional(),
 });
 export type FileMetadata = z.infer<typeof FileMetadataSchema>;
 

package/common/types/i-will-do-it-later.types.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { PortalType, TargetTableEnum } from './common.types';
+import { TaskPriority, TaskType } from './task.types';
+
+export enum IWillDoItLaterType {
+  KYC = 'KYC',
+  // Future types can be added here:
+  // AIC = 'AIC',
+  // AML = 'AML',
+}
+
+export const IWillDoItLaterBodySchema = z.object({
+  type: z.nativeEnum(IWillDoItLaterType).default(IWillDoItLaterType.KYC),
+});
+
+export type IWillDoItLaterBodyType = z.infer<typeof IWillDoItLaterBodySchema>;
+
+export const IWillDoItLaterResponseSchema = z.object({
+  message: z.string(),
+});
+
+export type IWillDoItLaterResponseType = z.infer<
+  typeof IWillDoItLaterResponseSchema
+>;
+
+/**
+ * @description Context required for processing "I'll do it later" actions.
+ */
+export interface IWillDoItLaterContext {
+  /** The ID of the target entity */
+  targetId: string;
+  /** The table name of the target entity */
+  targetTable: (typeof TargetTableEnum)[number];
+  /** The account ID associated with the action */
+  accountId: string;
+  /** The user ID who will be assigned the task */
+  assigneeId: string;
+}
+
+/**
+ * @description Configuration for each "I'll do it later" action type.
+ * Maps action types to their corresponding task configuration.
+ */
+export interface IWillDoItLaterTaskConfig {
+  taskType: TaskType;
+  portalType: PortalType;
+  title: string;
+  description: string;
+  priority: TaskPriority;
+}
+
+/**
+ * @description Mapping of "I'll do it later" types to their task configurations.
+ * This allows for easy extension of new action types without modifying the service logic.
+ */
+export const IWillDoItLaterTaskConfigMap: Record<
+  IWillDoItLaterType,
+  IWillDoItLaterTaskConfig
+> = {
+  [IWillDoItLaterType.KYC]: {
+    taskType: TaskType.COMPLETE_KYC,
+    portalType: PortalType.INVESTOR,
+    title: 'Complete KYC',
+    description:
+      'We are unable to verify your KYC information. Please complete your KYC.',
+    priority: TaskPriority.HIGH,
+  },
+};

package/common/types/index.ts

@@ -42,6 +42,7 @@ export * from './domain-filter.types';
 export * from './aic.types';
 export * from './default-theme-config.types';
 export * from './offering-reports.types';
+export * from './i-will-do-it-later.types';
 export * from './payment-methods.types';
 
 export enum Versions {

package/common/types/individuals.types.ts

@@ -12,9 +12,7 @@ import {
   InvestorAccountType,
   SetupStatusType,
   SetupStepType,
-  ComplianceReview,
   RetirementAccountType,
-  TradeStatus,
   EmploymentStatus,
   SourceOfIncome,
   AMLProvider,
@@ -60,8 +58,8 @@ export enum aicQuestionnaireQuestionType {
 }
 
 export enum FilterBy {
-  TRADE = 'TRADE',
-  INVESTOR = 'INVESTOR',
+  ALL = 'ALL',
+  PENDING_TRADES = 'PENDING_TRADES',
 }
 
 export const aicQuestionnaireQuestion = z.object({
@@ -243,17 +241,6 @@ export const IndividualFiltersZod = z.object({
 
 export const ComplianceIndividualFiltersZod = IndividualFiltersZod.extend({
   filterBy: z.nativeEnum(FilterBy).optional(),
-  tradeStatus: z.nativeEnum(TradeStatus).optional(),
-  complianceReview: z.nativeEnum(ComplianceReview).optional(),
-  hasPendingTrades: z.preprocess(
-    (val) =>
-      val === 'true' || val === '1'
-        ? true
-        : val === 'false' || val === '0'
-          ? false
-          : val,
-    z.boolean().optional(),
-  ),
 });
 
 /**

package/common/types/issuer-offering.types.ts

@@ -168,6 +168,7 @@ export const PostIssuerOffering = z
       .default(AssetTemplateType.STANDARD)
       .openapi({ example: AssetTemplateType.STANDARD }),
     tiers: z.array(z.number().positive()).nullable().optional(),
+    enableBonus: z.boolean().default(false).optional(),
   })
   .superRefine((data, ctx) => {
     // Check if both values are present, and if so, ensure minInvestment is less than maxInvestment
@@ -299,6 +300,7 @@ export const PatchIssuerOffering = z.object({
     .optional(),
   tiers: z.array(z.number().positive()).nullable().optional(),
   enabled: z.boolean().optional(),
+  enableBonus: z.boolean().optional(),
 });
 export type PatchIssuerOffering = z.infer<typeof PatchIssuerOffering>;
 

package/common/types/offering.types.ts

@@ -230,6 +230,7 @@ export const PatchOffering = PatchOfferingBase.merge(
       .nullable()
       .optional(),
     tiers: z.array(z.number().positive()).nullable().optional(),
+    enableBonus: z.boolean().optional(),
   }),
 );
 export type PatchOffering = z.infer<typeof PatchOffering>;
@@ -276,6 +277,7 @@ export const PostComplianceOffering = PatchOfferingBase.merge(
       .default(AssetTemplateType.STANDARD)
       .openapi({ example: AssetTemplateType.STANDARD }),
     tiers: z.array(z.number().positive()).nullable().optional(),
+    enableBonus: z.boolean().default(false).optional(),
   }),
 ).superRefine(postAssetRefinement);
 export type PostComplianceOffering = z.infer<typeof PostComplianceOffering>;

package/common/types/transaction.types.ts

@@ -1,10 +1,11 @@
+import { z } from 'zod';
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { TypeID } from 'typeid-js';
 import {
   dateSchema,
   InvestorAccountType,
   numberPrecisionSchema,
 } from './common.types';
-import { z } from 'zod';
 import { IBaseEntity } from './entity.types';
 import { accountIdSchema } from './account.types';
 import {
@@ -18,7 +19,9 @@ import {
   investorAccountIdSchema,
 } from './investor-account.types';
 import { TransactionStatus, TransactionType } from './common.types';
+import { userIdSchema } from './user.types';
 export { TransactionStatus, TransactionType };
+extendZodWithOpenApi(z);
 
 export enum RefundPaymentMethod {
   CHECK = 'CHECK',
@@ -115,6 +118,14 @@ export type InvestorPostTransactionZod = z.infer<
   typeof InvestorPostTransactionZod
 >;
 
+export const ClientPostTransactionZod = InvestorPostTransactionZod.extend({
+  userId: z
+    .lazy(() => userIdSchema)
+    .openapi({ example: 'user_01j5y5ghx5fg68d663j1fvy2x7' }),
+});
+
+export type ClientPostTransactionZod = z.infer<typeof ClientPostTransactionZod>;
+
 export const refundTransactionIdSchema = z.string().refine(
   (value) => {
     try {

package/common/types/user.types.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import {
   AccountStatus,
   AccountWithoutUsersZod,
@@ -12,7 +13,6 @@ import {
   UserType,
 } from './common.types';
 import { dateOrString, IBaseEntity } from './entity.types';
-import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { PhoneZodSchema } from './phone.type';
 import { IInvestorAccount } from './investor-account.types';
 import { TradeZod } from './trade.types';
@@ -51,6 +51,11 @@ export const UserDeleteResponse = z.object({
 });
 export type UserDeleteResponse = z.infer<typeof UserDeleteResponse>;
 
+export const UserRestoreResponse = z.object({
+  message: z.string(),
+});
+export type UserRestoreResponse = z.infer<typeof UserRestoreResponse>;
+
 export const GetMeResponse = IBaseEntity.extend({
   accountId: z.string().nullable(),
   accountName: z.string().nullable(),

package/contracts/clients/cart/index.ts

@@ -10,7 +10,11 @@ import {
   userIdSchema,
   tradeIdSchema,
 } from '../../../common/types';
-import { PatchCartBody } from '../../../common/types/cart.types';
+import {
+  PatchCartBody,
+  ClientPlacetradeBody,
+  PlaceTradeResponse,
+} from '../../../common/types/cart.types';
 
 const c = initContract();
 
@@ -34,6 +38,22 @@ export const cartContract = c.router(
         500: InternalError,
       },
     },
+    postCheckout: {
+      summary: 'Place a trade (checkout button)',
+      method: 'POST',
+      path: '/checkout',
+      metadata: {
+        auth: true,
+      },
+      body: ClientPlacetradeBody,
+      responses: {
+        200: PlaceTradeResponse,
+        400: BadRequestError,
+        401: UnauthorizedError,
+        403: ForbiddenError,
+        500: InternalError,
+      },
+    },
     patchCart: {
       summary: 'Patch a cart',
       method: 'PATCH',

package/contracts/clients/index.ts

@@ -19,6 +19,7 @@ import { sitesContract } from './sites';
 import { paymentMethodsContract } from './payment-methods';
 import { issuerPaymentMethodsContract } from './issuer-payment-methods';
 import { tradeLineItemsContract } from './trade-line-items';
+import { clientsTransactionsContract } from './transactions';
 
 const c = initContract();
 
@@ -45,6 +46,7 @@ export const clientsContract = c.router(
     sites: sitesContract,
     tradeLineItems: tradeLineItemsContract,
     trades: tradesContract,
+    transactions: clientsTransactionsContract,
   },
   {
     pathPrefix: '/clients/api/v1/',

package/contracts/clients/transactions/index.ts

@@ -0,0 +1,37 @@
+import { initContract } from '@ts-rest/core';
+import {
+  BadRequestError,
+  InternalError,
+  NotFoundError,
+  UnauthorizedError,
+} from '../../../common/types';
+import {
+  ClientPostTransactionZod,
+  TransactionZod,
+} from '../../../common/types/transaction.types';
+
+const c = initContract();
+
+export const clientsTransactionsContract = c.router(
+  {
+    postTransaction: {
+      summary: 'Create a transaction',
+      method: 'POST',
+      path: '',
+      metadata: {
+        auth: true,
+      },
+      body: ClientPostTransactionZod,
+      responses: {
+        201: TransactionZod,
+        400: BadRequestError,
+        401: UnauthorizedError,
+        404: NotFoundError,
+        500: InternalError,
+      },
+    },
+  },
+  {
+    pathPrefix: 'transactions',
+  },
+);

package/contracts/compliance/users/index.ts

@@ -21,6 +21,7 @@ import {
   IssuersActiveStatusUpdateZod,
   UpdateLockedStatus,
   UpdateUserRoleZod,
+  UserRestoreResponse,
 } from '../../../common/types';
 import { z } from 'zod';
 
@@ -143,6 +144,26 @@ export const usersContract = c.router(
         500: InternalError,
       },
     },
+    restoreUser: {
+      summary: 'Restore user by id',
+      method: 'POST',
+      path: '/:id/restore',
+      metadata: {
+        auth: true,
+      },
+      pathParams: z.object({
+        id: userIdSchema,
+      }),
+      body: z.object({}),
+      responses: {
+        200: UserRestoreResponse,
+        400: BadRequestError,
+        401: UnauthorizedError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        500: InternalError,
+      },
+    },
     updateActiveStatus: {
       summary: '[Admin] Update user active status',
       method: 'PATCH',

package/contracts/investors/individuals/index.ts

@@ -14,6 +14,8 @@ import {
   IIndividualZod,
   BadRequestError,
   InternalError,
+  IWillDoItLaterBodySchema,
+  IWillDoItLaterResponseSchema,
 } from '../../../common/types';
 import { z } from 'zod';
 
@@ -92,6 +94,26 @@ export const individualsContract = c.router(
         403: ForbiddenError,
       },
     },
+    iWillDoItLater: {
+      summary: "I'll do it later - Create a task for later completion",
+      method: 'POST',
+      path: '/:id/defer',
+      metadata: {
+        auth: true,
+      },
+      pathParams: z.object({
+        id: individualIdSchema,
+      }),
+      body: IWillDoItLaterBodySchema,
+      responses: {
+        201: IWillDoItLaterResponseSchema,
+        400: BadRequestError,
+        401: UnauthorizedError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        500: InternalError,
+      },
+    },
   },
   {
     pathPrefix: 'individuals',

package/contracts/issuers/disbursements/index.ts

@@ -17,8 +17,10 @@ import {
   DisbursementMissingConfigZod,
   DisbursementsIncludeQuery,
   DisbursementsMissingConfigQuery,
+  DisbursementPreviewZod,
   DisbursementSummaryZod,
   DisbursementZod,
+  GetDisbursementPreviewQueryZod,
   EligibleOfferingsFiltersZod,
   IPaginatedDisbursement,
   IPaginatedEligibleOffering,
@@ -148,6 +150,22 @@ export const disbursementsContract = c.router(
         500: InternalError,
       },
     },
+    getDisbursementPreview: {
+      summary: 'Get disbursement preview data for Step 2',
+      method: 'GET',
+      path: '/preview',
+      metadata: {
+        auth: true,
+      },
+      query: GetDisbursementPreviewQueryZod,
+      responses: {
+        200: DisbursementPreviewZod,
+        400: BadRequestError,
+        401: UnauthorizedError,
+        404: NotFoundError,
+        500: InternalError,
+      },
+    },
     getEligibleOfferings: {
       summary: 'Get eligible offerings for disbursement',
       method: 'GET',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalmore/api-contracts",
-  "version": "0.0.0-dev.0c67bc1",
+  "version": "0.0.0-dev.0fb0042",
   "description": "Type-safe API contracts for Dalmore Client Portal",
   "main": "./contracts/index.ts",
   "types": "./contracts/index.ts",