Delivery: last-mile dispatch and proof of delivery

// A minimal client for the wede REST API, used by the snippets below
export class WedeError extends Error {
  constructor(public status: number, public code: string, message: string) {
    super(message)
  }
}

export type Credential = { apiKey: string } | { token: string }

export async function wede(cred: Credential, method: string, path: string, body?: unknown) {
  const res = await fetch(`https://api.wede.pt${path}`, {
    method,
    headers: {
      ...('apiKey' in cred ? { 'x-wede-api-key': cred.apiKey } : { authorization: `Bearer ${cred.token}` }),
      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
    },
    body: body !== undefined ? JSON.stringify(body) : undefined,
  })
  const data = res.status === 204 ? null : await res.json().catch(() => null)
  if (!res.ok) throw new WedeError(res.status, data?.error ?? 'api_error', data?.message ?? `HTTP ${res.status}`)
  return data
}

export async function login(email: string, password: string): Promise<string> {
  const res = await fetch('https://api.wede.pt/v1/auth/login', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ email, password }),
  })
  const data = await res.json().catch(() => null)
  if (!res.ok) throw new WedeError(res.status, data?.error ?? 'api_error', data?.message ?? `HTTP ${res.status}`)
  return data.token
}

// Captures an operation for offline sync, with the capture time and the integrity checksum:
// SHA-256 of JSON.stringify(payload) + idempotency_key + offline_generated_at (see Sync)
export async function capture<T extends { idempotency_key: string; payload: Record<string, unknown> }>(event: T) {
  const offline_generated_at = new Date().toISOString()
  const bytes = new TextEncoder().encode(JSON.stringify(event.payload) + event.idempotency_key + offline_generated_at)
  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))
  const integrity_hash = [...digest].map(b => b.toString(16).padStart(2, '0')).join('')
  return { ...event, offline_generated_at, integrity_hash }
}

import { login, wede, WedeError } from './lib/wede'

const admin = { token: await login(process.env.WEDE_ADMIN_EMAIL!, process.env.WEDE_ADMIN_PASSWORD!) }

// The category id of "Deliveries" (code dlv) in the delivery vertical
const { data } = await wede(admin, 'GET', '/v1/catalog?vertical=delivery')
const deliveries = data[0].categories.find((c: any) => c.code === 'dlv').id

const types = [
  { code: 'parcel_pickup', name: 'Parcel pickup', requires_teams: true, required_equipment: ['van'] },
  { code: 'delivery_confirmed', name: 'Delivery confirmed', requires_teams: false },
  { code: 'cash_on_delivery', name: 'Cash on delivery collected', requires_teams: false, default_priority: 'high' },
]

for (const t of types) {
  try {
    await wede(admin, 'POST', '/v1/catalog/types', { vertical: 'delivery', category_id: deliveries, ...t })
  } catch (err) {
    // 409 conflict: the code already exists for this vertical, so the script is safe to rerun
    if (!(err instanceof WedeError && err.status === 409)) throw err
  }
}

import { wede } from '../lib/wede'

const server = { apiKey: process.env.WEDE_API_KEY! }

export async function requestPickup(orderId: string) {
  const res = await wede(server, 'POST', '/v1/events', {
    type: 'parcel_pickup',
    vertical: 'delivery',
    priority: 'normal',
    idempotency_key: `order-${orderId}-pickup`,
    payload: {
      order_ref: orderId,
      pickup: { lat: -25.9692, lng: 32.5732, label: 'Warehouse Baixa' },
      dropoff: { lat: -25.9531, lng: 32.5889, label: 'Customer 41' },
      parcels: 2,
      cash_on_delivery_minor: 150000,
      currency: 'MZN',
    },
    metadata: { zone_id: 'MPM-CENTRAL' },
  })

  return res.event_id
}

import { login, wede } from '../lib/wede'

const dispatcher = { token: await login(dispatcherEmail, dispatcherPassword) }

const eventId = 'c4b3a2d1-8e7f-4a6b-9c5d-3e2f1a0b9c8d' // event_id from step 2
const pickup = { lat: -25.9692, lng: 32.5732 }

const { scored, count, excluded } = await wede(dispatcher, 'POST', '/v1/teams/dispatch/score', {
  ...pickup,
  event_id: eventId,
})

if (count === 0) throw new Error(`No candidate driver (${excluded.map((x: any) => `${x.team_name}: ${x.reason}`).join(', ')})`)

const best = scored.find((t: any) => t.recommended) ?? scored[0]

await wede(dispatcher, 'POST', '/v1/teams/dispatch', {
  event_id: eventId,
  team_id: best.team_id,
  event_lat: pickup.lat,
  event_lng: pickup.lng,
  notes: 'Two parcels, cash on delivery',
})

// A dispatch assigns the mission to the team: find it and hand it to the driver
const { data } = await wede(dispatcher, 'GET', `/v1/missions?team_id=${best.team_id}&status=CREATED`)
const mission = data.find((m: any) => m.event_id === eventId)
if (!mission) throw new Error('Mission not found')

await pushToDriverApp(best.team_id, { mission_id: mission.id, order_ref: 'ORD-88214' }) // your code
await wede(dispatcher, 'PATCH', `/v1/missions/${mission.id}/status`, { status: 'SENT' })

import { login, wede, WedeError } from './lib/wede'

export const driver = { token: await login(driverEmail, driverPassword) }

type MissionStatus = 'CREATED' | 'SENT' | 'ACK' | 'ON_ROUTE' | 'ON_SITE' | 'COMPLETED' | 'FAILED'

export async function setStatus(
  missionId: string,
  status: MissionStatus,
  feedback?: Record<string, unknown>,
) {
  try {
    await wede(driver, 'PATCH', `/v1/missions/${missionId}/status`, { status, ...(feedback ? { feedback } : {}) })
  } catch (err) {
    if (!(err instanceof WedeError)) {
      // no answer from the network: keep it and retry when online
      await pendingUpdates.add({ missionId, status, feedback }) // your local store
      return
    }
    throw err
  }
}

await setStatus(missionId, 'ACK')
await setStatus(missionId, 'ON_ROUTE')
await setStatus(missionId, 'ON_SITE')
await setStatus(missionId, 'COMPLETED', { parcels_delivered: 2, recipient: 'front_desk' })

import { capture, wede } from './lib/wede'
import { driver } from './mission'

export async function confirmDelivery(orderRef: string, missionId: string, cashCollectedMinor: number) {
  const proof = await capture({
    type: 'delivery_confirmed',
    vertical: 'delivery',
    priority: 'normal',
    idempotency_key: `order-${orderRef}-delivered`,
    payload: { order_ref: orderRef, mission_id: missionId, parcels: 2, signature_ref: 'sig-5521' },
  })
  const cash = await capture({
    type: 'cash_on_delivery',
    vertical: 'delivery',
    priority: 'high',
    idempotency_key: `order-${orderRef}-cod`,
    payload: { order_ref: orderRef, amount_minor: cashCollectedMinor, currency: 'MZN' },
  })
  await offlineQueue.push(proof, cash) // your local store; keep the objects unchanged
}

export async function flush() {
  const queued = await offlineQueue.all()
  if (queued.length === 0) return

  const { results } = await wede(driver, 'POST', '/v1/sync/batch', { events: queued.slice(0, 500) })
  for (const r of results) {
    if (r.result === 'accepted' || r.result === 'duplicate') {
      await offlineQueue.remove(r.idempotency_key)
    } else {
      await flagForReview(r.idempotency_key, r.error_code) // your code
    }
  }
}

import { wede } from '../lib/wede'

await wede({ apiKey: process.env.WEDE_API_KEY! }, 'POST', '/v1/webhooks', {
  url: 'https://orders.example.co.mz/webhooks/wede',
  events: ['team.dispatched', 'mission.status_updated', 'event.created', 'sync.completed'],
  secret: process.env.WEDE_WEBHOOK_SECRET!,
  description: 'Order management backend',
})

{
  "id": "7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d",
  "event": "event.created",
  "created_at": "2026-09-14T16:05:31.207Z",
  "tenant_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "environment": "production",
  "data": {
    "event_id": "f0e1d2c3-b4a5-4968-8776-655443322110",
    "type": "delivery_confirmed",
    "category": "dlv",
    "requires_teams": false,
    "vertical": "delivery",
    "priority": "normal",
    "payload": { "order_ref": "ORD-88214", "mission_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "parcels": 2, "signature_ref": "sig-5521" },
    "offline_generated_at": "2026-09-14T15:48:02.114Z",
    "origin": "sync"
  }
}

import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'

const SECRET = process.env.WEDE_WEBHOOK_SECRET!
const TOLERANCE_SECONDS = 300 // your choice

function verify(header: string | undefined, rawBody: Buffer): boolean {
  if (!header) return false
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=', 2) as [string, string]))
  const t = Number(parts.t)
  if (!parts.v1 || !Number.isFinite(t)) return false
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false
  const expected = createHmac('sha256', SECRET).update(`${parts.t}.${rawBody.toString('utf8')}`).digest()
  const received = Buffer.from(parts.v1, 'hex')
  return received.length === expected.length && timingSafeEqual(received, expected)
}

const app = express()

app.post('/webhooks/wede', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verify(req.header('x-wede-signature'), req.body)) return res.status(401).end()

  const delivery = JSON.parse(req.body.toString('utf8'))
  if (await alreadyProcessed(delivery.id)) return res.status(200).end() // retries reuse the same id

  if (delivery.event === 'mission.status_updated') {
    await updateOrderTracking(delivery.data.mission_id, delivery.data.status)
  }
  if (delivery.event === 'event.created' && delivery.data.type === 'delivery_confirmed') {
    await closeOrder(delivery.data.payload.order_ref, delivery.data.offline_generated_at)
  }
  await markProcessed(delivery.id)
  res.status(200).end()
})

app.listen(3000)