Idempotency

[
  { "errors": { "message": "Unique request ID already exist" } }
]

import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
import { callMultigate, Outcome } from './multigate.js'; // the handler from the Errors page

const BASE_URL = process.env.MG_BASE_URL; // https://api-gateway-uat.mmacs.io/platform in the sandbox
const LOOKUP_DELAY_MS = 60_000;
const MAX_SENDS = 2; // the first attempt plus one retry with the same key

// Step 1 and 2: generate the key with the payout, and store it before calling Multigate.
export async function createPayout(db, details) {
  return db.payouts.insert({ ...details, uniqueRequestId: `acme_po_${randomUUID()}`, status: 'sending' });
}

// Steps 3 and 4: send it. A retry calls this again with the same stored payout, so the same key.
export async function sendPayout(db, payout, sends = 1) {
  const result = await callOrThrow(`${BASE_URL}/payment-service/api/v1/transfer/single-transfer`, {
    method: 'POST',
    body: toTransferBody(payout), // includes payout.uniqueRequestId
  });
  if (result.outcome === Outcome.SUCCESS) {
    return db.payouts.update(payout.id, { status: 'sent', transactionIds: [result.body.transactionId] });
  }
  if (result.outcome === Outcome.REFUSED && !isDuplicate(result)) {
    return db.payouts.update(payout.id, { status: 'refused', errors: result.errors }); // nothing happened
  }
  return recover(db, payout, sends); // unknown outcome, or "already exist"
}

// After a timeout, a 5xx or a duplicate: look it up, wait, look again, then retry with the same key.
async function recover(db, payout, sends) {
  let transfers = await findTransfers(payout.uniqueRequestId);
  if (transfers.length === 0) {
    await sleep(LOOKUP_DELAY_MS); // the first attempt may still be running
    transfers = await findTransfers(payout.uniqueRequestId);
  }
  if (transfers.length > 0) {
    return db.payouts.update(payout.id, { status: 'sent', transactionIds: transfers.map((t) => t.transactionId) });
  }
  if (sends >= MAX_SENDS) {
    return db.payouts.update(payout.id, { status: 'needs_review' }); // a person checks it, or a job retries later
  }
  return sendPayout(db, payout, sends + 1);
}

async function findTransfers(uniqueRequestId) {
  const url = new URL(`${BASE_URL}/payment-service/api/v1/transaction/report`);
  // "-1" is the first part of a split NGN transfer. Your original key isn't stored when a transfer is split.
  url.searchParams.set('uniqueRequestId', `${uniqueRequestId},${uniqueRequestId}-1`);
  const result = await callOrThrow(url.toString(), {});
  if (result.outcome !== Outcome.SUCCESS) {
    throw new Error(`Transfer lookup failed with HTTP ${result.status}; try again later`);
  }
  return result.body.data;
}

async function callOrThrow(url, options) {
  const result = await callMultigate(url, options);
  if (result.outcome === Outcome.CHECK_API_KEY) {
    // A 401 means nothing happened. The payout stays 'sending', so it is sent again once the key is fixed.
    throw new Error('Multigate refused the API key; check MG_API_KEY');
  }
  return result;
}

function isDuplicate(result) {
  return result.errors.some((error) => error.message === 'Unique request ID already exist');
}