Skip to main content
The SDK provides type-safe filter helpers for querying records.

​
Basic Filtering

Pass filter objects to list() methods: 
const { data } = await sdk.clients.list({
  filter: { type: "individual" },
});
Multiple filter properties are combined with AND logic: 
const { data } = await sdk.clients.list({
  filter: {
    type: "individual",
  },
});

​
Metadata filters

Use metadataFilters when you need exact key/value matches on metadata. Entries are AND-ed together. 
const { data } = await sdk.transactions.list({
  filter: {
    metadataFilters: [
      { key: "source", value: "api" },
      { key: "region", value: "mx" },
    ],
  },
});
Supported on: clients, addresses, bank accounts, contact methods, documents, alerts, and transactions.

​
Filter Helpers

Import helpers for building filters: 
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

Match if field contains substring (case-insensitive): 
await sdk.clients.list({
  filter: { name: contains("García") },
});
// Matches: "Juan García", "García López", "María García Hernández"

​
Starts With

Match if field starts with prefix: 
await sdk.clients.list({
  filter: { name: startsWith("Juan") },
});
// Matches: "Juan García", "Juan López", "Juana Martínez"

​
Ends With

Match if field ends with suffix: 
await sdk.clients.list({
  filter: { email: endsWith("@company.com") },
});

​
Equals / Not Equals

Exact match or exclusion: 
await sdk.clients.list({
  filter: { rfc: equals("XAXX010101000") },
});

await sdk.clients.list({
  filter: { status: notEquals("deleted") },
});

​
Array Filters

​
One Of

Match any of the values (OR): 
await sdk.clients.list({
  filter: { type: oneOf("individual", "company") },
});
// Matches if type is "individual" OR "company"

​
Not One Of

Exclude values: 
await sdk.clients.list({
  filter: { status: notOneOf("deleted", "archived") },
});
// Matches if status is NOT "deleted" AND NOT "archived"

​
Date Filters

​
Date Range

Inclusive range: 
await sdk.transactions.list({
  filter: {
    createdAt: dateRange(new Date("2024-01-01"), new Date("2024-12-31")),
  },
});
// Matches dates from Jan 1 to Dec 31, 2024 (inclusive)

​
After / Before

Exclusive comparisons: 
await sdk.transactions.list({
  filter: { createdAt: after(new Date("2024-01-01")) },
});
// Matches dates after Jan 1, 2024 (not including Jan 1)

await sdk.transactions.list({
  filter: { createdAt: before(new Date("2024-12-31")) },
});
// Matches dates before Dec 31, 2024 (not including Dec 31)

​
On Or After / On Or Before

Inclusive comparisons: 
await sdk.transactions.list({
  filter: { createdAt: onOrAfter(new Date("2024-01-01")) },
});
// Matches dates >= Jan 1, 2024

await sdk.transactions.list({
  filter: { createdAt: onOrBefore(new Date("2024-12-31")) },
});
// Matches dates <= Dec 31, 2024

​
Number Filters

​
Number Range

Inclusive range: 
await sdk.transactions.list({
  filter: { amount: numberRange(1000, 10000) },
});
// Matches amounts from 1000 to 10000 (inclusive)

​
Comparisons

// Greater than (exclusive)
await sdk.transactions.list({
  filter: { amount: greaterThan(1000) },
});
// Matches amounts > 1000

// Less than (exclusive)
await sdk.transactions.list({
  filter: { amount: lessThan(10000) },
});
// Matches amounts < 10000

// At least (inclusive)
await sdk.transactions.list({
  filter: { amount: atLeast(5000) },
});
// Matches amounts >= 5000

// At most (inclusive)
await sdk.transactions.list({
  filter: { amount: atMost(50000) },
});
// Matches amounts <= 50000

​
Boolean Filters

await sdk.clients.list({
  filter: { isActive: isTrue() },
});

await sdk.clients.list({
  filter: { isDeleted: isFalse() },
});

​
Null Filters

// Find records where field is null
await sdk.clients.list({
  filter: { deletedAt: isNull() },
});

// Find records where field is not null
await sdk.clients.list({
  filter: { rfc: isNotNull() },
});

​
Combining Filters

Combine multiple filters (AND logic): 
await sdk.clients.list({
  filter: {
    type: "individual",
    name: contains("García"),
    createdAt: after(new Date("2024-01-01")),
  },
});

​
Filter with Pagination

const { data, pagination } = await sdk.clients.list({
  filter: {
    type: oneOf("individual", "company"),
    createdAt: dateRange(startDate, endDate),
  },
  limit: 50,
});

// Iterate with filter
for await (const client of sdk.clients.iterate({
  type: "individual",
})) {
  console.log(client.name);
}