Fulfillment Agent

# Deploy reference fulfillment agent
$ hyperfold agent deploy --type=fulfillment --name="fulfillment-01"
 
> [Build] Using reference implementation...
> [Config] Loading shipping rules...
> [Deploy] Creating Cloud Run service...
> [Events] Subscribing to order events...
 
✓ Fulfillment agent deployed!
 
  Name:           fulfillment-01
  Subscriptions:  order.completed, shipment.*, return.*
  Carriers:       USPS, FedEx, UPS (via ShipStation)
 
# Deploy with custom configuration
$ hyperfold agent deploy --type=fulfillment \
  --name="fulfillment-premium" \
  --config=./agents/fulfillment-config.yaml

// Fulfillment agent shipping logic
 
@OnEvent('order.completed')
async handleOrderCompleted(order: Order) {
  // 1. Validate order can be fulfilled
  const inventory = await this.checkInventory(order.items);
  if (!inventory.canFulfill) {
    await this.handleBackorder(order, inventory);
    return;
  }
 
  // 2. Determine best shipping method
  const shippingOptions = await this.getRates({
    from: this.selectWarehouse(order),
    to: order.shipping_address,
    items: order.items,
    weight: order.total_weight,
  });
 
  // 3. Apply shipping rules
  const selectedRate = this.applyShippingRules(order, shippingOptions);
 
  // 4. Create shipment
  const shipment = await this.createShipment({
    order_id: order.id,
    carrier: selectedRate.carrier,
    service: selectedRate.service,
    items: order.items,
  });
 
  // 5. Generate label
  const label = await this.generateLabel(shipment);
 
  // 6. Update inventory
  await this.decrementInventory(order.items);
 
  // 7. Send tracking notification
  await this.sendTrackingEmail(order.customer, {
    order_id: order.id,
    tracking_number: shipment.tracking_number,
    carrier: shipment.carrier,
    estimated_delivery: shipment.estimated_delivery,
  });
 
  // 8. Publish event
  await this.events.publish('shipment.created', { order, shipment });
}
 
// Carrier selection logic
selectCarrier(order: Order, rates: ShippingRate[]): ShippingRate {
  // Premium customers get expedited shipping
  if (order.customer.tier === 'platinum') {
    return rates.find(r => r.service.includes('Express')) || rates[0];
  }
 
  // High-value orders get insured shipping
  if (order.total > 200) {
    return rates.find(r => r.insurance_included) || rates[0];
  }
 
  // Default to cheapest option that meets SLA
  return rates
    .filter(r => r.estimated_days <= order.shipping_sla)
    .sort((a, b) => a.cost - b.cost)[0];
}

# fulfillment-config.yaml
name: fulfillment-agent
type: fulfillment
version: "1.0"
 
# Shipping provider
shipping_provider: shipstation
shipstation:
  api_key: $SHIPSTATION_API_KEY
  api_secret: $SHIPSTATION_API_SECRET
 
# Warehouse configuration
warehouses:
  - id: warehouse_west
    name: "West Coast DC"
    address:
      city: Los Angeles
      state: CA
      zip: "90001"
    carriers: [usps, fedex, ups]
    priority: 1  # Primary warehouse
 
  - id: warehouse_east
    name: "East Coast DC"
    address:
      city: Newark
      state: NJ
      zip: "07102"
    carriers: [usps, fedex, ups]
    priority: 2
 
# Shipping rules
shipping_rules:
  # Free shipping threshold
  - name: free_shipping
    condition: "order.subtotal >= 100"
    action:
      free_shipping: true
      method: "standard"
 
  # Premium customer expedited
  - name: premium_expedited
    condition: "customer.tier in ['gold', 'platinum']"
    action:
      upgrade_to: "express"
      cost_to_customer: 0
 
  # Heavy items
  - name: heavy_freight
    condition: "order.total_weight > 70"
    action:
      carrier: "freight"
      method: "ltl"
 
  # Regional optimization
  - name: west_coast_usps
    condition: "shipping.state in ['CA', 'OR', 'WA', 'NV', 'AZ']"
    action:
      preferred_carrier: "usps"
      warehouse: "warehouse_west"
 
# Notification settings
notifications:
  send_tracking: true
  send_delivery: true
  send_delay_alert: true
  delay_threshold_hours: 24
 
# Return policy
returns:
  window_days: 30
  free_return_shipping: true
  restocking_fee_percent: 0
  auto_approve_under: 100