Countdown Timer API with Node.js

countdownshare.ts

// countdownshare.ts — no dependencies, Node 18+.
const BASE = "https://countdownshare.com/api/v1";

export class CountdownError extends Error {
  constructor(
    message: string,
    readonly code: string,
    readonly status: number,
    readonly requestId: string,
    readonly retryAfter?: number,
  ) {
    super(message);
    this.name = "CountdownError";
  }
}

export type Timer = {
  id: string;
  name: string;
  type: "fixed" | "duration" | "recurring" | "personalized";
  status: "draft" | "published" | "archived";
  revision: number;
  remaining_seconds: number | null;
};

async function request<T>(path: string, init: RequestInit = {}): Promise<T> {
  const response = await fetch(BASE + path, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.COUNTDOWNSHARE_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });

  const payload = await response.json();

  if (!response.ok) {
    throw new CountdownError(
      payload.error.message,
      payload.error.code,
      response.status,
      payload.request_id,
      Number(response.headers.get("Retry-After")) || undefined,
    );
  }

  return payload.data as T;
}

Retry with backoff

const RETRYABLE = new Set(["rate_limited", "internal_error"]);

/**
 * Retries only what is worth retrying.
 *
 * quota_exhausted is also a 429 but will NOT clear by waiting —
 * the monthly allowance resets with the billing cycle. Branch on
 * the code, never on the status alone.
 */
async function withRetry<T>(fn: () => Promise<T>, attempts = 4): Promise<T> {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const retryable =
        error instanceof CountdownError && RETRYABLE.has(error.code);

      if (!retryable || attempt >= attempts - 1) throw error;

      const wait = error.retryAfter
        ? error.retryAfter * 1000
        : Math.min(2 ** attempt * 500, 8000);

      await new Promise((resolve) => setTimeout(resolve, wait));
    }
  }
}

Create and read

export function createTimer(body: object, idempotencyKey: string) {
  return withRetry(() =>
    request<Timer>("/timers", {
      method: "POST",
      headers: { "Idempotency-Key": idempotencyKey },
      body: JSON.stringify(body),
    }),
  );
}

export function getStatus(timerId: string) {
  return request<{
    status: string;
    ended: boolean;
    server_time: string;
    remaining: { total_seconds: number };
  }>(`/timers/${timerId}/status`);
}

// Usage: the key is derived from the order, so a retry after a
// timeout returns the original timer instead of a second one.
const timer = await createTimer(
  {
    name: `Cart hold ${order.id}`,
    type: "duration",
    duration_seconds: 900,
    metadata: { order_id: order.id },
  },
  `hold_${order.id}`,
);

Read, write, retry on conflict

/**
 * Updates use optimistic concurrency: send the revision you read,
 * and the API refuses the write if anything changed underneath.
 * On conflict, re-read and reapply — retrying the same revision
 * fails identically.
 */
export async function extendDeadline(timerId: string, deadlineAt: string) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const timer = await request<Timer>(`/timers/${timerId}`);

    try {
      return await request<Timer>(`/timers/${timerId}`, {
        method: "PATCH",
        headers: { "If-Match": String(timer.revision) },
        body: JSON.stringify({ deadline_at: deadlineAt }),
      });
    } catch (error) {
      if (
        !(error instanceof CountdownError) ||
        error.code !== "revision_conflict"
      ) {
        throw error;
      }
    }
  }

  throw new Error("Timer is being modified faster than we can update it");
}

Express webhook route

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();

// express.raw on THIS route only. A global express.json() consumes
// the stream and the signature can never be verified afterwards.
app.post(
  "/webhooks/countdownshare",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!verify(req.body, req.headers, process.env.COUNTDOWNSHARE_WEBHOOK_SECRET!)) {
      return res.sendStatus(401);
    }

    const event = JSON.parse(req.body.toString());

    // Acknowledge first — the budget is 10 seconds, and slow
    // handlers get retried.
    res.sendStatus(200);

    await queue.add("countdown-event", event, {
      // Delivery is at-least-once. Deduplicate on the event id.
      jobId: event.id,
    });
  },
);

function verify(raw: Buffer, headers: express.Request["headers"], secret: string) {
  const timestamp = headers["x-countdownshare-timestamp"] as string;
  const signature = headers["x-countdownshare-signature"] as string;
  if (!timestamp || !signature) return false;

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${raw.toString()}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature.replace(/^v1=/, ""), "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}