@dalmore/api-contracts 0.0.0-dev.582cb9c → 0.0.0-dev.5e42638

package/common/types/trade.types.ts

@@ -22,12 +22,13 @@ import {
   AccountStatus,
   SavedQuery,
 } from './common.types';
-import { offeringIdSchema } from './offering.types';
+import { IOffering, offeringIdSchema } from './offering.types';
 import { IBaseEntity } from './entity.types';
 import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { TypeID } from 'typeid-js';
 import {
   paymentMethodIdSchema,
+  PaymentMethodResponse,
   PaymentMethodType,
 } from './payment-methods.types';
 import {
@@ -35,11 +36,12 @@ import {
   InvestorAccountExportFilters,
   ComplianceInvestorAccountExportFilters,
   RegisteredInvestorUserRawZod,
+  IInvestorAccount,
 } from './investor-account.types';
 import {
   tradeLineItemIdSchema,
   TradeLineItemZod,
-} from './trade-line-item.type';
+} from './trade-line-item.types';
 import { TradeAdjustmentZod } from './trade-adjustment.type';
 import { TransactionZod } from './transaction.types';
 import { accountIdSchema } from './account.types';
@@ -132,6 +134,7 @@ export const CheckResultsSchema = z.object({
 export type CheckResults = z.infer<typeof CheckResultsSchema>;
 
 export const TradeIdPrefix = 'trade';
+export const TradeSnapshotIdPrefix = 'trade_snapshot';
 
 export const tradeIdSchema = z.string().refine(
   (value) => {
@@ -170,6 +173,21 @@ export const tradeIdOrTidSchema = z.union([
     .openapi({ example: 'tid_00041061050r3gg28a1c60t3gf' }),
 ]);
 
+export const tradeSnapshotIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === TradeSnapshotIdPrefix;
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid trade snapshot ID format. Must be a valid TypeID with "trade_snapshot" prefix. ex: trade_snapshot_00041061050r3gg28a1c60t3gf',
+  },
+);
+
 export enum SaStatus {
   PENDING = BaseStatus.PENDING,
   SIGNED = BaseStatus.SIGNED,
@@ -274,9 +292,21 @@ export type TradeBalanceResultZod = z.infer<typeof TradeBalanceResultZod>;
 
 export const TradeZod = IBaseEntity.extend({
   investorAccountId: z.lazy(() => investorAccountIdSchema.nullable()),
+  investorAccount: z
+    .lazy(() => IInvestorAccount)
+    .optional()
+    .nullable(),
+  offering: z
+    .lazy(() => IOffering)
+    .optional()
+    .nullable(),
   accountId: accountIdSchema.nullable(),
   offeringId: z.lazy(() => offeringIdSchema.nullable()),
   paymentMethodId: z.lazy(() => paymentMethodIdSchema).nullable(),
+  paymentMethod: z
+    .lazy(() => PaymentMethodResponse)
+    .optional()
+    .nullable(),
   userId: z.lazy(() => userIdSchema.nullable()),
   tradeNumber: z.string(),
   ip: z.string().nullable(),
@@ -342,6 +372,21 @@ export const TradeZod = IBaseEntity.extend({
 });
 export type TradeZod = z.infer<typeof TradeZod>;
 
+export enum SnapshotEvent {
+  COMPLIANCE_APPROVED = 'COMPLIANCE_APPROVED',
+  COMPLIANCE_REJECTED = 'COMPLIANCE_REJECTED',
+  CANCELLED = 'CANCELLED',
+  PLACED = 'PLACED',
+  SETTLED = 'SETTLED',
+}
+
+export const GetTradeSnapshotEventsResponse = z.object({
+  events: z.array(z.nativeEnum(SnapshotEvent)),
+});
+export type GetTradeSnapshotEventsResponse = z.infer<
+  typeof GetTradeSnapshotEventsResponse
+>;
+
 export const IPaginatedTrade = z.object({
   items: z.array(TradeZod),
   meta: IPaginationMeta,
@@ -424,6 +469,7 @@ export const TradeFiltersZod = z.object({
     .openapi({
       example: 'issuer_01jfw4q6qef30s6fpqtsxw94ya',
     }),
+  snapshotEvent: z.nativeEnum(SnapshotEvent).optional(),
   offeringType: z.nativeEnum(OfferingType).optional(),
   managedBy: z.nativeEnum(ManagedByType).optional(),
   platform: z.nativeEnum(Platforms).optional(),

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/trusted-contact.types.ts

@@ -2,7 +2,11 @@ import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import { TypeID } from 'typeid-js';
 import { z } from 'zod';
 import { IBaseEntity } from './entity.types';
-import { IPaginationMeta, TrustedContactRelationship } from './common.types';
+import {
+  EmailSchema,
+  IPaginationMeta,
+  TrustedContactRelationship,
+} from './common.types';
 import { PhoneZodSchema } from './phone.type';
 import { AddressSchema } from './address.types';
 import { investorAccountIdSchema } from './investor-account.types';
@@ -68,7 +72,7 @@ export const PostTrustedContactZod = z
   .object({
     firstName: z.string().min(1).max(255).openapi({ example: 'John' }),
     lastName: z.string().min(1).max(255).openapi({ example: 'Doe' }),
-    email: z.string().email().openapi({ example: 'john.doe@example.com' }),
+    email: EmailSchema.openapi({ example: 'john.doe@example.com' }),
     phone: PhoneZodSchema.nullable().optional(),
     relationship: z
       .nativeEnum(TrustedContactRelationship)
@@ -92,11 +96,7 @@ export const PatchTrustedContactZod = z
       .optional()
       .openapi({ example: 'John' }),
     lastName: z.string().min(1).max(255).optional().openapi({ example: 'Doe' }),
-    email: z
-      .string()
-      .email()
-      .optional()
-      .openapi({ example: 'john.doe@example.com' }),
+    email: EmailSchema.optional(),
     phone: PhoneZodSchema.nullable().optional(),
     relationship: z.nativeEnum(TrustedContactRelationship).optional().openapi({
       example: TrustedContactRelationship.CHILD,

package/common/types/user.types.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
 import {
   AccountStatus,
   AccountWithoutUsersZod,
@@ -7,12 +8,12 @@ import {
   ManagedByType,
   OfferingType,
   PortalType,
+  StringToBooleanSchema,
   UserRole,
-  UserStatus,
   UserType,
+  EmailSchema,
 } 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 +52,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(),
@@ -59,7 +65,7 @@ export const GetMeResponse = IBaseEntity.extend({
   email: z.string().email(),
   provider: z.string(),
   active: z.boolean(),
-  status: z.lazy(() => z.nativeEnum(UserStatus)),
+  locked: z.boolean(),
   lastLoginAt: dateOrString.nullable(),
   loginCount: z.number(),
   role: z.string(),
@@ -142,11 +148,7 @@ export const UserMeUpdateZod = z.object({
   firstName: z.string().optional(),
   lastName: z.string().optional(),
   password: z.string().min(6).optional(),
-  email: z
-    .string()
-    .email()
-    .transform((val) => val.toLowerCase())
-    .optional(),
+  email: EmailSchema.optional(),
 });
 
 export const UserZod = IBaseEntity.extend({
@@ -157,7 +159,7 @@ export const UserZod = IBaseEntity.extend({
   onboarding: z.string().nullable(),
   account: AccountWithoutUsersZod.optional(),
   active: z.boolean(),
-  status: z.nativeEnum(UserStatus),
+  locked: z.boolean(),
   userLogin: IBaseEntity.extend({
     firstName: z.string(),
     lastName: z.string(),
@@ -179,27 +181,9 @@ export const UserFiltersZod = z.object({
   search: z.string().max(50).optional(),
   role: z.nativeEnum(UserRole).optional(),
   portal: z.string().optional(),
-  status: z.nativeEnum(UserStatus).optional(),
-  active: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'active must be a boolean string',
-    })
-    .transform((v) => {
-      if (!v) return undefined;
-      return v === 'true';
-    }),
-  twoFactorEnabled: z
-    .string()
-    .optional()
-    .refine((v) => !v || v === 'true' || v === 'false', {
-      message: 'twoFactorEnabled must be a boolean string',
-    })
-    .transform((v) => {
-      if (!v) return undefined;
-      return v === 'true';
-    }),
+  locked: StringToBooleanSchema.optional(),
+  active: StringToBooleanSchema.optional(),
+  twoFactorEnabled: StringToBooleanSchema.optional(),
 });
 
 const usersInclude = z.enum(['account', 'role']);
@@ -274,7 +258,7 @@ export type IssuerUsersStatusUpdateResponse = z.infer<
 >;
 
 export const UpdateLockedStatus = z.object({
-  status: z.nativeEnum(UserStatus),
+  locked: z.boolean(),
 });
 
 export type UpdateLockedStatus = z.infer<typeof UpdateLockedStatus>;
@@ -285,7 +269,7 @@ export const UsersSummaryFilterZod = z.object({
   portalType: z.nativeEnum(PortalType).optional(),
   search: z.string().trim().max(50).optional(),
   selectRole: z.nativeEnum(UserRole).optional(),
-  status: z.nativeEnum(UserStatus).optional(),
+  locked: StringToBooleanSchema.optional(),
 });
 export type UsersSummaryFilterZod = z.infer<typeof UsersSummaryFilterZod>;
 
@@ -299,7 +283,7 @@ export const UsersSummaryZod = z.object({
   portalType: z.string(),
   loginCount: z.number().int(),
   lastLogin: z.date(),
-  status: z.nativeEnum(UserStatus),
+  locked: z.boolean(),
 });
 export type UsersSummaryZod = z.infer<typeof UsersSummaryZod>;
 

package/common/types/webhook.types.ts

@@ -1,6 +1,148 @@
 import { z } from 'zod';
 import { PersonaStatus } from './common.types';
 
+/**
+ * Hook0 Webhook Provider Types
+ *
+ * Types for interacting with Hook0's webhooks-as-a-service API.
+ * @see https://documentation.hook0.com/api - API Reference
+ */
+
+/**
+ * Hook0 API error response format.
+ * @see https://documentation.hook0.com/api
+ */
+export const Hook0ApiErrorSchema = z.object({
+  type: z.string(),
+  status: z.number(),
+  title: z.string(),
+  detail: z.string(),
+  validation: z.unknown().nullable(),
+  id: z.string(),
+});
+export type Hook0ApiError = z.infer<typeof Hook0ApiErrorSchema>;
+
+/**
+ * Error returned from Hook0 provider operations.
+ * Wraps Hook0 API errors with additional context.
+ */
+export const Hook0ProviderErrorSchema = z.object({
+  message: z.string(),
+  statusCode: z.number().optional(),
+  code: z.string().optional(),
+  apiError: Hook0ApiErrorSchema.optional(),
+});
+export type Hook0ProviderError = z.infer<typeof Hook0ProviderErrorSchema>;
+
+/**
+ * Hook0 subscription target configuration.
+ * Defines where and how webhooks are delivered.
+ * @see https://documentation.hook0.com/reference/subscriptionscreate
+ */
+export const Hook0SubscriptionTargetSchema = z.object({
+  type: z.literal('http'),
+  method: z.string(),
+  url: z.string().url(),
+  headers: z.record(z.string()).optional(),
+});
+export type Hook0SubscriptionTarget = z.infer<
+  typeof Hook0SubscriptionTargetSchema
+>;
+
+/**
+ * Hook0 subscription response from create/get operations.
+ * @see https://documentation.hook0.com/reference/subscriptionscreate
+ * @see https://documentation.hook0.com/reference/subscriptionsget
+ */
+export const Hook0SubscriptionResponseSchema = z.object({
+  subscription_id: z.string().uuid(),
+  application_id: z.string().uuid(),
+  created_at: z.string().datetime().optional(),
+  dedicated_workers: z.array(z.string()).optional(),
+  description: z.string().optional(),
+  event_types: z.array(z.string()).optional(),
+  is_enabled: z.boolean().optional(),
+  label_key: z.string().optional(),
+  label_value: z.string().optional(),
+  labels: z.record(z.string()).optional(),
+  metadata: z.record(z.string()).optional(),
+  secret: z.string(),
+  target: Hook0SubscriptionTargetSchema.optional(),
+});
+export type Hook0SubscriptionResponse = z.infer<
+  typeof Hook0SubscriptionResponseSchema
+>;
+
+/**
+ * Simplified subscription result returned to callers.
+ */
+export const WebhookSubscriptionSchema = z.object({
+  subscriptionId: z.string(),
+  secret: z.string(),
+});
+export type WebhookSubscription = z.infer<typeof WebhookSubscriptionSchema>;
+
+/**
+ * Hook0 event type response from create operation.
+ * @see https://documentation.hook0.com/reference/eventtypescreate
+ */
+export const Hook0EventTypeResponseSchema = z.object({
+  service_name: z.string(),
+  resource_type_name: z.string(),
+  verb_name: z.string(),
+  event_type_name: z.string(),
+});
+export type Hook0EventTypeResponse = z.infer<
+  typeof Hook0EventTypeResponseSchema
+>;
+
+/**
+ * Hook0 event type list item.
+ * @see https://documentation.hook0.com/reference/eventtypeslist
+ */
+export const Hook0EventTypeSchema = z.object({
+  name: z.string(),
+  service: z.string().optional(),
+  resource_type: z.string().optional(),
+  verb: z.string().optional(),
+});
+export type Hook0EventType = z.infer<typeof Hook0EventTypeSchema>;
+
+/**
+ * Hook0 event ingestion response.
+ * @see https://documentation.hook0.com/api/#tag/events-ingestion/POST/api/v1/event/
+ */
+export const Hook0EventResponseSchema = z.object({
+  event_id: z.string().uuid().optional(),
+  received_at: z.string().datetime().optional(),
+});
+export type Hook0EventResponse = z.infer<typeof Hook0EventResponseSchema>;
+
+/**
+ * Simplified event response returned to callers.
+ */
+export const WebhookEventResponseSchema = z.object({
+  eventId: z.string(),
+  receivedAt: z.string(),
+});
+export type WebhookEventResponse = z.infer<typeof WebhookEventResponseSchema>;
+
+/**
+ * Payload sent when ingesting events to Hook0.
+ * Contains activity data to be delivered to webhook subscribers.
+ */
+export const WebhookEventPayloadSchema = z.object({
+  activityId: z.string(),
+  activityType: z.string(),
+  accountId: z.string(),
+  targetId: z.string().nullable(),
+  targetTable: z.string().nullable(),
+  message: z.string(),
+  metadata: z.record(z.unknown()),
+  occurredAt: z.string(),
+});
+export type WebhookEventPayload = z.infer<typeof WebhookEventPayloadSchema>;
+
 export const WebhookReceived = z.object({
   received: z.boolean(),
 });

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/trade-line-items/index.ts

@@ -14,7 +14,7 @@ import {
   TradeLineItemQuery,
   TradeLineItemResponse,
   TradeLineItemUpdate,
-} from '../../../common/types/trade-line-item.type';
+} from '../../../common/types/trade-line-item.types';
 
 const c = initContract();
 

package/contracts/clients/trades/index.ts

@@ -26,7 +26,7 @@ import {
   PostTradeLineItem,
   TradeLineItemQuery,
   TradeLineItemResponse,
-} from '../../../common/types/trade-line-item.type';
+} from '../../../common/types/trade-line-item.types';
 
 const c = initContract();
 

package/contracts/{investors → clients}/transactions/index.ts

@@ -6,13 +6,13 @@ import {
   UnauthorizedError,
 } from '../../../common/types';
 import {
-  InvestorPostTransactionZod,
+  ClientPostTransactionZod,
   TransactionZod,
 } from '../../../common/types/transaction.types';
 
 const c = initContract();
 
-export const investorsTransactionsContract = c.router(
+export const clientsTransactionsContract = c.router(
   {
     postTransaction: {
       summary: 'Create a transaction',
@@ -21,7 +21,7 @@ export const investorsTransactionsContract = c.router(
       metadata: {
         auth: true,
       },
-      body: InvestorPostTransactionZod,
+      body: ClientPostTransactionZod,
       responses: {
         201: TransactionZod,
         400: BadRequestError,

package/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @dalmore/api-contracts
+ * Main entry point - re-exports clients contract and types
+ */
+
+// Re-export clients contract
+export * from './contracts/clients/index.js';
+
+// Re-export all common types
+export * from './common/types/index.js';

package/package.json

@@ -1,48 +1,42 @@
 {
   "name": "@dalmore/api-contracts",
-  "version": "0.0.0-dev.582cb9c",
+  "version": "0.0.0-dev.5e42638",
   "description": "Type-safe API contracts for Dalmore Client Portal",
-  "main": "./contracts/index.ts",
-  "types": "./contracts/index.ts",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
   "exports": {
     ".": {
-      "types": "./contracts/index.ts",
-      "default": "./contracts/index.ts"
-    },
-    "./compliance": {
-      "types": "./contracts/compliance/index.ts",
-      "default": "./contracts/compliance/index.ts"
-    },
-    "./investors": {
-      "types": "./contracts/investors/index.ts",
-      "default": "./contracts/investors/index.ts"
-    },
-    "./issuers": {
-      "types": "./contracts/issuers/index.ts",
-      "default": "./contracts/issuers/index.ts"
+      "types": "./index.ts",
+      "import": "./index.ts",
+      "default": "./index.ts"
     },
     "./clients": {
       "types": "./contracts/clients/index.ts",
+      "import": "./contracts/clients/index.ts",
       "default": "./contracts/clients/index.ts"
     },
-    "./secondaries": {
-      "types": "./contracts/secondaries/index.ts",
-      "default": "./contracts/secondaries/index.ts"
-    },
-    "./compliance-apikey": {
-      "types": "./contracts/compliance-apikey/index.ts",
-      "default": "./contracts/compliance-apikey/index.ts"
-    },
     "./types": {
       "types": "./common/types/index.ts",
+      "import": "./common/types/index.ts",
       "default": "./common/types/index.ts"
-    },
-    "./types/*": {
-      "types": "./common/types/*.ts",
-      "default": "./common/types/*.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./index.ts"
+      ],
+      "clients": [
+        "./contracts/clients/index.ts"
+      ],
+      "types": [
+        "./common/types/index.ts"
+      ]
     }
   },
   "files": [
+    "index.ts",
     "contracts",
     "common"
   ],
@@ -68,9 +62,6 @@
     "typeid-js": "^1.2.0",
     "zod": "^3.24.4"
   },
-  "devDependencies": {
-    "typescript": "^5.8.3"
-  },
   "engines": {
     "node": ">=24.0.0 <25.0.0"
   }