@pixelbyte-software/pixcode 1.40.9 → 1.41.0

package/server/services/notification-orchestrator.js

@@ -3,13 +3,12 @@ import webPush from 'web-push';
 import { notificationPreferencesDb, pushSubscriptionsDb, sessionNamesDb } from '../database/db.js';
 
 import { notifyUser as notifyTelegramUser } from './telegram/bot.js';
-
-const KIND_TO_PREF_KEY = {
-  action_required: 'actionRequired',
-  stop: 'stop',
-  error: 'error',
-  update: 'updates'
-};
+import {
+  NOTIFICATION_EVENT_TYPES,
+  createNotificationEventContract,
+  getNotificationPreferenceKey,
+  normalizeNotificationEvent
+} from './notification-taxonomy.js';
 
 const PROVIDER_LABELS = {
   claude: 'Claude',
@@ -40,7 +39,7 @@ const cleanupOldEventKeys = () => {
 
 function shouldSendPush(preferences, event) {
   const webPushEnabled = Boolean(preferences?.channels?.webPush);
-  const prefEventKey = KIND_TO_PREF_KEY[event.kind];
+  const prefEventKey = getNotificationPreferenceKey(event);
   const eventEnabled = prefEventKey ? Boolean(preferences?.events?.[prefEventKey]) : true;
 
   return webPushEnabled && eventEnabled;
@@ -48,7 +47,7 @@ function shouldSendPush(preferences, event) {
 
 function shouldSendInApp(preferences, event) {
   const inAppEnabled = preferences?.channels?.inApp !== false;
-  const prefEventKey = KIND_TO_PREF_KEY[event.kind];
+  const prefEventKey = getNotificationPreferenceKey(event);
   const eventEnabled = prefEventKey ? preferences?.events?.[prefEventKey] !== false : true;
 
   return inAppEnabled && eventEnabled;
@@ -56,7 +55,7 @@ function shouldSendInApp(preferences, event) {
 
 function shouldSendTelegram(preferences, event) {
   const telegramEnabled = preferences?.channels?.telegram !== false;
-  const prefEventKey = KIND_TO_PREF_KEY[event.kind];
+  const prefEventKey = getNotificationPreferenceKey(event);
   const eventEnabled = prefEventKey ? preferences?.events?.[prefEventKey] !== false : true;
 
   return telegramEnabled && eventEnabled;
@@ -75,6 +74,7 @@ function isDuplicate(event) {
 function createNotificationEvent({
   provider,
   sessionId = null,
+  eventType = null,
   kind = 'info',
   code = 'generic.info',
   meta = {},
@@ -82,9 +82,10 @@ function createNotificationEvent({
   dedupeKey = null,
   requiresUserAction = false
 }) {
-  return {
+  return normalizeNotificationEvent({
     provider,
     sessionId,
+    eventType,
     kind,
     code,
     meta,
@@ -92,7 +93,7 @@ function createNotificationEvent({
     requiresUserAction,
     dedupeKey,
     createdAt: new Date().toISOString()
-  };
+  });
 }
 
 function normalizeErrorMessage(error) {
@@ -138,6 +139,16 @@ function resolveSessionName(event) {
 }
 
 function buildPushBody(event) {
+  const EVENT_TYPE_MAP = {
+    [NOTIFICATION_EVENT_TYPES.CHAT_DONE]: event.meta?.stopReason || 'Chat run completed',
+    [NOTIFICATION_EVENT_TYPES.ORCHESTRATION_DONE]: event.meta?.stopReason || 'Orchestration completed',
+    [NOTIFICATION_EVENT_TYPES.APPROVAL_NEEDED]: event.meta?.toolName
+      ? `Action Required: Tool "${event.meta.toolName}" needs approval`
+      : 'Action Required: A run needs your approval',
+    [NOTIFICATION_EVENT_TYPES.ERROR]: event.meta?.error ? `Error: ${event.meta.error}` : 'Pixcode encountered an error',
+    [NOTIFICATION_EVENT_TYPES.TEST_FAILED]: event.meta?.error ? `Test Failed: ${event.meta.error}` : 'A verification command failed',
+    [NOTIFICATION_EVENT_TYPES.LIVE_VIEW_FAILED]: event.meta?.error ? `Live View Failed: ${event.meta.error}` : 'Live View failed'
+  };
   const CODE_MAP = {
     'permission.required': event.meta?.toolName
       ? `Action Required: Tool "${event.meta.toolName}" needs approval`
@@ -155,16 +166,19 @@ function buildPushBody(event) {
   };
   const providerLabel = PROVIDER_LABELS[event.provider] || 'Assistant';
   const sessionName = resolveSessionName(event);
-  const message = CODE_MAP[event.code] || 'You have a new notification';
+  const message = EVENT_TYPE_MAP[event.eventType] || CODE_MAP[event.code] || 'You have a new notification';
 
   return {
     title: sessionName || 'Pixcode',
     body: `${providerLabel}: ${message}`,
     data: {
       sessionId: event.sessionId || null,
+      eventType: event.eventType || null,
       code: event.code,
       provider: event.provider || null,
       sessionName,
+      category: event.category || null,
+      preferenceKey: event.preferenceKey || getNotificationPreferenceKey(event),
       tag: `${event.provider || 'assistant'}:${event.sessionId || 'none'}:${event.code}`
     }
   };
@@ -172,11 +186,15 @@ function buildPushBody(event) {
 
 function buildNotificationPayload(event) {
   const pushBody = buildPushBody(event);
+  const contract = createNotificationEventContract(event);
   const baseId = event.dedupeKey || `${event.provider || 'system'}:${event.kind || 'info'}:${event.code || 'generic'}:${event.sessionId || 'none'}`;
   return {
     id: `${baseId}:${event.createdAt}`,
     title: pushBody.title,
     body: pushBody.body,
+    eventType: contract.eventType,
+    category: contract.category,
+    preferenceKey: contract.preferenceKey,
     kind: event.kind || 'info',
     code: event.code || 'generic.info',
     severity: event.severity || 'info',
@@ -188,6 +206,28 @@ function buildNotificationPayload(event) {
   };
 }
 
+function inferRunStoppedEventType({ provider, stopReason }) {
+  const reason = typeof stopReason === 'string' ? stopReason.toLowerCase() : '';
+  if (provider === 'system' && reason.includes('orchestration')) {
+    return NOTIFICATION_EVENT_TYPES.ORCHESTRATION_DONE;
+  }
+
+  return NOTIFICATION_EVENT_TYPES.CHAT_DONE;
+}
+
+function inferRunFailedEventType({ provider, error }) {
+  const message = normalizeErrorMessage(error).toLowerCase();
+  if (message.includes('live view')) {
+    return NOTIFICATION_EVENT_TYPES.LIVE_VIEW_FAILED;
+  }
+
+  if (message.includes('test') || message.includes('typecheck') || message.includes('lint') || message.includes('build')) {
+    return NOTIFICATION_EVENT_TYPES.TEST_FAILED;
+  }
+
+  return provider === 'system' ? NOTIFICATION_EVENT_TYPES.ERROR : NOTIFICATION_EVENT_TYPES.RUN_FAILED;
+}
+
 function broadcastInAppNotification(userId, event) {
   if (!notificationWebSocketServer || !userId || !event) {
     return;
@@ -280,12 +320,13 @@ function notifyUserIfEnabled({ userId, event }) {
   }
 }
 
-function notifyRunStopped({ userId, provider, sessionId = null, stopReason = 'completed', sessionName = null }) {
+function notifyRunStopped({ userId, provider, sessionId = null, stopReason = 'completed', sessionName = null, eventType = null }) {
   notifyUserIfEnabled({
     userId,
     event: createNotificationEvent({
       provider,
       sessionId,
+      eventType: eventType || inferRunStoppedEventType({ provider, stopReason }),
       kind: 'stop',
       code: 'run.stopped',
       meta: { stopReason, sessionName },
@@ -295,7 +336,7 @@ function notifyRunStopped({ userId, provider, sessionId = null, stopReason = 'co
   });
 }
 
-function notifyRunFailed({ userId, provider, sessionId = null, error, sessionName = null }) {
+function notifyRunFailed({ userId, provider, sessionId = null, error, sessionName = null, eventType = null }) {
   const errorMessage = normalizeErrorMessage(error);
 
   notifyUserIfEnabled({
@@ -303,6 +344,7 @@ function notifyRunFailed({ userId, provider, sessionId = null, error, sessionNam
     event: createNotificationEvent({
       provider,
       sessionId,
+      eventType: eventType || inferRunFailedEventType({ provider, error }),
       kind: 'error',
       code: 'run.failed',
       meta: { error: errorMessage, sessionName },
@@ -314,6 +356,7 @@ function notifyRunFailed({ userId, provider, sessionId = null, error, sessionNam
 
 export {
   createNotificationEvent,
+  createNotificationEventContract,
   setNotificationWebSocketServer,
   broadcastInAppNotification,
   notifyUserIfEnabled,

package/server/services/notification-taxonomy.js

@@ -0,0 +1,204 @@
+const NOTIFICATION_PREFERENCE_KEYS = Object.freeze({
+  ACTION_REQUIRED: 'actionRequired',
+  STOP: 'stop',
+  ERROR: 'error',
+  UPDATES: 'updates',
+});
+
+const NOTIFICATION_EVENT_TYPES = Object.freeze({
+  CHAT_DONE: 'chat.done',
+  ORCHESTRATION_DONE: 'orchestration.done',
+  APPROVAL_NEEDED: 'approval.needed',
+  ERROR: 'error',
+  TEST_FAILED: 'test.failed',
+  LIVE_VIEW_FAILED: 'live_view.failed',
+  RUN_STOPPED: 'run.stopped',
+  RUN_FAILED: 'run.failed',
+  AGENT_NOTIFICATION: 'agent.notification',
+  PUSH_ENABLED: 'push.enabled',
+  APP_UPDATE_AVAILABLE: 'app.update.available',
+  CLI_UPDATE_AVAILABLE: 'cli.update.available',
+});
+
+const NOTIFICATION_TAXONOMY = Object.freeze({
+  [NOTIFICATION_EVENT_TYPES.CHAT_DONE]: {
+    category: 'chat',
+    kind: 'stop',
+    severity: 'info',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.STOP,
+    description: 'A chat/provider run completed.',
+  },
+  [NOTIFICATION_EVENT_TYPES.ORCHESTRATION_DONE]: {
+    category: 'orchestration',
+    kind: 'stop',
+    severity: 'info',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.STOP,
+    description: 'An orchestration workflow completed.',
+  },
+  [NOTIFICATION_EVENT_TYPES.APPROVAL_NEEDED]: {
+    category: 'approval',
+    kind: 'action_required',
+    severity: 'warning',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.ACTION_REQUIRED,
+    requiresUserAction: true,
+    description: 'A run is waiting for human approval.',
+  },
+  [NOTIFICATION_EVENT_TYPES.ERROR]: {
+    category: 'system',
+    kind: 'error',
+    severity: 'error',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.ERROR,
+    description: 'A generic Pixcode error occurred.',
+  },
+  [NOTIFICATION_EVENT_TYPES.TEST_FAILED]: {
+    category: 'verification',
+    kind: 'error',
+    severity: 'error',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.ERROR,
+    description: 'A build, lint, typecheck, or test command failed.',
+  },
+  [NOTIFICATION_EVENT_TYPES.LIVE_VIEW_FAILED]: {
+    category: 'live_view',
+    kind: 'error',
+    severity: 'error',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.ERROR,
+    description: 'A Live View preview failed to start or stay healthy.',
+  },
+  [NOTIFICATION_EVENT_TYPES.RUN_STOPPED]: {
+    category: 'run',
+    kind: 'stop',
+    severity: 'info',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.STOP,
+    description: 'A run stopped without reporting a failure.',
+  },
+  [NOTIFICATION_EVENT_TYPES.RUN_FAILED]: {
+    category: 'run',
+    kind: 'error',
+    severity: 'error',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.ERROR,
+    description: 'A run failed.',
+  },
+  [NOTIFICATION_EVENT_TYPES.AGENT_NOTIFICATION]: {
+    category: 'agent',
+    kind: 'action_required',
+    severity: 'warning',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.ACTION_REQUIRED,
+    requiresUserAction: true,
+    description: 'An agent emitted a notification for the user.',
+  },
+  [NOTIFICATION_EVENT_TYPES.PUSH_ENABLED]: {
+    category: 'settings',
+    kind: 'info',
+    severity: 'info',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.UPDATES,
+    description: 'Push notifications were enabled.',
+  },
+  [NOTIFICATION_EVENT_TYPES.APP_UPDATE_AVAILABLE]: {
+    category: 'update',
+    kind: 'update',
+    severity: 'info',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.UPDATES,
+    description: 'A Pixcode app update is available.',
+  },
+  [NOTIFICATION_EVENT_TYPES.CLI_UPDATE_AVAILABLE]: {
+    category: 'update',
+    kind: 'update',
+    severity: 'info',
+    preferenceKey: NOTIFICATION_PREFERENCE_KEYS.UPDATES,
+    description: 'A CLI update is available.',
+  },
+});
+
+const LEGACY_CODE_TO_EVENT_TYPE = Object.freeze({
+  'permission.required': NOTIFICATION_EVENT_TYPES.APPROVAL_NEEDED,
+  'run.stopped': NOTIFICATION_EVENT_TYPES.RUN_STOPPED,
+  'run.failed': NOTIFICATION_EVENT_TYPES.RUN_FAILED,
+  'agent.notification': NOTIFICATION_EVENT_TYPES.AGENT_NOTIFICATION,
+  'push.enabled': NOTIFICATION_EVENT_TYPES.PUSH_ENABLED,
+  'app.update.available': NOTIFICATION_EVENT_TYPES.APP_UPDATE_AVAILABLE,
+  'cli.update.available': NOTIFICATION_EVENT_TYPES.CLI_UPDATE_AVAILABLE,
+  'chat.done': NOTIFICATION_EVENT_TYPES.CHAT_DONE,
+  'orchestration.done': NOTIFICATION_EVENT_TYPES.ORCHESTRATION_DONE,
+  'test.failed': NOTIFICATION_EVENT_TYPES.TEST_FAILED,
+  'live_view.failed': NOTIFICATION_EVENT_TYPES.LIVE_VIEW_FAILED,
+});
+
+const KIND_TO_EVENT_TYPE = Object.freeze({
+  action_required: NOTIFICATION_EVENT_TYPES.APPROVAL_NEEDED,
+  stop: NOTIFICATION_EVENT_TYPES.RUN_STOPPED,
+  error: NOTIFICATION_EVENT_TYPES.ERROR,
+  update: NOTIFICATION_EVENT_TYPES.APP_UPDATE_AVAILABLE,
+  info: NOTIFICATION_EVENT_TYPES.AGENT_NOTIFICATION,
+});
+
+function resolveNotificationEventType(event = {}) {
+  if (typeof event.eventType === 'string' && NOTIFICATION_TAXONOMY[event.eventType]) {
+    return event.eventType;
+  }
+
+  if (typeof event.code === 'string' && LEGACY_CODE_TO_EVENT_TYPE[event.code]) {
+    return LEGACY_CODE_TO_EVENT_TYPE[event.code];
+  }
+
+  if (typeof event.kind === 'string' && KIND_TO_EVENT_TYPE[event.kind]) {
+    return KIND_TO_EVENT_TYPE[event.kind];
+  }
+
+  return NOTIFICATION_EVENT_TYPES.AGENT_NOTIFICATION;
+}
+
+function getNotificationTaxonomy(event = {}) {
+  return NOTIFICATION_TAXONOMY[resolveNotificationEventType(event)];
+}
+
+function getNotificationPreferenceKey(event = {}) {
+  return getNotificationTaxonomy(event)?.preferenceKey || NOTIFICATION_PREFERENCE_KEYS.UPDATES;
+}
+
+function normalizeNotificationEvent(event = {}) {
+  const eventType = resolveNotificationEventType(event);
+  const taxonomy = NOTIFICATION_TAXONOMY[eventType];
+
+  return {
+    ...event,
+    eventType,
+    category: taxonomy.category,
+    kind: event.kind || taxonomy.kind,
+    severity: event.severity || taxonomy.severity,
+    preferenceKey: taxonomy.preferenceKey,
+    requiresUserAction: Boolean(event.requiresUserAction ?? taxonomy.requiresUserAction),
+  };
+}
+
+function createNotificationEventContract(event = {}) {
+  const normalized = normalizeNotificationEvent(event);
+  const taxonomy = NOTIFICATION_TAXONOMY[normalized.eventType];
+
+  return {
+    eventType: normalized.eventType,
+    category: normalized.category,
+    kind: normalized.kind,
+    severity: normalized.severity,
+    preferenceKey: normalized.preferenceKey,
+    requiresUserAction: normalized.requiresUserAction,
+    description: taxonomy.description,
+  };
+}
+
+function listNotificationTaxonomy() {
+  return Object.keys(NOTIFICATION_TAXONOMY).map((eventType) =>
+    createNotificationEventContract({ eventType })
+  );
+}
+
+export {
+  NOTIFICATION_EVENT_TYPES,
+  NOTIFICATION_PREFERENCE_KEYS,
+  NOTIFICATION_TAXONOMY,
+  createNotificationEventContract,
+  getNotificationPreferenceKey,
+  getNotificationTaxonomy,
+  listNotificationTaxonomy,
+  normalizeNotificationEvent,
+  resolveNotificationEventType,
+};