@checkstack/notification-common 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# @checkstack/notification-common
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/common@0.0.2
+  - @checkstack/signal-common@0.0.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [a65e002]
+  - @checkstack/common@0.2.0
+  - @checkstack/signal-common@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- b55fae6: Added realtime Signal Service for backend-to-frontend push notifications via WebSockets.
+
+  ## New Packages
+
+  - **@checkstack/signal-common**: Shared types including `Signal`, `SignalService`, `createSignal()`, and WebSocket protocol messages
+  - **@checkstack/signal-backend**: `SignalServiceImpl` with EventBus integration and Bun WebSocket handler using native pub/sub
+  - **@checkstack/signal-frontend**: React `SignalProvider` and `useSignal()` hook for consuming typed signals
+
+  ## Changes
+
+  - **@checkstack/backend-api**: Added `coreServices.signalService` reference for plugins to emit signals
+  - **@checkstack/backend**: Integrated WebSocket server at `/api/signals/ws` with session-based authentication
+
+  ## Usage
+
+  Backend plugins can emit signals:
+
+  ```typescript
+  import { coreServices } from "@checkstack/backend-api";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  const signalService = context.signalService;
+  await signalService.sendToUser(NOTIFICATION_RECEIVED, userId, { ... });
+  ```
+
+  Frontend components subscribe to signals:
+
+  ```tsx
+  import { useSignal } from "@checkstack/signal-frontend";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  useSignal(NOTIFICATION_RECEIVED, (payload) => {
+    // Handle realtime notification
+  });
+  ```
+
+- b354ab3: # Strategy Instructions Support & Telegram Notification Plugin
+
+  ## Strategy Instructions Interface
+
+  Added `adminInstructions` and `userInstructions` optional fields to the `NotificationStrategy` interface. These allow strategies to export markdown-formatted setup guides that are displayed in the configuration UI:
+
+  - **`adminInstructions`**: Shown when admins configure platform-wide strategy settings (e.g., how to create API keys)
+  - **`userInstructions`**: Shown when users configure their personal settings (e.g., how to link their account)
+
+  ### Updated Components
+
+  - `StrategyConfigCard` now accepts an `instructions` prop and renders it before config sections
+  - `StrategyCard` passes `adminInstructions` to `StrategyConfigCard`
+  - `UserChannelCard` renders `userInstructions` when users need to connect
+
+  ## New Telegram Notification Plugin
+
+  Added `@checkstack/notification-telegram-backend` plugin for sending notifications via Telegram:
+
+  - Uses [grammY](https://grammy.dev/) framework for Telegram Bot API integration
+  - Sends messages with MarkdownV2 formatting and inline keyboard buttons for actions
+  - Includes comprehensive admin instructions for bot setup via @BotFather
+  - Includes user instructions for account linking
+
+  ### Configuration
+
+  Admins need to configure a Telegram Bot Token obtained from @BotFather.
+
+  ### User Linking
+
+  The strategy uses `contactResolution: { type: "custom" }` for Telegram Login Widget integration. Full frontend integration for the Login Widget is pending future work.
+
+### Patch Changes
+
+- ffc28f6: ### Anonymous Role and Public Access
+
+  Introduces a configurable "anonymous" role for managing permissions available to unauthenticated users.
+
+  **Core Changes:**
+
+  - Added `userType: "public"` - endpoints accessible by both authenticated users (with their permissions) and anonymous users (with anonymous role permissions)
+  - Renamed `userType: "both"` to `"authenticated"` for clarity
+  - Renamed `isDefault` to `isAuthenticatedDefault` on Permission interface
+  - Added `isPublicDefault` flag for permissions that should be granted to the anonymous role by default
+
+  **Backend Infrastructure:**
+
+  - New `anonymous` system role created during auth-backend initialization
+  - New `disabled_public_default_permission` table tracks admin-disabled public defaults
+  - `autoAuthMiddleware` now checks anonymous role permissions for unauthenticated public endpoint access
+  - `AuthService.getAnonymousPermissions()` with 1-minute caching for performance
+  - Anonymous role filtered from `getRoles` endpoint (not assignable to users)
+  - Validation prevents assigning anonymous role to users
+
+  **Catalog Integration:**
+
+  - `catalog.read` permission now has both `isAuthenticatedDefault` and `isPublicDefault`
+  - Read endpoints (`getSystems`, `getGroups`, `getEntities`) now use `userType: "public"`
+
+  **UI:**
+
+  - New `PermissionGate` component for conditionally rendering content based on permissions
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [b55fae6]
+  - @checkstack/common@0.1.0
+  - @checkstack/signal-common@0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@checkstack/notification-common",
+  "version": "0.0.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
+    "@orpc/contract": "^1.13.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "typescript": "^5.7.2",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./schemas";
+export * from "./permissions";
+export * from "./rpc-contract";
+export * from "./signals";
+export * from "./plugin-metadata";
+export { notificationRoutes } from "./routes";

package/src/permissions.ts

@@ -0,0 +1,12 @@
+import { createPermission } from "@checkstack/common";
+
+export const permissions = {
+  /** Configure retention policy and send broadcasts */
+  notificationAdmin: createPermission(
+    "notification",
+    "manage",
+    "Configure notification settings and send broadcasts"
+  ),
+};
+
+export const permissionList = Object.values(permissions);

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the notification plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "notification",
+});

package/src/routes.ts

@@ -0,0 +1,9 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the notification plugin.
+ */
+export const notificationRoutes = createRoutes("notification", {
+  home: "/",
+  settings: "/settings",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,402 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { permissions } from "./permissions";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  createClientDefinition,
+  type ProcedureMetadata,
+} from "@checkstack/common";
+import {
+  NotificationSchema,
+  NotificationGroupSchema,
+  EnrichedSubscriptionSchema,
+  RetentionSettingsSchema,
+  PaginationInputSchema,
+} from "./schemas";
+
+// Base builder with full metadata support (userType + permissions)
+const _base = oc.$meta<ProcedureMetadata>({});
+
+// Notification RPC Contract
+export const notificationContract = {
+  // ==========================================================================
+  // USER NOTIFICATION ENDPOINTS (userType: "user")
+  // ==========================================================================
+
+  // Get current user's notifications (paginated)
+  getNotifications: _base
+    .meta({
+      userType: "user",
+    })
+    .input(PaginationInputSchema)
+    .output(
+      z.object({
+        notifications: z.array(NotificationSchema),
+        total: z.number(),
+      })
+    ),
+
+  // Get unread count for badge
+  getUnreadCount: _base
+    .meta({
+      userType: "user",
+    })
+    .output(z.object({ count: z.number() })),
+
+  // Mark notification(s) as read
+  markAsRead: _base
+    .meta({
+      userType: "user",
+    })
+    .input(
+      z.object({
+        notificationId: z.string().uuid().optional(), // If not provided, mark all as read
+      })
+    )
+    .output(z.void()),
+
+  // Delete a notification
+  deleteNotification: _base
+    .meta({
+      userType: "user",
+    })
+    .input(z.object({ notificationId: z.string().uuid() }))
+    .output(z.void()),
+
+  // ==========================================================================
+  // GROUP & SUBSCRIPTION ENDPOINTS (userType: "user")
+  // ==========================================================================
+
+  // Get all available notification groups
+  getGroups: _base
+    .meta({
+      userType: "authenticated", // Services can read groups too
+    })
+    .output(z.array(NotificationGroupSchema)),
+
+  // Get current user's subscriptions with group details
+  getSubscriptions: _base
+    .meta({
+      userType: "user",
+    })
+    .output(z.array(EnrichedSubscriptionSchema)),
+
+  // Subscribe to a notification group
+  subscribe: _base
+    .meta({
+      userType: "user",
+    })
+    .input(z.object({ groupId: z.string() }))
+    .output(z.void()),
+
+  // Unsubscribe from a notification group
+  unsubscribe: _base
+    .meta({
+      userType: "user",
+    })
+    .input(z.object({ groupId: z.string() }))
+    .output(z.void()),
+
+  // ==========================================================================
+  // ADMIN SETTINGS ENDPOINTS (userType: "user" with admin permissions)
+  // ==========================================================================
+
+  // Get retention schema for DynamicForm
+  getRetentionSchema: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.notificationAdmin.id],
+    })
+    .output(z.record(z.string(), z.unknown())),
+
+  // Get retention settings
+  getRetentionSettings: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.notificationAdmin.id],
+    })
+    .output(RetentionSettingsSchema),
+
+  // Update retention settings
+  setRetentionSettings: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.notificationAdmin.id],
+    })
+    .input(RetentionSettingsSchema)
+    .output(z.void()),
+
+  // ==========================================================================
+  // BACKEND-TO-BACKEND GROUP MANAGEMENT (userType: "service")
+  // ==========================================================================
+
+  // Create a notification group (for plugins to register their groups)
+  createGroup: _base
+    .meta({ userType: "service" })
+    .input(
+      z.object({
+        groupId: z
+          .string()
+          .describe(
+            "Unique group identifier, will be namespaced with ownerPlugin"
+          ),
+        name: z.string().describe("Display name for the group"),
+        description: z
+          .string()
+          .describe("Description of what notifications this group provides"),
+        ownerPlugin: z.string().describe("Plugin ID that owns this group"),
+      })
+    )
+    .output(z.object({ id: z.string() })),
+
+  // Delete a notification group
+  deleteGroup: _base
+    .meta({ userType: "service" })
+    .input(
+      z.object({
+        groupId: z.string().describe("Full namespaced group ID to delete"),
+        ownerPlugin: z
+          .string()
+          .describe("Plugin ID that owns this group (for validation)"),
+      })
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  // Get subscribers for a specific notification group
+  getGroupSubscribers: _base
+    .meta({ userType: "service" })
+    .input(
+      z.object({
+        groupId: z
+          .string()
+          .describe("Full namespaced group ID (e.g., 'catalog.system.123')"),
+      })
+    )
+    .output(z.object({ userIds: z.array(z.string()) })),
+
+  // Send notifications to a list of users (deduplicated by caller)
+  notifyUsers: _base
+    .meta({ userType: "service" })
+    .input(
+      z.object({
+        userIds: z.array(z.string()),
+        title: z.string(),
+        /** Notification body in markdown format */
+        body: z.string().describe("Notification body (supports markdown)"),
+        importance: z.enum(["info", "warning", "critical"]).optional(),
+        /** Primary action button */
+        action: z
+          .object({
+            label: z.string(),
+            url: z.string(),
+          })
+          .optional(),
+      })
+    )
+    .output(z.object({ notifiedCount: z.number() })),
+
+  // Notify all subscribers of multiple groups (deduplicates internally)
+  // Use this when an event affects multiple groups and you want to avoid
+  // duplicate notifications for users subscribed to multiple affected groups.
+  notifyGroups: _base
+    .meta({ userType: "service" })
+    .input(
+      z.object({
+        groupIds: z
+          .array(z.string())
+          .describe("Full namespaced group IDs to notify"),
+        title: z.string(),
+        /** Notification body in markdown format */
+        body: z.string().describe("Notification body (supports markdown)"),
+        importance: z.enum(["info", "warning", "critical"]).optional(),
+        /** Primary action button */
+        action: z
+          .object({
+            label: z.string(),
+            url: z.string(),
+          })
+          .optional(),
+      })
+    )
+    .output(z.object({ notifiedCount: z.number() })),
+
+  // Send transactional notification via ALL enabled strategies (no internal notification created)
+  // For security-critical messages like password reset, 2FA, account verification, etc.
+  // Unlike regular notifications, this bypasses user preferences and does not create a bell notification.
+  sendTransactional: _base
+    .meta({ userType: "service" })
+    .input(
+      z.object({
+        userId: z.string().describe("User to notify"),
+        notification: z.object({
+          title: z.string(),
+          body: z.string().describe("Notification body (supports markdown)"),
+          action: z
+            .object({
+              label: z.string(),
+              url: z.string(),
+            })
+            .optional(),
+        }),
+      })
+    )
+    .output(
+      z.object({
+        deliveredCount: z
+          .number()
+          .describe("Number of strategies that delivered successfully"),
+        results: z.array(
+          z.object({
+            strategyId: z.string(),
+            success: z.boolean(),
+            error: z.string().optional(),
+          })
+        ),
+      })
+    ),
+
+  // ==========================================================================
+  // DELIVERY STRATEGY ADMIN ENDPOINTS (userType: "user" with admin permissions)
+  // ==========================================================================
+
+  // Get all registered delivery strategies with current config
+  getDeliveryStrategies: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.notificationAdmin.id],
+    })
+    .output(
+      z.array(
+        z.object({
+          qualifiedId: z.string(),
+          displayName: z.string(),
+          description: z.string().optional(),
+          icon: z.string().optional(),
+          ownerPluginId: z.string(),
+          contactResolution: z.object({
+            type: z.enum([
+              "auth-email",
+              "auth-provider",
+              "user-config",
+              "oauth-link",
+              "custom",
+            ]),
+            provider: z.string().optional(),
+            field: z.string().optional(),
+          }),
+          requiresUserConfig: z.boolean(),
+          requiresOAuthLink: z.boolean(),
+          configSchema: z.record(z.string(), z.unknown()),
+          userConfigSchema: z.record(z.string(), z.unknown()).optional(),
+          /** Layout config schema for admin customization (logo, colors, etc.) */
+          layoutConfigSchema: z.record(z.string(), z.unknown()).optional(),
+          enabled: z.boolean(),
+          config: z.record(z.string(), z.unknown()).optional(),
+          /** Current layout config values */
+          layoutConfig: z.record(z.string(), z.unknown()).optional(),
+          /** Markdown instructions for admins (setup guides, etc.) */
+          adminInstructions: z.string().optional(),
+        })
+      )
+    ),
+
+  // Update strategy enabled state and config
+  updateDeliveryStrategy: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.notificationAdmin.id],
+    })
+    .input(
+      z.object({
+        strategyId: z.string().describe("Qualified strategy ID"),
+        enabled: z.boolean(),
+        config: z.record(z.string(), z.unknown()).optional(),
+        /** Layout customization (logo, colors, footer) */
+        layoutConfig: z.record(z.string(), z.unknown()).optional(),
+      })
+    )
+    .output(z.void()),
+
+  // ==========================================================================
+  // USER DELIVERY PREFERENCE ENDPOINTS (userType: "user")
+  // ==========================================================================
+
+  // Get available delivery channels for current user
+  getUserDeliveryChannels: _base.meta({ userType: "user" }).output(
+    z.array(
+      z.object({
+        strategyId: z.string(),
+        displayName: z.string(),
+        description: z.string().optional(),
+        icon: z.string().optional(),
+        contactResolution: z.object({
+          type: z.enum([
+            "auth-email",
+            "auth-provider",
+            "user-config",
+            "oauth-link",
+          ]),
+        }),
+        enabled: z.boolean(),
+        isConfigured: z.boolean(),
+        linkedAt: z.coerce.date().optional(),
+        /** JSON Schema for user config (for DynamicForm) */
+        userConfigSchema: z.record(z.string(), z.unknown()).optional(),
+        /** Current user config values */
+        userConfig: z.record(z.string(), z.unknown()).optional(),
+        /** Markdown instructions for users (connection guides, etc.) */
+        userInstructions: z.string().optional(),
+      })
+    )
+  ),
+
+  // Update user's preference for a delivery channel
+  setUserDeliveryPreference: _base
+    .meta({ userType: "user" })
+    .input(
+      z.object({
+        strategyId: z.string(),
+        enabled: z.boolean(),
+        userConfig: z.record(z.string(), z.unknown()).optional(),
+      })
+    )
+    .output(z.void()),
+
+  // Get OAuth link URL for a strategy (starts OAuth flow)
+  getDeliveryOAuthUrl: _base
+    .meta({ userType: "user" })
+    .input(
+      z.object({
+        strategyId: z.string(),
+        returnUrl: z.string().optional(),
+      })
+    )
+    .output(z.object({ authUrl: z.string() })),
+
+  // Unlink OAuth-connected delivery channel
+  unlinkDeliveryChannel: _base
+    .meta({ userType: "user" })
+    .input(z.object({ strategyId: z.string() }))
+    .output(z.void()),
+
+  // Send a test notification to the current user via a specific strategy
+  sendTestNotification: _base
+    .meta({ userType: "user" })
+    .input(z.object({ strategyId: z.string() }))
+    .output(
+      z.object({
+        success: z.boolean(),
+        error: z.string().optional(),
+      })
+    ),
+};
+
+// Export contract type
+export type NotificationContract = typeof notificationContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(NotificationApi);
+export const NotificationApi = createClientDefinition(
+  notificationContract,
+  pluginMetadata
+);

package/src/schemas.ts

@@ -0,0 +1,186 @@
+import { z } from "zod";
+
+// Notification importance levels
+export const ImportanceSchema = z.enum(["info", "warning", "critical"]);
+export type Importance = z.infer<typeof ImportanceSchema>;
+
+// Notification action for CTA buttons
+export const NotificationActionSchema = z.object({
+  label: z.string(),
+  url: z.string(),
+});
+export type NotificationAction = z.infer<typeof NotificationActionSchema>;
+
+// Core notification schema
+export const NotificationSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  title: z.string(),
+  /** Notification body (supports markdown) */
+  body: z.string(),
+  /** Primary action button */
+  action: NotificationActionSchema.optional(),
+  importance: ImportanceSchema,
+  isRead: z.boolean(),
+  groupId: z.string().optional(),
+  createdAt: z.coerce.date(),
+});
+export type Notification = z.infer<typeof NotificationSchema>;
+
+// Notification group schema (namespaced: "pluginId.groupName")
+export const NotificationGroupSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  ownerPlugin: z.string(),
+  createdAt: z.coerce.date(),
+});
+export type NotificationGroup = z.infer<typeof NotificationGroupSchema>;
+
+// User subscription to a notification group
+export const NotificationSubscriptionSchema = z.object({
+  userId: z.string(),
+  groupId: z.string(),
+  subscribedAt: z.coerce.date(),
+});
+export type NotificationSubscription = z.infer<
+  typeof NotificationSubscriptionSchema
+>;
+
+// Enriched subscription with group details for display
+export const EnrichedSubscriptionSchema = z.object({
+  groupId: z.string(),
+  groupName: z.string(),
+  groupDescription: z.string(),
+  ownerPlugin: z.string(),
+  subscribedAt: z.coerce.date(),
+});
+export type EnrichedSubscription = z.infer<typeof EnrichedSubscriptionSchema>;
+
+// Retention settings
+export const RetentionSettingsSchema = z.object({
+  retentionDays: z.number().min(1).max(365),
+  enabled: z.boolean(),
+});
+export type RetentionSettings = z.infer<typeof RetentionSettingsSchema>;
+
+// --- Input Schemas ---
+
+export const CreateNotificationInputSchema = z.object({
+  userId: z.string(),
+  title: z.string(),
+  /** Notification body (supports markdown) */
+  body: z.string(),
+  /** Primary action button */
+  action: NotificationActionSchema.optional(),
+  importance: ImportanceSchema.default("info"),
+});
+export type CreateNotificationInput = z.infer<
+  typeof CreateNotificationInputSchema
+>;
+
+export const NotificationGroupInputSchema = z.object({
+  groupId: z.string(),
+  name: z.string(),
+  description: z.string(),
+});
+export type NotificationGroupInput = z.infer<
+  typeof NotificationGroupInputSchema
+>;
+
+// Pagination schema for listing notifications
+export const PaginationInputSchema = z.object({
+  limit: z.number().min(1).max(100).default(20),
+  offset: z.number().min(0).default(0),
+  unreadOnly: z.boolean().default(false),
+});
+export type PaginationInput = z.infer<typeof PaginationInputSchema>;
+
+// --- Notification Strategy Schemas ---
+
+// Contact resolution type
+export const ContactResolutionSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("auth-email") }),
+  z.object({ type: z.literal("auth-provider"), provider: z.string() }),
+  z.object({ type: z.literal("user-config"), field: z.string() }),
+  z.object({ type: z.literal("oauth-link") }),
+]);
+export type ContactResolution = z.infer<typeof ContactResolutionSchema>;
+
+// Strategy info for API responses
+export const NotificationStrategyInfoSchema = z.object({
+  /** Qualified ID: {pluginId}.{strategyId} */
+  qualifiedId: z.string(),
+  /** Display name */
+  displayName: z.string(),
+  /** Description */
+  description: z.string().optional(),
+  /** Lucide icon name */
+  icon: z.string().optional(),
+  /** Owner plugin ID */
+  ownerPluginId: z.string(),
+  /** How contact info is resolved */
+  contactResolution: ContactResolutionSchema,
+  /** Whether strategy requires user config */
+  requiresUserConfig: z.boolean(),
+  /** Whether strategy requires OAuth linking */
+  requiresOAuthLink: z.boolean(),
+  /** JSON Schema for admin config (for DynamicForm) */
+  configSchema: z.record(z.string(), z.unknown()),
+  /** JSON Schema for user config (if applicable) */
+  userConfigSchema: z.record(z.string(), z.unknown()).optional(),
+});
+export type NotificationStrategyInfo = z.infer<
+  typeof NotificationStrategyInfoSchema
+>;
+
+// User's preference for a specific strategy
+export const UserNotificationPreferenceSchema = z.object({
+  strategyId: z.string(),
+  enabled: z.boolean(),
+  /** Whether this channel is ready (has contact info / is linked) */
+  isConfigured: z.boolean(),
+  /** When external account was linked (for OAuth strategies) */
+  linkedAt: z.coerce.date().optional(),
+});
+export type UserNotificationPreference = z.infer<
+  typeof UserNotificationPreferenceSchema
+>;
+
+// External notification payload
+export const ExternalNotificationPayloadSchema = z.object({
+  title: z.string(),
+  /** Markdown-formatted body content */
+  body: z.string().optional(),
+  importance: ImportanceSchema.default("info"),
+  /** Optional call-to-action */
+  action: z
+    .object({
+      label: z.string(),
+      url: z.string(),
+    })
+    .optional(),
+  /** Source type for filtering (e.g., "healthcheck.alert", "password-reset") */
+  type: z.string(),
+});
+export type ExternalNotificationPayload = z.infer<
+  typeof ExternalNotificationPayloadSchema
+>;
+
+// External delivery result
+export const ExternalDeliveryResultSchema = z.object({
+  sent: z.number(),
+  failed: z.number(),
+  skipped: z.number(),
+});
+export type ExternalDeliveryResult = z.infer<
+  typeof ExternalDeliveryResultSchema
+>;
+
+// Transactional message result
+export const TransactionalResultSchema = z.object({
+  success: z.boolean(),
+  externalId: z.string().optional(),
+  error: z.string().optional(),
+});
+export type TransactionalResult = z.infer<typeof TransactionalResultSchema>;

package/src/signals.ts

@@ -0,0 +1,38 @@
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+import { ImportanceSchema } from "./schemas";
+
+/**
+ * Signal emitted when a new notification is received.
+ * Used to update the notification bell count and show realtime notifications.
+ */
+export const NOTIFICATION_RECEIVED = createSignal(
+  "notification.received",
+  z.object({
+    id: z.string(),
+    title: z.string(),
+    body: z.string(),
+    importance: ImportanceSchema,
+  })
+);
+
+/**
+ * Signal emitted when the unread notification count changes.
+ * Used to update the badge count on the notification bell.
+ */
+export const NOTIFICATION_COUNT_CHANGED = createSignal(
+  "notification.countChanged",
+  z.object({
+    unreadCount: z.number(),
+  })
+);
+
+/**
+ * Signal emitted when a notification is marked as read.
+ */
+export const NOTIFICATION_READ = createSignal(
+  "notification.read",
+  z.object({
+    notificationId: z.string().optional(), // undefined means all marked as read
+  })
+);

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}