Initial Commit

packages/api-stack/api/api-plugin-notifications/src/schemas/notification-schemas.md

@@ -0,0 +1,95 @@
+# `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.