Class TransactionAdminQueryService

constructor

• new TransactionAdminQueryService(
      args: { db: B2bDatabase; valkeyClient: ValkeyClient | null },
  ): TransactionAdminQueryService

  Parameters

  • args: { db: B2bDatabase; valkeyClient: ValkeyClient | null }

  Returns TransactionAdminQueryService

Staticinstance

count

• count(args: TransactionAdminSearchArgs): Promise<{ ok: true; value: number }>

  How many rows the same filters match, ignoring page / pageSize.

  Separate from search rather than a column riding along with it: the count is a full scan of the filtered set, and only a surface rendering "x-y of N" needs it. Run it alongside search, not before it.

  The total is cached for 60 s and no write busts it, so it can be up to a minute behind the table it sits under. That is the price of not rescanning the filtered set on every render of the list: the first call for a filter set pays the scan, and identical calls inside the window, from any node, share it. A failed count is not stored, so the next call retries. This does not make the scan itself cheaper.

  Takes the whole search args because the list passes the same object to both calls; the key leaves out everything that does not change the count.

  Parameters

  • args: TransactionAdminSearchArgs

  Returns Promise<{ ok: true; value: number }>

countByMethod

• countByMethod(
      __namedParameters: {
          statuses: (
              | "PENDING"
              | "FAILED"
              | "PROCESSING"
              | "COMPLETED"
              | "RETURNED"
              | "CANCELLED"
          )[];
      },
  ): Promise<
      {
          ok: true;
          value: {
              counts: {
                  count: number;
                  method: | "ACH_CREDIT"
                  | "ACH_DEBIT"
                  | "AF_BANK"
                  | "AF_MOMO"
                  | "BLOCKCHAIN"
                  | "CASH"
                  | "CFX_NETWORK"
                  | "DEPOSIT"
                  | "ESCROW"
                  | "FEDWIRE"
                  | "FEDWIRE_DRAWDOWN"
                  | "FEDNOW"
                  | "RTP"
                  | "INSTANT"
                  | "SPEI"
                  | "DEBIT_CARD"
                  | "REWARD"
                  | "SWAP"
                  | "SWIFT"
                  | "TRANSFER"
                  | "VIRTUAL_CARD"
                  | "WITHDRAWAL";
                  methodDescription: string;
              }[];
          };
      },
  >

  Count distinct transactions grouped by method, scoped to the given statuses (e.g. ["PROCESSING"] for in-flight / stuck transactions). Returns one entry per method that has at least one matching row; methods with zero matches are omitted. Order is unspecified — callers sort.

  Parameters

  • __namedParameters: {
        statuses: (
            | "PENDING"
            | "FAILED"
            | "PROCESSING"
            | "COMPLETED"
            | "RETURNED"
            | "CANCELLED"
        )[];
    }

  Returns Promise<
      {
          ok: true;
          value: {
              counts: {
                  count: number;
                  method: | "ACH_CREDIT"
                  | "ACH_DEBIT"
                  | "AF_BANK"
                  | "AF_MOMO"
                  | "BLOCKCHAIN"
                  | "CASH"
                  | "CFX_NETWORK"
                  | "DEPOSIT"
                  | "ESCROW"
                  | "FEDWIRE"
                  | "FEDWIRE_DRAWDOWN"
                  | "FEDNOW"
                  | "RTP"
                  | "INSTANT"
                  | "SPEI"
                  | "DEBIT_CARD"
                  | "REWARD"
                  | "SWAP"
                  | "SWIFT"
                  | "TRANSFER"
                  | "VIRTUAL_CARD"
                  | "WITHDRAWAL";
                  methodDescription: string;
              }[];
          };
      },
  >

get

• get(
      __namedParameters: {
          customerId?: string;
          id?: string;
          key?: string;
          subType?:
              | "DEPOSIT"
              | "RETURN"
              | "FEE"
              | "ADJUSTMENT"
              | "POINTS"
              | "LEDGER_ACCOUNT"
              | "PLATFORM_SETTLEMENT"
              | null;
          type?: "CREDIT"
          | "DEBIT";
      },
  ): Promise<AdminTransaction | null>

  Fetch a single transaction, optionally pinned to a specific leg. Delegates to search (a pageSize: 1 lookup) instead of running its own query, so the UNION, enrichment JOINs, and row mapper stay defined in exactly one place.

  A transaction id is NOT unique on its own — one id spans CREDIT/DEBIT legs, fee/return sub-rows, and (admin-wide) multiple customer audiences (a card txn's cardholder leg and issuer leg share id+type but belong to different customers; see Transaction.id). The read model's unique key is the (id, type, subType, customerId) tuple — pass whichever parts the caller knows to land on the exact row. With only id, returns whichever leg sorts first (default newest createdAt), which is enough for id-scoped state checks like on-chain settlement (per-transaction, leg-agnostic).

  Parameters

  • __namedParameters: {
        customerId?: string;
        id?: string;
        key?: string;
        subType?:
            | "DEPOSIT"
            | "RETURN"
            | "FEE"
            | "ADJUSTMENT"
            | "POINTS"
            | "LEDGER_ACCOUNT"
            | "PLATFORM_SETTLEMENT"
            | null;
        type?: "CREDIT"
        | "DEBIT";
    }

    • OptionalcustomerId?: string

      Narrow to a single customer audience of the transaction.

    • Optionalid?: string

      Transaction id; optional when pinning by the exact Transaction.key.

    • Optionalkey?: string

      Exact unique-identity Transaction.key (id-type-subType). When set it resolves the single matching row directly via search({ keys: [key] }), superseding the tuple params below.

    • OptionalsubType?:
          | "DEPOSIT"
          | "RETURN"
          | "FEE"
          | "ADJUSTMENT"
          | "POINTS"
          | "LEDGER_ACCOUNT"
          | "PLATFORM_SETTLEMENT"
          | null

      Sub-row selector, mirroring search's subtypes tri-state: a value matches that sub-row (FEE / RETURN), null matches the main (non-subtyped) leg, and undefined doesn't filter on sub-row.

    • Optionaltype?: "CREDIT" | "DEBIT"

      Narrow to the CREDIT or DEBIT leg.

  Returns Promise<AdminTransaction | null>

search

• search(
      args: TransactionAdminSearchArgs,
  ): Promise<{ ok: true; value: AdminTransactionSearchPage }>

  Parameters

  • args: TransactionAdminSearchArgs

  Returns Promise<{ ok: true; value: AdminTransactionSearchPage }>

searchPages

• searchPages(
      args: Omit<TransactionAdminSearchArgs, "page" | "window">,
  ): AsyncGenerator<AdminTransaction[]>

  Every matching transaction, a page at a time, oldest page first.

  For callers that read the whole result set (the XLSX export, the DART reports) rather than one page of it. Walks by keyset, so the cost per page does not grow with how deep the walk has gone the way search's OFFSET paging does. The cache is deliberately not in the path: a full walk would evict every useful entry for a result nobody reads twice.

  Pages rather than rows so a caller can resolve related data for a whole page in one query instead of once per row.

  Parameters

  • args: Omit<TransactionAdminSearchArgs, "page" | "window">

  Returns AsyncGenerator<AdminTransaction[]>