@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/models/ContactMethod.ts

@@ -0,0 +1,197 @@
+/**
+ * ContactMethod Model
+ *
+ * Communication channel for a client (email, phone, etc.).
+ */
+
+import {
+  ContactMethodType,
+  type ContactMethod as ContactMethodSchema,
+} from "@artu-ai/shared";
+import { BaseModel } from "./base";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * Contact method data structure from the API
+ */
+export interface ContactMethodData
+  extends Omit<ContactMethodSchema, "verifiedAt"> {
+  id: string;
+  verifiedAt: string | null; // API returns ISO string or null (JSON serialization)
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ===========================
+// ContactMethod Model
+// ===========================
+
+/**
+ * ContactMethod Model.
+ *
+ * Provides typed accessors for contact method data with formatting helpers.
+ *
+ * @example
+ * ```typescript
+ * const contacts = await sdk.contactMethods.listByClient("client_123");
+ * for (const contact of contacts) {
+ *   console.log(contact.display);
+ *   console.log(`Verified: ${contact.isVerified}`);
+ * }
+ * ```
+ */
+export class ContactMethod extends BaseModel<ContactMethodData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Core Properties
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique contact method identifier
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * ID of the client this contact method belongs to
+   */
+  get clientId(): string {
+    return this._data.clientId;
+  }
+
+  /**
+   * Contact method type (email, phone, mobile, fax, other)
+   */
+  get type(): ContactMethodType {
+    return this._data.type;
+  }
+
+  /**
+   * Whether this is the primary contact method for its type
+   */
+  get isPrimary(): boolean {
+    return this._data.isPrimary;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Value Fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * The contact value (email address, phone number, etc.)
+   */
+  get value(): string {
+    return this._data.value;
+  }
+
+  /**
+   * Optional label (e.g., "Work", "Personal")
+   */
+  get label(): string | undefined {
+    return this._data.label;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Verification
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this contact method has been verified
+   */
+  get isVerified(): boolean {
+    return this._data.isVerified;
+  }
+
+  /**
+   * When this contact method was verified
+   */
+  get verifiedAt(): Date | null {
+    return this._data.verifiedAt ? new Date(this._data.verifiedAt) : null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Metadata
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * External ID
+   */
+  get externalId(): string | undefined {
+    return this._data.externalId;
+  }
+
+  /**
+   * Additional metadata
+   */
+  get metadata(): Record<string, unknown> | undefined {
+    return this._data.metadata;
+  }
+
+  /**
+   * When the contact method was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the contact method was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Type Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this is an email contact
+   */
+  get isEmail(): boolean {
+    return this.type === ContactMethodType.Email;
+  }
+
+  /**
+   * Whether this is a phone contact
+   */
+  get isPhone(): boolean {
+    return this.type === ContactMethodType.Phone;
+  }
+
+  /**
+   * Whether this is a mobile contact
+   */
+  get isMobile(): boolean {
+    return this.type === ContactMethodType.Mobile;
+  }
+
+  /**
+   * Whether this is a fax contact
+   */
+  get isFax(): boolean {
+    return this.type === ContactMethodType.Fax;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Formatting
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns a display string with optional label
+   */
+  get display(): string {
+    return this.label ? `${this.label}: ${this.value}` : this.value;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // String Representation
+  // ─────────────────────────────────────────────────────────────────
+
+  override toString(): string {
+    return `ContactMethod(${this.id}, ${this.type}, ${this.value})`;
+  }
+}

package/src/models/Document.ts

@@ -0,0 +1,355 @@
+/**
+ * Document model
+ *
+ * Represents a file uploaded for a client.
+ * Supports jurisdiction-specific document types (MX, US).
+ */
+
+import { BaseModel } from "./base";
+import {
+  DocumentStatus,
+  DocumentCategory,
+  Jurisdiction,
+  type DocumentResponse,
+} from "@artu-ai/shared";
+
+// ─────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Document data as returned by the API.
+ * Uses the centralized type from @artu-ai/shared.
+ */
+export type DocumentData = DocumentResponse;
+
+// ─────────────────────────────────────────────────────────────────
+// Document Model
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Document model - represents an uploaded file.
+ *
+ * @example
+ * ```typescript
+ * const doc = await sdk.documents.retrieve("doc_123");
+ *
+ * console.log(doc.filename);        // "passport.pdf"
+ * console.log(doc.formattedSize);   // "2.5 MB"
+ * console.log(doc.isAvailable);     // true
+ *
+ * if (doc.isMexico) {
+ *   console.log(doc.type); // "ine_front" | "rfc" | etc.
+ * }
+ * ```
+ */
+export class Document extends BaseModel<DocumentData> {
+  // ─────────────────────────────────────────────────────────────────
+  // Core Properties
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Unique identifier for the document
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * ID of the client this document belongs to
+   */
+  get clientId(): string {
+    return this._data.clientId;
+  }
+
+  /**
+   * Jurisdiction for this document (MX, US)
+   */
+  get jurisdiction(): Jurisdiction {
+    return this._data.jurisdiction;
+  }
+
+  /**
+   * Document type (jurisdiction-specific)
+   */
+  get type(): string {
+    return this._data.type;
+  }
+
+  /**
+   * Document category (identity, address, financial, etc.)
+   */
+  get category(): DocumentCategory {
+    return this._data.category;
+  }
+
+  /**
+   * Document status
+   */
+  get status(): DocumentStatus {
+    return this._data.status;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // File Properties
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether a file is attached to this document
+   */
+  get hasFile(): boolean {
+    return !!this._data.filename;
+  }
+
+  /**
+   * Original filename (undefined if no file attached)
+   */
+  get filename(): string | undefined {
+    return this._data.filename ?? undefined;
+  }
+
+  /**
+   * MIME content type (undefined if no file attached)
+   */
+  get contentType(): string | undefined {
+    return this._data.contentType ?? undefined;
+  }
+
+  /**
+   * File size in bytes (undefined if no file attached)
+   */
+  get size(): number | undefined {
+    return this._data.size ?? undefined;
+  }
+
+  /**
+   * Human-readable file size (e.g., "2.5 MB")
+   * Returns undefined if no file attached
+   */
+  get formattedSize(): string | undefined {
+    if (this._data.size === undefined || this._data.size === null)
+      return undefined;
+    return formatBytes(this._data.size);
+  }
+
+  /**
+   * File extension derived from filename
+   * Returns empty string if no file or no extension
+   */
+  get extension(): string {
+    if (!this.filename) return "";
+    const parts = this.filename.split(".");
+    const ext = parts.at(-1);
+    if (!ext || parts.length <= 1) return "";
+    return ext.toLowerCase();
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Status Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether the document is ready for download
+   */
+  get isAvailable(): boolean {
+    return (
+      this.status === DocumentStatus.Uploaded ||
+      this.status === DocumentStatus.Verified
+    );
+  }
+
+  /**
+   * Whether the document is pending upload
+   */
+  get isPending(): boolean {
+    return this.status === DocumentStatus.PendingUpload;
+  }
+
+  /**
+   * Whether the document has been verified
+   */
+  get isVerified(): boolean {
+    return this.status === DocumentStatus.Verified;
+  }
+
+  /**
+   * Whether the document was rejected
+   */
+  get isRejected(): boolean {
+    return this.status === DocumentStatus.Rejected;
+  }
+
+  /**
+   * Whether the document has expired
+   */
+  get isExpired(): boolean {
+    if (this.status === DocumentStatus.Expired) return true;
+    if (!this._data.expiresAt) return false;
+    return new Date(this._data.expiresAt) < new Date();
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Validity
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Document expiration date, if set
+   */
+  get expiresAt(): Date | undefined {
+    return this._data.expiresAt ? new Date(this._data.expiresAt) : undefined;
+  }
+
+  /**
+   * Days until document expires (negative if already expired)
+   */
+  get daysUntilExpiry(): number | undefined {
+    if (!this.expiresAt) return undefined;
+    const now = new Date();
+    const diffTime = this.expiresAt.getTime() - now.getTime();
+    return Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Fields
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Document-specific fields (extracted or provided data)
+   *
+   * For typed fields, use jurisdiction-specific document models:
+   * - MexIneFrontDocument.ineFields
+   * - MexPassportDocument.passportFields
+   * - etc.
+   */
+  get fields(): Record<string, unknown> | undefined {
+    return (this._data as DocumentData & { fields?: Record<string, unknown> })
+      .fields;
+  }
+
+  /**
+   * Get a specific field value
+   */
+  getField<T = unknown>(key: string): T | undefined {
+    return this.fields?.[key] as T | undefined;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Metadata
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * External ID
+   */
+  get externalId(): string | undefined {
+    return this._data.externalId ?? undefined;
+  }
+
+  /**
+   * Custom metadata attached to the document
+   */
+  get metadata(): Record<string, unknown> | undefined {
+    return this._data.metadata;
+  }
+
+  /**
+   * Get a specific metadata value
+   */
+  getMetadata<T = unknown>(key: string): T | undefined {
+    return this.metadata?.[key] as T | undefined;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Timestamps
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * When the document was created
+   */
+  get createdAt(): Date {
+    return new Date(this._data.createdAt);
+  }
+
+  /**
+   * When the document was last updated
+   */
+  get updatedAt(): Date {
+    return new Date(this._data.updatedAt);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Jurisdiction Type Guards
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this is a Mexico document
+   */
+  get isMexico(): boolean {
+    return this._data.jurisdiction === Jurisdiction.Mexico;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Category Helpers
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Whether this is an identity document
+   */
+  get isIdentityDocument(): boolean {
+    return this.category === DocumentCategory.Identity;
+  }
+
+  /**
+   * Whether this is an address proof document
+   */
+  get isAddressProof(): boolean {
+    return this.category === DocumentCategory.Address;
+  }
+
+  /**
+   * Whether this is a financial document
+   */
+  get isFinancialDocument(): boolean {
+    return this.category === DocumentCategory.Financial;
+  }
+
+  /**
+   * Whether this is an incorporation document
+   */
+  get isIncorporationDocument(): boolean {
+    return this.category === DocumentCategory.Incorporation;
+  }
+
+  /**
+   * Whether this is a tax document
+   */
+  get isTaxDocument(): boolean {
+    return this.category === DocumentCategory.Tax;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Format bytes into human-readable string
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 bytes";
+
+  const units = ["bytes", "KB", "MB", "GB"];
+  let size = bytes;
+  let unitIndex = 0;
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+
+  // Show decimals only for KB and larger
+  if (unitIndex === 0) {
+    return `${size} ${units[unitIndex]}`;
+  }
+
+  return `${size.toFixed(1)} ${units[unitIndex]}`;
+}

package/src/models/LinkedClient.ts

@@ -0,0 +1,84 @@
+/**
+ * LinkedClient Model
+ *
+ * Represents a client-to-client relationship with metadata.
+ */
+
+import type { ClientRelationshipType, LinkedClientResponse } from "@artu-ai/shared";
+import { BaseModel } from "./base";
+import { Client, type ClientData } from "./Client";
+
+/**
+ * Data structure for linked client.
+ */
+export type LinkedClientData = LinkedClientResponse;
+
+/**
+ * LinkedClient model class.
+ *
+ * Provides typed access to linked client data including:
+ * - Relationship type (legal_representative, controlling_beneficiary, etc.)
+ * - The linked client
+ * - Metadata for the relationship
+ * - Timestamps
+ *
+ * @example
+ * ```typescript
+ * const linkedClients = await sdk.clients.listLinkedClients(companyId);
+ * for (const linkedClient of linkedClients) {
+ *   console.log(linkedClient.id, linkedClient.relationshipType);
+ *   console.log(linkedClient.client.name);
+ *   console.log(linkedClient.metadata);
+ * }
+ * ```
+ */
+export class LinkedClient extends BaseModel<LinkedClientData> {
+  /**
+   * Unique identifier for this relationship
+   */
+  get id(): string {
+    return this._data.id;
+  }
+
+  /**
+   * Type of relationship between the parent and child client.
+   */
+  get relationshipType(): ClientRelationshipType {
+    return this._data.relationshipType;
+  }
+
+  /**
+   * The linked (child) client.
+   */
+  get client(): Client {
+    return new Client(this._data.client as ClientData);
+  }
+
+  /**
+   * Optional metadata for the relationship.
+   */
+  get metadata(): Record<string, unknown> | undefined {
+    return this._data.metadata;
+  }
+
+  /**
+   * When the relationship was created.
+   */
+  get createdAt(): string {
+    return this._data.createdAt;
+  }
+
+  /**
+   * When the relationship was last updated.
+   */
+  get updatedAt(): string {
+    return this._data.updatedAt;
+  }
+}
+
+/**
+ * Type guard for LinkedClient model.
+ */
+export function isLinkedClient(obj: unknown): obj is LinkedClient {
+  return obj instanceof LinkedClient;
+}