awb-extractor 0.1.1__tar.gz

awb_extractor-0.1.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: awb-extractor
+Version: 0.1.1
+Summary: Extract recipient address from AWB/shipping label PDF using Claude AI
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+
+# AWB Extractor
+
+Python SDK for extracting receiver and shipment information from AWB/shipping
+label PDF files using Claude AI.
+
+## Features
+
+- Extract from PDF bytes, local PDF files, or PDF URLs
+- Batch extraction from multiple URLs
+- Optional default HTTP headers for protected AWB URLs
+- Typed `AWBResult` dataclass output
+- Custom exceptions for API key, PDF download, and JSON parsing failures
+
+## Requirements
+
+- Python 3.10+
+- Anthropic API key
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install awb-extractor
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+result = extractor.from_file("label.pdf")
+
+print(result.recipient_name)
+print(result.to_dict())
+```
+
+Example result:
+
+```python
+{
+    "tracking_number": "NHSVC972103440",
+    "recipient_name": "Nguyen Van A",
+    "recipient_phone": "(+84)03******37",
+    "recipient_address": "237 Nguyen Trai",
+    "recipient_ward": "Phuong Ben Thanh",
+    "recipient_district": "Quan 1",
+    "recipient_province": "TP. Ho Chi Minh",
+    "sender_name": "Onflow",
+    "sender_address": "TP. Ho Chi Minh",
+    "cod": "0",
+    "weight": "0.700 KG",
+    "order_id": "584425059595159079",
+}
+```
+
+## Supported Inputs
+
+### PDF bytes
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+
+with open("label.pdf", "rb") as file:
+    result = extractor.from_bytes(file.read())
+```
+
+### Local PDF file
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+result = extractor.from_file("label.pdf")
+```
+
+### PDF URL
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(
+    api_key="sk-ant-...",
+    http_headers={"Authorization": "Bearer token"},
+)
+
+result = extractor.from_url("https://example.com/awb.pdf")
+```
+
+You can pass request-specific headers with `extra_headers`:
+
+```python
+result = extractor.from_url(
+    "https://example.com/awb.pdf",
+    extra_headers={"X-Request-ID": "request-123"},
+)
+```
+
+### Multiple URLs
+
+`from_urls()` returns a list of dictionaries with `url`, `data`, and `error`.
+Failed URLs do not stop the whole batch.
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+results = extractor.from_urls([
+    "https://example.com/good.pdf",
+    "https://example.com/bad.pdf",
+])
+```
+
+## Result Fields
+
+`AWBResult` includes:
+
+- `tracking_number`
+- `recipient_name`
+- `recipient_phone`
+- `recipient_address`
+- `recipient_ward`
+- `recipient_district`
+- `recipient_province`
+- `sender_name`
+- `sender_address`
+- `cod`
+- `weight`
+- `order_id`
+
+Use `to_dict()` or `to_json()` to serialize the result.
+
+## Exceptions
+
+- `APIKeyError`: missing API key
+- `PDFDownloadError`: PDF URL download failed
+- `ExtractionError`: Claude response could not be parsed as JSON
+
+## Package Structure
+
+- `awb_extractor/extractor.py`: public `AWBExtractor` class
+- `awb_extractor/models.py`: `AWBResult` dataclass
+- `awb_extractor/exceptions.py`: package exceptions
+
+## Publishing
+
+GitHub Actions builds and publishes the package to PyPI on every push to `main`.
+
+The repository must define this GitHub secret:
+
+```text
+PYPI_API_TOKEN
+```
+
+PyPI does not allow replacing an existing version. If a commit on `main` does not
+bump `project.version` in `pyproject.toml`, the publish step skips the existing
+distribution.

awb_extractor-0.1.1/README.md

@@ -0,0 +1,166 @@
+# AWB Extractor
+
+Python SDK for extracting receiver and shipment information from AWB/shipping
+label PDF files using Claude AI.
+
+## Features
+
+- Extract from PDF bytes, local PDF files, or PDF URLs
+- Batch extraction from multiple URLs
+- Optional default HTTP headers for protected AWB URLs
+- Typed `AWBResult` dataclass output
+- Custom exceptions for API key, PDF download, and JSON parsing failures
+
+## Requirements
+
+- Python 3.10+
+- Anthropic API key
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install awb-extractor
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+result = extractor.from_file("label.pdf")
+
+print(result.recipient_name)
+print(result.to_dict())
+```
+
+Example result:
+
+```python
+{
+    "tracking_number": "NHSVC972103440",
+    "recipient_name": "Nguyen Van A",
+    "recipient_phone": "(+84)03******37",
+    "recipient_address": "237 Nguyen Trai",
+    "recipient_ward": "Phuong Ben Thanh",
+    "recipient_district": "Quan 1",
+    "recipient_province": "TP. Ho Chi Minh",
+    "sender_name": "Onflow",
+    "sender_address": "TP. Ho Chi Minh",
+    "cod": "0",
+    "weight": "0.700 KG",
+    "order_id": "584425059595159079",
+}
+```
+
+## Supported Inputs
+
+### PDF bytes
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+
+with open("label.pdf", "rb") as file:
+    result = extractor.from_bytes(file.read())
+```
+
+### Local PDF file
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+result = extractor.from_file("label.pdf")
+```
+
+### PDF URL
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(
+    api_key="sk-ant-...",
+    http_headers={"Authorization": "Bearer token"},
+)
+
+result = extractor.from_url("https://example.com/awb.pdf")
+```
+
+You can pass request-specific headers with `extra_headers`:
+
+```python
+result = extractor.from_url(
+    "https://example.com/awb.pdf",
+    extra_headers={"X-Request-ID": "request-123"},
+)
+```
+
+### Multiple URLs
+
+`from_urls()` returns a list of dictionaries with `url`, `data`, and `error`.
+Failed URLs do not stop the whole batch.
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+results = extractor.from_urls([
+    "https://example.com/good.pdf",
+    "https://example.com/bad.pdf",
+])
+```
+
+## Result Fields
+
+`AWBResult` includes:
+
+- `tracking_number`
+- `recipient_name`
+- `recipient_phone`
+- `recipient_address`
+- `recipient_ward`
+- `recipient_district`
+- `recipient_province`
+- `sender_name`
+- `sender_address`
+- `cod`
+- `weight`
+- `order_id`
+
+Use `to_dict()` or `to_json()` to serialize the result.
+
+## Exceptions
+
+- `APIKeyError`: missing API key
+- `PDFDownloadError`: PDF URL download failed
+- `ExtractionError`: Claude response could not be parsed as JSON
+
+## Package Structure
+
+- `awb_extractor/extractor.py`: public `AWBExtractor` class
+- `awb_extractor/models.py`: `AWBResult` dataclass
+- `awb_extractor/exceptions.py`: package exceptions
+
+## Publishing
+
+GitHub Actions builds and publishes the package to PyPI on every push to `main`.
+
+The repository must define this GitHub secret:
+
+```text
+PYPI_API_TOKEN
+```
+
+PyPI does not allow replacing an existing version. If a commit on `main` does not
+bump `project.version` in `pyproject.toml`, the publish step skips the existing
+distribution.

awb_extractor-0.1.1/awb_extractor/__init__.py

@@ -0,0 +1,18 @@
+from .extractor import AWBExtractor
+from .models import AWBResult
+from .exceptions import (
+    AWBExtractorError,
+    APIKeyError,
+    PDFDownloadError,
+    ExtractionError,
+)
+
+__version__ = "0.1.1"
+__all__ = [
+    "AWBExtractor",
+    "AWBResult",
+    "AWBExtractorError",
+    "APIKeyError",
+    "PDFDownloadError",
+    "ExtractionError",
+]

awb_extractor-0.1.1/awb_extractor/exceptions.py

@@ -0,0 +1,22 @@
+class AWBExtractorError(Exception):
+    pass
+
+
+class APIKeyError(AWBExtractorError):
+    pass
+
+
+class PDFDownloadError(AWBExtractorError):
+    def __init__(self, url: str, status_code: int = None, message: str = None):
+        self.url = url
+        self.status_code = status_code
+        detail = f"status={status_code}" if status_code else message or "unknown error"
+        super().__init__(f"Failed to download PDF from {url!r}: {detail}")
+
+
+class ExtractionError(AWBExtractorError):
+    def __init__(self, raw_response: str = None):
+        self.raw_response = raw_response
+        super().__init__(
+            f"Failed to parse Claude response as JSON. Raw: {raw_response!r}"
+        )

awb_extractor-0.1.1/awb_extractor/extractor.py

@@ -0,0 +1,129 @@
+import base64
+import json
+from pathlib import Path
+from typing import Optional
+
+import anthropic
+import httpx
+
+from .exceptions import APIKeyError, ExtractionError, PDFDownloadError
+from .models import AWBResult
+
+_SYSTEM_PROMPT = """You are an OCR system that extracts information from shipping labels (AWB).
+Return only raw JSON, no explanation, no markdown. Required format:
+{
+  "tracking_number": "",
+  "recipient_name": "",
+  "recipient_phone": "",
+  "recipient_address": "",
+  "recipient_ward": "",
+  "recipient_district": "",
+  "recipient_province": "",
+  "sender_name": "",
+  "sender_address": "",
+  "cod": "",
+  "weight": "",
+  "order_id": ""
+}"""
+
+
+class AWBExtractor:
+    DEFAULT_MODEL = "claude-haiku-4-5-20251001"
+
+    def __init__(
+        self,
+        api_key: str,
+        http_headers: Optional[dict] = None,
+        model: str = DEFAULT_MODEL,
+        timeout: int = 30,
+    ):
+        if not api_key:
+            raise APIKeyError("api_key is required.")
+        self._client = anthropic.Anthropic(api_key=api_key)
+        self._http_headers = http_headers or {}
+        self._model = model
+        self._timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def from_bytes(self, pdf_bytes: bytes) -> AWBResult:
+        raw_json = self._call_claude(pdf_bytes)
+        return AWBResult.from_dict(raw_json)
+
+    def from_file(self, pdf_path: str) -> AWBResult:
+        pdf_bytes = Path(pdf_path).read_bytes()
+        return self.from_bytes(pdf_bytes)
+
+    def from_url(self, url: str, extra_headers: Optional[dict] = None) -> AWBResult:
+        pdf_bytes = self._download(url, extra_headers)
+        return self.from_bytes(pdf_bytes)
+
+    def from_urls(self, urls: list[str]) -> list[dict]:
+        results = []
+        for url in urls:
+            try:
+                results.append({
+                    "url": url,
+                    "data": self.from_url(url),
+                    "error": None,
+                })
+            except Exception as e:
+                results.append({
+                    "url": url,
+                    "data": None,
+                    "error": str(e),
+                })
+        return results
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _download(self, url: str, extra_headers: Optional[dict] = None) -> bytes:
+        headers = {**self._http_headers, **(extra_headers or {})}
+        try:
+            resp = httpx.get(url, headers=headers, follow_redirects=True, timeout=self._timeout)
+            resp.raise_for_status()
+            return resp.content
+        except httpx.HTTPStatusError as e:
+            raise PDFDownloadError(url, status_code=e.response.status_code) from e
+        except httpx.RequestError as e:
+            raise PDFDownloadError(url, message=str(e)) from e
+
+    def _call_claude(self, pdf_bytes: bytes) -> dict:
+        pdf_base64 = base64.standard_b64encode(pdf_bytes).decode("utf-8")
+
+        response = self._client.messages.create(
+            model=self._model,
+            max_tokens=1024,
+            system=_SYSTEM_PROMPT,
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "document",
+                            "source": {
+                                "type": "base64",
+                                "media_type": "application/pdf",
+                                "data": pdf_base64,
+                            },
+                        },
+                        {
+                            "type": "text",
+                            "text": "Extract all information from this shipping label.",
+                        },
+                    ],
+                }
+            ],
+        )
+
+        raw = response.content[0].text.strip()
+        raw = raw.replace("```json", "").replace("```", "").strip()
+
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ExtractionError(raw_response=raw) from e

awb_extractor-0.1.1/awb_extractor/models.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+import json
+
+
+@dataclass
+class AWBResult:
+    tracking_number: Optional[str] = None
+    recipient_name: Optional[str] = None
+    recipient_phone: Optional[str] = None
+    recipient_address: Optional[str] = None
+    recipient_ward: Optional[str] = None
+    recipient_district: Optional[str] = None
+    recipient_province: Optional[str] = None
+    sender_name: Optional[str] = None
+    sender_address: Optional[str] = None
+    cod: Optional[str] = None
+    weight: Optional[str] = None
+    order_id: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AWBResult":
+        valid_keys = cls.__dataclass_fields__.keys()
+        filtered = {k: v or None for k, v in data.items() if k in valid_keys}
+        return cls(**filtered)
+
+    def to_dict(self) -> dict:
+        return {k: v for k, v in asdict(self).items()}
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+
+    def __repr__(self) -> str:
+        fields = ", ".join(
+            f"{k}={v!r}" for k, v in self.to_dict().items() if v is not None
+        )
+        return f"AWBResult({fields})"

awb_extractor-0.1.1/awb_extractor.egg-info/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: awb-extractor
+Version: 0.1.1
+Summary: Extract recipient address from AWB/shipping label PDF using Claude AI
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+
+# AWB Extractor
+
+Python SDK for extracting receiver and shipment information from AWB/shipping
+label PDF files using Claude AI.
+
+## Features
+
+- Extract from PDF bytes, local PDF files, or PDF URLs
+- Batch extraction from multiple URLs
+- Optional default HTTP headers for protected AWB URLs
+- Typed `AWBResult` dataclass output
+- Custom exceptions for API key, PDF download, and JSON parsing failures
+
+## Requirements
+
+- Python 3.10+
+- Anthropic API key
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install awb-extractor
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+result = extractor.from_file("label.pdf")
+
+print(result.recipient_name)
+print(result.to_dict())
+```
+
+Example result:
+
+```python
+{
+    "tracking_number": "NHSVC972103440",
+    "recipient_name": "Nguyen Van A",
+    "recipient_phone": "(+84)03******37",
+    "recipient_address": "237 Nguyen Trai",
+    "recipient_ward": "Phuong Ben Thanh",
+    "recipient_district": "Quan 1",
+    "recipient_province": "TP. Ho Chi Minh",
+    "sender_name": "Onflow",
+    "sender_address": "TP. Ho Chi Minh",
+    "cod": "0",
+    "weight": "0.700 KG",
+    "order_id": "584425059595159079",
+}
+```
+
+## Supported Inputs
+
+### PDF bytes
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+
+with open("label.pdf", "rb") as file:
+    result = extractor.from_bytes(file.read())
+```
+
+### Local PDF file
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+result = extractor.from_file("label.pdf")
+```
+
+### PDF URL
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(
+    api_key="sk-ant-...",
+    http_headers={"Authorization": "Bearer token"},
+)
+
+result = extractor.from_url("https://example.com/awb.pdf")
+```
+
+You can pass request-specific headers with `extra_headers`:
+
+```python
+result = extractor.from_url(
+    "https://example.com/awb.pdf",
+    extra_headers={"X-Request-ID": "request-123"},
+)
+```
+
+### Multiple URLs
+
+`from_urls()` returns a list of dictionaries with `url`, `data`, and `error`.
+Failed URLs do not stop the whole batch.
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+results = extractor.from_urls([
+    "https://example.com/good.pdf",
+    "https://example.com/bad.pdf",
+])
+```
+
+## Result Fields
+
+`AWBResult` includes:
+
+- `tracking_number`
+- `recipient_name`
+- `recipient_phone`
+- `recipient_address`
+- `recipient_ward`
+- `recipient_district`
+- `recipient_province`
+- `sender_name`
+- `sender_address`
+- `cod`
+- `weight`
+- `order_id`
+
+Use `to_dict()` or `to_json()` to serialize the result.
+
+## Exceptions
+
+- `APIKeyError`: missing API key
+- `PDFDownloadError`: PDF URL download failed
+- `ExtractionError`: Claude response could not be parsed as JSON
+
+## Package Structure
+
+- `awb_extractor/extractor.py`: public `AWBExtractor` class
+- `awb_extractor/models.py`: `AWBResult` dataclass
+- `awb_extractor/exceptions.py`: package exceptions
+
+## Publishing
+
+GitHub Actions builds and publishes the package to PyPI on every push to `main`.
+
+The repository must define this GitHub secret:
+
+```text
+PYPI_API_TOKEN
+```
+
+PyPI does not allow replacing an existing version. If a commit on `main` does not
+bump `project.version` in `pyproject.toml`, the publish step skips the existing
+distribution.

awb_extractor-0.1.1/awb_extractor.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+awb_extractor/__init__.py
+awb_extractor/exceptions.py
+awb_extractor/extractor.py
+awb_extractor/models.py
+awb_extractor.egg-info/PKG-INFO
+awb_extractor.egg-info/SOURCES.txt
+awb_extractor.egg-info/dependency_links.txt
+awb_extractor.egg-info/requires.txt
+awb_extractor.egg-info/top_level.txt
+tests/test_extractor.py

awb_extractor-0.1.1/awb_extractor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

awb_extractor-0.1.1/awb_extractor.egg-info/requires.txt

@@ -0,0 +1,6 @@
+anthropic>=0.40.0
+httpx>=0.27.0
+
+[dev]
+pytest>=8.0
+pytest-mock>=3.14

awb_extractor-0.1.1/awb_extractor.egg-info/top_level.txt

@@ -0,0 +1 @@
+awb_extractor

awb_extractor-0.1.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "awb-extractor"
+version = "0.1.1"
+description = "Extract recipient address from AWB/shipping label PDF using Claude AI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "anthropic>=0.40.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.14",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["awb_extractor*"]

awb_extractor-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

awb_extractor-0.1.1/tests/test_extractor.py

@@ -0,0 +1,170 @@
+import json
+import pytest
+from unittest.mock import MagicMock, patch
+
+from awb_extractor import AWBExtractor, AWBResult
+from awb_extractor.exceptions import APIKeyError, ExtractionError, PDFDownloadError
+
+MOCK_PDF = b"%PDF-1.4 fake content"
+MOCK_RESPONSE = {
+    "tracking_number": "NHSVC972103440",
+    "recipient_name": "Nguyễn Thanh Huyền",
+    "recipient_phone": "(+84)03******37",
+    "recipient_address": "Trường Mầm Non Trung Chính, 237HNC19",
+    "recipient_ward": "Xã Trung Chính",
+    "recipient_district": "Huyện Nông Cống",
+    "recipient_province": "Thanh Hóa",
+    "sender_name": "BZU BZU VIỆT NAM",
+    "sender_address": "Số 3A đường An Phú Đông 13, Q.12, TP.HCM",
+    "cod": "Được đồng kiểm",
+    "weight": "0.700 KG",
+    "order_id": "584425059595159079",
+}
+
+
+def make_extractor():
+    return AWBExtractor(api_key="sk-ant-test")
+
+
+def mock_claude_response(data: dict):
+    msg = MagicMock()
+    msg.content = [MagicMock(text=json.dumps(data))]
+    return msg
+
+
+# ------------------------------------------------------------------
+# AWBResult
+# ------------------------------------------------------------------
+
+def test_awb_result_from_dict():
+    result = AWBResult.from_dict(MOCK_RESPONSE)
+    assert result.tracking_number == "NHSVC972103440"
+    assert result.recipient_name == "Nguyễn Thanh Huyền"
+    assert result.recipient_province == "Thanh Hóa"
+
+
+def test_awb_result_ignores_unknown_keys():
+    data = {**MOCK_RESPONSE, "unknown_field": "should be ignored"}
+    result = AWBResult.from_dict(data)
+    assert not hasattr(result, "unknown_field")
+
+
+def test_awb_result_to_dict():
+    result = AWBResult.from_dict(MOCK_RESPONSE)
+    d = result.to_dict()
+    assert d["tracking_number"] == "NHSVC972103440"
+
+
+def test_awb_result_to_json():
+    result = AWBResult.from_dict(MOCK_RESPONSE)
+    parsed = json.loads(result.to_json())
+    assert parsed["order_id"] == "584425059595159079"
+
+
+def test_awb_result_empty_string_becomes_none():
+    data = {**MOCK_RESPONSE, "cod": ""}
+    result = AWBResult.from_dict(data)
+    assert result.cod is None
+
+
+# ------------------------------------------------------------------
+# AWBExtractor init
+# ------------------------------------------------------------------
+
+def test_raises_if_no_api_key():
+    with pytest.raises(APIKeyError):
+        AWBExtractor(api_key="")
+
+
+# ------------------------------------------------------------------
+# from_bytes
+# ------------------------------------------------------------------
+
+def test_from_bytes_returns_awb_result():
+    extractor = make_extractor()
+    with patch.object(extractor._client.messages, "create", return_value=mock_claude_response(MOCK_RESPONSE)):
+        result = extractor.from_bytes(MOCK_PDF)
+    assert isinstance(result, AWBResult)
+    assert result.tracking_number == "NHSVC972103440"
+
+
+def test_from_bytes_raises_extraction_error_on_bad_json():
+    extractor = make_extractor()
+    bad_msg = MagicMock()
+    bad_msg.content = [MagicMock(text="not json at all")]
+    with patch.object(extractor._client.messages, "create", return_value=bad_msg):
+        with pytest.raises(ExtractionError):
+            extractor.from_bytes(MOCK_PDF)
+
+
+# ------------------------------------------------------------------
+# from_file
+# ------------------------------------------------------------------
+
+def test_from_file(tmp_path):
+    pdf_file = tmp_path / "test.pdf"
+    pdf_file.write_bytes(MOCK_PDF)
+    extractor = make_extractor()
+    with patch.object(extractor._client.messages, "create", return_value=mock_claude_response(MOCK_RESPONSE)):
+        result = extractor.from_file(str(pdf_file))
+    assert result.recipient_name == "Nguyễn Thanh Huyền"
+
+
+# ------------------------------------------------------------------
+# from_url
+# ------------------------------------------------------------------
+
+def test_from_url_success():
+    extractor = make_extractor()
+    with patch("awb_extractor.extractor.httpx.get") as mock_get, \
+         patch.object(extractor._client.messages, "create", return_value=mock_claude_response(MOCK_RESPONSE)):
+        mock_get.return_value = MagicMock(content=MOCK_PDF, raise_for_status=lambda: None)
+        result = extractor.from_url("https://example.com/awb.pdf")
+    assert result.order_id == "584425059595159079"
+
+
+def test_from_url_raises_download_error_on_http_error():
+    import httpx
+    extractor = make_extractor()
+    with patch("awb_extractor.extractor.httpx.get") as mock_get:
+        mock_response = MagicMock()
+        mock_response.status_code = 403
+        mock_get.return_value.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "403", request=MagicMock(), response=mock_response
+        )
+        with pytest.raises(PDFDownloadError) as exc_info:
+            extractor.from_url("https://example.com/awb.pdf")
+        assert exc_info.value.status_code == 403
+
+
+# ------------------------------------------------------------------
+# from_urls (batch)
+# ------------------------------------------------------------------
+
+def test_from_urls_handles_mixed_results():
+    import httpx
+    extractor = make_extractor()
+
+    def side_effect(url, **kwargs):
+        mock = MagicMock()
+        if "good" in url:
+            mock.content = MOCK_PDF
+            mock.raise_for_status = lambda: None
+            return mock
+        mock_response = MagicMock(status_code=404)
+        mock.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "404", request=MagicMock(), response=mock_response
+        )
+        return mock
+
+    with patch("awb_extractor.extractor.httpx.get", side_effect=side_effect), \
+         patch.object(extractor._client.messages, "create", return_value=mock_claude_response(MOCK_RESPONSE)):
+        results = extractor.from_urls([
+            "https://example.com/good.pdf",
+            "https://example.com/bad.pdf",
+        ])
+
+    assert results[0]["data"] is not None
+    assert results[0]["error"] is None
+    assert results[1]["data"] is None
+    assert results[1]["error"] is not None