Merge pull request #53 from CodeShellDev/feat/message-templates

feat: Message Templates

Author: CodeShellDev

.github/templates/README.template.md

@@ -31,10 +31,12 @@ endpoint restrictions, placeholders, flexible configuration
 - [Getting Started](#getting-started)
 - [Setup](#setup)
 - [Usage](#usage)
-- [Best Practices](#security-best-practices)
+- [Best Practices](#best-practices)
 - [Configuration](#configuration)
   - [Endpoints](#endpoints)
   - [Variables](#variables)
+  - [Data Aliases](#data-aliases)
+  - [Message Templates](#message-templates)
 - [Contributing](#contributing)
 - [Support](#support)
 - [License](#license)
@@ -119,31 +121,24 @@ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer API_T
 
 #### Placeholders
 
-If you are not comfortable / don't want to hardcode your Number for example and/or Recipients in you, may use **Placeholders** in your Request. See [Custom Variables](#variables).
+If you are not comfortable / don't want to hardcode your Number for example and/or Recipients in you, may use **Placeholders** in your Request.
 
-These Placeholders can be used in the Request Query or the Body of a Request like so:
+You can use [**Variable**](#variables) `{{.NUMBER}}` Placeholders and **Body** Placeholders `{{@data.key}}`.
 
-**Body**
+| Type  | Example                                                          |
+| :---- | :--------------------------------------------------------------- |
+| Body  | `{"number": "{{ .NUMBER }}", "recipients": "{{ .RECIPIENTS }}"}` |
+| Query | `http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}}`     |
+| Path  | `http://sec-signal-api:8880/v1/receive/{{.NUMBER}}`              |
+
+You can also combine them:
 
 ```json
 {
-	"number": "{{ .NUMBER }}",
-	"recipients": "{{ .RECIPIENTS }}"
+	"content": "{{.NUMBER}} -> {{.RECIPIENTS}}"
 }
 ```
 
-**Query**
-
-```
-http://sec-signal-api:8880/v1/receive/?@number={{.NUMBER}}
-```
-
-**Path**
-
-```
-http://sec-signal-api:8880/v1/receive/{{.NUMBER}}
-```
-
 #### KeyValue Pair Injection
 
 In some cases you may not be able to access / modify the Request Body, in that case specify needed values in the Request Query:
@@ -153,7 +148,7 @@ In some cases you may not be able to access / modify the Request Body, in that c
 In order to differentiate Injection Queries and _regular_ Queries
 you have to add `@` in front of any KeyValue Pair assignment.
 
-Supported types include **strings**, **ints** and **arrays**. See [Formatting](#string-to-type).
+Supported types include **strings**, **ints**, **arrays** and **json dictionaries**. See [Formatting](#string-to-type).
 
 ## Best Practices
 
@@ -293,12 +288,27 @@ settings:
     recipients: ["+123400002", "group.id", "user.id"]
 ```
 
-### Message Aliases
+### Message Templates
 
-To improve compatibility with other services Secured Signal API provides **Message Aliases** for the `message` attribute.
+To customize the `message` attribute you can use **Message Templates** to build your message by using other Body Keys and Variables.
+Use `messageTemplate` to configure:
+
+```yaml
+settings:
+  messageTemplate: |
+    Your Message:
+    {{@message}}.
+    Sent with Secured Signal API.
+```
+
+Use `{{@data.key}}` to reference Body Keys and `{{.KEY}}` for Variables.
+
+### Data Aliases
+
+To improve compatibility with other services Secured Signal API provides **Data Aliases** and a built-in `message` Alias.
 
 <details>
-<summary><strong>Default Message Aliases</strong></summary>
+<summary><strong>Default `message` Aliases</strong></summary>
 
 | Alias        | Score | Alias            | Score |
 | ------------ | ----- | ---------------- | ----- |
@@ -312,23 +322,27 @@ To improve compatibility with other services Secured Signal API provides **Messa
 
 </details>
 
-Secured Signal API will pick the best scoring Message Alias (if available) to extract the correct message from the Request Body.
+Secured Signal API will pick the best scoring Data Alias (if available) to extract set the Key to the correct Value from the Request Body.
 
-Message Aliases can be added by setting `messageAliases` in your config:
+Data Aliases can be added by setting `dataAliases` in your config:
 
 ```yaml
 settings:
-  messageAliases:
-    [
-      { alias: "msg", score: 80 },
-      { alias: "data.message", score: 79 },
-      { alias: "array[0].message", score: 78 },
-    ]
+  dataAliases:
+    "@message":
+      [
+        { alias: "msg", score: 80 },
+        { alias: "data.message", score: 79 },
+        { alias: "array[0].message", score: 78 },
+      ]
+    ".NUMBER": [{ alias: "phone_number", score: 100 }]
 ```
 
+Use `@` for aliasing Body Keys and `.` for aliasing Variables.
+
 ### Port
 
-To change the Port which Secured Signal API uses, you need to set `server.port` in your config. (default: `8880`)
+To change the Port which Secured Signal API uses, you need to set `service.port` in your config. (default: `8880`)
 
 ### Log Level
 

README.md

@@ -35,6 +35,7 @@ endpoint restrictions, placeholders, flexible configuration
 - [Configuration](#configuration)
   - [Endpoints](#endpoints)
   - [Variables](#variables)
+  - [Message Templates](#message-templates)
 - [Contributing](#contributing)
 - [Support](#support)
 - [License](#license)
@@ -65,10 +66,9 @@ services:
     container_name: secured-signal
     environment:
       API__URL: http://signal-api:8080
-      SETTINGS__VARIABLES__RECIPIENTS:
-        '[+123400002, +123400003, +123400004]'
+      SETTINGS__VARIABLES__RECIPIENTS: "[+123400002, +123400003, +123400004]"
       SETTINGS__VARIABLES__NUMBER: "+123400001"
-      API__TOKENS: '[LOOOOOONG_STRING]'
+      API__TOKENS: "[LOOOOOONG_STRING]"
     ports:
       - "8880:8880"
     restart: unless-stopped
@@ -100,10 +100,9 @@ services:
     container_name: secured-signal
     environment:
       API__URL: http://signal-api:8080
-      SETTINGS__VARIABLES__RECIPIENTS:
-        '[+123400002,+123400003,+123400004]'
+      SETTINGS__VARIABLES__RECIPIENTS: "[+123400002,+123400003,+123400004]"
       SETTINGS__VARIABLES__NUMBER: "+123400001"
-      API__TOKENS: '[LOOOOOONG_STRING]'
+      API__TOKENS: "[LOOOOOONG_STRING]"
     labels:
       - traefik.enable=true
       - traefik.http.routers.signal-api.rule=Host(`signal-api.mydomain.com`)
@@ -438,39 +437,6 @@ settings:
     recipients: ["+123400002", "group.id", "user.id"]
 ```
 
-### Message Aliases
-
-To improve compatibility with other services Secured Signal API provides **Message Aliases** for the `message` attribute.
-
-<details>
-<summary><strong>Default Message Aliases</strong></summary>
-
-| Alias        | Score | Alias            | Score |
-| ------------ | ----- | ---------------- | ----- |
-| msg          | 100   | data.content     | 9     |
-| content      | 99    | data.description | 8     |
-| description  | 98    | data.text        | 7     |
-| text         | 20    | data.summary     | 6     |
-| summary      | 15    | data.details     | 5     |
-| details      | 14    | body             | 2     |
-| data.message | 10    | data             | 1     |
-
-</details>
-
-Secured Signal API will pick the best scoring Message Alias (if available) to extract the correct message from the Request Body.
-
-Message Aliases can be added by setting `messageAliases` in your config:
-
-```yaml
-settings:
-  messageAliases:
-    [
-      { alias: "msg", score: 80 },
-      { alias: "data.message", score: 79 },
-      { alias: "array[0].message", score: 78 },
-    ]
-```
-
 ### Port
 
 To change the Port which Secured Signal API uses, you need to set `server.port` in your config. (default: `8880`)

data/defaults.yml

@@ -4,25 +4,26 @@ service:
 logLevel: info
 
 settings:
-  messageAliases:
-    [
-      { alias: msg, score: 100 },
-      { alias: content, score: 99 },
-      { alias: description, score: 98 },
-      { alias: text, score: 20 },
-      { alias: summary, score: 15 },
-      { alias: details, score: 14 },
+  dataAliases:
+    "@message":
+      [
+        { alias: msg, score: 100 },
+        { alias: content, score: 99 },
+        { alias: description, score: 98 },
+        { alias: text, score: 20 },
+        { alias: summary, score: 15 },
+        { alias: details, score: 14 },
 
-      { alias: data.message, score: 10 },
-      { alias: data.content, score: 9 },
-      { alias: data.description, score: 8 },
-      { alias: data.text, score: 7 },
-      { alias: data.summary, score: 6 },
-      { alias: data.details, score: 5 },
+        { alias: data.message, score: 10 },
+        { alias: data.content, score: 9 },
+        { alias: data.description, score: 8 },
+        { alias: data.text, score: 7 },
+        { alias: data.summary, score: 6 },
+        { alias: data.details, score: 5 },
 
-      { alias: body, score: 2 },
-      { alias: data, score: 1 },
-    ]
+        { alias: body, score: 2 },
+        { alias: data, score: 1 },
+      ]
 
   variables:
     recipients: ${RECIPIENTS}

examples/config.yml

@@ -1,18 +1,26 @@
 # Example Config (all configurations shown)
+service:
+  port: 8880
 
 api:
-  port: 8880
   url: http://signal-api:8080
   tokens: [token1, token2]
 
-logLevel: INFO
+logLevel: info
 
 settings:
+  messageTemplate: |
+    You've got a Notification:
+    {{@message}} 
+    At {{@data.timestamp}} on {{@data.date}}.
+    Send using {{.NUMBER}}.
+
   variables:
     number: "+123400001"
     recipients: ["+123400002", "group.id", "user.id"]
 
-  messageAliases: [{ alias: "msg", score: 100 }]
+  dataAliases: 
+    "@message": [{ alias: "msg", score: 100 }]
 
   blockedEndpoints:
     - /v1/about

internals/proxy/middlewares/body.go renamed to internals/proxy/middlewares/aliases.go

@@ -12,18 +12,24 @@ import (
 	request "github.com/codeshelldev/secured-signal-api/utils/request"
 )
 
-type BodyMiddleware struct {
+type AliasMiddleware struct {
 	Next 	http.Handler
 }
 
-func (data BodyMiddleware) Use() http.Handler {
+func (data AliasMiddleware) Use() http.Handler {
 	next := data.Next
 
 	return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
-		messageAliases := getSettingsByReq(req).MESSAGE_ALIASES
+		settings := getSettingsByReq(req)
 
-		if messageAliases == nil {
-			messageAliases = getSettings("*").MESSAGE_ALIASES
+		dataAliases := settings.DATA_ALIASES
+
+		if dataAliases == nil {
+			dataAliases = getSettings("*").DATA_ALIASES
+		}
+
+		if settings.VARIABLES == nil {
+			settings.VARIABLES = getSettings("*").VARIABLES
 		}
 
 		body, err := request.GetReqBody(w, req)
@@ -38,13 +44,20 @@ func (data BodyMiddleware) Use() http.Handler {
 		if !body.Empty {
 			bodyData = body.Data
 
-			content, ok := bodyData["message"]
+			aliasData := processDataAliases(dataAliases, bodyData)
 
-			if !ok || content == "" {
+			for key, value := range aliasData {
+				prefix := key[:1]
 
-				bodyData["message"], bodyData = getMessage(messageAliases, bodyData)
+				keyWithoutPrefix := key[1:]
 
-				modifiedBody = true
+				switch prefix {
+					case "@":
+						bodyData[keyWithoutPrefix] = value
+						modifiedBody = true
+					case ".":
+						settings.VARIABLES[keyWithoutPrefix] = value
+				}
 			}
 		}
 
@@ -70,32 +83,44 @@ func (data BodyMiddleware) Use() http.Handler {
 	})
 }
 
-func getMessage(aliases []middlewareTypes.MessageAlias, data map[string]any) (string, map[string]any) {
-	var content string
+func processDataAliases(aliases map[string][]middlewareTypes.DataAlias, data map[string]any) (map[string]any) {
+	aliasData := map[string]any{}
+
+	for key, alias := range aliases {
+		key, value := getData(key, alias, data)
+
+		aliasData[key] = value
+	}
+
+	return aliasData
+}
+
+func getData(key string, aliases []middlewareTypes.DataAlias, data map[string]any) (string, any) {
 	var best int
+	var value any
 
 	for _, alias := range aliases {
 		aliasValue, score, ok := processAlias(alias, data)
 
-		if ok && score > best {
-			content = aliasValue
-		}
+		if ok {
+			if score > best {
+				value = aliasValue
+			}
 
-		data[alias.Alias] = nil
+			data[alias.Alias] = nil
+		}
 	}
 
-	return content, data
+	return key, value
 }
 
-func processAlias(alias middlewareTypes.MessageAlias, data map[string]any) (string, int, bool) {
+func processAlias(alias middlewareTypes.DataAlias, data map[string]any) (any, int, bool) {
 	aliasKey := alias.Alias
 
 	value, ok := jsonutils.GetByPath(aliasKey, data)
 
-	aliasValue, isStr := value.(string)
-
-	if isStr && ok && aliasValue != "" {
-		return aliasValue, alias.Score, true
+	if ok && value != nil {
+		return value, alias.Score, true
 	} else {
 		return "", 0, false
 	}