@artu-ai/compliance-sdk 0.0.5 → 0.2.0

package/src/resources/bank-accounts.ts

@@ -0,0 +1,413 @@
+/**
+ * Bank Accounts Resource
+ *
+ * Manages bank account information for clients.
+ *
+ * This is the base (unscoped) resource. For jurisdiction-scoped SDKs, use:
+ * - MexBankAccountsResource - Mexico-scoped with flattened CLABE fields
+ */
+
+import { z } from "zod";
+import type {
+  CreateBankAccountInput,
+  UpdateBankAccountInput,
+  BankAccountFilter,
+  PaginatedResponse,
+  ListOptions,
+  AtomicBatchResult,
+  PartialBatchResult,
+  SyncItem,
+  SyncResult,
+} from "@artu-ai/shared";
+import {
+  createBankAccountInputSchema,
+  updateBankAccountInputSchema,
+  replaceSyncItemSchema,
+} from "@artu-ai/shared";
+import type { BatchOptions } from "./clients";
+import { BaseResource } from "./base";
+import { BankAccount, type BankAccountData } from "../models/BankAccount";
+
+// ===========================
+// BankAccountsResource
+// ===========================
+
+/**
+ * Base resource for managing client bank accounts.
+ *
+ * @example
+ * ```typescript
+ * // Create a bank account with full nested format
+ * const account = await sdk.bankAccounts.create("client_123", {
+ *   accountNumber: "1234567890",
+ *   bankName: "BBVA México",
+ *   type: BankAccountType.Checking,
+ *   currency: Currency.MXN,
+ *   jurisdictions: {
+ *     MX: {
+ *       clabe: "012345678901234567",
+ *     },
+ *   },
+ * });
+ *
+ * // List accounts for a client
+ * const accounts = await sdk.bankAccounts.list("client_123");
+ * ```
+ */
+export class BankAccountsResource extends BaseResource<
+  BankAccount,
+  CreateBankAccountInput,
+  UpdateBankAccountInput,
+  BankAccountFilter
+> {
+  // ─────────────────────────────────────────────────────────────────
+  // CRUD Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates a new bank account for a client.
+   *
+   * @param data - Bank account creation data (includes clientId)
+   * @returns The created bank account model
+   */
+  async create(data: CreateBankAccountInput): Promise<BankAccount> {
+    const validated = this.validate(createBankAccountInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.create.mutate(validated)
+    );
+
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a bank account by ID.
+   */
+  async retrieve(id: string): Promise<BankAccount> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.retrieve.query({ id })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a bank account by metadata key/value.
+   */
+  async retrieveByMetadata(key: string, value: string): Promise<BankAccount> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.retrieveByMetadata.query({ key, value })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Retrieves a bank account by externalId.
+   */
+  async retrieveByExternalId(externalId: string): Promise<BankAccount> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.retrieveByExternalId.query({ externalId })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Updates a bank account.
+   */
+  async update(id: string, data: UpdateBankAccountInput): Promise<BankAccount> {
+    const validated = this.validate(updateBankAccountInputSchema, data);
+
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.update.mutate({ id, data: validated })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Deletes a bank account.
+   */
+  async delete(id: string): Promise<void> {
+    await this.execute(() => this.trpc.bankAccounts.delete.mutate({ id }));
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // List & Pagination
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Lists bank accounts with optional filtering.
+   */
+  async list(
+    options?: ListOptions<BankAccountFilter>
+  ): Promise<PaginatedResponse<BankAccount>> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.list.query(options)
+    );
+
+    return {
+      data: response.data.map((a) => this.instantiate(a)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Lists all bank accounts for a specific client.
+   */
+  async listByClient(
+    clientId: string,
+    options?: { cursor?: string; limit?: number }
+  ): Promise<PaginatedResponse<BankAccount>> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.listByClient.query({ clientId, ...options })
+    );
+
+    return {
+      data: response.data.map((a) => this.instantiate(a)),
+      pagination: response.pagination,
+    };
+  }
+
+  /**
+   * Returns an async iterator over all bank accounts matching the filter.
+   */
+  iterate(
+    filter?: BankAccountFilter
+  ): AsyncGenerator<BankAccount, void, undefined> {
+    return this.createIterator({ filter });
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Convenience Methods
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Gets the primary bank account for a client.
+   *
+   * @param clientId - The client ID
+   * @returns The primary bank account, or null if none is marked as primary
+   */
+  async getPrimary(clientId: string): Promise<BankAccount | null> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.getPrimary.query({ clientId })
+    );
+
+    return response ? this.instantiate(response) : null;
+  }
+
+  /**
+   * Sets a bank account as the primary account for a client.
+   */
+  async setPrimary(id: string): Promise<BankAccount> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.update.mutate({ id, data: { isPrimary: true } })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Activates a bank account.
+   */
+  async activate(id: string): Promise<BankAccount> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.update.mutate({ id, data: { isActive: true } })
+    );
+    return this.instantiate(response);
+  }
+
+  /**
+   * Deactivates a bank account.
+   */
+  async deactivate(id: string): Promise<BankAccount> {
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.update.mutate({ id, data: { isActive: false } })
+    );
+    return this.instantiate(response);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Batch Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Creates multiple bank accounts in a single request.
+   *
+   * @param accounts - Array of bank account creation data (each includes clientId)
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async createMany(
+    accounts: CreateBankAccountInput[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<BankAccount>>;
+  async createMany(
+    accounts: CreateBankAccountInput[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<BankAccount>>;
+  async createMany(
+    accounts: CreateBankAccountInput[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<BankAccount> | PartialBatchResult<BankAccount>> {
+    const atomic = options.atomic ?? true;
+    const validated = this.validate(
+      z.array(createBankAccountInputSchema),
+      accounts
+    );
+
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.createMany.mutate({ items: validated, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((a) => this.instantiate(a)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  /**
+   * Updates multiple bank accounts in a single request.
+   *
+   * @param updates - Array of { id, data } updates
+   * @param options - Batch options (atomic: true by default)
+   * @returns Atomic result with data array, or partial result with succeeded/failed
+   */
+  async updateMany(
+    updates: { id: string; data: UpdateBankAccountInput }[],
+    options?: { atomic?: true }
+  ): Promise<AtomicBatchResult<BankAccount>>;
+  async updateMany(
+    updates: { id: string; data: UpdateBankAccountInput }[],
+    options: { atomic: false }
+  ): Promise<PartialBatchResult<BankAccount>>;
+  async updateMany(
+    updates: { id: string; data: UpdateBankAccountInput }[],
+    options: BatchOptions = {}
+  ): Promise<AtomicBatchResult<BankAccount> | PartialBatchResult<BankAccount>> {
+    const atomic = options.atomic ?? true;
+    const updateItemSchema = z.object({
+      id: z.uuid(),
+      data: updateBankAccountInputSchema,
+    });
+
+    const validated = this.validate(z.array(updateItemSchema), updates);
+
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.updateMany.mutate({ items: validated, atomic })
+    );
+
+    if (response.atomic) {
+      return {
+        atomic: true,
+        data: response.data.map((a) => this.instantiate(a)),
+      };
+    } else {
+      return {
+        atomic: false,
+        succeeded: response.succeeded.map((item) => ({
+          index: item.index,
+          data: this.instantiate(item.data),
+        })),
+        failed: response.failed,
+      };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Sync Operations
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Syncs bank accounts for a client - handles create, update, and delete in bulk.
+   *
+   * This is the most efficient way to reconcile a set of bank accounts for a client.
+   *
+   * @param clientId - The client ID
+   * @param items - Array of sync items:
+   *   - Without `id`: create new bank account
+   *   - With `id` and `_delete: true`: delete existing bank account
+   *   - With `id` (no `_delete`): update existing bank account
+   * @param options - Sync options
+   * @param options.replaceMode - When true, items not in the array are deleted (default: false)
+   * @returns Sync result with created, updated, and deleted arrays
+   *
+   * @example
+   * ```typescript
+   * // Patch mode (default) - only mentioned items are affected
+   * const result = await sdk.bankAccounts.sync("client_123", [
+   *   // Create new account (no id)
+   *   { accountNumber: "1234567890", bankName: "BBVA", country: "MX" },
+   *   // Update existing account (has id)
+   *   { id: "ba_456", bankName: "BBVA México" },
+   *   // Delete account (has id and _delete: true)
+   *   { id: "ba_789", _delete: true },
+   * ]);
+   *
+   * // Replace mode - provided array becomes the complete set (requires full create input for new items)
+   * const result = await sdk.bankAccounts.sync("client_123", accounts, { replaceMode: true });
+   *
+   * console.log(result.created);  // newly created accounts
+   * console.log(result.updated);  // updated accounts
+   * console.log(result.deleted);  // array of deleted IDs
+   * ```
+   */
+  async sync(
+    clientId: string,
+    items: SyncItem<CreateBankAccountInput>[],
+    options: { replaceMode: true }
+  ): Promise<SyncResult<BankAccount>>;
+  async sync(
+    clientId: string,
+    items: SyncItem<UpdateBankAccountInput>[],
+    options?: { replaceMode?: boolean }
+  ): Promise<SyncResult<BankAccount>>;
+  async sync(
+    clientId: string,
+    items: SyncItem<UpdateBankAccountInput | CreateBankAccountInput>[],
+    options?: { replaceMode?: boolean }
+  ): Promise<SyncResult<BankAccount>> {
+    const validated = this.validate(
+      z.array(
+        replaceSyncItemSchema(
+          createBankAccountInputSchema,
+          updateBankAccountInputSchema
+        )
+      ),
+      items
+    );
+
+    const response = await this.execute(() =>
+      this.trpc.bankAccounts.sync.mutate({
+        clientId,
+        items: validated,
+        replaceMode: options?.replaceMode,
+      })
+    );
+
+    return {
+      created: response.created.map((a) => this.instantiate(a)),
+      updated: response.updated.map((a) => this.instantiate(a)),
+      deleted: response.deleted,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Instantiation (protected for subclasses to override)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Instantiates a BankAccount model from API response data.
+   * Subclasses override this to return their specific model type.
+   */
+  protected instantiate(data: BankAccountData): BankAccount {
+    return new BankAccount(data);
+  }
+}