<?php

namespace Modules\NX600Lab\Contracts;

/**
 * Pluggable lab-provider contract.
 *
 * Implementations route a lab order request out to a specific analyzer or
 * reference lab (NX600 in-house, IDEXX VetConnect, Antech, etc.) and pull
 * back results into the same UI/data model. The vet UI is provider-agnostic
 * once an order is placed.
 */
interface LabAdapterInterface
{
    /** Stable identifier used in the per-business config row. */
    public function key(): string;

    /** Display name (e.g. "NX600 in-house", "IDEXX VetConnect PLUS"). */
    public function displayName(): string;

    /**
     * Submit a lab order. Returns an external reference id that the adapter
     * can later use to pull results back. May throw on transport failure.
     *
     * @param array $order  Includes pet_id, business_id, requested_tests[],
     *                      doctor_id, priority, and any provider-specific
     *                      extras passed through from the UI.
     */
    public function pushOrder(array $order): string;

    /**
     * Pull results for an order. Returns a list of analyte rows shaped for
     * direct insertion into the lab results store. Empty array = no results
     * yet (poll again later).
     *
     * @return array<int, array{analyte: string, value: string, unit?: string, flag?: string}>
     */
    public function pullResults(string $orderRef): array;

    /**
     * Catalogue of analytes this provider can run, for the UI test picker.
     *
     * @return array<int, array{code: string, name: string, category?: string}>
     */
    public function listAnalytes(): array;

    /**
     * Liveness check — does the provider answer? Used by the settings UI to
     * show a green/red dot.
     */
    public function ping(): bool;
}
