@dalmore/api-contracts 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# @dalmore/api-contracts
+
+Type-safe API contracts for Dalmore Client Portal, powered by [ts-rest](https://ts-rest.com/).
+
+## Installation
+
+```bash
+# Production (stable releases from main branch)
+npm install @dalmore/api-contracts
+
+# Development (latest from dev branch)
+npm install @dalmore/api-contracts@dev
+```
+
+## Usage
+
+### Import specific contracts (recommended for tree-shaking)
+
+```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 types
+
+```typescript
+import type { IInvestorAccount } from '@dalmore/api-contracts/types/investor-account.types';
+import type { ITrade } from '@dalmore/api-contracts/types/trade.types';
+```
+
+### Create a typed client
+
+```typescript
+import { complianceContract } from '@dalmore/api-contracts/compliance';
+import { initClient } from '@ts-rest/core';
+
+const client = initClient(complianceContract, {
+  baseUrl: 'https://platform.dalmoregroup.com',
+  baseHeaders: {
+    Authorization: `Bearer ${token}`,
+  },
+});
+
+// Fully typed API calls
+const { status, body } = await client.accounts.getAccounts({
+  query: { page: 1, limit: 10 },
+});
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+- `@ts-rest/core` ^3.0.0
+- `zod` ^3.0.0
+
+## Available Contracts
+
+- `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)
+
+## TypeScript Configuration
+
+This package ships TypeScript source files for maximum type safety. Your `tsconfig.json` should include:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true
+  }
+}
+```

package/common/types/account-contact.types.ts

@@ -0,0 +1,98 @@
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { TypeID } from 'typeid-js';
+import { z } from 'zod';
+import { accountIdSchema } from './account.types';
+import { PhoneZodSchema } from './phone.type';
+import {
+  AccountContactType,
+  AccountZod,
+  IPaginationMeta,
+} from './common.types';
+import { IBaseEntity } from './entity.types';
+import { PhoneNumberData } from './sms.types';
+
+extendZodWithOpenApi(z);
+
+export const accountContactIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'account_contact';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid account contact ID format. Must be a valid TypeID with "account_contact" prefix.',
+  },
+);
+
+export const IAccountContact = IBaseEntity.extend({
+  id: accountContactIdSchema,
+  title: z.string().nullable().openapi({ example: 'Mr' }),
+  firstName: z.string().nullable().openapi({ example: 'John' }),
+  lastName: z.string().nullable().openapi({ example: 'Doe' }),
+  email: z
+    .string()
+    .email()
+    .nullable()
+    .openapi({ example: 'john.doe@example.com' }),
+  phone: PhoneNumberData.nullable().optional().openapi({ example: null }),
+  type: z
+    .nativeEnum(AccountContactType)
+    .openapi({ example: AccountContactType.GENERAL }),
+  accountId: accountIdSchema.openapi({
+    example: 'account_01je6ht4b8fbmttkzh2hs82xqp',
+  }),
+  account: AccountZod.optional().nullable(),
+  referenceLink: z.string().nullable().optional(),
+});
+export type IAccountContact = z.infer<typeof IAccountContact>;
+
+export const PatchAccountContactZod = z.object({
+  title: z
+    .string()
+    .min(1)
+    .max(50)
+    .nullable()
+    .optional()
+    .openapi({ example: 'Mr' }),
+  firstName: z.string().min(1).max(150).openapi({ example: 'John' }),
+  lastName: z.string().min(1).max(150).openapi({ example: 'Doe' }),
+  email: z.string().email().openapi({ example: 'john.doe@example.com' }),
+  phone: PhoneZodSchema.nullable()
+    .optional()
+    .openapi({ example: '+12124567890' }),
+});
+
+export type PatchAccountContactZod = z.infer<typeof PatchAccountContactZod>;
+
+export const CompliancePatchAccountContactZod = PatchAccountContactZod.extend({
+  accountId: accountIdSchema.openapi({
+    example: 'account_01je6ht4b8fbmttkzh2hs82xqp',
+  }),
+  referenceLink: z
+    .string()
+    .url()
+    .max(2048)
+    .nullable()
+    .optional()
+    .openapi({ example: 'https://www.google.com' }),
+});
+export type CompliancePatchAccountContactZod = z.infer<
+  typeof CompliancePatchAccountContactZod
+>;
+
+export const IPaginatedAccountContact = z.object({
+  items: z.array(IAccountContact),
+  meta: IPaginationMeta,
+});
+export type IPaginatedAccountContact = z.infer<typeof IPaginatedAccountContact>;
+
+export const AccountContactDeleteResponse = z.object({
+  status: z.enum(['pass', 'fail']),
+});
+export type AccountContactDeleteResponse = z.infer<
+  typeof AccountContactDeleteResponse
+>;

package/common/types/account-detail.types.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { IAsset } from './asset.types';
+import { IIssuer } from './issuer.types';
+import { IOffering } from './offering.types';
+import { IIssuerPaymentMethod } from './issuer-payment-method.types';
+import { SiteZod } from './site.types';
+import { IPage } from './page.types';
+
+export const AccountDetailSummaryZod = z.object({
+  id: z.string(),
+  name: z.string(),
+  issuers: z.array(
+    IIssuer.extend({
+      offerings: z.lazy(() =>
+        z.array(
+          IOffering.extend({
+            assets: z.lazy(() => z.array(IAsset)),
+          }),
+        ),
+      ),
+      paymentMethods: z.lazy(() => z.array(IIssuerPaymentMethod)),
+    }),
+  ),
+  sites: z.lazy(() => z.array(SiteZod)),
+  pages: z.lazy(() => z.array(IPage)),
+});
+export type AccountDetailSummaryZod = z.infer<typeof AccountDetailSummaryZod>;

package/common/types/account-integration.types.ts

@@ -0,0 +1,143 @@
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { TypeID } from 'typeid-js';
+import { z } from 'zod';
+import { IBaseEntity } from './entity.types';
+import { accountIdSchema } from './account.types';
+import { IPaginationMeta } from './common.types';
+
+extendZodWithOpenApi(z);
+
+export enum IntegrationType {
+  RAISI = 'RAISI',
+}
+
+export const accountIntegrationIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'account_integration';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid account integration ID format. Must be a valid TypeID with "account_integration" prefix.',
+  },
+);
+
+export const AccountIntegrationZod = IBaseEntity.extend({
+  id: accountIntegrationIdSchema,
+  name: z.string(),
+  integration: z.nativeEnum(IntegrationType),
+  description: z.string().nullable(),
+  partnerId: z.string().nullable(),
+  url: z.string().nullable(),
+  webhook: z.string().nullable(),
+  active: z.boolean(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+  accountId: z.lazy(() => accountIdSchema),
+});
+export type AccountIntegrationZod = z.infer<typeof AccountIntegrationZod>;
+
+export const IPaginatedAccountIntegration = z.object({
+  items: z.array(AccountIntegrationZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedAccountIntegration = z.infer<
+  typeof IPaginatedAccountIntegration
+>;
+
+export const PostAccountIntegrationZod = z.object({
+  name: z.string().min(1).max(100).openapi({ example: 'Raisi' }),
+  integration: z
+    .nativeEnum(IntegrationType)
+    .openapi({ example: IntegrationType.RAISI }),
+  description: z
+    .string()
+    .min(1)
+    .max(1000)
+    .nullable()
+    .optional()
+    .openapi({ example: 'Raisi integration' }),
+  partnerId: z
+    .string()
+    .min(1)
+    .max(100)
+    .nullable()
+    .optional()
+    .openapi({ example: '1234567890' }),
+  url: z
+    .string()
+    .url()
+    .nullable()
+    .optional()
+    .openapi({ example: 'https://www.raisi.com' }),
+  webhook: z
+    .string()
+    .url()
+    .nullable()
+    .optional()
+    .openapi({ example: 'https://www.raisi.com/webhook' }),
+  active: z.boolean().default(true).openapi({ example: true }),
+  metadata: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .optional()
+    .openapi({ example: { key: 'value' } }),
+});
+export type PostAccountIntegrationZod = z.infer<
+  typeof PostAccountIntegrationZod
+>;
+
+export const PatchAccountIntegrationZod = z.object({
+  name: z
+    .string()
+    .min(1)
+    .max(100)
+    .nullable()
+    .optional()
+    .openapi({ example: 'Raisi' }),
+  integration: z
+    .nativeEnum(IntegrationType)
+    .optional()
+    .openapi({ example: IntegrationType.RAISI }),
+  description: z
+    .string()
+    .min(1)
+    .max(1000)
+    .nullable()
+    .optional()
+    .openapi({ example: 'Raisi integration' }),
+  partnerId: z.string().min(1).max(100).nullable().optional(),
+  url: z
+    .string()
+    .url()
+    .nullable()
+    .optional()
+    .openapi({ example: 'https://www.raisi.com' }),
+  webhook: z
+    .string()
+    .url()
+    .nullable()
+    .optional()
+    .openapi({ example: 'https://www.raisi.com/webhook' }),
+  active: z.boolean().nullable().optional(),
+  metadata: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .optional()
+    .openapi({ example: { key: 'value' } }),
+});
+export type PatchAccountIntegrationZod = z.infer<
+  typeof PatchAccountIntegrationZod
+>;
+
+export const AccountIntegrationFiltersZod = z.object({
+  search: z.string().max(50).optional(),
+  integration: z.nativeEnum(IntegrationType).optional(),
+  active: z.boolean().optional(),
+});
+export type AccountIntegrationFiltersZod = z.infer<
+  typeof AccountIntegrationFiltersZod
+>;

package/common/types/account-manager.types.ts

@@ -0,0 +1,114 @@
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { z } from 'zod';
+import { TypeID } from 'typeid-js';
+import { IBaseEntity } from './entity.types';
+import { PhoneNumberData } from './sms.types';
+import { userIdSchema, UserZod } from './user.types';
+import { IPaginationMeta } from './common.types';
+import { PhoneZodSchema } from './phone.type';
+
+extendZodWithOpenApi(z);
+export const accountManagerIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'account_manager';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: `Invalid account manager ID format. Must be a valid TypeID with "account_manager" prefix. Example: account_manager_01j5y5ghx5fg68d663j1fvy2x7`,
+  },
+);
+
+export const accountManagersInclude = z.enum(['accounts', 'user']);
+
+/**
+ * @description Query parameters for including related entities
+ * @xample in contract us as -> query: z.object({}).merge(AccountManagersIncludeQuery),
+ */
+export const AccountManagersIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          accountManagersInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include option provided. Valid options are: ${accountManagersInclude.options.join(',')}`,
+      },
+    )
+    .openapi({
+      example: `${accountManagersInclude.options.join(',')}`,
+    }),
+});
+
+export const IAccountManagerZod = IBaseEntity.extend({
+  firstName: z.string().openapi({ example: 'John' }),
+  lastName: z.string().openapi({ example: 'Doe' }),
+  email: z.string().email().openapi({ example: 'john.doe@example.com' }),
+  phone: PhoneNumberData.nullable().openapi({ example: '+12124567890' }),
+  isDefault: z.boolean().openapi({ example: false }),
+  userId: z
+    .lazy(() => userIdSchema)
+    .nullable()
+    .openapi({ example: 'user_01je6ht4b8fbmttkzh2hs82xqp' }),
+  user: z
+    .lazy(() => UserZod)
+    .optional()
+    .nullable(),
+});
+
+export type IAccountManagerZod = z.infer<typeof IAccountManagerZod>;
+
+export const PostAccountManagerZod = 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' }),
+  phone: PhoneZodSchema.nullable()
+    .optional()
+    .openapi({ example: '+12124567890' }),
+  isDefault: z.boolean().openapi({ example: false }),
+});
+
+export type PostAccountManagerZod = z.infer<typeof PostAccountManagerZod>;
+
+export const PatchAccountManagerZod = z.object({
+  firstName: z.string().min(1).max(255).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' }),
+  phone: PhoneZodSchema.nullable()
+    .optional()
+    .openapi({ example: '+12124567890' }),
+  isDefault: z.boolean().optional().openapi({ example: false }),
+});
+export type PatchAccountManagerZod = z.infer<typeof PatchAccountManagerZod>;
+
+export const IPaginatedAccountManager = z.object({
+  items: z.array(IAccountManagerZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedAccountManager = z.infer<typeof IPaginatedAccountManager>;
+
+export const AccountManagerDeleteResponse = z.object({
+  status: z.boolean().openapi({ example: true }),
+});
+export type AccountManagerDeleteResponse = z.infer<
+  typeof AccountManagerDeleteResponse
+>;
+export const SetDefaultAccountManagerForAllAccountsResponse = z.object({
+  message: z
+    .string()
+    .openapi({ example: 'Default account manager set for all accounts' }),
+});
+export type SetDefaultAccountManagerForAllAccountsResponse = z.infer<
+  typeof SetDefaultAccountManagerForAllAccountsResponse
+>;

package/common/types/account.types.ts

@@ -0,0 +1,239 @@
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { TypeID } from 'typeid-js';
+import { z } from 'zod';
+import {
+  AccountZod,
+  dateSchema,
+  IPaginationMeta,
+  IssuerOnboardingSetupType,
+  ManagedByType,
+  Platform,
+  SortBy,
+  SortOrder,
+  AccountStatus,
+} from './common.types';
+import { notionPageIdSchema } from './notion-page.types';
+
+extendZodWithOpenApi(z);
+
+export const accountIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'account';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message:
+      'Invalid account ID format. Must be a valid TypeID with "account" prefix.',
+  },
+);
+
+export const UpdateAccountZod = z.object({
+  name: z.string().min(1).max(100),
+  status: z.nativeEnum(AccountStatus).optional(),
+  platform: z
+    .nativeEnum(Platform)
+    .optional()
+    .openapi({ example: Platform.INTEGRATION }),
+  managedBy: z
+    .nativeEnum(ManagedByType)
+    .optional()
+    .openapi({ example: ManagedByType.DALMORE }),
+  approversCount: z.number().min(1).max(5).optional(),
+});
+export type UpdateAccountZod = z.infer<typeof UpdateAccountZod>;
+
+export const CreateAccountZod = z.object({
+  name: z.string().min(1).max(100),
+  platform: z
+    .nativeEnum(Platform)
+    .optional()
+    .openapi({ example: Platform.INTEGRATION }),
+  managedBy: z
+    .nativeEnum(ManagedByType)
+    .optional()
+    .openapi({ example: ManagedByType.DALMORE }),
+  approversCount: z.number().min(1).max(5).optional(),
+});
+export type CreateAccountZod = z.infer<typeof CreateAccountZod>;
+
+export const IPaginatedAccount = z.object({
+  items: z.array(AccountZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedAccount = z.infer<typeof IPaginatedAccount>;
+
+export const AccountFiltersZod = z.object({
+  search: z.string().max(50).optional(),
+  status: z.nativeEnum(AccountStatus).optional(),
+  platform: z
+    .nativeEnum(Platform)
+    .optional()
+    .openapi({ example: Platform.INTEGRATION }),
+  managedBy: z
+    .nativeEnum(ManagedByType)
+    .optional()
+    .openapi({ example: ManagedByType.DALMORE }),
+  from: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
+  to: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
+});
+
+const accountsInclude = z.enum([
+  'accountManager',
+  'accountIntegrations',
+  'apiKeys',
+  'assets',
+  'dataRooms',
+  'individuals',
+  'investorAccounts',
+  'invites',
+  'issuers',
+  'legalEntities',
+  'offerings',
+  'sites',
+  'trades',
+  'users',
+]);
+
+/**
+ * @description Query parameters for including related entities
+ * @xample in contract us as -> query: z.object({}).merge(AccountsIncludeQuery),
+ */
+export const AccountsIncludeQuery = z.object({
+  include: z
+    .string()
+    .optional()
+    .transform((str) => (str ? str.split(',') : []))
+    .refine(
+      (includes) =>
+        includes.every((include) =>
+          accountsInclude.options.includes(include as any),
+        ),
+      {
+        message: `Invalid include option provided. Valid options are: ${accountsInclude.options.join(',')}`,
+      },
+    )
+    .openapi({
+      example: `${accountsInclude.options.join(',')}`,
+    }),
+});
+export interface AccountsIncludeQuery
+  extends z.infer<typeof AccountsIncludeQuery> {}
+
+export const PatchAccountZod = z.object({
+  name: z.string().min(1).max(100),
+  approversCount: z.number().min(1).max(5).optional(),
+  managedBy: z.nativeEnum(ManagedByType).optional(),
+  platform: z.nativeEnum(Platform).optional(),
+  integrationGuideId: notionPageIdSchema.nullable().optional(),
+  productPrimaries: z.boolean().optional(),
+  productSecondaries: z.boolean().optional(),
+  featureDisbursements: z.boolean().optional(),
+});
+export type PatchAccountZod = z.infer<typeof PatchAccountZod>;
+
+export const PostAccountResponse = z.object({
+  id: z.string(),
+});
+export type PostAccountResponse = z.infer<typeof PostAccountResponse>;
+
+export const GetAccountIssuersZod = z.object({
+  name: z.string().optional(),
+  accountId: accountIdSchema.optional(),
+});
+export type GetAccountIssuersZod = z.infer<typeof GetAccountIssuersZod>;
+
+export const UpdateAccountIssuersStatusZod = z.object({
+  status: z.nativeEnum(AccountStatus),
+});
+export type UpdateAccountIssuersStatusZod = z.infer<
+  typeof UpdateAccountIssuersStatusZod
+>;
+
+export const UpdateAccountStatusReponse = z.object({
+  id: accountIdSchema,
+  status: z.nativeEnum(AccountStatus),
+});
+export type UpdateAccountStatusReponse = z.infer<
+  typeof UpdateAccountStatusReponse
+>;
+
+export const AccountsSummaryFilterZod = z.object({
+  search: z.string().trim().max(50).optional(),
+  status: z.nativeEnum(AccountStatus).optional(),
+  from: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
+  to: dateSchema.optional().openapi({ example: 'MM/DD/YYYY' }),
+});
+export type AccountsSummaryFilterZod = z.infer<typeof AccountsSummaryFilterZod>;
+
+export const AccountSortZod = z.object({
+  sort: z.enum([SortBy.NAME, SortBy.CREATED_AT, SortBy.UPDATED_AT]).optional(),
+  dir: z.nativeEnum(SortOrder).optional(),
+});
+export type AccountSortZod = z.infer<typeof AccountSortZod>;
+
+export const AccountsSummaryZod = z.object({
+  accountId: accountIdSchema,
+  accountName: z.string(),
+  issuers: z.number().int(),
+  offerings: z.number().int(),
+  assets: z.number().int(),
+  users: z.number().int(),
+  createdOn: z.string(),
+  status: z.string(),
+});
+export type AccountsSummaryZod = z.infer<typeof AccountsSummaryZod>;
+
+export const IPaginatedAccountsSummaryResponse = z.object({
+  items: z.array(AccountsSummaryZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedAccountsSummaryResponse = z.infer<
+  typeof IPaginatedAccountsSummaryResponse
+>;
+export const PatchIssuerOnboardingStep = z.object({
+  step: z.nativeEnum(IssuerOnboardingSetupType),
+});
+export type PatchIssuerOnboardingStep = z.infer<
+  typeof PatchIssuerOnboardingStep
+>;
+
+export const IssuerOnboardingStepZod = z.object({
+  offeringSetup: z.boolean().default(false),
+  investorPortalSetup: z.boolean().default(false),
+  paymentMethodSetup: z.boolean().default(false),
+  accountContactsSetup: z.boolean().default(false),
+});
+export type IssuerOnboardingStepZod = z.infer<typeof IssuerOnboardingStepZod>;
+
+export const OnboardingAccountSummaryZod = z.object({
+  accountId: accountIdSchema,
+  accountName: z.string(),
+  siteId: z.string().nullable(),
+  offeringId: z.string().nullable(),
+  investorPortalSetup: z.boolean(),
+  offeringSetup: z.boolean(),
+  paymentMethodSetup: z.boolean(),
+  accountContactsSetup: z.boolean(),
+});
+export type OnboardingAccountSummaryZod = z.infer<
+  typeof OnboardingAccountSummaryZod
+>;
+
+export const IPaginatedOnboardingAccountSummaryResponse = z.object({
+  items: z.array(OnboardingAccountSummaryZod),
+  meta: IPaginationMeta,
+});
+export type IPaginatedOnboardingAccountSummaryResponse = z.infer<
+  typeof IPaginatedOnboardingAccountSummaryResponse
+>;
+
+export const OnboardingAccountSummaryFilterZod = z.object({
+  status: z.nativeEnum(AccountStatus).optional(),
+});
+export type OnboardingAccountSummaryFilterZod = z.infer<
+  typeof OnboardingAccountSummaryFilterZod
+>;