@artu-ai/compliance-sdk 0.0.6 → 0.2.0

package/src/models/Report.ts

@@ -0,0 +1,193 @@
+/**
+ * Base Report Model
+ *
+ * Pure data model with no API calls.
+ * Provides type-safe access to common report properties.
+ */
+
+import { BaseModel } from "./base";
+import { ReportStatus } from "@artu-ai/shared";
+import type { BaseReport, Report as ReportSchema } from "@artu-ai/shared";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Report data as returned from the API.
+ */
+export type ReportData = ReportSchema;
+
+// ===========================
+// Report Model
+// ===========================
+
+/**
+ * Base Report Model.
+ *
+ * Pure data model with no API calls.
+ * Extended by jurisdiction-specific models (MexReport, etc.).
+ *
+ * @example
+ * ```typescript
+ * const report = await sdk.reports.retrieve("report_123");
+ * console.log(report.type);
+ * console.log(report.status);
+ * ```
+ */
+export class Report extends BaseModel<ReportData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Identity
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique identifier
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * Organization ID
+   */
+  get organizationId(): string {
+    return this._data.organizationId;
+  }
+
+  /**
+   * Environment (test or live)
+   */
+  get environment(): "test" | "live" {
+    return this._data.environment;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Status
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Report status
+   */
+  get status(): ReportStatus {
+    return this._data.status;
+  }
+
+  /**
+   * Number of items in the report
+   */
+  get itemCount(): number {
+    return this._data.itemCount;
+  }
+
+  /**
+   * Whether the report is in draft status
+   */
+  get isDraft(): boolean {
+    return this._data.status === ReportStatus.Draft;
+  }
+
+  /**
+   * Whether the report has been validated successfully
+   */
+  get isValid(): boolean {
+    return this._data.status === ReportStatus.Valid;
+  }
+
+  /**
+   * Whether the report failed validation
+   */
+  get isInvalid(): boolean {
+    return this._data.status === ReportStatus.Invalid;
+  }
+
+  /**
+   * Whether the report has been submitted
+   */
+  get isSubmitted(): boolean {
+    return this._data.status === ReportStatus.Submitted;
+  }
+
+  /**
+   * Whether the report can be edited
+   */
+  get canEdit(): boolean {
+    return [
+      ReportStatus.Draft,
+      ReportStatus.Valid,
+      ReportStatus.Invalid,
+    ].includes(this._data.status);
+  }
+
+  /**
+   * Whether the report can be validated/generated
+   */
+  get canGenerate(): boolean {
+    return [ReportStatus.Draft, ReportStatus.Valid].includes(this._data.status);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Jurisdiction
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Raw jurisdiction data object
+   */
+  get jurisdictions(): BaseReport["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;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Timestamps
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * When the report was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the report was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `Report(${this.id}, ${this.status})`;
+  }
+}
+
+// ===========================
+// Type Guards
+// ===========================
+
+/**
+ * Check if value is any type of Report model
+ */
+export function isReport(value: unknown): value is Report {
+  return value instanceof Report;
+}

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 name (denormalized for display)
+   */
+  get clientName(): string | undefined {
+    return this._data.clientName;
+  }
+
+  /**
+   * 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.clientName ?? "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)})`;
+  }
+}