return_premium

Given a valid return premium id, export it through the guarded export path.

Code
This is a thin wrapper around `policies.utils.billing.export_return_premium_by_id`,
which is the single guarded implementation shared with the Return Premiums UI, the
Celery worker and the vendor export jobs. Keep it a wrapper: exporting a return premium
mutates the ORM and writes accounting rows, which belongs in `policies.utils.billing`
and not in the API layer, and a second implementation here is exactly how this entry
point drifted away from the others (BC-24101).

Every guard the shared path applies therefore applies here. The return premium must not
already be exported, voided, canceled, rejected or transferred, and must be authorized
when `billing / use_authorize_return_premium` is enabled; a check number is consumed
only when `policies / refund-check-counter` is configured or check issuance returns one;
`CheckIssuanceIntegrationPoint` is called when a check issuance instance is connected;
and the `'Exported Return Premium'` account history row that BriteData's
`changeInExportedReturnPremium` measure reads is written.

Parameters
----------
returnPremiumId : str
    A return premium id (UUID) to export.

Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    A dictionary containing the following:
    ::

        {
        'checkNumber': int or None,
        'returnPremiumId': UUID,
        'export_status': bool
        }

    `checkNumber` is None when no check number was assigned, which is the case when
    `policies / refund-check-counter` is not configured.

Code
Given a valid from_date and to_date, return a list of return premiums that match the given
parameters, sorted from newest to oldest by return premium date.

Parameters
----------
policy_type_ids : list of str, optional
    A list of policy type ids to filter the return premiums.
    The function will return only the return premiums that have a policy type id in this list.
from_date : str, required
    The start date and time) for the return premium date range.
    The date should be in the format 'YYYY-mm-dd HH:MM:SS'.
to_date : str, required
    The end date time for the return premium date range.
    The date should be in the format 'YYYY-mm-dd HH:MM:SS'.
canceled : bool, optional
    If provided, the function will return only the return premiums
    that have the canceled flag set to this value.
exported : bool, optional
    If provided, the function will return only the return premiums
    that have the exported flag set to this value.
transferred : bool, optional
    If provided, the function will return only the return premiums
    that have the transferred flag set to this value.
rejected : bool, optional
    If provided, the function will return only the return premiums
    that have the rejected flag set to this value.
voided : bool, optional
    If provided, the function will return only the return premiums
    that have the voided flag set to this value.
authorized : bool, optional
    If provided, the function will return only the return premiums
    that have the authorized flag set to this value.
policy_id : str, optional
    A policy id to filter the return premiums.
    The function will return only the return premiums that belong to this policy.
    Kept last in the signature so existing positional callers are unaffected.

Returns
-------
success : bool
    True if the function executed successfully, false if there was an error.
messages : list of str
    List of human-readable error messages. If the function executed successfully, this list will be empty.
data : list of dict
    The matching return premiums, sorted from newest to oldest, so data[0] is always the most
    recent return premium. Return premium dates carry no time of day, so same-day return
    premiums are ordered by when the underlying account history entry was raised.