@checkstack/announcement-backend 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @checkstack/announcement-backend
+
+## 0.2.0
+
+### Minor Changes
+
+- dee86ec: feat: add portal announcement system
+
+  Introduces a complete announcement system for communicating with portal users:
+
+  - **announcement-common**: Zod schemas for announcements (severity, visibility, display mode), oRPC contract with 6 procedures (public retrieval, user dismissal, admin CRUD), access rules, and `ANNOUNCEMENT_UPDATED` signal definition
+  - **announcement-backend**: Drizzle schema with `announcements` and `announcement_dismissals` tables, router with temporal filtering, visibility control, per-user dismissal persistence, user cleanup hook, real-time signal broadcasting on create/update/delete, and command palette registration ("Create Announcement", "Manage Announcements" with `⇧⌘A` shortcut)
+  - **announcement-frontend**: Admin management page with create/edit dialog, global banner component above the navbar (severity-colored, expandable markdown), dashboard cards with compact expand/collapse, admin menu link, and real-time WebSocket signal subscription for instant UI updates
+  - **frontend**: Integrates AnnouncementBanner into App.tsx for global visibility
+
+### Patch Changes
+
+- Updated dependencies [dee86ec]
+  - @checkstack/announcement-common@0.2.0

package/drizzle/0000_cooing_onslaught.sql

@@ -0,0 +1,23 @@
+CREATE TABLE "announcement_dismissals" (
+	"announcement_id" text NOT NULL,
+	"user_id" text NOT NULL,
+	"dismissed_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "announcement_dismissals_announcement_id_user_id_pk" PRIMARY KEY("announcement_id","user_id")
+);
+--> statement-breakpoint
+CREATE TABLE "announcements" (
+	"id" text PRIMARY KEY NOT NULL,
+	"title" text NOT NULL,
+	"message" text NOT NULL,
+	"severity" text DEFAULT 'info' NOT NULL,
+	"visibility" text DEFAULT 'all' NOT NULL,
+	"display_mode" text DEFAULT 'both' NOT NULL,
+	"active" boolean DEFAULT true NOT NULL,
+	"starts_at" timestamp,
+	"expires_at" timestamp,
+	"created_by" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "announcement_dismissals" ADD CONSTRAINT "announcement_dismissals_announcement_id_announcements_id_fk" FOREIGN KEY ("announcement_id") REFERENCES "announcements"("id") ON DELETE cascade ON UPDATE no action;

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,164 @@
+{
+  "id": "fb3688d6-20bb-4c60-8f3b-c0cd4674e705",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.announcement_dismissals": {
+      "name": "announcement_dismissals",
+      "schema": "",
+      "columns": {
+        "announcement_id": {
+          "name": "announcement_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "announcement_dismissals_announcement_id_announcements_id_fk": {
+          "name": "announcement_dismissals_announcement_id_announcements_id_fk",
+          "tableFrom": "announcement_dismissals",
+          "tableTo": "announcements",
+          "columnsFrom": [
+            "announcement_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "announcement_dismissals_announcement_id_user_id_pk": {
+          "name": "announcement_dismissals_announcement_id_user_id_pk",
+          "columns": [
+            "announcement_id",
+            "user_id"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.announcements": {
+      "name": "announcements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "message": {
+          "name": "message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "severity": {
+          "name": "severity",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'info'"
+        },
+        "visibility": {
+          "name": "visibility",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'all'"
+        },
+        "display_mode": {
+          "name": "display_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'both'"
+        },
+        "active": {
+          "name": "active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "starts_at": {
+          "name": "starts_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1776417116365,
+      "tag": "0000_cooing_onslaught",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dialect: "postgresql",
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@checkstack/announcement-backend",
+  "version": "0.2.0",
+  "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"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "0.10.0",
+    "@checkstack/announcement-common": "0.1.0",
+    "@checkstack/auth-backend": "0.4.14",
+    "@checkstack/command-backend": "0.1.15",
+    "@checkstack/common": "0.6.4",
+    "@checkstack/signal-common": "0.1.8",
+    "drizzle-orm": "^0.45.0",
+    "zod": "^4.2.1",
+    "@orpc/server": "^1.13.2"
+  },
+  "devDependencies": {
+    "@checkstack/drizzle-helper": "0.0.4",
+    "@checkstack/scripts": "0.1.2",
+    "@checkstack/test-utils-backend": "0.1.15",
+    "@checkstack/tsconfig": "0.0.4",
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import {
+  pluginMetadata,
+  announcementContract,
+  announcementAccessRules,
+  announcementAccess,
+  announcementRoutes,
+} from "@checkstack/announcement-common";
+import { resolveRoute } from "@checkstack/common";
+import { eq } from "drizzle-orm";
+import * as schema from "./schema";
+import { createAnnouncementRouter } from "./router";
+import { authHooks } from "@checkstack/auth-backend";
+import { registerSearchProvider } from "@checkstack/command-backend";
+import type { SafeDatabase } from "@checkstack/backend-api";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Register access rules
+    env.registerAccessRules(announcementAccessRules);
+
+    env.registerInit({
+      schema,
+      deps: {
+        rpc: coreServices.rpc,
+        logger: coreServices.logger,
+        signalService: coreServices.signalService,
+      },
+      init: async ({ database, rpc, signalService }) => {
+        const db = database as SafeDatabase<typeof schema>;
+
+        // Create and register the announcement router
+        const router = createAnnouncementRouter(db, signalService);
+        rpc.registerRouter(router, announcementContract);
+
+        // Register commands in the command palette
+        registerSearchProvider({
+          pluginMetadata,
+          commands: [
+            {
+              id: "create",
+              title: "Create Announcement",
+              subtitle: "Create a new portal announcement",
+              iconName: "Megaphone",
+              route:
+                resolveRoute(announcementRoutes.routes.manage) +
+                "?action=create",
+              requiredAccessRules: [announcementAccess.manage],
+            },
+            {
+              id: "manage",
+              title: "Manage Announcements",
+              subtitle: "View and manage portal announcements",
+              iconName: "Megaphone",
+              shortcuts: ["meta+shift+a", "ctrl+shift+a"],
+              route: resolveRoute(announcementRoutes.routes.manage),
+              requiredAccessRules: [announcementAccess.manage],
+            },
+          ],
+        });
+      },
+      afterPluginsReady: async ({ database, logger, onHook }) => {
+        const db = database as SafeDatabase<typeof schema>;
+
+        // Clean up dismissals when a user is deleted
+        onHook(
+          authHooks.userDeleted,
+          async ({ userId }) => {
+            logger.debug(
+              `Cleaning up announcement dismissals for deleted user: ${userId}`,
+            );
+            await db
+              .delete(schema.announcementDismissals)
+              .where(eq(schema.announcementDismissals.userId, userId));
+            logger.debug(
+              `Cleaned up announcement dismissals for user: ${userId}`,
+            );
+          },
+          { mode: "work-queue", workerGroup: "user-cleanup" },
+        );
+
+        logger.debug("✅ Announcement Backend afterPluginsReady complete.");
+      },
+    });
+  },
+});

package/src/router.test.ts

@@ -0,0 +1,403 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { createAnnouncementRouter } from "./router";
+import { createMockRpcContext } from "@checkstack/backend-api";
+import { createMockDb } from "@checkstack/test-utils-backend";
+import { ANNOUNCEMENT_UPDATED } from "@checkstack/announcement-common";
+import { call } from "@orpc/server";
+
+describe("Announcement Router", () => {
+  const adminUser = {
+    type: "user" as const,
+    id: "admin-user-1",
+    accessRules: ["*"],
+    roles: [],
+  };
+
+  const regularUser = {
+    type: "user" as const,
+    id: "regular-user-1",
+    accessRules: ["announcement.announcement.read"],
+    roles: [],
+  };
+
+  let mockDb: ReturnType<typeof createMockDb>;
+  let router: ReturnType<typeof createAnnouncementRouter>;
+
+  const mockSignalService = {
+    broadcast: mock(() => Promise.resolve()),
+    sendToUser: mock(() => Promise.resolve()),
+    sendToUsers: mock(() => Promise.resolve()),
+    sendToAuthorizedUsers: mock(() => Promise.resolve()),
+  };
+
+  const sampleAnnouncement = {
+    id: "ann-1",
+    title: "Test Announcement",
+    message: "This is a **test** announcement.",
+    severity: "info",
+    visibility: "all",
+    displayMode: "both",
+    active: true,
+    startsAt: undefined,
+    expiresAt: undefined,
+    createdBy: "admin-user-1",
+    createdAt: new Date("2026-04-17T10:00:00Z"),
+    updatedAt: new Date("2026-04-17T10:00:00Z"),
+  };
+
+  beforeEach(() => {
+    mockDb = createMockDb();
+    mockSignalService.broadcast.mockClear();
+    router = createAnnouncementRouter(mockDb as never, mockSignalService);
+  });
+
+  // ---------------------------------------------------------------------------
+  // getActiveAnnouncements
+  // ---------------------------------------------------------------------------
+  describe("getActiveAnnouncements", () => {
+    it("returns active announcements for anonymous users", async () => {
+      const context = createMockRpcContext({ user: undefined });
+
+      // Mock select chain for announcements query
+      const mockWhereChain = Promise.resolve([sampleAnnouncement]);
+      const mockFromChain = Object.assign(
+        Promise.resolve([sampleAnnouncement]),
+        { where: mock(() => mockWhereChain) },
+      );
+      mockDb.select.mockReturnValueOnce({
+        from: mock(() => mockFromChain),
+      } as never);
+
+      const result = await call(router.getActiveAnnouncements, undefined, {
+        context,
+      });
+
+      expect(result.announcements).toHaveLength(1);
+      expect(result.announcements[0].title).toBe("Test Announcement");
+    });
+
+    it("filters out authenticated-only announcements for anonymous users", async () => {
+      const context = createMockRpcContext({ user: undefined });
+
+      const authenticatedOnly = {
+        ...sampleAnnouncement,
+        id: "ann-2",
+        visibility: "authenticated",
+      };
+
+      const mockWhereChain = Promise.resolve([
+        sampleAnnouncement,
+        authenticatedOnly,
+      ]);
+      const mockFromChain = Object.assign(
+        Promise.resolve([sampleAnnouncement, authenticatedOnly]),
+        { where: mock(() => mockWhereChain) },
+      );
+      mockDb.select.mockReturnValueOnce({
+        from: mock(() => mockFromChain),
+      } as never);
+
+      const result = await call(router.getActiveAnnouncements, undefined, {
+        context,
+      });
+
+      // Only the "all" visibility announcement should be returned
+      expect(result.announcements).toHaveLength(1);
+      expect(result.announcements[0].visibility).toBe("all");
+    });
+
+    it("excludes dismissed announcements for authenticated users", async () => {
+      const context = createMockRpcContext({ user: adminUser });
+
+      // First query: active announcements
+      const mockWhereChain = Promise.resolve([sampleAnnouncement]);
+      const mockFromChain = Object.assign(
+        Promise.resolve([sampleAnnouncement]),
+        { where: mock(() => mockWhereChain) },
+      );
+      mockDb.select.mockReturnValueOnce({
+        from: mock(() => mockFromChain),
+      } as never);
+
+      // Second query: dismissals for this user (ann-1 is dismissed)
+      const dismissalWhereChain = Promise.resolve([
+        { announcementId: "ann-1" },
+      ]);
+      const dismissalFromChain = Object.assign(
+        Promise.resolve([{ announcementId: "ann-1" }]),
+        { where: mock(() => dismissalWhereChain) },
+      );
+      mockDb.select.mockReturnValueOnce({
+        from: mock(() => dismissalFromChain),
+      } as never);
+
+      const result = await call(router.getActiveAnnouncements, undefined, {
+        context,
+      });
+
+      expect(result.announcements).toHaveLength(0);
+    });
+
+    it("includes dismissed announcements when includeDismissed is true", async () => {
+      const context = createMockRpcContext({ user: adminUser });
+
+      // Query returns one active announcement
+      const mockWhereChain = Promise.resolve([sampleAnnouncement]);
+      const mockFromChain = Object.assign(
+        Promise.resolve([sampleAnnouncement]),
+        { where: mock(() => mockWhereChain) },
+      );
+      mockDb.select.mockReturnValueOnce({
+        from: mock(() => mockFromChain),
+      } as never);
+
+      // No second select should happen (dismissals query is skipped)
+      const result = await call(
+        router.getActiveAnnouncements,
+        { includeDismissed: true },
+        { context },
+      );
+
+      // ann-1 should still be returned even though it would normally be dismissed
+      expect(result.announcements).toHaveLength(1);
+      expect(result.announcements[0].id).toBe("ann-1");
+      // Only one select call (no dismissal query)
+      expect(mockDb.select).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // dismissAnnouncement
+  // ---------------------------------------------------------------------------
+  describe("dismissAnnouncement", () => {
+    it("creates a dismissal record for authenticated users", async () => {
+      const context = createMockRpcContext({ user: regularUser });
+
+      // Mock: check announcement exists
+      const mockWhereChain = Object.assign(Promise.resolve([{ id: "ann-1" }]), {
+        limit: mock(() => Promise.resolve([{ id: "ann-1" }])),
+      });
+      const mockFromChain = Object.assign(
+        Promise.resolve([{ id: "ann-1" }]),
+        { where: mock(() => mockWhereChain) },
+      );
+      mockDb.select.mockReturnValueOnce({
+        from: mock(() => mockFromChain),
+      } as never);
+
+      // Mock: insert dismissal with onConflictDoNothing chain
+      mockDb.insert.mockReturnValueOnce({
+        values: mock(() => ({
+          onConflictDoNothing: mock(() => Promise.resolve()),
+        })),
+      } as never);
+
+      await call(
+        router.dismissAnnouncement,
+        { announcementId: "ann-1" },
+        { context },
+      );
+
+      expect(mockDb.insert).toHaveBeenCalled();
+    });
+
+    it("rejects unauthenticated users", async () => {
+      const context = createMockRpcContext({ user: undefined });
+
+      await expect(
+        call(
+          router.dismissAnnouncement,
+          { announcementId: "ann-1" },
+          { context },
+        ),
+      ).rejects.toThrow("Authentication required");
+    });
+
+    it("throws NOT_FOUND for non-existent announcements", async () => {
+      const context = createMockRpcContext({ user: regularUser });
+
+      // Mock: announcement not found
+      const mockWhereChain = Object.assign(Promise.resolve([]), {
+        limit: mock(() => Promise.resolve([])),
+      });
+      const mockFromChain = Object.assign(Promise.resolve([]), {
+        where: mock(() => mockWhereChain),
+      });
+      mockDb.select.mockReturnValueOnce({
+        from: mock(() => mockFromChain),
+      } as never);
+
+      await expect(
+        call(
+          router.dismissAnnouncement,
+          { announcementId: "nonexistent" },
+          { context },
+        ),
+      ).rejects.toThrow("Announcement not found");
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Admin: CRUD operations
+  // ---------------------------------------------------------------------------
+  describe("createAnnouncement", () => {
+    it("creates an announcement with all fields", async () => {
+      const context = createMockRpcContext({ user: adminUser });
+
+      // Mock: insert with returning chain
+      const createdRow = {
+        ...sampleAnnouncement,
+        id: "new-id",
+        title: "New Announcement",
+        severity: "warning",
+        displayMode: "banner",
+        createdBy: adminUser.id,
+      };
+      mockDb.insert.mockReturnValueOnce({
+        values: mock(() => ({
+          returning: mock(() => Promise.resolve([createdRow])),
+        })),
+      } as never);
+
+      const result = await call(
+        router.createAnnouncement,
+        {
+          title: "New Announcement",
+          message: "Important update!",
+          severity: "warning",
+          visibility: "all",
+          displayMode: "banner",
+          active: true,
+        },
+        { context },
+      );
+
+      expect(mockDb.insert).toHaveBeenCalled();
+      expect(result.title).toBe("New Announcement");
+      expect(result.severity).toBe("warning");
+      expect(result.displayMode).toBe("banner");
+
+      // Verify signal was broadcast
+      expect(mockSignalService.broadcast).toHaveBeenCalledWith(
+        ANNOUNCEMENT_UPDATED,
+        { announcementId: "new-id", action: "created" },
+      );
+    });
+
+    it("rejects unauthenticated users", async () => {
+      const context = createMockRpcContext({ user: undefined });
+
+      await expect(
+        call(
+          router.createAnnouncement,
+          {
+            title: "Test",
+            message: "Test",
+            severity: "info",
+            visibility: "all",
+            displayMode: "both",
+          },
+          { context },
+        ),
+      ).rejects.toThrow("Authentication required");
+    });
+  });
+
+  describe("updateAnnouncement", () => {
+    it("updates an existing announcement", async () => {
+      const context = createMockRpcContext({ user: adminUser });
+
+      const updatedRow = { ...sampleAnnouncement, title: "Updated Title" };
+      mockDb.update.mockReturnValueOnce({
+        set: mock(() => ({
+          where: mock(() => ({
+            returning: mock(() => Promise.resolve([updatedRow])),
+          })),
+        })),
+      } as never);
+
+      const result = await call(
+        router.updateAnnouncement,
+        { id: "ann-1", title: "Updated Title" },
+        { context },
+      );
+
+      expect(result.title).toBe("Updated Title");
+
+      // Verify signal was broadcast
+      expect(mockSignalService.broadcast).toHaveBeenCalledWith(
+        ANNOUNCEMENT_UPDATED,
+        { announcementId: "ann-1", action: "updated" },
+      );
+    });
+
+    it("throws NOT_FOUND for non-existent announcement", async () => {
+      const context = createMockRpcContext({ user: adminUser });
+
+      mockDb.update.mockReturnValueOnce({
+        set: mock(() => ({
+          where: mock(() => ({
+            returning: mock(() => Promise.resolve([])),
+          })),
+        })),
+      } as never);
+
+      await expect(
+        call(
+          router.updateAnnouncement,
+          { id: "nonexistent", title: "Test" },
+          { context },
+        ),
+      ).rejects.toThrow("Announcement not found");
+    });
+  });
+
+  describe("deleteAnnouncement", () => {
+    it("deletes an announcement and returns success", async () => {
+      const context = createMockRpcContext({ user: adminUser });
+
+      // Mock: delete with returning chain
+      mockDb.delete.mockReturnValueOnce({
+        where: mock(() => ({
+          returning: mock(() => Promise.resolve([{ id: "ann-1" }])),
+        })),
+      } as never);
+
+      const result = await call(
+        router.deleteAnnouncement,
+        { id: "ann-1" },
+        { context },
+      );
+
+      expect(result.success).toBe(true);
+      expect(mockDb.delete).toHaveBeenCalled();
+
+      // Verify signal was broadcast
+      expect(mockSignalService.broadcast).toHaveBeenCalledWith(
+        ANNOUNCEMENT_UPDATED,
+        { announcementId: "ann-1", action: "deleted" },
+      );
+    });
+  });
+
+  describe("listAllAnnouncements", () => {
+    it("returns all announcements for admins", async () => {
+      const context = createMockRpcContext({ user: adminUser });
+
+      const mockOrderByChain = Promise.resolve([sampleAnnouncement]);
+      const mockFromChain = Object.assign(
+        Promise.resolve([sampleAnnouncement]),
+        { orderBy: mock(() => mockOrderByChain) },
+      );
+      mockDb.select.mockReturnValueOnce({
+        from: mock(() => mockFromChain),
+      } as never);
+
+      const result = await call(router.listAllAnnouncements, undefined, {
+        context,
+      });
+
+      expect(result.announcements).toHaveLength(1);
+    });
+  });
+});

package/src/router.ts

@@ -0,0 +1,255 @@
+import { implement, ORPCError } from "@orpc/server";
+import {
+  announcementContract,
+  ANNOUNCEMENT_UPDATED,
+  type Announcement,
+} from "@checkstack/announcement-common";
+import type { SignalService } from "@checkstack/signal-common";
+import {
+  autoAuthMiddleware,
+  type RpcContext,
+  type RealUser,
+} from "@checkstack/backend-api";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import * as schema from "./schema";
+import { eq, and, or, lte, gte, isNull } from "drizzle-orm";
+
+type AnnouncementDb = SafeDatabase<typeof schema>;
+
+/**
+ * Maps a database row to the Announcement domain type.
+ */
+function toAnnouncement(
+  row: typeof schema.announcements.$inferSelect,
+): Announcement {
+  return {
+    id: row.id,
+    title: row.title,
+    message: row.message,
+    severity: row.severity as Announcement["severity"],
+    visibility: row.visibility as Announcement["visibility"],
+    displayMode: row.displayMode as Announcement["displayMode"],
+    active: row.active,
+    startsAt: row.startsAt ?? undefined,
+    expiresAt: row.expiresAt ?? undefined,
+    createdBy: row.createdBy,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+/**
+ * Creates the announcement router using contract-based implementation.
+ */
+export function createAnnouncementRouter(
+  db: AnnouncementDb,
+  signalService: SignalService,
+) {
+  const os = implement(announcementContract)
+    .$context<RpcContext>()
+    .use(autoAuthMiddleware);
+
+  return os.router({
+    // -------------------------------------------------------------------------
+    // Public: Get active announcements
+    // -------------------------------------------------------------------------
+    getActiveAnnouncements: os.getActiveAnnouncements.handler(
+      async ({ input, context }) => {
+        const now = new Date();
+        const includeDismissed = input?.includeDismissed ?? false;
+
+        // Base query: active announcements within their time window
+        const rows = await db
+          .select()
+          .from(schema.announcements)
+          .where(
+            and(
+              eq(schema.announcements.active, true),
+              or(
+                isNull(schema.announcements.startsAt),
+                lte(schema.announcements.startsAt, now),
+              ),
+              or(
+                isNull(schema.announcements.expiresAt),
+                gte(schema.announcements.expiresAt, now),
+              ),
+            ),
+          );
+
+        let announcements = rows.map((row) => toAnnouncement(row));
+
+        // If the caller is authenticated, filter out their dismissed announcements
+        // (unless includeDismissed is explicitly requested, e.g. for dashboard)
+        const user = context.user;
+        if (!includeDismissed && user && "id" in user) {
+          const userId = (user as RealUser).id;
+          const dismissals = await db
+            .select({ announcementId: schema.announcementDismissals.announcementId })
+            .from(schema.announcementDismissals)
+            .where(eq(schema.announcementDismissals.userId, userId));
+
+          const dismissedIds = new Set(dismissals.map((d) => d.announcementId));
+          announcements = announcements.filter((a) => !dismissedIds.has(a.id));
+        }
+
+        // Filter visibility for unauthenticated users
+        if (!user) {
+          announcements = announcements.filter(
+            (a) => a.visibility === "all",
+          );
+        }
+
+        return { announcements };
+      },
+    ),
+
+    // -------------------------------------------------------------------------
+    // Authenticated: Dismiss an announcement
+    // -------------------------------------------------------------------------
+    dismissAnnouncement: os.dismissAnnouncement.handler(
+      async ({ input, context }) => {
+        const userId = (context.user as RealUser).id;
+
+        // Verify the announcement exists
+        const existing = await db
+          .select({ id: schema.announcements.id })
+          .from(schema.announcements)
+          .where(eq(schema.announcements.id, input.announcementId))
+          .limit(1);
+
+        if (existing.length === 0) {
+          throw new ORPCError("NOT_FOUND", {
+            message: "Announcement not found",
+          });
+        }
+
+        // Upsert dismissal (idempotent)
+        await db
+          .insert(schema.announcementDismissals)
+          .values({
+            announcementId: input.announcementId,
+            userId,
+            dismissedAt: new Date(),
+          })
+          .onConflictDoNothing();
+      },
+    ),
+
+    // -------------------------------------------------------------------------
+    // Admin: List all announcements
+    // -------------------------------------------------------------------------
+    listAllAnnouncements: os.listAllAnnouncements.handler(async () => {
+      const rows = await db
+        .select()
+        .from(schema.announcements)
+        .orderBy(schema.announcements.createdAt);
+
+      return { announcements: rows.map((row) => toAnnouncement(row)) };
+    }),
+
+    // -------------------------------------------------------------------------
+    // Admin: Create announcement
+    // -------------------------------------------------------------------------
+    createAnnouncement: os.createAnnouncement.handler(
+      async ({ input, context }) => {
+        const userId =
+          context.user && "id" in context.user ? context.user.id : "system";
+        const id = crypto.randomUUID();
+        const now = new Date();
+
+        const [row] = await db
+          .insert(schema.announcements)
+          .values({
+            id,
+            title: input.title,
+            message: input.message,
+            severity: input.severity,
+            visibility: input.visibility,
+            displayMode: input.displayMode,
+            active: input.active ?? true,
+            startsAt: input.startsAt ?? undefined,
+            expiresAt: input.expiresAt ?? undefined,
+            createdBy: userId,
+            createdAt: now,
+            updatedAt: now,
+          })
+          .returning();
+
+        const announcement = toAnnouncement(row);
+
+        await signalService.broadcast(ANNOUNCEMENT_UPDATED, {
+          announcementId: announcement.id,
+          action: "created",
+        });
+
+        return announcement;
+      },
+    ),
+
+    // -------------------------------------------------------------------------
+    // Admin: Update announcement
+    // -------------------------------------------------------------------------
+    updateAnnouncement: os.updateAnnouncement.handler(async ({ input }) => {
+      const { id, ...updates } = input;
+
+      // Build update object, only including provided fields
+      const updateData: Record<string, unknown> = {
+        updatedAt: new Date(),
+      };
+
+      if (updates.title !== undefined) updateData.title = updates.title;
+      if (updates.message !== undefined) updateData.message = updates.message;
+      if (updates.severity !== undefined) updateData.severity = updates.severity;
+      if (updates.visibility !== undefined)
+        updateData.visibility = updates.visibility;
+      if (updates.displayMode !== undefined)
+        updateData.displayMode = updates.displayMode;
+      if (updates.active !== undefined) updateData.active = updates.active;
+      if (updates.startsAt !== undefined) updateData.startsAt = updates.startsAt;
+      if (updates.expiresAt !== undefined)
+        updateData.expiresAt = updates.expiresAt;
+
+      const [row] = await db
+        .update(schema.announcements)
+        .set(updateData)
+        .where(eq(schema.announcements.id, id))
+        .returning();
+
+      if (!row) {
+        throw new ORPCError("NOT_FOUND", {
+          message: "Announcement not found",
+        });
+      }
+
+      const announcement = toAnnouncement(row);
+
+      await signalService.broadcast(ANNOUNCEMENT_UPDATED, {
+        announcementId: announcement.id,
+        action: "updated",
+      });
+
+      return announcement;
+    }),
+
+    // -------------------------------------------------------------------------
+    // Admin: Delete announcement
+    // -------------------------------------------------------------------------
+    deleteAnnouncement: os.deleteAnnouncement.handler(async ({ input }) => {
+      const result = await db
+        .delete(schema.announcements)
+        .where(eq(schema.announcements.id, input.id))
+        .returning({ id: schema.announcements.id });
+
+      if (result.length > 0) {
+        await signalService.broadcast(ANNOUNCEMENT_UPDATED, {
+          announcementId: input.id,
+          action: "deleted",
+        });
+      }
+
+      return { success: result.length > 0 };
+    }),
+  });
+}
+
+export type AnnouncementRouter = ReturnType<typeof createAnnouncementRouter>;

package/src/schema.ts

@@ -0,0 +1,44 @@
+import {
+  pgTable,
+  text,
+  timestamp,
+  boolean,
+  primaryKey,
+} from "drizzle-orm/pg-core";
+
+/**
+ * Main announcements table.
+ * Stores admin-created portal announcements with temporal lifecycle support.
+ */
+export const announcements = pgTable("announcements", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  message: text("message").notNull(),
+  severity: text("severity").notNull().default("info"),
+  visibility: text("visibility").notNull().default("all"),
+  displayMode: text("display_mode").notNull().default("both"),
+  active: boolean("active").notNull().default(true),
+  startsAt: timestamp("starts_at"),
+  expiresAt: timestamp("expires_at"),
+  createdBy: text("created_by").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+});
+
+/**
+ * Tracks which announcements have been dismissed by which users.
+ * Allows server-side persistence of dismissals for authenticated users.
+ */
+export const announcementDismissals = pgTable(
+  "announcement_dismissals",
+  {
+    announcementId: text("announcement_id")
+      .notNull()
+      .references(() => announcements.id, { onDelete: "cascade" }),
+    userId: text("user_id").notNull(),
+    dismissedAt: timestamp("dismissed_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    pk: primaryKey(t.announcementId, t.userId),
+  }),
+);

package/tsconfig.json

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