`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

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:

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.

3.1 KiB Raw Blame History

schemas/notification-schemas