Auction countdown API

openLot

// One timer per lot. Every bidder counts to the same instant.
export async function openLot(lot) {
  const timer = await call("/timers", {
    method: "POST",
    headers: { "Idempotency-Key": `lot_${lot.id}` },
    body: JSON.stringify({
      name: `Lot ${lot.number} — ${lot.title}`,
      type: "fixed",
      deadline_at: lot.closesAt,
      publish: true,
      metadata: { lot_id: lot.id },
      expiry: { behavior: "show_message", message: "Bidding has closed" },
    }),
  });

  await db.lots.update(lot.id, { timerId: timer.id });

  // Warn bidders, then settle.
  await attachRule(timer.id, "Two minutes left", {
    field: "remaining_seconds", operator: "less_than_or_equal", value: 120,
  });
  await attachRule(timer.id, "Lot closed", {
    field: "status", operator: "equals", value: "ended",
  });

  return timer;
}

placeBid

/**
 * The bid endpoint. The clock the browser shows is presentation;
 * this read is the decision.
 */
export async function placeBid(lotId, bidderId, amount) {
  const lot = await db.lots.find(lotId);
  const status = await call(`/timers/${lot.timerId}/status`);

  // A device with a fast clock, a stale tab, or a crafted request
  // all fail here rather than winning the lot.
  if (status.ended) {
    throw new BiddingClosedError("Bidding has closed for this lot");
  }

  const bid = await db.transaction(async (tx) => {
    const highest = await tx.bids.highestFor(lotId, { lock: true });
    if (amount <= highest.amount) {
      throw new BidTooLowError(highest.amount);
    }
    return tx.bids.create({ lotId, bidderId, amount });
  });

  // Anti-snipe: a late bid extends the clock for everyone.
  if (status.remaining.total_seconds < ANTI_SNIPE_WINDOW) {
    await extendLot(lot, ANTI_SNIPE_EXTENSION);
  }

  return bid;
}

extendLot

const ANTI_SNIPE_WINDOW = 120;      // bid inside the last 2 minutes
const ANTI_SNIPE_EXTENSION = 120;   // pushes the close out by 2 more

/**
 * Extending is a normal update, so it is free and unlimited —
 * a heavily contested lot can extend dozens of times without
 * touching your monthly timer allowance.
 */
async function extendLot(lot, seconds) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const timer = await call(`/timers/${lot.timerId}`);

    const extended = new Date(
      new Date(timer.deadline_at).getTime() + seconds * 1000,
    );

    try {
      return await call(`/timers/${lot.timerId}`, {
        method: "PATCH",
        headers: { "If-Match": String(timer.revision) },
        body: JSON.stringify({ deadline_at: extended.toISOString() }),
      });
    } catch (error) {
      // Two bids landed at once and both tried to extend. Re-read
      // and reapply, so the extensions add rather than overwrite.
      if (error.code !== "revision_conflict") throw error;
    }
  }
}

handleLotClosed

// The lot closes. This fires whether or not anyone is watching.
async function handleLotClosed(event) {
  const lotId = event.timer.metadata.lot_id;

  await db.transaction(async (tx) => {
    const lot = await tx.lots.find(lotId, { lock: true });

    // Idempotent: a replayed delivery finds it already settled.
    if (!lot || lot.status !== "open") return;

    const winning = await tx.bids.highestFor(lotId);

    await tx.lots.update(lotId, {
      status: "closed",
      winningBidId: winning?.id ?? null,
    });
  });

  await notifyWinner(lotId);
  await notifyUnderbidders(lotId);
}

Client clock

// Every bidder renders against the SAME server clock, so the
// page cannot show one person more time than another.
const { remaining_seconds, server_time } = await fetch(
  `/api/lots/${lot.id}/clock`,   // your proxy
).then((r) => r.json());

const skew = Date.now() - new Date(server_time).getTime();
const endsAt = Date.now() - skew + remaining_seconds * 1000;

// Re-sync more aggressively than usual: the deadline moves when
// someone snipes, and a stale client would show a closed lot.
setInterval(sync, 10_000);