Class RecurringFeeInvoiceAdminService

Issues each month's invoice and publishes the events that email it and its receipt. The terms promise the invoice before payment, so the sweep waits for the invoice email before charge, which also refuses an undelivered one.

Hierarchy (View Summary)

RecurringFeeInvoiceAdminQueryService
- RecurringFeeInvoiceAdminService

Index

Constructors

constructor

new RecurringFeeInvoiceAdminService(
    args: {
        db: B2bDatabase;
        internalEventPublisher: Pick<InternalEventPublisher, "publishConfirmed">;
        now?: () => Instant;
        receiptPageSize?: number;
        recurringFeeAdminService: Pick<
            RecurringFeeAdminService,
            "get"
            | "chargeAgain",
        >;
    },
): RecurringFeeInvoiceAdminService
Parameters
- args: {
      db: B2bDatabase;
      internalEventPublisher: Pick<InternalEventPublisher, "publishConfirmed">;
      now?: () => Instant;
      receiptPageSize?: number;
      recurringFeeAdminService: Pick<
          RecurringFeeAdminService,
          "get"
          | "chargeAgain",
      >;
  }
  - db: B2bDatabase
  - internalEventPublisher: Pick<InternalEventPublisher, "publishConfirmed">
  - Optionalnow?: () => Instant
    
    The issue clock. Tests pin it to land invoices on a chosen Chicago day.
  - OptionalreceiptPageSize?: number
    
    Rows per page of republishUnsentReceipts; tests shrink it.
  - recurringFeeAdminService: Pick<RecurringFeeAdminService, "get" | "chargeAgain">
Returns RecurringFeeInvoiceAdminService
Overrides RecurringFeeInvoiceAdminQueryService.constructor
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:575

Properties

`Protected` `Readonly`db

db: B2bDatabase

`Static`instance

instance: (...args: []) => RecurringFeeInvoiceAdminService = ...

The process default: built from each dependency's own instance().

Methods

chargeAgain

chargeAgain(
    month: { billingDate?: string; customerId: string; periodKey: string },
): Promise<
    | { ok: true; value: RecurringFeeChargeOutcome }
    | {
        error:
            | ServiceError<
                "INVALID_PERIOD_KEY"
                | "FUTURE_PERIOD_KEY",
                { periodKey: string },
            >
            | ServiceError<
                "RECURRING_FEE_MONTH_NOT_ESCALATED",
                { customerId: string; periodKey: string },
            >;
        ok: false;
    },
>
The dashboard's Charge again. An escalated month whose invoice was never emailed, as the sweep leaves a reissue at the retry limit, has it emailed instead (INVOICE_SENT); the next Charge again charges once delivered.
Parameters
- month: { billingDate?: string; customerId: string; periodKey: string }
  - OptionalbillingDate?: string
    
    YYYY-MM-DD in the billing timezone; today when omitted.
  - customerId: string
  - periodKey: string
Returns Promise<
    | { ok: true; value: RecurringFeeChargeOutcome }
    | {
        error:
            | ServiceError<
                "INVALID_PERIOD_KEY"
                | "FUTURE_PERIOD_KEY",
                { periodKey: string },
            >
            | ServiceError<
                "RECURRING_FEE_MONTH_NOT_ESCALATED",
                { customerId: string; periodKey: string },
            >;
        ok: false;
    },
>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:1588

escalate

escalate(
__namedParameters: { customerId: string; periodKey: string },
): Promise<RecurringFeeEscalationOutcome>
Ask ops to chase a month at RECURRING_FEE_RETRY_LIMIT and stamp its live invoice so the sweep leaves it. Posts once per customer-month under a fixed envelope id, confirmed before the stamp so a crash reposts, never drops.
Parameters
- __namedParameters: { customerId: string; periodKey: string }
Returns Promise<RecurringFeeEscalationOutcome>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:1502

`Protected`forPeriod

forPeriod(
__namedParameters: { customerId: string; periodKey: string },
): Promise<RecurringFeeInvoice | null>
Parameters
- __namedParameters: { customerId: string; periodKey: string }
Returns Promise<RecurringFeeInvoice | null>
Inherited from RecurringFeeInvoiceAdminQueryService.forPeriod
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:531

get

get(__namedParameters: { id: string }): Promise<RecurringFeeInvoice | null>
Parameters
- __namedParameters: { id: string }
Returns Promise<RecurringFeeInvoice | null>
Inherited from RecurringFeeInvoiceAdminQueryService.get
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:522

invoiceDelivery

invoiceDelivery(
__namedParameters: { invoiceId: string; since: Instant },
): Promise<{ ok: true; value: RecurringFeeInvoiceDelivery }>
Whether SES accepted the invoice email. A skip counts only when recorded at or after since, so the skip that blocked last night's attempt does not fail tonight's before the lambda has handled the republish.
Parameters
- __namedParameters: { invoiceId: string; since: Instant }
Returns Promise<{ ok: true; value: RecurringFeeInvoiceDelivery }>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:949

issue

issue(
    __namedParameters: {
        billingDate?: string;
        customerId: string;
        periodKey: string;
    },
): Promise<
    | { ok: true; value: RecurringFeeInvoiceIssueOutcome }
    | {
        error:
            | ServiceError<
                "RECURRING_FEE_SOURCE_ACCOUNT_UNAVAILABLE",
                { sourceAccountId: string },
            >
            | ServiceError<"FUTURE_PERIOD_KEY", { periodKey: string }>;
        ok: false;
    },
>
The month's invoice, issued if none, numbered CFX-YYYYMMDD-NN under an advisory lock on the date. Unmailed and uncharged, it takes the current terms; billingDate is charge's, so both refuse a later month alike.
Parameters
- __namedParameters: { billingDate?: string; customerId: string; periodKey: string }
  - OptionalbillingDate?: string
    
    YYYY-MM-DD in the billing timezone; the issue clock's date when omitted.
  - customerId: string
  - periodKey: string
Returns Promise<
    | { ok: true; value: RecurringFeeInvoiceIssueOutcome }
    | {
        error:
            | ServiceError<
                "RECURRING_FEE_SOURCE_ACCOUNT_UNAVAILABLE",
                { sourceAccountId: string },
            >
            | ServiceError<"FUTURE_PERIOD_KEY", { periodKey: string }>;
        ok: false;
    },
>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:599

listOpen

listOpen(
__namedParameters: { before: string },
): Promise<RecurringFeeOpenMonth[]>
Unbilled months for the sweep: before before with no COMPLETED charge, the previous month uninvoiced, and before once CANCELLED. Waived drop, escalated stay with ops unless CANCELLED, each with its reason if known.
Parameters
- __namedParameters: { before: string }
Returns Promise<RecurringFeeOpenMonth[]>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:1047

publishIssued

publishIssued(
    __namedParameters: { invoiceId: string },
): Promise<
    | { ok: true; value: RecurringFeeInvoicePublishOutcome }
    | { error: ServiceError; ok: false },
>
Publish the invoice email event unless already mailed or voided. publishedAt is the database clock email_delivery rows use, so a waiter can ignore a skip recorded for an earlier publish.
Parameters
- __namedParameters: { invoiceId: string }
Returns Promise<
| { ok: true; value: RecurringFeeInvoicePublishOutcome }
| { error: ServiceError; ok: false },
>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:877

publishPaid

publishPaid(
    __namedParameters: { feeTransferId: string },
): Promise<
    | { ok: true; value: RecurringFeeReceiptOutcome }
    | { error: ServiceError; ok: false },
>
Publish the receipt event for a settled recurring charge with a live invoice. Finds the invoice by customer and period, not fee_transfer_id: the transfer can settle before charge links it, so it links it here.
Parameters
- __namedParameters: { feeTransferId: string }
Returns Promise<
| { ok: true; value: RecurringFeeReceiptOutcome }
| { error: ServiceError; ok: false },
>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:973

publishUnbilled

publishUnbilled(
    __namedParameters: {
        billingDate?: string;
        failed: RecurringFeeBillingMonth[];
        pastDue: RecurringFeeBillingMonth[];
        periodKey: string;
    },
): Promise<{ published: boolean }>
Tell operators which customers the sweep left unbilled: an earlier month only while still open after the run and once (a failed child's is under failed), with its reason, such as paused, when the fee no longer bills.
Parameters
- __namedParameters: {
      billingDate?: string;
      failed: RecurringFeeBillingMonth[];
      pastDue: RecurringFeeBillingMonth[];
      periodKey: string;
  }
  - OptionalbillingDate?: string
    
    The sweep's listing date; the clock's date for a sweep that predates it.
  - failed: RecurringFeeBillingMonth[]
    
    Charges whose child workflow failed tonight.
  - pastDue: RecurringFeeBillingMonth[]
    
    Earlier months still open when the sweep started.
  - periodKey: string
Returns Promise<{ published: boolean }>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:1240

republishUnsentReceipts

republishUnsentReceipts(): Promise<{ republished: number }>
Republish receipts settled one hour to seven days ago and never sent, paging through all so unsendable ones cannot crowd out the rest. The fixed event id dedupes; republished counts SNS accepts, and a refusal throws.

Returns Promise<{ republished: number }>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:1164

search

search(
    __namedParameters: {
        customerIds?: string[];
        escalated?: boolean;
        ids?: string[];
        page?: number;
        pageSize?: number;
        paid?: boolean;
        periodKeys?: string[];
        voided?: boolean;
        waived?: boolean;
    },
): Promise<
    {
        ok: true;
        value: { hasNext: boolean; items: RecurringFeeInvoice[]; total: number };
    },
>
Parameters
- __namedParameters: {
      customerIds?: string[];
      escalated?: boolean;
      ids?: string[];
      page?: number;
      pageSize?: number;
      paid?: boolean;
      periodKeys?: string[];
      voided?: boolean;
      waived?: boolean;
  }
  - OptionalcustomerIds?: string[]
  - Optionalescalated?: boolean
    
    Omit for both; true keeps only invoices escalated to ops.
  - Optionalids?: string[]
  - Optionalpage?: number
  - OptionalpageSize?: number
  - Optionalpaid?: boolean
    
    Omit for both; false keeps only months with no COMPLETED charge.
  - OptionalperiodKeys?: string[]
  - Optionalvoided?: boolean
    
    Omit for both; false keeps only the live invoice of each month.
  - Optionalwaived?: boolean
    
    Omit for both; false drops waived invoices.
Returns Promise<
    {
        ok: true;
        value: { hasNext: boolean; items: RecurringFeeInvoice[]; total: number };
    },
>
Inherited from RecurringFeeInvoiceAdminQueryService.search
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:297

waivePausedOrInactiveMonths

waivePausedOrInactiveMonths(
__namedParameters: { billingDate: string; periodKey: string },
): Promise<{ marked: number; waived: number }>
Close a month that ended unbilled with the fee PAUSED or the customer not ACTIVE. A sweep past the billing day records it with a voided invoice, which a resume reissues past; next month's sweep waives it if still inactive. Idempotent per customer-month; not emailed.
Parameters
- __namedParameters: { billingDate: string; periodKey: string }
Returns Promise<{ marked: number; waived: number }>
- Defined in fee-services/src/RecurringFeeInvoiceAdminService.ts:1314

Class RecurringFeeInvoiceAdminService

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

db: B2bDatabase

internalEventPublisher: Pick<InternalEventPublisher, "publishConfirmed">

Optionalnow?: () => Instant

OptionalreceiptPageSize?: number

recurringFeeAdminService: Pick<RecurringFeeAdminService, "get" | "chargeAgain">

Returns RecurringFeeInvoiceAdminService

Properties

Protected Readonlydb

Staticinstance

Methods

chargeAgain

Parameters

OptionalbillingDate?: string

customerId: string

periodKey: string

Returns Promise< | { ok: true; value: RecurringFeeChargeOutcome } | { error: | ServiceError< "INVALID_PERIOD_KEY" | "FUTURE_PERIOD_KEY", { periodKey: string }, > | ServiceError< "RECURRING_FEE_MONTH_NOT_ESCALATED", { customerId: string; periodKey: string }, >; ok: false; },>

escalate

Parameters

Returns Promise<RecurringFeeEscalationOutcome>

ProtectedforPeriod

Parameters

Returns Promise<RecurringFeeInvoice | null>

get

Parameters

Returns Promise<RecurringFeeInvoice | null>

invoiceDelivery

Parameters

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

issue

Parameters

OptionalbillingDate?: string

customerId: string

periodKey: string

Returns Promise< | { ok: true; value: RecurringFeeInvoiceIssueOutcome } | { error: | ServiceError< "RECURRING_FEE_SOURCE_ACCOUNT_UNAVAILABLE", { sourceAccountId: string }, > | ServiceError<"FUTURE_PERIOD_KEY", { periodKey: string }>; ok: false; },>

listOpen

Parameters

Returns Promise<RecurringFeeOpenMonth[]>

publishIssued

Parameters

Returns Promise< | { ok: true; value: RecurringFeeInvoicePublishOutcome } | { error: ServiceError; ok: false },>

publishPaid

Parameters

Returns Promise< | { ok: true; value: RecurringFeeReceiptOutcome } | { error: ServiceError; ok: false },>

publishUnbilled

Parameters

OptionalbillingDate?: string

failed: RecurringFeeBillingMonth[]

pastDue: RecurringFeeBillingMonth[]

periodKey: string

Returns Promise<{ published: boolean }>

republishUnsentReceipts

Returns Promise<{ republished: number }>

search

Parameters

OptionalcustomerIds?: string[]

Optionalescalated?: boolean

Optionalids?: string[]

Optionalpage?: number

OptionalpageSize?: number

Optionalpaid?: boolean

OptionalperiodKeys?: string[]

Optionalvoided?: boolean

Optionalwaived?: boolean

Returns Promise< { ok: true; value: { hasNext: boolean; items: RecurringFeeInvoice[]; total: number }; },>

waivePausedOrInactiveMonths

Parameters

Returns Promise<{ marked: number; waived: number }>

Settings

On This Page

`Optional`now?: () => Instant

`Optional`receiptPageSize?: number

`Protected` `Readonly`db

`Static`instance

`Optional`billingDate?: string

Returns Promise<
| { ok: true; value: RecurringFeeChargeOutcome }
| {
error:
| ServiceError<
"INVALID_PERIOD_KEY"
| "FUTURE_PERIOD_KEY",
{ periodKey: string },
>
| ServiceError<
"RECURRING_FEE_MONTH_NOT_ESCALATED",
{ customerId: string; periodKey: string },
>;
ok: false;
},
>

`Protected`forPeriod

`Optional`billingDate?: string

Returns Promise<
| { ok: true; value: RecurringFeeInvoiceIssueOutcome }
| {
error:
| ServiceError<
"RECURRING_FEE_SOURCE_ACCOUNT_UNAVAILABLE",
{ sourceAccountId: string },
>
| ServiceError<"FUTURE_PERIOD_KEY", { periodKey: string }>;
ok: false;
},
>

Returns Promise<
| { ok: true; value: RecurringFeeInvoicePublishOutcome }
| { error: ServiceError; ok: false },
>

Returns Promise<
| { ok: true; value: RecurringFeeReceiptOutcome }
| { error: ServiceError; ok: false },
>

`Optional`billingDate?: string

`Optional`customerIds?: string[]

`Optional`escalated?: boolean

`Optional`ids?: string[]

`Optional`page?: number

`Optional`pageSize?: number

`Optional`paid?: boolean

`Optional`periodKeys?: string[]

`Optional`voided?: boolean

`Optional`waived?: boolean

Returns Promise<
{
ok: true;
value: { hasNext: boolean; items: RecurringFeeInvoice[]; total: number };
},
>