Fulfillment Automation

# Add shipping carriers
$ hyperfold fulfillment providers add shipstation

> [OAuth] Opening ShipStation authorization...
> [Config] Configuring carrier accounts...

✓ ShipStation connected!

Carriers:
  - USPS (Ground, Priority, Express)
  - FedEx (Ground, 2Day, Overnight)
  - UPS (Ground, 2nd Day Air, Next Day)

# Configure carrier selection rules
$ hyperfold fulfillment rules set

Rules configured:
- Orders < $50: USPS Ground
- Orders $50-150: FedEx Ground
- Orders > $150: FedEx Ground (Free shipping)
- Express selected: FedEx 2Day
- Overnight selected: UPS Next Day

// Fulfillment agent implementation
@HyperfoldAgent({
name: 'fulfillment-agent',
version: '1.0.0',
})
export class FulfillmentAgent {
@OnEvent('order.paid')
async handlePaidOrder(event: OrderPaidEvent) {
  const { order_id } = event;
  const order = await getOrder(order_id);

  // Select optimal carrier based on rules
  const carrier = await selectCarrier({
    total: order.total,
    shipping_option: order.shipping_option,
    destination: order.shipping_address,
  });

  // Generate shipping label
  const label = await createLabel({
    carrier,
    from: this.warehouseAddress,
    to: order.shipping_address,
    weight: calculateWeight(order.items),
    dimensions: calculateDimensions(order.items),
  });

  // Update order with tracking
  await updateOrder(order_id, {
    status: 'shipped',
    tracking_number: label.tracking_number,
    carrier: carrier.name,
    label_url: label.label_url,
  });

  // Notify customer
  await sendShippingNotification(order, label);
}
}

// Handle tracking updates
@OnWebhook('shipstation', 'tracking_update')
async handleTrackingUpdate(event: TrackingEvent) {
const { tracking_number, status, location, timestamp } = event;

// Find order by tracking number
const order = await findOrderByTracking(tracking_number);

// Update order status
await updateOrder(order.id, {
  shipping_status: mapStatus(status),
  last_location: location,
  last_update: timestamp,
});

// Notify on key events
if (status === 'DELIVERED') {
  await sendDeliveryConfirmation(order);
}
}

# Configure return policy
$ hyperfold fulfillment returns configure \
--window=30d \
--free-returns=true \
--carrier=usps

# The agent automatically generates return labels when
# customers request returns within the policy window