@checkstack/notification-frontend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,175 @@
+# @checkstack/notification-frontend
+
+## 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/auth-frontend@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/frontend-api@0.0.2
+  - @checkstack/notification-common@0.0.2
+  - @checkstack/signal-frontend@0.0.2
+  - @checkstack/ui@0.0.2
+
+## 0.1.4
+
+### Patch Changes
+
+- a65e002: Add compile-time type safety for Lucide icon names
+
+  - Add `LucideIconName` type and `lucideIconSchema` Zod schema to `@checkstack/common`
+  - Update backend interfaces (`AuthStrategy`, `NotificationStrategy`, `IntegrationProvider`, `CommandDefinition`) to use `LucideIconName`
+  - Update RPC contracts to use `lucideIconSchema` for proper type inference across RPC boundaries
+  - Simplify `SocialProviderButton` to use `DynamicIcon` directly (removes 30+ lines of pascalCase conversion)
+  - Replace static `iconMap` in `SearchDialog` with `DynamicIcon` for dynamic icon rendering
+  - Add fallback handling in `DynamicIcon` when icon name isn't found
+  - Fix legacy kebab-case icon names to PascalCase: `mail`→`Mail`, `send`→`Send`, `github`→`Github`, `key-round`→`KeyRound`, `network`→`Network`, `AlertCircle`→`CircleAlert`
+
+- ae33df2: Move command palette from dashboard to centered navbar position
+
+  - Converted `command-frontend` into a plugin with `NavbarCenterSlot` extension
+  - Added compact `NavbarSearch` component with responsive search trigger
+  - Moved `SearchDialog` from dashboard-frontend to command-frontend
+  - Keyboard shortcut (⌘K / Ctrl+K) now works on every page
+  - Renamed navbar slots for clarity:
+    - `NavbarSlot` → `NavbarRightSlot`
+    - `NavbarMainSlot` → `NavbarLeftSlot`
+    - Added new `NavbarCenterSlot` for centered content
+
+- 32ea706: ### User Menu Loading State Fix
+
+  Fixed user menu items "popping in" one after another due to independent async permission checks.
+
+  **Changes:**
+
+  - Added `UserMenuItemsContext` interface with `permissions` and `hasCredentialAccount` to `@checkstack/frontend-api`
+  - `LoginNavbarAction` now pre-fetches all permissions and credential account info before rendering the menu
+  - All user menu item components now use the passed context for synchronous permission checks instead of async hooks
+  - Uses `qualifyPermissionId` helper for fully-qualified permission IDs
+
+  **Result:** All menu items appear simultaneously when the user menu opens.
+
+- Updated dependencies [52231ef]
+- Updated dependencies [b0124ef]
+- Updated dependencies [54cc787]
+- Updated dependencies [a65e002]
+- Updated dependencies [ae33df2]
+- Updated dependencies [a65e002]
+- Updated dependencies [32ea706]
+  - @checkstack/auth-frontend@0.3.0
+  - @checkstack/ui@0.1.2
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/notification-common@0.1.1
+  - @checkstack/signal-frontend@0.1.1
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies [1bf71bb]
+  - @checkstack/auth-frontend@0.2.1
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [e26c08e]
+  - @checkstack/auth-frontend@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [0f8cc7d]
+  - @checkstack/frontend-api@0.0.3
+  - @checkstack/auth-frontend@0.1.1
+  - @checkstack/ui@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
+
+- Updated dependencies [eff5b4e]
+- Updated dependencies [ffc28f6]
+- Updated dependencies [32f2535]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+  - @checkstack/ui@0.1.0
+  - @checkstack/common@0.1.0
+  - @checkstack/notification-common@0.1.0
+  - @checkstack/auth-frontend@0.1.0
+  - @checkstack/signal-frontend@0.1.0
+  - @checkstack/frontend-api@0.0.2

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@checkstack/notification-frontend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.tsx",
+  "checkstack": {
+    "type": "frontend"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/notification-common": "workspace:*",
+    "@checkstack/frontend-api": "workspace:*",
+    "@checkstack/auth-frontend": "workspace:*",
+    "@checkstack/signal-frontend": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/ui": "workspace:*",
+    "react": "^18.2.0",
+    "react-router-dom": "^6.22.0",
+    "lucide-react": "^0.344.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/react": "^18.2.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/components/NotificationBell.tsx

@@ -0,0 +1,283 @@
+import { useState, useEffect, useCallback } from "react";
+import { Link } from "react-router-dom";
+import { Bell, CheckCheck } from "lucide-react";
+import {
+  Badge,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  DropdownMenuSeparator,
+  Button,
+  stripMarkdown,
+} from "@checkstack/ui";
+import { useApi, rpcApiRef } from "@checkstack/frontend-api";
+import { useSignal } from "@checkstack/signal-frontend";
+import { resolveRoute } from "@checkstack/common";
+import type { Notification } from "@checkstack/notification-common";
+import {
+  NotificationApi,
+  NOTIFICATION_RECEIVED,
+  NOTIFICATION_COUNT_CHANGED,
+  NOTIFICATION_READ,
+  notificationRoutes,
+} from "@checkstack/notification-common";
+import { authApiRef } from "@checkstack/auth-frontend/api";
+
+export const NotificationBell = () => {
+  const authApi = useApi(authApiRef);
+  const { data: session, isPending: isAuthLoading } = authApi.useSession();
+  const rpcApi = useApi(rpcApiRef);
+  const notificationClient = rpcApi.forPlugin(NotificationApi);
+
+  const [unreadCount, setUnreadCount] = useState(0);
+  const [recentNotifications, setRecentNotifications] = useState<
+    Notification[]
+  >([]);
+  const [isOpen, setIsOpen] = useState(false);
+  const [loading, setLoading] = useState(true);
+
+  const fetchUnreadCount = useCallback(async () => {
+    // Skip fetch if not authenticated
+    if (!session) return;
+    try {
+      const { count } = await notificationClient.getUnreadCount();
+      setUnreadCount(count);
+    } catch (error) {
+      console.error("Failed to fetch unread count:", error);
+    }
+  }, [notificationClient, session]);
+
+  const fetchRecentNotifications = useCallback(async () => {
+    // Skip fetch if not authenticated
+    if (!session) return;
+    try {
+      const { notifications } = await notificationClient.getNotifications({
+        limit: 5,
+        offset: 0,
+        unreadOnly: true, // Only show unread notifications in the dropdown
+      });
+      setRecentNotifications(notifications);
+    } catch (error) {
+      console.error("Failed to fetch notifications:", error);
+    }
+  }, [notificationClient, session]);
+
+  // Initial fetch
+  useEffect(() => {
+    if (!session) {
+      setLoading(false);
+      return;
+    }
+    const init = async () => {
+      await Promise.all([fetchUnreadCount(), fetchRecentNotifications()]);
+      setLoading(false);
+    };
+    void init();
+  }, [fetchUnreadCount, fetchRecentNotifications, session]);
+
+  // ==========================================================================
+  // REALTIME SIGNAL SUBSCRIPTIONS (replaces polling)
+  // ==========================================================================
+
+  // Handle new notification received
+  useSignal(
+    NOTIFICATION_RECEIVED,
+    useCallback((payload) => {
+      // Increment unread count
+      setUnreadCount((prev) => prev + 1);
+
+      // Add to recent notifications if dropdown is open
+      setRecentNotifications((prev) => [
+        {
+          id: payload.id,
+          title: payload.title,
+          body: payload.body,
+          importance: payload.importance,
+          userId: "", // Not needed for display
+          isRead: false,
+          createdAt: new Date(),
+        },
+        ...prev.slice(0, 4), // Keep only 5 items
+      ]);
+    }, [])
+  );
+
+  // Handle count changes from other sources
+  useSignal(
+    NOTIFICATION_COUNT_CHANGED,
+    useCallback((payload) => {
+      setUnreadCount(payload.unreadCount);
+    }, [])
+  );
+
+  // Handle notification marked as read
+  useSignal(
+    NOTIFICATION_READ,
+    useCallback((payload) => {
+      if (payload.notificationId) {
+        // Single notification marked as read - remove from list
+        setRecentNotifications((prev) =>
+          prev.filter((n) => n.id !== payload.notificationId)
+        );
+        setUnreadCount((prev) => Math.max(0, prev - 1));
+      } else {
+        // All marked as read - clear the list
+        setRecentNotifications([]);
+        setUnreadCount(0);
+      }
+    }, [])
+  );
+
+  // ==========================================================================
+
+  // Fetch notifications when dropdown opens
+  useEffect(() => {
+    if (isOpen) {
+      void fetchRecentNotifications();
+    }
+  }, [isOpen, fetchRecentNotifications]);
+
+  const handleMarkAllAsRead = async () => {
+    try {
+      await notificationClient.markAsRead({});
+      setUnreadCount(0);
+      setRecentNotifications([]);
+    } catch (error) {
+      console.error("Failed to mark all as read:", error);
+    }
+  };
+
+  const handleClose = useCallback(() => {
+    setIsOpen(false);
+  }, []);
+
+  // Hide notification bell for unauthenticated users
+  if (isAuthLoading || !session) {
+    return;
+  }
+
+  if (loading) {
+    return (
+      <Button variant="ghost" size="icon" className="relative" disabled>
+        <Bell className="h-5 w-5" />
+      </Button>
+    );
+  }
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        onClick={() => {
+          setIsOpen(!isOpen);
+        }}
+      >
+        <Button variant="ghost" size="icon" className="relative group">
+          <Bell className="h-5 w-5 transition-transform group-hover:scale-110" />
+          {unreadCount > 0 && (
+            <span className="absolute -top-1 -right-1 flex h-5 min-w-[20px] items-center justify-center">
+              <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-destructive opacity-75" />
+              <Badge
+                variant="destructive"
+                className="relative h-5 min-w-[20px] flex items-center justify-center p-0 text-xs font-bold"
+              >
+                {unreadCount > 99 ? "99+" : unreadCount}
+              </Badge>
+            </span>
+          )}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        isOpen={isOpen}
+        onClose={handleClose}
+        className="w-80"
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-3 py-2 border-b border-border">
+          <span className="font-semibold text-sm">Notifications</span>
+          {unreadCount > 0 && (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 text-xs"
+              onClick={() => {
+                void handleMarkAllAsRead();
+              }}
+            >
+              <CheckCheck className="h-3 w-3 mr-1" />
+              Mark all read
+            </Button>
+          )}
+        </div>
+
+        {/* Notification List */}
+        <div className="max-h-[400px] overflow-y-auto">
+          {recentNotifications.length === 0 ? (
+            <div className="px-3 py-6 text-center text-sm text-muted-foreground">
+              No unread notifications
+            </div>
+          ) : (
+            <>
+              {recentNotifications.map((notification) => (
+                <DropdownMenuItem
+                  key={notification.id}
+                  className={`flex flex-col items-start gap-1 px-3 py-2 cursor-pointer ${
+                    notification.importance === "critical"
+                      ? "border-l-2 border-l-destructive"
+                      : notification.importance === "warning"
+                      ? "border-l-2 border-l-warning"
+                      : ""
+                  }`}
+                >
+                  <div
+                    className={`font-medium text-sm ${
+                      notification.importance === "critical"
+                        ? "text-destructive"
+                        : notification.importance === "warning"
+                        ? "text-warning"
+                        : "text-foreground"
+                    }`}
+                  >
+                    {notification.title}
+                  </div>
+                  <div className="text-xs text-muted-foreground line-clamp-2">
+                    {stripMarkdown(notification.body)}
+                  </div>
+                  {notification.action && (
+                    <div className="flex gap-2 mt-1">
+                      <Link
+                        to={notification.action.url}
+                        className="text-xs text-primary hover:underline"
+                        onClick={(e: React.MouseEvent) => {
+                          e.stopPropagation();
+                        }}
+                      >
+                        {notification.action.label}
+                      </Link>
+                    </div>
+                  )}
+                </DropdownMenuItem>
+              ))}
+            </>
+          )}
+        </div>
+
+        <DropdownMenuSeparator />
+
+        {/* Footer */}
+        <DropdownMenuItem
+          onClick={() => {
+            handleClose();
+          }}
+        >
+          <Link
+            to={resolveRoute(notificationRoutes.routes.home)}
+            className="w-full text-center text-sm text-primary"
+          >
+            View all notifications
+          </Link>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+};

package/src/components/StrategyCard.tsx

@@ -0,0 +1,163 @@
+import {
+  StrategyConfigCard,
+  type ConfigSection,
+  type LucideIconName,
+} from "@checkstack/ui";
+
+/**
+ * Strategy data from getDeliveryStrategies endpoint
+ */
+export interface DeliveryStrategy {
+  qualifiedId: string;
+  displayName: string;
+  description?: string;
+  icon?: LucideIconName;
+  ownerPluginId: string;
+  contactResolution: {
+    type:
+      | "auth-email"
+      | "auth-provider"
+      | "user-config"
+      | "oauth-link"
+      | "custom";
+    provider?: string;
+    field?: string;
+  };
+  requiresUserConfig: boolean;
+  requiresOAuthLink: boolean;
+  configSchema: Record<string, unknown>;
+  userConfigSchema?: Record<string, unknown>;
+  /** Layout config schema for admin customization (logo, colors, etc.) */
+  layoutConfigSchema?: Record<string, unknown>;
+  enabled: boolean;
+  config?: Record<string, unknown>;
+  /** Current layout config values */
+  layoutConfig?: Record<string, unknown>;
+  /** Markdown instructions for admins (setup guides, etc.) */
+  adminInstructions?: string;
+}
+
+export interface StrategyCardProps {
+  strategy: DeliveryStrategy;
+  onUpdate: (
+    strategyId: string,
+    enabled: boolean,
+    config?: Record<string, unknown>,
+    layoutConfig?: Record<string, unknown>
+  ) => Promise<void>;
+  saving?: boolean;
+}
+
+/**
+ * Get contact resolution type badge for notification strategies
+ */
+function getResolutionBadge(
+  type: DeliveryStrategy["contactResolution"]["type"]
+) {
+  switch (type) {
+    case "auth-email": {
+      return { label: "User Email", variant: "secondary" as const };
+    }
+    case "auth-provider": {
+      return { label: "Auth Provider", variant: "secondary" as const };
+    }
+    case "user-config": {
+      return { label: "User Config Required", variant: "outline" as const };
+    }
+    case "oauth-link": {
+      return { label: "OAuth Link", variant: "default" as const };
+    }
+    default: {
+      return { label: "Custom", variant: "outline" as const };
+    }
+  }
+}
+
+/**
+ * Admin card for configuring a delivery strategy.
+ * Uses the shared StrategyConfigCard component.
+ */
+export function StrategyCard({
+  strategy,
+  onUpdate,
+  saving,
+}: StrategyCardProps) {
+  // Build badges array from strategy properties
+  const badges = [
+    getResolutionBadge(strategy.contactResolution.type),
+    ...(strategy.requiresOAuthLink
+      ? [{ label: "OAuth", variant: "outline" as const, className: "text-xs" }]
+      : []),
+  ];
+
+  // Check if config is missing - has schema properties but no saved config
+  const hasConfigSchema =
+    strategy.configSchema &&
+    "properties" in strategy.configSchema &&
+    Object.keys(strategy.configSchema.properties as Record<string, unknown>)
+      .length > 0;
+  const configMissing = hasConfigSchema && strategy.config === undefined;
+
+  const handleToggle = async (id: string, enabled: boolean) => {
+    await onUpdate(id, enabled, strategy.config, strategy.layoutConfig);
+  };
+
+  // Build config sections array
+  const configSections: ConfigSection[] = [];
+
+  // Main configuration section
+  if (hasConfigSchema) {
+    configSections.push({
+      id: "config",
+      title: "Configuration",
+      schema: strategy.configSchema,
+      value: strategy.config,
+      onSave: async (config) => {
+        await onUpdate(
+          strategy.qualifiedId,
+          strategy.enabled,
+          config,
+          strategy.layoutConfig
+        );
+      },
+    });
+  }
+
+  // Layout configuration section (if strategy supports it)
+  if (strategy.layoutConfigSchema) {
+    configSections.push({
+      id: "layout",
+      title: "Email Layout",
+      schema: strategy.layoutConfigSchema,
+      value: strategy.layoutConfig,
+      onSave: async (layoutConfig) => {
+        await onUpdate(
+          strategy.qualifiedId,
+          strategy.enabled,
+          strategy.config,
+          layoutConfig
+        );
+      },
+    });
+  }
+
+  return (
+    <StrategyConfigCard
+      strategy={{
+        id: strategy.qualifiedId,
+        displayName: strategy.displayName,
+        description: strategy.description,
+        icon: strategy.icon,
+        enabled: strategy.enabled,
+      }}
+      configSections={configSections}
+      onToggle={handleToggle}
+      saving={saving}
+      badges={badges}
+      subtitle={`From: ${strategy.ownerPluginId}`}
+      disabledWarning="Enable this channel to allow users to receive notifications"
+      configMissing={configMissing}
+      instructions={strategy.adminInstructions}
+    />
+  );
+}