@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/models/mex/MexAddress.ts

@@ -0,0 +1,184 @@
+/**
+ * Mexico Address Model
+ *
+ * Extends Address with Mexico-specific accessors for the standard
+ * Mexican address format: street, exteriorNumber, interiorNumber, neighborhood.
+ */
+
+import type { MexAddressData } from "@artu-ai/shared";
+import { Address } from "../Address";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Mexico-specific address data
+ */
+export type { MexAddressData };
+
+// ===========================
+// MexAddress Model
+// ===========================
+
+/**
+ * Mexico Address Model.
+ *
+ * Extends `Address` with Mexico-specific accessors for the standard
+ * Mexican address format.
+ *
+ * @example
+ * ```typescript
+ * if (address instanceof MexAddress) {
+ *   console.log(`Street: ${address.street}`);
+ *   console.log(`Number: ${address.exteriorNumber}`);
+ *   console.log(`Neighborhood: ${address.neighborhood}`);
+ *   console.log(`Formatted: ${address.formattedMexican}`);
+ * }
+ * ```
+ */
+export class MexAddress extends Address {
+  // ─────────────────────────────────────────────────────────────────
+  // Mexico-Specific Data
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Mexico-specific address data
+   */
+  protected get mexicoData(): MexAddressData | undefined {
+    return this._data.jurisdictions?.MX as MexAddressData | undefined;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Mexico Address Fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Exterior number (número exterior)
+   * @example "222", "S/N"
+   */
+  get exteriorNumber(): string | undefined {
+    return this.mexicoData?.exteriorNumber;
+  }
+
+  /**
+   * Interior number (número interior)
+   * @example "Piso 5", "Depto. 301", "Local A"
+   */
+  get interiorNumber(): string | undefined {
+    return this.mexicoData?.interiorNumber;
+  }
+
+  /**
+   * Neighborhood/Colony (colonia)
+   * @example "Juárez", "Roma Norte", "Polanco"
+   */
+  get neighborhood(): string | undefined {
+    return this.mexicoData?.neighborhood;
+  }
+
+  /**
+   * Municipality or delegation (municipio/alcaldía)
+   * @example "Cuauhtémoc", "Miguel Hidalgo"
+   */
+  get municipality(): string | undefined {
+    return this.mexicoData?.municipality;
+  }
+
+  /**
+   * Between streets reference (entre calles)
+   * @example "Between Varsovia and Praga"
+   */
+  get betweenStreets(): string | undefined {
+    return this.mexicoData?.betweenStreets;
+  }
+
+  /**
+   * Additional reference (referencia)
+   * @example "Blue building in front of the park"
+   */
+  get reference(): string | undefined {
+    return this.mexicoData?.reference;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Formatting
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Street address line with number (Mexican format)
+   * @example "Paseo de la Reforma 222 Int. Piso 5"
+   */
+  get streetLine(): string {
+    const parts = [this.street, this.exteriorNumber];
+    if (this.interiorNumber) {
+      parts.push(`Int. ${this.interiorNumber}`);
+    }
+    return parts.filter(Boolean).join(" ");
+  }
+
+  /**
+   * Returns a formatted single-line address in Mexican format
+   * @example "Paseo de la Reforma 222, Col. Juárez, 06600 Ciudad de México, CDMX"
+   */
+  get formattedMexican(): string {
+    const parts = [
+      this.streetLine,
+      this.neighborhood ? `Col. ${this.neighborhood}` : undefined,
+      `${this.postalCode} ${this.city}`,
+      this.state,
+    ].filter(Boolean);
+    return parts.join(", ");
+  }
+
+  /**
+   * Returns a formatted multi-line address in Mexican format
+   */
+  get formattedMexicanMultiLine(): string {
+    const lines = [
+      this.streetLine,
+      this.neighborhood ? `Col. ${this.neighborhood}` : undefined,
+      this.municipality ? `${this.municipality}` : undefined,
+      `${this.postalCode} ${this.city}, ${this.state}`,
+      this.betweenStreets,
+      this.reference,
+    ].filter(Boolean);
+    return lines.join("\n");
+  }
+
+  /**
+   * Override the base formatted to use Mexican format
+   */
+  override get formatted(): string {
+    return this.formattedMexican;
+  }
+
+  /**
+   * Override the base formattedMultiLine to use Mexican format
+   */
+  override get formattedMultiLine(): string {
+    return this.formattedMexicanMultiLine;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    const location = this.neighborhood || this.city;
+    return `MexAddress(${this.id}, ${this.type}, ${location})`;
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+import type { AddressModel } from "../types";
+
+/**
+ * Check if address is a Mexico address
+ */
+export function isMexAddress(address: AddressModel): address is MexAddress {
+  return address instanceof MexAddress;
+}

package/src/models/mex/MexBankAccount.ts

@@ -0,0 +1,121 @@
+/**
+ * Mexico Bank Account Model
+ *
+ * Extends BankAccount with Mexico-specific accessors.
+ * Data is flattened at root level (clabe, codigoBanco, codigoPlaza).
+ */
+
+import type { MexBankAccount as MexBankAccountSchema } from "@artu-ai/shared";
+import { BankAccount } from "../BankAccount";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Mexico bank account data (with MX-specific fields at root)
+ */
+export type MexBankAccountData = MexBankAccountSchema;
+
+// ===========================
+// MexBankAccount Model
+// ===========================
+
+/**
+ * Mexico Bank Account Model.
+ *
+ * Provides typed accessors for Mexico-specific fields like CLABE.
+ *
+ * @example
+ * ```typescript
+ * const account = await sdk.bankAccounts.retrieve(id);
+ *
+ * if (account.country === "MX") {
+ *   // account is MexBankAccount
+ *   console.log(`CLABE: ${account.clabe}`);
+ *   console.log(`Bank Code: ${account.codigoBanco}`);
+ * }
+ * ```
+ */
+export class MexBankAccount extends BankAccount {
+  // Narrow the data type for Mexico-specific fields
+  declare protected _data: MexBankAccountData;
+
+  // ─────────────────────────────────────────────────────────────────
+  // CLABE (Clave Bancaria Estandarizada)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * CLABE (18-digit Mexican interbank code)
+   *
+   * The CLABE is structured as:
+   * - Digits 1-3: Bank code
+   * - Digits 4-6: Plaza (branch location) code
+   * - Digits 7-17: Account number
+   * - Digit 18: Check digit
+   */
+  get clabe(): string | undefined {
+    return this._data.clabe;
+  }
+
+  /**
+   * Bank code from CLABE (first 3 digits)
+   */
+  get codigoBanco(): string | undefined {
+    return this._data.codigoBanco;
+  }
+
+  /**
+   * Plaza (branch location) code from CLABE (digits 4-6)
+   */
+  get codigoPlaza(): string | undefined {
+    return this._data.codigoPlaza;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Formatting
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns a masked CLABE (shows last 4 digits)
+   */
+  get maskedClabe(): string | undefined {
+    const clabe = this.clabe;
+    if (!clabe) return undefined;
+    const lastFour = clabe.slice(-4);
+    return `**************${lastFour}`;
+  }
+
+  /**
+   * Returns a formatted CLABE with spaces for readability
+   * Format: XXX XXX XXXXXXXXXXX X
+   */
+  get formattedClabe(): string | undefined {
+    const clabe = this.clabe;
+    if (!clabe || clabe.length !== 18) return clabe;
+    return `${clabe.slice(0, 3)} ${clabe.slice(3, 6)} ${clabe.slice(6, 17)} ${clabe.slice(17)}`;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `MexBankAccount(${this.id}, ${this.bankName}, ${this.maskedClabe ?? this.maskedAccountNumber})`;
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+import type { BankAccountModel } from "../types";
+
+/**
+ * Check if bank account is a Mexico bank account
+ */
+export function isMexBankAccount(
+  account: BankAccountModel
+): account is MexBankAccount {
+  return account instanceof MexBankAccount;
+}

package/src/models/mex/MexClient.ts

@@ -0,0 +1,177 @@
+/**
+ * Mexico Client Model
+ *
+ * Extends base Client with Mexico-specific accessors.
+ * Provides type-safe access to RFC, CURP, and jurisdiction data.
+ */
+
+import { Client, type ClientData } from "../Client";
+import type {
+  ClientRelationshipType,
+  MexJurisdictionData,
+} from "@artu-ai/shared";
+import { MexBankAccount } from "./MexBankAccount";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Client data with Mexico jurisdiction
+ */
+export type MexClientData = ClientData & {
+  jurisdictions?: {
+    MX?: MexJurisdictionData;
+    [key: string]: unknown;
+  };
+};
+
+// ===========================
+// MexClient Model
+// ===========================
+
+/**
+ * Mexico Client Model.
+ *
+ * Provides typed accessors for Mexico-specific data:
+ * - RFC (Registro Federal de Contribuyentes)
+ * - CURP (Clave Única de Registro de Población)
+ * - Actividad Económica
+ * - Giro Mercantil
+ *
+ * @example
+ * ```typescript
+ * if (client instanceof MexClient) {
+ *   console.log(`RFC: ${client.rfc}`);
+ *   console.log(`CURP: ${client.curp}`);
+ * }
+ * ```
+ */
+export class MexClient extends Client {
+  // ─────────────────────────────────────────────────────────────────
+  // Mexico Jurisdiction Data
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Mexico-specific jurisdiction data
+   */
+  protected get mexicoData(): MexJurisdictionData | undefined {
+    return (this._data as MexClientData).jurisdictions?.MX;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Tax Identifiers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * RFC (Registro Federal de Contribuyentes)
+   * Tax identification number
+   */
+  get rfc(): string | undefined {
+    return this.mexicoData?.rfc;
+  }
+
+  /**
+   * CURP (Clave Única de Registro de Población)
+   * Only applicable for personas físicas
+   */
+  get curp(): string | undefined {
+    return this.mexicoData?.curp;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Economic Activity
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Economic activity classification code
+   */
+  get actividadEconomica(): string | undefined {
+    return this.mexicoData?.actividadEconomica;
+  }
+
+  /**
+   * Business sector (giro mercantil)
+   */
+  get giroMercantil(): string | undefined {
+    return this.mexicoData?.giroMercantil;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Actividades Vulnerables
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether client is registered for any Actividad Vulnerable
+   */
+  get isActividadVulnerable(): boolean {
+    const av = this.mexicoData?.actividadVulnerable;
+    if (!av) return false;
+    return !!(av.AVI || av.JYS || av.TSC);
+  }
+
+  /**
+   * Activity codes the client is registered for
+   */
+  get activityCodes(): string[] {
+    const av = this.mexicoData?.actividadVulnerable;
+    if (!av) return [];
+    const codes: string[] = [];
+    if (av.AVI) codes.push("AVI");
+    if (av.JYS) codes.push("JYS");
+    if (av.TSC) codes.push("TSC");
+    return codes;
+  }
+
+  /**
+   * Checks if registered for a specific activity
+   */
+  hasActivity(code: "AVI" | "JYS" | "TSC"): boolean {
+    return this.activityCodes.includes(code);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `MexClient(${this.id}, ${this.name}, RFC: ${this.rfc ?? "N/A"})`;
+  }
+
+  /**
+   * Linked clients (if included) instantiated as MexClient
+   */
+  override get linkedClients():
+    | {
+        relationshipType: ClientRelationshipType;
+        client: MexClient;
+      }[]
+    | undefined {
+    return (this._data.linkedClients ?? []).map((l) => ({
+      relationshipType: l.relationshipType,
+      client: new MexClient(l.client),
+    }));
+  }
+
+  override get addresses(): MexAddress[] | undefined {
+    return this._data.addresses?.map((a) => new MexAddress(a));
+  }
+
+  override get bankAccounts(): MexBankAccount[] | undefined {
+    return this._data.bankAccounts?.map((b) => new MexBankAccount(b));
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+import type { ClientModel } from "../types";
+import { MexAddress } from "./MexAddress";
+
+/**
+ * Check if client is a Mexico client
+ */
+export function isMexClient(client: ClientModel): client is MexClient {
+  return client instanceof MexClient;
+}