@newhomestar/sdk 0.8.9 → 0.8.10

package/dist/events.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Register a Zod payload schema for emit-time validation.
+ * Called by `novaEndpoint()` in next.ts for each event that has a `payload` field.
+ * @internal
+ */
+export declare function registerEventPayloadSchema(slug: string, schema: {
+    safeParse: (data: unknown) => any;
+}): void;
+/**
+ * Look up a registered payload schema by event slug.
+ * Returns `undefined` if no schema was registered (validation is skipped).
+ * @internal
+ */
+export declare function getEventPayloadSchema(slug: string): {
+    safeParse: (data: unknown) => {
+        success: boolean;
+        error?: {
+            message?: string;
+            issues?: unknown[];
+        };
+    };
+} | undefined;
 /** Full request body for POST /events/queue */
 export interface QueueEventPayload {
     /**

package/dist/events.js

@@ -36,6 +36,34 @@ import { Agent as UndiciAgent } from 'undici';
 if (!process.env.NOVA_EVENTS_SERVICE_URL) {
     dotenv.config({ path: '.env.local', override: false });
 }
+// ── Event Payload Schema Registry ──────────────────────────────────────────────
+//
+// Module-level registry mapping event slugs to their Zod payload schemas.
+// Populated by `novaEndpoint()` (in next.ts) when events declare a `payload`
+// field. Used by `withServiceEventOutbox()` for emit-time validation:
+//   - development (NODE_ENV=development): validation failure throws immediately
+//   - production: validation failure logs a warning, event is still emitted
+//
+// This avoids coupling events.ts to Zod at the import level — we only call
+// `.safeParse()` on whatever object was registered (duck-typed).
+/** @internal */
+const _eventPayloadSchemas = new Map();
+/**
+ * Register a Zod payload schema for emit-time validation.
+ * Called by `novaEndpoint()` in next.ts for each event that has a `payload` field.
+ * @internal
+ */
+export function registerEventPayloadSchema(slug, schema) {
+    _eventPayloadSchemas.set(slug, schema);
+}
+/**
+ * Look up a registered payload schema by event slug.
+ * Returns `undefined` if no schema was registered (validation is skipped).
+ * @internal
+ */
+export function getEventPayloadSchema(slug) {
+    return _eventPayloadSchemas.get(slug);
+}
 // ── Internal helpers ───────────────────────────────────────────────────────────
 function _getEnvOrThrow(key, context) {
     const val = process.env[key];
@@ -178,8 +206,24 @@ export async function withServiceEventOutbox(db, reqOrCallback, maybeCallback) {
     const outboxRows = [];
     // ── Atomic: callback + outbox INSERTs in one transaction ─────────────────
     const result = await db.$transaction(async (tx) => {
-        // The emit fn is synchronous — events are staged and written after callback returns
+        // The emit fn is synchronous — events are staged and written after callback returns.
+        // If the event has a registered payload schema (from novaEndpoint), validate at emit time.
         const emit = (topic, payload, idempotencyKey) => {
+            // ── Emit-time payload validation ──────────────────────────────────
+            const payloadSchema = getEventPayloadSchema(topic);
+            if (payloadSchema) {
+                const result = payloadSchema.safeParse(payload);
+                if (!result.success) {
+                    const errorMsg = result.error?.message ?? JSON.stringify(result.error?.issues ?? 'unknown');
+                    const isDev = process.env.NODE_ENV === 'development';
+                    if (isDev) {
+                        throw new Error(`[nova/events] Payload validation failed for event "${topic}": ${errorMsg}`);
+                    }
+                    else {
+                        console.warn(`[nova/events] Payload validation warning for event "${topic}": ${errorMsg}`);
+                    }
+                }
+            }
             stagedEmits.push({ topic, payload, idempotencyKey });
         };
         const callbackResult = await callback(tx, emit);

package/dist/next.d.ts

@@ -296,6 +296,34 @@ export interface NovaEndpointEventDef {
     priority_level?: 'low' | 'medium' | 'high';
     /** Whether this event should trigger a push notification. Defaults to false. */
     triggers_notification?: boolean;
+    /**
+     * Optional Zod schema describing the shape of this event's payload (attributes).
+     *
+     * Used for:
+     * 1. **Emit-time validation** — `withServiceEventOutbox()` validates the payload
+     *    against this schema at emit time. In development mode (`NODE_ENV=development`),
+     *    validation failures throw immediately. In production, failures are logged as
+     *    warnings but the event is still emitted.
+     * 2. **JSON Schema generation** — `nova services push` converts this Zod schema to
+     *    JSON Schema via `zodToJsonSchema()` and stores it as `payload_schema` on the
+     *    event_type record in the Events Service. The Gamification Rule Builder UI uses
+     *    the JSON Schema to dynamically render filter forms.
+     *
+     * @example
+     * ```ts
+     * events: [{
+     *   slug: 'EMPLOYEE_UPDATED',
+     *   name: 'Employee Updated',
+     *   category: 'hris',
+     *   payload: z.object({
+     *     employee_id: z.string().uuid(),
+     *     changed_fields: z.array(z.string()),
+     *     department: z.string().optional(),
+     *   }),
+     * }]
+     * ```
+     */
+    payload?: ZodTypeAny;
 }
 /**
  * Human-readable metadata for a single permission slug.

package/dist/next.js

@@ -28,6 +28,7 @@
  * ```
  */
 import { z } from 'zod';
+import { registerEventPayloadSchema } from './events.js';
 // ─── Factory function ─────────────────────────────────────────────────────────
 /**
  * novaEndpoint() — define a Nova service endpoint co-located with its route.
@@ -46,6 +47,17 @@ import { z } from 'zod';
  * ```
  */
 export function novaEndpoint(cfg) {
+    // Register event payload schemas for emit-time validation.
+    // When a route file is imported, novaEndpoint() runs and populates the
+    // module-level registry in events.ts. withServiceEventOutbox() then uses
+    // the registry to validate payloads at emit time (throw in dev, warn in prod).
+    if (cfg.events) {
+        for (const evt of cfg.events) {
+            if (evt.payload) {
+                registerEventPayloadSchema(evt.slug, evt.payload);
+            }
+        }
+    }
     return {
         ...cfg,
         parseQuery(req) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.8.9",
+  "version": "0.8.10",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {