@artu-ai/compliance-sdk

Type-safe TypeScript SDK for the Artu Compliance API — manage KYC/KYB clients, transactions, alerts, documents, and regulatory reporting, with first-class support for jurisdiction-specific compliance scopes (e.g. Mexico AML).

• 🔒 Fully typed requests and responses
• 🌎 Scope-aware: get types specific to a jurisdiction + activity (e.g. Mexico · Actividad Vulnerable · Activos Virtuales)
• 🔁 Async auto-pagination
• ✅ Client-side validation with clear, typed errors

Installation

npm install @artu-ai/compliance-sdk

pnpm add @artu-ai/compliance-sdk

yarn add @artu-ai/compliance-sdk

@artu-ai/shared and zod are installed automatically as dependencies.

Quick start

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

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

// Create a client
const client = await sdk.clients.create({
  type: ClientType.Individual,
  name: "Juan García",
  scopes: ["MX"],
});

// Retrieve, update
await sdk.clients.update(client.id, { name: "Juan A. García" });

// Auto-paginate
for await (const txn of sdk.transactions.iterate()) {
  console.log(txn.id, txn.amount);
}

Authentication & configuration

const sdk = new ComplianceSDK({
  apiKey: "sk_test_...",   // or the ARTU_API_KEY env var
  environment: "test",      // "test" | "live"  (or ARTU_ENVIRONMENT)

  // Optional
  scope: "MX:AV:AVI",       // see "Scopes" below
  baseUrl: "https://api.artu.ai",
  organizationId: "org_...",
  apiVersion: "v1",
  timeout: 30000,            // ms
});

Configuration can also be supplied via environment variables: ARTU_API_KEY, ARTU_ENVIRONMENT, ARTU_BASE_URL, ARTU_ORGANIZATION_ID.

Browser / server-side (cookie auth)

For session-cookie authentication (e.g. a dashboard or a Next.js server component), use cookie mode instead of an API key:

// Browser — send the session cookie with each request
const sdk = new ComplianceSDK({ mode: "cookie", environment: "test", credentials: "include" });

// Next.js server component — forward the incoming cookie
import { cookies } from "next/headers";
const sdk = new ComplianceSDK({
  mode: "cookie",
  environment: "test",
  headers: { cookie: (await cookies()).toString() },
});

Scopes

Scopes partition data by jurisdiction and regulated activity. Pass a scope and the SDK returns an instance whose resources are typed for that scope:

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

// Mexico
const mx = new ComplianceSDK({ apiKey, environment: "test", scope: "MX" });

// Mexico · Actividad Vulnerable · Activos Virtuales (crypto) — AVI-typed resources
const avi = new ComplianceSDK({ apiKey, environment: "test", scope: "MX:AV:AVI" });

avi.scope;       // "MX:AV:AVI"
avi.isScoped;    // true
avi.environment; // "test"
avi.isTest;      // true

Scoped entry points

For static typing without runtime dispatch, import from a scope-specific entry point. Each re-exports the input/output types and resources for that scope:

import {
  ComplianceSDK,
  type CreateClientInput, // AVI-specific
  type Client,            // AVI-typed
} from "@artu-ai/compliance-sdk/mx/av/avi";

Available entry points:

| Import path | Scope | | --- | --- | | @artu-ai/compliance-sdk | Base (all data) | | @artu-ai/compliance-sdk/mx | Mexico | | @artu-ai/compliance-sdk/mx/av/avi | MX · Actividad Vulnerable · Activos Virtuales | | @artu-ai/compliance-sdk/mx/av/ari | MX · Actividad Vulnerable · Arrendamiento | | @artu-ai/compliance-sdk/mx/av/inm | MX · Actividad Vulnerable · Inmuebles | | @artu-ai/compliance-sdk/mx/av/jys | MX · Actividad Vulnerable · Joyería y Piedras | | @artu-ai/compliance-sdk/mx/av/mjr | MX · Actividad Vulnerable · Metales y Joyas | | @artu-ai/compliance-sdk/mx/av/tsc | MX · Actividad Vulnerable · Tarjetas de Servicio | | @artu-ai/compliance-sdk/mx/cnbv | MX · CNBV | | @artu-ai/compliance-sdk/mx/cnbv/transmisor | MX · CNBV · Transmisores de Dinero |

Resources

Resources are accessed as properties on the SDK instance. Each supports the standard operations — list, retrieve, create, update, delete — and list endpoints also provide iterate() for async auto-pagination.

| Resource | Description | | --- | --- | | sdk.clients | KYC/KYB clients (individuals, companies, trusts) | | sdk.transactions | Transactions | | sdk.alerts | Regulatory alerts (also generate, validate, submit) | | sdk.documents | Documents | | sdk.evidence | Supporting evidence and file uploads | | sdk.addresses | Addresses | | sdk.bankAccounts | Bank accounts | | sdk.contactMethods | Contact methods | | sdk.products | Products | | sdk.reports | Regulatory reports | | sdk.exchangeRates | Exchange rates (read-only) | | sdk.workflows | Compliance workflows | | sdk.auditLogs | Audit trail (read-only) | | sdk.tenant | Tenant settings and defaults |

The SDK also exposes account-management resources (sdk.users, sdk.roles, sdk.apiKeys). Workflow tooling is nested under sdk.workflows — sdk.workflows.executions, .variables, .templates, and .links. See the full API reference in the Artu documentation.

Models

Resource methods return immutable model instances with typed accessors and type guards:

const client = await sdk.clients.retrieve("client_123");

if (client.isIndividual) {
  console.log(client.birthDate);
} else if (client.isCompany) {
  console.log(client.incorporationDate);
}

// Models are immutable data containers — persist changes through the resource:
const updated = await sdk.clients.update(client.id, { name: "New Name" });

Pagination

// Auto-pagination
for await (const client of sdk.clients.iterate()) {
  console.log(client.id);
}

// Manual pagination
const page1 = await sdk.clients.list({ limit: 10 });
if (page1.hasMore) {
  const page2 = await sdk.clients.list({
    limit: 10,
    startingAfter: page1.data[page1.data.length - 1].id,
  });
}

Filtering & sorting

const clients = await sdk.clients.list({
  filter: { type: "individual" },
  sort: { field: "createdAt", order: "desc" },
});

Error handling

All errors extend ComplianceError. The two you'll handle most often are ValidationError (client-side input validation) and APIError (errors returned by the API):

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

try {
  await sdk.clients.create({ /* ... */ });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log("Invalid input:", error.errors);
  } else if (error instanceof APIError) {
    console.log("API error:", error.code, error.message);
  }
}

APIError has typed subclasses you can narrow on when useful: NotFoundError, UnauthorizedError, ForbiddenError, RateLimitError, ServerError, NetworkError, and TimeoutError.

Documentation

Full guides and API reference are at docs.artu.ai:

• SDK guide
• API reference

License

MIT