@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/utils/filters.ts

@@ -0,0 +1,412 @@
+/**
+ * Filter utilities
+ *
+ * Helpers for building type-safe filter objects for list operations.
+ * These functions create filter objects that match the API's filter schemas.
+ */
+
+import type {
+  ClientFilter,
+  TransactionFilter,
+  DocumentFilter,
+  BankAccountFilter,
+} from "@artu-ai/shared";
+
+// ===========================
+// Filter Builders
+// ===========================
+
+/**
+ * Helper to build a type-safe client filter object.
+ * Provides autocomplete for valid filter properties.
+ *
+ * @param filter - Client filter object
+ * @returns The same filter object (type-safe passthrough)
+ *
+ * @example
+ * ```typescript
+ * const filter = buildClientFilter({
+ *   name: { contains: "García" },
+ *   type: { in: ["individual", "company"] },
+ * });
+ * ```
+ */
+export function buildClientFilter(filter: ClientFilter): ClientFilter {
+  return filter;
+}
+
+/**
+ * Helper to build a type-safe transaction filter object.
+ *
+ * @param filter - Transaction filter object
+ * @returns The same filter object (type-safe passthrough)
+ */
+export function buildTransactionFilter(
+  filter: TransactionFilter
+): TransactionFilter {
+  return filter;
+}
+
+/**
+ * Helper to build a type-safe document filter object.
+ *
+ * @param filter - Document filter object
+ * @returns The same filter object (type-safe passthrough)
+ */
+export function buildDocumentFilter(filter: DocumentFilter): DocumentFilter {
+  return filter;
+}
+
+/**
+ * Helper to build a type-safe bank account filter object.
+ *
+ * @param filter - Bank account filter object
+ * @returns The same filter object (type-safe passthrough)
+ */
+export function buildBankAccountFilter(
+  filter: BankAccountFilter
+): BankAccountFilter {
+  return filter;
+}
+
+// ===========================
+// String Filter Helpers
+// ===========================
+
+/**
+ * Creates a "contains" filter for a string field.
+ * Matches if the field contains the substring (case-insensitive).
+ *
+ * @param value - Substring to search for
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { name: contains("García") }
+ * // Matches: "Juan García", "García López", etc.
+ * ```
+ */
+export function contains(value: string) {
+  return { contains: value };
+}
+
+/**
+ * Creates a "starts with" filter for a string field.
+ * Matches if the field starts with the prefix (case-insensitive).
+ *
+ * @param value - Prefix to match
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { name: startsWith("Juan") }
+ * // Matches: "Juan García", "Juan López", etc.
+ * ```
+ */
+export function startsWith(value: string) {
+  return { startsWith: value };
+}
+
+/**
+ * Creates an "ends with" filter for a string field.
+ * Matches if the field ends with the suffix (case-insensitive).
+ *
+ * @param value - Suffix to match
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { email: endsWith("@company.com") }
+ * ```
+ */
+export function endsWith(value: string) {
+  return { endsWith: value };
+}
+
+/**
+ * Creates an "equals" filter for exact string matching.
+ * Matches if the field equals the value exactly (case-sensitive).
+ *
+ * @param value - Exact value to match
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { rfc: equals("XAXX010101000") }
+ * ```
+ */
+export function equals<T extends string | number | boolean>(value: T) {
+  return { eq: value };
+}
+
+/**
+ * Creates a "not equals" filter.
+ * Matches if the field does not equal the value.
+ *
+ * @param value - Value to exclude
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { status: notEquals("deleted") }
+ * ```
+ */
+export function notEquals<T extends string | number | boolean>(value: T) {
+  return { neq: value };
+}
+
+// ===========================
+// Array Filter Helpers
+// ===========================
+
+/**
+ * Creates an "in" filter for matching one of multiple values.
+ * Matches if the field equals any of the provided values.
+ *
+ * @param values - Values to match against
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { type: oneOf("individual", "company") }
+ * // Matches if type is "individual" OR "company"
+ * ```
+ */
+export function oneOf<T extends string | number>(...values: T[]) {
+  return { in: values };
+}
+
+/**
+ * Creates a "not in" filter for excluding values.
+ * Matches if the field does NOT equal any of the provided values.
+ *
+ * @param values - Values to exclude
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { status: notOneOf("deleted", "archived") }
+ * // Matches if status is NOT "deleted" AND NOT "archived"
+ * ```
+ */
+export function notOneOf<T extends string | number>(...values: T[]) {
+  return { nin: values };
+}
+
+// ===========================
+// Date Filter Helpers
+// ===========================
+
+/**
+ * Creates a date range filter (inclusive on both ends).
+ *
+ * @param start - Start of range (optional)
+ * @param end - End of range (optional)
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { createdAt: dateRange(new Date("2024-01-01"), new Date("2024-12-31")) }
+ * // Matches dates from Jan 1 to Dec 31, 2024 (inclusive)
+ * ```
+ */
+export function dateRange(start?: Date, end?: Date) {
+  const filter: { gte?: string; lte?: string } = {};
+  if (start) filter.gte = start.toISOString();
+  if (end) filter.lte = end.toISOString();
+  return filter;
+}
+
+/**
+ * Creates an "after" date filter (exclusive).
+ * Matches if the field is strictly after the date.
+ *
+ * @param date - Date to compare against
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { createdAt: after(new Date("2024-01-01")) }
+ * // Matches dates after Jan 1, 2024 (not including Jan 1)
+ * ```
+ */
+export function after(date: Date) {
+  return { gt: date.toISOString() };
+}
+
+/**
+ * Creates a "before" date filter (exclusive).
+ * Matches if the field is strictly before the date.
+ *
+ * @param date - Date to compare against
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { createdAt: before(new Date("2024-12-31")) }
+ * // Matches dates before Dec 31, 2024 (not including Dec 31)
+ * ```
+ */
+export function before(date: Date) {
+  return { lt: date.toISOString() };
+}
+
+/**
+ * Creates an "on or after" date filter (inclusive).
+ *
+ * @param date - Date to compare against
+ * @returns Filter object
+ */
+export function onOrAfter(date: Date) {
+  return { gte: date.toISOString() };
+}
+
+/**
+ * Creates an "on or before" date filter (inclusive).
+ *
+ * @param date - Date to compare against
+ * @returns Filter object
+ */
+export function onOrBefore(date: Date) {
+  return { lte: date.toISOString() };
+}
+
+// ===========================
+// Number Filter Helpers
+// ===========================
+
+/**
+ * Creates a number range filter (inclusive on both ends).
+ *
+ * @param min - Minimum value (optional)
+ * @param max - Maximum value (optional)
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { amount: numberRange(1000, 10000) }
+ * // Matches amounts from 1000 to 10000 (inclusive)
+ * ```
+ */
+export function numberRange(min?: number, max?: number) {
+  const filter: { gte?: number; lte?: number } = {};
+  if (min !== undefined) filter.gte = min;
+  if (max !== undefined) filter.lte = max;
+  return filter;
+}
+
+/**
+ * Creates a "greater than" number filter (exclusive).
+ *
+ * @param value - Value to compare against
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { amount: greaterThan(1000) }
+ * // Matches amounts > 1000
+ * ```
+ */
+export function greaterThan(value: number) {
+  return { gt: value };
+}
+
+/**
+ * Creates a "less than" number filter (exclusive).
+ *
+ * @param value - Value to compare against
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { amount: lessThan(10000) }
+ * // Matches amounts < 10000
+ * ```
+ */
+export function lessThan(value: number) {
+  return { lt: value };
+}
+
+/**
+ * Creates a "greater than or equal" number filter (inclusive).
+ *
+ * @param value - Value to compare against
+ * @returns Filter object
+ */
+export function atLeast(value: number) {
+  return { gte: value };
+}
+
+/**
+ * Creates a "less than or equal" number filter (inclusive).
+ *
+ * @param value - Value to compare against
+ * @returns Filter object
+ */
+export function atMost(value: number) {
+  return { lte: value };
+}
+
+// ===========================
+// Boolean Filter Helpers
+// ===========================
+
+/**
+ * Creates a filter for true boolean values.
+ *
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { isActive: isTrue() }
+ * ```
+ */
+export function isTrue() {
+  return { eq: true };
+}
+
+/**
+ * Creates a filter for false boolean values.
+ *
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { isDeleted: isFalse() }
+ * ```
+ */
+export function isFalse() {
+  return { eq: false };
+}
+
+// ===========================
+// Null Filter Helpers
+// ===========================
+
+/**
+ * Creates a filter for null/undefined values.
+ *
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { deletedAt: isNull() }
+ * ```
+ */
+export function isNull() {
+  return { eq: null };
+}
+
+/**
+ * Creates a filter for non-null values.
+ *
+ * @returns Filter object
+ *
+ * @example
+ * ```typescript
+ * { rfc: isNotNull() }
+ * ```
+ */
+export function isNotNull() {
+  return { neq: null };
+}

package/src/utils/index.ts

@@ -0,0 +1,134 @@
+/**
+ * SDK utilities
+ *
+ * This module exports utility functions for working with the SDK.
+ */
+
+// ===========================
+// tRPC Client - Phase 1.3
+// ===========================
+
+export {
+  createAPIClient,
+  generateRequestId,
+  isTRPCError,
+  getRequestIdFromError,
+  LATEST_API_VERSION,
+  DEFAULT_TIMEOUT,
+} from "./trpc-client";
+
+export type {
+  TRPCClient,
+  TRPCClientConfig,
+  APIVersion,
+  SDKEnvironment,
+} from "./trpc-client";
+
+// ===========================
+// Environment - Phase 1.4
+// ===========================
+
+export {
+  validateEnvironment,
+  isValidEnvironment,
+  getDefaultBaseUrl,
+  resolveBaseUrl,
+  environmentSchema,
+  DEFAULT_BASE_URL,
+} from "./environment";
+
+export type { Environment, SDKEnvironmentConfig } from "./environment";
+
+// ===========================
+// Session helper
+// ===========================
+
+export {
+  fetchSession,
+  createAuthLoginUrl,
+  type SessionInfo,
+  type SessionType,
+  type SessionOptions,
+  type SessionOptionsWithReturnTo,
+  type SessionOptionsWithoutReturnTo,
+  type SDKSessionOptions,
+  type SDKSessionOptionsWithReturnTo,
+  type SDKSessionOptionsWithoutReturnTo,
+  type SessionResult,
+  type SessionResultWithRedirect,
+  type SessionResultWithoutRedirect,
+  type SessionResultAuthenticated,
+  type SessionResultUnauthenticatedWithRedirect,
+  type SessionResultUnauthenticatedNoRedirect,
+} from "./session";
+
+// ===========================
+// Pagination - Phase 1.4
+// ===========================
+
+export {
+  createPaginatedIterator,
+  collectAll,
+  collectUpTo,
+  getFirst,
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+} from "./pagination";
+
+// ===========================
+// Filters - Phase 1.4
+// ===========================
+
+export {
+  // Filter builders
+  buildClientFilter,
+  buildTransactionFilter,
+  buildDocumentFilter,
+  buildBankAccountFilter,
+  // 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 "./filters";
+
+// ===========================
+// Upload Utilities
+// ===========================
+
+export {
+  uploadToS3,
+  normalizeFile,
+  validateFileSize,
+  MAX_FILE_SIZE_BYTES,
+  DEFAULT_UPLOAD_TIMEOUT_MS,
+} from "./upload";
+
+export type {
+  UploadableFile,
+  ProgressCallback,
+  UploadToS3Options,
+  UploadToS3Result,
+} from "./upload";

package/src/utils/pagination.ts

@@ -0,0 +1,143 @@
+/**
+ * Pagination utilities
+ *
+ * Helpers for working with paginated API responses.
+ * Includes async iterators for automatic pagination.
+ */
+
+import type { PaginationInput, PaginatedResponse } from "@artu-ai/shared";
+
+// ===========================
+// Constants
+// ===========================
+
+/**
+ * Default page size for paginated requests
+ */
+export const DEFAULT_PAGE_SIZE = 20;
+
+/**
+ * Maximum page size allowed by the API
+ */
+export const MAX_PAGE_SIZE = 200;
+
+// ===========================
+// Functions
+// ===========================
+
+/**
+ * Creates an async iterator for paginated results.
+ * Automatically fetches subsequent pages as you iterate.
+ *
+ * @param fetchPage - Function that fetches a page of results
+ * @param options - Iterator options
+ * @returns Async generator yielding individual items
+ *
+ * @example
+ * ```typescript
+ * const iterator = createPaginatedIterator(
+ *   (pagination) => client.clients.list.query(pagination)
+ * );
+ *
+ * for await (const client of iterator) {
+ *   console.log(client.name);
+ * }
+ * ```
+ */
+export async function* createPaginatedIterator<T>(
+  fetchPage: (pagination: PaginationInput) => Promise<PaginatedResponse<T>>,
+  options?: { limit?: number }
+): AsyncGenerator<T, void, undefined> {
+  let cursor: string | undefined;
+  let hasMore = true;
+  const pageSize = options?.limit ?? DEFAULT_PAGE_SIZE;
+
+  while (hasMore) {
+    const response = await fetchPage({
+      cursor,
+      limit: Math.min(pageSize, MAX_PAGE_SIZE),
+    });
+
+    for (const item of response.data) {
+      yield item;
+    }
+
+    hasMore = response.pagination.hasMore;
+    cursor = response.pagination.nextCursor ?? undefined;
+  }
+}
+
+/**
+ * Collects all items from a paginated iterator into an array.
+ * Use with caution on large datasets.
+ *
+ * @param iterator - Async iterator to collect from
+ * @returns Array of all items
+ *
+ * @example
+ * ```typescript
+ * const allClients = await collectAll(
+ *   createPaginatedIterator((p) => client.clients.list.query(p))
+ * );
+ * ```
+ */
+export async function collectAll<T>(
+  iterator: AsyncGenerator<T, void, undefined>
+): Promise<T[]> {
+  const items: T[] = [];
+  for await (const item of iterator) {
+    items.push(item);
+  }
+  return items;
+}
+
+/**
+ * Collects items from a paginated iterator up to a maximum count.
+ * Useful when you only need a subset of results.
+ *
+ * @param iterator - Async iterator to collect from
+ * @param maxItems - Maximum number of items to collect
+ * @returns Array of collected items
+ *
+ * @example
+ * ```typescript
+ * // Get first 100 clients
+ * const clients = await collectUpTo(
+ *   createPaginatedIterator((p) => client.clients.list.query(p)),
+ *   100
+ * );
+ * ```
+ */
+export async function collectUpTo<T>(
+  iterator: AsyncGenerator<T, void, undefined>,
+  maxItems: number
+): Promise<T[]> {
+  const items: T[] = [];
+  for await (const item of iterator) {
+    items.push(item);
+    if (items.length >= maxItems) {
+      break;
+    }
+  }
+  return items;
+}
+
+/**
+ * Gets the first item from a paginated iterator, or undefined if empty.
+ *
+ * @param iterator - Async iterator to get first item from
+ * @returns First item or undefined
+ *
+ * @example
+ * ```typescript
+ * const firstClient = await getFirst(
+ *   createPaginatedIterator((p) => client.clients.list.query({ ...p, limit: 1 }))
+ * );
+ * ```
+ */
+export async function getFirst<T>(
+  iterator: AsyncGenerator<T, void, undefined>
+): Promise<T | undefined> {
+  const result = await iterator.next();
+  return result.done ? undefined : result.value;
+}