Invoice Lifecycle Hooks

Hook::add('gate:invoice.create', 10, function ($target_type, $target_id, $duedate) {
    // Raising a renewal while a cancellation is open only annoys the customer.
    if ($target_type === 'service' && Acme::cancelPending($target_id))
        return 'A cancellation is open; no renewal invoice was raised.';

    return null;
});

Hook::add('filter:invoice.create_payload', 10, function (&$data) {
    // Add your own reference; the JSON fields arrive encoded already.
    $data['notes'] = trim(($data['notes'] ?? '') . ' ' . Acme::stamp());
});

Hook::add('action:invoice.created.any', 10, function ($invoice_id, $data) {
    if ($invoice_id === 0) return;                 // the write failed

    Accounting::mirror($invoice_id, $data);
});

Hook::add('action:invoice.created', 10, function ($invoice_id) {
    // These are renewals ONLY; for all invoices use the .any hook.
    Dunning::scheduleReminder((int) $invoice_id);
});

Hook::add('action:invoice.created_manually', 10, function ($invoice_id, $data) {
    // A manual invoice is reported apart from the automatic ones.
    Accounting::tagManual((int) $invoice_id);
});

Hook::add('gate:invoice.status_change', 10,
    function ($invoice, $status, $old_status, $options) {
        // Taking a paid invoice back breaks the books.
        if ($old_status === 'paid' && $status === 'unpaid')
            return 'A paid invoice cannot go back to unpaid.';

        return null;
    });

Hook::add('action:invoice.status_changed', 10,
    function ($invoice, $status, $old_status, $options) {
        // Did money REALLY arrive? React to the move into paid alone.
        if ($status === 'paid' && $old_status !== 'paid')
            Accounting::settled((int) ($invoice['id'] ?? 0), $options['pmethod'] ?? '');
    });

Hook::add('gate:invoice.delete', 10, function ($id, $invoice) {
    // A formalised invoice is not deleted; it is cancelled.
    if (!empty($invoice['taxed'])) return 'A formalised invoice cannot be deleted.';

    return null;
});

Hook::add('action:invoice.deleted', 10, function ($id, $invoice) {
    // The record is gone: take what you need from the snapshot.
    Acme::voidInAccounting($id, $invoice['number'] ?? '');
});

Hook::add('action:invoice.items_split', 10,
    function ($source_invoice_id, $new_invoice_id, $item_ids) {
        // Both invoices need to reach accounting separately.
        Acme::resync($source_invoice_id);
        Acme::resync($new_invoice_id);
    });

Hook::add('action:invoice.renewal_generated', 10,
    function ($invoice_id, $target_type, $target) {
        // The same invoice can arrive more than once: make this safe to repeat.
        Acme::noteRenewal($invoice_id, $target_type, (int) ($target['id'] ?? 0));
    });

Hook::add('action:invoice.reminder_sent', 10, function ($invoice) {
    // Nudge over a second channel as well.
    Acme::smsReminder((int) ($invoice['user_id'] ?? 0), $invoice['number'] ?? '');
});

Hook::add('action:invoice.viewed_by_client', 10, function ($invoice, $id, $ctx) {
    // Knowing it was read softens the collection flow.
    Acme::markSeen($id, (int) ($invoice['user_id'] ?? 0));
});

Hook::add('gate:invoice.update_status', 10,
    function ($id, $status, $pmethod, $refund_method) {
        // No manual refunds once the period is closed.
        if ($status === 'refund' && Acme::periodClosed($id))
            return 'This period is closed, so the refund belongs in accounting.';

        return null;
    });

Hook::add('gate:invoice.share_view', 10,
    function ($invoice, $id, $owner, $token, $isOwner) {
        // Hold access without a session to your own address list.
        if (!$isOwner && !Acme::ipAllowed()) return 'access denied';

        return null;
    });

Hook::add('filter:invoice.client_details', 10, function (&$merged_data, $invoice) {
    // Match the company title to the official name in accounting.
    $official = Acme::officialName($merged_data['company_tax_number'] ?? '');
    if ($official !== '') $merged_data['company'] = $official;
});