Accounting export

<?php
// PracticeHub.php
use GuzzleHttp\Client;
use GuzzleHttp\Exception\BadResponseException;

final class ApiError extends RuntimeException {
    public function __construct(public readonly int $status, public readonly string $code, string $message, public readonly array $errors = []) {
        parent::__construct("$status $code: $message");
    }
}

final class PracticeHub {
    private Client $http;

    public function __construct(private readonly string $baseUrl, string $key) {
        $this->http = new Client([
            'base_uri' => rtrim($baseUrl, '/') . '/',
            'headers' => ['Authorization' => "Bearer $key", 'Accept' => 'application/json'],
            'timeout' => 30,
        ]);
    }

    /** GET a path (or an absolute links.next URL); retries 429/5xx with backoff. */
    public function get(string $pathOrUrl): array {
        for ($attempt = 0; ; $attempt++) {
            try {
                return json_decode((string) $this->http->get($pathOrUrl)->getBody(), true, 512, JSON_THROW_ON_ERROR);
            } catch (BadResponseException $e) {
                $res = $e->getResponse();
                if (($res->getStatusCode() === 429 || $res->getStatusCode() >= 500) && $attempt < 4) {
                    sleep((int) ($res->getHeaderLine('Retry-After') ?: 2 ** $attempt));
                    continue;
                }
                $body = json_decode((string) $res->getBody(), true) ?: [];
                throw new ApiError($res->getStatusCode(), $body['code'] ?? 'unknown', $body['message'] ?? $res->getReasonPhrase(), $body['errors'] ?? []);
            }
        }
    }

    /** Walk a list by cursor, yielding rows. $query must NOT contain cursor/page. */
    public function walk(string $resource, array $query): Generator {
        $query['cursor'] = '';
        $query['page_size'] = 100;
        $url = $resource . '?' . http_build_query($query);
        while ($url) {
            $page = $this->get($url);
            yield from $page['data'];
            $url = $page['links']['next'];          // absolute URL or null
        }
    }
}

$ph = new PracticeHub(getenv('PRACTICEHUB_BASE_URL'), getenv('PRACTICEHUB_API_KEY'));

$me = $ph->get('me')['data'];
$currency = $me['account']['currency'];          // "GBP" — the currency of every amount below
$timezone = $me['account']['timezone'];          // "Europe/London" — for invoice_date / payment_date, which are clinic-local dates

// payment methods → your accounting "payment account" mapping (Cash, Card, BACS, …)
$methods = [];
foreach ($ph->walk('payment_methods', []) as $m) {
    $methods[$m['id']] = $m['name'];
}

$since = $store->get('watermark') ?? '2026-01-01 00:00:00';       // UTC, from your last run
$overlap = (new DateTimeImmutable($since, new DateTimeZone('UTC')))->modify('-15 minutes')->format('Y-m-d H:i:s');
$runStartedAt = gmdate('Y-m-d H:i:s');

$window = ['updated' => "gte:$overlap", 'sort' => 'updated:asc'];

foreach ($ph->walk('invoices', $window) as $inv) {
    // $inv: id, number, state (paid|unpaid|void), type, invoice_date, patient_id, practitioner_id, location_id,
    //       subtotal, total, balance, patient_balance, third_party_balance, note, created, updated, metadata

    if ($inv['state'] === 'void') {
        $ledger->voidInvoice("invoice-{$inv['id']}");               // idempotent: no-op if already void
        $ledger->unallocateAllFor("invoice-{$inv['id']}");         // the void released its allocations in PracticeHub too
        continue;
    }

    $lines = [];
    foreach ($ph->walk('line_items', ['invoice_id' => "eq:{$inv['id']}"]) as $li) {
        // $li: id, description, quantity, price, tax_amount, subtotal, total, billable_item_id, provider_id, currency
        $lines[] = [
            'external_id' => "line-{$li['id']}",
            'description' => $li['description'],
            'quantity'    => $li['quantity'],
            'unit_price'  => $li['price'],          // "45.00" — keep as decimal string
            'tax'         => $li['tax_amount'],
            'total'       => $li['total'],
        ];
    }

    $ledger->upsertInvoice([
        'external_id' => "invoice-{$inv['id']}",
        'number'      => $inv['number'],
        'contact_ref' => "patient-{$inv['patient_id']}",       // map to a customer once, see below
        'date'        => $inv['invoice_date'],
        'currency'    => $currency,
        'total'       => $inv['total'],
        'balance'     => $inv['balance'],
        'lines'       => $lines,
        'reference'   => $inv['metadata']['ledger_ref'] ?? null,
    ]);
}

foreach ($ph->walk('payments', $window) as $pay) {
    // $pay: id, amount, payment_type_id, patient_id, location_id, payment_date, status, note, third_party, created, updated
    // status: completed (or empty for older rows), pending, failed, refunded, requires_action — only post settled money
    if (! in_array($pay['status'], ['completed', '', null], true)) {
        $ledger->reverseReceiptIfPosted("payment-{$pay['id']}");
        continue;
    }
    $ledger->upsertReceipt([
        'external_id' => "payment-{$pay['id']}",
        'contact_ref' => "patient-{$pay['patient_id']}",
        'date'        => $pay['payment_date'],
        'amount'      => $pay['amount'],
        'account'     => $methods[$pay['payment_type_id']] ?? 'Other',   // e.g. "Card", "Cash", "BACS"
        'reference'   => $pay['note'],
    ]);
}

foreach ($ph->walk('payment_allocations', $window) as $alloc) {
    // $alloc: id, payment_id, invoice_id, patient_id, amount, created, updated
    $ledger->allocate("payment-{$alloc['payment_id']}", "invoice-{$alloc['invoice_id']}", $alloc['amount'], "allocation-{$alloc['id']}");
}

function customerFor(PracticeHub $ph, Ledger $ledger, int $patientId): void {
    if ($ledger->hasContact("patient-$patientId")) return;
    $p = $ph->get("patients/$patientId")['data'];
    $ledger->upsertContact(['external_id' => "patient-$patientId", 'name' => trim("{$p['first_name']} {$p['last_name']}"), 'email' => $p['email']]);
}

$store->set('watermark', $runStartedAt);