Merge pull request #100 from johntrickett86/feat-email-invoices

Add invoice emailing functionality and tests

Author: dcblogdev

src/Resources/Invoices.php

@@ -5,7 +5,12 @@
 namespace Dcblogdev\Xero\Resources;
 
 use Dcblogdev\Xero\Enums\FilterOptions;
+use Dcblogdev\Xero\Enums\InvoiceStatus;
+use Dcblogdev\Xero\Enums\InvoiceType;
 use Dcblogdev\Xero\Xero;
+use Exception;
+use Illuminate\Http\Client\RequestException;
+use Illuminate\Support\Facades\Http;
 use InvalidArgumentException;
 
 class Invoices extends Xero
@@ -76,4 +81,147 @@ public function attachment(string $invoiceId, ?string $attachmentId = null, ?str
 
         return $result['body'];
     }
+
+    /**
+     * Email an invoice to the contact's primary email and any contact persons with IncludeInEmails flag set to true.
+     * The invoice must be of Type ACCREC and a valid Status for sending (SUBMITTED, AUTHORISED or PAID).
+     *
+     * @param  string  $invoiceId  The invoice ID to email
+     * @return array Returns an array with status code, success flag, and any messages/errors:
+     *               - 'status': HTTP status code (204, 400, etc.)
+     *               - 'success': boolean indicating if the email was sent successfully
+     *               - 'message': optional success message
+     *               - 'errors': optional array of error details
+     *               - 'body': optional response body
+     *
+     * @throws Exception
+     */
+    public function email(string $invoiceId): array
+    {
+        try {
+            $response = Http::withToken($this->getAccessToken())
+                ->withHeaders(['Xero-tenant-id' => $this->getTenantId()])
+                ->accept('application/json')
+                ->post('https://api.xero.com/api.xro/2.0/Invoices/'.$invoiceId.'/Email', []);
+
+            $statusCode = $response->status();
+            $body = $response->json() ?? [];
+
+            // For 204 No Content (success)
+            if ($statusCode === 204) {
+                return [
+                    'status' => 204,
+                    'success' => true,
+                    'message' => 'Invoice email sent successfully',
+                    'body' => [],
+                ];
+            }
+
+            // For 400 errors, return structured error information
+            if ($statusCode === 400) {
+                return [
+                    'status' => 400,
+                    'success' => false,
+                    'errors' => $body,
+                    'message' => $body['Message'] ?? $body['Detail'] ?? 'Invoice email failed',
+                    'body' => $body,
+                ];
+            }
+
+            // For other errors, throw exception
+            $response->throw();
+
+            // This should never be reached, but PHPStan requires a return
+            return [];
+        } catch (RequestException $e) {
+            $statusCode = $e->response->status();
+            $body = $e->response->json() ?? [];
+
+            // For 400 errors, return structured error information
+            if ($statusCode === 400) {
+                return [
+                    'status' => 400,
+                    'success' => false,
+                    'errors' => $body,
+                    'message' => $body['Message'] ?? $body['Detail'] ?? 'Invoice email failed',
+                    'body' => $body,
+                ];
+            }
+
+            // For other errors, throw exception as usual
+            $response = json_decode($e->response->body());
+            throw new Exception($response->Detail ?? "Type: $response?->Type Message: $response?->Message Error Number: $response?->ErrorNumber");
+        } catch (Exception $e) {
+            throw new Exception($e->getMessage());
+        }
+    }
+
+    /**
+     * Get the list of email addresses that will receive the invoice email.
+     * Returns the primary contact email and any contact persons with IncludeInEmails flag set to true.
+     *
+     * @param  string  $invoiceId  The invoice ID
+     * @return array<string> Array of email addresses
+     *
+     * @throws Exception
+     */
+    public function getEmailRecipients(string $invoiceId): array
+    {
+        $invoice = $this->find($invoiceId);
+        $contactId = $invoice['Contact']['ContactID'] ?? null;
+
+        if (! $contactId) {
+            return [];
+        }
+
+        $contact = $this->contacts()->find($contactId);
+        $recipients = [];
+
+        // Add primary contact email if it exists
+        if (! empty($contact['EmailAddress'])) {
+            $recipients[] = $contact['EmailAddress'];
+        }
+
+        // Add contact persons with IncludeInEmails flag set to true
+        if (! empty($contact['ContactPersons']) && is_array($contact['ContactPersons'])) {
+            foreach ($contact['ContactPersons'] as $contactPerson) {
+                if (isset($contactPerson['IncludeInEmails']) && $contactPerson['IncludeInEmails'] === true) {
+                    if (! empty($contactPerson['EmailAddress'])) {
+                        $recipients[] = $contactPerson['EmailAddress'];
+                    }
+                }
+            }
+        }
+
+        return array_unique($recipients);
+    }
+
+    /**
+     * Check if an invoice can be emailed.
+     * The invoice must be of Type ACCREC and have a Status of SUBMITTED, AUTHORISED, or PAID.
+     *
+     * @param  string  $invoiceId  The invoice ID to check
+     * @return bool Returns true if the invoice can be emailed, false otherwise
+     *
+     * @throws Exception
+     */
+    public function canEmail(string $invoiceId): bool
+    {
+        $invoice = $this->find($invoiceId);
+
+        // Invoice must be Type ACCREC
+        if (($invoice['Type'] ?? '') !== InvoiceType::AccRec->value) {
+            return false;
+        }
+
+        // Invoice must have a valid status for sending
+        $status = $invoice['Status'] ?? '';
+        $validStatuses = [
+            InvoiceStatus::Submitted->value,
+            InvoiceStatus::Authorised->value,
+            InvoiceStatus::Paid->value,
+        ];
+
+        return in_array($status, $validStatuses, true);
+    }
 }