@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/models/Address.ts

@@ -0,0 +1,235 @@
+/**
+ * Address Model
+ *
+ * Physical or mailing address for a client.
+ */
+
+import {
+  AddressType,
+  type Address as AddressSchema,
+  type CountryIso2,
+} from "@artu-ai/shared";
+import { BaseModel } from "./base";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Address data structure from the API
+ */
+export interface AddressData extends AddressSchema {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ===========================
+// Address Model
+// ===========================
+
+/**
+ * Address Model.
+ *
+ * Provides typed accessors for address data with formatting helpers.
+ *
+ * @example
+ * ```typescript
+ * const addresses = await sdk.addresses.listByClient("client_123");
+ * for (const addr of addresses) {
+ *   console.log(addr.formatted);
+ *   console.log(`Primary: ${addr.isPrimary}`);
+ * }
+ * ```
+ */
+export class Address extends BaseModel<AddressData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Core Properties
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique address identifier
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * ID of the client this address belongs to
+   */
+  get clientId(): string {
+    return this._data.clientId;
+  }
+
+  /**
+   * Address type (home, business, mailing, legal, other)
+   */
+  get type(): AddressType {
+    return this._data.type;
+  }
+
+  /**
+   * Whether this is the primary address
+   */
+  get isPrimary(): boolean {
+    return this._data.isPrimary ?? false;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Address Fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Street address line
+   */
+  get street(): string {
+    return this._data.street;
+  }
+
+  /**
+   * City name
+   */
+  get city(): string {
+    return this._data.city;
+  }
+
+  /**
+   * State or province
+   */
+  get state(): string {
+    return this._data.state;
+  }
+
+  /**
+   * Postal/ZIP code
+   */
+  get postalCode(): string {
+    return this._data.postalCode;
+  }
+
+  /**
+   * Country code (ISO 3166-1 alpha-2)
+   */
+  get country(): CountryIso2 {
+    return this._data.country;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Jurisdictions & Metadata
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Jurisdiction-scoped data
+   * (e.g., Mexico: exteriorNumber, neighborhood)
+   */
+  get jurisdictions(): AddressSchema["jurisdictions"] {
+    return this._data.jurisdictions;
+  }
+
+  /**
+   * External ID
+   */
+  get externalId(): string | undefined {
+    return this._data.externalId;
+  }
+
+  /**
+   * Additional metadata
+   */
+  get metadata(): Record<string, unknown> | undefined {
+    return this._data.metadata;
+  }
+
+  /**
+   * When the address was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the address was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Type Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this is a home address
+   */
+  get isHome(): boolean {
+    return this.type === AddressType.Home;
+  }
+
+  /**
+   * Whether this is a business address
+   */
+  get isBusiness(): boolean {
+    return this.type === AddressType.Business;
+  }
+
+  /**
+   * Whether this is a mailing address
+   */
+  get isMailing(): boolean {
+    return this.type === AddressType.Mailing;
+  }
+
+  /**
+   * Whether this is a legal address
+   */
+  get isLegal(): boolean {
+    return this.type === AddressType.Legal;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Formatting
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns a formatted single-line address string
+   */
+  get formatted(): string {
+    const parts = [
+      this.street,
+      `${this.city}, ${this.state} ${this.postalCode}`,
+      this.country,
+    ].filter(Boolean);
+    return parts.join(", ");
+  }
+
+  /**
+   * Returns a formatted multi-line address string
+   */
+  get formattedMultiLine(): string {
+    const lines = [
+      this.street,
+      `${this.city}, ${this.state} ${this.postalCode}`,
+      this.country,
+    ].filter(Boolean);
+    return lines.join("\n");
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `Address(${this.id}, ${this.type}, ${this.city})`;
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+/**
+ * Check if value is any type of Address model
+ */
+export function isAddress(value: unknown): value is Address {
+  return value instanceof Address;
+}

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;
+}