From 6edc9f7a1c84c6d79297443dae5f793122319d11 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 02:06:35 +0700 Subject: [PATCH 01/12] docs: update the send notification flow --- docs/single-flow.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/single-flow.md diff --git a/docs/single-flow.md b/docs/single-flow.md new file mode 100644 index 0000000..e0e2eb6 --- /dev/null +++ b/docs/single-flow.md @@ -0,0 +1,45 @@ +# The Telegram Git Notifier flow + +This document describes the flow of the telegram git notifier. + +## Handle the webhook and send a notification + +### The user adds this bot URL to the git repository webhook + +The user adds the bot URL to the git repository webhook. The bot URL is the URL of the bot server. + +### The git repository sends a webhook to the bot + +The git repository sends a webhook to the bot if any event occurs. The webhook contains the event details. + +### The bot processes the webhook message + +The bot will receive the webhook message and process it. The bot will check the validity of the webhook message. + +### The bot gets the message details if the event is valid + +If the event is valid, the bot will get the message details of this event and set the message details to the message object. + +### The bot sends a notification + +The bot sends a notification with the message details of the event to the user, group, or channel. + +## Sending notifications to multiple users + +If the bot supports sending notifications to multiple users, groups, or channels, it will manage this process. This could involve iterating over a list of recipients, handling individual user preferences, etc. + +## Packages + +This flow is implemented in two packages: `telegram-git-notifier` and `laravel-telegram-git-notifier`. + +### telegram-git-notifier + +This package handles the core functionality of receiving and processing webhooks from GitHub and GitLab, and sending notifications to Telegram. + +### laravel-telegram-git-notifier + +This package is a Laravel wrapper for the `telegram-git-notifier` package. It provides a Laravel-friendly way to use the `telegram-git-notifier` functionality, including configuration and views for customizing the notifications. + +## Future Work + +In the future, additional flows will be implemented to handle other aspects of the bot's functionality, such as error handling, customizing notifications, and sending notifications to multiple users. From b7cc6c08aa5d86a8b11748260b8af181ad081228 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 02:15:55 +0700 Subject: [PATCH 02/12] docs: create erDiagram for the send notification flow --- docs/single-flow.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/single-flow.md b/docs/single-flow.md index e0e2eb6..d25f6f2 100644 --- a/docs/single-flow.md +++ b/docs/single-flow.md @@ -43,3 +43,39 @@ This package is a Laravel wrapper for the `telegram-git-notifier` package. It pr ## Future Work In the future, additional flows will be implemented to handle other aspects of the bot's functionality, such as error handling, customizing notifications, and sending notifications to multiple users. + +```mermaid +erDiagram + User ||--o{ Webhook: sets + Webhook ||--|| Event: triggers + Event ||--o{ Notification: generates + Notification ||--o{ Recipient: sends_to + + User { + int id PK + string webhook_url + } + + Webhook { + int id PK + string url + } + + Event { + int id PK + string name + string action + object payload + } + + Notification { + int id PK + string message + } + + Recipient { + int id PK + string type "user, group, channel, topic, etc." + string identifier + } +``` From c8c2c6832278a70879dea6b4eca1cd3b5de491e8 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 11:25:23 +0700 Subject: [PATCH 03/12] docs: update erDiagram for the send notification flow --- docs/single-flow.md | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/docs/single-flow.md b/docs/single-flow.md index d25f6f2..7a82aa3 100644 --- a/docs/single-flow.md +++ b/docs/single-flow.md @@ -46,36 +46,54 @@ In the future, additional flows will be implemented to handle other aspects of t ```mermaid erDiagram - User ||--o{ Webhook: sets - Webhook ||--|| Event: triggers - Event ||--o{ Notification: generates - Notification ||--o{ Recipient: sends_to + User ||--o{ Bot: owns + User ||--o{ GitRepository: owns + Bot ||--o{ Webhook: creates + GitRepository ||--o{ Webhook: has + GitRepository ||--o{ Event: triggers + Event ||--o{ Webhook: sends_through + Webhook ||--o{ Bot: received_by + Bot ||--o{ Notification: sends + Notification ||--o{ Recipient: received_by + + Bot { + int id PK + string token "The bot token" + string bot_id "The bot ID" + } User { int id PK - string webhook_url + string telegram_id "The user Telegram ID" } Webhook { int id PK - string url + string url "The URL of the webhook" } Event { int id PK - string name - string action - object payload + json payload "The webhook payload" + string event_name "The name of the event in payload" + string action "The action of the event in payload" } Notification { int id PK - string message + string message "The notification message" } Recipient { int id PK - string type "user, group, channel, topic, etc." - string identifier + string type "bot, group, channel, topic, etc." + string identifier "The recipient identifier (e.g., bot ID, group ID)" + } + + GitRepository { + int id PK + string platform "The git platform (e.g., GitHub, GitLab)" + string name "The name of the git repository" + string url "The URL of the git repository" } ``` From b07f6aadaf17696c8e20e0db79b68bbeb6e6e01b Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 11:50:57 +0700 Subject: [PATCH 04/12] docs: create flowchart for the send notification flow --- .../send-notification-flow.md} | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) rename docs/{single-flow.md => single/send-notification-flow.md} (84%) diff --git a/docs/single-flow.md b/docs/single/send-notification-flow.md similarity index 84% rename from docs/single-flow.md rename to docs/single/send-notification-flow.md index 7a82aa3..f9d1742 100644 --- a/docs/single-flow.md +++ b/docs/single/send-notification-flow.md @@ -97,3 +97,21 @@ erDiagram string url "The URL of the git repository" } ``` + +```mermaid +flowchart TD + title[The Telegram Git Notifier - send notification flow] + + application(New application created) + application-->bot[Create a new bot] + bot-->webhookCheck{Is webhook set?} + webhookCheck-->|No|setNewWebhook[Set new webhook] + webhookCheck-->|Yes|updateWebhook[Update existing webhook] + updateWebhook-->webhook[Webhook updated] + setNewWebhook-->webhook[Webhook set] + user[User] + user-->addWebhookToRepo[Add webhook to repository] + addWebhookToRepo-->repository[Repository] + user-->ownsRepo[Owns] + ownsRepo-->repository +``` From 2722a2ca01d6fca79eb960576cb232837c25119d Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 12:33:17 +0700 Subject: [PATCH 05/12] docs: update flowchart for the send notification flow --- docs/single/send-notification-flow.md | 36 +++++++++++++++++++++------ 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/docs/single/send-notification-flow.md b/docs/single/send-notification-flow.md index f9d1742..3172085 100644 --- a/docs/single/send-notification-flow.md +++ b/docs/single/send-notification-flow.md @@ -75,7 +75,7 @@ erDiagram Event { int id PK json payload "The webhook payload" - string event_name "The name of the event in payload" + string name "The name of the event in payload" string action "The action of the event in payload" } @@ -98,20 +98,42 @@ erDiagram } ``` +Here is the flowchart of the Telegram Git Notifier - send notification flow: + ```mermaid flowchart TD title[The Telegram Git Notifier - send notification flow] application(New application created) - application-->bot[Create a new bot] + application-->bot[Bot created] + bot[Bot] bot-->webhookCheck{Is webhook set?} webhookCheck-->|No|setNewWebhook[Set new webhook] webhookCheck-->|Yes|updateWebhook[Update existing webhook] updateWebhook-->webhook[Webhook updated] setNewWebhook-->webhook[Webhook set] - user[User] - user-->addWebhookToRepo[Add webhook to repository] - addWebhookToRepo-->repository[Repository] - user-->ownsRepo[Owns] - ownsRepo-->repository + + subgraph "User and Repository Interaction" + webhook-->user[User] + user-->addWebhookToRepo[Add webhook to repository] + addWebhookToRepo-->repository[Repository] + user-->ownsRepo[Owns] + ownsRepo-->repository + end + + repository-->triggerEvent{Trigger event} + triggerEvent-->sendPayload[Send event payload to bot] + sendPayload-->bot + bot-->processEvent{Process event} + processEvent-->checkAction{Is there an action?} + checkAction-->|Yes|actionMessage[Event type: Action] + checkAction-->|No|eventNameMessage[Event type: Event name] + eventNameMessage-->checkSettings{Is event allowed in settings?} + actionMessage-->checkSettings + checkSettings-->|Yes|findTemplate{Find message template} + checkSettings-->|No|endFlow[End flow] + findTemplate-->|Exists|setMessage[Set message for notification] + findTemplate-->|Not Exists|logAndEndFlow[Log and end flow] + setMessage-->continueFlow[Continue flow] + logAndEndFlow-->endFlow ``` From fb339783cea7cf93b52254f551dbe47f539e6054 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 12:45:39 +0700 Subject: [PATCH 06/12] docs: update flowchart for the send notification flow --- docs/single/send-notification-flow.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/single/send-notification-flow.md b/docs/single/send-notification-flow.md index 3172085..c08255c 100644 --- a/docs/single/send-notification-flow.md +++ b/docs/single/send-notification-flow.md @@ -134,6 +134,10 @@ flowchart TD checkSettings-->|No|endFlow[End flow] findTemplate-->|Exists|setMessage[Set message for notification] findTemplate-->|Not Exists|logAndEndFlow[Log and end flow] - setMessage-->continueFlow[Continue flow] logAndEndFlow-->endFlow + setMessage-->checkMessage{Is message empty?} + checkMessage-->|Yes|endFlow[End flow] + checkMessage-->|No|sendNotification[Send notification] + sendNotification-->|Success|endFlow[End flow] + sendNotification-->|Failure|logAndEndFlow[Log and end flow] ``` From 6dc97e2d2d2415058118a1fff998088d2c0a0dc5 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 12:51:12 +0700 Subject: [PATCH 07/12] docs: update flowchart for the send notification flow --- docs/single/send-notification-flow.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/single/send-notification-flow.md b/docs/single/send-notification-flow.md index c08255c..c2a6449 100644 --- a/docs/single/send-notification-flow.md +++ b/docs/single/send-notification-flow.md @@ -40,9 +40,7 @@ This package handles the core functionality of receiving and processing webhooks This package is a Laravel wrapper for the `telegram-git-notifier` package. It provides a Laravel-friendly way to use the `telegram-git-notifier` functionality, including configuration and views for customizing the notifications. -## Future Work - -In the future, additional flows will be implemented to handle other aspects of the bot's functionality, such as error handling, customizing notifications, and sending notifications to multiple users. +## Entity Relationship Diagram ```mermaid erDiagram @@ -98,6 +96,8 @@ erDiagram } ``` +## Send notification flowchart + Here is the flowchart of the Telegram Git Notifier - send notification flow: ```mermaid @@ -141,3 +141,7 @@ flowchart TD sendNotification-->|Success|endFlow[End flow] sendNotification-->|Failure|logAndEndFlow[Log and end flow] ``` + +## Future Work + +In the future, additional flows will be implemented to handle other aspects of the bot's functionality, such as error handling, customizing notifications, and sending notifications to multiple users. From db21cc97f55de9be167f0082c13660b6d4fb9d68 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 13:43:32 +0700 Subject: [PATCH 08/12] docs: update flowchart for the send notification flow --- docs/single/send-notification-flow.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/single/send-notification-flow.md b/docs/single/send-notification-flow.md index c2a6449..08391f1 100644 --- a/docs/single/send-notification-flow.md +++ b/docs/single/send-notification-flow.md @@ -124,12 +124,16 @@ flowchart TD repository-->triggerEvent{Trigger event} triggerEvent-->sendPayload[Send event payload to bot] sendPayload-->bot - bot-->processEvent{Process event} - processEvent-->checkAction{Is there an action?} - checkAction-->|Yes|actionMessage[Event type: Action] - checkAction-->|No|eventNameMessage[Event type: Event name] - eventNameMessage-->checkSettings{Is event allowed in settings?} - actionMessage-->checkSettings + + subgraph "Event Processing" + bot-->processEvent{Process event} + processEvent-->checkAction{Is there an action?} + checkAction-->|Yes|actionMessage[Event type: Action] + checkAction-->|No|eventNameMessage[Event type: Event name] + eventNameMessage-->checkSettings{Is event allowed in settings?} + actionMessage-->checkSettings + end + checkSettings-->|Yes|findTemplate{Find message template} checkSettings-->|No|endFlow[End flow] findTemplate-->|Exists|setMessage[Set message for notification] From 998602520237f63e897f24ea5c4a7c5be90475c3 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 13:52:30 +0700 Subject: [PATCH 09/12] docs: update flowchart for the send notification flow --- docs/single/send-notification-flow.md | 82 ++++++++++++++------------- 1 file changed, 43 insertions(+), 39 deletions(-) diff --git a/docs/single/send-notification-flow.md b/docs/single/send-notification-flow.md index 08391f1..13bf65c 100644 --- a/docs/single/send-notification-flow.md +++ b/docs/single/send-notification-flow.md @@ -18,7 +18,8 @@ The bot will receive the webhook message and process it. The bot will check the ### The bot gets the message details if the event is valid -If the event is valid, the bot will get the message details of this event and set the message details to the message object. +If the event is valid, the bot will get the message details of this event and set the message details to the message +object. ### The bot sends a notification @@ -26,7 +27,8 @@ The bot sends a notification with the message details of the event to the user, ## Sending notifications to multiple users -If the bot supports sending notifications to multiple users, groups, or channels, it will manage this process. This could involve iterating over a list of recipients, handling individual user preferences, etc. +If the bot supports sending notifications to multiple users, groups, or channels, it will manage this process. This +could involve iterating over a list of recipients, handling individual user preferences, etc. ## Packages @@ -34,11 +36,13 @@ This flow is implemented in two packages: `telegram-git-notifier` and `laravel-t ### telegram-git-notifier -This package handles the core functionality of receiving and processing webhooks from GitHub and GitLab, and sending notifications to Telegram. +This package handles the core functionality of receiving and processing webhooks from GitHub and GitLab, and sending +notifications to Telegram. ### laravel-telegram-git-notifier -This package is a Laravel wrapper for the `telegram-git-notifier` package. It provides a Laravel-friendly way to use the `telegram-git-notifier` functionality, including configuration and views for customizing the notifications. +This package is a Laravel wrapper for the `telegram-git-notifier` package. It provides a Laravel-friendly way to use +the `telegram-git-notifier` functionality, including configuration and views for customizing the notifications. ## Entity Relationship Diagram @@ -56,7 +60,7 @@ erDiagram Bot { int id PK - string token "The bot token" + string token "The bot token" string bot_id "The bot ID" } @@ -103,49 +107,49 @@ Here is the flowchart of the Telegram Git Notifier - send notification flow: ```mermaid flowchart TD title[The Telegram Git Notifier - send notification flow] - application(New application created) - application-->bot[Bot created] + application --> bot[Bot created] bot[Bot] - bot-->webhookCheck{Is webhook set?} - webhookCheck-->|No|setNewWebhook[Set new webhook] - webhookCheck-->|Yes|updateWebhook[Update existing webhook] - updateWebhook-->webhook[Webhook updated] - setNewWebhook-->webhook[Webhook set] + bot --> webhookCheck{Is webhook set?} + webhookCheck -->|No| setNewWebhook[Set new webhook] + webhookCheck -->|Yes| updateWebhook[Update existing webhook] + updateWebhook --> webhook[Webhook updated] + setNewWebhook --> webhook[Webhook set] subgraph "User and Repository Interaction" - webhook-->user[User] - user-->addWebhookToRepo[Add webhook to repository] - addWebhookToRepo-->repository[Repository] - user-->ownsRepo[Owns] - ownsRepo-->repository + webhook --> user[User] + user --> addWebhookToRepo[Add webhook to repository] + addWebhookToRepo --> repository[Repository] + user --> ownsRepo[Owns] + ownsRepo --> repository end - repository-->triggerEvent{Trigger event} - triggerEvent-->sendPayload[Send event payload to bot] - sendPayload-->bot - + repository --> triggerEvent{Trigger event} + triggerEvent --> sendPayload[Send event payload to bot] + sendPayload --> bot + subgraph "Event Processing" - bot-->processEvent{Process event} - processEvent-->checkAction{Is there an action?} - checkAction-->|Yes|actionMessage[Event type: Action] - checkAction-->|No|eventNameMessage[Event type: Event name] - eventNameMessage-->checkSettings{Is event allowed in settings?} - actionMessage-->checkSettings + bot --> processEvent{Process event} + processEvent --> checkAction{Is there an action?} + checkAction -->|Yes| actionMessage[Event type: Action] + checkAction -->|No| eventNameMessage[Event type: Event name] + eventNameMessage --> checkSettings{Is event allowed in settings?} + actionMessage --> checkSettings end - - checkSettings-->|Yes|findTemplate{Find message template} - checkSettings-->|No|endFlow[End flow] - findTemplate-->|Exists|setMessage[Set message for notification] - findTemplate-->|Not Exists|logAndEndFlow[Log and end flow] - logAndEndFlow-->endFlow - setMessage-->checkMessage{Is message empty?} - checkMessage-->|Yes|endFlow[End flow] - checkMessage-->|No|sendNotification[Send notification] - sendNotification-->|Success|endFlow[End flow] - sendNotification-->|Failure|logAndEndFlow[Log and end flow] + + checkSettings -->|Yes| findTemplate{Find message template} + checkSettings -->|No| endFlow[End flow] + findTemplate -->|Exists| setMessage[Set message for notification] + findTemplate -->|Not Exists| log[Log error] + setMessage --> checkMessage{Is message empty?} + checkMessage -->|Yes| endFlow[End flow] + checkMessage -->|No| sendNotification[Send notification] + sendNotification -->|Success| endFlow[End flow] + sendNotification -->|Failure| log[Log error] + log --> endFlow ``` ## Future Work -In the future, additional flows will be implemented to handle other aspects of the bot's functionality, such as error handling, customizing notifications, and sending notifications to multiple users. +In the future, additional flows will be implemented to handle other aspects of the bot's functionality, such as error +handling, customizing notifications, and sending notifications to multiple users. From ea779bf1009bc467047c6c82a8536d961e9f4aad Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 14:53:30 +0700 Subject: [PATCH 10/12] docs: update some info for send notification flow --- docs/single/send-notification-flow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/single/send-notification-flow.md b/docs/single/send-notification-flow.md index 13bf65c..e046a60 100644 --- a/docs/single/send-notification-flow.md +++ b/docs/single/send-notification-flow.md @@ -1,6 +1,6 @@ -# The Telegram Git Notifier flow +# Send Notification Flow - The Telegram Git Notifier Package -This document describes the flow of the telegram git notifier. +This document describes the flow of sending notifications in the Telegram Git Notifier package. ## Handle the webhook and send a notification @@ -25,7 +25,7 @@ object. The bot sends a notification with the message details of the event to the user, group, or channel. -## Sending notifications to multiple users +## Sending notifications to multiple recipients If the bot supports sending notifications to multiple users, groups, or channels, it will manage this process. This could involve iterating over a list of recipients, handling individual user preferences, etc. From a8ea74c6190e13fa633447af0e0528f7fbf16586 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 19:06:49 +0700 Subject: [PATCH 11/12] docs: update infos for send notification flow --- docs/single/send-notification-flow.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/single/send-notification-flow.md b/docs/single/send-notification-flow.md index e046a60..986c997 100644 --- a/docs/single/send-notification-flow.md +++ b/docs/single/send-notification-flow.md @@ -8,17 +8,20 @@ This document describes the flow of sending notifications in the Telegram Git No The user adds the bot URL to the git repository webhook. The bot URL is the URL of the bot server. +Example: `https://localhost:8000/telegram-git-notifier/` + ### The git repository sends a webhook to the bot The git repository sends a webhook to the bot if any event occurs. The webhook contains the event details. ### The bot processes the webhook message -The bot will receive the webhook message and process it. The bot will check the validity of the webhook message. +When an application receives a webhook message from the git repository, the bot processes the webhook message. +It checks if the webhook is set or not. If the event has any actions and the event is allowed notify in the settings, etc. ### The bot gets the message details if the event is valid -If the event is valid, the bot will get the message details of this event and set the message details to the message +If the event/action is valid, the bot will get the message details of this event/action and set the message details to the message object. ### The bot sends a notification From 48a784ad14509a3e2535ded4ca052c33383d7880 Mon Sep 17 00:00:00 2001 From: Tan Nguyen Date: Tue, 4 Jun 2024 19:07:48 +0700 Subject: [PATCH 12/12] chore: update the path for sending notification flow docs --- docs/{single => }/send-notification-flow.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{single => }/send-notification-flow.md (100%) diff --git a/docs/single/send-notification-flow.md b/docs/send-notification-flow.md similarity index 100% rename from docs/single/send-notification-flow.md rename to docs/send-notification-flow.md