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

```bash
npm install @artu-ai/compliance-sdk
```

```bash
pnpm add @artu-ai/compliance-sdk
```

```bash
yarn add @artu-ai/compliance-sdk
```

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

## Quick start

```typescript
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

```typescript
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:

```typescript
// 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:

```typescript
// 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:

```typescript
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:

```typescript
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

```typescript
// 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

```typescript
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):

```typescript
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](https://docs.artu.ai)**:

- [SDK guide](https://docs.artu.ai/sdk)
- [API reference](https://docs.artu.ai/api-reference)

## License

[MIT](./LICENSE)