sync(receiptwitness): copy latest standalone code to monorepo

Syncs receiptwitness standalone repo code into monorepo subdirectory.
Includes email parsing, notifications, queue, and worker modules.
Keeps monorepo Dockerfile (uses local common/).

Co-Authored-By: Paperclip <noreply@paperclip.ing>

receiptwitness/src/receiptwitness/api/routes.py

@@ -1,9 +1,61 @@
 """Internal API routes for triggering scrapes and checking status."""
 
-from fastapi import APIRouter
+import hashlib
+import hmac
+import re
+import time
+
+from fastapi import APIRouter, HTTPException, Request
+
+from receiptwitness.config import settings
+from receiptwitness.queue.email import EmailJob, enqueue_email, get_redis
 
 router = APIRouter()
 
+TOKEN_PATTERN = re.compile(r"receipts\+([A-Za-z0-9_-]+)@")
+
+
+def verify_mailgun_signature(token: str, timestamp: str, signature: str) -> bool:
+    """Verify Mailgun webhook signature."""
+    if abs(time.time() - int(timestamp)) > 300:  # 5 min freshness
+        return False
+    key = settings.mailgun_webhook_signing_key.encode()
+    hmac_digest = hmac.new(key, f"{timestamp}{token}".encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(signature, hmac_digest)
+
+
+@router.post("/inbound/email")
+async def receive_inbound_email(request: Request):
+    form = await request.form()
+    # 1. Verify Mailgun signature
+    token = str(form.get("token", ""))
+    timestamp = str(form.get("timestamp", ""))
+    signature = str(form.get("signature", ""))
+    if not verify_mailgun_signature(token, timestamp, signature):
+        raise HTTPException(status_code=406, detail="Invalid signature")
+    # 2. Extract account token from recipient
+    recipient = str(form.get("recipient", ""))
+    match = TOKEN_PATTERN.search(recipient)
+    if not match:
+        raise HTTPException(status_code=406, detail="Invalid recipient")
+    account_token = match.group(1)
+    # 3. Enqueue — worker resolves token -> user_id
+    body_html_val = form.get("body-html")
+    body_plain_val = form.get("body-plain")
+    job = EmailJob(
+        user_id=account_token,
+        sender=str(form.get("sender", "")),
+        recipient=recipient,
+        subject=str(form.get("subject", "")),
+        body_html=str(body_html_val) if body_html_val is not None else None,
+        body_plain=str(body_plain_val) if body_plain_val is not None else None,
+        received_at=str(form.get("timestamp", "")),
+        message_id=str(form.get("Message-Id", "")),
+    )
+    client = await get_redis()
+    await enqueue_email(client, job)
+    return {"status": "queued"}
+
 
 @router.get("/health")
 async def health():

receiptwitness/src/receiptwitness/config.py

@@ -22,5 +22,13 @@ class ReceiptWitnessSettings(BaseSettings):
     headless: bool = True
     browser_timeout_ms: int = 60000
 
+    # Email notifications (Resend)
+    resend_api_key: str = ""
+    notification_email_from: str = "notifications@cartsnitch.com"
+    notifications_enabled: bool = False
+
+    # Mailgun inbound email webhook
+    mailgun_webhook_signing_key: str = ""
+
 
 settings = ReceiptWitnessSettings()

receiptwitness/src/receiptwitness/events.py

@@ -2,12 +2,17 @@
 
 import json
 import logging
+import uuid
 from datetime import UTC, datetime
 from decimal import Decimal
 
 import redis.asyncio as aioredis
+from cartsnitch_common.database import get_async_session_factory
+from cartsnitch_common.models.user import User
+from sqlalchemy import select
 
 from receiptwitness.config import settings
+from receiptwitness.notifications.email import send_receipt_notification
 
 logger = logging.getLogger(__name__)
 
@@ -39,6 +44,36 @@ async def get_redis_client() -> aioredis.Redis:
     return aioredis.Redis(connection_pool=_get_pool())
 
 
+async def _send_notification_for_event(payload: dict) -> None:
+    """Look up user email and send receipt notification. Silently skips on error."""
+    try:
+        user_uuid = uuid.UUID(payload["user_id"])
+    except (ValueError, KeyError):
+        logger.warning("Invalid user_id in event payload: %s", payload.get("user_id"))
+        return
+
+    try:
+        session_factory = get_async_session_factory(settings.database_url)
+        async with session_factory() as session:
+            result = await session.execute(select(User.email).where(User.id == user_uuid))
+            row = result.scalar_one_or_none()
+            if not row:
+                logger.warning("User %s not found for notification", user_uuid)
+                return
+            user_email = row
+    except Exception:
+        logger.exception("Failed to look up user email for notification")
+        return
+
+    await send_receipt_notification(
+        user_email=user_email,
+        store_name=payload["store_slug"],
+        item_count=payload["item_count"],
+        total=payload["total"],
+        purchase_date=payload["purchase_date"],
+    )
+
+
 async def publish_receipt_ingested(
     user_id: str,
     store_slug: str,
@@ -48,18 +83,19 @@ async def publish_receipt_ingested(
     total: Decimal | float,
 ) -> None:
     """Publish a cartsnitch.receipts.ingested event after successful ingestion."""
+    payload = {
+        "user_id": user_id,
+        "store_slug": store_slug,
+        "purchase_id": purchase_id,
+        "purchase_date": purchase_date,
+        "item_count": item_count,
+        "total": float(total) if isinstance(total, Decimal) else total,
+    }
     event = {
         "event_type": CHANNEL_RECEIPTS_INGESTED,
         "timestamp": datetime.now(UTC).isoformat(),
         "service": "receiptwitness",
-        "payload": {
-            "user_id": user_id,
-            "store_slug": store_slug,
-            "purchase_id": purchase_id,
-            "purchase_date": purchase_date,
-            "item_count": item_count,
-            "total": float(total) if isinstance(total, Decimal) else total,
-        },
+        "payload": payload,
     }
 
     try:
@@ -73,3 +109,5 @@ async def publish_receipt_ingested(
     except aioredis.ConnectionError:
         logger.error("Failed to publish event — Redis/DragonflyDB connection error")
         raise
+    else:
+        await _send_notification_for_event(payload)

receiptwitness/src/receiptwitness/notifications/email.py

@@ -0,0 +1,45 @@
+"""Email notifications via Resend."""
+
+import asyncio
+import html
+import logging
+
+import resend
+
+from receiptwitness.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+async def send_receipt_notification(
+    user_email: str,
+    store_name: str,
+    item_count: int,
+    total: float,
+    purchase_date: str,
+) -> None:
+    """Send receipt ingestion confirmation email via Resend."""
+    if not settings.notifications_enabled or not settings.resend_api_key:
+        logger.debug("Notifications disabled — skipping email send")
+        return
+
+    resend.api_key = settings.resend_api_key
+    store_name_safe = html.escape(store_name)
+    purchase_date_safe = html.escape(purchase_date)
+    try:
+        await asyncio.to_thread(
+            resend.Emails.send,
+            {
+                "from": settings.notification_email_from,
+                "to": [user_email],
+                "subject": f"Receipt processed: {store_name} - ${total:.2f}",
+                "html": (
+                    f"<p>Your receipt from <strong>{store_name_safe}</strong> on "
+                    f"{purchase_date_safe} has been processed.</p>"
+                    f"<p>{item_count} items, total: ${total:.2f}</p>"
+                ),
+            },
+        )
+        logger.info("Receipt notification sent to %s", user_email)
+    except Exception:
+        logger.exception("Failed to send receipt notification to %s", user_email)

receiptwitness/src/receiptwitness/parsers/email/__init__.py

@@ -0,0 +1 @@
+"""Email receipt parsers for retailer email receipts."""

receiptwitness/src/receiptwitness/parsers/email/base.py

@@ -0,0 +1,32 @@
+"""Base interface for email receipt parsers."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+
+@dataclass
+class EmailReceipt:
+    """Raw email data before parsing."""
+
+    sender: str
+    recipient: str
+    subject: str
+    body_html: str | None = None
+    body_plain: str | None = None
+    received_at: str | None = None
+    raw_headers: dict = field(default_factory=dict)
+
+
+class BaseEmailParser(ABC):
+    """All retailer email parsers implement this interface."""
+
+    @abstractmethod
+    def can_parse(self, email: EmailReceipt) -> bool:
+        """Return True if this parser handles this email."""
+        ...
+
+    @abstractmethod
+    def parse(self, email: EmailReceipt) -> dict:
+        """Parse email into a dict matching PurchaseCreate schema fields.
+        Must include an items list matching PurchaseItemCreate fields."""
+        ...

receiptwitness/src/receiptwitness/parsers/email/detector.py

@@ -0,0 +1,25 @@
+"""Detect which retailer sent a receipt email."""
+
+import re
+
+from receiptwitness.parsers.email.base import EmailReceipt
+
+RETAILER_PATTERNS: dict[str, list[str]] = {
+    "meijer": [r"@meijer\.com$", r"@email\.meijer\.com$"],
+    "kroger": [r"@kroger\.com$", r"@email\.kroger\.com$"],
+    "target": [r"@target\.com$", r"@email\.target\.com$"],
+}
+
+
+def detect_retailer(email: EmailReceipt) -> str | None:
+    """Return retailer slug or None if unrecognized."""
+    sender = email.sender.lower().strip()
+    # Extract email from "Name <email>" format
+    match = re.search(r"<([^>]+)>", sender)
+    if match:
+        sender = match.group(1)
+    for retailer, patterns in RETAILER_PATTERNS.items():
+        for pattern in patterns:
+            if re.search(pattern, sender):
+                return retailer
+    return None

receiptwitness/src/receiptwitness/parsers/email/kroger.py

@@ -0,0 +1,157 @@
+"""Kroger email receipt parser."""
+
+import logging
+import re
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+
+from bs4 import BeautifulSoup
+
+from receiptwitness.parsers.email.base import BaseEmailParser, EmailReceipt
+
+logger = logging.getLogger(__name__)
+
+
+def _to_decimal(value: str | float | int | None, default: Decimal = Decimal("0")) -> Decimal:
+    """Safely convert a value to Decimal."""
+    if value is None:
+        return default
+    try:
+        return Decimal(str(value).replace("$", "").replace(",", "").strip())
+    except (InvalidOperation, ValueError):
+        return default
+
+
+def _extract_total(body: str) -> Decimal:
+    """Extract the transaction total from email body."""
+    patterns = [
+        r"Total[:\s]*\$?([0-9,]+\.[0-9]{2})",
+        r"Amount[:\s]*\$?([0-9,]+\.[0-9]{2})",
+        r"Grand\s+Total[:\s]*\$?([0-9,]+\.[0-9]{2})",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, body, re.IGNORECASE)
+        if match:
+            return _to_decimal(match.group(1))
+    return Decimal("0")
+
+
+def _extract_receipt_id(body: str) -> str | None:
+    """Extract receipt ID / transaction ID from HTML body.
+
+    Strips HTML tags first so that whitespace between delimiters and values
+    (e.g. from ``</strong> KR-2026-0315-4829`` -> `` KR-2026-0315-4829``)
+    is normalized and the pattern can match cleanly.
+    """
+    stripped = re.sub(r"<[^>]+>", "", body)
+    patterns = [
+        r"Receipt\s*#[:\s]*([A-Z0-9-]+)",
+        r"Transaction\s*#[:\s]*([A-Z0-9-]+)",
+        r"Order\s*#[:\s]*([A-Z0-9-]+)",
+        r"Confirmation\s*#[:\s]*([A-Z0-9-]+)",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, stripped, re.IGNORECASE)
+        if match:
+            return match.group(1)
+    return None
+
+
+def _extract_date(body: str) -> str:
+    """Extract purchase date from email body. Returns ISO date string or empty string."""
+    patterns = [
+        r"(\d{1,2}[/-]\d{1,2}[/-]\d{2,4})",
+        r"([A-Z][a-z]{2}\s+\d{1,2},?\s+\d{4})",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, body)
+        if match:
+            raw = match.group(1)
+            try:
+                dt = datetime.strptime(raw.replace(",", ""), "%b %d %Y")
+                return dt.strftime("%Y-%m-%d")
+            except ValueError:
+                pass
+            try:
+                for fmt in ("%m/%d/%Y", "%m/%d/%y", "%d/%m/%Y", "%d/%m/%y"):
+                    try:
+                        dt = datetime.strptime(raw, fmt)
+                        return dt.strftime("%Y-%m-%d")
+                    except ValueError:
+                        continue
+            except Exception:
+                pass
+    return ""
+
+
+def _extract_items_soup(body: str) -> list[dict]:
+    """Extract line items from HTML email body using BeautifulSoup."""
+    items = []
+    try:
+        soup = BeautifulSoup(body, "html.parser")
+        text = soup.get_text(separator="\n", strip=True)
+        # Strip HTML tags from raw body to normalize whitespace
+        stripped = re.sub(r"<[^>]+>", " ", body)
+        stripped = re.sub(r"\s+", " ", stripped)
+        skip_prefixes = (
+            "Subtotal",
+            "Tax",
+            "Total",
+            "Kroger",
+            "Target",
+            "Date",
+            "Receipt",
+            "Order",
+            "Transaction",
+            "Confirmation",
+            "Thank",
+            "Questions",
+            "Keep",
+            "Receipt",
+        )
+        for line in text.split("\n"):
+            line = line.strip()
+            if not line or line.startswith(skip_prefixes):
+                continue
+            # Match lines like "Product Name $9.99"
+            match = re.match(r"(.+?)\s+\$([0-9]+\.[0-9]{2})\s*$", line)
+            if match:
+                name = match.group(1).strip()
+                price = _to_decimal(match.group(2))
+                if len(name) > 2 and price > 0:
+                    items.append(
+                        {
+                            "product_name_raw": name,
+                            "quantity": Decimal("1"),
+                            "unit_price": price,
+                            "extended_price": price,
+                        }
+                    )
+    except Exception:
+        pass
+    return items[:20]
+
+
+class KrogerEmailParser(BaseEmailParser):
+    """Parse Kroger email receipts (digital receipts via kroger.com)."""
+
+    KROGER_KEYWORDS = ("kroger", "kroger.com", "plus")
+
+    def can_parse(self, email: EmailReceipt) -> bool:
+        sender = (email.sender or "").lower()
+        body = (email.body_html or email.body_plain or "").lower()
+        return any(kw in sender or kw in body for kw in self.KROGER_KEYWORDS)
+
+    def parse(self, email: EmailReceipt) -> dict:
+        body = (email.body_html or email.body_plain or "").strip()
+        total = _extract_total(body)
+        receipt_id = _extract_receipt_id(body) or ""
+        purchase_date = _extract_date(body)
+        items = _extract_items_soup(body)
+
+        return {
+            "receipt_id": receipt_id,
+            "purchase_date": purchase_date,
+            "total": total,
+            "items": items,
+        }

receiptwitness/src/receiptwitness/parsers/email/meijer.py

@@ -0,0 +1,259 @@
+"""Parse Meijer digital receipt emails into structured purchase data."""
+
+import re
+from decimal import Decimal, InvalidOperation
+
+from bs4 import BeautifulSoup
+from bs4.element import Tag
+
+from receiptwitness.parsers.email.base import BaseEmailParser, EmailReceipt
+
+
+def _to_decimal(value, default: str = "0") -> Decimal:
+    """Safely convert a value to Decimal."""
+    if value is None:
+        return Decimal(default)
+    try:
+        return Decimal(str(value).replace("$", "").replace(",", "").strip())
+    except (InvalidOperation, ValueError, TypeError):
+        return Decimal(default)
+
+
+def _extract_receipt_id(soup: BeautifulSoup, subject: str | None) -> str | None:
+    """Extract receipt/transaction ID from subject or body."""
+    if subject:
+        match = re.search(r"TXN[-\s]\d{4}[-\s]\d{4}[-\s]\d+", subject)
+        if match:
+            return match.group(0).replace(" ", "-")
+    # Fallback: look in body
+    text = soup.get_text()
+    match = re.search(r"TXN[-\s]\d{4}[-\s]\d{4}[-\s]\d+", text)
+    if match:
+        return match.group(0).replace(" ", "-")
+    return None
+
+
+def _extract_purchase_date(soup: BeautifulSoup, subject: str | None) -> str | None:
+    """Extract purchase date from subject or body."""
+    text = soup.get_text()
+
+    # Try ISO format first: YYYY-MM-DD
+    match = re.search(r"(\d{4})-(\d{2})-(\d{2})", text)
+    if match:
+        return f"{match.group(1)}-{match.group(2)}-{match.group(3)}"
+
+    # Try written format: March 15, 2026
+    match = re.search(r"([A-Za-z]+)\s+(\d{1,2}),?\s+(\d{4})", text)
+    if match:
+        month_str = match.group(1).lower()
+        day = match.group(2)
+        year = match.group(3)
+        month_map = {
+            "january": "01",
+            "february": "02",
+            "march": "03",
+            "april": "04",
+            "may": "05",
+            "june": "06",
+            "july": "07",
+            "august": "08",
+            "september": "09",
+            "october": "10",
+            "november": "11",
+            "december": "12",
+        }
+        month = month_map.get(month_str)
+        if month:
+            return f"{year}-{month}-{day.zfill(2)}"
+
+    # MM/DD/YYYY
+    match = re.search(r"(\d{1,2})/(\d{1,2})/(\d{4})", text)
+    if match:
+        return f"{match.group(3)}-{match.group(1).zfill(2)}-{match.group(2).zfill(2)}"
+
+    return None
+
+
+def _extract_store_info(soup: BeautifulSoup) -> dict:
+    """Extract store name and number from the email body."""
+    store_info: dict = {}
+
+    # Look for store number in header
+    store_num_match = re.search(r"Meijer\s+Store\s+#?(\d+)", soup.get_text(), re.IGNORECASE)
+    if store_num_match:
+        store_info["store_number"] = store_num_match.group(1)
+
+    return store_info
+
+
+def _extract_items(table: Tag | None) -> list[dict]:
+    """Extract line items from the items table."""
+    items: list[dict] = []
+    if not table:
+        return items
+
+    rows = table.find_all("tr")
+    for row in rows:
+        cells = row.find_all("td")
+        if len(cells) < 3:
+            continue
+
+        name_cell = cells[0].get_text(strip=True)
+        qty_cell = cells[1].get_text(strip=True)
+        price_cell = cells[2].get_text(strip=True)
+
+        if not name_cell or name_cell.lower() in ("item", "description"):
+            continue
+
+        # Skip subtotal/tax/total/savings rows
+        if any(
+            label in name_cell.lower()
+            for label in ("subtotal", "tax", "total", "savings", "grand total")
+        ):
+            continue
+
+        try:
+            quantity = Decimal(qty_cell)
+        except (InvalidOperation, ValueError, TypeError):
+            quantity = Decimal("1")
+
+        price_str = price_cell.replace("$", "").replace(",", "").strip()
+        try:
+            unit_price = Decimal(price_str)
+        except (InvalidOperation, ValueError, TypeError):
+            unit_price = Decimal("0")
+
+        extended_price = unit_price  # Default to unit price; no qty column in fixture
+
+        items.append(
+            {
+                "product_name_raw": name_cell,
+                "quantity": quantity,
+                "unit_price": unit_price,
+                "extended_price": extended_price,
+            }
+        )
+
+    return items
+
+
+def _extract_totals_plain(text: str) -> dict:
+    """Extract totals from plain text (no HTML)."""
+    totals: dict = {
+        "subtotal": None,
+        "tax": None,
+        "total": None,
+        "savings_total": None,
+    }
+
+    match = re.search(r"\bSubtotal\b[:\s$]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+    if match:
+        totals["subtotal"] = _to_decimal(match.group(1))
+
+    match = re.search(r"\bTax\b[:\s$]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+    if match:
+        totals["tax"] = _to_decimal(match.group(1))
+
+    grand_total_match = re.search(r"Grand\s+Total\b[:\s$]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+    if grand_total_match:
+        totals["total"] = _to_decimal(grand_total_match.group(1))
+
+    savings_match = re.search(r"\bSavings\b[:\s$\-]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+    if savings_match:
+        totals["savings_total"] = _to_decimal(savings_match.group(1))
+
+    if totals["total"] is None:
+        total_match = re.search(r"\bTotal\b[:\s$]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+        if total_match:
+            totals["total"] = _to_decimal(total_match.group(1))
+
+    return totals
+
+
+def _extract_totals(soup: BeautifulSoup) -> dict:
+    """Extract subtotal, tax, total, and savings from the totals section."""
+    text = soup.get_text()
+
+    totals: dict = {
+        "subtotal": None,
+        "tax": None,
+        "total": None,
+        "savings_total": None,
+    }
+
+    # Subtotal — use word boundary to avoid matching "Subtotal" with "Total"
+    match = re.search(r"\bSubtotal\b[:\s$]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+    if match:
+        totals["subtotal"] = _to_decimal(match.group(1))
+
+    # Tax
+    match = re.search(r"\bTax\b[:\s$]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+    if match:
+        totals["tax"] = _to_decimal(match.group(1))
+
+    # Grand Total (before plain "Total" to avoid matching "Subtotal")
+    grand_total_match = re.search(r"Grand\s+Total\b[:\s$]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+    if grand_total_match:
+        totals["total"] = _to_decimal(grand_total_match.group(1))
+
+    # Savings — allow any combination of whitespace/$- around the number
+    savings_match = re.search(r"\bSavings\b[:\s$\-]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+    if savings_match:
+        totals["savings_total"] = _to_decimal(savings_match.group(1))
+
+    # Plain "Total" only if Grand Total wasn't found
+    if totals["total"] is None:
+        total_match = re.search(r"\bTotal\b[:\s$]*([0-9,]+\.?\d*)", text, re.IGNORECASE)
+        if total_match:
+            totals["total"] = _to_decimal(total_match.group(1))
+
+    return totals
+
+
+class MeijerEmailParser(BaseEmailParser):
+    """Parse Meijer digital receipt emails forwarded by users."""
+
+    def can_parse(self, email: EmailReceipt) -> bool:
+        sender = email.sender.lower().strip()
+        # Extract email from "Name <email>" format
+        match = re.search(r"<([^>]+)>", sender)
+        if match:
+            sender = match.group(1)
+        return "meijer" in sender
+
+    def parse(self, email: EmailReceipt) -> dict:
+        body_html = email.body_html
+        body_plain = email.body_plain or ""
+        body = body_html or body_plain
+        soup = BeautifulSoup(body, "html.parser")
+
+        receipt_id = _extract_receipt_id(soup, email.subject)
+        purchase_date = _extract_purchase_date(soup, email.subject)
+        _ = _extract_store_info(soup)
+
+        # Find the items table — look for one with Item/Qty/Price headers
+        table = None
+        for tbl in soup.find_all("table"):
+            headers = tbl.find_all("th")
+            header_texts = [h.get_text(strip=True).lower() for h in headers]
+            if any("item" in h or "qty" in h or "price" in h for h in header_texts):
+                table = tbl
+                break
+
+        items = _extract_items(table)
+
+        # Extract totals from HTML; fall back to plain text if no HTML
+        if body_html:
+            totals = _extract_totals(soup)
+        else:
+            totals = _extract_totals_plain(body_plain)
+
+        return {
+            "receipt_id": receipt_id or "",
+            "purchase_date": purchase_date or "",
+            "total": totals["total"] or Decimal("0"),
+            "subtotal": totals["subtotal"],
+            "tax": totals["tax"],
+            "savings_total": totals["savings_total"],
+            "items": items,
+        }

receiptwitness/src/receiptwitness/parsers/email/target.py

@@ -0,0 +1,156 @@
+"""Target email receipt parser."""
+
+import logging
+import re
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+
+from bs4 import BeautifulSoup
+
+from receiptwitness.parsers.email.base import BaseEmailParser, EmailReceipt
+
+logger = logging.getLogger(__name__)
+
+
+def _to_decimal(value: str | float | int | None, default: Decimal = Decimal("0")) -> Decimal:
+    """Safely convert a value to Decimal."""
+    if value is None:
+        return default
+    try:
+        return Decimal(str(value).replace("$", "").replace(",", "").strip())
+    except (InvalidOperation, ValueError):
+        return default
+
+
+def _extract_total(body: str) -> Decimal:
+    """Extract the transaction total from email body."""
+    patterns = [
+        r"Total[:\s]*\$?([0-9,]+\.[0-9]{2})",
+        r"Amount[:\s]*\$?([0-9,]+\.[0-9]{2})",
+        r"Grand\s+Total[:\s]*\$?([0-9,]+\.[0-9]{2})",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, body, re.IGNORECASE)
+        if match:
+            return _to_decimal(match.group(1))
+    return Decimal("0")
+
+
+def _extract_receipt_id(body: str) -> str | None:
+    """Extract receipt ID / transaction ID from HTML body.
+
+    Strips HTML tags first so that whitespace between delimiters and values
+    (e.g. from ``</strong> TGT-2026-0318-9124`` -> `` TGT-2026-0318-9124``)
+    is normalized and the pattern can match cleanly.
+    """
+    stripped = re.sub(r"<[^>]+>", "", body)
+    patterns = [
+        r"Receipt\s*#[:\s]*([A-Z0-9-]+)",
+        r"Order\s*#[:\s]*([A-Z0-9-]+)",
+        r"Confirmation\s*#[:\s]*([A-Z0-9-]+)",
+        r"Target\s+Order\s*#[:\s]*([A-Z0-9-]+)",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, stripped, re.IGNORECASE)
+        if match:
+            return match.group(1)
+    return None
+
+
+def _extract_date(body: str) -> str:
+    """Extract purchase date from email body. Returns ISO date string or empty string."""
+    patterns = [
+        r"(\d{1,2}[/-]\d{1,2}[/-]\d{2,4})",
+        r"([A-Z][a-z]{2}\s+\d{1,2},?\s+\d{4})",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, body)
+        if match:
+            raw = match.group(1)
+            try:
+                dt = datetime.strptime(raw.replace(",", ""), "%b %d %Y")
+                return dt.strftime("%Y-%m-%d")
+            except ValueError:
+                pass
+            try:
+                for fmt in ("%m/%d/%Y", "%m/%d/%y", "%d/%m/%Y", "%d/%m/%y"):
+                    try:
+                        dt = datetime.strptime(raw, fmt)
+                        return dt.strftime("%Y-%m-%d")
+                    except ValueError:
+                        continue
+            except Exception:
+                pass
+    return ""
+
+
+def _extract_items_soup(body: str) -> list[dict]:
+    """Extract line items from HTML email body using BeautifulSoup."""
+    items = []
+    try:
+        soup = BeautifulSoup(body, "html.parser")
+        text = soup.get_text(separator="\n", strip=True)
+        for line in text.split("\n"):
+            line = line.strip()
+            if not line or line.startswith(
+                (
+                    "Subtotal",
+                    "Tax",
+                    "Total",
+                    "Target",
+                    "Kroger",
+                    "Date",
+                    "Receipt",
+                    "Order",
+                    "Transaction",
+                    "Confirmation",
+                    "Thank",
+                    "Questions",
+                    "Keep",
+                    "Receipt",
+                    "Store",
+                )
+            ):
+                continue
+            # Match lines like "Product Name $9.99"
+            match = re.match(r"(.+?)\s+\$([0-9]+\.[0-9]{2})\s*$", line)
+            if match:
+                name = match.group(1).strip()
+                price = _to_decimal(match.group(2))
+                if len(name) > 2 and price > 0:
+                    items.append(
+                        {
+                            "product_name_raw": name,
+                            "quantity": Decimal("1"),
+                            "unit_price": price,
+                            "extended_price": price,
+                        }
+                    )
+    except Exception:
+        pass
+    return items[:20]
+
+
+class TargetEmailParser(BaseEmailParser):
+    """Parse Target email receipts (Circle order confirmations)."""
+
+    TARGET_KEYWORDS = ("target.com", "targetnow", "circle", "target")
+
+    def can_parse(self, email: EmailReceipt) -> bool:
+        sender = (email.sender or "").lower()
+        body = (email.body_html or email.body_plain or "").lower()
+        return any(kw in sender or kw in body for kw in self.TARGET_KEYWORDS)
+
+    def parse(self, email: EmailReceipt) -> dict:
+        body = (email.body_html or email.body_plain or "").strip()
+        total = _extract_total(body)
+        receipt_id = _extract_receipt_id(body) or ""
+        purchase_date = _extract_date(body)
+        items = _extract_items_soup(body)
+
+        return {
+            "receipt_id": receipt_id,
+            "purchase_date": purchase_date,
+            "total": total,
+            "items": items,
+        }

receiptwitness/src/receiptwitness/queue/__init__.py

@@ -0,0 +1 @@
+"""DragonflyDB Streams queue for email receipt processing."""

receiptwitness/src/receiptwitness/queue/email.py

@@ -0,0 +1,77 @@
+"""DragonflyDB Streams queue for email receipt processing."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict, dataclass
+from typing import cast
+
+import redis.asyncio as aioredis
+
+from receiptwitness.config import settings
+
+logger = logging.getLogger(__name__)
+
+STREAM_KEY = "email:receipts"
+CONSUMER_GROUP = "email-workers"
+
+
+@dataclass
+class EmailJob:
+    """Payload for an email receipt processing job."""
+
+    user_id: str
+    sender: str
+    recipient: str
+    subject: str
+    body_html: str | None
+    body_plain: str | None
+    received_at: str
+    message_id: str  # from email provider, for dedup
+
+
+async def get_redis() -> aioredis.Redis:
+    """Get async Redis/DragonflyDB client."""
+    return cast(aioredis.Redis, aioredis.from_url(settings.redis_url, decode_responses=True))
+
+
+async def ensure_consumer_group(client: aioredis.Redis) -> None:
+    """Create consumer group if it does not exist."""
+    try:
+        await client.xgroup_create(STREAM_KEY, CONSUMER_GROUP, id="0", mkstream=True)
+    except aioredis.ResponseError as e:
+        if "BUSYGROUP" not in str(e):
+            raise
+
+
+async def enqueue_email(client: aioredis.Redis, job: EmailJob) -> str:
+    """Add email job to the stream. Returns the stream message ID."""
+    payload: dict[str, str | bytes | int | float] = {"data": json.dumps(asdict(job))}
+    msg_id: str = cast(str, await client.xadd(STREAM_KEY, payload))  # type: ignore[arg-type]  # redis-py StreamCommands.xadd expects broader FieldT union; runtime behavior is correct
+    logger.info("Enqueued email job %s for user %s", msg_id, job.user_id)
+    return msg_id
+
+
+async def consume_emails(
+    client: aioredis.Redis,
+    consumer_name: str,
+    count: int = 1,
+    block_ms: int = 5000,
+) -> list[tuple[str, EmailJob]]:
+    """Read pending messages from the stream. Returns list of (msg_id, EmailJob)."""
+    await ensure_consumer_group(client)
+    messages = await client.xreadgroup(
+        CONSUMER_GROUP, consumer_name, {STREAM_KEY: ">"}, count=count, block=block_ms
+    )
+    results = []
+    for _stream, entries in messages:
+        for msg_id, fields in entries:
+            job = EmailJob(**json.loads(fields["data"]))
+            results.append((msg_id, job))
+    return results
+
+
+async def ack_email(client: aioredis.Redis, msg_id: str) -> None:
+    """Acknowledge a processed message."""
+    await client.xack(STREAM_KEY, CONSUMER_GROUP, msg_id)

receiptwitness/src/receiptwitness/worker/__init__.py

@@ -0,0 +1 @@
+"""Async email receipt worker consuming from DragonflyDB Streams."""

receiptwitness/src/receiptwitness/worker/email_worker.py

@@ -0,0 +1,104 @@
+"""Async worker that consumes email receipt jobs from DragonflyDB Streams."""
+
+import asyncio
+import logging
+
+from cartsnitch_common.database import get_async_session_factory
+from cartsnitch_common.models.user import User
+from sqlalchemy import select
+
+from receiptwitness.config import settings
+from receiptwitness.events import publish_receipt_ingested
+from receiptwitness.parsers.email.base import BaseEmailParser, EmailReceipt
+from receiptwitness.parsers.email.detector import detect_retailer
+from receiptwitness.parsers.email.kroger import KrogerEmailParser
+from receiptwitness.parsers.email.meijer import MeijerEmailParser
+from receiptwitness.parsers.email.target import TargetEmailParser
+from receiptwitness.queue.email import ack_email, consume_emails, get_redis
+
+logger = logging.getLogger(__name__)
+
+CONSUMER_NAME = "worker-1"
+
+# Registry of available email parsers
+PARSERS: dict[str, BaseEmailParser] = {
+    "meijer": MeijerEmailParser(),
+    "kroger": KrogerEmailParser(),
+    "target": TargetEmailParser(),
+}
+
+
+async def resolve_user(token: str) -> str | None:
+    """Look up user_id from email_inbound_token."""
+    session_factory = get_async_session_factory(settings.database_url)
+    async with session_factory() as session:
+        result = await session.execute(select(User.id).where(User.email_inbound_token == token))
+        row = result.scalar_one_or_none()
+        return str(row) if row else None
+
+
+async def process_job(msg_id: str, job) -> bool:
+    """Process a single email job. Returns True on success."""
+    # 1. Resolve user from token
+    user_id = await resolve_user(job.user_id)  # user_id field holds token
+    if not user_id:
+        logger.warning("Unknown token %s, dropping message %s", job.user_id, msg_id)
+        return True  # ack to avoid infinite retry
+
+    # 2. Build EmailReceipt
+    email = EmailReceipt(
+        sender=job.sender,
+        recipient=job.recipient,
+        subject=job.subject,
+        body_html=job.body_html,
+        body_plain=job.body_plain,
+        received_at=job.received_at,
+    )
+
+    # 3. Detect retailer
+    retailer = detect_retailer(email)
+    if not retailer or retailer not in PARSERS:
+        logger.warning(
+            "Unrecognized retailer from %s, archiving msg %s",
+            job.sender,
+            msg_id,
+        )
+        return True  # ack — no parser available
+
+    # 4. Parse
+    parser = PARSERS[retailer]
+    parsed = parser.parse(email)
+
+    # 5. Publish event
+    await publish_receipt_ingested(
+        user_id=user_id,
+        store_slug=retailer,
+        purchase_id=parsed.get("receipt_id", msg_id),
+        purchase_date=parsed.get("purchase_date", ""),
+        item_count=len(parsed.get("items", [])),
+        total=parsed.get("total", 0),
+    )
+    return True
+
+
+async def run_worker() -> None:
+    """Main worker loop — consume and process email jobs."""
+    client = await get_redis()
+    logger.info("Email worker started, consuming from email:receipts")
+    while True:
+        try:
+            jobs = await consume_emails(client, CONSUMER_NAME, count=5, block_ms=5000)
+            for msg_id, job in jobs:
+                try:
+                    success = await process_job(msg_id, job)
+                    if success:
+                        await ack_email(client, msg_id)
+                except Exception:
+                    logger.exception("Failed to process email job %s", msg_id)
+        except Exception:
+            logger.exception("Worker loop error, retrying in 5s")
+            await asyncio.sleep(5)
+
+
+if __name__ == "__main__":
+    asyncio.run(run_worker())