feat: add fake payment API

Author: autochamchikim-pixel

README.md

@@ -1,6 +1,53 @@
 # Template API Project
 
 This is a template project with best-practice modules:
+
 - Winterspec for defining the API
 - bun testing
 - Zustand store with zod definition for database state
+
+## Fake payment API
+
+This repo now includes a focused fake payment lifecycle API for bounty/testing workflows.
+
+### Endpoints
+
+- `POST /payments/send` — create a pending fake payment.
+- `GET /payments/list` — list all payments.
+- `GET /payments/list?status=pending|completed|cancelled|failed` — list payments by status.
+- `GET /payments/get?payment_id=0` — fetch one payment by id.
+- `POST /payments/update_status` — update a payment status.
+
+### Idempotency
+
+`/payments/send` accepts an optional `idempotency_key`. Reusing the same key returns the original payment instead of creating a duplicate.
+
+### Example request
+
+```json
+{
+  "amount": 25,
+  "currency": "usd",
+  "recipient": "octocat",
+  "memo": "bounty payout",
+  "idempotency_key": "idem-1"
+}
+```
+
+### Example response
+
+```json
+{
+  "payment": {
+    "payment_id": "0",
+    "amount": 25,
+    "currency": "USD",
+    "recipient": "octocat",
+    "memo": "bounty payout",
+    "idempotency_key": "idem-1",
+    "status": "pending",
+    "created_at": "2026-05-13T00:00:00.000Z",
+    "updated_at": "2026-05-13T00:00:00.000Z"
+  }
+}
+```

lib/db/db-client.ts

@@ -1,8 +1,12 @@
-import { createStore, type StoreApi } from "zustand/vanilla"
-import { immer } from "zustand/middleware/immer"
-import { hoist, type HoistedStoreApi } from "zustand-hoist"
+import { createStore } from "zustand/vanilla"
+import { hoist } from "zustand-hoist"
 
-import { databaseSchema, type DatabaseSchema, type Thing } from "./schema.ts"
+import {
+  databaseSchema,
+  type Payment,
+  type PaymentStatus,
+  type Thing,
+} from "./schema.ts"
 import { combine } from "zustand/middleware"
 
 export const createDatabase = () => {
@@ -11,7 +15,15 @@ export const createDatabase = () => {
 
 export type DbClient = ReturnType<typeof createDatabase>
 
-const initializer = combine(databaseSchema.parse({}), (set) => ({
+export interface CreatePaymentInput {
+  amount: number
+  currency: string
+  recipient: string
+  memo?: string
+  idempotency_key?: string
+}
+
+const initializer = combine(databaseSchema.parse({}), (set, get) => ({
   addThing: (thing: Omit<Thing, "thing_id">) => {
     set((state) => ({
       things: [
@@ -21,4 +33,61 @@ const initializer = combine(databaseSchema.parse({}), (set) => ({
       idCounter: state.idCounter + 1,
     }))
   },
+
+  createPayment: (payment: CreatePaymentInput): Payment => {
+    const now = new Date().toISOString()
+    const existingPayment = payment.idempotency_key
+      ? get().payments.find(
+          (existing) => existing.idempotency_key === payment.idempotency_key,
+        )
+      : undefined
+
+    if (existingPayment) return existingPayment
+
+    const newPayment: Payment = {
+      payment_id: get().paymentIdCounter.toString(),
+      amount: payment.amount,
+      currency: payment.currency.toUpperCase(),
+      recipient: payment.recipient,
+      memo: payment.memo,
+      idempotency_key: payment.idempotency_key,
+      status: "pending",
+      created_at: now,
+      updated_at: now,
+    }
+
+    set((state) => ({
+      payments: [...state.payments, newPayment],
+      paymentIdCounter: state.paymentIdCounter + 1,
+    }))
+
+    return newPayment
+  },
+
+  getPayment: (paymentId: string): Payment | undefined => {
+    return get().payments.find((payment) => payment.payment_id === paymentId)
+  },
+
+  listPayments: (status?: PaymentStatus): Payment[] => {
+    const payments = get().payments
+    return status ? payments.filter((payment) => payment.status === status) : payments
+  },
+
+  updatePaymentStatus: (
+    paymentId: string,
+    status: PaymentStatus,
+  ): Payment | undefined => {
+    let updatedPayment: Payment | undefined
+    const now = new Date().toISOString()
+
+    set((state) => ({
+      payments: state.payments.map((payment) => {
+        if (payment.payment_id !== paymentId) return payment
+        updatedPayment = { ...payment, status, updated_at: now }
+        return updatedPayment
+      }),
+    }))
+
+    return updatedPayment
+  },
 }))

lib/db/schema.ts

@@ -9,8 +9,31 @@ export const thingSchema = z.object({
 })
 export type Thing = z.infer<typeof thingSchema>
 
+export const paymentStatusSchema = z.enum([
+  "pending",
+  "completed",
+  "cancelled",
+  "failed",
+])
+export type PaymentStatus = z.infer<typeof paymentStatusSchema>
+
+export const paymentSchema = z.object({
+  payment_id: z.string(),
+  amount: z.number().positive(),
+  currency: z.string().min(3).max(12),
+  recipient: z.string().min(1),
+  memo: z.string().optional(),
+  idempotency_key: z.string().optional(),
+  status: paymentStatusSchema.default("pending"),
+  created_at: z.string(),
+  updated_at: z.string(),
+})
+export type Payment = z.infer<typeof paymentSchema>
+
 export const databaseSchema = z.object({
   idCounter: z.number().default(0),
+  paymentIdCounter: z.number().default(0),
   things: z.array(thingSchema).default([]),
+  payments: z.array(paymentSchema).default([]),
 })
 export type DatabaseSchema = z.infer<typeof databaseSchema>

routes/payments/get.ts

@@ -0,0 +1,26 @@
+import { paymentSchema } from "lib/db/schema"
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import { z } from "zod"
+
+export default withRouteSpec({
+  methods: ["GET"],
+  jsonResponse: z.object({
+    ok: z.boolean(),
+    payment: paymentSchema.optional(),
+    error: z.string().optional(),
+  }),
+})((req, ctx) => {
+  const url = new URL(req.url)
+  const paymentId = url.searchParams.get("payment_id")
+
+  if (!paymentId) {
+    return ctx.json({ ok: false, error: "payment_id is required" })
+  }
+
+  const payment = ctx.db.getPayment(paymentId)
+  if (!payment) {
+    return ctx.json({ ok: false, error: "payment not found" })
+  }
+
+  return ctx.json({ ok: true, payment })
+})

routes/payments/list.ts

@@ -0,0 +1,16 @@
+import { paymentSchema, paymentStatusSchema } from "lib/db/schema"
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import { z } from "zod"
+
+export default withRouteSpec({
+  methods: ["GET"],
+  jsonResponse: z.object({
+    payments: z.array(paymentSchema),
+  }),
+})((req, ctx) => {
+  const url = new URL(req.url)
+  const statusParam = url.searchParams.get("status")
+  const status = statusParam ? paymentStatusSchema.parse(statusParam) : undefined
+
+  return ctx.json({ payments: ctx.db.listPayments(status) })
+})

routes/payments/send.ts

@@ -0,0 +1,22 @@
+import { paymentSchema } from "lib/db/schema"
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import { z } from "zod"
+
+export default withRouteSpec({
+  methods: ["POST"],
+  jsonBody: z.object({
+    amount: z.number().positive(),
+    currency: z.string().min(3).max(12),
+    recipient: z.string().min(1),
+    memo: z.string().optional(),
+    idempotency_key: z.string().min(1).optional(),
+  }),
+  jsonResponse: z.object({
+    payment: paymentSchema,
+  }),
+})(async (req, ctx) => {
+  const paymentRequest = await req.json()
+  const payment = ctx.db.createPayment(paymentRequest)
+
+  return ctx.json({ payment })
+})

routes/payments/update_status.ts

@@ -0,0 +1,25 @@
+import { paymentSchema, paymentStatusSchema } from "lib/db/schema"
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import { z } from "zod"
+
+export default withRouteSpec({
+  methods: ["POST"],
+  jsonBody: z.object({
+    payment_id: z.string().min(1),
+    status: paymentStatusSchema,
+  }),
+  jsonResponse: z.object({
+    ok: z.boolean(),
+    payment: paymentSchema.optional(),
+    error: z.string().optional(),
+  }),
+})(async (req, ctx) => {
+  const { payment_id, status } = await req.json()
+  const payment = ctx.db.updatePaymentStatus(payment_id, status)
+
+  if (!payment) {
+    return ctx.json({ ok: false, error: "payment not found" })
+  }
+
+  return ctx.json({ ok: true, payment })
+})

tests/routes/payments.test.ts

@@ -0,0 +1,45 @@
+import { getTestServer } from "tests/fixtures/get-test-server"
+import { test, expect } from "bun:test"
+
+test("send, list, get, and update payments", async () => {
+  const { axios } = await getTestServer()
+
+  const first = await axios.post("/payments/send", {
+    amount: 25,
+    currency: "usd",
+    recipient: "octocat",
+    memo: "bounty payout",
+    idempotency_key: "idem-1",
+  })
+
+  expect(first.data.payment.payment_id).toBe("0")
+  expect(first.data.payment.currency).toBe("USD")
+  expect(first.data.payment.status).toBe("pending")
+
+  const duplicate = await axios.post("/payments/send", {
+    amount: 25,
+    currency: "usd",
+    recipient: "octocat",
+    memo: "bounty payout",
+    idempotency_key: "idem-1",
+  })
+
+  expect(duplicate.data.payment.payment_id).toBe(first.data.payment.payment_id)
+
+  const list = await axios.get("/payments/list")
+  expect(list.data.payments).toHaveLength(1)
+
+  const get = await axios.get("/payments/get?payment_id=0")
+  expect(get.data.ok).toBe(true)
+  expect(get.data.payment.recipient).toBe("octocat")
+
+  const completed = await axios.post("/payments/update_status", {
+    payment_id: "0",
+    status: "completed",
+  })
+  expect(completed.data.ok).toBe(true)
+  expect(completed.data.payment.status).toBe("completed")
+
+  const filtered = await axios.get("/payments/list?status=completed")
+  expect(filtered.data.payments).toHaveLength(1)
+})