@artu-ai/compliance-sdk 0.0.6 → 0.2.0

package/src/models/BankAccount.ts

@@ -0,0 +1,235 @@
+/**
+ * BankAccount Model
+ *
+ * Bank account information for a client.
+ * Uses discriminated union based on `country` field.
+ */
+
+import {
+  BankAccountType,
+  type BankAccount as BankAccountSchema,
+  type CurrencyCode,
+} from "@artu-ai/shared";
+import { BaseModel } from "./base";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Bank account data structure from the API (discriminated union)
+ */
+export type BankAccountData = BankAccountSchema;
+
+// ===========================
+// BankAccount Model
+// ===========================
+
+/**
+ * BankAccount Model.
+ *
+ * Base class for bank account data. The concrete type depends on
+ * the `country` field:
+ * - `country === "MX"` → MexBankAccount with clabe, codigoBanco, codigoPlaza
+ * - Other countries → GenericBankAccount
+ *
+ * @example
+ * ```typescript
+ * const account = await sdk.bankAccounts.retrieve(id);
+ *
+ * // Check country for type narrowing
+ * if (account.country === "MX") {
+ *   console.log(account.clabe); // MexBankAccount
+ * }
+ * ```
+ */
+export class BankAccount extends BaseModel<BankAccountData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Core Properties
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique bank account identifier
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * ID of the client this bank account belongs to
+   */
+  get clientId(): string {
+    return this._data.clientId;
+  }
+
+  /**
+   * Account number
+   */
+  get accountNumber(): string {
+    return this._data.accountNumber;
+  }
+
+  /**
+   * Bank name
+   */
+  get bankName(): string {
+    return this._data.bankName;
+  }
+
+  /**
+   * Bank code (e.g., SWIFT, routing number)
+   */
+  get bankCode(): string | undefined {
+    return this._data.bankCode;
+  }
+
+  /**
+   * Country where the bank account is held (ISO 3166-1 alpha-2)
+   *
+   * This is the discriminator field - determines which fields are available.
+   */
+  get country(): string {
+    return this._data.country;
+  }
+
+  /**
+   * Account type (checking, savings, investment, other)
+   */
+  get type(): BankAccountType {
+    return this._data.type;
+  }
+
+  /**
+   * Account currency (ISO 4217 code)
+   */
+  get currency(): CurrencyCode {
+    return this._data.currency;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Status
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this is the primary bank account
+   */
+  get isPrimary(): boolean {
+    return this._data.isPrimary ?? false;
+  }
+
+  /**
+   * Whether this account is active
+   */
+  get isActive(): boolean {
+    return this._data.isActive ?? true;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Metadata
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Optional label (e.g., "Personal Checking")
+   */
+  get label(): string | undefined {
+    return this._data.label;
+  }
+
+  /**
+   * External ID
+   */
+  get externalId(): string | undefined {
+    return this._data.externalId;
+  }
+
+  /**
+   * Additional metadata
+   */
+  get metadata(): Record<string, unknown> | undefined {
+    return this._data.metadata;
+  }
+
+  /**
+   * When the bank account was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the bank account was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Type Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this is a checking account
+   */
+  get isChecking(): boolean {
+    return this.type === BankAccountType.Checking;
+  }
+
+  /**
+   * Whether this is a savings account
+   */
+  get isSavings(): boolean {
+    return this.type === BankAccountType.Savings;
+  }
+
+  /**
+   * Whether this is an investment account
+   */
+  get isInvestment(): boolean {
+    return this.type === BankAccountType.Investment;
+  }
+
+  /**
+   * Whether this is a Mexican bank account
+   */
+  get isMexican(): boolean {
+    return this.country === "MX";
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Formatting
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns a masked account number (shows last 4 digits)
+   */
+  get maskedAccountNumber(): string {
+    const lastFour = this.accountNumber.slice(-4);
+    return `****${lastFour}`;
+  }
+
+  /**
+   * Returns a display string with bank name and masked account
+   */
+  get display(): string {
+    return `${this.bankName} (${this.maskedAccountNumber})`;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `BankAccount(${this.id}, ${this.bankName}, ${this.country})`;
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+/**
+ * Check if value is any type of BankAccount model
+ */
+export function isBankAccount(value: unknown): value is BankAccount {
+  return value instanceof BankAccount;
+}

package/src/models/Client.ts

@@ -0,0 +1,343 @@
+/**
+ * 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";
+
+// ===========================
+// 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 ? new Date(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 ? new Date(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 ? new Date(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;
+}