@dalmore/api-contracts 0.0.0-dev.2dc8e92

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/helpers/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Contract helpers - minimal subset for API documentation generation
+ */
+
+type CurlOptions = {
+  query?: Record<string, string>;
+  headers?: Record<string, string>;
+  body?: Record<string, unknown>;
+  formData?: Record<string, string>;
+};
+
+export const authHeader: CurlOptions['headers'] = {
+  Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
+};
+
+const generateCurlExample = (
+  method: string,
+  path: string,
+  options: CurlOptions,
+) => {
+  const baseUrl = 'https://dalmore-client-portal-api-prod.onrender.com/api/v1';
+  let curl = `curl -X ${method.toUpperCase()} '${baseUrl}${path}`;
+  if (options.query) {
+    const queryString = new URLSearchParams(options.query).toString();
+    curl += `?${queryString}`;
+  }
+  curl += "'";
+  if (options.headers) {
+    Object.entries(options.headers).forEach(([key, value]) => {
+      curl += ` \\\n  --header '${key}: ${value}'`;
+    });
+  }
+  if (options.body) {
+    curl += ` \\\n  --header 'Content-Type: application/json'`;
+    curl += ` \\\n  --data '${JSON.stringify(options.body)}'`;
+  }
+  if (options.formData) {
+    Object.entries(options.formData).forEach(([key, value]) => {
+      curl += ` \\\n  --form '${key}=${value}'`;
+    });
+  }
+  return curl;
+};
+
+export const generateApiDescription = (
+  summary: string,
+  method: string,
+  path: string,
+  options: CurlOptions,
+) => {
+  const curlExample = generateCurlExample(method, path, options);
+  return `${summary}
+
+### Example curl request
+
+\`\`\`bash
+${curlExample}
+\`\`\``;
+};

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,124 @@
+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
+>;
+
+export const AccountManagerDeleteQuery = z.object({
+  reassignTo: accountManagerIdSchema
+    .nullable()
+    .optional()
+    .openapi({ example: 'account_manager_01j5y5ghx5fg68d663j1fvy2x7' }),
+});
+export type AccountManagerDeleteQuery = z.infer<
+  typeof AccountManagerDeleteQuery
+>;