@dalmore/api-contracts 0.0.0-dev.801385 → 0.0.0-dev.9d42e16

package/README.md

@@ -14,32 +14,33 @@ npm install @dalmore/api-contracts@dev
 
 ## Usage
 
-### Import specific contracts (recommended for tree-shaking)
+### Import from main entry
 
 ```typescript
-import { complianceContract } from '@dalmore/api-contracts/compliance';
-import { investorsContract } from '@dalmore/api-contracts/investors';
-import { issuersContract } from '@dalmore/api-contracts/issuers';
-import { clientsContract } from '@dalmore/api-contracts/clients';
+import { clientsContract } from '@dalmore/api-contracts';
+import type { IInvestorAccount } from '@dalmore/api-contracts';
 ```
 
-### Import types
+### Import specific subpaths (recommended for tree-shaking)
 
 ```typescript
-import type { IInvestorAccount } from '@dalmore/api-contracts/types/investor-account.types';
-import type { ITrade } from '@dalmore/api-contracts/types/trade.types';
+// Import clients contract
+import { clientsContract } from '@dalmore/api-contracts/clients';
+
+// Import types
+import type { IInvestorAccount, ITrade } from '@dalmore/api-contracts/types';
 ```
 
 ### Create a typed client
 
 ```typescript
-import { complianceContract } from '@dalmore/api-contracts/compliance';
+import { clientsContract } from '@dalmore/api-contracts/clients';
 import { initClient } from '@ts-rest/core';
 
-const client = initClient(complianceContract, {
+const client = initClient(clientsContract, {
   baseUrl: 'https://platform.dalmoregroup.com',
   baseHeaders: {
-    Authorization: `Bearer ${token}`,
+    'X-API-Key': `${apiKey}`,
   },
 });
 
@@ -53,17 +54,20 @@ const { status, body } = await client.accounts.getAccounts({
 
 This package requires the following peer dependencies:
 
-- `@ts-rest/core` ^3.0.0
-- `zod` ^3.0.0
+- `@anatine/zod-openapi` ^1.14.2
+- `@ts-rest/core` ^3.52.1
+- `typeid-js` ^1.2.0
+- `zod` ^3.24.4
 
-## Available Contracts
+## Available Exports
 
-- `complianceContract` - Compliance portal API
-- `investorsContract` - Investor portal API
-- `issuersContract` - Issuer portal API
 - `clientsContract` - Client API (API key auth)
-- `secondariesContract` - Secondaries API
-- `complianceApiKeyContract` - Compliance API (API key auth)
+
+## Available Subpath Exports
+
+- `@dalmore/api-contracts` - Main entry (clients contract and types)
+- `@dalmore/api-contracts/clients` - Clients contract
+- `@dalmore/api-contracts/types` - All common types
 
 ## TypeScript Configuration
 

package/common/types/account.types.ts

@@ -101,6 +101,7 @@ const accountsInclude = z.enum([
   'issuers',
   'legalEntities',
   'offerings',
+  'pages',
   'sites',
   'trades',
   'users',

package/common/types/comply-advantage-api.types.ts

@@ -30,7 +30,7 @@ export const CreateSearchRequestSchema = z.object({
         .optional(),
     })
     .optional(),
-  tags: z.record(z.string()).optional(),
+  tags: z.union([z.record(z.string()), z.array(z.any())]).optional(),
   share_url: z.union([z.literal(0), z.literal(1)]).optional(),
   exact_match: z.boolean().optional(),
 });
@@ -268,7 +268,7 @@ export const GetSearchDetailsResponseSchema = z.object({
       total_matches: z.number(),
       updated_at: z.string(),
       created_at: z.string(),
-      tags: z.record(z.string()).optional(),
+      tags: z.union([z.record(z.string()), z.array(z.any())]).optional(),
       labels: z
         .array(
           z.object({
@@ -310,7 +310,7 @@ export const UpdateSearchRequestSchema = z.object({
   risk_level: z.enum(['low', 'medium', 'high', 'unknown']).optional(),
   assignee_id: z.number().optional(),
   limit: z.number().int().max(100).optional(),
-  tags: z.record(z.string()).optional(),
+  tags: z.union([z.record(z.string()), z.array(z.any())]).optional(),
 });
 
 export type UpdateSearchRequest = z.infer<typeof UpdateSearchRequestSchema>;

package/common/types/mail-template.types.ts

@@ -434,3 +434,37 @@ export type EmailThemeSetting = z.infer<typeof EmailThemeSettingZod>;
 
 export const EmailThemeSettingsZod = z.array(EmailThemeSettingZod);
 export type EmailThemeSettingsZod = z.infer<typeof EmailThemeSettingsZod>;
+
+/**
+ * Response from a successful email send operation.
+ * Based on SendGrid SDK's ClientResponse structure.
+ */
+export const EmailSendResponseSchema = z.object({
+  /** HTTP status code from SendGrid (e.g., 202 for accepted) */
+  statusCode: z.number(),
+  /** SendGrid's x-message-id header for tracking emails in their dashboard */
+  messageId: z.string().optional(),
+  /** Full response headers, available for debugging if needed */
+  headers: z.record(z.string(), z.unknown()).optional(),
+});
+export type EmailSendResponse = z.infer<typeof EmailSendResponseSchema>;
+
+/**
+ * Error from a failed email send operation.
+ * Fields are optional because error shapes vary depending on failure type
+ * (network errors vs SendGrid API errors).
+ */
+export const EmailSendErrorSchema = z.object({
+  /** Human-readable error message */
+  message: z.string(),
+  /** Network-level error code (e.g., 'ECONNREFUSED', 'ETIMEDOUT') */
+  code: z.string().optional(),
+  /** HTTP status code if request reached SendGrid (e.g., 400, 401, 403, 413, 500) */
+  statusCode: z.number().optional(),
+  /**
+   * SendGrid's error response body. Structure: { errors: [{ message, field, help, id }] }
+   * @see https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send#responses
+   */
+  response: z.unknown().optional(),
+});
+export type EmailSendError = z.infer<typeof EmailSendErrorSchema>;

package/common/types/notification.types.ts

@@ -208,6 +208,16 @@ export type EmailNotificationPayload = z.infer<
   typeof EmailNotificationPayloadSchema
 >;
 
+/**
+ * Payload for Slack notifications sent via Incoming Webhooks.
+ *
+ * @property webhookUrl - Slack Incoming Webhook URL
+ * @property channelEmail - Slack channel email integration (alternative delivery method)
+ * @property message - Plain text message (also serves as fallback for notifications)
+ * @property blocks - Optional Slack Block Kit elements for rich message formatting.
+ *   Blocks allow structured layouts with headers, sections, images, buttons, etc.
+ *   @see https://docs.slack.dev/messaging/creating-interactive-messages
+ */
 export const SlackNotificationPayloadSchema = z.object({
   webhookUrl: z.string().url().optional(),
   channelEmail: z.string().email().optional(),

package/common/types/trade.types.ts

@@ -21,6 +21,7 @@ import {
   createDateSchema,
   AccountStatus,
   SavedQuery,
+  AccountZod,
 } from './common.types';
 import { IOffering, offeringIdSchema } from './offering.types';
 import { IBaseEntity } from './entity.types';
@@ -301,6 +302,7 @@ export const TradeZod = IBaseEntity.extend({
     .optional()
     .nullable(),
   accountId: accountIdSchema.nullable(),
+  account: z.lazy(() => AccountZod).nullable(),
   offeringId: z.lazy(() => offeringIdSchema.nullable()),
   paymentMethodId: z.lazy(() => paymentMethodIdSchema).nullable(),
   paymentMethod: z

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/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.801385",
+  "version": "0.0.0-dev.9d42e16",
   "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"
   }

package/contracts/compliance/account-contacts/index.ts

@@ -1,82 +0,0 @@
-import { initContract } from '@ts-rest/core';
-import {
-  accountIdSchema,
-  BadRequestError,
-  ForbiddenError,
-  InternalError,
-  NotFoundError,
-  UnauthorizedError,
-} from '../../../common/types';
-import {
-  accountContactIdSchema,
-  CompliancePatchAccountContactZod,
-  IAccountContact,
-} from '../../../common/types/account-contact.types';
-import { z } from 'zod';
-
-const c = initContract();
-
-export const accountContactsContract = c.router(
-  {
-    getAccountContacts: {
-      summary: '[ADMIN] Get Account Contacts',
-      method: 'GET',
-      path: '',
-      metadata: {
-        auth: true,
-      },
-      query: z.object({
-        accountId: accountIdSchema,
-      }),
-      responses: {
-        200: z.array(IAccountContact),
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        500: InternalError,
-      },
-    },
-    getAccountContact: {
-      summary: '[ADMIN] Get account contact by id',
-      method: 'GET',
-      path: '/:id',
-      metadata: {
-        auth: true,
-      },
-      pathParams: z.object({
-        id: accountContactIdSchema,
-      }),
-      query: z.object({
-        accountId: accountIdSchema,
-      }),
-      responses: {
-        200: IAccountContact,
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        404: NotFoundError,
-      },
-    },
-    patchAccountContact: {
-      summary: '[ADMIN] Update account contact',
-      method: 'PATCH',
-      path: '/:id',
-      metadata: {
-        auth: true,
-      },
-      pathParams: z.object({
-        id: accountContactIdSchema,
-      }),
-      body: CompliancePatchAccountContactZod,
-      responses: {
-        200: IAccountContact,
-        400: BadRequestError,
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        404: NotFoundError,
-        500: InternalError,
-      },
-    },
-  },
-  {
-    pathPrefix: 'account-contacts',
-  },
-);

package/contracts/compliance/account-managers/index.ts

@@ -1,142 +0,0 @@
-import { initContract } from '@ts-rest/core';
-import { z } from 'zod';
-import {
-  BadRequestError,
-  ForbiddenError,
-  InternalError,
-  NotFoundError,
-  PaginationOptionsZod,
-  PreconditionFailedError,
-  UnauthorizedError,
-} from '../../../common/types';
-import {
-  AccountManagerDeleteQuery,
-  AccountManagerDeleteResponse,
-  accountManagerIdSchema,
-  AccountManagersIncludeQuery,
-  IAccountManagerZod,
-  IPaginatedAccountManager,
-  PatchAccountManagerZod,
-  PostAccountManagerZod,
-  SetDefaultAccountManagerForAllAccountsResponse,
-} from '../../../common/types/account-manager.types';
-
-const c = initContract();
-
-export const accountManagersContract = c.router(
-  {
-    getAccountManagers: {
-      summary: 'Get account managers',
-      method: 'GET',
-      path: '',
-      metadata: {
-        auth: true,
-      },
-      query: PaginationOptionsZod.merge(AccountManagersIncludeQuery),
-      responses: {
-        200: IPaginatedAccountManager,
-        400: BadRequestError,
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        500: InternalError,
-      },
-    },
-    getAccountManager: {
-      summary: 'Get account manager by id',
-      method: 'GET',
-      path: '/:id',
-      metadata: {
-        auth: true,
-      },
-      query: z.object({}).merge(AccountManagersIncludeQuery),
-      pathParams: z.object({
-        id: accountManagerIdSchema,
-      }),
-      responses: {
-        200: IAccountManagerZod,
-        400: BadRequestError,
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        404: NotFoundError,
-        500: InternalError,
-      },
-    },
-    setDefaultAccountManagerForAllAccounts: {
-      summary: '[ADMIN] Set default account manager for all accounts',
-      method: 'PATCH',
-      path: '/set-default-for-all-accounts',
-      metadata: {
-        auth: true,
-      },
-      body: z.object({}),
-      responses: {
-        200: SetDefaultAccountManagerForAllAccountsResponse,
-        400: BadRequestError,
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        500: InternalError,
-      },
-    },
-    patchAccountManager: {
-      summary: 'Update account manager by id',
-      method: 'PATCH',
-      path: '/:id',
-      metadata: {
-        auth: true,
-      },
-      pathParams: z.object({
-        id: accountManagerIdSchema,
-      }),
-      body: PatchAccountManagerZod,
-      responses: {
-        201: IAccountManagerZod,
-        400: BadRequestError,
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        404: NotFoundError,
-        500: InternalError,
-      },
-    },
-    postAccountManager: {
-      summary: 'Create account manager',
-      method: 'POST',
-      path: '',
-      metadata: {
-        auth: true,
-      },
-      body: PostAccountManagerZod,
-      responses: {
-        201: IAccountManagerZod,
-        400: BadRequestError,
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        500: InternalError,
-      },
-    },
-    deleteAccountManager: {
-      summary: 'Delete account manager by id',
-      method: 'DELETE',
-      path: '/:id',
-      metadata: {
-        auth: true,
-      },
-      pathParams: z.object({
-        id: accountManagerIdSchema,
-      }),
-      query: AccountManagerDeleteQuery,
-      responses: {
-        201: AccountManagerDeleteResponse,
-        400: BadRequestError,
-        401: UnauthorizedError,
-        403: ForbiddenError,
-        404: NotFoundError,
-        412: PreconditionFailedError,
-        500: InternalError,
-      },
-    },
-  },
-
-  {
-    pathPrefix: 'account-managers',
-  },
-);