Use case: a REST API for users, products and orders

import { PGlite, type Transaction } from "@electric-sql/pglite";
import { createDatabaseClient, createMigrationRunner, noopDatabaseLogger } from "@zudojs/database";
import type { DatabaseClient, DatabaseTransactionContext, Migration, PrismaClientLike } from "@zudojs/database";

/* PostgreSQL error codes → the Prisma codes @zudojs/database turns into 409s and 404s. */
const CODES: Record<string, string> = { "23505": "P2002", "23503": "P2003", "40001": "P2034" };

function rawSql(db: PGlite | Transaction): DatabaseTransactionContext {
  async function run(sql: string, values: unknown[]) {
    try {
      return await db.query<Record<string, unknown>>(sql, values);
    } catch (error) {
      const code = CODES[(error as { code?: string }).code ?? ""];
      throw code ? Object.assign(new Error((error as Error).message), { code, clientVersion: "pglite" }) : error;
    }
  }
  return {
    $queryRawUnsafe: async <T>(sql: string, ...values: unknown[]) => (await run(sql, values)).rows as T,
    $executeRawUnsafe: async (sql: string, ...values: unknown[]) => (await run(sql, values)).affectedRows ?? 0,
    $queryRaw: () => Promise.reject(new Error("Use $queryRawUnsafe with $1 parameters")),
    $executeRaw: () => Promise.reject(new Error("Use $executeRawUnsafe with $1 parameters")),
  };
}

const SCHEMA = [
  `CREATE TABLE users (
     id serial PRIMARY KEY,
     email text NOT NULL UNIQUE,
     name text NOT NULL,
     password_hash text NOT NULL,
     role text NOT NULL DEFAULT 'customer' CHECK (role IN ('customer', 'admin')))`,
  `CREATE TABLE products (
     id serial PRIMARY KEY,
     sku text NOT NULL UNIQUE,
     name text NOT NULL,
     category text NOT NULL,
     price_kobo integer NOT NULL CHECK (price_kobo > 0),
     stock integer NOT NULL CHECK (stock >= 0))`,
  `CREATE TABLE orders (
     id serial PRIMARY KEY,
     user_id integer NOT NULL REFERENCES users (id),
     status text NOT NULL DEFAULT 'placed' CHECK (status IN ('placed', 'cancelled')),
     total_kobo integer NOT NULL CHECK (total_kobo > 0),
     created_at timestamptz NOT NULL DEFAULT now())`,
  `CREATE TABLE order_lines (
     order_id integer NOT NULL REFERENCES orders (id),
     product_id integer NOT NULL REFERENCES products (id),
     quantity integer NOT NULL CHECK (quantity > 0),
     price_kobo integer NOT NULL,
     PRIMARY KEY (order_id, product_id))`,
  "CREATE INDEX orders_user_idx ON orders (user_id, id)",
  "CREATE INDEX products_category_idx ON products (category, id)",
];

const migrations: Migration[] = [
  {
    version: 1,
    name: "create-market",
    up: async (tx) => {
      for (const statement of SCHEMA) await tx.$executeRawUnsafe(statement);
    },
  },
];

export async function openDatabase(): Promise<DatabaseClient> {
  const pg = new PGlite();
  const prisma: PrismaClientLike = {
    ...rawSql(pg),
    $connect: async () => { await pg.waitReady; },
    $disconnect: async () => { if (!pg.closed) await pg.close(); },
    $transaction: <T>(work: (tx: DatabaseTransactionContext) => Promise<T>) => pg.transaction((tx) => work(rawSql(tx))),
  };
  const client = createDatabaseClient({ prisma, logger: noopDatabaseLogger });
  await client.connect();
  await createMigrationRunner(client, migrations).migrate();
  return client;
}

import { openDatabase } from "./db.js";

const db = await openDatabase();
const tables = await db.queryRawUnsafe<{ name: string }[]>(
  "SELECT tablename AS name FROM pg_tables WHERE schemaname = 'public' ORDER BY 1",
);
console.log(tables.map((t) => t.name));

const broken = [
  "INSERT INTO products (sku, name, category, price_kobo, stock) VALUES ('rice-5kg', 'Rice', 'grains', 0, 5)",
  "INSERT INTO products (sku, name, category, price_kobo, stock) VALUES ('rice-5kg', 'Rice', 'grains', 1250000, -1)",
];
for (const sql of broken) {
  try {
    await db.executeRawUnsafe(sql);
  } catch (error) {
    console.log("refused:", (error as Error).message);
  }
}
await db.disconnect();

[ '_migrations', 'order_lines', 'orders', 'products', 'users' ]
refused: new row for relation "products" violates check constraint "products_price_kobo_check"
refused: new row for relation "products" violates check constraint "products_stock_check"

import { schema } from "@zudojs/schema";
import type { Infer } from "@zudojs/schema";

export const CATEGORIES = ["grains", "drinks", "spices", "household"] as const;

/* What clients send. */
export const Register = schema.object({
  email: schema.string().trim().toLowerCase().email().max(254),
  name: schema.string().trim().min(1).max(80),
  password: schema.string().min(12).max(128),
});
export const Login = schema.object({
  email: schema.string().trim().toLowerCase().max(254),
  password: schema.string().min(1).max(128),
});
export const NewProduct = schema.object({
  sku: schema.string().regex(/^[a-z0-9-]{3,40}$/),
  name: schema.string().trim().min(2).max(100),
  category: schema.enum(CATEGORIES),
  priceKobo: schema.number().int().min(1).max(10_000_000),
  stock: schema.number().int().min(0).max(100_000),
});
export const ProductPatch = NewProduct.omit(["sku"]).partial().strict();
export const ProductQuery = schema.object({
  category: schema.optional(schema.enum(CATEGORIES)),
  limit: schema.default(schema.coerce.number().int().min(1).max(50), 20),
  cursor: schema.optional(schema.string().max(200)),
});
export const IdParams = schema.object({ id: schema.coerce.number().int().min(1).max(2_147_483_647) });
export const NewOrder = schema.object({
  items: schema
    .array(schema.object({ productId: schema.number().int().min(1), quantity: schema.number().int().min(1).max(10) }))
    .min(1)
    .max(20),
});

/* What the API sends back: allow-lists, so internal columns never leak. */
export const UserOut = schema.object({
  id: schema.number().int(),
  email: schema.string(),
  name: schema.string(),
  role: schema.enum(["customer", "admin"] as const),
});
export const ProductOut = schema.object({
  id: schema.number().int(),
  sku: schema.string(),
  name: schema.string(),
  category: schema.enum(CATEGORIES),
  priceKobo: schema.number().int(),
  stock: schema.number().int(),
});
export const ProductPage = schema.object({
  data: schema.array(ProductOut),
  nextCursor: schema.nullable(schema.string()),
});
export const OrderOut = schema.object({
  id: schema.number().int(),
  status: schema.enum(["placed", "cancelled"] as const),
  totalKobo: schema.number().int(),
  items: schema.array(schema.object({ productId: schema.number().int(), quantity: schema.number().int(), priceKobo: schema.number().int() })),
});
export const OrderList = schema.array(OrderOut);
export const TokenOut = schema.object({ accessToken: schema.string(), tokenType: schema.string(), expiresIn: schema.number().int() });
export const ErrorOut = schema.object({
  error: schema.object({
    code: schema.string(),
    message: schema.string(),
    issues: schema.optional(schema.array(schema.object({ path: schema.string(), message: schema.string() }))),
    requestId: schema.optional(schema.string()),
  }),
});

export type UserOut = Infer<typeof UserOut>;
export type ProductOut = Infer<typeof ProductOut>;
export type OrderOut = Infer<typeof OrderOut>;

import type { Schema } from "@zudojs/schema";
import { NewOrder, ProductPatch, ProductQuery, Register, UserOut } from "./schemas.js";

function show(label: string, schema: Schema<unknown>, input: unknown): void {
  const result = schema.safeParse(input);
  const text = result.success
    ? JSON.stringify(result.data)
    : result.issues.map((issue) => `${issue.path.join(".") || "(body)"}: ${issue.message}`).join("; ");
  console.log(`${label.padEnd(18)} ${text}`);
}

show("register", Register, { email: " Ada@Example.com ", name: "Ada", password: "ada's long passphrase", role: "admin" });
show("query strings", ProductQuery, { category: "drinks", limit: "5" });
show("query defaults", ProductQuery, {});
show("query too big", ProductQuery, { limit: "5000" });
show("patch", ProductPatch, { priceKobo: 0, sku: "cheap" });
show("order", NewOrder, { items: [{ productId: 1, quantity: 11 }] });
show("user out", UserOut, { id: 1, email: "ada@example.com", name: "Ada", role: "customer", password_hash: "scrypt$..." });

register           {"email":"ada@example.com","name":"Ada","password":"ada's long passphrase"}
query strings      {"category":"drinks","limit":5}
query defaults     {"limit":20}
query too big      limit: Expected <= 50, received 5000
patch              priceKobo: Expected >= 1, received 0; (body): Unknown key: sku
order              items.0.quantity: Expected <= 10, received 11
user out           {"id":1,"email":"ada@example.com","name":"Ada","role":"customer"}

import { createTokenPair, hashPassword, parseBearerToken, toUserId, verifyAccessToken, verifyPassword } from "@zudojs/auth";
import type { TokenConfig } from "@zudojs/auth";
import type { DatabaseClient } from "@zudojs/database";
import { AuthenticationError, AuthorizationError, ConflictError } from "@zudojs/errors";
import type { HttpMiddleware, HttpRouterContext } from "@zudojs/http";
import { Login, Register, UserOut } from "./schemas.js";

const USER_COLUMNS = "id, email, name, role";

export function createUsers(db: DatabaseClient, tokens: TokenConfig) {
  const decoy = hashPassword("decoy password for unknown e-mails");

  /** Middleware: a valid access token, and a user that still exists. */
  const requireUser: HttpMiddleware = async (ctx, next) => {
    const token = parseBearerToken(ctx.request.getHeader("authorization"));
    const result = token === null ? null : verifyAccessToken(token, tokens);
    if (!result?.valid || result.payload === undefined) throw new AuthenticationError("Send a valid access token");
    const [user] = await db.queryRawUnsafe<UserOut[]>(`SELECT ${USER_COLUMNS} FROM users WHERE id = $1`, [
      Number(result.payload.sub),
    ]);
    if (!user) throw new AuthenticationError("Send a valid access token");
    ctx.state.set("user", user);
    return next();
  };

  return {
    requireUser,

    async register(input: unknown): Promise<UserOut> {
      const { email, name, password } = Register.parse(input);
      const rows = await db.queryRawUnsafe<UserOut[]>(
        `INSERT INTO users (email, name, password_hash) VALUES ($1, $2, $3)
         ON CONFLICT (email) DO NOTHING RETURNING ${USER_COLUMNS}`,
        [email, name, await hashPassword(password)],
      );
      if (!rows[0]) throw new ConflictError("An account with this e-mail already exists");
      return UserOut.parse(rows[0]);
    },

    async login(input: unknown) {
      const { email, password } = Login.parse(input);
      const [row] = await db.queryRawUnsafe<{ id: number; password_hash: string }[]>(
        "SELECT id, password_hash FROM users WHERE email = $1",
        [email],
      );
      const valid = await verifyPassword(password, row?.password_hash ?? (await decoy));
      if (!row || !valid) throw new AuthenticationError("Wrong e-mail or password");
      const pair = createTokenPair(toUserId(String(row.id)), tokens);
      return { accessToken: pair.accessToken, tokenType: pair.tokenType, expiresIn: pair.expiresIn };
    },
  };
}

export function currentUser(ctx: HttpRouterContext): UserOut {
  const user = ctx.state.get("user") as UserOut | undefined;
  if (!user) throw new Error("requireUser is missing on this route");
  return user;
}

export function requireAdmin(ctx: HttpRouterContext): UserOut {
  const user = currentUser(ctx);
  if (user.role !== "admin") throw new AuthorizationError("Only admins may do this");
  return user;
}

import type { DatabaseClient } from "@zudojs/database";
import { decodeCursor, encodeCursor } from "@zudojs/database";
import { NotFoundError } from "@zudojs/errors";
import { NewProduct, ProductOut, ProductPatch, ProductQuery } from "./schemas.js";

const SELECT = `SELECT id, sku, name, category, price_kobo AS "priceKobo", stock FROM products`;

export function createProducts(db: DatabaseClient, cursorSecret: string) {
  return {
    async list(query: unknown) {
      const { category, limit, cursor } = ProductQuery.parse(query);
      const after = cursor === undefined ? 0 : decodeCursor<{ id: number }>(cursor, { secret: cursorSecret, allowedFields: ["id"] }).id;
      const rows = await db.queryRawUnsafe<ProductOut[]>(
        `${SELECT} WHERE ($1::text IS NULL OR category = $1) AND id > $2 ORDER BY id LIMIT $3`,
        [category ?? null, after, limit + 1],
      );
      const data = rows.slice(0, limit);
      const last = data.at(-1);
      const nextCursor = rows.length > limit && last ? encodeCursor({ id: last.id }, { secret: cursorSecret }) : null;
      return { data, nextCursor };
    },

    async get(id: number): Promise<ProductOut> {
      const [row] = await db.queryRawUnsafe<ProductOut[]>(`${SELECT} WHERE id = $1`, [id]);
      if (!row) throw new NotFoundError(`Product ${id} not found`);
      return row;
    },

    async create(input: unknown): Promise<ProductOut> {
      const p = NewProduct.parse(input);
      const [row] = await db.queryRawUnsafe<ProductOut[]>(
        `INSERT INTO products (sku, name, category, price_kobo, stock) VALUES ($1, $2, $3, $4, $5)
         RETURNING id, sku, name, category, price_kobo AS "priceKobo", stock`,
        [p.sku, p.name, p.category, p.priceKobo, p.stock],
      );
      return row!;
    },

    async update(id: number, input: unknown): Promise<ProductOut> {
      const patch = ProductPatch.parse(input);
      const [row] = await db.queryRawUnsafe<ProductOut[]>(
        `UPDATE products SET name = COALESCE($2, name), category = COALESCE($3, category),
           price_kobo = COALESCE($4, price_kobo), stock = COALESCE($5, stock)
         WHERE id = $1 RETURNING id, sku, name, category, price_kobo AS "priceKobo", stock`,
        [id, patch.name ?? null, patch.category ?? null, patch.priceKobo ?? null, patch.stock ?? null],
      );
      if (!row) throw new NotFoundError(`Product ${id} not found`);
      return row;
    },
  };
}

import type { DatabaseClient } from "@zudojs/database";
import { withTransaction } from "@zudojs/database";
import { ConflictError, DomainError, NotFoundError } from "@zudojs/errors";
import { NewOrder, type OrderOut } from "./schemas.js";

interface Line { productId: number; quantity: number; priceKobo: number }

export function createOrders(db: DatabaseClient) {
  async function load(userId: number, orderId: number): Promise<OrderOut> {
    const [order] = await db.queryRawUnsafe<{ id: number; status: OrderOut["status"]; totalKobo: number }[]>(
      `SELECT id, status, total_kobo AS "totalKobo" FROM orders WHERE id = $1 AND user_id = $2`,
      [orderId, userId],
    );
    if (!order) throw new NotFoundError(`Order ${orderId} not found`);
    const items = await db.queryRawUnsafe<Line[]>(
      `SELECT product_id AS "productId", quantity, price_kobo AS "priceKobo" FROM order_lines WHERE order_id = $1 ORDER BY product_id`,
      [orderId],
    );
    return { ...order, items };
  }

  return {
    load,

    async place(userId: number, input: unknown): Promise<OrderOut> {
      const { items } = NewOrder.parse(input);
      const ids = items.map((item) => item.productId);
      if (new Set(ids).size !== ids.length) throw new DomainError("List each product once", { code: "DUPLICATE_ITEM" });

      const orderId = await withTransaction(db, async (tx) => {
        const lines: Line[] = [];
        for (const { productId, quantity } of items) {
          const [taken] = await tx.$queryRawUnsafe<{ price_kobo: number }[]>(
            "UPDATE products SET stock = stock - $1 WHERE id = $2 AND stock >= $1 RETURNING price_kobo",
            quantity, productId,
          );
          if (!taken) {
            const [exists] = await tx.$queryRawUnsafe<unknown[]>("SELECT 1 FROM products WHERE id = $1", productId);
            if (!exists) throw new DomainError(`Product ${productId} does not exist`, { code: "UNKNOWN_PRODUCT" });
            throw new ConflictError(`Not enough stock for product ${productId}`);
          }
          lines.push({ productId, quantity, priceKobo: taken.price_kobo });
        }
        const total = lines.reduce((sum, line) => sum + line.priceKobo * line.quantity, 0);
        const [order] = await tx.$queryRawUnsafe<{ id: number }[]>(
          "INSERT INTO orders (user_id, total_kobo) VALUES ($1, $2) RETURNING id", userId, total,
        );
        for (const line of lines) {
          await tx.$executeRawUnsafe(
            "INSERT INTO order_lines (order_id, product_id, quantity, price_kobo) VALUES ($1, $2, $3, $4)",
            order!.id, line.productId, line.quantity, line.priceKobo,
          );
        }
        return order!.id;
      });
      return load(userId, orderId);
    },

    async listMine(userId: number) {
      const rows = await db.queryRawUnsafe<{ id: number }[]>("SELECT id FROM orders WHERE user_id = $1 ORDER BY id DESC LIMIT 50", [userId]);
      return Promise.all(rows.map((row) => load(userId, row.id)));
    },

    async cancel(userId: number, orderId: number): Promise<OrderOut> {
      await withTransaction(db, async (tx) => {
        const [order] = await tx.$queryRawUnsafe<{ id: number }[]>(
          "UPDATE orders SET status = 'cancelled' WHERE id = $1 AND user_id = $2 AND status = 'placed' RETURNING id",
          orderId, userId,
        );
        if (!order) {
          const [mine] = await tx.$queryRawUnsafe<unknown[]>("SELECT 1 FROM orders WHERE id = $1 AND user_id = $2", orderId, userId);
          if (!mine) throw new NotFoundError(`Order ${orderId} not found`);
          return; // already cancelled: nothing to do, and no stock goes back twice
        }
        await tx.$executeRawUnsafe(
          "UPDATE products p SET stock = p.stock + l.quantity FROM order_lines l WHERE l.order_id = $1 AND p.id = l.product_id",
          orderId,
        );
      });
      return load(userId, orderId);
    },
  };
}

import { randomUUID } from "node:crypto";
import { normalizeToBaseError } from "@zudojs/errors";
import { createResponseContext, type HttpRequestContext } from "@zudojs/http";
import type { Logger } from "@zudojs/logger";
import { isSchemaValidationError } from "@zudojs/schema";

/** One error shape for every route: { error: { code, message, issues?, requestId? } }. */
export function createErrorHandler(logger: Logger) {
  return (thrown: unknown, request: HttpRequestContext) => {
    if (isSchemaValidationError(thrown)) {
      const issues = thrown.issues.map((issue) => ({ path: issue.path.join(".") || "(body)", message: issue.message }));
      return createResponseContext({ status: 400 }).json({ error: { code: "VALIDATION_FAILED", message: "The request is not valid", issues } });
    }
    const error = normalizeToBaseError(thrown);
    if (error.expose && error.statusCode < 500) {
      return createResponseContext({ status: error.statusCode }).json({ error: { code: error.code, message: error.message } });
    }
    const requestId = randomUUID();
    logger.error("Request failed", { requestId, method: request.method, path: request.path, error: thrown instanceof Error ? thrown : String(thrown) });
    return createResponseContext({ status: 500 }).json({ error: { code: "INTERNAL", message: "Something went wrong on our side", requestId } });
  };
}

import { DomainError, serializePublicError } from "@zudojs/errors";
import { createRequestContext } from "@zudojs/http";
import { createLogger } from "@zudojs/logger";
import { createErrorHandler } from "./errors.js";

const error = new DomainError("Product 99 does not exist", {
  code: "UNKNOWN_PRODUCT",
  metadata: { productId: 99, warehouse: "lagos-ikeja-2", supplierCost: 910000 },
});
console.log("serializePublicError:", serializePublicError(error).metadata);

const handle = createErrorHandler(createLogger({ name: "demo", transports: [] }));
const response = await handle(error, createRequestContext({ method: "POST", url: "/v1/orders" }));
console.log("our handler:", response.status, response.body);

serializePublicError: { productId: 99, warehouse: 'lagos-ikeja-2', supplierCost: 910000 }
our handler: 422 {"error":{"code":"UNKNOWN_PRODUCT","message":"Product 99 does not exist"}}

import type { TokenConfig } from "@zudojs/auth";
import type { DatabaseClient } from "@zudojs/database";
import {
  badRequest, createHttpServer, createNodeHttpAdapter, createRateLimitMiddleware, createResponseContext, createRouter, mountOpenAPI,
} from "@zudojs/http";
import type { HttpRouterContext } from "@zudojs/http";
import type { Logger } from "@zudojs/logger";
import { createComponentReference } from "@zudojs/openapi";
import { createErrorHandler } from "./errors.js";
import { createOrders } from "./orders.js";
import { createProducts } from "./products.js";
import * as S from "./schemas.js";
import { createUsers, currentUser, requireAdmin } from "./users.js";

export interface ApiOptions {
  readonly db: DatabaseClient;
  readonly tokens: TokenConfig;
  readonly cursorSecret: string;
  readonly logger: Logger;
}

function body(ctx: HttpRouterContext): unknown {
  if (!(ctx.request.getHeader("content-type") ?? "").startsWith("application/json")) throw badRequest("Send JSON with Content-Type: application/json");
  try {
    return JSON.parse(new TextDecoder().decode(ctx.request.body as Uint8Array));
  } catch {
    throw badRequest("The body is not valid JSON");
  }
}
const id = (ctx: HttpRouterContext) => S.IdParams.parse(ctx.params).id;
const ref = (name: string) => createComponentReference("schemas", name);
const errors = (...codes: string[]) => Object.fromEntries(codes.map((code) => [code, { schema: ref("Error") }]));
const created = (location: string, data: unknown) => createResponseContext({ status: 201 }).setHeader("location", location).json(data);

export function createApi({ db, tokens, cursorSecret, logger }: ApiOptions) {
  const users = createUsers(db, tokens);
  const products = createProducts(db, cursorSecret);
  const orders = createOrders(db);
  const signedIn = [users.requireUser];
  const bearer = [{ bearerAuth: [] }];
  const router = createRouter({
    notFoundHandler: () => createResponseContext({ status: 404 }).json({ error: { code: "NO_SUCH_ROUTE", message: "No such route" } }),
    methodNotAllowedHandler: (_ctx, allowed) =>
      createResponseContext({ status: 405 }).setHeader("allow", allowed.join(", "))
        .json({ error: { code: "METHOD_NOT_ALLOWED", message: `Use ${allowed.join(" or ")}` } }),
  });

  router.post("/v1/users", async (ctx) => {
    const user = await users.register(body(ctx));
    return created(`/v1/users/${user.id}`, user);
  }, { openapi: { operationId: "users.register", tags: ["Users"], security: [], body: S.Register,
    responses: { "201": { schema: ref("User") }, ...errors("400", "409") } } });

  router.post("/v1/tokens", async (ctx) => createResponseContext().json(await users.login(body(ctx))), {
    middleware: [createRateLimitMiddleware({ max: 10, windowMs: 60_000 })],
    openapi: { operationId: "tokens.create", tags: ["Users"], security: [], body: S.Login,
      responses: { "200": { schema: ref("Token") }, ...errors("400", "401", "429") } } });

  router.get("/v1/users/me", (ctx) => currentUser(ctx), { middleware: signedIn,
    openapi: { operationId: "users.me", tags: ["Users"], security: bearer, responses: { "200": { schema: ref("User") }, ...errors("401") } } });

  router.get("/v1/products", async (ctx) => products.list(ctx.query), {
    openapi: { operationId: "products.list", tags: ["Products"], security: [], query: S.ProductQuery,
      responses: { "200": { schema: ref("ProductPage") }, ...errors("400") } } });

  router.get("/v1/products/:id", async (ctx) => products.get(id(ctx)), {
    openapi: { operationId: "products.get", tags: ["Products"], security: [], params: S.IdParams,
      responses: { "200": { schema: ref("Product") }, ...errors("400", "404") } } });

  router.post("/v1/products", async (ctx) => {
    requireAdmin(ctx);
    const product = await products.create(body(ctx));
    return created(`/v1/products/${product.id}`, product);
  }, { middleware: signedIn, openapi: { operationId: "products.create", tags: ["Products"], security: bearer, body: S.NewProduct,
    responses: { "201": { schema: ref("Product") }, ...errors("400", "401", "403", "409") } } });

  router.patch("/v1/products/:id", async (ctx) => {
    requireAdmin(ctx);
    return products.update(id(ctx), body(ctx));
  }, { middleware: signedIn, openapi: { operationId: "products.update", tags: ["Products"], security: bearer, params: S.IdParams, body: S.ProductPatch,
    responses: { "200": { schema: ref("Product") }, ...errors("400", "401", "403", "404") } } });

  router.post("/v1/orders", async (ctx) => {
    const order = await orders.place(currentUser(ctx).id, body(ctx));
    return created(`/v1/orders/${order.id}`, order);
  }, { middleware: signedIn, openapi: { operationId: "orders.place", tags: ["Orders"], security: bearer, body: S.NewOrder,
    responses: { "201": { schema: ref("Order") }, ...errors("400", "401", "409", "422") } } });

  router.get("/v1/orders", async (ctx) => orders.listMine(currentUser(ctx).id), { middleware: signedIn,
    openapi: { operationId: "orders.list", tags: ["Orders"], security: bearer,
      responses: { "200": { schema: ref("OrderList") }, ...errors("401") } } });

  router.get("/v1/orders/:id", async (ctx) => orders.load(currentUser(ctx).id, id(ctx)), { middleware: signedIn,
    openapi: { operationId: "orders.get", tags: ["Orders"], security: bearer, params: S.IdParams,
      responses: { "200": { schema: ref("Order") }, ...errors("400", "401", "404") } } });

  router.post("/v1/orders/:id/cancel", async (ctx) => orders.cancel(currentUser(ctx).id, id(ctx)), { middleware: signedIn,
    openapi: { operationId: "orders.cancel", tags: ["Orders"], security: bearer, params: S.IdParams,
      responses: { "200": { schema: ref("Order") }, ...errors("400", "401", "404") } } });

  const docs = mountOpenAPI(router, {
    info: { title: "Oja Market API", version: "1.0.0" },
    securitySchemes: { bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" } },
    schemas: { User: S.UserOut, Token: S.TokenOut, Product: S.ProductOut, ProductPage: S.ProductPage, Order: S.OrderOut, OrderList: S.OrderList, Error: S.ErrorOut },
    validate: true,
    branding: false,
  });

  const server = createHttpServer({
    adapter: createNodeHttpAdapter({ host: "127.0.0.1", port: 0 }),
    handler: async (request) => (await router.dispatch(request)).response,
    errorHandler: createErrorHandler(logger),
  });
  return { server, docs, router, requireUser: users.requireUser };
}

import { randomBytes } from "node:crypto";
import { createLogger, createTextLoggerFormatter } from "@zudojs/logger";
import { createApi } from "./api.js";
import { openDatabase } from "./db.js";

/* DEMO ONLY: random secrets for each run. Your app reads them from the environment. */
const secret = () => randomBytes(32).toString("base64url");

export interface Reply {
  readonly status: number;
  readonly headers: Headers;
  readonly body: any; // test helper: the contract check below verifies the shape
}

/** Starts the whole API on a free port, with an empty database. */
export async function startMarket(log: (line: string) => void = console.log) {
  const db = await openDatabase();
  const logger = createLogger({
    name: "oja",
    formatter: createTextLoggerFormatter({ includeTimestamp: false }),
    transports: [
      (entry) => {
        const { requestId, error } = entry.metadata as { requestId?: string; error?: { name: string; message: string } };
        log(`[${entry.levelName}] ${entry.message} requestId=${requestId} ${error?.name}: ${error?.message}`);
      },
    ],
  });
  const api = createApi({
    db,
    logger,
    tokens: { accessSecret: secret(), refreshSecret: secret(), accessTtl: 15 * 60, issuer: "oja", audience: "oja-api" },
    cursorSecret: secret(),
  });
  await api.server.start();
  const base = `http://127.0.0.1:${api.server.address?.port}`;

  async function call(method: string, path: string, data?: unknown, token?: string): Promise<Reply> {
    const response = await fetch(base + path, {
      method,
      headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
      body: data === undefined ? undefined : JSON.stringify(data),
    });
    const text = await response.text();
    return { status: response.status, headers: response.headers, body: text ? JSON.parse(text) : null };
  }

  async function signUp(email: string, role: "customer" | "admin" = "customer"): Promise<string> {
    const password = `${email} long passphrase`;
    await call("POST", "/v1/users", { email, name: email.split("@")[0], password });
    if (role === "admin") await db.executeRawUnsafe("UPDATE users SET role = 'admin' WHERE email = $1", [email]);
    return (await call("POST", "/v1/tokens", { email, password })).body.accessToken;
  }

  async function stop(): Promise<void> {
    await api.server.stop();
    await db.disconnect();
  }

  return { db, base, call, signUp, stop, docs: api.docs, router: api.router, requireUser: api.requireUser };
}

import { startMarket, type Reply } from "./market.js";

const market = await startMarket();
const { call } = market;
function show(label: string, reply: Reply): void {
  const error = reply.body?.error;
  console.log(`${label} -> ${reply.status}`, error ? `${error.code}: ${error.message}` : "");
}

const admin = await market.signUp("admin@oja.test", "admin");
for (const product of [
  { sku: "rice-5kg", name: "Ofada rice 5 kg", category: "grains", priceKobo: 1_250_000, stock: 3 },
  { sku: "palm-oil-1l", name: "Palm oil 1 l", category: "household", priceKobo: 280_000, stock: 10 },
  { sku: "zobo-500ml", name: "Zobo 500 ml", category: "drinks", priceKobo: 50_000, stock: 40 },
]) {
  const reply = await call("POST", "/v1/products", product, admin);
  console.log("create product ->", reply.status, reply.headers.get("location"));
}

const password = "ada's long passphrase";
const joined = await call("POST", "/v1/users", { email: " Ada@Example.com ", name: "Ada", password, role: "admin" });
console.log("register ->", joined.status, joined.body);
show("register again", await call("POST", "/v1/users", { email: "ada@example.com", name: "Ada", password }));
show("wrong password", await call("POST", "/v1/tokens", { email: "ada@example.com", password: "guess" }));
const login = await call("POST", "/v1/tokens", { email: "ada@example.com", password });
console.log("log in ->", login.status, login.body.tokenType, login.body.expiresIn);
const ada = login.body.accessToken;

show("Ada adds a product", await call("POST", "/v1/products", { sku: "free", name: "Free", category: "grains", priceKobo: 1, stock: 9 }, ada));
const order = await call("POST", "/v1/orders", { items: [{ productId: 1, quantity: 2 }, { productId: 3, quantity: 4 }] }, ada);
console.log("place order ->", order.status, order.headers.get("location"), order.body);
show("rice again", await call("POST", "/v1/orders", { items: [{ productId: 3, quantity: 1 }, { productId: 1, quantity: 2 }] }, ada));
show("unknown product", await call("POST", "/v1/orders", { items: [{ productId: 99, quantity: 1 }] }, ada));
show("no token", await call("GET", "/v1/orders"));
const bola = await market.signUp("bola@example.com");
show("Bola reads Ada's order", await call("GET", "/v1/orders/1", undefined, bola));

const shelf = await call("GET", "/v1/products");
console.log(shelf.body.data.map((p: { sku: string; stock: number }) => `${p.sku}: ${p.stock}`).join(", "));
await market.stop();

create product -> 201 /v1/products/1
create product -> 201 /v1/products/2
create product -> 201 /v1/products/3
register -> 201 { id: 2, email: 'ada@example.com', name: 'Ada', role: 'customer' }
register again -> 409 ERR_CONFLICT: An account with this e-mail already exists
wrong password -> 401 ERR_AUTHENTICATION_FAILED: Wrong e-mail or password
log in -> 200 Bearer 900
Ada adds a product -> 403 ERR_FORBIDDEN: Only admins may do this
place order -> 201 /v1/orders/1 {
  id: 1,
  status: 'placed',
  totalKobo: 2700000,
  items: [
    { productId: 1, quantity: 2, priceKobo: 1250000 },
    { productId: 3, quantity: 4, priceKobo: 50000 }
  ]
}
rice again -> 409 ERR_CONFLICT: Not enough stock for product 1
unknown product -> 422 UNKNOWN_PRODUCT: Product 99 does not exist
no token -> 401 ERR_AUTHENTICATION_FAILED: Send a valid access token
Bola reads Ada's order -> 404 ERR_RESOURCE_NOT_FOUND: Order 1 not found
rice-5kg: 1, palm-oil-1l: 10, zobo-500ml: 36

import { startMarket } from "./market.js";

const market = await startMarket();
const admin = await market.signUp("admin@oja.test", "admin");
const add = (sku: string, category: string) =>
  market.call("POST", "/v1/products", { sku, name: sku, category, priceKobo: 100_000, stock: 5 }, admin);
for (const sku of ["beans-1kg", "garri-2kg", "zobo-500ml", "rice-5kg", "pepper-soup-mix"]) {
  await add(sku, sku.startsWith("zobo") ? "drinks" : sku.startsWith("pepper") ? "spices" : "grains");
}

let path = "/v1/products?category=grains&limit=2";
for (let page = 1; path; page++) {
  const reply = await market.call("GET", path);
  console.log(`page ${page}:`, reply.body.data.map((p: { sku: string }) => p.sku), reply.body.nextCursor ? "more" : "last");
  if (page === 1) await add("millet-1kg", "grains"); // a new product appears while the client is paging
  path = reply.body.nextCursor ? `/v1/products?category=grains&limit=2&cursor=${reply.body.nextCursor}` : "";
}

const first = await market.call("GET", "/v1/products?limit=2");
const [, signature] = first.body.nextCursor.split(".");
const forged = `${Buffer.from('{"id":0}').toString("base64url")}.${signature}`;
for (const query of [`cursor=${forged}`, "limit=500", "category=cars"]) {
  const { status, body } = await market.call("GET", `/v1/products?${query}`);
  console.log(query.split("=")[0], "->", status, body.error.message, body.error.issues ?? "");
}
await market.stop();

page 1: [ 'beans-1kg', 'garri-2kg' ] more
page 2: [ 'rice-5kg', 'millet-1kg' ] last
cursor -> 400 Invalid pagination cursor signature.
limit -> 400 The request is not valid [ { path: 'limit', message: 'Expected <= 50, received 500' } ]
category -> 400 The request is not valid [
  {
    path: 'category',
    message: 'Expected one of "grains", "drinks", "spices", "household"'
  }
]

import { startMarket } from "./market.js";

const market = await startMarket();
const document = market.docs.document();
console.log(document.openapi, document.info.title);
for (const [path, item] of Object.entries(document.paths)) {
  for (const [method, operation] of Object.entries(item ?? {})) {
    const op = operation as { operationId: string; security?: unknown[] };
    const auth = op.security?.length === 0 ? "public" : "bearer";
    console.log(method.toUpperCase().padEnd(6), path.padEnd(22), op.operationId.padEnd(16), auth);
  }
}
console.log(JSON.stringify(document.paths["/v1/products"]?.get?.parameters?.[1]));

const spec = await fetch(`${market.base}/openapi.json`);
const docsPage = await fetch(`${market.base}/docs`);
console.log(spec.status, spec.headers.get("content-type"), "|", docsPage.status, docsPage.headers.get("content-type"));
await market.stop();

3.1.0 Oja Market API
POST   /v1/users              users.register   public
POST   /v1/tokens             tokens.create    public
GET    /v1/users/me           users.me         bearer
GET    /v1/products           products.list    public
POST   /v1/products           products.create  bearer
GET    /v1/products/{id}      products.get     public
PATCH  /v1/products/{id}      products.update  bearer
POST   /v1/orders             orders.place     bearer
GET    /v1/orders             orders.list      bearer
GET    /v1/orders/{id}        orders.get       bearer
POST   /v1/orders/{id}/cancel orders.cancel    bearer
{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}
200 application/json; charset=utf-8 | 200 text/html; charset=utf-8

import { Ajv2020 } from "ajv/dist/2020.js";
import type { OpenAPIDocument } from "@zudojs/openapi";

const METHODS = ["get", "post", "put", "patch", "delete"] as const;

/** Checks a real response against the OpenAPI document the server publishes. */
export function createContractCheck(doc: OpenAPIDocument) {
  const ajv = new Ajv2020({ strict: false, allErrors: true });
  ajv.addSchema({ $id: "api", components: doc.components });

  return function check(operationId: string, status: number, body: unknown): string[] {
    const operation = Object.values(doc.paths)
      .flatMap((item) => METHODS.map((method) => item?.[method]))
      .find((op) => op?.operationId === operationId);
    if (!operation) return [`no operation ${operationId}`];
    const response = operation.responses?.[String(status)];
    if (!response) return [`${operationId} does not document status ${status}`];
    const schema = "content" in response ? response.content?.["application/json"]?.schema : undefined;
    const ref = (schema as { $ref?: string } | undefined)?.$ref;
    const validate = ref === undefined ? undefined : ajv.getSchema(`api${ref}`);
    if (!validate) return [`${operationId} ${status} has no JSON schema to check`];
    return validate(body) ? [] : (validate.errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message}`);
  };
}

import { createContractCheck } from "./contract.js";
import { startMarket } from "./market.js";

const market = await startMarket();
const check = createContractCheck(market.docs.document());
const admin = await market.signUp("admin@oja.test", "admin");

const created = await market.call("POST", "/v1/products", { sku: "rice-5kg", name: "Rice", category: "grains", priceKobo: 1_250_000, stock: 3 }, admin);
console.log("products.create 201:", check("products.create", created.status, created.body));
const list = await market.call("GET", "/v1/products");
console.log("products.list 200:", check("products.list", list.status, list.body));
const denied = await market.call("POST", "/v1/orders", { items: [] });
console.log("orders.place 401:", check("orders.place", denied.status, denied.body));

// What a careless change would send: a price in naira as a string, and an internal column.
const drifted = { ...created.body, priceKobo: "12500.00", cost_kobo: 900_000 };
console.log("drifted product:", check("products.get", 200, drifted));
console.log("undocumented status:", check("products.get", 418, {}));
await market.stop();

products.create 201: []
products.list 200: []
orders.place 401: []
drifted product: [ '/priceKobo must be integer' ]
undocumented status: [ 'products.get does not document status 418' ]

import { startMarket } from "./market.js";

const market = await startMarket();
await market.db.executeRawUnsafe("ALTER TABLE products RENAME TO products_old"); // a bad deploy

const reply = await market.call("GET", "/v1/products");
console.log(reply.status, reply.body);

const missing = await market.call("GET", "/v1/prodcts");
const wrongMethod = await market.call("DELETE", "/v1/products");
console.log(missing.status, missing.body.error, "|", wrongMethod.status, wrongMethod.headers.get("allow"), wrongMethod.body.error.code);
await market.stop();

[error] Request failed requestId=458a35ba-e4d7-4870-98b5-644a3c4ad7c9 DatabaseError: relation "products" does not exist
500 {
  error: {
    code: 'INTERNAL',
    message: 'Something went wrong on our side',
    requestId: '458a35ba-e4d7-4870-98b5-644a3c4ad7c9'
  }
}
404 { code: 'NO_SUCH_ROUTE', message: 'No such route' } | 405 GET, POST METHOD_NOT_ALLOWED

import { defineConfig } from "vitest/config";

export default defineConfig({ test: { include: ["tests/**/*.test.ts"], testTimeout: 20_000, hookTimeout: 30_000 } });

import { startVitest } from "vitest/node";

/** Runs test files with Vitest and prints one line per test. */
export async function runTests(...files: string[]): Promise<void> {
  const vitest = await startVitest("test", files, { watch: false, reporters: [] });
  for (const file of vitest.state.getTestModules()) {
    for (const error of file.errors()) console.log(`× ${file.relativeModuleId}: ${error.message}`);
    for (const test of file.children.allTests()) {
      const { state, errors = [] } = test.result();
      console.log(`${state === "passed" ? "✓" : "×"} ${test.fullName}`);
      for (const error of errors) console.log(`    ${error.message}`);
    }
  }
  await vitest.close();
}

import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
import { createContractCheck } from "../contract.js";
import { startMarket } from "../market.js";

let market: Awaited<ReturnType<typeof startMarket>>;
let admin: string;
let ada: string;
let check: ReturnType<typeof createContractCheck>;
const logs: string[] = [];

beforeAll(async () => {
  market = await startMarket((line) => logs.push(line));
  check = createContractCheck(market.docs.document());
  admin = await market.signUp("admin@oja.test", "admin");
  ada = await market.signUp("ada@example.com");
});
afterAll(() => market.stop());

beforeEach(async () => {
  logs.length = 0;
  await market.db.executeRawUnsafe("TRUNCATE products, orders, order_lines RESTART IDENTITY");
  for (const [sku, stock] of [["rice-5kg", 3], ["palm-oil-1l", 10]] as const) {
    await market.call("POST", "/v1/products", { sku, name: sku, category: "grains", priceKobo: 1000, stock }, admin);
  }
});

const stockOf = async (id: number) => (await market.call("GET", `/v1/products/${id}`)).body.stock;

describe("Oja Market API", () => {
  it("never takes a role from the request body", async () => {
    const res = await market.call("POST", "/v1/users", { email: "eve@example.com", name: "Eve", password: "eve long passphrase", role: "admin" });
    expect(res.status).toBe(201);
    expect(res.body.role).toBe("customer");
  });

  it("answers every mistake with the documented error shape", async () => {
    const cases = [
      ["products.create", await market.call("POST", "/v1/products", { sku: "x" }, admin), 400],
      ["products.create", await market.call("POST", "/v1/products", { sku: "tea", name: "Tea", category: "drinks", priceKobo: 1, stock: 1 }), 401],
      ["products.create", await market.call("POST", "/v1/products", { sku: "tea", name: "Tea", category: "drinks", priceKobo: 1, stock: 1 }, ada), 403],
      ["products.get", await market.call("GET", "/v1/products/999"), 404],
      ["orders.place", await market.call("POST", "/v1/orders", { items: [{ productId: 1, quantity: 9 }] }, ada), 409],
      ["orders.place", await market.call("POST", "/v1/orders", { items: [{ productId: 77, quantity: 1 }] }, ada), 422],
    ] as const;
    for (const [operation, res, status] of cases) {
      expect(res.status).toBe(status);
      expect(check(operation, res.status, res.body)).toEqual([]);
    }
  });

  it("keeps orders private: someone else's order is 404", async () => {
    const order = await market.call("POST", "/v1/orders", { items: [{ productId: 1, quantity: 1 }] }, ada);
    const bola = await market.signUp("bola@example.com");
    expect((await market.call("GET", `/v1/orders/${order.body.id}`, undefined, bola)).status).toBe(404);
    expect((await market.call("POST", `/v1/orders/${order.body.id}/cancel`, undefined, bola)).status).toBe(404);
    expect((await market.call("GET", "/v1/orders", undefined, bola)).body).toEqual([]);
  });

  it("rolls back every line when one line fails", async () => {
    const res = await market.call("POST", "/v1/orders", { items: [{ productId: 2, quantity: 5 }, { productId: 1, quantity: 4 }] }, ada);
    expect(res.status).toBe(409);
    expect(await stockOf(2)).toBe(10);
  });

  it("puts the stock back once, however often an order is cancelled", async () => {
    const order = await market.call("POST", "/v1/orders", { items: [{ productId: 1, quantity: 2 }] }, ada);
    for (let i = 0; i < 3; i++) {
      const res = await market.call("POST", `/v1/orders/${order.body.id}/cancel`, undefined, ada);
      expect(res.body.status).toBe("cancelled");
    }
    expect(await stockOf(1)).toBe(3);
  });

  it("pages never repeat or skip, even when products are added between pages", async () => {
    const first = await market.call("GET", "/v1/products?limit=1");
    await market.call("POST", "/v1/products", { sku: "zobo", name: "Zobo", category: "drinks", priceKobo: 500, stock: 1 }, admin);
    const second = await market.call("GET", `/v1/products?limit=1&cursor=${first.body.nextCursor}`);
    const third = await market.call("GET", `/v1/products?limit=1&cursor=${second.body.nextCursor}`);
    expect([first, second, third].flatMap((page) => page.body.data.map((p: { sku: string }) => p.sku))).toEqual(["rice-5kg", "palm-oil-1l", "zobo"]);
    expect(third.body.nextCursor).toBeNull();
    const forged = `${Buffer.from('{"id":0}').toString("base64url")}.${first.body.nextCursor.split(".")[1]}`;
    expect((await market.call("GET", `/v1/products?cursor=${forged}`)).status).toBe(400);
  });

  it("hides the reason for a 500 from the client but logs it with a request id", async () => {
    await market.db.executeRawUnsafe("ALTER TABLE products RENAME TO products_old");
    const res = await market.call("GET", "/v1/products");
    await market.db.executeRawUnsafe("ALTER TABLE products_old RENAME TO products");
    expect(res.status).toBe(500);
    expect(JSON.stringify(res.body)).not.toContain("products");
    expect(logs).toEqual([expect.stringContaining(`requestId=${res.body.error.requestId}`)]);
  });
});