@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/models/ReportItem.ts

@@ -0,0 +1,211 @@
+/**
+ * Base Report Item Model
+ *
+ * Pure data model with no API calls.
+ * Provides type-safe access to common report item properties.
+ */
+
+import { BaseModel } from "./base";
+import type {
+  ReportItem as ReportItemSchema,
+  ReportItemValidationError,
+  BaseReportItem,
+} from "@artu-ai/shared";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Report item data as returned from the API.
+ */
+export type ReportItemData = ReportItemSchema;
+
+// ===========================
+// ReportItem Model
+// ===========================
+
+/**
+ * Base Report Item Model.
+ *
+ * Pure data model with no API calls.
+ * Extended by jurisdiction-specific models.
+ *
+ * @example
+ * ```typescript
+ * const items = await sdk.reports.listItems("report_123");
+ * for (const item of items) {
+ *   console.log(item.clientName, item.transactionAmount);
+ * }
+ * ```
+ */
+export class ReportItem extends BaseModel<ReportItemData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Identity
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique identifier
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * Parent report ID
+   */
+  get reportId(): string {
+    return this._data.reportId;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // References
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Transaction ID (if item is transaction-based)
+   */
+  get transactionId(): string | undefined {
+    return this._data.transactionId;
+  }
+
+  /**
+   * Client ID
+   */
+  get clientId(): string | undefined {
+    return this._data.clientId;
+  }
+
+  /**
+   * Whether this item is based on a transaction
+   */
+  get isTransactionBased(): boolean {
+    return !!this._data.transactionId;
+  }
+
+  /**
+   * Whether this item is client-only (no transaction)
+   */
+  get isClientOnly(): boolean {
+    return !this._data.transactionId && !!this._data.clientId;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Denormalized Data
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Client names (denormalized for display)
+   */
+  get clientNames(): string[] | undefined {
+    return this._data.clientNames;
+  }
+
+  /**
+   * Transaction amount (denormalized for display)
+   */
+  get transactionAmount(): number | undefined {
+    return this._data.transactionAmount;
+  }
+
+  /**
+   * Transaction currency (denormalized for display)
+   */
+  get transactionCurrency(): string | undefined {
+    return this._data.transactionCurrency;
+  }
+
+  /**
+   * Transaction date (denormalized for display)
+   */
+  get transactionDate(): string | undefined {
+    return this._data.transactionDate;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Validation
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Validation errors for this item
+   */
+  get validationErrors(): ReportItemValidationError[] {
+    return this._data.validationErrors ?? [];
+  }
+
+  /**
+   * Whether this item has validation errors
+   */
+  get hasErrors(): boolean {
+    return this.validationErrors.some((e) => e.severity === "error");
+  }
+
+  /**
+   * Whether this item has validation warnings
+   */
+  get hasWarnings(): boolean {
+    return this.validationErrors.some((e) => e.severity === "warning");
+  }
+
+  /**
+   * Number of errors
+   */
+  get errorCount(): number {
+    return this.validationErrors.filter((e) => e.severity === "error").length;
+  }
+
+  /**
+   * Number of warnings
+   */
+  get warningCount(): number {
+    return this.validationErrors.filter((e) => e.severity === "warning").length;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Jurisdiction
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Raw jurisdiction data object
+   */
+  get jurisdictions(): BaseReportItem["jurisdictions"] {
+    return this._data.jurisdictions ?? {};
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Timestamps
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * When the item was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the item was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `ReportItem(${this.id}, ${this.clientNames?.join(", ") ?? "Unknown"})`;
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+/**
+ * Check if value is any type of ReportItem model
+ */
+export function isReportItem(value: unknown): value is ReportItem {
+  return value instanceof ReportItem;
+}

package/src/models/Transaction.ts

@@ -0,0 +1,219 @@
+/**
+ * Base Transaction Model
+ *
+ * Pure data model with no API calls.
+ * Provides type-safe access to common transaction properties.
+ */
+
+import { BaseModel } from "./base";
+import { TransactionStatus } from "@artu-ai/shared";
+import type { BaseTransaction, Jurisdiction } from "@artu-ai/shared";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Transaction data as returned from the API.
+ * Extends the base schema with server-generated fields.
+ */
+export interface TransactionData extends Omit<BaseTransaction, "timestamp"> {
+  id: string;
+  timestamp: string; // API returns ISO string (JSON serialization)
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ===========================
+// Transaction Model
+// ===========================
+
+/**
+ * Base Transaction Model.
+ *
+ * Pure data model with no API calls.
+ * Extended by jurisdiction-specific models (MexTransaction, etc.).
+ *
+ * @example
+ * ```typescript
+ * const txn = await sdk.transactions.retrieve("txn_123");
+ * console.log(txn.formattedAmount);
+ * console.log(txn.status);
+ * ```
+ */
+export class Transaction extends BaseModel<TransactionData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Identity
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique identifier
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * Transaction status
+   */
+  get status(): TransactionStatus {
+    return this._data.status;
+  }
+
+  /**
+   * Whether the transaction is completed
+   */
+  get isCompleted(): boolean {
+    return this._data.status === TransactionStatus.Completed;
+  }
+
+  /**
+   * Whether the transaction is pending
+   */
+  get isPending(): boolean {
+    return this._data.status === TransactionStatus.Pending;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Amount
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Transaction amount
+   */
+  get amount(): number {
+    return this._data.amount;
+  }
+
+  /**
+   * Currency code (ISO 4217)
+   */
+  get currency(): string {
+    return this._data.currency;
+  }
+
+  /**
+   * Formats amount with currency
+   */
+  get formattedAmount(): string {
+    try {
+      return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: this.currency,
+      }).format(this.amount);
+    } catch {
+      // Fallback for unsupported currencies
+      return `${this.currency} ${this.amount.toLocaleString()}`;
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // References
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * IDs of clients related to this transaction
+   */
+  get relatedClientIds(): string[] {
+    return this._data.relatedClientIds ?? [];
+  }
+
+  /**
+   * External ID for integration with other systems
+   */
+  get externalId(): string | undefined {
+    return this._data.externalId;
+  }
+
+  /**
+   * Transaction description
+   */
+  get description(): string | undefined {
+    return this._data.description;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Jurisdiction
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Primary jurisdiction for compliance purposes
+   */
+  get primaryJurisdiction(): Jurisdiction | undefined {
+    return this._data.primaryJurisdiction;
+  }
+
+  /**
+   * Checks if transaction 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(): BaseTransaction["jurisdictions"] {
+    return this._data.jurisdictions ?? {};
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Timing
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * When the transaction was executed/occurred
+   */
+  get timestamp(): Date {
+    return new Date(this._data.timestamp);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Metadata
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Custom metadata
+   */
+  get metadata(): Record<string, unknown> | undefined {
+    return this._data.metadata;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Timestamps
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * When the transaction record was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the transaction record was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `Transaction(${this.id}, ${this.formattedAmount}, ${this.status})`;
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+/**
+ * Check if value is any type of Transaction model
+ */
+export function isTransaction(value: unknown): value is Transaction {
+  return value instanceof Transaction;
+}

package/src/models/base.ts

@@ -0,0 +1,56 @@
+/**
+ * Base Model Class
+ *
+ * Abstract base class for all data models.
+ * Models are pure data containers - they never make API calls.
+ */
+
+// ===========================
+// Base Model Class
+// ===========================
+
+/**
+ * Abstract base class for all data models.
+ *
+ * - **Immutable**: Data is frozen on construction
+ * - **Pure data**: No API calls, just typed accessors
+ * - **Serializable**: `toJSON()` returns the raw data
+ *
+ * @typeParam TData - The raw data type this model wraps
+ *
+ * @example
+ * ```typescript
+ * class Client extends BaseModel<BaseClientData> {
+ *   get id(): string { return this._data.id; }
+ *   get name(): string { return this._data.name; }
+ * }
+ * ```
+ */
+export abstract class BaseModel<TData extends object> {
+  /**
+   * The underlying raw data.
+   * Frozen to ensure immutability.
+   */
+  protected readonly _data: TData;
+
+  constructor(data: TData) {
+    // Deep freeze to ensure complete immutability
+    this._data = Object.freeze(data) as TData;
+  }
+
+  /**
+   * Returns the raw data object.
+   * Useful for serialization and debugging.
+   */
+  toJSON(): TData {
+    return this._data;
+  }
+
+  /**
+   * Returns a string representation of the model.
+   * Override in subclasses for better output.
+   */
+  toString(): string {
+    return `${this.constructor.name}(${JSON.stringify(this._data)})`;
+  }
+}

package/src/models/index.ts

@@ -0,0 +1,148 @@
+/**
+ * Data Models
+ *
+ * Pure data models with typed accessors.
+ * Models never make API calls - they're just data containers.
+ */
+
+// Base model class
+export { BaseModel } from "./base";
+
+// Base client (root level)
+export {
+  Client,
+  type ClientData,
+  isClient,
+  isIndividual,
+  isCompany,
+  isTrust,
+} from "./Client";
+
+// Base transaction (root level)
+export { Transaction, type TransactionData, isTransaction } from "./Transaction";
+
+// Base report (root level)
+export { Report, type ReportData, isReport } from "./Report";
+export { ReportItem, type ReportItemData, isReportItem } from "./ReportItem";
+
+// Supporting models
+export { Address, type AddressData, isAddress } from "./Address";
+export { ContactMethod, type ContactMethodData } from "./ContactMethod";
+export { BankAccount, type BankAccountData, isBankAccount } from "./BankAccount";
+export { Document, type DocumentData } from "./Document";
+export {
+  LinkedClient,
+  type LinkedClientData,
+  isLinkedClient,
+} from "./LinkedClient";
+
+// Mexico hierarchy
+export {
+  MexClient,
+  type MexClientData,
+  isMexClient,
+  MexTransaction,
+  type MexTransactionData,
+  isMexTransaction,
+  MexBankAccount,
+  type MexBankAccountData,
+  isMexBankAccount,
+  MexAddress,
+  type MexAddressData,
+  isMexAddress,
+  // Mexico documents
+  MexDocument,
+  MexIneFrontDocument,
+  MexIneBackDocument,
+  MexPassportDocument,
+  MexCurpDocument,
+  MexRfcConstanciaDocument,
+  MexAddressProofDocument,
+  MexActaConstitutivaDocument,
+  MexPoderNotarialDocument,
+  isMexDocument,
+  isMexIneFront,
+  isMexIneBack,
+  isMexPassport,
+  isMexCurp,
+  isMexRfcConstancia,
+  isMexAddressProof,
+  isMexActaConstitutiva,
+  isMexPoderNotarial,
+  // Mexico reports
+  MexReport,
+  type MexReportData,
+  isMexReport,
+  MexReportItem,
+  type MexReportItemData,
+  isMexReportItem,
+} from "./mex";
+export {
+  // Clients
+  MexActividadVulnerableClient,
+  isActividadVulnerable,
+  MexAVIClient,
+  isMexAVIClient,
+  MexJYSClient,
+  isMexJYSClient,
+  MexTSCClient,
+  isMexTSCClient,
+  // Transactions
+  MexActividadVulnerableTransaction,
+  isActividadVulnerableTransaction,
+  MexAVITransaction,
+  isMexAVITransaction,
+  MexJYSTransaction,
+  isMexJYSTransaction,
+  MexTSCTransaction,
+  isMexTSCTransaction,
+  // Reports
+  MexActividadVulnerableReport,
+  type MexActividadVulnerableReportData,
+  isActividadVulnerableReport,
+  MexActividadVulnerableReportItem,
+  type MexActividadVulnerableReportItemData,
+  isActividadVulnerableReportItem,
+  MexAVIReport,
+  type MexAVIReportData,
+  isMexAVIReport,
+  MexAVIReportItem,
+  type MexAVIReportItemData,
+  isMexAVIReportItem,
+  MexJYSReport,
+  type MexJYSReportData,
+  isMexJYSReport,
+  MexJYSReportItem,
+  type MexJYSReportItemData,
+  isMexJYSReportItem,
+  MexTSCReport,
+  type MexTSCReportData,
+  isMexTSCReport,
+  MexTSCReportItem,
+  type MexTSCReportItemData,
+  isMexTSCReportItem,
+} from "./mex/actividad-vulnerable";
+
+// Type definitions
+export type {
+  // Client types
+  ClientModel,
+  MexClientModel,
+  ActividadVulnerableClientModel,
+  // Transaction types
+  TransactionModel,
+  MexTransactionModel,
+  ActividadVulnerableTransactionModel,
+  // Address types
+  AddressModel,
+  // Bank account types
+  BankAccountModel,
+  // Report types
+  ReportModel,
+  MexReportModel,
+  ActividadVulnerableReportModel,
+  ReportItemModel,
+  MexReportItemModel,
+  ActividadVulnerableReportItemModel,
+} from "./types";
+