> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> The @artu-ai/compliance-sdk client — installation, instantiation, and scope-typed instances

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

```bash theme={null}
npm install @artu-ai/compliance-sdk
# or
pnpm add @artu-ai/compliance-sdk
# or
yarn add @artu-ai/compliance-sdk
```

## Instantiation

```typescript theme={null}
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

<ParamField body="apiKey" type="string">
  Your Artu API key. If omitted, the SDK reads the `ARTU_API_KEY` environment variable.
</ParamField>

<ParamField body="environment" type="'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.
</ParamField>

<ParamField body="scope" type="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.
</ParamField>

<ParamField body="baseUrl" type="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.
</ParamField>

<ParamField body="timeout" type="number" default="30000">
  Request timeout in milliseconds.
</ParamField>

<ParamField body="validation.enablePostalCodeValidation" type="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.
</ParamField>

## 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:

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
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](/scopes/overview). For Mexico-specific validators (RFC, CURP, CLABE), see the [Mexico page](/scopes/mexico).

## Type Exports

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

```typescript theme={null}
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](/sdk/errors) for the full error reference.

```typescript theme={null}
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`);
  }
}
```