@checkstack/announcement-common 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @checkstack/announcement-common
+
+## 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

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@checkstack/announcement-common",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.6.4",
+    "@checkstack/signal-common": "0.1.8",
+    "@orpc/contract": "^1.13.14",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.4",
+    "@checkstack/scripts": "0.1.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,20 @@
+import { access } from "@checkstack/common";
+
+/**
+ * Access rules for the Announcement plugin.
+ * Announcements don't use instance-level access (no teams/resource filtering).
+ * Only a single "manage" rule is needed — reading active announcements is public.
+ */
+export const announcementAccess = {
+  /** Manage announcements — create, edit, and delete. Admin-only. */
+  manage: access(
+    "announcement",
+    "manage",
+    "Manage announcements — create, edit, and delete",
+  ),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const announcementAccessRules = [announcementAccess.manage];

package/src/index.ts

@@ -0,0 +1,23 @@
+export { announcementAccess, announcementAccessRules } from "./access";
+export {
+  announcementContract,
+  AnnouncementApi,
+  type AnnouncementContract,
+} from "./rpc-contract";
+export {
+  AnnouncementSeverityEnum,
+  AnnouncementVisibilityEnum,
+  AnnouncementDisplayModeEnum,
+  AnnouncementSchema,
+  CreateAnnouncementInputSchema,
+  UpdateAnnouncementInputSchema,
+  type AnnouncementSeverity,
+  type AnnouncementVisibility,
+  type AnnouncementDisplayMode,
+  type Announcement,
+  type CreateAnnouncementInput,
+  type UpdateAnnouncementInput,
+} from "./schemas";
+export * from "./plugin-metadata";
+export { announcementRoutes } from "./routes";
+export { ANNOUNCEMENT_UPDATED } from "./signals";

package/src/plugin-metadata.ts

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

package/src/routes.ts

@@ -0,0 +1,8 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the announcement plugin.
+ */
+export const announcementRoutes = createRoutes("announcement", {
+  manage: "/manage",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { createClientDefinition, proc } from "@checkstack/common";
+import { announcementAccess } from "./access";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  AnnouncementSchema,
+  CreateAnnouncementInputSchema,
+  UpdateAnnouncementInputSchema,
+} from "./schemas";
+
+export const announcementContract = {
+  // ---------------------------------------------------------------------------
+  // Public endpoints
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get currently active announcements.
+   * Public endpoint — anyone can read active announcements.
+   * If the caller is authenticated, dismissed announcements are excluded.
+   */
+  getActiveAnnouncements: proc({
+    operationType: "query",
+    userType: "public",
+    access: [],
+  })
+    .input(
+      z
+        .object({
+          /** If true, include dismissed announcements in the result. */
+          includeDismissed: z.boolean().optional(),
+        })
+        .optional(),
+    )
+    .output(z.object({ announcements: z.array(AnnouncementSchema) })),
+
+  // ---------------------------------------------------------------------------
+  // Authenticated user endpoints
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Dismiss an announcement for the current user.
+   * Records a server-side dismissal so the announcement won't appear again.
+   */
+  dismissAnnouncement: proc({
+    operationType: "mutation",
+    userType: "user",
+    access: [],
+  })
+    .input(z.object({ announcementId: z.string() }))
+    .output(z.void()),
+
+  // ---------------------------------------------------------------------------
+  // Admin endpoints
+  // ---------------------------------------------------------------------------
+
+  /** List all announcements regardless of active/temporal state (admin view). */
+  listAllAnnouncements: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [announcementAccess.manage],
+  }).output(z.object({ announcements: z.array(AnnouncementSchema) })),
+
+  /** Create a new announcement. */
+  createAnnouncement: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [announcementAccess.manage],
+  })
+    .input(CreateAnnouncementInputSchema)
+    .output(AnnouncementSchema),
+
+  /** Update an existing announcement. */
+  updateAnnouncement: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [announcementAccess.manage],
+  })
+    .input(UpdateAnnouncementInputSchema)
+    .output(AnnouncementSchema),
+
+  /** Delete an announcement permanently. */
+  deleteAnnouncement: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [announcementAccess.manage],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+};
+
+// Export contract type
+export type AnnouncementContract = typeof announcementContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(AnnouncementApi);
+export const AnnouncementApi = createClientDefinition(
+  announcementContract,
+  pluginMetadata,
+);

package/src/schemas.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+
+/**
+ * Announcement severity determines the visual styling of the announcement.
+ * - info: Blue/primary accent — general information
+ * - warning: Amber — important notice
+ * - critical: Red/destructive — urgent alert
+ */
+export const AnnouncementSeverityEnum = z.enum(["info", "warning", "critical"]);
+export type AnnouncementSeverity = z.infer<typeof AnnouncementSeverityEnum>;
+
+/**
+ * Controls who can see the announcement.
+ * - all: Everyone, including unauthenticated visitors
+ * - authenticated: Only logged-in users
+ */
+export const AnnouncementVisibilityEnum = z.enum(["all", "authenticated"]);
+export type AnnouncementVisibility = z.infer<typeof AnnouncementVisibilityEnum>;
+
+/**
+ * Controls where the announcement is displayed.
+ * - banner: Global strip above the navbar on every page
+ * - dashboard: Card in the dashboard Overview section
+ * - both: Displayed in both locations
+ */
+export const AnnouncementDisplayModeEnum = z.enum([
+  "banner",
+  "dashboard",
+  "both",
+]);
+export type AnnouncementDisplayMode = z.infer<
+  typeof AnnouncementDisplayModeEnum
+>;
+
+/**
+ * Core announcement entity schema.
+ */
+export const AnnouncementSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  message: z.string(),
+  severity: AnnouncementSeverityEnum,
+  visibility: AnnouncementVisibilityEnum,
+  displayMode: AnnouncementDisplayModeEnum,
+  active: z.boolean(),
+  startsAt: z.date().optional(),
+  expiresAt: z.date().optional(),
+  createdBy: z.string(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type Announcement = z.infer<typeof AnnouncementSchema>;
+
+/**
+ * Input schema for creating an announcement.
+ */
+export const CreateAnnouncementInputSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+  message: z.string().min(1, "Message is required"),
+  severity: AnnouncementSeverityEnum,
+  visibility: AnnouncementVisibilityEnum,
+  displayMode: AnnouncementDisplayModeEnum,
+  active: z.boolean().optional().default(true),
+  startsAt: z.date().optional(),
+  expiresAt: z.date().optional(),
+});
+export type CreateAnnouncementInput = z.infer<
+  typeof CreateAnnouncementInputSchema
+>;
+
+/**
+ * Input schema for updating an announcement.
+ */
+export const UpdateAnnouncementInputSchema = z.object({
+  id: z.string(),
+  title: z.string().min(1).optional(),
+  message: z.string().min(1).optional(),
+  severity: AnnouncementSeverityEnum.optional(),
+  visibility: AnnouncementVisibilityEnum.optional(),
+  displayMode: AnnouncementDisplayModeEnum.optional(),
+  active: z.boolean().optional(),
+  startsAt: z.date().optional(),
+  expiresAt: z.date().optional(),
+});
+export type UpdateAnnouncementInput = z.infer<
+  typeof UpdateAnnouncementInputSchema
+>;

package/src/signals.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { createSignal } from "@checkstack/signal-common";
+
+/**
+ * Broadcast when an announcement is created, updated, or deleted.
+ * Frontend components listening to this signal should refetch active announcements.
+ */
+export const ANNOUNCEMENT_UPDATED = createSignal(
+  "announcement.updated",
+  z.object({
+    announcementId: z.string(),
+    action: z.enum(["created", "updated", "deleted"]),
+  }),
+);

package/tsconfig.json

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