@artu-ai/compliance-sdk 0.13.4 → 0.17.0

package/dist/models/Evidence.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Evidence model
+ *
+ * Represents a compliance evidence record optionally backed by a file.
+ * Evidence can be created with a file upload, with data fields only, or both.
+ */
+import type { EvidenceResponse } from "@artu-ai/shared";
+import { EvidenceStatus } from "@artu-ai/shared";
+import { BaseModel } from "./base";
+/**
+ * Evidence data as returned by the API.
+ */
+export type EvidenceData = EvidenceResponse;
+/**
+ * Evidence model - represents a compliance evidence record.
+ *
+ * @example
+ * ```typescript
+ * const evidence = await sdk.evidence.retrieve("ev_123");
+ *
+ * console.log(evidence.status);         // "uploaded"
+ * console.log(evidence.filename);       // "contrato.pdf"
+ * console.log(evidence.formattedSize);  // "1.2 MB"
+ * console.log(evidence.isAvailable);    // true
+ * ```
+ */
+export declare class Evidence extends BaseModel<EvidenceData> {
+    /**
+     * Unique identifier for this evidence record
+     */
+    get id(): string;
+    /**
+     * Scope for this evidence (MX, US)
+     */
+    get scope(): "MX" | "US";
+    /**
+     * Evidence type (scope-specific)
+     */
+    get type(): string;
+    /**
+     * Evidence category
+     */
+    get category(): string;
+    /**
+     * Lifecycle status
+     */
+    get status(): EvidenceStatus;
+    /**
+     * Whether a file is attached to this evidence
+     */
+    get hasFile(): boolean;
+    /**
+     * Original filename (undefined if no file attached)
+     */
+    get filename(): string | undefined;
+    /**
+     * MIME content type (undefined if no file attached)
+     */
+    get contentType(): string | undefined;
+    /**
+     * File size in bytes (undefined if no file attached)
+     */
+    get size(): number | undefined;
+    /**
+     * Human-readable file size (e.g., "1.2 MB").
+     * Returns undefined if no file attached.
+     */
+    get formattedSize(): string | undefined;
+    /**
+     * File extension derived from filename.
+     * Returns empty string if no file or no extension.
+     */
+    get extension(): string;
+    /**
+     * Whether the evidence is available (uploaded or verified)
+     */
+    get isAvailable(): boolean;
+    /**
+     * Whether the evidence is pending a file upload
+     */
+    get isPendingUpload(): boolean;
+    /**
+     * Whether the evidence has no file (data-only)
+     */
+    get isNoFile(): boolean;
+    /**
+     * Whether the evidence has been submitted for review
+     */
+    get isPendingReview(): boolean;
+    /**
+     * Whether the evidence has been verified
+     */
+    get isVerified(): boolean;
+    /**
+     * Whether the evidence was rejected
+     */
+    get isRejected(): boolean;
+    /**
+     * Evidence expiration date, if set
+     */
+    get expiresAt(): Date | undefined;
+    /**
+     * Days until evidence expires (negative if already expired).
+     * Returns undefined if no expiration is set.
+     */
+    get daysUntilExpiry(): number | undefined;
+    /**
+     * Reason the evidence was rejected, if any
+     */
+    get rejectionReason(): string | undefined;
+    /**
+     * Timestamp when the evidence was reviewed (verified or rejected)
+     */
+    get reviewedAt(): Date | undefined;
+    /**
+     * Opaque ID of the user who reviewed the evidence
+     */
+    get reviewedBy(): string | undefined;
+    /**
+     * Timestamp when the evidence was verified
+     */
+    get verifiedAt(): Date | undefined;
+    /**
+     * Opaque ID of the user who verified the evidence
+     */
+    get verifiedBy(): string | undefined;
+    /**
+     * Evidence-specific fields (extracted or provided data)
+     */
+    get fields(): Record<string, unknown> | undefined;
+    /**
+     * Get a specific field value
+     */
+    getField<T = unknown>(key: string): T | undefined;
+    /**
+     * External ID for idempotent operations
+     */
+    get externalId(): string | undefined;
+    /**
+     * Custom metadata attached to the evidence
+     */
+    get metadata(): Record<string, unknown> | undefined;
+    /**
+     * Get a specific metadata value
+     */
+    getMetadata<T = unknown>(key: string): T | undefined;
+    /**
+     * When the evidence record was created
+     */
+    get createdAt(): Date;
+    /**
+     * When the evidence record was last updated
+     */
+    get updatedAt(): Date;
+    /**
+     * Whether this is Mexico evidence
+     */
+    get isMexico(): boolean;
+}
+/**
+ * Type guard for Evidence model
+ */
+export declare function isEvidence(value: unknown): value is Evidence;

package/dist/models/Evidence.js

@@ -0,0 +1,298 @@
+/**
+ * Evidence model
+ *
+ * Represents a compliance evidence record optionally backed by a file.
+ * Evidence can be created with a file upload, with data fields only, or both.
+ */
+import { EvidenceStatus } from "@artu-ai/shared";
+import { BaseModel } from "./base";
+// ─────────────────────────────────────────────────────────────────
+// Evidence Model
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Evidence model - represents a compliance evidence record.
+ *
+ * @example
+ * ```typescript
+ * const evidence = await sdk.evidence.retrieve("ev_123");
+ *
+ * console.log(evidence.status);         // "uploaded"
+ * console.log(evidence.filename);       // "contrato.pdf"
+ * console.log(evidence.formattedSize);  // "1.2 MB"
+ * console.log(evidence.isAvailable);    // true
+ * ```
+ */
+export class Evidence extends BaseModel {
+    // ─────────────────────────────────────────────────────────────────
+    // Core Properties
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Unique identifier for this evidence record
+     */
+    get id() {
+        return this._data.id;
+    }
+    /**
+     * Scope for this evidence (MX, US)
+     */
+    get scope() {
+        return this._data.scope;
+    }
+    /**
+     * Evidence type (scope-specific)
+     */
+    get type() {
+        return this._data.type;
+    }
+    /**
+     * Evidence category
+     */
+    get category() {
+        return this._data.category;
+    }
+    /**
+     * Lifecycle status
+     */
+    get status() {
+        return this._data.status;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // File Properties
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Whether a file is attached to this evidence
+     */
+    get hasFile() {
+        return !!this._data.filename;
+    }
+    /**
+     * Original filename (undefined if no file attached)
+     */
+    get filename() {
+        return this._data.filename ?? undefined;
+    }
+    /**
+     * MIME content type (undefined if no file attached)
+     */
+    get contentType() {
+        return this._data.contentType ?? undefined;
+    }
+    /**
+     * File size in bytes (undefined if no file attached)
+     */
+    get size() {
+        return this._data.size ?? undefined;
+    }
+    /**
+     * Human-readable file size (e.g., "1.2 MB").
+     * Returns undefined if no file attached.
+     */
+    get formattedSize() {
+        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() {
+        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 evidence is available (uploaded or verified)
+     */
+    get isAvailable() {
+        return (this.status === EvidenceStatus.Uploaded ||
+            this.status === EvidenceStatus.Verified);
+    }
+    /**
+     * Whether the evidence is pending a file upload
+     */
+    get isPendingUpload() {
+        return this.status === EvidenceStatus.PendingUpload;
+    }
+    /**
+     * Whether the evidence has no file (data-only)
+     */
+    get isNoFile() {
+        return this.status === EvidenceStatus.NoFile;
+    }
+    /**
+     * Whether the evidence has been submitted for review
+     */
+    get isPendingReview() {
+        return this.status === EvidenceStatus.PendingReview;
+    }
+    /**
+     * Whether the evidence has been verified
+     */
+    get isVerified() {
+        return this.status === EvidenceStatus.Verified;
+    }
+    /**
+     * Whether the evidence was rejected
+     */
+    get isRejected() {
+        return this.status === EvidenceStatus.Rejected;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Validity
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Evidence expiration date, if set
+     */
+    get expiresAt() {
+        return this._data.expiresAt ? new Date(this._data.expiresAt) : undefined;
+    }
+    /**
+     * Days until evidence expires (negative if already expired).
+     * Returns undefined if no expiration is set.
+     */
+    get daysUntilExpiry() {
+        if (!this.expiresAt)
+            return undefined;
+        const now = new Date();
+        const diffTime = this.expiresAt.getTime() - now.getTime();
+        return Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Review Audit
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Reason the evidence was rejected, if any
+     */
+    get rejectionReason() {
+        const value = this._data.rejectionReason;
+        return typeof value === "string" ? value : undefined;
+    }
+    /**
+     * Timestamp when the evidence was reviewed (verified or rejected)
+     */
+    get reviewedAt() {
+        const value = this._data.reviewedAt;
+        return typeof value === "string" ? new Date(value) : undefined;
+    }
+    /**
+     * Opaque ID of the user who reviewed the evidence
+     */
+    get reviewedBy() {
+        const value = this._data.reviewedBy;
+        return typeof value === "string" ? value : undefined;
+    }
+    /**
+     * Timestamp when the evidence was verified
+     */
+    get verifiedAt() {
+        const value = this._data.verifiedAt;
+        return typeof value === "string" ? new Date(value) : undefined;
+    }
+    /**
+     * Opaque ID of the user who verified the evidence
+     */
+    get verifiedBy() {
+        const value = this._data.verifiedBy;
+        return typeof value === "string" ? value : undefined;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Fields
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Evidence-specific fields (extracted or provided data)
+     */
+    get fields() {
+        const value = this._data.fields;
+        return value ?? undefined;
+    }
+    /**
+     * Get a specific field value
+     */
+    getField(key) {
+        return this.fields?.[key];
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Metadata
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * External ID for idempotent operations
+     */
+    get externalId() {
+        return this._data.externalId ?? undefined;
+    }
+    /**
+     * Custom metadata attached to the evidence
+     */
+    get metadata() {
+        return this._data.metadata ?? undefined;
+    }
+    /**
+     * Get a specific metadata value
+     */
+    getMetadata(key) {
+        return this.metadata?.[key];
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Timestamps
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * When the evidence record was created
+     */
+    get createdAt() {
+        return new Date(this._data.createdAt);
+    }
+    /**
+     * When the evidence record was last updated
+     */
+    get updatedAt() {
+        return new Date(this._data.updatedAt);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Scope Helpers
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Whether this is Mexico evidence
+     */
+    get isMexico() {
+        return this._data.scope === "MX";
+    }
+}
+// ─────────────────────────────────────────────────────────────────
+// Type Guard
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Type guard for Evidence model
+ */
+export function isEvidence(value) {
+    return value instanceof Evidence;
+}
+// ─────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────
+/**
+ * Format bytes into a human-readable string
+ */
+function formatBytes(bytes) {
+    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++;
+    }
+    if (unitIndex === 0) {
+        return `${size} ${units[unitIndex]}`;
+    }
+    return `${size.toFixed(1)} ${units[unitIndex]}`;
+}

package/dist/models/LinkedClient.d.ts

@@ -59,4 +59,3 @@ export declare class LinkedClient extends BaseModel<LinkedClientData> {
  * Type guard for LinkedClient model.
  */
 export declare function isLinkedClient(obj: unknown): obj is LinkedClient;
-//# sourceMappingURL=LinkedClient.d.ts.map

package/dist/models/Product.d.ts

@@ -4,7 +4,7 @@
  * Pure data model with no API calls.
  * Provides type-safe access to common product properties.
  */
-import type { BaseProduct, EmbeddedTag, Jurisdiction } from "@artu-ai/shared";
+import type { BaseProduct, EmbeddedTag, Scope } from "@artu-ai/shared";
 import { BaseModel } from "./base";
 /**
  * Product data as returned from the API.
@@ -54,15 +54,15 @@ export declare class Product extends BaseModel<ProductData> {
      */
     get tags(): EmbeddedTag[];
     /**
-     * Checks if product has data for a specific jurisdiction
+     * Checks if product has data for a specific scope
      */
-    hasJurisdiction(jurisdiction: Jurisdiction): boolean;
+    hasScope(scope: Scope): boolean;
     /**
-     * Raw jurisdiction data object
+     * Raw scope data object
      */
-    get jurisdictions(): BaseProduct["jurisdictions"];
+    get scopeData(): BaseProduct["scopeData"];
     /**
-     * Raw data for jurisdiction-specific access
+     * Raw data for scope-specific access
      */
     get data(): ProductData;
     /**
@@ -83,4 +83,3 @@ export declare class Product extends BaseModel<ProductData> {
  * Check if value is any type of Product model
  */
 export declare function isProduct(value: unknown): value is Product;
-//# sourceMappingURL=Product.d.ts.map

package/dist/models/Product.js

@@ -64,24 +64,24 @@ export class Product extends BaseModel {
         return this._data.tags ?? [];
     }
     // ─────────────────────────────────────────────────────────────────
-    // Jurisdiction
+    // Scope
     // ─────────────────────────────────────────────────────────────────
     /**
-     * Checks if product has data for a specific jurisdiction
+     * Checks if product has data for a specific scope
      */
-    hasJurisdiction(jurisdiction) {
-        if (!this._data.jurisdictions)
+    hasScope(scope) {
+        if (!this._data.scopeData)
             return false;
-        return jurisdiction in this._data.jurisdictions;
+        return scope in this._data.scopeData;
     }
     /**
-     * Raw jurisdiction data object
+     * Raw scope data object
      */
-    get jurisdictions() {
-        return this._data.jurisdictions ?? {};
+    get scopeData() {
+        return this._data.scopeData ?? {};
     }
     /**
-     * Raw data for jurisdiction-specific access
+     * Raw data for scope-specific access
      */
     get data() {
         return this._data;

package/dist/models/Transaction.d.ts

@@ -4,14 +4,14 @@
  * Pure data model with no API calls.
  * Provides type-safe access to common transaction properties.
  */
-import type { BaseTransaction, EmbeddedTag, Jurisdiction, RiskAssessmentSnapshot, RiskAssessments } from "@artu-ai/shared";
+import type { EmbeddedTag, RelatedClient, RiskAssessmentSnapshot, RiskAssessments, Scope, TransactionResponse } from "@artu-ai/shared";
 import { TransactionStatus } from "@artu-ai/shared";
 import { BaseModel } from "./base";
 /**
  * Transaction data as returned from the API.
  * Extends the base schema with server-generated fields.
  */
-export interface TransactionData extends Omit<BaseTransaction, "timestamp"> {
+export interface TransactionData extends Omit<TransactionResponse, "timestamp"> {
     id: string;
     timestamp: string;
     createdAt: string;
@@ -26,7 +26,7 @@ export interface TransactionData extends Omit<BaseTransaction, "timestamp"> {
  * Base Transaction Model.
  *
  * Pure data model with no API calls.
- * Extended by jurisdiction-specific models (MexTransaction, etc.).
+ * Extended by scope-specific models (MexTransaction, etc.).
  *
  * @example
  * ```typescript
@@ -69,6 +69,13 @@ export declare class Transaction extends BaseModel<TransactionData> {
      * IDs of clients related to this transaction
      */
     get relatedClientIds(): string[];
+    /**
+     * Per-link client payload (with `role` + `metadata`) when the API
+     * populated it — `retrieve` and mutation responses include this.
+     * List endpoints may return only `relatedClientIds` for cost reasons,
+     * in which case this getter returns the same set with no role/metadata.
+     */
+    get relatedClients(): RelatedClient[];
     /**
      * Whether this transaction is referenced by at least one active alert item
      */
@@ -98,13 +105,13 @@ export declare class Transaction extends BaseModel<TransactionData> {
      */
     get tags(): EmbeddedTag[];
     /**
-     * Checks if transaction has data for a specific jurisdiction
+     * Checks if transaction has data for a specific scope
      */
-    hasJurisdiction(jurisdiction: Jurisdiction): boolean;
+    hasScope(scope: Scope): boolean;
     /**
-     * Raw jurisdiction data object
+     * Raw scope data object
      */
-    get jurisdictions(): BaseTransaction["jurisdictions"];
+    get scopeData(): TransactionResponse["scopeData"];
     /**
      * Raw risk assessments map — keyed by assessment name, each value is an
      * append-only array of snapshots representing the assessment history.
@@ -188,4 +195,3 @@ export declare class Transaction extends BaseModel<TransactionData> {
  * Check if value is any type of Transaction model
  */
 export declare function isTransaction(value: unknown): value is Transaction;
-//# sourceMappingURL=Transaction.d.ts.map

package/dist/models/Transaction.js

@@ -28,7 +28,7 @@ function applyRiskRounding(value, mode, decimalPlaces = 0) {
  * Base Transaction Model.
  *
  * Pure data model with no API calls.
- * Extended by jurisdiction-specific models (MexTransaction, etc.).
+ * Extended by scope-specific models (MexTransaction, etc.).
  *
  * @example
  * ```typescript
@@ -106,6 +106,16 @@ export class Transaction extends BaseModel {
     get relatedClientIds() {
         return this._data.relatedClientIds ?? [];
     }
+    /**
+     * Per-link client payload (with `role` + `metadata`) when the API
+     * populated it — `retrieve` and mutation responses include this.
+     * List endpoints may return only `relatedClientIds` for cost reasons,
+     * in which case this getter returns the same set with no role/metadata.
+     */
+    get relatedClients() {
+        return (this._data.relatedClients ??
+            this.relatedClientIds.map((clientId) => ({ clientId })));
+    }
     /**
      * Whether this transaction is referenced by at least one active alert item
      */
@@ -137,7 +147,7 @@ export class Transaction extends BaseModel {
         return this._data.productId;
     }
     // ─────────────────────────────────────────────────────────────────
-    // Jurisdiction
+    // Scope
     // ─────────────────────────────────────────────────────────────────
     /**
      * Scopes this transaction belongs to (e.g. ["MX", "MX:AV:AVI"]).
@@ -152,18 +162,18 @@ export class Transaction extends BaseModel {
         return this._data.tags ?? [];
     }
     /**
-     * Checks if transaction has data for a specific jurisdiction
+     * Checks if transaction has data for a specific scope
      */
-    hasJurisdiction(jurisdiction) {
-        if (!this._data.jurisdictions)
+    hasScope(scope) {
+        if (!this._data.scopeData)
             return false;
-        return jurisdiction in this._data.jurisdictions;
+        return scope in this._data.scopeData;
     }
     /**
-     * Raw jurisdiction data object
+     * Raw scope data object
      */
-    get jurisdictions() {
-        return this._data.jurisdictions ?? {};
+    get scopeData() {
+        return this._data.scopeData ?? {};
     }
     // ─────────────────────────────────────────────────────────────────
     // Risk Assessments