Best practices and troubleshooting

const POLLING_INTERVAL = 30000; // 30 seconds

setInterval(async () => {
  try {
    const events = await fetchEvents();
    for (const event of events) {
      await processEvent(event);
      await acknowledgeEvent(event.eventId);
    }
  } catch (error) {
    logger.error('Polling failed', error);
  }
}, POLLING_INTERVAL);

async function processEvent(event) {
  // 1. Process
  await updateOrderStatus(event.orderId, event.type);

  // 2. Acknowledge IMMEDIATELY
  await acknowledgeEvent(event.eventId);

  // Without acknowledge = continuous reprocessing
}

const processedEventIds = new Set();

async function processEvent(event) {
  if (processedEventIds.has(event.eventId)) {
    logger.info(`Event ${event.eventId} already processed`);
    return; // Ignore duplicate
  }

  // ... process event ...

  processedEventIds.add(event.eventId);
}

// Clear Set periodically (e.g., every 24h)
setInterval(() => {
  processedEventIds.clear();
}, 24 * 60 * 60 * 1000);

const TOKEN_BUFFER = 5 * 60 * 1000; // 5 minutes

async function ensureValidToken() {
  if (!token || isExpiringSoon(token)) {
    token = await refreshToken();
    token.refreshedAt = Date.now();
  }
  return token;
}

function isExpiringSoon(token) {
  const expiresIn = token.expiresAt - Date.now();
  return expiresIn < TOKEN_BUFFER;
}

async function requestWithRetry(fn, maxRetries = 5) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      // Transient errors: retry
      if (isTransient(error)) {
        if (attempt < maxRetries) {
          const delay = Math.pow(2, attempt - 1) * 1000; // 1s, 2s, 4s, 8s...
          const jitter = Math.random() * 1000; // Prevents thundering herd
          await sleep(delay + jitter);
          continue;
        }
      }
      // Permanent errors: fail immediately
      throw error;
    }
  }
}

function isTransient(error) {
  // 5xx, timeouts, rate limiting
  return error.status >= 500 ||
         error.status === 429 ||
         error.code === 'ECONNREFUSED';
}

const logEntry = {
  timestamp: new Date().toISOString(),
  orderId: order.id,
  operation: 'requestDriver',
  status: 'success',
  duration: Date.now() - startTime,
  attempt: currentAttempt,
  error: error?.message,
  statusCode: response?.status,
};

logger.info('Shipping operation', logEntry);

// Validate orderId
function isValidUUID(uuid) {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid);
}

// Validate phone
function isValidPhone(countryCode, areaCode, number) {
  return countryCode === '55' && // Brazil
         areaCode.length === 2 &&
         (number.length === 8 || number.length === 9);
}

// Validate postal code
function isValidPostalCode(postalCode) {
  return /^\d{8}$/.test(postalCode.replace('-', ''));
}

// Validate coordinates
function isValidCoordinates(lat, lng) {
  return lat >= -90 && lat <= 90 &&
         lng >= -180 && lng <= 180;
}

// Validate quoteId before using
function isValidQuote(quote) {
  return quote &&
         isValidUUID(quote.id) &&
         new Date(quote.expirationAt) > new Date();
}

1. Average preparation time (benchmarking)
   Ex: 12 minutes

2. Add margin for peak hours
   Ex: +3 minutes

3. Convert to seconds
   (12 + 3) * 60 = 900 seconds

Week 1: preparationTime = 900s (15 min)
  ↓ (Monitor deliveries)
  ↓
If courier arrives very early:
  → Increase to 1000s (16 min)

If courier arrives very late:
  → Decrease to 800s (13 min)

Order created
  ↓
REQUEST_DRIVER (202)
  ↓
Polling... waiting for success
  ↓
REQUEST_DRIVER_SUCCESS
  ↓ (NOW, query tracking)
  ↓
GET /tracking

// After REQUEST_DRIVER_SUCCESS
setInterval(async () => {
  try {
    const tracking = await getTracking(orderId);
    updateUI(tracking);
  } catch (error) {
    if (error.status === 404) {
      logger.info('Tracking not yet available');
      // Courier still being assigned, retry later
    }
  }
}, 30000); // 30 seconds

const tracking = await getTracking(orderId);

// Safe: check null before using
if (tracking.latitude && tracking.longitude) {
  updateMapMarker(tracking.latitude, tracking.longitude);
}

// Can be null
if (tracking.expectedDelivery) {
  updateETA(tracking.expectedDelivery);
}

// Can be negative (pickup delay)
const pickupDelay = tracking.pickupEtaStart < 0
  ? `Delayed ${Math.abs(tracking.pickupEtaStart)}s`
  : `${tracking.pickupEtaStart}s remaining`;

1. Success rate per endpoint
   - Alert: < 95%
   - Interval: 1 hour

2. P95 latency
   - Alert: > 5 seconds
   - Interval: 5 minutes

3. Error rate by type
   - Alert: HighDemand > 20%
   - Interval: 15 minutes

4. Consecutive polling failures
   - Alert: > 3 failures in a row
   - Interval: real-time

5. Timeout rate
   - Alert: > 5%
   - Interval: 1 hour

1. Token renewal failure
   → All requests will fail with 401

2. Polling stopped
   → Events will not be processed

3. Error rate > 10% for 30 min
   → System-wide issue in progress

4. Event delay > 5 min
   → Possible system bottleneck

// WRONG
const response = await requestDriver(orderId, quoteId);
// response.status === 202
console.log('Courier allocated!'); // WRONG!

// CORRECT
const response = await requestDriver(orderId, quoteId);
// response.status === 202
logger.info('Allocation requested, awaiting confirmation...');

// Then monitor events
// Only confirm when receiving REQUEST_DRIVER_SUCCESS

async function cancelOrder(orderId) {
  const idempotencyKey = `cancel-${orderId}-${Date.now()}`;

  return fetch(`/orders/${orderId}/cancel`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify({
      reason: 'Customer requested',
      cancellationCode: 817
    })
  });
}

// Monitor event to get code
function handleEvent(event) {
  if (event.type === 'DELIVERY_DROP_CODE_REQUESTED') {
    const code = event.metadata.CODE;

    // Notify customer via SMS/email/app
    sendCodeToCustomer(customer.phone, code);

    // Instruct courier to request code
    updateDeliveryInstructions(orderId,
      `Request code ${code} before delivery`);
  }
}

const safeDelivery = await getSafeDeliveryScore(orderId);

switch(safeDelivery.score) {
  case 'LOW':
    // Require additional validation
    sendVerificationToCustomer(orderId);
    addAlert(`Low-risk delivery: ${orderId}`);
    break;

  case 'MODERATE':
    // Monitor normally
    logger.info(`Moderate risk: ${orderId}`);
    break;

  case 'HIGH':
  case 'VERY_HIGH':
    // Standard processing
    break;
}

Orders on platform:
  [ ] GET /deliveryAvailabilities works
  [ ] POST /requestDriver returns 202
  [ ] Events are received
  [ ] GET /tracking works after success
  [ ] Cancellation works

Orders outside platform:
  [ ] GET /merchants/{merchantId}/deliveryAvailabilities works
  [ ] POST /merchants/{merchantId}/orders returns 202 + trackingUrl
  [ ] Confirmation code is received
  [ ] Address changes work
  [ ] Safe Delivery Score works

Errors:
  [ ] HighDemand is handled with retry
  [ ] 404 on tracking is ignored before success
  [ ] Rate limiting is respected
  [ ] Expired tokens are renewed

Monitoring:
  [ ] Structured logs at all points
  [ ] Alerts configured
  [ ] Dashboard visible
  [ ] Metrics being collected

Attempt 1: 1s
Attempt 2: 2s
Attempt 3: 4s
Attempt 4: 8s
Attempt 5: 16s

Valid format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Example: 57cd1046-2e06-446f-a2dd-18a518212c3c

1. Request courier (202)
2. Wait for REQUEST_DRIVER_SUCCESS event (polling)
3. After that, tracking becomes available

1. Polling every 30s?       ✓
2. Event acknowledgment?    ✓
3. Deduplication by ID?     ✓
4. Logs for each event?     ✓

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 50
X-RateLimit-Reset: 1693...

GET /deliveryAvailabilities
  ↓ (validates coverage + gets quoteId)
  ↓
POST /requestDriver (with quoteId)

async function requestWithRetry(fn, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (isTransient(error) && attempt < maxRetries) {
        const delay = Math.pow(2, attempt - 1) * 1000;
        await sleep(delay);
      } else {
        throw error;
      }
    }
  }
}

function isTransient(error) {
  return error.status >= 500 || error.status === 429;
}

- Success rate per endpoint
- P95 latency (95th percentile)
- Errors by type
- Polling to processing time
- Timeout rate

timestamp: 2023-08-17T20:10:00Z
orderId: 57cd1046-2e06-446f-a2dd-18a518212c3c
operation: requestDriver
status: success
duration: 150ms