notifkit 0.1.3 → 0.1.5

package/src/contracts/envelope.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { EventMetadataSchema, type EventMetadata } from "./metadata.js";
+import type { EventPayloadMap, KnownEventType } from "./registry.js";
+
+/**
+ * Wire format written to Redis Streams. The payload field is an opaque record
+ * at the envelope level — use registry.parsePayload() to get a typed payload.
+ */
+export const EventEnvelopeSchema = z.object({
+  id: z.string().uuid(),
+  type: z.string(),
+  timestamp: z.string().datetime(),
+  payload: z.record(z.string(), z.unknown()),
+  metadata: EventMetadataSchema,
+});
+export type EventEnvelope = z.infer<typeof EventEnvelopeSchema>;
+
+/** Typed envelope where the payload is strongly typed via EventPayloadMap. */
+export type TypedEventEnvelope<K extends KnownEventType> = Omit<
+  EventEnvelope,
+  "type" | "payload"
+> & {
+  type: K;
+  payload: EventPayloadMap[K];
+};
+
+// Backward-compatible alias used by the queue / workers packages.
+export type StreamEvent = EventEnvelope;
+export const StreamEventSchema = EventEnvelopeSchema;
+export type StreamEventMetadata = EventMetadata;
+export const StreamEventMetadataSchema = EventMetadataSchema;

package/src/contracts/events/notification-ai-pending.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { NotificationChannelSchema, NotificationPrioritySchema } from "@/contracts/common.js";
+import { RecipientProfileSchema } from "./notification-enriched.js";
+
+export const NotificationAiPendingPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  enrichedEventId: z.string().uuid(),
+  recipientId: z.string().min(1),
+  channel: NotificationChannelSchema,
+  priority: NotificationPrioritySchema,
+  templateId: z.string().min(1).optional(),
+  templateVariables: z.record(z.string(), z.unknown()),
+  recipient: RecipientProfileSchema,
+  aiPrompts: z.record(z.string(), z.string()),
+  scheduledAt: z.string().datetime().optional(),
+  fallbackChain: z.array(NotificationChannelSchema).optional(),
+});
+export type NotificationAiPendingPayload = z.infer<typeof NotificationAiPendingPayloadSchema>;

package/src/contracts/events/notification-canceled.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+export const NotificationCanceledPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  taskId: z.string().min(1),
+});
+export type NotificationCanceledPayload = z.infer<typeof NotificationCanceledPayloadSchema>;

package/src/contracts/events/notification-created.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { NotificationChannelSchema, NotificationPrioritySchema } from "@/contracts/common.js";
+
+export const NotificationCreatedPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  recipientId: z.string().min(1),
+  channel: NotificationChannelSchema,
+  priority: NotificationPrioritySchema.default("normal"),
+  templateId: z.string().min(1).optional(),
+  payload: z.record(z.string(), z.unknown()),
+  scheduledAt: z.string().datetime().optional(),
+  idempotencyKey: z.string().optional(),
+});
+export type NotificationCreatedPayload = z.infer<typeof NotificationCreatedPayloadSchema>;

package/src/contracts/events/notification-delivered.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { NotificationChannelSchema } from "@/contracts/common.js";
+
+export const NotificationDeliveredPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  taskId: z.string().min(1),
+  enrichedEventId: z.string().uuid(),
+  channel: NotificationChannelSchema,
+  deliveredAt: z.string().datetime(),
+  providerMessageId: z.string().optional(),
+  providerResponse: z.record(z.string(), z.unknown()).optional(),
+  templateId: z.string().uuid().optional(),
+  workflowInstanceId: z.string().uuid().optional(),
+  /** Campaign this message belongs to, carried from the originating request. */
+  campaignId: z.string().min(1).max(128).optional(),
+});
+export type NotificationDeliveredPayload = z.infer<typeof NotificationDeliveredPayloadSchema>;

package/src/contracts/events/notification-dispatched.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { NotificationChannelSchema, NotificationPrioritySchema } from "@/contracts/common.js";
+import { RecipientProfileSchema } from "./notification-enriched.js";
+
+export const RenderedContentSchema = z.object({
+  content: z.record(z.string(), z.unknown()),
+  attachments: z
+    .array(
+      z.object({
+        name: z.string(),
+        contentType: z.string(),
+        url: z.string().url(),
+      }),
+    )
+    .optional(),
+});
+export type RenderedContent = z.infer<typeof RenderedContentSchema>;
+
+export const DeliveryOptionsSchema = z.object({
+  maxAttempts: z.number().int().positive().default(3),
+  timeoutMs: z.number().int().positive().default(10_000),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+export type DeliveryOptions = z.infer<typeof DeliveryOptionsSchema>;
+
+export const NotificationDispatchedPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  taskId: z.string().min(1),
+  enrichedEventId: z.string().uuid(),
+  recipientId: z.string().min(1),
+  channel: NotificationChannelSchema,
+  priority: NotificationPrioritySchema,
+  templateId: z.string().min(1).optional(),
+  templateVariables: z.record(z.string(), z.unknown()).default({}),
+  aiPrompts: z.record(z.string(), z.string()).optional(),
+  recipient: RecipientProfileSchema.optional(),
+  renderedContent: RenderedContentSchema,
+  destination: z.string().min(1).optional(),
+  deliveryOptions: DeliveryOptionsSchema,
+  fallbackChain: z.array(NotificationChannelSchema).optional(),
+  throttleAttemptCount: z.number().int().nonnegative().optional(),
+  /** Campaign this message belongs to, carried from the originating request. */
+  campaignId: z.string().min(1).max(128).optional(),
+});
+export type NotificationDispatchedPayload = z.infer<typeof NotificationDispatchedPayloadSchema>;

package/src/contracts/events/notification-enriched.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { NotificationChannelSchema, NotificationPrioritySchema } from "@/contracts/common.js";
+
+export const RecipientProfileSchema = z.object({
+  id: z.string(),
+  email: z.string().email().optional(),
+  phone: z.string().optional(),
+  webhook: z.string().url().optional(),
+  pushTokens: z.array(z.string()).optional(),
+  pushToken: z.string().optional(),
+  telegram: z.string().optional(),
+  discord: z.string().url().optional(),
+  slack: z.string().optional(),
+  locale: z.string().default("en"),
+  timezone: z.string().default("UTC"),
+  preferences: z.object({
+    optedOut: z.boolean().default(false),
+    channels: z.array(NotificationChannelSchema).default([]),
+    quietHours: z
+      .array(
+        z.object({
+          start: z.string(),
+          end: z.string(),
+        }),
+      )
+      .optional(),
+  }),
+});
+export type RecipientProfile = z.infer<typeof RecipientProfileSchema>;
+
+export const NotificationEnrichedPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  rawEventId: z.string().uuid(),
+  recipientId: z.string().min(1),
+  channel: NotificationChannelSchema,
+  priority: NotificationPrioritySchema,
+  templateId: z.string().min(1).optional(),
+  templateVariables: z.record(z.string(), z.unknown()),
+  recipient: RecipientProfileSchema,
+  aiPrompts: z.record(z.string(), z.string()).optional(),
+  scheduledAt: z.string().datetime().optional(),
+  fallbackChain: z.array(NotificationChannelSchema).optional(),
+  /** Campaign this message belongs to, carried from the originating request. */
+  campaignId: z.string().min(1).max(128).optional(),
+});
+export type NotificationEnrichedPayload = z.infer<typeof NotificationEnrichedPayloadSchema>;

package/src/contracts/events/notification-failed.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { NotificationChannelSchema } from "@/contracts/common.js";
+
+export const NotificationFailedPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  taskId: z.string().min(1),
+  enrichedEventId: z.string().uuid(),
+  channel: NotificationChannelSchema,
+  failureReason: z.string(),
+  failureCode: z.string(),
+  retryable: z.boolean(),
+  attempt: z.number().int().positive(),
+  providerResponse: z.record(z.string(), z.unknown()).optional(),
+  templateId: z.string().uuid().optional(),
+  workflowInstanceId: z.string().uuid().optional(),
+  /** Campaign this message belongs to, carried from the originating request. */
+  campaignId: z.string().min(1).max(128).optional(),
+});
+export type NotificationFailedPayload = z.infer<typeof NotificationFailedPayloadSchema>;

package/src/contracts/events/notification-requested.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { NotificationChannelSchema, NotificationPrioritySchema } from "@/contracts/common.js";
+
+/**
+ * A high-level notification request as issued by the SDK's `notify()` call.
+ *
+ * Unlike `notification.created` (which targets a single resolved recipient),
+ * this event carries the *unresolved* target — a user id, a segment, or a
+ * topic. A downstream resolver stage fans it out into one
+ * `notification.created` per matching recipient, applying preference filters.
+ */
+export const NotificationTargetSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("user"), userId: z.string().min(1) }),
+  z.object({ type: z.literal("segment"), segment: z.string().min(1) }),
+  z.object({ type: z.literal("topic"), topic: z.string().min(1) }),
+]);
+export type NotificationTarget = z.infer<typeof NotificationTargetSchema>;
+
+export const NotificationRequestedPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  target: NotificationTargetSchema,
+  templateId: z.string().min(1),
+  priority: NotificationPrioritySchema.default("normal"),
+  channels: z.array(NotificationChannelSchema).nonempty().optional(),
+  data: z.record(z.string(), z.unknown()).default({}),
+  fallback: z.boolean().default(false),
+  aiPrompts: z.record(z.string(), z.string()).optional(),
+  scheduledAt: z.string().datetime().optional(),
+  idempotencyKey: z.string().optional(),
+  /**
+   * Groups every message this request fans out into, so the send can be
+   * reported on afterwards. Carried unchanged to the delivery log.
+   */
+  campaignId: z.string().min(1).max(128).optional(),
+});
+export type NotificationRequestedPayload = z.infer<typeof NotificationRequestedPayloadSchema>;

package/src/contracts/events/notification-scheduled.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const NotificationScheduledPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  enrichedEventId: z.string().uuid(),
+  taskId: z.string().min(1),
+  scheduledAt: z.string().datetime(),
+});
+export type NotificationScheduledPayload = z.infer<typeof NotificationScheduledPayloadSchema>;

package/src/contracts/events/notification-skipped.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const NotificationSkippedPayloadSchema = z.object({
+  projectId: z.string().uuid(),
+  eventId: z.string().uuid(),
+  recipientId: z.string(),
+  reason: z.string(),
+});
+export type NotificationSkippedPayload = z.infer<typeof NotificationSkippedPayloadSchema>;

package/src/contracts/helpers.ts

@@ -0,0 +1,21 @@
+import { randomUUID } from "node:crypto";
+import { type EventEnvelope } from "./envelope.js";
+
+// Legacy factory helpers — backward compatible with the queue package's publish() API,
+// which accepts Omit<StreamEvent, "id" | "timestamp">.
+export function buildStreamEvent(
+  type: string,
+  payload: Record<string, unknown>,
+  source: string,
+  traceId?: string,
+): Omit<EventEnvelope, "id" | "timestamp"> {
+  return {
+    type,
+    payload,
+    metadata: {
+      traceId: traceId ?? randomUUID(),
+      source,
+      retryCount: 0,
+    },
+  };
+}

package/src/contracts/index.ts

@@ -0,0 +1,46 @@
+// Core building blocks
+export * from "./common.js";
+export * from "./metadata.js";
+export * from "./registry.js";
+export * from "./envelope.js";
+export * from "./streams.js";
+export * from "./helpers.js";
+export * from "./sdk.js";
+
+// Event payload schemas and types
+export * from "./events/notification-requested.js";
+export * from "./events/notification-created.js";
+export * from "./events/notification-enriched.js";
+export * from "./events/notification-scheduled.js";
+export * from "./events/notification-dispatched.js";
+export * from "./events/notification-delivered.js";
+export * from "./events/notification-failed.js";
+export * from "./events/notification-skipped.js";
+export * from "./events/notification-canceled.js";
+export * from "./events/notification-ai-pending.js";
+
+// Register all built-in event schemas in the global registry.
+// This runs once at module load time; call registry.define() in your own
+// module to add new event types without modifying this file.
+import { registry } from "./registry.js";
+import { NotificationRequestedPayloadSchema } from "./events/notification-requested.js";
+import { NotificationCreatedPayloadSchema } from "./events/notification-created.js";
+import { NotificationEnrichedPayloadSchema } from "./events/notification-enriched.js";
+import { NotificationScheduledPayloadSchema } from "./events/notification-scheduled.js";
+import { NotificationDispatchedPayloadSchema } from "./events/notification-dispatched.js";
+import { NotificationDeliveredPayloadSchema } from "./events/notification-delivered.js";
+import { NotificationFailedPayloadSchema } from "./events/notification-failed.js";
+import { NotificationSkippedPayloadSchema } from "./events/notification-skipped.js";
+import { NotificationCanceledPayloadSchema } from "./events/notification-canceled.js";
+import { NotificationAiPendingPayloadSchema } from "./events/notification-ai-pending.js";
+
+registry.define("notification.requested", NotificationRequestedPayloadSchema);
+registry.define("notification.created", NotificationCreatedPayloadSchema);
+registry.define("notification.enriched", NotificationEnrichedPayloadSchema);
+registry.define("notification.scheduled", NotificationScheduledPayloadSchema);
+registry.define("notification.dispatched", NotificationDispatchedPayloadSchema);
+registry.define("notification.delivered", NotificationDeliveredPayloadSchema);
+registry.define("notification.failed", NotificationFailedPayloadSchema);
+registry.define("notification.skipped", NotificationSkippedPayloadSchema);
+registry.define("notification.canceled", NotificationCanceledPayloadSchema);
+registry.define("notification.ai_pending", NotificationAiPendingPayloadSchema);

package/src/contracts/metadata.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const EventMetadataSchema = z.object({
+  traceId: z.string(),
+  source: z.string(),
+  retryCount: z.number().int().nonnegative().default(0),
+  correlationId: z.string().optional(),
+  causationId: z.string().optional(),
+});
+export type EventMetadata = z.infer<typeof EventMetadataSchema>;

package/src/contracts/registry.ts

@@ -0,0 +1,88 @@
+import { z, type ZodTypeAny, type ZodError } from "zod";
+import type { NotificationRequestedPayload } from "./events/notification-requested.js";
+import type { NotificationCreatedPayload } from "./events/notification-created.js";
+import type { NotificationEnrichedPayload } from "./events/notification-enriched.js";
+import type { NotificationScheduledPayload } from "./events/notification-scheduled.js";
+import type { NotificationDispatchedPayload } from "./events/notification-dispatched.js";
+import type { NotificationDeliveredPayload } from "./events/notification-delivered.js";
+import type { NotificationFailedPayload } from "./events/notification-failed.js";
+import type { NotificationSkippedPayload } from "./events/notification-skipped.js";
+import type { NotificationCanceledPayload } from "./events/notification-canceled.js";
+import type { NotificationAiPendingPayload } from "./events/notification-ai-pending.js";
+/**
+ * Built-in event payload types.
+ * External packages extend this interface via declaration merging:
+ *
+ *   declare module "../index.js" {
+ *     interface EventPayloadMap {
+ *       "my.custom.event": { field: string };
+ *     }
+ *   }
+ *
+ * Then call registry.define("my.custom.event", MySchema) at app startup.
+ */
+export interface EventPayloadMap {
+  "notification.requested": NotificationRequestedPayload;
+  "notification.created": NotificationCreatedPayload;
+  "notification.enriched": NotificationEnrichedPayload;
+  "notification.scheduled": NotificationScheduledPayload;
+  "notification.dispatched": NotificationDispatchedPayload;
+  "notification.delivered": NotificationDeliveredPayload;
+  "notification.failed": NotificationFailedPayload;
+  "notification.skipped": NotificationSkippedPayload;
+  "notification.canceled": NotificationCanceledPayload;
+  "notification.ai_pending": NotificationAiPendingPayload;
+}
+
+export type KnownEventType = keyof EventPayloadMap & string;
+
+export type ParseResult<T> = { success: true; data: T } | { success: false; error: ZodError };
+
+export class EventRegistry {
+  private readonly schemas = new Map<string, ZodTypeAny>();
+
+  define(type: string, schema: ZodTypeAny): void {
+    if (this.schemas.has(type)) {
+      throw new Error(`Event type "${type}" is already registered`);
+    }
+    this.schemas.set(type, schema);
+  }
+
+  getSchema(type: string): ZodTypeAny | undefined {
+    return this.schemas.get(type);
+  }
+
+  has(type: string): boolean {
+    return this.schemas.has(type);
+  }
+
+  types(): string[] {
+    return [...this.schemas.keys()];
+  }
+
+  parsePayload<K extends KnownEventType>(type: K, payload: unknown): EventPayloadMap[K] {
+    const schema = this.schemas.get(type);
+    if (!schema) throw new Error(`Unknown event type: "${type}"`);
+    return schema.parse(payload) as EventPayloadMap[K];
+  }
+
+  safeParsePayload<K extends KnownEventType>(
+    type: K,
+    payload: unknown,
+  ): ParseResult<EventPayloadMap[K]> {
+    const schema = this.schemas.get(type);
+    if (!schema) {
+      return {
+        success: false,
+        error: new z.ZodError([
+          { code: "custom", message: `Unknown event type: "${type}"`, path: [] },
+        ]),
+      };
+    }
+    const result = schema.safeParse(payload);
+    if (result.success) return { success: true, data: result.data as EventPayloadMap[K] };
+    return { success: false, error: result.error };
+  }
+}
+
+export const registry = new EventRegistry();