Merge pull request #18 from paywithextend/development

Release 1.1.0

Author: byjoh

extend/__init__.py

@@ -5,7 +5,7 @@
 from extend.models import VirtualCard, Transaction, RecurrenceConfig
 from .extend import ExtendClient
 
-__version__ = "0.1.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "ExtendClient",

extend/extend.py

@@ -3,6 +3,7 @@
 from .resources.credit_cards import CreditCards
 from .resources.expense_data import ExpenseData
 from .resources.receipt_attachments import ReceiptAttachments
+from .resources.receipt_capture import ReceiptCapture
 from .resources.transactions import Transactions
 
 
@@ -33,3 +34,4 @@ def __init__(self, api_key: str, api_secret: str):
         self.transactions = Transactions(self._api_client)
         self.expense_data = ExpenseData(self._api_client)
         self.receipt_attachments = ReceiptAttachments(self._api_client)
+        self.receipt_capture = ReceiptCapture(self._api_client)

extend/resources/receipt_attachments.py

@@ -1,4 +1,4 @@
-from typing import Dict, IO
+from typing import Dict, IO, Optional
 
 from extend.client import APIClient
 from .resource import Resource
@@ -14,15 +14,15 @@ def __init__(self, api_client: APIClient):
 
     async def create_receipt_attachment(
             self,
-            transaction_id: str,
             file: IO,
+            transaction_id: Optional[str] = None,
     ) -> Dict:
         """Create a receipt attachment for a transaction by uploading a file using multipart form data.
 
         Args:
-            transaction_id (str): The unique identifier of the transaction to attach the receipt to
             file (IO): A file-like object opened in binary mode that contains the data
                        to be uploaded
+            transaction_id (Optional[str]): The optional unique identifier of the transaction to attach the receipt to
 
         Returns:
             Dict: A dictionary representing the receipt attachment, including:
@@ -39,5 +39,5 @@ async def create_receipt_attachment(
 
         return await self._request(
             method="post_multipart",
-            data={"transactionId": transaction_id},
+            data={"transactionId": transaction_id} if transaction_id else None,
             files={"file": file})

extend/resources/receipt_capture.py

@@ -0,0 +1,78 @@
+from typing import Dict, List, Any
+
+from extend.client import APIClient
+from .resource import Resource
+
+
+class ReceiptCapture(Resource):
+    @property
+    def _base_url(self) -> str:
+        return "/receiptcapture"
+
+    def __init__(self, api_client: APIClient):
+        super().__init__(api_client)
+
+    async def automatch_receipts(
+            self,
+            receipt_attachment_ids: List[str],
+    ) -> Dict[str, Any]:
+        """
+        Initiates an asynchronous bulk receipt automatch job.
+
+        This method triggers an asynchronous job on the server that processes the provided receipt
+        attachment IDs. The operation is non-blocking: it immediately returns a job ID and preliminary
+        details, while the matching process is performed in the background.
+
+        The server returns a response conforming to the BulkReceiptAutomatchResponse structure, which includes:
+          - id (str): The bulk automatch job ID.
+          - tasks (List[Dict]): A list of tasks representing individual automatch operations. Each task includes:
+              - id (str): Task ID.
+              - status (str): Task status.
+              - receiptAttachmentId (str): Receipt attachment ID.
+              - transactionId (Optional[str]): Matched transaction ID (if available).
+              - attachmentsCount (Optional[int]): Number of attachments on the matched transaction.
+
+        Args:
+            receipt_attachment_ids (List[str]): A list of receipt attachment IDs to be automatched.
+
+        Returns:
+            Dict[str, Any]: A dictionary representing the Bulk Receipt Automatch Response, including the job ID.
+
+        Raises:
+            httpx.HTTPError: If the request fails.
+        """
+        payload = {"receiptAttachmentIds": receipt_attachment_ids}
+
+        return await self._request(
+            method="post",
+            path="/automatch",
+            params=payload,
+        )
+
+    async def get_automatch_status(
+            self,
+            job_id: str,
+    ) -> Dict[str, Any]:
+        """
+        Retrieves the status of a bulk receipt capture automatch job.
+
+        This method calls a GET endpoint with the provided job ID to fetch the current status of the
+        asynchronous automatch job. The response conforms to the BulkReceiptAutomatchResponse structure and includes:
+          - id (str): The job ID.
+          - tasks (List[Dict]): A list of automatch task views containing details such as task ID, status,
+            receipt attachment ID, the matched transaction ID (if available), and the number of attachments
+            on the transaction.
+
+        Args:
+            job_id (str): The ID of the automatch job whose status is to be retrieved.
+
+        Returns:
+            Dict[str, Any]: A dictionary representing the current Bulk Receipt Automatch Response.
+
+        Raises:
+            httpx.HTTPError: If the request fails.
+        """
+        return await self._request(
+            method="get",
+            path=f"/{job_id}/status",
+        )

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paywithextend"
-version = "1.0.0"
+version = "1.1.0"
 description = "Python client for the Extend API"
 readme = "README.md"
 authors = [{ name = "Extend Engineering", email = "[email protected]" }]

tests/test_client.py

@@ -1,6 +1,6 @@
 import os
 from datetime import datetime, timedelta
-from typing import Any
+from typing import Any, Dict, List
 
 import httpx
 import pytest
@@ -593,3 +593,59 @@ async def test_update_expense_category_label(extend, mocker):
 
     assert response["name"] == "Updated Label"
     assert response["active"] is True
+
+
+@pytest.mark.asyncio
+async def test_automatch_receipts(extend, mocker):
+    """
+    Test that the automatch_receipts endpoint returns the expected job and task details.
+    """
+    mock_response: Dict[str, Any] = {
+        "id": "job_123",
+        "tasks": [
+            {
+                "id": "task_1",
+                "status": "PENDING",
+                "receiptAttachmentId": "ra_123",
+                "transactionId": None,
+                "attachmentsCount": 0
+            }
+        ]
+    }
+
+    mocker.patch.object(extend._api_client, 'post', return_value=mock_response)
+    receipt_attachment_ids: List[str] = ["ra_123"]
+
+    response = await extend.receipt_capture.automatch_receipts(
+        receipt_attachment_ids=receipt_attachment_ids
+    )
+
+    assert response["id"] == "job_123"
+    assert len(response["tasks"]) == 1
+    assert response["tasks"][0]["receiptAttachmentId"] == "ra_123"
+
+
+@pytest.mark.asyncio
+async def test_get_automatch_status(extend, mocker):
+    """
+    Test that the get_automatch_status endpoint returns the current job status and task details.
+    """
+    mock_response: Dict[str, Any] = {
+        "id": "job_123",
+        "tasks": [
+            {
+                "id": "task_1",
+                "status": "COMPLETED",
+                "receiptAttachmentId": "ra_123",
+                "transactionId": "txn_123",
+                "attachmentsCount": 1
+            }
+        ]
+    }
+
+    mocker.patch.object(extend._api_client, 'get', return_value=mock_response)
+    response = await extend.receipt_capture.get_automatch_status("job_123")
+
+    assert response["id"] == "job_123"
+    assert len(response["tasks"]) == 1
+    assert response["tasks"][0]["transactionId"] == "txn_123"

tests/test_integration.py

@@ -435,7 +435,8 @@ async def test_update_transaction_expense_data_with_specific_category_and_label(
         transactions_response = await extend.transactions.get_transactions(per_page=1)
         assert "report" in transactions_response, "Response should include 'report'"
         assert "transactions" in transactions_response["report"], "Response should include 'transactions'"
-        assert transactions_response["report"]["transactions"], "No transactions available for testing expense data update"
+        assert transactions_response["report"][
+            "transactions"], "No transactions available for testing expense data update"
         transaction = transactions_response["report"]["transactions"][0]
         transaction_id = transaction["id"]
 
@@ -494,6 +495,46 @@ async def test_create_receipt_attachment(self, extend):
         assert response["contentType"] == "image/png", "Content type should be 'image/png'"
 
 
+@pytest.mark.integration
+class TestReceiptCaptureEndpoints:
+    """Integration tests for the new receipt capture endpoints"""
+
+    @pytest.mark.asyncio
+    async def test_automatch_receipts_and_get_status(self, extend):
+        """
+        Integration test that:
+          1. Creates a dummy receipt attachment for an existing transaction.
+          2. Initiates an automatch job using the new endpoint.
+          3. Retrieves and verifies the automatch job status.
+        """
+        # Create a dummy PNG file in memory (a minimal PNG header plus extra bytes)
+        png_header = b'\x89PNG\r\n\x1a\n'
+        dummy_content = png_header + b'\x00' * 100
+        file_obj = BytesIO(dummy_content)
+        file_obj.name = f"test_receipt_{uuid.uuid4()}.png"
+
+        # Create a receipt attachment using the receipt_attachments endpoint
+        attachment_response = await extend.receipt_attachments.create_receipt_attachment(
+            file=file_obj
+        )
+        assert "id" in attachment_response, "Receipt attachment should have an id"
+        receipt_attachment_id = attachment_response["id"]
+
+        # Initiate an automatch job using the new receipt capture endpoint
+        automatch_response = await extend.receipt_capture.automatch_receipts(
+            receipt_attachment_ids=[receipt_attachment_id]
+        )
+        assert "id" in automatch_response, "Automatch response should include a job id"
+        assert "tasks" in automatch_response, "Automatch response should include tasks"
+        job_id = automatch_response["id"]
+
+        # Retrieve the automatch job status using the new endpoint
+        status_response = await extend.receipt_capture.get_automatch_status(job_id)
+        assert "id" in status_response, "Status response should include a job id"
+        assert status_response["id"] == job_id, "Job id should match the one returned during automatch"
+        assert "tasks" in status_response, "Status response should include tasks"
+
+
 def test_environment_variables():
     """Test that required environment variables are set"""
     assert os.getenv("EXTEND_API_KEY"), "EXTEND_API_KEY environment variable is required"