Add fake payments API

README.md

@@ -4,3 +4,17 @@ 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
+
+The fake payment routes are intentionally in-memory and safe for local testing:
+
+- `POST /payments/send` creates a pending fake payment and accepts optional bounty metadata.
+- `GET /payments/list` lists payments, with optional `recipient`, `repository`, and `status` filters.
+- `GET /payments/get?payment_id=...` returns one payment.
+- `POST /payments/complete` marks a pending payment as completed.
+- `POST /payments/cancel` marks a pending payment as canceled.
+- `POST /payments/fail` marks a pending payment as failed.
+
+`POST /payments/send` also supports an optional `idempotency_key` so retrying the
+same fake payment request does not create duplicate records.

lib/db/db-client.ts

@@ -1,17 +1,39 @@
-import { createStore, type StoreApi } from "zustand/vanilla"
+import { type HoistedStoreApi, hoist } from "zustand-hoist"
 import { immer } from "zustand/middleware/immer"
-import { hoist, type HoistedStoreApi } from "zustand-hoist"
+import { type StoreApi, createStore } from "zustand/vanilla"
 
-import { databaseSchema, type DatabaseSchema, type Thing } from "./schema.ts"
 import { combine } from "zustand/middleware"
+import {
+  type DatabaseSchema,
+  type Payment,
+  type PaymentStatus,
+  type Thing,
+  databaseSchema,
+} from "./schema.ts"
 
 export const createDatabase = () => {
   return hoist(createStore(initializer))
 }
 
 export type DbClient = ReturnType<typeof createDatabase>
 
-const initializer = combine(databaseSchema.parse({}), (set) => ({
+type SendPaymentInput = Pick<Payment, "recipient" | "amount"> &
+  Partial<
+    Pick<
+      Payment,
+      | "currency"
+      | "bounty_id"
+      | "issue_number"
+      | "repository"
+      | "idempotency_key"
+    >
+  >
+
+type ListPaymentsFilters = Partial<
+  Pick<Payment, "recipient" | "status" | "repository">
+>
+
+const initializer = combine(databaseSchema.parse({}), (set, get) => ({
   addThing: (thing: Omit<Thing, "thing_id">) => {
     set((state) => ({
       things: [
@@ -21,4 +43,82 @@ const initializer = combine(databaseSchema.parse({}), (set) => ({
       idCounter: state.idCounter + 1,
     }))
   },
+  sendPayment: (input: SendPaymentInput) => {
+    const idempotentPayment =
+      input.idempotency_key != null
+        ? get().payments.find(
+            (payment) => payment.idempotency_key === input.idempotency_key,
+          )
+        : undefined
+
+    if (idempotentPayment) {
+      return idempotentPayment
+    }
+
+    const now = new Date().toISOString()
+    const payment: Payment = {
+      payment_id: get().paymentIdCounter.toString(),
+      recipient: input.recipient,
+      amount: input.amount,
+      currency: input.currency ?? "USD",
+      status: "pending",
+      bounty_id: input.bounty_id,
+      issue_number: input.issue_number,
+      repository: input.repository,
+      idempotency_key: input.idempotency_key,
+      created_at: now,
+      updated_at: now,
+    }
+
+    set((state) => ({
+      payments: [...state.payments, payment],
+      paymentIdCounter: state.paymentIdCounter + 1,
+    }))
+
+    return payment
+  },
+  getPayment: (paymentId: string) => {
+    return get().payments.find((payment) => payment.payment_id === paymentId)
+  },
+  listPayments: (filters: ListPaymentsFilters = {}) => {
+    return get().payments.filter((payment) => {
+      if (filters.recipient && payment.recipient !== filters.recipient) {
+        return false
+      }
+      if (filters.status && payment.status !== filters.status) {
+        return false
+      }
+      if (filters.repository && payment.repository !== filters.repository) {
+        return false
+      }
+      return true
+    })
+  },
+  updatePaymentStatus: (paymentId: string, status: PaymentStatus) => {
+    const payment = get().payments.find(
+      (candidate) => candidate.payment_id === paymentId,
+    )
+
+    if (!payment) {
+      return undefined
+    }
+
+    if (payment.status !== "pending") {
+      return payment
+    }
+
+    const updatedPayment = {
+      ...payment,
+      status,
+      updated_at: new Date().toISOString(),
+    }
+
+    set((state) => ({
+      payments: state.payments.map((candidate) =>
+        candidate.payment_id === paymentId ? updatedPayment : candidate,
+      ),
+    }))
+
+    return updatedPayment
+  },
 }))

lib/db/schema.ts

@@ -9,8 +9,33 @@ export const thingSchema = z.object({
 })
 export type Thing = z.infer<typeof thingSchema>
 
+export const paymentStatusSchema = z.enum([
+  "pending",
+  "completed",
+  "canceled",
+  "failed",
+])
+export type PaymentStatus = z.infer<typeof paymentStatusSchema>
+
+export const paymentSchema = z.object({
+  payment_id: z.string(),
+  recipient: z.string(),
+  amount: z.number().positive(),
+  currency: z.string(),
+  status: paymentStatusSchema,
+  bounty_id: z.string().optional(),
+  issue_number: z.number().int().positive().optional(),
+  repository: z.string().optional(),
+  idempotency_key: z.string().optional(),
+  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),
   things: z.array(thingSchema).default([]),
+  paymentIdCounter: z.number().default(0),
+  payments: z.array(paymentSchema).default([]),
 })
 export type DatabaseSchema = z.infer<typeof databaseSchema>

lib/middleware/with-db.ts

@@ -2,14 +2,16 @@ import type { DbClient } from "lib/db/db-client"
 import { createDatabase } from "lib/db/db-client"
 import type { Middleware } from "winterspec"
 
+const fallbackDb = createDatabase()
+
 export const withDb: Middleware<
   {},
   {
     db: DbClient
   }
 > = async (req, ctx, next) => {
   if (!ctx.db) {
-    ctx.db = createDatabase()
+    ctx.db = fallbackDb
   }
   return next(req, ctx)
 }

lib/payments/response-schemas.ts

@@ -0,0 +1,14 @@
+import { paymentSchema } from "lib/db/schema"
+import { z } from "zod"
+
+export const paymentResponseSchema = z.object({
+  payment: paymentSchema,
+})
+
+export const paymentsResponseSchema = z.object({
+  payments: z.array(paymentSchema),
+})
+
+export const paymentErrorResponseSchema = z.object({
+  error: z.string(),
+})

routes/payments/cancel.ts

@@ -0,0 +1,25 @@
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import {
+  paymentErrorResponseSchema,
+  paymentResponseSchema,
+} from "lib/payments/response-schemas"
+import { z } from "zod"
+
+const paymentStatusRequestSchema = z.object({
+  payment_id: z.string().min(1),
+})
+
+export default withRouteSpec({
+  methods: ["POST"],
+  jsonBody: paymentStatusRequestSchema,
+  jsonResponse: paymentResponseSchema.or(paymentErrorResponseSchema),
+})(async (req, ctx) => {
+  const { payment_id } = paymentStatusRequestSchema.parse(await req.json())
+  const payment = ctx.db.updatePaymentStatus(payment_id, "canceled")
+
+  if (!payment) {
+    return ctx.json({ error: "Payment not found" }, { status: 404 })
+  }
+
+  return ctx.json({ payment })
+})

routes/payments/complete.ts

@@ -0,0 +1,25 @@
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import {
+  paymentErrorResponseSchema,
+  paymentResponseSchema,
+} from "lib/payments/response-schemas"
+import { z } from "zod"
+
+const paymentStatusRequestSchema = z.object({
+  payment_id: z.string().min(1),
+})
+
+export default withRouteSpec({
+  methods: ["POST"],
+  jsonBody: paymentStatusRequestSchema,
+  jsonResponse: paymentResponseSchema.or(paymentErrorResponseSchema),
+})(async (req, ctx) => {
+  const { payment_id } = paymentStatusRequestSchema.parse(await req.json())
+  const payment = ctx.db.updatePaymentStatus(payment_id, "completed")
+
+  if (!payment) {
+    return ctx.json({ error: "Payment not found" }, { status: 404 })
+  }
+
+  return ctx.json({ payment })
+})

routes/payments/fail.ts

@@ -0,0 +1,25 @@
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import {
+  paymentErrorResponseSchema,
+  paymentResponseSchema,
+} from "lib/payments/response-schemas"
+import { z } from "zod"
+
+const paymentStatusRequestSchema = z.object({
+  payment_id: z.string().min(1),
+})
+
+export default withRouteSpec({
+  methods: ["POST"],
+  jsonBody: paymentStatusRequestSchema,
+  jsonResponse: paymentResponseSchema.or(paymentErrorResponseSchema),
+})(async (req, ctx) => {
+  const { payment_id } = paymentStatusRequestSchema.parse(await req.json())
+  const payment = ctx.db.updatePaymentStatus(payment_id, "failed")
+
+  if (!payment) {
+    return ctx.json({ error: "Payment not found" }, { status: 404 })
+  }
+
+  return ctx.json({ payment })
+})

routes/payments/get.ts

@@ -0,0 +1,25 @@
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import {
+  paymentErrorResponseSchema,
+  paymentResponseSchema,
+} from "lib/payments/response-schemas"
+import { z } from "zod"
+
+const getPaymentQuerySchema = z.object({
+  payment_id: z.string().min(1),
+})
+
+export default withRouteSpec({
+  methods: ["GET"],
+  jsonResponse: paymentResponseSchema.or(paymentErrorResponseSchema),
+})(async (req, ctx) => {
+  const query = Object.fromEntries(new URL(req.url).searchParams.entries())
+  const { payment_id } = getPaymentQuerySchema.parse(query)
+  const payment = ctx.db.getPayment(payment_id)
+
+  if (!payment) {
+    return ctx.json({ error: "Payment not found" }, { status: 404 })
+  }
+
+  return ctx.json({ payment })
+})

routes/payments/list.ts

@@ -0,0 +1,22 @@
+import { paymentStatusSchema } from "lib/db/schema"
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import { paymentsResponseSchema } from "lib/payments/response-schemas"
+import { z } from "zod"
+
+const listPaymentQuerySchema = z.object({
+  recipient: z.string().optional(),
+  repository: z.string().optional(),
+  status: paymentStatusSchema.optional(),
+})
+
+export default withRouteSpec({
+  methods: ["GET"],
+  jsonResponse: paymentsResponseSchema,
+})(async (req, ctx) => {
+  const query = Object.fromEntries(new URL(req.url).searchParams.entries())
+  const filters = listPaymentQuerySchema.parse(query)
+
+  return ctx.json({
+    payments: ctx.db.listPayments(filters),
+  })
+})

routes/payments/send.ts

@@ -0,0 +1,24 @@
+import { withRouteSpec } from "lib/middleware/with-winter-spec"
+import { paymentResponseSchema } from "lib/payments/response-schemas"
+import { z } from "zod"
+
+const sendPaymentRequestSchema = z.object({
+  recipient: z.string().min(1),
+  amount: z.number().positive(),
+  currency: z.string().min(3).default("USD"),
+  bounty_id: z.string().optional(),
+  issue_number: z.number().int().positive().optional(),
+  repository: z.string().optional(),
+  idempotency_key: z.string().optional(),
+})
+
+export default withRouteSpec({
+  methods: ["POST"],
+  jsonBody: sendPaymentRequestSchema,
+  jsonResponse: paymentResponseSchema,
+})(async (req, ctx) => {
+  const paymentInput = sendPaymentRequestSchema.parse(await req.json())
+  const payment = ctx.db.sendPayment(paymentInput)
+
+  return ctx.json({ payment })
+})

tests/middleware/with-db.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "bun:test"
+import { createDatabase } from "lib/db/db-client"
+import { withDb } from "lib/middleware/with-db"
+
+const request = new Request("http://localhost/test") as any
+const next = async () => new Response("ok")
+
+test("reuses fallback db when middleware context has no db", async () => {
+  const firstContext: Record<string, unknown> = {}
+  const secondContext: Record<string, unknown> = {}
+
+  await withDb(request, firstContext as any, next as any)
+  await withDb(request, secondContext as any, next as any)
+
+  expect(firstContext.db).toBe(secondContext.db)
+})
+
+test("preserves db supplied by an outer middleware", async () => {
+  const suppliedDb = createDatabase()
+  const context = { db: suppliedDb }
+
+  await withDb(request, context as any, next as any)
+
+  expect(context.db).toBe(suppliedDb)
+})