@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/errors/validation.ts

@@ -0,0 +1,163 @@
+/**
+ * Validation error class
+ *
+ * Thrown when input validation fails, either client-side (Zod)
+ * or server-side (API validation).
+ */
+
+import type { ZodError } from "zod";
+import { ComplianceError } from "./base";
+
+// ===========================
+// Types
+// ===========================
+
+/**
+ * A single validation issue
+ */
+export interface ValidationIssue {
+  /**
+   * Path to the field that failed validation.
+   * Example: ["addresses", "0", "postalCode"]
+   */
+  path: PropertyKey[];
+
+  /**
+   * Human-readable error message
+   */
+  message: string;
+
+  /**
+   * Validation rule that failed (optional)
+   */
+  code?: string;
+}
+
+// ===========================
+// Validation Error Class
+// ===========================
+
+/**
+ * Error thrown when input validation fails.
+ *
+ * Contains structured information about which fields failed
+ * and why, making it easy to display errors in forms.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.clients.create({ name: "" });
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     error.issues.forEach((issue) => {
+ *       console.log(`${issue.path.join(".")}: ${issue.message}`);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class ValidationError extends ComplianceError {
+  /**
+   * List of validation issues
+   */
+  public readonly issues: ValidationIssue[];
+
+  constructor(issues: ValidationIssue[], requestId?: string) {
+    const message = ValidationError.formatMessage(issues);
+    super(message, "VALIDATION_ERROR", {
+      requestId,
+      details: { issues },
+    });
+    this.name = "ValidationError";
+    this.issues = issues;
+  }
+
+  /**
+   * Creates a ValidationError from a Zod error.
+   *
+   * @param error - Zod validation error
+   * @param requestId - Optional request ID for tracing
+   * @returns ValidationError with formatted issues
+   */
+  static fromZodError(error: ZodError, requestId?: string): ValidationError {
+    const issues: ValidationIssue[] = error.issues.map((issue) => ({
+      path: issue.path,
+      message: issue.message,
+      code: issue.code,
+    }));
+    return new ValidationError(issues, requestId);
+  }
+
+  /**
+   * Gets validation errors for a specific field path.
+   *
+   * @param path - Field path (e.g., "name" or "addresses.0.city")
+   * @returns Array of error messages for the field
+   *
+   * @example
+   * ```typescript
+   * const nameErrors = error.getFieldErrors("name");
+   * // ["Name is required", "Name must be at least 2 characters"]
+   * ```
+   */
+  getFieldErrors(path: string): string[] {
+    const pathParts = path.split(".");
+    return this.issues
+      .filter((issue) => {
+        if (issue.path.length !== pathParts.length) return false;
+        return pathParts.every((part, i) => String(issue.path[i]) === part);
+      })
+      .map((issue) => issue.message);
+  }
+
+  /**
+   * Checks if a specific field has validation errors.
+   *
+   * @param path - Field path to check
+   * @returns True if the field has errors
+   */
+  hasFieldError(path: string): boolean {
+    return this.getFieldErrors(path).length > 0;
+  }
+
+  /**
+   * Gets a flat object of field paths to error messages.
+   * Useful for form libraries.
+   *
+   * @returns Object mapping field paths to error messages
+   *
+   * @example
+   * ```typescript
+   * const fieldErrors = error.toFieldErrors();
+   * // { "name": "Name is required", "email": "Invalid email" }
+   * ```
+   */
+  toFieldErrors(): Record<string, string> {
+    const errors: Record<string, string> = {};
+    for (const issue of this.issues) {
+      const path = issue.path.join(".");
+      // Only keep first error per field
+      if (!errors[path]) {
+        errors[path] = issue.message;
+      }
+    }
+    return errors;
+  }
+
+  /**
+   * Formats the validation issues into a human-readable message.
+   */
+  private static formatMessage(issues: ValidationIssue[]): string {
+    if (issues.length === 0) {
+      return "Validation failed";
+    }
+    if (issues.length === 1) {
+      const [issue] = issues;
+      if (issue) {
+        const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+        return `Validation failed: ${path}${issue.message}`;
+      }
+    }
+    return `Validation failed with ${issues.length} errors`;
+  }
+}

package/src/exports/base.ts

@@ -0,0 +1,139 @@
+/**
+ * Base exports shared across all entry points
+ *
+ * @internal - Not meant for direct import by users
+ */
+
+// ===========================
+// Errors
+// ===========================
+
+export {
+  ComplianceError,
+  type ComplianceErrorOptions,
+  type ComplianceErrorJSON,
+  ValidationError,
+  type ValidationIssue,
+  APIError,
+  NotFoundError,
+  UnauthorizedError,
+  ForbiddenError,
+  RateLimitError,
+  ServerError,
+  NetworkError,
+  TimeoutError,
+  UploadError,
+  FileTooLargeError,
+  UploadTimeoutError,
+  InvalidFileTypeError,
+  UploadAbortedError,
+  UploadUrlExpiredError,
+  mapTRPCError,
+  isAPIError,
+  isUploadError,
+  type UploadStage,
+} from "../errors";
+
+// ===========================
+// Utilities
+// ===========================
+
+export {
+  collectAll,
+  collectUpTo,
+  getFirst,
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+  contains,
+  startsWith,
+  endsWith,
+  equals,
+  notEquals,
+  oneOf,
+  notOneOf,
+  dateRange,
+  after,
+  before,
+  onOrAfter,
+  onOrBefore,
+  numberRange,
+  greaterThan,
+  lessThan,
+  atLeast,
+  atMost,
+  isTrue,
+  isFalse,
+  isNull,
+  isNotNull,
+  type Environment,
+} from "../utils";
+
+// ===========================
+// Session Types (for SDK.session() method)
+// ===========================
+
+export type {
+  SDKSessionOptions,
+  SDKSessionOptionsWithReturnTo,
+  SessionResult,
+  SessionResultWithRedirect,
+  SessionResultWithoutRedirect,
+  SessionResultAuthenticated,
+  SessionResultUnauthenticatedWithRedirect,
+  SessionResultUnauthenticatedNoRedirect,
+  SessionInfo,
+} from "../utils";
+
+// ===========================
+// Base Models (non-scoped entities)
+// ===========================
+
+export {
+  Address,
+  type AddressData,
+  ContactMethod,
+  type ContactMethodData,
+  Document,
+  type DocumentData,
+} from "../models";
+
+// ===========================
+// Base Resources (non-scoped entities)
+// ===========================
+
+export {
+  AddressesResource,
+  ContactMethodsResource,
+  DocumentsResource,
+} from "../resources";
+
+// ===========================
+// Shared Types from Shared Package
+// ===========================
+
+export type {
+  // Address types (non-scoped)
+  CreateAddressInput,
+  UpdateAddressInput,
+  // Contact method types (non-scoped)
+  CreateContactMethodInput,
+  UpdateContactMethodInput,
+  // Document types (non-scoped)
+  CreateDocumentInput,
+  UpdateDocumentInput,
+  // Pagination
+  PaginationInput,
+  PaginatedResponse,
+  PaginationMeta,
+  ListOptions,
+  IterateOptions,
+  // Filters
+  ClientFilter,
+  TransactionFilter,
+  DocumentFilter,
+  BankAccountFilter,
+  // API error responses
+  APIError as APIErrorResponse,
+  APIValidationError as APIValidationErrorResponse,
+  BatchResult,
+} from "@artu-ai/shared";

package/src/exports/index.ts

@@ -0,0 +1,187 @@
+/**
+ * @artu/compliance-sdk
+ *
+ * TypeScript SDK for the Global Compliance API
+ *
+ * @example
+ * ```typescript
+ * import { ComplianceSDK, ClientType, Jurisdiction, Mexico } from "@artu/compliance-sdk";
+ *
+ * const sdk = new ComplianceSDK({
+ *   apiKey: process.env.COMPLIANCE_API_KEY!,
+ *   environment: "test",
+ * });
+ *
+ * // Create a client
+ * const client = await sdk.clients.create({
+ *   type: ClientType.Person,
+ *   name: "Juan García",
+ *   primaryJurisdiction: Jurisdiction.Mexico,
+ * });
+ *
+ * // List transactions
+ * for await (const txn of sdk.transactions.iterate()) {
+ *   console.log(txn.id, txn.amount);
+ * }
+ *
+ * // Access Mexico-specific functionality via namespace
+ * Mexico.Enums.ActividadEconomica
+ * Mexico.Validators.Rfc.validate("...")
+ * ```
+ */
+
+// ===========================
+// SDK
+// ===========================
+
+export {
+  ComplianceSDK,
+  type ComplianceSDKOptions,
+  type ComplianceSDKConstructor,
+  type SDKScope,
+  type UnscopedComplianceSDK,
+  type SessionInfo,
+} from "../sdk";
+
+// ===========================
+// Enums
+// ===========================
+
+export {
+  // Enum values
+  ClientType,
+  Jurisdiction,
+  AddressType,
+  ContactMethodType,
+  TransactionStatus,
+  DocumentStatus,
+  DocumentCategory,
+  ReportStatus,
+  BankAccountType,
+  ClientRole,
+  ClientRelationshipType,
+  Country,
+  Currency,
+  // Enum utilities (with .enum, .map, .codes, .options, .schema())
+  ClientTypes,
+  Jurisdictions,
+  AddressTypes,
+  ContactMethodTypes,
+  TransactionStatuses,
+  DocumentStatuses,
+  DocumentCategories,
+  ReportStatuses,
+  BankAccountTypes,
+  ClientRoles,
+  ClientRelationshipTypes,
+} from "@artu-ai/shared";
+
+// ===========================
+// Jurisdiction Namespaces
+// ===========================
+
+export { Mexico } from "../namespaces/mexico";
+
+// ===========================
+// Base Resources
+// ===========================
+
+export {
+  BaseResource,
+  ReadOnlyResource,
+  type ResourceConfig,
+  ClientsResource,
+  TransactionsResource,
+  type RelatedClient,
+  BankAccountsResource,
+  ReportsResource,
+  type ReportFilter,
+  type ReportItemFilter,
+  type AddItemsResult,
+  DocumentsResource,
+  type CreateDocumentResult,
+} from "../resources";
+
+// ===========================
+// Base Models
+// ===========================
+
+export {
+  BaseModel,
+  Client,
+  type ClientData,
+  Transaction,
+  type TransactionData,
+  Report,
+  type ReportData,
+  ReportItem,
+  type ReportItemData,
+  BankAccount,
+  type BankAccountData,
+  LinkedClient,
+  type LinkedClientData,
+  type ClientModel,
+  type TransactionModel,
+  type BankAccountModel,
+  type ReportModel,
+  type ReportItemModel,
+  isClient,
+  isIndividual,
+  isCompany,
+  isTrust,
+  isTransaction,
+  isBankAccount,
+  isReport,
+  isReportItem,
+  isLinkedClient,
+} from "../models";
+
+// ===========================
+// Schema Types (raw API types)
+// ===========================
+
+export type {
+  BaseClient,
+  Address as AddressSchema,
+  BaseTransaction,
+  Document as DocumentSchema,
+  ContactMethod as ContactMethodSchema,
+  Report as ReportSchema,
+  ReportItem as ReportItemSchema,
+  BankAccount as BankAccountSchema,
+  // Value types
+  CountryIso2,
+  CountryIso3,
+  CurrencyCode,
+} from "@artu-ai/shared";
+
+// ===========================
+// Scoped Types (base scope)
+// ===========================
+
+export type {
+  // Client types
+  CreateClientInput,
+  UpdateClientInput,
+  // Transaction types
+  CreateTransactionInput,
+  UpdateTransactionInput,
+  // Report types
+  CreateReportInput,
+  UpdateReportInput,
+  CreateReportItemInput,
+  ReportValidationError,
+  ValidationSummary,
+  ValidationResult,
+  GenerateResult,
+  SubmissionResult,
+  // Bank account types
+  CreateBankAccountInput,
+  UpdateBankAccountInput,
+} from "@artu-ai/shared";
+
+// ===========================
+// Base Exports (errors, utilities, etc.)
+// ===========================
+
+export * from "./base";

package/src/exports/mexico/actividad-vulnerable/avi.ts

@@ -0,0 +1,207 @@
+/**
+ * @artu/compliance-sdk/mexico/actividad-vulnerable/avi
+ *
+ * AVI (Activos Virtuales) scoped SDK entry point.
+ * Import from here for virtual asset compliance workflows.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   ComplianceSDK,
+ *   Enums,
+ *   Validators,
+ *   Models,
+ *   Resources,
+ *   TypeGuards,
+ * } from "@artu/compliance-sdk/mexico/actividad-vulnerable/avi";
+ *
+ * const sdk = new ComplianceSDK({
+ *   apiKey: process.env.COMPLIANCE_API_KEY!,
+ *   jurisdiction: "MX",
+ *   actividadVulnerable: "AVI",
+ * });
+ *
+ * // AVI-specific enums (flat, no nesting)
+ * Enums.TipoOperacion.Buy
+ * Enums.TipoAlerta.Inusual
+ *
+ * // Validators
+ * Validators.Rfc.validate("GOAP820528H00")
+ * ```
+ */
+
+import {
+  avi,
+  CodigoActividad,
+  CodigosActividad,
+  Moneda,
+  Monedas,
+  TipoIdentificacion,
+  TiposIdentificacion,
+  Prioridad,
+  Prioridades,
+  Rfc,
+  Curp,
+  Clabe,
+} from "@artu-ai/shared";
+
+import {
+  MexAVIClient,
+  MexAVITransaction,
+  MexAVIReport,
+  MexAVIReportItem,
+  isMexAVIClient,
+  isMexAVITransaction,
+  isMexAVIReport,
+  isMexAVIReportItem,
+  MexBankAccount,
+  type MexBankAccountData,
+} from "../../../models";
+
+import {
+  AVIClientsResource,
+  AVITransactionsResource,
+  AVIReportsResource,
+  MexBankAccountsResource,
+} from "../../../resources";
+
+// ===========================
+// SDK
+// ===========================
+
+import {
+  AVIComplianceSDKScoped,
+  type AVIScopedSDKOptions,
+} from "../../../sdk/mex/actividad-vulnerable/avi";
+
+/** Options for AVI-scoped SDK */
+export type ComplianceSDKOptions = AVIScopedSDKOptions;
+
+/** AVI-scoped ComplianceSDK - re-exported from sdk */
+export { AVIComplianceSDKScoped as ComplianceSDK };
+
+// ===========================
+// Enums (flat - AVI specific + Actividad Vulnerable base)
+// ===========================
+
+export const Enums = {
+  // AVI-specific enum values
+  TipoOperacion: avi.TipoOperacion,
+  TipoAlerta: avi.TipoAlerta,
+  InstrumentoMonetario: avi.InstrumentoMonetario,
+  ActivoVirtual: avi.ActivoVirtual,
+  // AVI-specific enum utilities
+  TiposOperacion: avi.TiposOperacion,
+  TiposAlerta: avi.TiposAlerta,
+  InstrumentosMonetarios: avi.InstrumentosMonetarios,
+  ActivosVirtuales: avi.ActivosVirtuales,
+  // Actividad Vulnerable base enum values
+  CodigoActividad,
+  Moneda,
+  TipoIdentificacion,
+  Prioridad,
+  // Actividad Vulnerable base enum utilities
+  CodigosActividad,
+  Monedas,
+  TiposIdentificacion,
+  Prioridades,
+} as const;
+
+// ===========================
+// Validators
+// ===========================
+
+export const Validators = {
+  Rfc,
+  Curp,
+  Clabe,
+} as const;
+
+// ===========================
+// Models (flat)
+// ===========================
+
+export const Models = {
+  Client: MexAVIClient,
+  Transaction: MexAVITransaction,
+  Report: MexAVIReport,
+  ReportItem: MexAVIReportItem,
+  BankAccount: MexBankAccount,
+} as const;
+
+export {
+  MexAVIClient as Client,
+  MexAVITransaction as Transaction,
+  MexAVIReport as Report,
+  MexAVIReportItem as ReportItem,
+  MexBankAccount as BankAccount,
+  type MexBankAccountData as BankAccountData,
+};
+
+// ===========================
+// Resources (scoped + base for non-scoped)
+// ===========================
+
+export const Resources = {
+  Clients: AVIClientsResource,
+  Transactions: AVITransactionsResource,
+  Reports: AVIReportsResource,
+  BankAccounts: MexBankAccountsResource,
+} as const;
+
+export {
+  AVIClientsResource as ClientsResource,
+  AVITransactionsResource as TransactionsResource,
+  AVIReportsResource as ReportsResource,
+  MexBankAccountsResource as BankAccountsResource,
+};
+
+// ===========================
+// TypeGuards (flat)
+// ===========================
+
+export const TypeGuards = {
+  isClient: isMexAVIClient,
+  isTransaction: isMexAVITransaction,
+  isReport: isMexAVIReport,
+  isReportItem: isMexAVIReportItem,
+} as const;
+
+export {
+  isMexAVIClient as isClient,
+  isMexAVITransaction as isTransaction,
+  isMexAVIReport as isReport,
+  isMexAVIReportItem as isReportItem,
+};
+
+// ===========================
+// Scoped Types (AVI) - aliased for convenience
+// ===========================
+
+export type {
+  // Client types
+  CreateAVIClientInput as CreateClientInput,
+  UpdateAVIClientInput as UpdateClientInput,
+  // Transaction types
+  CreateAVITransactionInput as CreateTransactionInput,
+  UpdateAVITransactionInput as UpdateTransactionInput,
+  // Report types
+  CreateAVIReportInput as CreateReportInput,
+  UpdateAVIReportInput as UpdateReportInput,
+  CreateAVIReportItemInput as CreateReportItemInput,
+  UpdateAVIReportItemInput as UpdateReportItemInput,
+  ReportValidationError,
+  ValidationSummary,
+  ValidationResult,
+  GenerateResult,
+  SubmissionResult,
+  // Bank account types (uses Mexico scope)
+  CreateMexBankAccountInput as CreateBankAccountInput,
+  UpdateMexBankAccountInput as UpdateBankAccountInput,
+} from "@artu-ai/shared";
+
+// ===========================
+// Base Exports (errors, utilities, base models/resources)
+// ===========================
+
+export * from "../../base";