Class PositivePayFileAdminService

constructor

• new PositivePayFileAdminService(
      args: { db: B2bDatabase; eventPublisher: CustomerEventPublisher },
  ): PositivePayFileAdminService

  Parameters

  • args: { db: B2bDatabase; eventPublisher: CustomerEventPublisher }

  Returns PositivePayFileAdminService

Staticinstance

beginSendAttempt

• beginSendAttempt(
      __namedParameters: { id: string; sendAttemptId: string },
  ): Promise<
      {
          ok: true;
          value: {
              file: PositivePayFile;
              outcome: "PROCEED"
              | "ALREADY_SENT"
              | "IN_DOUBT";
          };
      },
  >

  Claims the one send that can mail Jack Henry a second decision file. ALREADY_SENT is a replay of the attempt SES accepted; IN_DOUBT is an attempt that reached SES and never came back, which only a human can resolve; anything else is a new deliberate send, including the operator's resend, and stamps itself as the attempt in flight.

  Both arms compare against sentAttemptId, not sentAt: a resend's sentAt is already set by the original send, so reading it would report a lost resend as a completed one.

  Parameters

  • __namedParameters: { id: string; sendAttemptId: string }

  Returns Promise<
      {
          ok: true;
          value: {
              file: PositivePayFile;
              outcome: "PROCEED"
              | "ALREADY_SENT"
              | "IN_DOUBT";
          };
      },
  >

claim

• claim(
      __namedParameters: {
          bankId: "dart";
          businessDate: string;
          idempotencyKey: string;
          trigger: "MANUAL" | "SCHEDULE";
          triggeredByAdminUserId?: string;
      },
  ): Promise<
      {
          ok: true;
          value: {
              decisions: (
                  Omit<
                      {
                          addenda: string
                          | null;
                          amount: string;
                          bankAccountExternalId: string;
                          bankAccountId: number;
                          bankId: string;
                          companyDiscretionaryData: string | null;
                          companyId: string | null;
                          companyName: string | null;
                          createdAt: Date;
                          customerExternalId: string | null;
                          customerId: number | null;
                          decidedAt: Date | null;
                          decidedBy: string | null;
                          decidedByAdminUserId: string | null;
                          decisionSource: "ADMIN" | "DEFAULT" | "UNFUNDED" | null;
                          effectiveEntryDate: string | null;
                          entryDescription: string | null;
                          externalAccountNumber: string | null;
                          externalId: string;
                          fileExternalId: string | null;
                          fileId: number | null;
                          id: number;
                          identityExternalId: string | null;
                          identityId: number | null;
                          individualId: string | null;
                          ledgerAccountExternalId: string | null;
                          ledgerAccountId: number | null;
                          mismatchAt: Date | null;
                          organizationExternalId: string | null;
                          organizationId: number | null;
                          originatingAba: string | null;
                          originatorName: string | null;
                          postedOn: string;
                          presentedOn: string;
                          receiverName: string | null;
                          requestedAt: Date | null;
                          requestedDecision: "APPROVE" | "DENY" | null;
                          secCode: string | null;
                          settledAt: Date | null;
                          status: "PENDING" | "APPROVED" | "DENIED";
                          submittedAt: Date | null;
                          traceNumber: string | null;
                          transactionCode: string | null;
                          updatedAt: Date;
                          victorTraceId: string | null;
                          victorTransactionId: string;
                          virtualAccountExternalId: string | null;
                          virtualAccountId: number | null;
                          withdrawalExternalId: string | null;
                          withdrawalId: number | null;
                      },
                      | "id"
                      | "externalId"
                      | "organizationId"
                      | "customerId"
                      | "customerExternalId"
                      | "identityId"
                      | "identityExternalId"
                      | "organizationExternalId"
                      | "ledgerAccountId"
                      | "ledgerAccountExternalId"
                      | "bankAccountId"
                      | "bankAccountExternalId"
                      | "amount"
                      | "withdrawalId"
                      | "withdrawalExternalId"
                      | "virtualAccountId"
                      | "virtualAccountExternalId"
                      | "fileId"
                      | "fileExternalId",
                  > & {
                      amount: BigNumber;
                      decisionDeadline: Date;
                      entityId: string
                      | null;
                      fileId: string | null;
                      id: string;
                      identityId: string | null;
                      ledgerAccountId: string | null;
                      organizationId: string | null;
                      statusDescription: string;
                      victorAccountId: string;
                      victorAccountName: string;
                      virtualAccountId: string | null;
                      withdrawalId: string | null;
                  } & { customerId: string
                  | null }
              )[];
              file: PositivePayFile;
              unclaimable: (
                  Omit<
                      {
                          addenda: string
                          | null;
                          amount: string;
                          bankAccountExternalId: string;
                          bankAccountId: number;
                          bankId: string;
                          companyDiscretionaryData: string | null;
                          companyId: string | null;
                          companyName: string | null;
                          createdAt: Date;
                          customerExternalId: string | null;
                          customerId: number | null;
                          decidedAt: Date | null;
                          decidedBy: string | null;
                          decidedByAdminUserId: string | null;
                          decisionSource: "ADMIN" | "DEFAULT" | "UNFUNDED" | null;
                          effectiveEntryDate: string | null;
                          entryDescription: string | null;
                          externalAccountNumber: string | null;
                          externalId: string;
                          fileExternalId: string | null;
                          fileId: number | null;
                          id: number;
                          identityExternalId: string | null;
                          identityId: number | null;
                          individualId: string | null;
                          ledgerAccountExternalId: string | null;
                          ledgerAccountId: number | null;
                          mismatchAt: Date | null;
                          organizationExternalId: string | null;
                          organizationId: number | null;
                          originatingAba: string | null;
                          originatorName: string | null;
                          postedOn: string;
                          presentedOn: string;
                          receiverName: string | null;
                          requestedAt: Date | null;
                          requestedDecision: "APPROVE" | "DENY" | null;
                          secCode: string | null;
                          settledAt: Date | null;
                          status: "PENDING" | "APPROVED" | "DENIED";
                          submittedAt: Date | null;
                          traceNumber: string | null;
                          transactionCode: string | null;
                          updatedAt: Date;
                          victorTraceId: string | null;
                          victorTransactionId: string;
                          virtualAccountExternalId: string | null;
                          virtualAccountId: number | null;
                          withdrawalExternalId: string | null;
                          withdrawalId: number | null;
                      },
                      | "id"
                      | "externalId"
                      | "organizationId"
                      | "customerId"
                      | "customerExternalId"
                      | "identityId"
                      | "identityExternalId"
                      | "organizationExternalId"
                      | "ledgerAccountId"
                      | "ledgerAccountExternalId"
                      | "bankAccountId"
                      | "bankAccountExternalId"
                      | "amount"
                      | "withdrawalId"
                      | "withdrawalExternalId"
                      | "virtualAccountId"
                      | "virtualAccountExternalId"
                      | "fileId"
                      | "fileExternalId",
                  > & {
                      amount: BigNumber;
                      decisionDeadline: Date;
                      entityId: string
                      | null;
                      fileId: string | null;
                      id: string;
                      identityId: string | null;
                      ledgerAccountId: string | null;
                      organizationId: string | null;
                      statusDescription: string;
                      victorAccountId: string;
                      victorAccountName: string;
                      virtualAccountId: string | null;
                      withdrawalId: string | null;
                  } & { customerId: string
                  | null }
              )[];
          };
      },
  >

  Opens a file for businessDate and claims every unfiled row presented on or before it in one UPDATE: the CASE default-denies whatever is still PENDING, denies an APPROVED row its ledger account has not funded, and files both in the same statement that sets fileId, so a concurrent undo() can't land between a deny and a claim — Postgres re-evaluates the CASE against the latest committed row on the concurrent-update recheck.

  Idempotent on idempotencyKey: a retry re-finds its own file and recounts from the rows carrying that file id, never from the UPDATE's row count — which is zero on a retry because the rows are already claimed.

  Parameters

  • __namedParameters: {
        bankId: "dart";
        businessDate: string;
        idempotencyKey: string;
        trigger: "MANUAL" | "SCHEDULE";
        triggeredByAdminUserId?: string;
    }

  Returns Promise<
      {
          ok: true;
          value: {
              decisions: (
                  Omit<
                      {
                          addenda: string
                          | null;
                          amount: string;
                          bankAccountExternalId: string;
                          bankAccountId: number;
                          bankId: string;
                          companyDiscretionaryData: string | null;
                          companyId: string | null;
                          companyName: string | null;
                          createdAt: Date;
                          customerExternalId: string | null;
                          customerId: number | null;
                          decidedAt: Date | null;
                          decidedBy: string | null;
                          decidedByAdminUserId: string | null;
                          decisionSource: "ADMIN" | "DEFAULT" | "UNFUNDED" | null;
                          effectiveEntryDate: string | null;
                          entryDescription: string | null;
                          externalAccountNumber: string | null;
                          externalId: string;
                          fileExternalId: string | null;
                          fileId: number | null;
                          id: number;
                          identityExternalId: string | null;
                          identityId: number | null;
                          individualId: string | null;
                          ledgerAccountExternalId: string | null;
                          ledgerAccountId: number | null;
                          mismatchAt: Date | null;
                          organizationExternalId: string | null;
                          organizationId: number | null;
                          originatingAba: string | null;
                          originatorName: string | null;
                          postedOn: string;
                          presentedOn: string;
                          receiverName: string | null;
                          requestedAt: Date | null;
                          requestedDecision: "APPROVE" | "DENY" | null;
                          secCode: string | null;
                          settledAt: Date | null;
                          status: "PENDING" | "APPROVED" | "DENIED";
                          submittedAt: Date | null;
                          traceNumber: string | null;
                          transactionCode: string | null;
                          updatedAt: Date;
                          victorTraceId: string | null;
                          victorTransactionId: string;
                          virtualAccountExternalId: string | null;
                          virtualAccountId: number | null;
                          withdrawalExternalId: string | null;
                          withdrawalId: number | null;
                      },
                      | "id"
                      | "externalId"
                      | "organizationId"
                      | "customerId"
                      | "customerExternalId"
                      | "identityId"
                      | "identityExternalId"
                      | "organizationExternalId"
                      | "ledgerAccountId"
                      | "ledgerAccountExternalId"
                      | "bankAccountId"
                      | "bankAccountExternalId"
                      | "amount"
                      | "withdrawalId"
                      | "withdrawalExternalId"
                      | "virtualAccountId"
                      | "virtualAccountExternalId"
                      | "fileId"
                      | "fileExternalId",
                  > & {
                      amount: BigNumber;
                      decisionDeadline: Date;
                      entityId: string
                      | null;
                      fileId: string | null;
                      id: string;
                      identityId: string | null;
                      ledgerAccountId: string | null;
                      organizationId: string | null;
                      statusDescription: string;
                      victorAccountId: string;
                      victorAccountName: string;
                      virtualAccountId: string | null;
                      withdrawalId: string | null;
                  } & { customerId: string
                  | null }
              )[];
              file: PositivePayFile;
              unclaimable: (
                  Omit<
                      {
                          addenda: string
                          | null;
                          amount: string;
                          bankAccountExternalId: string;
                          bankAccountId: number;
                          bankId: string;
                          companyDiscretionaryData: string | null;
                          companyId: string | null;
                          companyName: string | null;
                          createdAt: Date;
                          customerExternalId: string | null;
                          customerId: number | null;
                          decidedAt: Date | null;
                          decidedBy: string | null;
                          decidedByAdminUserId: string | null;
                          decisionSource: "ADMIN" | "DEFAULT" | "UNFUNDED" | null;
                          effectiveEntryDate: string | null;
                          entryDescription: string | null;
                          externalAccountNumber: string | null;
                          externalId: string;
                          fileExternalId: string | null;
                          fileId: number | null;
                          id: number;
                          identityExternalId: string | null;
                          identityId: number | null;
                          individualId: string | null;
                          ledgerAccountExternalId: string | null;
                          ledgerAccountId: number | null;
                          mismatchAt: Date | null;
                          organizationExternalId: string | null;
                          organizationId: number | null;
                          originatingAba: string | null;
                          originatorName: string | null;
                          postedOn: string;
                          presentedOn: string;
                          receiverName: string | null;
                          requestedAt: Date | null;
                          requestedDecision: "APPROVE" | "DENY" | null;
                          secCode: string | null;
                          settledAt: Date | null;
                          status: "PENDING" | "APPROVED" | "DENIED";
                          submittedAt: Date | null;
                          traceNumber: string | null;
                          transactionCode: string | null;
                          updatedAt: Date;
                          victorTraceId: string | null;
                          victorTransactionId: string;
                          virtualAccountExternalId: string | null;
                          virtualAccountId: number | null;
                          withdrawalExternalId: string | null;
                          withdrawalId: number | null;
                      },
                      | "id"
                      | "externalId"
                      | "organizationId"
                      | "customerId"
                      | "customerExternalId"
                      | "identityId"
                      | "identityExternalId"
                      | "organizationExternalId"
                      | "ledgerAccountId"
                      | "ledgerAccountExternalId"
                      | "bankAccountId"
                      | "bankAccountExternalId"
                      | "amount"
                      | "withdrawalId"
                      | "withdrawalExternalId"
                      | "virtualAccountId"
                      | "virtualAccountExternalId"
                      | "fileId"
                      | "fileExternalId",
                  > & {
                      amount: BigNumber;
                      decisionDeadline: Date;
                      entityId: string
                      | null;
                      fileId: string | null;
                      id: string;
                      identityId: string | null;
                      ledgerAccountId: string | null;
                      organizationId: string | null;
                      statusDescription: string;
                      victorAccountId: string;
                      victorAccountName: string;
                      virtualAccountId: string | null;
                      withdrawalId: string | null;
                  } & { customerId: string
                  | null }
              )[];
          };
      },
  >

clearSendAttempt

• clearSendAttempt(
      __namedParameters: { id: string; sendAttemptId: string },
  ): Promise<{ ok: true; value: void }>

  Unstamps an attempt SES definitively rejected, so the bounded retry behaves normally instead of meeting its own stamp and reporting IN_DOUBT. Only ever called where a response came back saying the mail was not taken.

  Parameters

  • __namedParameters: { id: string; sendAttemptId: string }

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

markFailed

• markFailed(
      __namedParameters: { error: string; id: string; releaseClaim?: boolean },
  ): Promise<{ ok: true; value: void }>

  A file that never reached the bank releases its rows: leaving them claimed freezes undo, decide and confirmRequested on a file nobody can fix. The default-deny stamps stay — they were correct at file time, and with the lock gone ops can override them before the next send picks the rows up.

  releaseClaim: false is the one exception: a send whose result was lost may already be at the bank, so its rows must not go back in tomorrow's file.

  Parameters

  • __namedParameters: { error: string; id: string; releaseClaim?: boolean }

    • error: string

    • id: string

    • OptionalreleaseClaim?: boolean

      False only when the send's result was lost and the bank may hold the file.

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

markSent

• markSent(
      __namedParameters: {
          fileName: string;
          id: string;
          recipients: string[];
          s3Key: string;
          sendAttemptId: string;
      },
  ): Promise<{ ok: true; value: PositivePayFile }>

  First send stamps the decisions and publishes; a resend only records the time. Either way sent_attempt_id records which attempt SES accepted, which is what beginSendAttempt reads to tell a completed send from a lost one.

  Parameters

  • __namedParameters: {
        fileName: string;
        id: string;
        recipients: string[];
        s3Key: string;
        sendAttemptId: string;
    }

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