Initial Commit

packages/api-stack/api/api-plugin-payment/src/schemas/routes/empty-body.md

@@ -0,0 +1,42 @@
+# empty-body
+
+## Purpose
+
+Strict empty-object body schema shared by `POST /payments/intents/:id/confirm` and `POST /payments/intents/:id/cancel`. Both routes take their operand from the `:id` path parameter — there's no per-request input beyond the path. Hono/OpenAPI's body parser still requires a typed schema for documented routes, so this module supplies one explicit schema both routes import.
+
+Using a strict empty object (`z.object({}).strict()`) rather than `z.never()` or skipping the body schema entirely gives Hono a real validator to attach, ensures the OpenAPI doc lists `application/json` with an empty `properties: {}` object (and not `null`), and rejects accidental extra fields — a stray `{ amount: ... }` body on the confirm route would silently be ignored if the schema accepted unknowns, masking client-side bugs.
+
+## Features
+
+- `EmptyBodySchema` accepts `{}` only — rejects every extra key via `.strict()`.
+- Single import point so the confirm/cancel routes share one validator.
+
+## Usage: Basic
+
+```ts
+import { EmptyBodySchema } from "@suaveplan/api-plugin-payment/schemas/routes";
+
+EmptyBodySchema.parse({}); // ok
+const bad = EmptyBodySchema.safeParse({ amount: 1 });
+bad.success; // false
+```
+
+## Usage: Advanced
+
+```ts
+// confirm route — typed empty body
+const confirm = POST("/intents/{id}/confirm")
+    .params(PaymentIntentIdParamSchema)
+    .body(EmptyBodySchema)
+    .response(successResponse(PaymentIntentResponseSchema))
+    .build();
+```
+
+## API Reference
+
+- `EmptyBodySchema` — `z.object({}).strict()`.
+- `EmptyBody` — inferred TS type (`Record<string, never>`).
+
+## Implementation Notes
+
+Calling `.strict()` is important — Zod's default object behaviour is `passthrough` only with explicit `.passthrough()`, but in current Zod versions extra keys are silently stripped. `.strict()` raises a `ZodError` on extras so client bugs surface immediately. The `EmptyBody` type infers to `Record<string, never>` which TypeScript surfaces as `{}` at use sites — the right ergonomics for a route that takes no body.