@dalmore/api-contracts 1.0.0

package/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/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/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>;