התראות

NotificationService הוא ההפשטה מהשורה הראשונה של Triggerfish למסירת התראות לבעלים של הסוכן בכל הערוצים המחוברים.

למה שירות התראות?

ללא שירות ייעודי, לוגיקת התראות נוטה להתפזר ברחבי קוד המקור -- כל תכונה מיישמת דפוס "הודע לבעלים" משלה. זה מוביל להתנהגות לא עקבית, התראות שהוחמצו וכפילויות.

Triggerfish מרכז את כל מסירת ההתראות דרך שירות יחיד שמטפל בעדיפות, תורים וסינון כפילויות.

כיצד זה עובד

כאשר כל רכיב צריך להודיע לבעלים -- משימת cron שהושלמה, טריגר שזיהה משהו חשוב, webhook שהופעל -- הוא קורא ל-NotificationService. השירות קובע כיצד ולאן למסור את ההתראה.

ממשק

interface NotificationService {
  /** מסירה או שמירה בתור של התראה למשתמש. */
  deliver(options: DeliverOptions): Promise<void>;

  /** קבלת התראות ממתינות (שלא נמסרו) למשתמש. */
  getPending(userId: UserId): Promise<Notification[]>;

  /** אישור שהתראה נמסרה. */
  acknowledge(notificationId: string): Promise<void>;
}

רמות עדיפות

כל התראה נושאת עדיפות שמשפיעה על התנהגות המסירה:

עדיפות	התנהגות
critical	נמסרת מיידית לכל הערוצים המחוברים. עוקפת שעות שקט.
normal	נמסרת לערוץ המועדף. נשמרת בתור אם המשתמש לא מקוון.
low	נשמרת בתור ונמסרת בקבוצות. עשויה להיות מסוכמת.

אפשרויות מסירה

interface DeliverOptions {
  readonly userId: UserId;
  readonly message: string;
  readonly priority: NotificationPriority; // "critical" | "normal" | "low"
}

תורים ומסירה לא-מקוונת

כאשר משתמש היעד אינו מקוון או שאין ערוצים מחוברים, התראות נשמרות בתור. הן נמסרות כאשר:

• המשתמש מתחיל סשן חדש.
• ערוץ מתחבר מחדש.
• המשתמש מבקש במפורש התראות ממתינות.

ניתן לאחזר התראות ממתינות עם getPending() ולאשר עם acknowledge().

סינון כפילויות

NotificationService מונע מהתראות כפולות להגיע למשתמש. אם אותו תוכן התראה נמסר מספר פעמים בתוך חלון זמן, רק המסירה הראשונה עוברת.

תצורה

הגדירו התנהגות התראות ב-triggerfish.yaml:

notifications:
  preferred_channel: telegram # ערוץ מסירה ברירת מחדל
  quiet_hours: "22:00-07:00" # דיכוי normal/low בשעות אלו
  batch_interval: 15m # קיבוץ התראות בעדיפות נמוכה

דוגמאות שימוש

התראות משמשות ברחבי המערכת:

• משימות cron מודיעות לבעלים כאשר משימה מתוזמנת הושלמה או נכשלה.
• טריגרים מודיעים לבעלים כאשר ניטור מזהה משהו שדורש תשומת לב.
• Webhooks מודיעים לבעלים כאשר אירוע חיצוני מופעל (PR ב-GitHub, התראת Sentry).
• הפרות מדיניות מודיעות לבעלים כאשר ניסיון פעולה חסומה.
• סטטוס ערוץ מודיע לבעלים כאשר ערוץ מתנתק או מתחבר מחדש.

תור ההתראות נשמר דרך StorageProvider (מרחב שמות:

notifications:) עם שמירה ברירת מחדל של 7 ימים לאחר מסירה. התראות שלא נמסרו נשמרות עד שמאושרות. :::