Add shopper accounts, reviews, tracking, and seed_demo (#9)

Closes #9. Shop-gated buyer accounts, purchase reviews, Stripe customer ids, shipment tracking, slim public contact form, and a template-neutral seed_demo command.

site/shipping/hooks.py

@@ -1,5 +1,6 @@
 from core.registry import (
     register_dashboard_collector,
+    register_dispatcher,
     register_feature,
     register_portal_nav,
 )
@@ -15,6 +16,7 @@ def register() -> None:
         order=50,
     )
     register_dashboard_collector(_dashboard)
+    register_dispatcher(_sync_tracking)
 
 
 def _dashboard(request) -> dict:
@@ -29,3 +31,9 @@ def _dashboard(request) -> dict:
         .exclude(pk__in=labeled)
         .count()
     }
+
+
+def _sync_tracking() -> int:
+    from shipping.services import sync_open_tracking
+
+    return sync_open_tracking()

site/shipping/migrations/0002_shipment_tracking.py

@@ -0,0 +1,54 @@
+# Generated by Django 6.1
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("shipping", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="shipment",
+            name="last_tracked_at",
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name="shipment",
+            name="tracker_id",
+            field=models.CharField(blank=True, max_length=255),
+        ),
+        migrations.AddField(
+            model_name="shipment",
+            name="tracking_events",
+            field=models.JSONField(blank=True, default=list),
+        ),
+        migrations.AddField(
+            model_name="shipment",
+            name="tracking_status",
+            field=models.CharField(
+                blank=True,
+                choices=[
+                    ("unknown", "Unknown"),
+                    ("pre_transit", "Pre-transit"),
+                    ("in_transit", "In transit"),
+                    ("out_for_delivery", "Out for delivery"),
+                    ("delivered", "Delivered"),
+                    ("available_for_pickup", "Available for pickup"),
+                    ("return_to_sender", "Return to sender"),
+                    ("failure", "Exception"),
+                    ("cancelled", "Cancelled"),
+                    ("error", "Error"),
+                ],
+                default="unknown",
+                max_length=32,
+            ),
+        ),
+        migrations.AddField(
+            model_name="shipment",
+            name="tracking_url",
+            field=models.URLField(blank=True),
+        ),
+    ]

site/shipping/models.py

@@ -11,6 +11,18 @@ class Shipment(UUIDPrimaryKeyModel, TimeStampedModel):
         LABELED = "labeled", "Labeled"
         VOID = "void", "Void"
 
+    class TrackingStatus(models.TextChoices):
+        UNKNOWN = "unknown", "Unknown"
+        PRE_TRANSIT = "pre_transit", "Pre-transit"
+        IN_TRANSIT = "in_transit", "In transit"
+        OUT_FOR_DELIVERY = "out_for_delivery", "Out for delivery"
+        DELIVERED = "delivered", "Delivered"
+        AVAILABLE_FOR_PICKUP = "available_for_pickup", "Available for pickup"
+        RETURN_TO_SENDER = "return_to_sender", "Return to sender"
+        FAILURE = "failure", "Exception"
+        CANCELLED = "cancelled", "Cancelled"
+        ERROR = "error", "Error"
+
     order = models.ForeignKey(Order, on_delete=models.PROTECT, related_name="shipments")
     status = models.CharField(
         max_length=16, choices=Status.choices, default=Status.DRAFT
@@ -18,6 +30,16 @@ class Shipment(UUIDPrimaryKeyModel, TimeStampedModel):
     carrier = models.CharField(max_length=32, blank=True)
     service = models.CharField(max_length=64, blank=True)
     tracking_number = models.CharField(max_length=64, blank=True)
+    tracking_status = models.CharField(
+        max_length=32,
+        choices=TrackingStatus.choices,
+        default=TrackingStatus.UNKNOWN,
+        blank=True,
+    )
+    tracking_url = models.URLField(blank=True)
+    tracker_id = models.CharField(max_length=255, blank=True)
+    tracking_events = models.JSONField(default=list, blank=True)
+    last_tracked_at = models.DateTimeField(null=True, blank=True)
     label_url = models.URLField(blank=True)
     rate_amount = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True)
     currency = models.CharField(max_length=8, default="usd")

site/shipping/services.py

@@ -7,8 +7,11 @@ import io
 import logging
 from decimal import Decimal
 
+from urllib.parse import quote
+
 import requests
 from django.conf import settings
+from django.utils import timezone
 
 from shipping.models import Shipment
 from shop.models import Order
@@ -135,6 +138,10 @@ def buy_label(shipment: Shipment, *, rate_id: str = "") -> Shipment:
             "updated_at",
         ]
     )
+    try:
+        refresh_tracking(shipment)
+    except Exception:
+        logger.exception("tracking refresh failed after label buy for %s", shipment.pk)
     return shipment
 
 
@@ -182,3 +189,169 @@ def pirate_ship_csv(orders=None) -> str:
             ]
         )
     return buffer.getvalue()
+
+
+def public_tracking_url(carrier: str, tracking_number: str) -> str:
+    code = quote((tracking_number or "").strip())
+    if not code:
+        return ""
+    name = (carrier or "").upper()
+    if "USPS" in name:
+        return f"https://tools.usps.com/go/TrackConfirmAction?tLabels={code}"
+    if "UPS" in name:
+        return f"https://www.ups.com/track?tracknum={code}"
+    if "FEDEX" in name or "FDX" in name:
+        return f"https://www.fedex.com/fedextrack/?trknbr={code}"
+    if "DHL" in name:
+        return f"https://www.dhl.com/en/express/tracking.html?AWB={code}"
+    return f"https://www.google.com/search?q={quote((tracking_number or '') + ' tracking')}"
+
+
+def _normalize_tracking_status(raw: str) -> str:
+    value = (raw or "").strip().lower().replace(" ", "_")
+    aliases = {
+        "pretransit": Shipment.TrackingStatus.PRE_TRANSIT,
+        "pre_transit": Shipment.TrackingStatus.PRE_TRANSIT,
+        "in_transit": Shipment.TrackingStatus.IN_TRANSIT,
+        "out_for_delivery": Shipment.TrackingStatus.OUT_FOR_DELIVERY,
+        "delivered": Shipment.TrackingStatus.DELIVERED,
+        "available_for_pickup": Shipment.TrackingStatus.AVAILABLE_FOR_PICKUP,
+        "return_to_sender": Shipment.TrackingStatus.RETURN_TO_SENDER,
+        "failure": Shipment.TrackingStatus.FAILURE,
+        "cancelled": Shipment.TrackingStatus.CANCELLED,
+        "canceled": Shipment.TrackingStatus.CANCELLED,
+        "error": Shipment.TrackingStatus.ERROR,
+        "unknown": Shipment.TrackingStatus.UNKNOWN,
+    }
+    return aliases.get(value, Shipment.TrackingStatus.UNKNOWN)
+
+
+def apply_tracker_payload(shipment: Shipment, payload: dict) -> Shipment:
+    """Apply EasyPost tracker (or compatible) JSON onto a shipment."""
+    data = payload or {}
+    tracking = (data.get("tracking_code") or data.get("tracking_number") or "").strip()
+    if tracking:
+        shipment.tracking_number = tracking
+    tracker_id = (data.get("id") or "").strip()
+    if tracker_id.startswith("trk_"):
+        shipment.tracker_id = tracker_id
+    carrier = (data.get("carrier") or "").strip()
+    if carrier and not shipment.carrier:
+        shipment.carrier = carrier
+    shipment.tracking_status = _normalize_tracking_status(data.get("status") or "")
+    public_url = (data.get("public_url") or "").strip()
+    shipment.tracking_url = public_url or public_tracking_url(
+        shipment.carrier, shipment.tracking_number
+    )
+    events = []
+    for item in data.get("tracking_details") or []:
+        loc = item.get("tracking_location") or {}
+        place = " ".join(
+            part
+            for part in [loc.get("city") or "", loc.get("state") or ""]
+            if part
+        ).strip()
+        events.append(
+            {
+                "status": item.get("status") or "",
+                "message": item.get("message") or "",
+                "datetime": item.get("datetime") or "",
+                "location": place,
+            }
+        )
+    if events:
+        shipment.tracking_events = events
+    shipment.last_tracked_at = timezone.now()
+    shipment.save(
+        update_fields=[
+            "tracking_number",
+            "tracker_id",
+            "carrier",
+            "tracking_status",
+            "tracking_url",
+            "tracking_events",
+            "last_tracked_at",
+            "updated_at",
+        ]
+    )
+    return shipment
+
+
+def refresh_tracking(shipment: Shipment) -> Shipment:
+    """Pull latest scan events from EasyPost, or stub status without an API key.
+
+    Works for EasyPost-bought labels and for tracking numbers pasted from
+    Pirate Ship / the carrier — EasyPost's tracker API looks up
+    USPS, UPS, FedEx, and DHL by number.
+    """
+    tracking = (shipment.tracking_number or "").strip()
+    if not tracking:
+        return shipment
+    key = _easypost_key()
+    if not key:
+        if not shipment.tracking_status or shipment.tracking_status == Shipment.TrackingStatus.UNKNOWN:
+            shipment.tracking_status = Shipment.TrackingStatus.PRE_TRANSIT
+        shipment.tracking_url = shipment.tracking_url or public_tracking_url(
+            shipment.carrier, tracking
+        )
+        shipment.last_tracked_at = timezone.now()
+        shipment.save(
+            update_fields=[
+                "tracking_status",
+                "tracking_url",
+                "last_tracked_at",
+                "updated_at",
+            ]
+        )
+        return shipment
+
+    payload = {"tracker": {"tracking_code": tracking}}
+    if shipment.carrier:
+        payload["tracker"]["carrier"] = shipment.carrier
+    response = requests.post(
+        "https://api.easypost.com/v2/trackers",
+        auth=(key, ""),
+        json=payload,
+        timeout=20,
+    )
+    response.raise_for_status()
+    return apply_tracker_payload(shipment, response.json())
+
+
+def attach_tracking(
+    shipment: Shipment, *, tracking_number: str, carrier: str = ""
+) -> Shipment:
+    tracking_number = (tracking_number or "").strip()
+    if not tracking_number:
+        raise ShippingError("Tracking number is required.")
+    shipment.tracking_number = tracking_number
+    if carrier:
+        shipment.carrier = carrier.strip()
+    if shipment.status != Shipment.Status.LABELED:
+        shipment.status = Shipment.Status.LABELED
+    shipment.save(
+        update_fields=["tracking_number", "carrier", "status", "updated_at"]
+    )
+    return refresh_tracking(shipment)
+
+
+def sync_open_tracking() -> int:
+    """Refresh labeled, not-yet-delivered shipments (dispatch_due)."""
+    done = 0
+    qs = (
+        Shipment.objects.filter(status=Shipment.Status.LABELED)
+        .exclude(tracking_number="")
+        .exclude(
+            tracking_status__in=[
+                Shipment.TrackingStatus.DELIVERED,
+                Shipment.TrackingStatus.CANCELLED,
+            ]
+        )[:50]
+    )
+    for shipment in qs:
+        try:
+            refresh_tracking(shipment)
+            done += 1
+        except Exception:
+            logger.exception("tracking sync failed for %s", shipment.pk)
+    return done

site/shipping/templates/shipping/detail.html

@@ -3,8 +3,52 @@
 {% block topbar_title %}{{ shipment.order.number }}{% endblock %}
 {% block portal_content %}
 <p>{{ shipment.order.email }} · {{ shipment.get_status_display }}</p>
-{% if shipment.tracking_number %}<p>Tracking: {{ shipment.tracking_number }}</p>{% endif %}
+{% if shipment.tracking_number %}
+<p>
+  Tracking: {{ shipment.tracking_number }}
+  {% if shipment.tracking_status %} · {{ shipment.get_tracking_status_display }}{% endif %}
+</p>
+{% if shipment.tracking_url %}<p><a href="{{ shipment.tracking_url }}" target="_blank" rel="noopener">Track package</a></p>{% endif %}
+<form method="post" action="{% url 'shipping:shipment_refresh_tracking' shipment.pk %}">
+  {% csrf_token %}
+  <button class="btn btn-ghost btn-sm" type="submit">Refresh tracking</button>
+</form>
+{% endif %}
 {% if shipment.label_url %}<p><a href="{{ shipment.label_url }}">Download label</a></p>{% endif %}
+
+<h3>Add tracking</h3>
+<p class="hint-block">Paste a number from Pirate Ship or the carrier. EasyPost looks up scan events when an API key is set.</p>
+<form method="post" action="{% url 'shipping:shipment_attach_tracking' shipment.pk %}">
+  {% csrf_token %}
+  <div class="form-grid">
+    <div class="field">
+      <label for="id_tracking_number">Tracking number</label>
+      <input id="id_tracking_number" name="tracking_number" value="{{ shipment.tracking_number }}" required>
+    </div>
+    <div class="field">
+      <label for="id_carrier">Carrier</label>
+      <input id="id_carrier" name="carrier" value="{{ shipment.carrier }}" placeholder="USPS, UPS, FedEx">
+    </div>
+  </div>
+  <button class="btn btn-primary" type="submit">Save tracking</button>
+</form>
+
+{% if shipment.tracking_events %}
+<h3>Scan history</h3>
+<table class="table">
+  <thead><tr><th>When</th><th>Status</th><th>Detail</th></tr></thead>
+  <tbody>
+    {% for event in shipment.tracking_events %}
+    <tr>
+      <td>{{ event.datetime }}</td>
+      <td>{{ event.status }}</td>
+      <td>{{ event.message }}{% if event.location %} · {{ event.location }}{% endif %}</td>
+    </tr>
+    {% endfor %}
+  </tbody>
+</table>
+{% endif %}
+
 {% if shipment.status != 'labeled' %}
 <form method="post" action="{% url 'shipping:shipment_buy' shipment.pk %}">
   {% csrf_token %}

site/shipping/tests.py

@@ -1,4 +1,5 @@
 from decimal import Decimal
+import json
 
 from django.contrib.auth import get_user_model
 from django.test import Client, TestCase
@@ -49,11 +50,65 @@ class ShippingServiceTests(TestCase):
         buy_label(shipment)
         self.assertNotIn(self.order.number, pirate_ship_csv())
 
+    def test_stub_buy_sets_pre_transit_tracking(self):
+        shipment = create_shipment_for_order(self.order)
+        quote_rates(shipment)
+        buy_label(shipment)
+        shipment.refresh_from_db()
+        self.assertTrue(shipment.tracking_number)
+        self.assertEqual(shipment.tracking_status, Shipment.TrackingStatus.PRE_TRANSIT)
+        self.assertTrue(shipment.tracking_url)
+
+    def test_attach_tracking_from_pirate_ship(self):
+        from shipping.services import attach_tracking
+
+        shipment = create_shipment_for_order(self.order)
+        attach_tracking(shipment, tracking_number="9400111899223197428490", carrier="USPS")
+        shipment.refresh_from_db()
+        self.assertEqual(shipment.status, Shipment.Status.LABELED)
+        self.assertEqual(shipment.tracking_status, Shipment.TrackingStatus.PRE_TRANSIT)
+        self.assertIn("usps.com", shipment.tracking_url.lower())
+
+    def test_easypost_webhook_updates_status(self):
+        shipment = create_shipment_for_order(self.order)
+        shipment.tracking_number = "EZ1000000001"
+        shipment.status = Shipment.Status.LABELED
+        shipment.save()
+        payload = {
+            "description": "tracker.updated",
+            "result": {
+                "id": "trk_test",
+                "tracking_code": "EZ1000000001",
+                "status": "in_transit",
+                "public_url": "https://track.easypost.com/djE0",
+                "tracking_details": [
+                    {
+                        "status": "in_transit",
+                        "message": "Departed facility",
+                        "datetime": "2026-09-07T12:00:00Z",
+                        "tracking_location": {"city": "Chicago", "state": "IL"},
+                    }
+                ],
+            },
+        }
+        response = Client().post(
+            reverse("shipping:easypost_webhook"),
+            data=json.dumps(payload),
+            content_type="application/json",
+        )
+        self.assertEqual(response.status_code, 200)
+        shipment.refresh_from_db()
+        self.assertEqual(shipment.tracking_status, Shipment.TrackingStatus.IN_TRANSIT)
+        self.assertEqual(shipment.tracker_id, "trk_test")
+        self.assertEqual(shipment.tracking_events[0]["location"], "Chicago IL")
+
 
 class ShippingPortalTests(TestCase):
     def setUp(self):
         User = get_user_model()
-        self.user = User.objects.create_user("shipper", password="test-pass-123")
+        self.user = User.objects.create_user(
+            "shipper", password="test-pass-123", is_staff=True
+        )
         self.client = Client()
         self.client.login(username="shipper", password="test-pass-123")
         self.order = Order.objects.create(

site/shipping/urls.py

@@ -8,6 +8,17 @@ urlpatterns = [
     path("", views.shipment_list, name="shipment_list"),
     path("new/", views.shipment_create, name="shipment_create"),
     path("export/pirate-ship.csv", views.pirate_ship_export, name="pirate_ship_export"),
+    path("webhooks/easypost/", views.easypost_webhook, name="easypost_webhook"),
     path("<uuid:pk>/", views.shipment_detail, name="shipment_detail"),
     path("<uuid:pk>/buy/", views.shipment_buy, name="shipment_buy"),
+    path(
+        "<uuid:pk>/tracking/",
+        views.shipment_attach_tracking,
+        name="shipment_attach_tracking",
+    ),
+    path(
+        "<uuid:pk>/tracking/refresh/",
+        views.shipment_refresh_tracking,
+        name="shipment_refresh_tracking",
+    ),
 ]

site/shipping/views.py

@@ -1,18 +1,24 @@
+import json
 import logging
 
+from django.conf import settings
 from django.contrib import messages
 from django.contrib.auth.decorators import login_required
-from django.http import HttpResponse
+from django.http import HttpResponse, HttpResponseBadRequest
 from django.shortcuts import get_object_or_404, redirect, render
+from django.views.decorators.csrf import csrf_exempt
 from django.views.decorators.http import require_http_methods, require_POST
 
 from shipping.models import Shipment
 from shipping.services import (
     ShippingError,
+    apply_tracker_payload,
+    attach_tracking,
     buy_label,
     create_shipment_for_order,
     pirate_ship_csv,
     quote_rates,
+    refresh_tracking,
 )
 from shop.models import Order
 
@@ -77,6 +83,40 @@ def shipment_buy(request, pk):
     return redirect("shipping:shipment_detail", pk=shipment.pk)
 
 
+@login_required
+@require_POST
+def shipment_attach_tracking(request, pk):
+    shipment = get_object_or_404(Shipment, pk=pk)
+    try:
+        attach_tracking(
+            shipment,
+            tracking_number=request.POST.get("tracking_number") or "",
+            carrier=request.POST.get("carrier") or "",
+        )
+    except ShippingError as exc:
+        messages.error(request, str(exc))
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("attach tracking failed")
+        messages.error(request, f"Could not save tracking: {exc}")
+    else:
+        messages.success(request, "Tracking saved.")
+    return redirect("shipping:shipment_detail", pk=shipment.pk)
+
+
+@login_required
+@require_POST
+def shipment_refresh_tracking(request, pk):
+    shipment = get_object_or_404(Shipment, pk=pk)
+    try:
+        refresh_tracking(shipment)
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("refresh tracking failed")
+        messages.error(request, f"Could not refresh tracking: {exc}")
+    else:
+        messages.success(request, "Tracking updated.")
+    return redirect("shipping:shipment_detail", pk=shipment.pk)
+
+
 @login_required
 @require_http_methods(["GET"])
 def pirate_ship_export(request):
@@ -84,3 +124,36 @@ def pirate_ship_export(request):
     response = HttpResponse(body, content_type="text/csv")
     response["Content-Disposition"] = 'attachment; filename="pirate-ship-orders.csv"'
     return response
+
+
+@csrf_exempt
+@require_http_methods(["POST"])
+def easypost_webhook(request):
+    secret = (getattr(settings, "EASYPOST_WEBHOOK_SECRET", "") or "").strip()
+    if secret:
+        got = (
+            request.headers.get("X-Webhook-Secret")
+            or request.GET.get("token")
+            or ""
+        ).strip()
+        if got != secret:
+            return HttpResponseBadRequest("invalid secret")
+    try:
+        payload = json.loads(request.body.decode("utf-8") or "{}")
+    except json.JSONDecodeError:
+        return HttpResponseBadRequest("invalid json")
+    result = payload.get("result") or payload
+    if not isinstance(result, dict):
+        return HttpResponse("ok")
+    tracker_id = (result.get("id") or "").strip()
+    tracking = (result.get("tracking_code") or result.get("tracking_number") or "").strip()
+    shipment = None
+    if tracker_id:
+        shipment = Shipment.objects.filter(tracker_id=tracker_id).first()
+    if shipment is None and tracking:
+        shipment = Shipment.objects.filter(tracking_number=tracking).first()
+    if shipment is None:
+        return HttpResponse("ok")
+    apply_tracker_payload(shipment, result)
+    logger.info("easypost tracker updated shipment %s", shipment.pk)
+    return HttpResponse("ok")