TypeScript SDK - Artu Compliance SDK

The @artu-ai/compliance-sdk package is the recommended way to interact with the Artu Compliance API from TypeScript or JavaScript. It provides full type safety, async iterators, and convenient helper methods built on top of the HTTP API.

Installation

npm install @artu-ai/compliance-sdk
# or
pnpm add @artu-ai/compliance-sdk
# or
yarn add @artu-ai/compliance-sdk

Instantiation

import { ComplianceSDK } from "@artu-ai/compliance-sdk";

const sdk = new ComplianceSDK({
  apiKey: process.env.ARTU_API_KEY,
  environment: "test",
});

The API key can also be read automatically from the ARTU_API_KEY environment variable if apiKey is omitted.

Constructor Options

apiKey

string

Your Artu API key. If omitted, the SDK reads the ARTU_API_KEY environment variable.

environment

'test' | 'live'

default:"test"

Target environment. "test" uses isolated test data; "live" targets production data and regulatory submissions.Can also be set via the ARTU_ENVIRONMENT environment variable.

scope

Scope

Constrains the SDK to a specific compliance scope/activity. Uses colon-separated format, for example "MX", "MX:AV:AVI", or "MX:CNBV:TRANSMISOR".When set, create operations default to that scope and list operations filter by it automatically.

baseUrl

string

Override the API base URL. Defaults to https://api.artu.ai. Useful for local development.Can also be set via the ARTU_BASE_URL environment variable.

timeout

number

default:"30000"

Request timeout in milliseconds.

validation.enablePostalCodeValidation

boolean

default:"false"

When true, the SDK validates postal code format client-side before sending address requests. Mirror your tenant’s postal-code setting here for consistent behavior.

Instance Properties

Environment

Property	Type	Description
`environment`	`"test" \| "live"`	Current environment
`isTest`	`boolean`	`true` when environment is `"test"`
`isLive`	`boolean`	`true` when environment is `"live"`
`apiVersion`	`string`	API version in use
`baseUrl`	`string`	Resolved API base URL

Scope

Property	Type	Description
`scope`	`Scope \| undefined`	Current scope string, if any
`isScoped`	`boolean`	`true` when a scope is set

Resources

The SDK exposes the following resource managers:

Resource	Description
`clients`	Create, retrieve, update, delete, and list clients
`transactions`	Create, retrieve, update, delete, and list transactions
`addresses`	Address management for clients
`contactMethods`	Email, phone, and other contact method management
`bankAccounts`	Bank account management for clients
`documents`	Document upload, download, and lifecycle management
`evidence`	Compliance evidence record management
`alerts`	Regulatory alert generation and submission
`reports`	Read-only access to generated report files
`workflows`	Monitoring workflow management
`workflows.variables`	Configurable workflow threshold and value management
`exchangeRates`	Exchange rate lookups with caching
`referenceData`	Read-only reference datasets (postal codes, Basel AML, etc.)
`tenant`	Organization-level metadata
`tags`	Org-scoped tag management
`roles`	Role management and user role assignments
`users`	Organization member management
`apiKeys`	API key management with role-based permissions
`auditLogs`	Read-only immutable audit trail

Scoped SDK Instances

Passing a scope option to the constructor returns a strongly-typed SDK instance whose resource methods accept and return scope-specific model types. TypeScript infers the correct return type automatically:

import { ComplianceSDK } from "@artu-ai/compliance-sdk";

// Unscoped — base Client / Transaction / Alert types
const sdk = new ComplianceSDK({ apiKey, environment: "test" });

// Mexico-scoped — MexClient / MexTransaction / MexAlert types
const mexSdk = new ComplianceSDK({
  apiKey,
  environment: "test",
  scope: "MX",
});

// AVI-scoped — MexAVIClient / MexAVITransaction / MexAVIAlert types
const aviSdk = new ComplianceSDK({
  apiKey,
  environment: "test",
  scope: "MX:AV:AVI",
});

console.log(aviSdk.scope);     // "MX:AV:AVI"
console.log(aviSdk.isScoped);  // true

When the SDK is scoped:

Create operations automatically apply the scope to new records.
List operations automatically filter to records in that scope.
Models returned are the narrowed type for that scope (e.g. MexAVIClient instead of Client), giving direct access to scope-specific fields without type guards.

Scoped Sub-Exports

For tree-shaking or when you want to import the fully typed SDK class for a specific scope directly, use the sub-entry points:

// Main export (unscoped constructor — uses scope option for dispatch)
import { ComplianceSDK } from "@artu-ai/compliance-sdk";

// Mexico
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx";

// Mexico > Actividad Vulnerable
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/av";

// Mexico > Actividad Vulnerable > individual scopes
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/av/avi";
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/av/jys";
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/av/mjr";
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/av/tsc";
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/av/ari";
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/av/inm";
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/av/mpc";

// Mexico > CNBV
import { ComplianceSDK } from "@artu-ai/compliance-sdk/mx/cnbv/transmisor";

Each sub-export exposes a ComplianceSDK class whose constructor does not require a scope option (the scope is baked in), and whose resources are fully typed for that scope. Sub-exports also expose scope-specific Enums and TypeGuards namespaces:

import { Enums, TypeGuards } from "@artu-ai/compliance-sdk/mx/av/avi";

// Access AVI-specific enums
const { TipoOperacion, TipoAlerta, ActivoVirtual } = Enums;

// Use scope-specific type guards
if (TypeGuards.isClient(client)) {
  console.log(client.dominioPlataforma);
}

Available Scopes

Scope string	Sub-export path	Description
`"MX"`	`@artu-ai/compliance-sdk/mx`	Mexico (all activities)
`"MX:AV:AVI"`	`@artu-ai/compliance-sdk/mx/av/avi`	Activos Virtuales (virtual assets)
`"MX:AV:JYS"`	`@artu-ai/compliance-sdk/mx/av/jys`	Juegos y Sorteos (games/lotteries)
`"MX:AV:MJR"`	`@artu-ai/compliance-sdk/mx/av/mjr`	Metales y Joyas al por Menor
`"MX:AV:TSC"`	`@artu-ai/compliance-sdk/mx/av/tsc`	Tarjetas de Servicio y Crédito
`"MX:AV:ARI"`	`@artu-ai/compliance-sdk/mx/av/ari`	Arrendadoras e Inmobiliarias
`"MX:AV:INM"`	`@artu-ai/compliance-sdk/mx/av/inm`	Inmobiliarias
`"MX:AV:MPC"`	`@artu-ai/compliance-sdk/mx/av/mpc`	Mutuo, Préstamos y Créditos
`"MX:CNBV:TRANSMISOR"`	`@artu-ai/compliance-sdk/mx/cnbv/transmisor`	Transmisores de Dinero

For the full per-scope field reference, see the Scopes tab. For Mexico-specific validators (RFC, CURP, CLABE), see the Mexico page.

Type Exports

The SDK re-exports all types you need for integration:

import {
  // SDK class
  ComplianceSDK,
  type ComplianceSDKOptions,

  // Enums
  ClientType,
  ClientRole,
  ClientRelationshipType,
  AddressType,
  BankAccountType,
  ContactMethodType,
  Currency,
  Country,
  DocumentCategory,
  DocumentStatus,
  TransactionStatus,
  AlertStatus,

  // Models
  type Client,
  type Transaction,
  type Address,
  type Document,
  type Alert,
  type BankAccount,

  // Input types
  type CreateClientInput,
  type UpdateClientInput,
  type CreateTransactionInput,
  type UpsertProductInput,

  // Filter utilities
  contains,
  dateRange,
  oneOf,

  // Pagination utilities
  collectAll,
  collectUpTo,
  getFirst,

  // Error classes
  ComplianceError,
  ValidationError,
  NotFoundError,
  APIError,
  UploadError,
} from "@artu-ai/compliance-sdk";

Error Handling

All SDK methods throw typed errors on failure. See Errors for the full error reference.

import { NotFoundError, ValidationError, RateLimitError } from "@artu-ai/compliance-sdk";

try {
  const client = await sdk.clients.retrieve("client_123");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Client not found:", error.resourceId);
  } else if (error instanceof ValidationError) {
    for (const issue of error.issues) {
      console.log(`${issue.path.join(".")}: ${issue.message}`);
    }
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited — retry after ${error.retryAfter}s`);
  }
}

​Installation

​Instantiation

​Constructor Options

​Instance Properties

​Environment

​Scope

​Resources

​Scoped SDK Instances

​Scoped Sub-Exports

​Available Scopes

​Type Exports

​Error Handling

Installation

Instantiation

Constructor Options

Instance Properties

Environment

Scope

Resources

Scoped SDK Instances

Scoped Sub-Exports

Available Scopes

Type Exports

Error Handling