Initial Commit

packages/api-stack/api/api-schemas/src/common/id-param.md

@@ -0,0 +1,62 @@
+# id-param
+
+## Purpose
+
+Provides Zod schemas for URL path parameter objects carrying resource identifiers. Rather than validating raw strings ad-hoc in every route handler, all Suaveplan endpoints that accept an `:id` segment share this schema, ensuring consistent error messages, type inference, and zero-duplication across the server plugin layer and generated OpenAPI documents.
+
+## Features
+
+- `IdParam` object schema — validates a single `{id: string}` path parameter (non-empty)
+- `NestedIdParam` object schema — validates `{parentId, id}` pairs for nested resource routes (e.g. `/orgs/:orgId/members/:id`)
+- Both schemas enforce non-empty strings, catching blank or missing identifiers before any database query is attempted
+- Full TypeScript inference via `z.infer<>` — no manual interface duplication
+- Zod v4 compatible
+
+## Usage: Basic Example
+
+```ts
+import { IdParam } from "@suaveplan/api-schemas/common";
+
+// Validate route params from an HTTP framework
+const params = IdParam.parse({ id: "user_01J8ZGCZ7ECTFAKEUID123456" });
+// → { id: "user_01J8ZGCZ7ECTFAKEUID123456" }
+```
+
+## Usage: Advanced Example
+
+```ts
+import { NestedIdParam } from "@suaveplan/api-schemas/common";
+
+// Validate nested resource route params: /orgs/:parentId/members/:id
+function getMember(rawParams: unknown) {
+  const { parentId, id } = NestedIdParam.parse(rawParams);
+  return db.member.findUnique({ where: { id, orgId: parentId } });
+}
+```
+
+## API Reference
+
+### `IdParam`
+
+Zod object schema for single-resource routes.
+
+| Field | Type             | Description                                    |
+|-------|------------------|------------------------------------------------|
+| `id`  | `string` (min 1) | Non-empty resource identifier from URL segment |
+
+**Type export:** `type IdParam = z.infer<typeof IdParam>`
+
+### `NestedIdParam`
+
+Zod object schema for nested-resource routes.
+
+| Field      | Type             | Description                      |
+|------------|------------------|----------------------------------|
+| `parentId` | `string` (min 1) | Parent resource identifier       |
+| `id`       | `string` (min 1) | Child resource identifier        |
+
+**Type export:** `type NestedIdParam = z.infer<typeof NestedIdParam>`
+
+## Implementation Notes
+
+Both schemas use `z.string().min(1)` rather than additional format constraints (UUID, ULID, etc.) to keep them format-agnostic. Suaveplan uses multiple ID formats depending on the domain (ULIDs for user-facing resources, SHA hashes for content-addressable objects, numeric sequences for legacy integrations). Services that require a specific format should compose these schemas with `.refine()` or `.regex()` at the route layer rather than tightening the shared base schema.