notifkit 0.1.2 → 0.1.4

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();

package/src/contracts/sdk.ts

@@ -0,0 +1,242 @@
+import { z } from "zod";
+import { NotificationChannelSchema, NotificationPrioritySchema } from "./common.js";
+
+// ─── Preferences ──────────────────────────────────────────────────────────────
+//
+// Preferences are stored as JSONB and are intentionally open-ended so new
+// channels/topics can be added without a migration. `channels` and `topics`
+// are boolean opt-in maps; `quietHours` is a list of UTC HH:MM windows.
+
+export const QuietHoursSchema = z.object({
+  start: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "expected HH:MM (24h, UTC)"),
+  end: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "expected HH:MM (24h, UTC)"),
+});
+export type QuietHours = z.infer<typeof QuietHoursSchema>;
+
+export const PreferencesSchema = z.object({
+  channels: z.record(z.string(), z.boolean()).optional(),
+  topics: z.record(z.string(), z.boolean()).optional(),
+  quietHours: z.array(QuietHoursSchema).optional(),
+});
+export type Preferences = z.infer<typeof PreferencesSchema>;
+
+// ─── Contacts ─────────────────────────────────────────────────────────────────
+
+/** Channels that carry an addressable target (email address, phone, push token, url, chat id). */
+export const ContactChannelSchema = z.enum([
+  "email",
+  "sms",
+  "push",
+  "webhook",
+  "telegram",
+  "discord",
+  "whatsapp",
+  "slack",
+]);
+export type ContactChannel = z.infer<typeof ContactChannelSchema>;
+
+/** Accept a single value or an array; always normalise to a non-empty array. */
+const stringOrArray = z
+  .union([z.string().min(1), z.array(z.string().min(1))])
+  .transform((v) => (Array.isArray(v) ? v : [v]));
+
+// ─── Users ────────────────────────────────────────────────────────────────────
+
+/**
+ * addUser({ id, email, phone, pushToken, segments, preferences })
+ * email / phone / pushToken accept a single string or an array.
+ */
+export const AddUserSchema = z.object({
+  id: z.string().min(1),
+  language: z.string().optional(),
+  timezone: z.string().optional(),
+  email: stringOrArray.optional(),
+  phone: stringOrArray.optional(),
+  pushToken: stringOrArray.optional(),
+  segments: z.array(z.string().min(1)).optional(),
+  preferences: PreferencesSchema.optional(),
+});
+export type AddUserInput = z.input<typeof AddUserSchema>;
+
+/** updateUser(id, patch) — every field optional; id comes from the path. */
+export const UpdateUserSchema = z.object({
+  language: z.string().optional(),
+  timezone: z.string().optional(),
+  email: stringOrArray.optional(),
+  phone: stringOrArray.optional(),
+  pushToken: stringOrArray.optional(),
+  segments: z.array(z.string().min(1)).optional(),
+  preferences: PreferencesSchema.optional(),
+});
+export type UpdateUserInput = z.input<typeof UpdateUserSchema>;
+
+/** addUserContact(userId, channel, { target, preferences }) — channel carried in body. */
+export const AddContactSchema = z.object({
+  channel: ContactChannelSchema,
+  target: z.string().min(1),
+  preferences: PreferencesSchema.optional(),
+});
+export type AddContactInput = z.infer<typeof AddContactSchema>;
+
+// ─── Templates ────────────────────────────────────────────────────────────────
+
+export const TemplateSchema = z.object({
+  id: z.string().min(1),
+  channel: NotificationChannelSchema,
+  topic: z
+    .union([z.string().min(1), z.array(z.string().min(1))])
+    .transform((v) => (Array.isArray(v) ? v : [v]))
+    .optional(),
+  content: z.record(z.string(), z.unknown()),
+  aiPrompts: z.record(z.string(), z.string()).optional(),
+});
+export type TemplateInput = z.infer<typeof TemplateSchema>;
+
+export const SyncTemplatesSchema = z.object({
+  templates: z.array(TemplateSchema).min(1),
+});
+export type SyncTemplatesInput = z.infer<typeof SyncTemplatesSchema>;
+
+// ─── notify() ─────────────────────────────────────────────────────────────────
+
+/** Inline user object accepted by notify({ user: {...} }). */
+export const InlineUserSchema = z.object({
+  id: z.string().min(1),
+  language: z.string().optional(),
+  timezone: z.string().optional(),
+  email: stringOrArray.optional(),
+  phone: stringOrArray.optional(),
+  pushToken: stringOrArray.optional(),
+  segments: z.array(z.string().min(1)).optional(),
+  preferences: PreferencesSchema.optional(),
+});
+export type InlineUser = z.infer<typeof InlineUserSchema>;
+
+/**
+ * notify(...) request body.
+ *
+ * Exactly one of `user` / `segment` / `topic` must be provided.
+ */
+/**
+ * The field set shared by `notify()` and a workflow's `notify` step. The two
+ * differ only in whether naming a target is mandatory, so the fields live here
+ * once and each schema layers its own target rule on top.
+ */
+const NotifyRequestFields = z.object({
+  user: z
+    .union([
+      z.string().min(1),
+      InlineUserSchema,
+      z.array(z.union([z.string().min(1), InlineUserSchema])).nonempty(),
+    ])
+    .optional(),
+  segment: z.string().min(1).optional(),
+  topic: z.string().min(1).optional(),
+  template: z.string().min(1),
+  data: z.record(z.string(), z.unknown()).optional(),
+  aiPrompts: z.record(z.string(), z.string()).optional(),
+  priority: NotificationPrioritySchema.optional(),
+  channels: z.array(NotificationChannelSchema).nonempty().optional(),
+  fallback: z.boolean().optional(),
+  sendAt: z.string().datetime().optional(),
+  /**
+   * A label grouping every message this call produces, so the send can be
+   * reported on later via `/v1/campaigns/:id/stats`. Free-form, but reusing one
+   * label across calls merges them into a single campaign — which is either
+   * what you want (a send split into batches) or a reporting bug.
+   */
+  campaign: z.string().min(1).max(128).optional(),
+});
+
+function countTargets(val: { user?: unknown; segment?: unknown; topic?: unknown }): number {
+  return [val.user, val.segment, val.topic].filter((t) => t !== undefined).length;
+}
+
+export const NotifyRequestSchema = NotifyRequestFields.superRefine((val, ctx) => {
+  const targets = countTargets(val);
+  if (targets === 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "one of `user`, `segment`, or `topic` is required",
+      path: ["user"],
+    });
+  } else if (targets > 1) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "provide exactly one of `user`, `segment`, or `topic`",
+      path: ["user"],
+    });
+  }
+});
+export type NotifyRequestInput = z.input<typeof NotifyRequestSchema>;
+
+/**
+ * The payload of a workflow `notify` step — every field `notify()` takes.
+ *
+ * The one difference is that a target is optional here: a step naming none
+ * inherits the instance's own user, which is the ordinary case. Naming one
+ * overrides that, so a step can notify a different user, a segment, or a topic.
+ */
+export const WorkflowNotifyPayloadSchema = NotifyRequestFields.superRefine((val, ctx) => {
+  if (countTargets(val) > 1) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "provide at most one of `user`, `segment`, or `topic`",
+      path: ["user"],
+    });
+  }
+});
+export type WorkflowNotifyInput = z.input<typeof WorkflowNotifyPayloadSchema>;
+
+// ─── Workflows ────────────────────────────────────────────────────────────────
+
+export const TriggerWorkflowSchema = z.object({
+  name: z.string().min(1),
+  input: z.record(z.string(), z.unknown()).optional(),
+  user: z.union([z.string().min(1), InlineUserSchema]).optional(),
+});
+export type TriggerWorkflowInput = z.infer<typeof TriggerWorkflowSchema>;
+
+// ─── Events ───────────────────────────────────────────────────────────────────
+
+export const IngestEventSchema = z.object({
+  name: z.string().min(1),
+  properties: z.record(z.string(), z.unknown()),
+});
+export type IngestEventInput = z.infer<typeof IngestEventSchema>;
+
+export const WorkflowStepSchema = z.discriminatedUnion("action", [
+  z.object({
+    action: z.literal("notify"),
+    payload: WorkflowNotifyPayloadSchema,
+  }),
+  z.object({
+    action: z.literal("wait"),
+    duration: z.string(), // e.g. "1h", "5m"
+  }),
+  z.object({
+    action: z.literal("waitForEvent"),
+    event: z.string(),
+    options: z
+      .object({
+        timeout: z.string().optional(), // e.g. "24h"
+      })
+      .optional(),
+  }),
+]);
+export type WorkflowStepDef = z.infer<typeof WorkflowStepSchema>;
+
+export const CreateWorkflowSchema = z.object({
+  name: z.string().min(1),
+  steps: z.array(WorkflowStepSchema).min(1),
+});
+export type CreateWorkflowInput = z.infer<typeof CreateWorkflowSchema>;
+
+// ─── Projects ─────────────────────────────────────────────────────────────────
+
+export const UpdateProjectSchema = z.object({
+  rateLimitRpm: z.number().nullable().optional(),
+  throttleLimit: z.number().nullable().optional(),
+  throttleWindowHours: z.number().nullable().optional(),
+});
+export type UpdateProjectInput = z.infer<typeof UpdateProjectSchema>;

package/src/contracts/streams.ts

@@ -0,0 +1,62 @@
+export const STREAMS = {
+  INBOUND_CRITICAL: "notifkit:stream:inbound:critical",
+  INBOUND_NORMAL: "notifkit:stream:inbound:normal",
+  INBOUND_LOW: "notifkit:stream:inbound:low",
+  ENRICHED_CRITICAL: "notifkit:stream:enriched:critical",
+  ENRICHED_NORMAL: "notifkit:stream:enriched:normal",
+  ENRICHED_LOW: "notifkit:stream:enriched:low",
+  AI_PENDING: "notifkit:stream:ai:pending",
+  SCHEDULED: "notifkit:stream:scheduled",
+  OUTBOUND_CRITICAL: "notifkit:stream:outbound:critical",
+  OUTBOUND_NORMAL: "notifkit:stream:outbound:normal",
+  OUTBOUND_LOW: "notifkit:stream:outbound:low",
+  DEAD_LETTER: "notifkit:stream:dlq",
+  WORKFLOW_INBOUND: "notifkit:stream:workflow:inbound",
+  EVENTS_INBOUND: "notifkit:stream:events:inbound",
+} as const;
+
+export const INBOUND_STREAMS = [
+  STREAMS.INBOUND_CRITICAL,
+  STREAMS.INBOUND_NORMAL,
+  STREAMS.INBOUND_LOW,
+] as const;
+
+export const ENRICHED_STREAMS = [
+  STREAMS.ENRICHED_CRITICAL,
+  STREAMS.ENRICHED_NORMAL,
+  STREAMS.ENRICHED_LOW,
+] as const;
+
+export const OUTBOUND_STREAMS = [
+  STREAMS.OUTBOUND_CRITICAL,
+  STREAMS.OUTBOUND_NORMAL,
+  STREAMS.OUTBOUND_LOW,
+] as const;
+export type StreamName = (typeof STREAMS)[keyof typeof STREAMS];
+
+/**
+ * Redis pub/sub channels used to drop cached state across every process.
+ *
+ * Each cache also carries a TTL, so these only shorten the window in which a
+ * worker can act on stale data — they are not the sole correctness mechanism.
+ */
+export const PUBSUB_CHANNELS = {
+  /** Payload: `{projectId}:{templateId}`. */
+  TEMPLATE_INVALIDATED: "template.invalidated",
+  /** Payload: `{projectId}`. Published when project settings change. */
+  PROJECT_INVALIDATED: "project.invalidated",
+  /** Payload: a token hash, or `*` for the whole cache. */
+  API_KEY_INVALIDATED: "apikey.invalidated",
+} as const;
+export type PubSubChannel = (typeof PUBSUB_CHANNELS)[keyof typeof PUBSUB_CHANNELS];
+
+export const CONSUMER_GROUPS = {
+  ENRICHER: "notifkit:group:enricher",
+  ENGINE: "notifkit:group:engine",
+  DELIVERY: "notifkit:group:delivery",
+  SCHEDULER: "notifkit:group:scheduler",
+  AI: "notifkit:group:ai",
+  WORKFLOW: "notifkit:group:workflow",
+  EVENTS: "notifkit:group:events",
+} as const;
+export type ConsumerGroup = (typeof CONSUMER_GROUPS)[keyof typeof CONSUMER_GROUPS];