Utilities - Artu Compliance SDK

The SDK exports a set of utility functions for building filters, working with paginated results, and narrowing types at runtime. For Mexico-specific validators (RFC, CURP, CLABE), see the Mexico page.

Filter Utilities

Import filter helpers from the main entry point:

import {
  // String filters
  contains,
  startsWith,
  endsWith,
  equals,
  notEquals,
  // Array filters
  oneOf,
  notOneOf,
  // Date filters
  dateRange,
  after,
  before,
  onOrAfter,
  onOrBefore,
  // Number filters
  numberRange,
  greaterThan,
  lessThan,
  atLeast,
  atMost,
  // Boolean filters
  isTrue,
  isFalse,
  // Null filters
  isNull,
  isNotNull,
} from "@artu-ai/compliance-sdk";

String Filters

`contains(value)`

Match if a field contains the given substring.

contains(value: string): { contains: string }

sdk.clients.list({ filter: { name: contains("García") } });
// Matches: "Juan García", "García López"

`startsWith(value)`

Match if a field starts with the given prefix.

startsWith(value: string): { startsWith: string }

`endsWith(value)`

Match if a field ends with the given suffix.

endsWith(value: string): { endsWith: string }

sdk.clients.list({ filter: { email: endsWith("@company.com") } });

`equals(value)`

Exact match (case-sensitive).

equals<T>(value: T): { eq: T }

sdk.clients.list({ filter: { externalId: equals("crm-001") } });

`notEquals(value)`

Not equal.

notEquals<T>(value: T): { neq: T }

Array Filters

`oneOf(...values)`

Match any of the provided values (OR).

oneOf<T>(...values: T[]): { in: T[] }

sdk.clients.list({ filter: { type: oneOf("individual", "company") } });

`notOneOf(...values)`

Exclude all provided values.

notOneOf<T>(...values: T[]): { nin: T[] }

sdk.clients.list({ filter: { status: notOneOf("deleted", "archived") } });

Date Filters

`dateRange(start?, end?)`

Inclusive date range.

dateRange(start?: Date, end?: Date): { gte?: string; lte?: string }

sdk.transactions.list({
  filter: { createdAt: dateRange(new Date("2024-01-01"), new Date("2024-12-31")) },
});

`after(date)` / `before(date)`

Exclusive date comparisons.

after(date: Date): { gt: string }
before(date: Date): { lt: string }

`onOrAfter(date)` / `onOrBefore(date)`

Inclusive date comparisons.

onOrAfter(date: Date): { gte: string }
onOrBefore(date: Date): { lte: string }

Number Filters

`numberRange(min?, max?)`

Inclusive number range.

numberRange(min?: number, max?: number): { gte?: number; lte?: number }

sdk.transactions.list({ filter: { amount: numberRange(1000, 10000) } });

`greaterThan(value)` / `lessThan(value)`

Exclusive number comparisons.

greaterThan(value: number): { gt: number }
lessThan(value: number): { lt: number }

`atLeast(value)` / `atMost(value)`

Inclusive number comparisons.

atLeast(value: number): { gte: number }
atMost(value: number): { lte: number }

Boolean Filters

`isTrue()` / `isFalse()`

isTrue(): { eq: true }
isFalse(): { eq: false }

sdk.bankAccounts.list({ filter: { isActive: isTrue() } });

Null Filters

`isNull()` / `isNotNull()`

isNull(): { eq: null }
isNotNull(): { neq: null }

sdk.clients.list({ filter: { deletedAt: isNull() } });

Pagination Utilities

Import pagination helpers from the main entry point:

import {
  collectAll,
  collectUpTo,
  getFirst,
  DEFAULT_PAGE_SIZE,
  MAX_PAGE_SIZE,
} from "@artu-ai/compliance-sdk";

Constants

Constant	Value	Description
`DEFAULT_PAGE_SIZE`	`20`	Default page size for list calls
`MAX_PAGE_SIZE`	`200`	Maximum allowed page size

`collectAll(iterator)`

Collects all items from an async iterator into an array. Use with caution on large datasets.

collectAll<T>(iterator: AsyncGenerator<T, void, undefined>): Promise<T[]>

const allClients = await collectAll(sdk.clients.iterate());
console.log(`Total: ${allClients.length}`);

`collectUpTo(iterator, maxItems)`

Collects up to maxItems from an iterator.

collectUpTo<T>(iterator: AsyncGenerator<T, void, undefined>, maxItems: number): Promise<T[]>

const first100 = await collectUpTo(sdk.clients.iterate(), 100);

`getFirst(iterator)`

Returns the first item from an iterator, or undefined if empty.

getFirst<T>(iterator: AsyncGenerator<T, void, undefined>): Promise<T | undefined>

const first = await getFirst(sdk.clients.iterate({ filter: { type: "individual" } }));

Manual Cursor Pagination

let cursor: string | undefined;

do {
  const { data, pagination } = await sdk.clients.list({ cursor, limit: 100 });
  await processBatch(data);
  cursor = pagination.nextCursor;
} while (cursor);

Async Iterator Pattern

// Automatically handles cursor pagination
for await (const client of sdk.clients.iterate({ filter: { type: "individual" } })) {
  await processClient(client);
}

// Early exit
let count = 0;
for await (const client of sdk.clients.iterate()) {
  await processClient(client);
  if (++count >= 500) break;
}

Type Guards

Type guards narrow model types at runtime and give access to scope-specific fields without unsafe casts.

Base Type Guards

import {
  isClient,
  isIndividual,
  isCompany,
  isTrust,
  isTransaction,
  isBankAccount,
  isAlert,
  isAlertItem,
  isAddress,
  isLinkedClient,
  isAPIError,
  isUploadError,
} from "@artu-ai/compliance-sdk";

Guard	Narrows to
`isClient`	`Client` model
`isIndividual`	Individual client
`isCompany`	Company client
`isTrust`	Trust client
`isTransaction`	`Transaction` model
`isBankAccount`	`BankAccount` model
`isAlert`	`Alert` model
`isAlertItem`	`AlertItem` model
`isAddress`	`Address` model
`isLinkedClient`	`LinkedClient` model
`isAPIError`	`APIError` subclass
`isUploadError`	`UploadError` subclass

if (isClient(value)) {
  console.log(value.name);
}

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

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

Scoped Type Guards

Each scope sub-export provides type guards for that scope’s model types, available both as direct named exports and via a TypeGuards namespace object:

import { isClient, isTransaction, TypeGuards } from "@artu-ai/compliance-sdk/mx";

if (isClient(client)) {
  console.log(client.rfc);
  console.log(client.curp);
}

// Or via the namespace
if (TypeGuards.isClient(client)) {
  console.log(client.rfc);
}

import { isClient, isTransaction } from "@artu-ai/compliance-sdk/mx/av/ari";

if (isTransaction(txn)) {
  console.log(txn.operationType);
}

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

if (isClient(client)) {
  console.log(client.username);
}

if (isTransaction(txn)) {
  console.log(txn.operationType);
  console.log(txn.hash);
}

import { isClient, isTransaction } from "@artu-ai/compliance-sdk/mx/av/inm";

if (isTransaction(txn)) {
  console.log(txn.operationType);
  console.log(txn.figuraCliente);
}

import { isClient, isTransaction } from "@artu-ai/compliance-sdk/mx/av/jys";

if (isTransaction(txn)) {
  console.log(txn.operationType);
  console.log(txn.businessLine);
}

import { isClient, isTransaction } from "@artu-ai/compliance-sdk/mx/av/mjr";

if (isTransaction(txn)) {
  console.log(txn.operationType);
  console.log(txn.operationPostalCode);
}

import { isClient, isTransaction } from "@artu-ai/compliance-sdk/mx/av/mpc";

if (isTransaction(txn)) {
  console.log(txn.operationType);
  console.log(txn.postalCode);
}

import { isClient, isTransaction } from "@artu-ai/compliance-sdk/mx/av/tsc";

if (isTransaction(txn)) {
  console.log(txn.cardType);
  console.log(txn.idNumber);
}

import { isClient, isTransaction } from "@artu-ai/compliance-sdk/mx/av/veh";

if (isTransaction(txn)) {
  console.log(txn.operationType);
  console.log(txn.postalCode);
}

import { isClient, isTransaction } from "@artu-ai/compliance-sdk/mx/cnbv/transmisor";

if (isClient(client)) {
  console.log(client.numeroCuenta);
  console.log(client.claveSujetoObligado);
}

if (isTransaction(txn)) {
  console.log(txn.tipoOperacion);
  console.log(txn.instrumentoMonetario);
}

Mexico Document Guards

import {
  isDocument,
  isIneFront,
  isIneBack,
  isPassport,
  isCurp,
  isRfcConstancia,
  isAddressProof,
  isActaConstitutiva,
  isPoderNotarial,
} from "@artu-ai/compliance-sdk/mx";

if (isIneFront(doc)) {
  console.log(doc.fields.cic);
  console.log(doc.fields.claveElector);
}

if (isRfcConstancia(doc)) {
  console.log(doc.fields.rfc);
  console.log(doc.fields.regimenFiscal);
}

Conditional Processing Pattern

import { isClient } from "@artu-ai/compliance-sdk/mx";
import { isClient as isAVIClient } from "@artu-ai/compliance-sdk/mx/av/avi";

async function processClient(client: Client) {
  if (isClient(client)) {
    await validateRfc(client.rfc);

    if (isAVIClient(client)) {
      await validatePlatform(client.dominioPlataforma);
    }
  }
}

Error Type Guards

import { isAPIError, isUploadError } from "@artu-ai/compliance-sdk";

try {
  await sdk.clients.retrieve("id");
} catch (error) {
  if (isAPIError(error)) {
    console.log("API error:", error.statusCode, error.requestId);
  } else if (isUploadError(error)) {
    console.log("Upload failed at stage:", error.stage);
  }
}

​Filter Utilities

​String Filters

​contains(value)

​startsWith(value)

​endsWith(value)

​equals(value)

​notEquals(value)

​Array Filters

​oneOf(...values)

​notOneOf(...values)

​Date Filters

​dateRange(start?, end?)

​after(date) / before(date)

​onOrAfter(date) / onOrBefore(date)

​Number Filters

​numberRange(min?, max?)

​greaterThan(value) / lessThan(value)

​atLeast(value) / atMost(value)

​Boolean Filters

​isTrue() / isFalse()

​Null Filters

​isNull() / isNotNull()

​Pagination Utilities

​Constants

​collectAll(iterator)

​collectUpTo(iterator, maxItems)

​getFirst(iterator)

​Manual Cursor Pagination

​Async Iterator Pattern

​Type Guards

​Base Type Guards

​Scoped Type Guards

​Mexico Document Guards

​Conditional Processing Pattern

​Error Type Guards