Trigger: AfterShip tracking event received
Condition: Status is "Exception" or "Failed Attempt"
Action: Create customer service task in Gorgias or Zendesk
Action: Send internal Slack notification to #shipping-exceptions

// Register a tracking number with EasyPost to receive webhook updates
async function registerEasyPostTracker(params: {
  trackingNumber: string;
  carrier: string; // 'UPS', 'FedEx', 'USPS', 'DHL'
  orderId: string;
}): Promise<void> {
  const response = await fetch('https://api.easypost.com/v2/trackers', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.EASYPOST_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      tracker: {
        tracking_code: params.trackingNumber,
        carrier: params.carrier,
      },
    }),
  });
  const tracker = await response.json();
  // Store tracker.id to correlate future webhook events with this order
  await db.shipments.update({ tracking_number: params.trackingNumber }, {
    easypost_tracker_id: tracker.id,
  });
}

// Receive EasyPost webhook and update order status
// POST /webhooks/easypost
async function handleEasyPostWebhook(rawBody: Buffer, signature: string): Promise<void> {
  // Verify webhook signature
  const expectedSig = crypto
    .createHmac('sha256', process.env.EASYPOST_WEBHOOK_SECRET!)
    .update(rawBody)
    .digest('hex');
  if (expectedSig !== signature) throw new Error('Invalid webhook signature');

  const event = JSON.parse(rawBody.toString());
  if (event.description !== 'tracker.updated') return;

  const tracker = event.result;
  const shipment = await db.shipments.findByEasyPostTrackerId(tracker.id);
  if (!shipment) return;

  // Normalize EasyPost status to your internal status
  const statusMap: Record<string, string> = {
    pre_transit: 'label_created',
    in_transit: 'in_transit',
    out_for_delivery: 'out_for_delivery',
    delivered: 'delivered',
    failure: 'exception',
    return_to_sender: 'returned',
  };
  const normalizedStatus = statusMap[tracker.status] ?? 'in_transit';

  await db.shipments.update(shipment.id, { status: normalizedStatus });

  // Update order to delivered when package arrives
  if (normalizedStatus === 'delivered') {
    await db.orders.update(shipment.order_id, { status: 'delivered', delivered_at: new Date() });
  }

  // Send notification email at key milestones
  if (['in_transit', 'out_for_delivery', 'delivered', 'exception'].includes(normalizedStatus)) {
    await sendTrackingNotificationEmail(shipment.order_id, normalizedStatus, tracker.tracking_code);
  }
}