FaxDocumentService
├── storeFaxDocument()          # Store fax with automatic patient matching
├── assignFaxToPatient()        # Assign unassigned fax to patient
├── findPatientByPhone()        # Auto-match patient by phone number
├── getUnassignedFaxes()        # List unassigned received faxes
├── getFaxDocument()            # Retrieve fax details
└── deleteFaxDocument()         # Mark fax as deleted

Incoming Fax
    ↓
[Download/Retrieve Media]
    ↓
[Attempt Patient Matching by Phone]
    ↓
[Store Document via FaxDocumentService]
    ↓
[Insert/Update oe_faxsms_queue]
    ├── job_id (provider SID)
    ├── status (received, delivered, failed, etc.)
    ├── direction (inbound)
    ├── patient_id (if matched)
    ├── document_id (OpenEMR document)
    ├── media_path (stored file location)
    └── details_json (complete metadata)

private function storeInboundFax(array $faxData): void
{
    // 1. Download media using oeHttp with Bearer token
    $mediaContent = $this->downloadFaxMediaContent($mediaUrl);

    // 2. Initialize FaxDocumentService
    $faxService = new FaxDocumentService($siteId);

    // 3. Attempt patient matching by phone
    $patientId = $faxService->findPatientByPhone($fromNumber);

    // 4. Store document
    $result = $faxService->storeFaxDocument(
        $faxSid,
        $mediaContent,
        $fromNumber,
        $patientId,
        $mimeType
    );

    // 5. Insert/update queue record
    QueryUtils::sqlStatementThrowException($sql, [
        // ... parameters with document_id and media_path
    ]);
}

private function downloadFaxMediaContent(string $mediaUrl): ?string
{
    // 1. Validate URL (SSRF protection)
    if (!$this->isValidSignalWireUrl($mediaUrl)) {
        return null;
    }

    // 2. Get and decrypt credentials
    $apiToken = $this->getDecryptedApiToken();

    // 3. Download using oeHttp with Bearer token
    $httpRequest = oeHttpRequest::newArgs(oeHttp::client());
    $httpRequest->usingHeaders([
        'Authorization' => 'Bearer ' . $apiToken
    ]);
    $response = $httpRequest->get($mediaUrl);

    return $response->body();
}

private function isValidSignalWireUrl(string $url): bool
{
    $parsedUrl = parse_url($url);

    // Only HTTPS
    if ($parsedUrl['scheme'] !== 'https') {
        return false;
    }

    // Whitelist SignalWire domains
    $allowedDomains = [
        'files.signalwire.com',
        'api.signalwire.com'
    ];

    // Check host
    $host = strtolower($parsedUrl['host']);
    foreach ($allowedDomains as $domain) {
        if ($host === $domain || str_ends_with($host, '.' . $domain)) {
            return true;
        }
    }

    return false;
}

$fax = $this->client->fax->v1->faxes->create([
    'to' => $phone,
    'from' => $this->faxNumber,
    'mediaUrl' => $mediaUrl
]);

// Build metadata
$faxData = [
    'sid' => $fax->sid,
    'from' => $this->faxNumber,
    'to' => $phone,
    'direction' => 'outbound',
    'status' => $fax->status ?? 'queued',
    'recipient_name' => $recipientName,
    'sent_by' => $user['username'],
    'dateCreated' => date('Y-m-d H:i:s')
];

// Store in queue
QueryUtils::sqlStatementThrowException($sql, [
    $uid, $fax->sid, $this->faxNumber, $phone,
    json_encode($faxData), 'outbound', $fax->status ?? 'queued', $siteId
]);

private function upsertFaxFromSignalWire($fax): void
{
    // Only process inbound faxes
    if ($fax->direction !== 'inbound') {
        return;
    }

    // Fetch fresh status from API
    $freshFax = $this->client->fax->v1->faxes->getContext($jobId)->fetch();

    // Build standardized fax data
    $faxData = [
        'sid' => $jobId,
        'from' => $from,
        'to' => $to,
        'status' => $status,
        'direction' => 'inbound',
        'numPages' => $numPages,
        'mediaUrl' => $mediaUrl,
        'mimeType' => 'application/pdf'
    ];

    // Use standardized storage method
    $this->storeInboundFax($faxData);
}

public function insertFaxQueue($faxDetails): int
{
    try {
        // 1. Decode fax content
        $mediaContent = base64_decode((string)$faxDetails->FaxImage);

        // 2. Initialize FaxDocumentService
        $faxService = new FaxDocumentService($siteId);

        // 3. Auto-match patient
        $patientId = $faxService->findPatientByPhone($fromNumber);

        // 4. Store document
        $result = $faxService->storeFaxDocument(
            $jobId,
            $mediaContent,
            $fromNumber,
            $patientId,
            $docType
        );

        // 5. Insert queue record with document references
        QueryUtils::sqlStatementThrowException($sql, [
            $uid, $account, $jobId, $received,
            $fromNumber, $toNumber, $docType,
            json_encode($faxData),
            'received', 'inbound',
            $siteId, $patientId, $documentId, $mediaPath
        ]);

        return (int)$recordId;
    } catch (Exception $e) {
        error_log("EtherFaxActions.insertFaxQueue(): ERROR - " . $e->getMessage());
        throw $e;
    }
}

$siteId = $_SESSION['site_id'] ?? 'default';

// Query includes site_id filter
$result = QueryUtils::querySingleRow(
    "SELECT * FROM oe_faxsms_queue WHERE job_id = ? AND site_id = ?",
    [$jobId, $siteId]
);

Input Phone: +1 (555) 123-4567

Patterns Tried (in order):
1. 5551234567 (digits only)
2. +15551234567 (E.164 format)
3. 15551234567 (with country code)
4. 555-123-4567 (formatted)
5. (555) 123-4567 (formatted with parens)

Database Search:
- phone_cell LIKE '%pattern%'
- phone_home LIKE '%pattern%'
- phone_biz LIKE '%pattern%'

Returns: Patient ID if found, 0 otherwise

try {
    // Business logic
} catch (FaxDocumentException $e) {
    error_log("Service: Error - " . $e->getMessage());
    throw $e;  // Propagate or handle gracefully
} catch (Exception $e) {
    error_log("Service: Unexpected error - " . $e->getMessage());
    // Continue with queue insert even if document storage fails
}

INFO: "Successfully stored fax {jobId} (patient_id={pid}, document_id={docId})"
WARN: "Failed to download media for fax {jobId}"
ERROR: "insertFaxQueue(): ERROR - {message}"
DEBUG: "Processing fax sid={sid}, from={from}, direction={direction}"

# The module installer automatically applies SQL migrations
# Or manually:
mysql -u user -p database < table.sql

KEY `job_id` (`job_id`(255)) -- Fast SID lookup
KEY `site_id` (`site_id`) -- Multi-site filtering
KEY `patient_id` (`patient_id`) -- Patient-based queries
KEY `uid` (`uid`,`receive_date`) -- User timeline

error_log("DEBUG: storeInboundFax() - Processing fax {$faxSid}");
error_log("DEBUG: downloadFaxMediaContent() - Downloaded " . strlen($content) . " bytes");
error_log("DEBUG: Patient match result: {$patientId}");
error_log("DEBUG: Document created: {$documentId}");