@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/models/Client.ts

@@ -0,0 +1,363 @@
+/**
+ * Base Client Model
+ *
+ * Pure data model with no API calls.
+ * Provides type-safe access to common client properties.
+ */
+
+import { BaseModel } from "./base";
+import { ClientType } from "@artu-ai/shared";
+import type {
+  BaseClient,
+  Jurisdiction,
+  AddressResponse,
+  ContactMethodResponse,
+  BankAccountResponse,
+  DocumentResponse,
+  LinkedClientResponse,
+  ClientRelationshipType,
+} from "@artu-ai/shared";
+import { Address } from "./Address";
+import { ContactMethod } from "./ContactMethod";
+import { BankAccount } from "./BankAccount";
+import { Document } from "./Document";
+
+// ===========================
+// Utilities
+// ===========================
+
+/**
+ * Parse a date string, handling date-only strings (YYYY-MM-DD) as local time
+ * to avoid timezone conversion issues.
+ */
+function parseDateString(value: string): Date {
+  // For date-only strings (yyyy-MM-dd), parse as local time to avoid timezone issues
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    const parts = value.split("-").map(Number);
+    const year = parts[0] ?? 0;
+    const month = parts[1] ?? 1;
+    const day = parts[2] ?? 1;
+    return new Date(year, month - 1, day);
+  }
+  return new Date(value);
+}
+
+// ===========================
+// Types
+// ===========================
+
+export type ClientData = BaseClient & {
+  // Server-generated fields (added by API)
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  // Optional enriched fields
+  email?: string | null;
+  phone?: string | null;
+  addresses?: AddressResponse[];
+  contactMethods?: ContactMethodResponse[];
+  bankAccounts?: BankAccountResponse[];
+  documents?: DocumentResponse[];
+  linkedClients?: LinkedClientResponse[];
+};
+
+// ===========================
+// Client Model
+// ===========================
+
+/**
+ * Base Client Model.
+ *
+ * Pure data model with no API calls.
+ * Extended by jurisdiction-specific models (MexClient, etc.).
+ *
+ * @example
+ * ```typescript
+ * const client = await sdk.clients.retrieve("client_123");
+ * console.log(client.name);
+ * console.log(client.email);
+ * ```
+ */
+export class Client extends BaseModel<ClientData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Identity
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique identifier
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * Client type: "individual" or "company"
+   */
+  get type(): ClientType {
+    return this._data.type;
+  }
+
+  /**
+   * Whether this is an individual (individual)
+   */
+  get isIndividual(): boolean {
+    return this._data.type === ClientType.Individual;
+  }
+
+  /**
+   * Whether this is a company (legal entity)
+   */
+  get isCompany(): boolean {
+    return this._data.type === ClientType.Company;
+  }
+
+  /**
+   * Whether this is a trust
+   */
+  get isTrust(): boolean {
+    return this._data.type === ClientType.Trust;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Common Fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Full name (individual) or legal name (company)
+   */
+  get name(): string {
+    return this._data.name;
+  }
+
+  /**
+   * Nationalities as ISO2 country codes
+   */
+  get nationalities(): string[] {
+    return this._data.nationalities ?? [];
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Individual-specific fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Birth date (individuals only)
+   * Returns undefined for companies and trusts
+   */
+  get birthDate(): Date | undefined {
+    // Access via record since BaseClient is a discriminated union
+    const raw = (this._data as Record<string, unknown>).birthDate as
+      | string
+      | undefined;
+    return raw ? parseDateString(raw) : undefined;
+  }
+
+  /**
+   * Middle name (individuals only)
+   */
+  get middleName(): string | undefined {
+    return (this._data as Record<string, unknown>).middleName as
+      | string
+      | undefined;
+  }
+
+  /**
+   * Last name(s) (individuals only)
+   * Returns as array to support multiple surnames (e.g., Spanish naming)
+   */
+  get lastName(): string[] | undefined {
+    return (this._data as Record<string, unknown>).lastName as
+      | string[]
+      | undefined;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Company-specific fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Incorporation date (companies only)
+   * Returns undefined for individuals and trusts
+   */
+  get incorporationDate(): Date | undefined {
+    const raw = (this._data as Record<string, unknown>).incorporationDate as
+      | string
+      | undefined;
+    return raw ? parseDateString(raw) : undefined;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Trust-specific fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Formation date (trusts only)
+   * Returns undefined for individuals and companies
+   */
+  get formationDate(): Date | undefined {
+    const raw = (this._data as Record<string, unknown>).formationDate as
+      | string
+      | undefined;
+    return raw ? parseDateString(raw) : undefined;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Jurisdiction
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Primary jurisdiction for compliance purposes.
+   * May be undefined if not set (can be inferred from SDK scope).
+   */
+  get primaryJurisdiction(): Jurisdiction | undefined {
+    return this._data.primaryJurisdiction;
+  }
+
+  /**
+   * Checks if client has data for a specific jurisdiction
+   */
+  hasJurisdiction(jurisdiction: Jurisdiction): boolean {
+    if (!this._data.jurisdictions) return false;
+    return jurisdiction in this._data.jurisdictions;
+  }
+
+  /**
+   * Raw jurisdiction data object
+   */
+  get jurisdictions(): BaseClient["jurisdictions"] {
+    return this._data.jurisdictions ?? {};
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Metadata
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * External ID for integration with other systems
+   */
+  get externalId(): string | undefined {
+    return this._data.externalId;
+  }
+
+  /**
+   * Custom metadata
+   */
+  get metadata(): Record<string, unknown> | undefined {
+    return this._data.metadata;
+  }
+
+  /**
+   * Primary email (if included)
+   */
+  get email(): string | null | undefined {
+    return this._data.email;
+  }
+
+  /**
+   * Primary phone (if included)
+   */
+  get phone(): string | null | undefined {
+    return this._data.phone;
+  }
+
+  /**
+   * Addresses (if included)
+   */
+  get addresses(): Address[] | undefined {
+    return this._data.addresses?.map((a) => new Address(a));
+  }
+
+  /**
+   * Contact methods (if included)
+   */
+  get contactMethods(): ContactMethod[] | undefined {
+    return this._data.contactMethods?.map((c) => new ContactMethod(c));
+  }
+
+  /**
+   * Bank accounts (if included)
+   */
+  get bankAccounts(): BankAccount[] | undefined {
+    return this._data.bankAccounts?.map((b) => new BankAccount(b));
+  }
+
+  /**
+   * Documents (if included)
+   */
+  get documents(): Document[] | undefined {
+    return this._data.documents?.map((d) => new Document(d));
+  }
+
+  /**
+   * Linked clients (if included)
+   */
+  get linkedClients():
+    | {
+        relationshipType: ClientRelationshipType;
+        client: Client;
+      }[]
+    | undefined {
+    return this._data.linkedClients?.map((l) => ({
+      relationshipType: l.relationshipType,
+      client: new Client(l.client),
+    }));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Timestamps
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * When the client was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the client was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `Client(${this.id}, ${this.name})`;
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+/**
+ * Check if value is any type of Client model
+ */
+export function isClient(value: unknown): value is Client {
+  return value instanceof Client;
+}
+
+/**
+ * Check if client is an individual (individual)
+ */
+export function isIndividual(client: Client): boolean {
+  return client.isIndividual;
+}
+
+/**
+ * Check if client is a company (legal entity)
+ */
+export function isCompany(client: Client): boolean {
+  return client.isCompany;
+}
+
+/**
+ * Check if client is a trust
+ */
+export function isTrust(client: Client): boolean {
+  return client.isTrust;
+}

package/src/models/ContactMethod.ts

@@ -0,0 +1,197 @@
+/**
+ * ContactMethod Model
+ *
+ * Communication channel for a client (email, phone, etc.).
+ */
+
+import {
+  ContactMethodType,
+  type ContactMethod as ContactMethodSchema,
+} from "@artu-ai/shared";
+import { BaseModel } from "./base";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Contact method data structure from the API
+ */
+export interface ContactMethodData
+  extends Omit<ContactMethodSchema, "verifiedAt"> {
+  id: string;
+  verifiedAt: string | null; // API returns ISO string or null (JSON serialization)
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ===========================
+// ContactMethod Model
+// ===========================
+
+/**
+ * ContactMethod Model.
+ *
+ * Provides typed accessors for contact method data with formatting helpers.
+ *
+ * @example
+ * ```typescript
+ * const contacts = await sdk.contactMethods.listByClient("client_123");
+ * for (const contact of contacts) {
+ *   console.log(contact.display);
+ *   console.log(`Verified: ${contact.isVerified}`);
+ * }
+ * ```
+ */
+export class ContactMethod extends BaseModel<ContactMethodData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Core Properties
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique contact method identifier
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * ID of the client this contact method belongs to
+   */
+  get clientId(): string {
+    return this._data.clientId;
+  }
+
+  /**
+   * Contact method type (email, phone, mobile, fax, other)
+   */
+  get type(): ContactMethodType {
+    return this._data.type;
+  }
+
+  /**
+   * Whether this is the primary contact method for its type
+   */
+  get isPrimary(): boolean {
+    return this._data.isPrimary;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Value Fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * The contact value (email address, phone number, etc.)
+   */
+  get value(): string {
+    return this._data.value;
+  }
+
+  /**
+   * Optional label (e.g., "Work", "Personal")
+   */
+  get label(): string | undefined {
+    return this._data.label;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Verification
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this contact method has been verified
+   */
+  get isVerified(): boolean {
+    return this._data.isVerified;
+  }
+
+  /**
+   * When this contact method was verified
+   */
+  get verifiedAt(): Date | null {
+    return this._data.verifiedAt ? new Date(this._data.verifiedAt) : null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Metadata
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * External ID
+   */
+  get externalId(): string | undefined {
+    return this._data.externalId;
+  }
+
+  /**
+   * Additional metadata
+   */
+  get metadata(): Record<string, unknown> | undefined {
+    return this._data.metadata;
+  }
+
+  /**
+   * When the contact method was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the contact method was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Type Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this is an email contact
+   */
+  get isEmail(): boolean {
+    return this.type === ContactMethodType.Email;
+  }
+
+  /**
+   * Whether this is a phone contact
+   */
+  get isPhone(): boolean {
+    return this.type === ContactMethodType.Phone;
+  }
+
+  /**
+   * Whether this is a mobile contact
+   */
+  get isMobile(): boolean {
+    return this.type === ContactMethodType.Mobile;
+  }
+
+  /**
+   * Whether this is a fax contact
+   */
+  get isFax(): boolean {
+    return this.type === ContactMethodType.Fax;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Formatting
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns a display string with optional label
+   */
+  get display(): string {
+    return this.label ? `${this.label}: ${this.value}` : this.value;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `ContactMethod(${this.id}, ${this.type}, ${this.value})`;
+  }
+}