@artu-ai/compliance-sdk 0.0.6 → 0.3.0

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

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