# `schemas/notification-schemas`

## Purpose

Zod boundary schemas for the notification entity and every wire surface
the plugin exposes — list / get / create / update / mark-read /
mark-many-as-read / dismiss / delete / unread-count / grouped. The
schemas live inside the plugin because the suaveplan
`@suaveplan/api-schemas` package does not yet ship a `notification`
subpath; co-locating keeps the plugin self-contained until the upstream
package is augmented.

## Features

- Zod 4 default-import style (`import z from "zod"`) per CLAUDE.md.
- Twelve canonical notification types and six target types, both
  pinned by `z.enum(...)`.
- Passthrough `NotificationMetadataSchema` so callers may attach
  domain-specific fields without forking the schema.
- Query schema with `z.coerce.number()` / `z.coerce.boolean()` so
  query-string values arriving as strings parse cleanly.
- Response wrappers (`NotificationListResponseSchema`,
  `UnreadCountResponseSchema`, `GroupedNotificationsSchema`,
  `BulkOperationResponseSchema`) used by `createNotificationRoutes`.
- Param schema for `/:id` path captures (`NotificationIdParamSchema`).

## Usage: Basic

```ts
import { CreateNotificationSchema } from "@suaveplan/api-plugin-notifications";

const data = CreateNotificationSchema.parse({
    type: "friend_request",
    recipient: "user:abc",
    content: "sent you a friend request",
});
```

## Usage: Advanced

Compose with `@hono/zod-openapi`'s `createRoute` to produce an OpenAPI
schema and request validator in one step:

```ts
import { createRoute } from "@hono/zod-openapi";
import {
    CreateNotificationSchema,
    NotificationSchema,
} from "@suaveplan/api-plugin-notifications";

createRoute({
    method: "post",
    path: "/",
    request: {
        body: {
            content: {
                "application/json": { schema: CreateNotificationSchema },
            },
        },
    },
    responses: {
        201: {
            description: "Created",
            content: {
                "application/json": { schema: NotificationSchema },
            },
        },
    },
});
```

## API Reference

- `NotificationTypeSchema` / `NotificationType`
- `TargetTypeSchema` / `TargetType`
- `NotificationMetadataSchema` / `NotificationMetadata`
- `NotificationSchema` / `Notification`
- `CreateNotificationSchema` / `CreateNotification`
- `UpdateNotificationSchema` / `UpdateNotification`
- `NotificationQuerySchema` / `NotificationQuery`
- `NotificationListResponseSchema` / `NotificationListResponse`
- `UnreadCountResponseSchema` / `UnreadCountResponse`
- `GroupedNotificationsSchema` / `GroupedNotifications`
- `MarkManyAsReadSchema` / `MarkManyAsRead`
- `NotificationIdParamSchema` / `NotificationIdParam`
- `BulkOperationResponseSchema` / `BulkOperationResponse`

## Implementation Notes

`recipient`, `actor`, `target_id`, and `site` are typed as `z.string()`
rather than tightening to a SurrealDB record-id regex because tests and
upstream callers pass both bare ids (`abc`) and prefixed ids
(`user:abc`); the repository normalises on the way down. The schema
deliberately accepts both forms at the boundary so handlers can stay
permissive while persistence remains strict.