@checkstack/notification-backend 0.0.2

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@checkstack/notification-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "checkstack": {
+    "type": "backend"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "generate": "drizzle-kit generate",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/notification-common": "workspace:*",
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
+    "@checkstack/queue-api": "workspace:*",
+    "@checkstack/auth-backend": "workspace:*",
+    "@checkstack/auth-common": "workspace:*",
+    "drizzle-orm": "^0.45.1",
+    "zod": "^4.2.1",
+    "@checkstack/common": "workspace:*"
+  },
+  "devDependencies": {
+    "@checkstack/drizzle-helper": "workspace:*",
+    "@checkstack/scripts": "workspace:*",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/test-utils-backend": "workspace:*",
+    "@orpc/server": "^1.13.2",
+    "@types/node": "^20.0.0",
+    "drizzle-kit": "^0.31.8",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,280 @@
+import {
+  createBackendPlugin,
+  coreServices,
+  createExtensionPoint,
+  coreHooks,
+  type NotificationStrategy,
+  type RegisteredNotificationStrategy,
+  type NotificationStrategyRegistry,
+} from "@checkstack/backend-api";
+import {
+  permissionList,
+  pluginMetadata,
+  notificationContract,
+} from "@checkstack/notification-common";
+import type { PluginMetadata } from "@checkstack/common";
+import { eq } from "drizzle-orm";
+
+import * as schema from "./schema";
+import { createNotificationRouter } from "./router";
+import { authHooks } from "@checkstack/auth-backend";
+import { createOAuthCallbackHandler } from "./oauth-callback-handler";
+import { createStrategyService } from "./strategy-service";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Extension Point
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export interface NotificationStrategyExtensionPoint {
+  /**
+   * Register a notification strategy.
+   * The strategy will be namespaced by the plugin's ID automatically.
+   */
+  addStrategy<TConfig, TUserConfig, TLayoutConfig>(
+    strategy: NotificationStrategy<TConfig, TUserConfig, TLayoutConfig>,
+    pluginMetadata: PluginMetadata
+  ): void;
+}
+
+export const notificationStrategyExtensionPoint =
+  createExtensionPoint<NotificationStrategyExtensionPoint>(
+    "notification.strategyExtensionPoint"
+  );
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Registry Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Create a new notification strategy registry instance.
+ */
+function createNotificationStrategyRegistry(): NotificationStrategyRegistry & {
+  getNewPermissions: () => Array<{
+    id: string;
+    description: string;
+    ownerPluginId: string;
+  }>;
+} {
+  const strategies = new Map<
+    string,
+    RegisteredNotificationStrategy<unknown, unknown, unknown>
+  >();
+  const newPermissions: Array<{
+    id: string;
+    description: string;
+    ownerPluginId: string;
+  }> = [];
+
+  return {
+    register<TConfig, TUserConfig, TLayoutConfig>(
+      strategy: NotificationStrategy<TConfig, TUserConfig, TLayoutConfig>,
+      metadata: PluginMetadata
+    ): void {
+      const qualifiedId = `${metadata.pluginId}.${strategy.id}`;
+      const permissionId = `${metadata.pluginId}.strategy.${strategy.id}.use`;
+
+      // Cast to unknown for storage - registry stores heterogeneous strategies
+      const registered: RegisteredNotificationStrategy<
+        unknown,
+        unknown,
+        unknown
+      > = {
+        ...(strategy as NotificationStrategy<unknown, unknown, unknown>),
+        qualifiedId,
+        ownerPluginId: metadata.pluginId,
+        permissionId,
+      };
+
+      strategies.set(qualifiedId, registered);
+
+      // Track new permission for later registration
+      newPermissions.push({
+        id: permissionId,
+        description: `Use ${strategy.displayName} notification channel`,
+        ownerPluginId: metadata.pluginId,
+      });
+    },
+
+    getStrategy(
+      qualifiedId: string
+    ): RegisteredNotificationStrategy<unknown, unknown, unknown> | undefined {
+      return strategies.get(qualifiedId);
+    },
+
+    getStrategies(): RegisteredNotificationStrategy<
+      unknown,
+      unknown,
+      unknown
+    >[] {
+      return [...strategies.values()];
+    },
+
+    getStrategiesForUser(
+      userPermissions: Set<string>
+    ): RegisteredNotificationStrategy<unknown, unknown, unknown>[] {
+      return [...strategies.values()].filter((s) =>
+        userPermissions.has(s.permissionId)
+      );
+    },
+
+    getNewPermissions() {
+      return newPermissions;
+    },
+  };
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Create the strategy registry
+    const strategyRegistry = createNotificationStrategyRegistry();
+
+    // Register static permissions
+    env.registerPermissions(permissionList);
+
+    // Register the extension point
+    env.registerExtensionPoint(notificationStrategyExtensionPoint, {
+      addStrategy: (strategy, metadata) => {
+        strategyRegistry.register(strategy, metadata);
+      },
+    });
+
+    env.registerInit({
+      schema,
+      deps: {
+        logger: coreServices.logger,
+        rpc: coreServices.rpc,
+        rpcClient: coreServices.rpcClient,
+        config: coreServices.config,
+        signalService: coreServices.signalService,
+      },
+      init: async ({
+        logger,
+        database,
+        rpc,
+        rpcClient,
+        config,
+        signalService,
+      }) => {
+        logger.debug("🔔 Initializing Notification Backend...");
+
+        const db = database;
+        const baseUrl =
+          process.env.VITE_API_BASE_URL ?? "http://localhost:3000";
+
+        // Create strategy service for config management (shared with afterPluginsReady)
+        const strategyService = createStrategyService({
+          db,
+          configService: config,
+          strategyRegistry,
+        });
+
+        // Store for afterPluginsReady access
+        (
+          env as unknown as { strategyService: typeof strategyService }
+        ).strategyService = strategyService;
+
+        // Create and register the notification router with strategy registry
+        const router = createNotificationRouter(
+          db,
+          config,
+          signalService,
+          strategyRegistry,
+          rpcClient,
+          logger
+        );
+        rpc.registerRouter(router, notificationContract);
+
+        // Register OAuth callback handler for strategy OAuth flows
+        const oauthHandler = createOAuthCallbackHandler({
+          db,
+          configService: config,
+          strategyRegistry,
+          baseUrl,
+        });
+        rpc.registerHttpHandler(oauthHandler, "/oauth");
+
+        logger.debug("✅ Notification Backend initialized.");
+      },
+      afterPluginsReady: async ({ database, logger, onHook, emitHook }) => {
+        const db = database;
+
+        // Log registered strategies
+        const strategies = strategyRegistry.getStrategies();
+        logger.debug(
+          `📧 Registered ${
+            strategies.length
+          } notification strategies: ${strategies
+            .map((s) => s.qualifiedId)
+            .join(", ")}`
+        );
+
+        // Emit dynamic permissions for strategies
+        const newPermissions = strategyRegistry.getNewPermissions();
+        if (newPermissions.length > 0) {
+          logger.debug(
+            `🔐 Registering ${newPermissions.length} dynamic strategy permissions`
+          );
+
+          // Group permissions by owner plugin and emit hooks
+          const byPlugin = new Map<
+            string,
+            Array<{ id: string; description: string }>
+          >();
+          for (const perm of newPermissions) {
+            const existing = byPlugin.get(perm.ownerPluginId) ?? [];
+            existing.push({ id: perm.id, description: perm.description });
+            byPlugin.set(perm.ownerPluginId, existing);
+          }
+
+          // Emit permissions registered hook for each plugin's permissions
+          for (const [ownerPluginId, permissions] of byPlugin) {
+            await emitHook(coreHooks.permissionsRegistered, {
+              pluginId: ownerPluginId,
+              permissions: permissions.map((p) => ({
+                id: p.id,
+                description: p.description,
+              })),
+            });
+          }
+        }
+
+        // Subscribe to user deletion to clean up notifications and subscriptions
+        onHook(
+          authHooks.userDeleted,
+          async ({ userId }) => {
+            logger.debug(
+              `Cleaning up notifications for deleted user: ${userId}`
+            );
+            // Delete user notification preferences via ConfigService
+            const strategyService = (
+              env as unknown as {
+                strategyService: ReturnType<typeof createStrategyService>;
+              }
+            ).strategyService;
+            if (strategyService) {
+              await strategyService.deleteUserPreferences(userId);
+            }
+            // Delete subscriptions (has userId reference)
+            await db
+              .delete(schema.notificationSubscriptions)
+              .where(eq(schema.notificationSubscriptions.userId, userId));
+            // Delete notifications for this user
+            await db
+              .delete(schema.notifications)
+              .where(eq(schema.notifications.userId, userId));
+            logger.debug(`Cleaned up notifications for user: ${userId}`);
+          },
+          { mode: "work-queue", workerGroup: "user-cleanup" }
+        );
+
+        logger.debug("✅ Notification Backend afterPluginsReady complete.");
+      },
+    });
+  },
+});

package/src/oauth-callback-handler.ts

@@ -0,0 +1,209 @@
+/**
+ * OAuth Callback Handler
+ *
+ * Handles OAuth callback redirects from external providers.
+ * Registered as HTTP handlers at `/api/notification/oauth/{strategyId}/callback`.
+ */
+
+import type {
+  NotificationStrategyRegistry,
+  ConfigService,
+} from "@checkstack/backend-api";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { createStrategyService } from "./strategy-service";
+import type * as schema from "./schema";
+
+export interface OAuthCallbackDeps {
+  db: NodePgDatabase<typeof schema>;
+  configService: ConfigService;
+  strategyRegistry: NotificationStrategyRegistry;
+  baseUrl: string;
+}
+
+/**
+ * Create an OAuth callback handler that routes to the appropriate strategy.
+ *
+ * @param deps - Service dependencies
+ * @returns HTTP handler function for OAuth callbacks
+ */
+export function createOAuthCallbackHandler(
+  deps: OAuthCallbackDeps
+): (req: Request) => Promise<Response> {
+  const { db, configService, strategyRegistry, baseUrl } = deps;
+
+  const strategyService = createStrategyService({
+    db,
+    configService,
+    strategyRegistry,
+  });
+
+  return async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+
+    // Extract strategy ID from path: /oauth/{strategyId}/callback
+    const pathParts = url.pathname.split("/");
+    const oauthIndex = pathParts.indexOf("oauth");
+    if (oauthIndex === -1 || pathParts.length <= oauthIndex + 2) {
+      return new Response("Invalid OAuth path", { status: 400 });
+    }
+
+    const strategyId = pathParts[oauthIndex + 1];
+    const action = pathParts[oauthIndex + 2]; // "callback" or other actions
+
+    if (action !== "callback") {
+      return new Response(`Unknown OAuth action: ${action}`, { status: 400 });
+    }
+
+    // Find strategy
+    const strategy = strategyRegistry.getStrategy(strategyId);
+    if (!strategy) {
+      return new Response(`Strategy not found: ${strategyId}`, { status: 404 });
+    }
+
+    if (!strategy.oauth) {
+      return new Response(`Strategy ${strategyId} does not support OAuth`, {
+        status: 400,
+      });
+    }
+
+    const oauth = strategy.oauth;
+
+    // Get code and state from query params
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    const error = url.searchParams.get("error");
+
+    // Handle error from provider
+    if (error) {
+      const errorDescription =
+        url.searchParams.get("error_description") || error;
+      return Response.redirect(
+        `${baseUrl}/notification/settings?error=${encodeURIComponent(
+          errorDescription
+        )}`,
+        302
+      );
+    }
+
+    if (!code || !state) {
+      return Response.redirect(
+        `${baseUrl}/notification/settings?error=${encodeURIComponent(
+          "Missing code or state parameter"
+        )}`,
+        302
+      );
+    }
+
+    // Decode state
+    let stateData: { userId: string; returnUrl: string };
+    try {
+      const decoded = atob(state);
+      stateData = JSON.parse(decoded);
+    } catch {
+      return Response.redirect(
+        `${baseUrl}/notification/settings?error=${encodeURIComponent(
+          "Invalid state parameter"
+        )}`,
+        302
+      );
+    }
+
+    const { userId, returnUrl } = stateData;
+    const defaultReturnUrl = "/notification/settings";
+    const finalReturnUrl = returnUrl || defaultReturnUrl;
+
+    try {
+      // Get strategy config to pass to OAuth functions
+      const strategyConfig = await strategyService.getStrategyConfig(
+        strategyId
+      );
+      if (!strategyConfig) {
+        return Response.redirect(
+          `${baseUrl}${finalReturnUrl}?error=${encodeURIComponent(
+            "Strategy not configured"
+          )}`,
+          302
+        );
+      }
+
+      // Exchange code for tokens
+      const callbackUrl = `${baseUrl}/api/notification/oauth/${strategyId}/callback`;
+
+      // Call OAuth config functions with strategy config
+      const clientId = oauth.clientId(strategyConfig);
+      const clientSecret = oauth.clientSecret(strategyConfig);
+      const tokenUrl = oauth.tokenUrl(strategyConfig);
+
+      // Exchange authorization code for tokens
+      const tokenResponse = await fetch(tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          redirect_uri: callbackUrl,
+          client_id: clientId,
+          client_secret: clientSecret,
+        }),
+      });
+
+      if (!tokenResponse.ok) {
+        const errorText = await tokenResponse.text();
+        console.error(`OAuth token exchange failed: ${errorText}`);
+        return Response.redirect(
+          `${baseUrl}${finalReturnUrl}?error=${encodeURIComponent(
+            "Token exchange failed"
+          )}`,
+          302
+        );
+      }
+
+      const tokens = (await tokenResponse.json()) as Record<string, unknown>;
+
+      // Extract tokens using strategy's extractors or defaults
+      const accessToken =
+        oauth.extractAccessToken?.(tokens) || (tokens.access_token as string);
+      const refreshToken =
+        oauth.extractRefreshToken?.(tokens) ||
+        (tokens.refresh_token as string | undefined);
+      const expiresIn =
+        oauth.extractExpiresIn?.(tokens) ||
+        (typeof tokens.expires_in === "number" ? tokens.expires_in : undefined);
+
+      // Extract external ID using strategy's extractor
+      const externalId = oauth.extractExternalId(tokens);
+
+      // Calculate expiration date
+      const expiresAt = expiresIn
+        ? new Date(Date.now() + expiresIn * 1000)
+        : undefined;
+
+      // Store tokens via StrategyService
+      await strategyService.storeOAuthTokens({
+        userId,
+        strategyId,
+        externalId,
+        accessToken,
+        refreshToken,
+        expiresAt,
+      });
+
+      // Redirect to return URL with success
+      return Response.redirect(
+        `${baseUrl}${finalReturnUrl}?linked=${strategyId}`,
+        302
+      );
+    } catch (error_) {
+      console.error("OAuth callback error:", error_);
+      return Response.redirect(
+        `${baseUrl}${finalReturnUrl}?error=${encodeURIComponent(
+          "OAuth processing failed"
+        )}`,
+        302
+      );
+    }
+  };
+}

package/src/retention-config.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+/**
+ * Plugin-level configuration for notification retention policy.
+ * This controls how long notifications are kept before automatic purging.
+ */
+export const retentionConfigV1 = z.object({
+  /**
+   * Whether automatic purging of old notifications is enabled.
+   */
+  enabled: z
+    .boolean()
+    .default(false)
+    .describe("Enable auto-purging of old notifications"),
+
+  /**
+   * Number of days to retain notifications before purging.
+   */
+  retentionDays: z
+    .number()
+    .min(1)
+    .max(365)
+    .default(30)
+    .describe("Number of days to retain notifications before purging"),
+});
+
+export type RetentionConfig = z.infer<typeof retentionConfigV1>;
+
+export const RETENTION_CONFIG_VERSION = 1;
+export const RETENTION_CONFIG_ID = "notification.retention";

package/src/router.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "bun:test";
+
+/**
+ * Basic structural tests for notification-backend.
+ *
+ * Note: Full integration tests with mocked DB chains are complex due to
+ * oRPC middleware validation. These tests verify module exports and basic imports.
+ * More comprehensive testing should be done via integration tests with a real test DB.
+ */
+
+describe("Notification Backend Module", () => {
+  it("exports createNotificationRouter", async () => {
+    const { createNotificationRouter } = await import("./router");
+    expect(createNotificationRouter).toBeDefined();
+    expect(typeof createNotificationRouter).toBe("function");
+  });
+
+  it("exports schema tables", async () => {
+    const schema = await import("./schema");
+    expect(schema.notifications).toBeDefined();
+    expect(schema.notificationGroups).toBeDefined();
+    expect(schema.notificationSubscriptions).toBeDefined();
+  });
+
+  it("exports plugin default", async () => {
+    const plugin = await import("./index");
+    expect(plugin.default).toBeDefined();
+  });
+
+  it("exports service functions", async () => {
+    const service = await import("./service");
+    expect(service.getUserNotifications).toBeDefined();
+    expect(service.getUnreadCount).toBeDefined();
+    expect(service.markAsRead).toBeDefined();
+    expect(service.subscribeToGroup).toBeDefined();
+    expect(service.unsubscribeFromGroup).toBeDefined();
+  });
+});