Class CustomerFeeTransferAdminService

constructor

• new CustomerFeeTransferAdminService(
      args: {
          backofficeWalletQueryService: BackofficeWalletQueryService;
          db: B2bDatabase;
          internalEventPublisher: InternalEventPublisher;
          ledgerAccountAdminQueryService: LedgerAccountAdminQueryService;
          solanaBackofficeLedgerAccountService: SolanaBackofficeLedgerAccountService;
          solanaMintfxTransferService: SolanaMintfxTransferService;
          solanaTransactionService: SolanaTransactionService;
          temporalClient: TemporalWorkflowClient<Workflows>;
          transactionCacheBuster: TransactionCacheBuster;
      },
  ): CustomerFeeTransferAdminService

  Parameters

  • args: {
        backofficeWalletQueryService: BackofficeWalletQueryService;
        db: B2bDatabase;
        internalEventPublisher: InternalEventPublisher;
        ledgerAccountAdminQueryService: LedgerAccountAdminQueryService;
        solanaBackofficeLedgerAccountService: SolanaBackofficeLedgerAccountService;
        solanaMintfxTransferService: SolanaMintfxTransferService;
        solanaTransactionService: SolanaTransactionService;
        temporalClient: TemporalWorkflowClient<Workflows>;
        transactionCacheBuster: TransactionCacheBuster;
    }

    • backofficeWalletQueryService: BackofficeWalletQueryService

    • db: B2bDatabase

    • internalEventPublisher: InternalEventPublisher

    • ledgerAccountAdminQueryService: LedgerAccountAdminQueryService

    • solanaBackofficeLedgerAccountService: SolanaBackofficeLedgerAccountService

      Source of the master fee ledger account id, resolved per create call rather than taken by value. Taking the id by value forced every composition root to await a DB round trip before it could construct this service — at module scope in the Temporal workers, which on Lambda put a database call on the cold-start init path where a failure is an Init Error that Sentry cannot see.

    • solanaMintfxTransferService: SolanaMintfxTransferService

    • solanaTransactionService: SolanaTransactionService

    • temporalClient: TemporalWorkflowClient<Workflows>

    • transactionCacheBuster: TransactionCacheBuster

  Returns CustomerFeeTransferAdminService

Staticinstance

create

• create(
      __namedParameters: Pick<
          CustomerFeeTransfer,
          "description"
          | "sourceAccountId"
          | "type",
      > & {
          customerId: string;
          entityId: string;
          guard?: RecurringChargeGuard;
          idempotencyKey?: string;
          notMonthlyFee?: true;
          recurringFee?: { periodKey: string };
          sourceAmount: BigNumber;
      },
  ): Promise<
      | { ok: true; value: CreatedFeeTransfer }
      | {
          error:
              | IdempotencyKeyReused
              | ServiceError<"INVALID_TRANSFER">
              | ServiceError<"INVALID_LEDGER_ACCOUNT", { ledgerAccountId: string }>
              | ServiceError<"RECURRING_FEE_CONFIGURED", { customerId: string }>
              | RecurringChargeRefused;
          ok: false;
      },
  >

  Parameters

  • __namedParameters: Pick<CustomerFeeTransfer, "description" | "sourceAccountId" | "type"> & {
        customerId: string;
        entityId: string;
        guard?: RecurringChargeGuard;
        idempotencyKey?: string;
        notMonthlyFee?: true;
        recurringFee?: { periodKey: string };
        sourceAmount: BigNumber;
    }

    • customerId: string

    • entityId: string

    • Optionalguard?: RecurringChargeGuard

      Not run on a replay of an existing key: nothing new is written.

    • OptionalidempotencyKey?: string

      Dedupe token: a repeated key returns the existing live transfer, starting a PROCESSING one's workflow if no run holds its id. Absent, every call inserts a row.

      Unlike ledger-account transfers this key does NOT touch the on-chain Mintfx idempotency key — the fee transfer PDA is seeded by the external id (see feeTransferTransaction and ledgerAccountFeeTransferWorkflowActivities).

    • OptionalnotMonthlyFee?: true

      The operator's confirmation that a manual PLATFORM fee is not the monthly fee, required when the customer has a recurring fee configured.

    • OptionalrecurringFee?: { periodKey: string }

      Set by the monthly platform-fee sweep (ENG-3083) to mark this charge as one of its own and record the period it settles.

      Stored on data rather than left implicit in idempotencyKey: the key encodes the period as a suffix, which answers "was this customer billed for August" but cannot answer "every recurring fee taken in August" without a scan no index can serve.

    • sourceAmount: BigNumber

  Returns Promise<
      | { ok: true; value: CreatedFeeTransfer }
      | {
          error:
              | IdempotencyKeyReused
              | ServiceError<"INVALID_TRANSFER">
              | ServiceError<"INVALID_LEDGER_ACCOUNT", { ledgerAccountId: string }>
              | ServiceError<"RECURRING_FEE_CONFIGURED", { customerId: string }>
              | RecurringChargeRefused;
          ok: false;
      },
  >

feeTransferTransaction

• feeTransferTransaction(
      __namedParameters: { id: string },
  ): Promise<
      {
          ok: true;
          value: {
              amount: string;
              lastValidBlockHeight: number;
              message: SolanaBlockhashTransactionMessage;
              sourceAccountId: string;
          };
      },
  >

  Parameters

  • __namedParameters: { id: string }

  Returns Promise<
      {
          ok: true;
          value: {
              amount: string;
              lastValidBlockHeight: number;
              message: SolanaBlockhashTransactionMessage;
              sourceAccountId: string;
          };
      },
  >

  Solana transaction to execute a transfer from a ledger account to another, with the account it debits and the amount, which signing needs

replayRecurringCharge

• replayRecurringCharge(
      request: Pick<
          ReplayRequest,
          "customerId"
          | "idempotencyKey"
          | "sourceAmount",
      > & { recurringFee: { periodKey: string } },
  ): Promise<
      | { ok: true; value: CreatedFeeTransfer }
      | { error: IdempotencyKeyReused; ok: false }
      | null,
  >

  create's replay of a recurring charge and nothing else: null when no live transfer holds the key, so it never inserts a row or runs a guard.

  Parameters

  • request: Pick<ReplayRequest, "customerId" | "idempotencyKey" | "sourceAmount"> & {
        recurringFee: { periodKey: string };
    }

  Returns Promise<
      | { ok: true; value: CreatedFeeTransfer }
      | { error: IdempotencyKeyReused; ok: false }
      | null,
  >

update

• update(
      __namedParameters: {
          data: Partial<
              Pick<CustomerFeeTransfer, "receipt"> & { status: FeeTransferStatus },
          >;
          id: string;
      },
  ): Promise<{ ok: true; value: void }>

  Update the transfer details in DB and publish an event if required

  Parameters

  • __namedParameters: {
        data: Partial<
            Pick<CustomerFeeTransfer, "receipt"> & { status: FeeTransferStatus },
        >;
        id: string;
    }

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