@dalmore/api-contracts 1.0.5 → 1.0.6

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

@@ -0,0 +1,316 @@
+import { z } from 'zod';
+import { ComplyAdvantageStatus } from './comply-advantage.types';
+
+/**
+ * POST /searches - Create a new search
+ * @see https://docs.complyadvantage.com/api-docs/#creating-searches
+ */
+export const CreateSearchRequestSchema = z.object({
+  search_term: z.union([
+    z.string(),
+    z.object({
+      first_name: z.string().optional(),
+      middle_names: z.string().optional(),
+      last_name: z.string(),
+    }),
+  ]),
+  client_ref: z.string().max(255).optional(),
+  search_profile: z.string().optional(),
+  fuzziness: z.number().min(0).max(1).optional(),
+  offset: z.number().int().optional(),
+  limit: z.number().int().max(100).optional(),
+  filters: z
+    .object({
+      types: z.array(z.string()).optional(),
+      birth_year: z.union([z.string(), z.number()]).optional(),
+      remove_deceased: z.union([z.literal('0'), z.literal('1')]).optional(),
+      country_codes: z.array(z.string()).optional(),
+      entity_type: z
+        .enum(['person', 'company', 'organisation', 'vessel', 'aircraft'])
+        .optional(),
+    })
+    .optional(),
+  tags: z.record(z.string()).optional(),
+  share_url: z.union([z.literal(0), z.literal(1)]).optional(),
+  exact_match: z.boolean().optional(),
+});
+
+export type CreateSearchRequest = z.infer<typeof CreateSearchRequestSchema>;
+
+/**
+ * Entity model returned in search results
+ * @see https://docs.complyadvantage.com/api-docs/#concepts
+ */
+export const EntitySchema = z
+  .object({
+    id: z.string(),
+    entity_type: z.string().optional(),
+    last_updated_utc: z.string().optional(),
+    name: z.string(),
+    first_name: z.string().optional(),
+    middle_name: z.string().optional(),
+    last_name: z.string().optional(),
+    sources: z.array(z.string()).optional(),
+    types: z.array(z.string()).optional(),
+    fields: z
+      .array(
+        z.object({
+          name: z.string(),
+          tag: z.string().optional(),
+          value: z.string(),
+          source: z.string().optional(),
+          locale: z.string().optional(),
+        }),
+      )
+      .optional(),
+    aka: z
+      .array(
+        z.object({
+          name: z.string(),
+        }),
+      )
+      .optional(),
+    associates: z
+      .array(
+        z.object({
+          name: z.string(),
+          association: z.string().optional(),
+        }),
+      )
+      .optional(),
+    media: z
+      .array(
+        z.object({
+          date: z.string().optional(),
+          snippet: z.string().optional(),
+          title: z.string().optional(),
+          url: z.string(),
+          pdf_url: z.string().optional(),
+        }),
+      )
+      .optional(),
+    source_notes: z
+      .record(
+        z.object({
+          aml_types: z.array(z.string()).optional(),
+          country_codes: z.array(z.string()).optional(),
+          listing_started_utc: z.string().optional(),
+          listing_ended_utc: z.string().optional(),
+          name: z.string().optional(),
+          source_id: z.string().optional(),
+          url: z.string().optional(),
+        }),
+      )
+      .optional(),
+    keywords: z.array(z.string()).optional(),
+    assets: z
+      .array(
+        z.object({
+          public_url: z.string().optional(),
+          source: z.string().optional(),
+          type: z.string().optional(),
+          url: z.string(),
+        }),
+      )
+      .optional(),
+  })
+  .passthrough();
+
+export type Entity = z.infer<typeof EntitySchema>;
+
+/**
+ * Hit model - individual search result entity with metadata
+ * @see https://docs.complyadvantage.com/api-docs/#creating-searches
+ */
+export const HitSchema = z.object({
+  doc: EntitySchema,
+  is_whitelisted: z.boolean().optional(),
+  match_types: z.array(z.string()),
+  match_types_details: z.any().optional(),
+  score: z.number(),
+  match_status: z.nativeEnum(ComplyAdvantageStatus).optional(),
+  risk_level: z.enum(['low', 'medium', 'high', 'unknown']).optional(),
+});
+
+export type Hit = z.infer<typeof HitSchema>;
+
+/**
+ * Search profile information
+ * @see https://docs.complyadvantage.com/api-docs/#creating-searches
+ */
+export const SearchProfileSchema = z.object({
+  name: z.string(),
+  slug: z.string(),
+});
+
+export type SearchProfile = z.infer<typeof SearchProfileSchema>;
+
+/**
+ * User information
+ * @see https://docs.complyadvantage.com/api-docs/#other-endpoints
+ */
+export const UserSchema = z.object({
+  id: z.number(),
+  email: z.string(),
+  name: z.string(),
+  phone: z.string().nullable(),
+  created_at: z.string(),
+  user_is_active: z.boolean().optional(),
+});
+
+export type User = z.infer<typeof UserSchema>;
+
+/**
+ * POST /searches response - Create search response
+ * @see https://docs.complyadvantage.com/api-docs/#creating-searches
+ */
+export const CreateSearchResponseSchema = z.object({
+  status: z.enum(['success', 'failure']),
+  code: z.number().optional(),
+  content: z.object({
+    data: z.object({
+      id: z.number(),
+      ref: z.string(),
+      searcher_id: z.number(),
+      assignee_id: z.number(),
+      search_profile: SearchProfileSchema.optional(),
+      filters: z
+        .object({
+          entity_type: z.string().optional(),
+          types: z.array(z.string()).optional(),
+          birth_year: z.union([z.string(), z.number()]).optional(),
+          passport: z.string().optional(),
+          exact_match: z.boolean().optional(),
+          fuzziness: z.number().optional(),
+          country_codes: z.array(z.string()).optional(),
+          remove_deceased: z.number().optional(),
+        })
+        .optional(),
+      match_status: z.nativeEnum(ComplyAdvantageStatus),
+      risk_level: z.enum(['low', 'medium', 'high', 'unknown']),
+      search_term: z.string(),
+      submitted_term: z.string().optional(),
+      client_ref: z.string().optional(),
+      total_hits: z.number(),
+      total_matches: z.number(),
+      updated_at: z.string(),
+      created_at: z.string(),
+      tags: z.record(z.string()).optional(),
+      labels: z
+        .array(
+          z.object({
+            type: z.string(),
+            name: z.string(),
+            value: z.string(),
+          }),
+        )
+        .optional(),
+      blacklist_filters: z
+        .object({
+          blacklist_ids: z.array(z.string()),
+        })
+        .optional(),
+      total_blacklist_hits: z.number().optional(),
+      limit: z.number().optional(),
+      offset: z.number().optional(),
+      share_url: z.string().optional(),
+      searcher: UserSchema.optional(),
+      assignee: UserSchema.optional(),
+      hits: z.array(HitSchema).optional(),
+      blacklist_hits: z.array(z.any()).optional(),
+    }),
+  }),
+  message: z.string().optional(),
+});
+
+export type CreateSearchResponse = z.infer<typeof CreateSearchResponseSchema>;
+
+/**
+ * GET /searches/{ref}/entities/comply - Get search entities response
+ * @see https://docs.complyadvantage.com/api-docs/#get-searchesrefentitiesentity_provider
+ */
+export const GetSearchEntitiesResponseSchema = z.array(HitSchema);
+
+export type GetSearchEntitiesResponse = z.infer<
+  typeof GetSearchEntitiesResponseSchema
+>;
+
+/**
+ * GET /searches/{ref}/details - Get search details response
+ * @see https://docs.complyadvantage.com/api-docs/#get-searchesiddetails
+ */
+export const GetSearchDetailsResponseSchema = z.object({
+  code: z.number(),
+  status: z.enum(['success', 'failure']),
+  content: z.object({
+    data: z.object({
+      id: z.number(),
+      ref: z.string(),
+      searcher_id: z.number(),
+      assignee_id: z.number(),
+      filters: z
+        .object({
+          country_codes: z.array(z.string()).optional(),
+          remove_deceased: z.number().optional(),
+          types: z.array(z.string()).optional(),
+          exact_match: z.boolean().optional(),
+          fuzziness: z.number().optional(),
+          birth_year: z.union([z.string(), z.number()]).optional(),
+          entity_type: z.string().optional(),
+        })
+        .optional(),
+      match_status: z.nativeEnum(ComplyAdvantageStatus),
+      risk_level: z.enum(['low', 'medium', 'high', 'unknown']),
+      search_term: z.string(),
+      submitted_term: z.string().optional(),
+      client_ref: z.string().optional(),
+      total_hits: z.number(),
+      total_matches: z.number(),
+      updated_at: z.string(),
+      created_at: z.string(),
+      tags: z.record(z.string()).optional(),
+      labels: z
+        .array(
+          z.object({
+            type: z.string(),
+            name: z.string(),
+            value: z.string(),
+          }),
+        )
+        .optional(),
+      blacklist_filters: z
+        .object({
+          blacklist_ids: z.array(z.string()),
+        })
+        .optional(),
+      total_blacklist_hits: z.number().optional(),
+      limit: z.number().optional(),
+      offset: z.number().optional(),
+      search_profile: SearchProfileSchema.optional(),
+      searcher: UserSchema.optional(),
+      assignee: UserSchema.optional(),
+      hits: z.array(HitSchema),
+      blacklist_hits: z.array(z.any()).optional(),
+      share_url: z.string().optional(),
+    }),
+  }),
+  message: z.string().optional(),
+});
+
+export type GetSearchDetailsResponse = z.infer<
+  typeof GetSearchDetailsResponseSchema
+>;
+
+/**
+ * PATCH /searches/{ref} - Update search request
+ * @see https://docs.complyadvantage.com/api-docs/#patch-searchesid
+ */
+export const UpdateSearchRequestSchema = z.object({
+  match_status: z.nativeEnum(ComplyAdvantageStatus).optional(),
+  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(),
+});
+
+export type UpdateSearchRequest = z.infer<typeof UpdateSearchRequestSchema>;

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

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+export enum ComplyAdvantageStatus {
+  FALSE_POSITIVE = 'false_positive',
+  TRUE_POSITIVE = 'true_positive',
+  POTENTIAL_MATCH = 'potential_match',
+  NO_MATCH = 'no_match',
+  UNKNOWN = 'unknown',
+  TRUE_POSITIVE_APPROVE = 'true_positive_approve',
+  TRUE_POSITIVE_REJECT = 'true_positive_reject',
+}
+
+export const ComplyAdvantageResponseSchema = z.object({
+  status: z.enum(['success', 'failure']),
+  content: z.object({
+    data: z.object({
+      match_status: z.nativeEnum(ComplyAdvantageStatus),
+    }),
+  }),
+  message: z.string().optional(),
+});
+
+export type ComplyAdvantageResponseSchema = z.infer<
+  typeof ComplyAdvantageResponseSchema
+>;

package/src/common/types/contact-us.types.ts

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import { extendZodWithOpenApi } from '@anatine/zod-openapi';
+import { TypeID } from 'typeid-js';
+import { BaseContactUsOptions, createUrlSchema } from './common.types';
+extendZodWithOpenApi(z);
+
+export const contactUsIdSchema = z.string().refine(
+  (value) => {
+    try {
+      const tid = TypeID.fromString(value);
+      return tid.getType() === 'contact_us';
+    } catch {
+      return false;
+    }
+  },
+  {
+    message: `Invalid contact_us ID format. Must be a valid TypeID with "contact_us" prefix. Example: contact_us_01j5y5ghx5fg68d663j1fvy2x7`,
+  },
+);
+
+export enum InvestorContactOptions {
+  ISSUER = BaseContactUsOptions.ISSUER,
+  TECHNICAL_SUPPORT = BaseContactUsOptions.TECHNICAL_SUPPORT,
+}
+
+export enum PublicIssuerContactOptions {
+  TECHNICAL_SUPPORT = BaseContactUsOptions.TECHNICAL_SUPPORT,
+  SALES = BaseContactUsOptions.SALES,
+  ACCOUNT_MANAGER = BaseContactUsOptions.ACCOUNT_MANAGER,
+}
+
+export enum IssuerContactOptions {
+  TECHNICAL_SUPPORT = BaseContactUsOptions.TECHNICAL_SUPPORT,
+  ACCOUNT_MANAGER = BaseContactUsOptions.ACCOUNT_MANAGER,
+}
+
+export const PostContactUsZod = z.object({
+  contactOption: z
+    .nativeEnum(IssuerContactOptions)
+    .openapi({ example: IssuerContactOptions.TECHNICAL_SUPPORT }),
+  subject: z.string().min(1).max(60).openapi({ example: 'subject' }),
+  message: z.string().min(1).max(1000).openapi({ example: 'message' }),
+});
+export type PostContactUsZod = z.infer<typeof PostContactUsZod>;
+
+export const PostContactUsResponse = z.object({
+  message: z.string(),
+});
+export type PostContactUsResponse = z.infer<typeof PostContactUsResponse>;
+export const InvestorPostContactUsZod = PostContactUsZod.extend({
+  contactOption: z.nativeEnum(InvestorContactOptions).openapi({
+    example: InvestorContactOptions.TECHNICAL_SUPPORT,
+  }),
+});
+export type InvestorPostContactUsZod = z.infer<typeof InvestorPostContactUsZod>;
+
+export const PublicInvestorContactUsZod = PostContactUsZod.extend({
+  email: z.string().email().openapi({ example: 'email@example.com' }),
+  firstName: z.string().min(1).max(100).openapi({ example: 'John' }),
+  lastName: z.string().min(1).max(100).openapi({ example: 'Doe' }),
+  contactOption: z.nativeEnum(InvestorContactOptions).openapi({
+    example: InvestorContactOptions.TECHNICAL_SUPPORT,
+  }),
+  url: createUrlSchema({ strict: true }).openapi({
+    example: 'test-dev.test.com',
+  }),
+  turnstileToken: z
+    .string()
+    .min(1)
+    .max(10000)
+    .openapi({ example: '0.WdnEAAAAAIjVJHV...8V1ffXx0Q' }),
+});
+export type PublicInvestorContactUsZod = z.infer<
+  typeof PublicInvestorContactUsZod
+>;
+
+export const PublicIssuerContactUsZod = PostContactUsZod.extend({
+  email: z.string().email().openapi({ example: 'email@example.com' }),
+  firstName: z.string().min(1).max(100).openapi({ example: 'John' }),
+  lastName: z.string().min(1).max(100).openapi({ example: 'Doe' }),
+  contactOption: z.nativeEnum(PublicIssuerContactOptions).openapi({
+    example: PublicIssuerContactOptions.TECHNICAL_SUPPORT,
+  }),
+  turnstileToken: z
+    .string()
+    .min(1)
+    .max(10000)
+    .openapi({ example: '0.WdnEAAAAAIjVJHV...8V1ffXx0Q' }),
+});
+
+export type PublicIssuerContactUsZod = z.infer<typeof PublicIssuerContactUsZod>;
+
+export const HandleContactOptionZod = z.object({
+  email: z.string().email().openapi({ example: 'email@example.com' }),
+  accountId: z.string().optional().nullable().openapi({ example: 'accountId' }),
+  senderName: z
+    .string()
+    .optional()
+    .nullable()
+    .openapi({ example: 'senderName' }),
+  senderEmail: z
+    .string()
+    .optional()
+    .nullable()
+    .openapi({ example: 'senderEmail' }),
+});
+export type HandleContactOptionZod = z.infer<typeof HandleContactOptionZod>;

package/src/common/types/contract-helpers.ts

@@ -0,0 +1,205 @@
+/**
+ * Contract helpers - minimal subset for API contracts package
+ * This file is copied directly to @dalmore/api-contracts
+ */
+import { HttpStatus } from '@nestjs/common';
+import parsePhoneNumberFromString, {
+  CountryCode,
+  PhoneNumber,
+} from 'libphonenumber-js';
+import { err, ok, Result } from 'neverthrow';
+import { ErrorResult } from './common.types';
+
+/**
+ * Validates a US zip code format (12345 or 12345-6789)
+ */
+export const validateUSZipCode = (zipCode: string): boolean => {
+  const regex = /^[0-9]{5}(?:-[0-9]{4})?$/;
+  return regex.test(zipCode);
+};
+
+/**
+ * Validates a Canadian postal code format (A1A 1A1)
+ */
+export const validateCanadaZipCode = (zipCode: string): boolean => {
+  const regex = /^[A-Za-z]\d[A-Za-z] \d[A-Za-z]\d$/;
+  return regex.test(zipCode);
+};
+
+/**
+ * Normalizes a short date string (M/D/YY or M/D/YYYY) to MM/DD/YYYY format
+ */
+export function normalizeShortDate(input: string): string {
+  const [month, day, year] = input.split('/');
+
+  if (!month || !day || !year) {
+    throw new Error('Invalid date format');
+  }
+
+  const paddedMonth = month.padStart(2, '0');
+  const paddedDay = day.padStart(2, '0');
+  const fullYear = year.length === 2 ? `20${year}` : year;
+
+  return `${paddedMonth}/${paddedDay}/${fullYear}`;
+}
+
+/**
+ * Converts a string into a URL-safe slug
+ */
+export function slugify(input: string, exclude: boolean = false): string {
+  if (exclude) {
+    const excludeWords = ['llc', 'inc', 'corp', 'co'];
+    const negativeWordsList = [
+      'www',
+      'api',
+      'admin',
+      'dashboard',
+      'auth',
+      'cdn',
+      'static',
+      'blog',
+      'support',
+      'status',
+      'mail',
+      'smtp',
+      'ftp',
+      'ssh',
+      'login',
+      'register',
+      'signup',
+      'account',
+      'accounts',
+      'user',
+      'users',
+      'profile',
+      'settings',
+      'help',
+      'docs',
+      'documentation',
+      'developer',
+      'developers',
+      'app',
+      'apps',
+      'test',
+      'demo',
+      'staging',
+      'dev',
+      'prod',
+      'production',
+      'beta',
+      'alpha',
+      'portal',
+      'portals',
+      'client',
+      'clients',
+      'investor',
+      'investors',
+      'issuer',
+      'issuers',
+      'compliance',
+      'offering',
+      'offerings',
+      'trade',
+      'trades',
+    ];
+
+    let slug = input
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, '')
+      .replace(/[\s_-]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+
+    excludeWords.forEach((word) => {
+      slug = slug.replace(new RegExp(`-${word}$`, 'i'), '');
+    });
+
+    if (negativeWordsList.includes(slug)) {
+      return 'new-account';
+    }
+
+    return slug;
+  }
+
+  return input
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+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}
+\`\`\``;
+};
+
+/**
+ * Normalizes a phone number to E.164 format
+ */
+export function normalizePhoneNumber(
+  phoneNumber: string,
+  countryCode: CountryCode,
+): Result<PhoneNumber, ErrorResult> {
+  const parsedPhoneNumber = parsePhoneNumberFromString(
+    phoneNumber,
+    countryCode,
+  );
+
+  if (!parsedPhoneNumber || !parsedPhoneNumber.isValid()) {
+    return err({
+      status: HttpStatus.BAD_REQUEST,
+      message: 'Invalid phone number. Only numbers',
+    });
+  }
+  return ok(parsedPhoneNumber);
+}