fix(nodejs): narrow required route parameters

rest/nodejs/src/api/checkout.ts

@@ -37,6 +37,7 @@ import {
   PaymentDataSchema,
   type PostalAddress,
 } from "../models";
+import { type IdParamContext } from "../utils/validation";
 
 /**
  * Schema for the request body when completing a checkout session.
@@ -494,8 +495,8 @@ export class CheckoutService {
     }
   };
 
-  getCheckout = async (c: Context) => {
-    const id = c.req.param("id");
+  getCheckout = async (c: IdParamContext) => {
+    const { id } = c.req.valid("param");
 
     // Log Request
     logRequest("GET", `/checkout-sessions/${id}`, id, {});
@@ -507,8 +508,8 @@ export class CheckoutService {
     return c.json(checkout, 200);
   };
 
-  updateCheckout = async (c: Context) => {
-    const id = c.req.param("id");
+  updateCheckout = async (c: IdParamContext) => {
+    const { id } = c.req.valid("param");
     const idempotencyKey = c.req.header("Idempotency-Key");
     const ucpAgent = c.req.header("UCP-Agent");
     const updateRequest = await c.req.json<ExtendedCheckoutUpdateRequest>();
@@ -627,8 +628,8 @@ export class CheckoutService {
     }
   };
 
-  completeCheckout = async (c: Context) => {
-    const id = c.req.param("id");
+  completeCheckout = async (c: IdParamContext) => {
+    const { id } = c.req.valid("param");
     const idempotencyKey = c.req.header("Idempotency-Key");
     const rawBody = await c.req.json<CompleteCheckoutRequest>();
     let requestHash = "";
@@ -863,8 +864,8 @@ export class CheckoutService {
     }
   };
 
-  cancelCheckout = async (c: Context) => {
-    const id = c.req.param("id");
+  cancelCheckout = async (c: IdParamContext) => {
+    const { id } = c.req.valid("param");
     const idempotencyKey = c.req.header("Idempotency-Key");
     const rawBody = {}; // Empty body for cancel usually
     let requestHash = "";

rest/nodejs/src/api/order.ts

@@ -1,13 +1,13 @@
-import { type Context } from "hono";
 import { getOrder, logRequest, saveOrder } from "../data";
 import { type Order } from "../models";
+import { type IdParamContext } from "../utils/validation";
 
 /**
  * Service for managing orders.
  */
 export class OrderService {
-  getOrder = async (c: Context) => {
-    const id = c.req.param("id");
+  getOrder = async (c: IdParamContext) => {
+    const { id } = c.req.valid("param");
 
     // Log Request
     logRequest("GET", `/orders/${id}`, undefined, {});
@@ -19,8 +19,8 @@ export class OrderService {
     return c.json(order, 200);
   };
 
-  updateOrder = async (c: Context) => {
-    const id = c.req.param("id");
+  updateOrder = async (c: IdParamContext) => {
+    const { id } = c.req.valid("param");
     const updateRequest = await c.req.json<Order>();
 
     // Log Request

rest/nodejs/src/api/testing.ts

@@ -1,11 +1,10 @@
-import { type Context } from "hono";
-
+import { type IdParamContext } from "../utils/validation";
 import { CheckoutService } from "./checkout";
 
 export class TestingService {
   constructor(private readonly checkoutService: CheckoutService) {}
 
-  shipOrder = async (c: Context) => {
+  shipOrder = async (c: IdParamContext) => {
     const secret = c.req.header("Simulation-Secret");
     const expectedSecret =
       process.env.SIMULATION_SECRET || "super-secret-sim-key";
@@ -14,7 +13,7 @@ export class TestingService {
       return c.json({ detail: "Invalid Simulation Secret" }, 403);
     }
 
-    const id = c.req.param("id");
+    const { id } = c.req.valid("param");
     try {
       await this.checkoutService.shipOrder(id);
       return c.json({ status: "shipped" }, 200);

rest/nodejs/src/utils/validation.ts

@@ -1,4 +1,4 @@
-import { type Context } from "hono";
+import { type Context, type Env } from "hono";
 import * as z from "zod";
 
 /**
@@ -36,3 +36,12 @@ export function prettyValidation<T>(
 export const IdParamSchema = z.object({
   id: z.string(),
 });
+
+export type IdParamContext = Context<
+  Env,
+  string,
+  {
+    in: { param: z.input<typeof IdParamSchema> };
+    out: { param: z.output<typeof IdParamSchema> };
+  }
+>;

rest/nodejs/test/validation.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { IdParamSchema } from "../src/utils/validation";
+
+test("accepts a required route ID", () => {
+  const result = IdParamSchema.safeParse({ id: "item-123" });
+
+  assert.equal(result.success, true);
+  if (result.success) {
+    assert.equal(result.data.id, "item-123");
+  }
+});
+
+test("rejects a missing route ID", () => {
+  const result = IdParamSchema.safeParse({});
+
+  assert.equal(result.success, false);
+});