# 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.