@checkstack/notification-common 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @checkstack/notification-common
 
+## 1.2.0
+
+### Minor Changes
+
+- f23f3c9: Add per-channel notification delivery-attempt tracking
+  (Phase 8 of the v1 polishing plan). The external dispatch loop now
+  persists one row per `strategy.send(...)` call into a new
+  `notification_delivery_attempts` table - both successes and
+  failures - so silent delivery breakage (misconfigured webhooks, dead
+  channels) becomes queryable instead of buried in logs.
+
+  - `@checkstack/notification-backend` adds the
+    `notification_delivery_attempts` table, the matching Drizzle
+    migration, and a new `dispatchWithAttempt` helper that wraps every
+    external `strategy.send(...)` with duration measurement and
+    best-effort row persistence. The insert is intentionally
+    fire-and-forget: if writing the attempt row itself errors, the
+    dispatch loop logs and continues so visibility tracking can never
+    introduce a _new_ silent failure.
+  - `@checkstack/notification-common` exports a new
+    `DeliveryAttemptSchema` zod schema, the
+    `ListDeliveryAttemptsInputSchema =
+PaginationInput.extend({ notificationId })` input, and a new
+    `getDeliveryAttempts` procedure on the contract. The procedure is
+    gated by the existing `notificationAccess.admin`
+    (`notification:manage`) access rule - no new permission was
+    introduced.
+  - `@checkstack/notification-frontend` adds a minimal admin-only
+    `DeliveryAttemptsPage` (route id `notification.deliveryAttempts`,
+    path `/notifications/delivery-attempts`) and an "Open inspector"
+    link from the Notification Settings page for users with
+    `notification:manage`. No client-side `isAdmin` gate - the FORBIDDEN
+    case is rendered via the standard error-state branch on the page,
+    enforced by the contract.
+
+  Visibility only: there is no retry mechanism in this phase. A
+  `failure` row is a final outcome an admin actions manually
+  (re-trigger the source event, fix the misconfigured channel).
+  Automated retries are deferred to v1.1.
+
+  Strategy errors thrown during `send(...)` are persisted via
+  `extractErrorMessage(error)` so secrets potentially embedded in raw
+  error objects (webhook URLs, OAuth tokens reachable from the strategy
+  send context) are not stored verbatim.
+
+  See the new
+  `docs/src/content/docs/backend/notification-delivery.md` page for the
+  full surface description.
+
+- f23f3c9: Sweep every paginated `*-common` contract onto the canonical
+  `PaginationInput` / `PaginatedResult` from `@checkstack/common` and
+  remove the now-unused legacy exports.
+
+  **BREAKING CHANGE** - `@checkstack/common` drops the deprecated
+  `PaginationInputSchema`, `paginatedOutput`, and `PaginatedResponse`
+  symbols. Callers must consume `PaginationInput` (input) and
+  `PaginatedResult(itemSchema)` (output) instead. The canonical input is
+  `{ limit (1-100, default 20), offset (>= 0, default 0) }`; the
+  canonical output envelope is
+  `{ items, total, limit, offset }`.
+
+  **BREAKING CHANGE** - `@checkstack/notification-common` migrates
+  `getNotifications` off the legacy `PaginationInputSchema`
+  (`{ limit, offset, unreadOnly }` with output `{ notifications, total }`)
+  onto `ListNotificationsInputSchema =
+PaginationInput.extend({ unreadOnly })` and
+  `PaginatedResult(NotificationSchema)`. The output key changes from
+  `notifications` to `items`, and `limit` / `offset` are now echoed on
+  the response. The `PaginationInput` type alias previously exported
+  from `notification-common` is removed - use `ListNotificationsInput`
+  or the canonical `PaginationInput` from `@checkstack/common`.
+
+  **BREAKING CHANGE** - `@checkstack/integration-common` migrates
+  `listSubscriptions` (inline `{ page, pageSize, ... }` -> output
+  `{ subscriptions, total }`) and `getDeliveryLogs` (via
+  `DeliveryLogQueryInputSchema` `{ subscriptionId?, eventType?, status?,
+page, pageSize }` -> output `{ logs, total }`) onto the canonical
+  `PaginationInput.extend({...})` input and
+  `PaginatedResult(itemSchema)` output. External callers must switch
+  from `{ page, pageSize }` to `{ limit, offset }` and read response
+  items from `data.items` (no more `data.subscriptions` / `data.logs`).
+
+  The matching `*-backend` handlers were updated to consume the new
+  input shape (`offset` arithmetic in lieu of `(page - 1) * pageSize`)
+  and to echo `limit` / `offset` on the response. The `*-frontend` call
+  sites in `NotificationsPage`, `NotificationBell`, `IntegrationsPage`,
+  and `DeliveryLogsPage` were updated to send the new input shape and
+  read `data.items`.
+
+### Patch Changes
+
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+  - @checkstack/common@0.11.0
+  - @checkstack/signal-common@0.2.4
+
 ## 1.1.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/notification-common",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {

package/src/routes.ts

@@ -6,4 +6,10 @@ import { createRoutes } from "@checkstack/common";
 export const notificationRoutes = createRoutes("notification", {
   home: "/",
   settings: "/settings",
+  /**
+   * Admin-only visibility surface for per-channel delivery attempts.
+   * Visibility, not a dashboard — see Phase 8 of the v1 polishing
+   * plan and `docs/.../backend/notification-delivery.md`.
+   */
+  deliveryAttempts: "/delivery-attempts",
 });

package/src/rpc-contract.ts

@@ -1,14 +1,20 @@
 import { z } from "zod";
 import { notificationAccess } from "./access";
 import { pluginMetadata } from "./plugin-metadata";
-import { createClientDefinition, proc } from "@checkstack/common";
+import {
+  createClientDefinition,
+  PaginatedResult,
+  proc,
+} from "@checkstack/common";
 import {
   NotificationSchema,
   NotificationGroupSchema,
   EnrichedSubscriptionSchema,
   RetentionSettingsSchema,
-  PaginationInputSchema,
+  ListNotificationsInputSchema,
   NotificationSubjectSchema,
+  DeliveryAttemptSchema,
+  ListDeliveryAttemptsInputSchema,
 } from "./schemas";
 
 // Shared input fragments for the notify* procedures.
@@ -78,13 +84,8 @@ export const notificationContract = {
     userType: "user",
     access: [],
   })
-    .input(PaginationInputSchema)
-    .output(
-      z.object({
-        notifications: z.array(NotificationSchema),
-        total: z.number(),
-      })
-    ),
+    .input(ListNotificationsInputSchema)
+    .output(PaginatedResult(NotificationSchema)),
 
   // Get unread count for badge
   getUnreadCount: proc({
@@ -196,6 +197,30 @@ export const notificationContract = {
     .input(RetentionSettingsSchema)
     .output(z.void()),
 
+  /**
+   * List per-channel delivery attempts (paginated, newest first).
+   *
+   * Admin-only visibility surface for external-delivery outcomes. Each
+   * row corresponds to one `strategy.send(...)` call against an
+   * external notification channel; failures expose the silent-failure
+   * mode the dispatch loop swallowed pre-v1.
+   *
+   * When `notificationId` is supplied, results are scoped to that
+   * notification; otherwise the caller sees every recent attempt
+   * across the platform.
+   *
+   * Visibility-only — there is no retry mechanism in v1; a `failure`
+   * here is a final outcome that an admin actions manually (re-trigger
+   * the source event, fix the misconfigured channel, etc.).
+   */
+  getDeliveryAttempts: proc({
+    operationType: "query",
+    userType: "user",
+    access: [notificationAccess.admin],
+  })
+    .input(ListDeliveryAttemptsInputSchema)
+    .output(PaginatedResult(DeliveryAttemptSchema)),
+
   // ==========================================================================
   // BACKEND-TO-BACKEND GROUP MANAGEMENT (userType: "service")
   // ==========================================================================

package/src/schemas.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { PaginationInput as CanonicalPaginationInput } from "@checkstack/common";
 
 // Notification importance levels
 export const ImportanceSchema = z.enum(["info", "warning", "critical"]);
@@ -145,13 +146,14 @@ 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),
+// Notification list input — extends the canonical `PaginationInput` from
+// `@checkstack/common` with the notification-specific `unreadOnly` filter.
+// Compose with `.extend({...})` to add further domain filters; do NOT
+// redefine the base `limit` / `offset` fields.
+export const ListNotificationsInputSchema = CanonicalPaginationInput.extend({
   unreadOnly: z.boolean().default(false),
 });
-export type PaginationInput = z.infer<typeof PaginationInputSchema>;
+export type ListNotificationsInput = z.infer<typeof ListNotificationsInputSchema>;
 
 // --- Notification Strategy Schemas ---
 
@@ -241,3 +243,45 @@ export const TransactionalResultSchema = z.object({
   error: z.string().optional(),
 });
 export type TransactionalResult = z.infer<typeof TransactionalResultSchema>;
+
+// --- Delivery attempt schemas ---
+
+/**
+ * Outcome of one external `strategy.send(...)` call. Visibility-only —
+ * `failure` here is a final, surfaced outcome (no retries in v1).
+ */
+export const DeliveryAttemptStatusSchema = z.enum(["success", "failure"]);
+export type DeliveryAttemptStatus = z.infer<typeof DeliveryAttemptStatusSchema>;
+
+/**
+ * One row from `notification_delivery_attempts`. Mirrors the Drizzle
+ * table 1:1 — keep these in sync; the schema-drift CI check (Phase 10)
+ * will catch column-name skew once it lands.
+ */
+export const DeliveryAttemptSchema = z.object({
+  id: z.string().uuid(),
+  notificationId: z.string().uuid(),
+  /** Qualified strategy id, e.g. `notification-discord.send`. */
+  strategyQualifiedId: z.string(),
+  attemptedAt: z.coerce.date(),
+  status: DeliveryAttemptStatusSchema,
+  /** Sanitised via `extractErrorMessage` on the backend before persistence. */
+  errorMessage: z.string().nullable(),
+  /** Wall-clock duration of the `send()` call in milliseconds. */
+  durationMs: z.number().int().min(0),
+});
+export type DeliveryAttempt = z.infer<typeof DeliveryAttemptSchema>;
+
+/**
+ * Input shape for `getDeliveryAttempts`. Extends the canonical
+ * `PaginationInput` with an optional `notificationId` filter — when
+ * supplied, results are scoped to that notification; otherwise the
+ * caller gets every attempt across the system (newest first), useful
+ * for admin "recent failures" dashboards.
+ */
+export const ListDeliveryAttemptsInputSchema = CanonicalPaginationInput.extend({
+  notificationId: z.string().uuid().optional(),
+});
+export type ListDeliveryAttemptsInput = z.infer<
+  typeof ListDeliveryAttemptsInputSchema
+>;