Skip to content

Commit 7cee659

Browse files
CodeShellDevCodeShellDev
authored
chore: update docs according to chore/restructure-code (#91)
1 parent 0583d98 commit 7cee659

File tree

17 files changed

+180
-166
lines changed

17 files changed

+180
-166
lines changed

‎.github/templates/README.template.md‎

Lines changed: 41 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Check out the official [Documentation](https://codeshelldev.github.io/secured-si
5454
- [Configuration](#configuration)
5555
- [Endpoints](#endpoints)
5656
- [Variables](#variables)
57-
- [Data Aliases](#data-aliases)
57+
- [Field Mappings](#field-mappings)
5858
- [Message Templates](#message-templates)
5959
- [Integrations](https://codeshelldev.github.io/secured-signal-api/docs/integrations/compatibility)
6060
- [Contributing](#contributing)
@@ -229,25 +229,26 @@ These Endpoints are blocked by default due to Security Risks.
229229
> [!NOTE]
230230
> Matching works by checking if the requested Endpoints starts with a Blocked or an Allowed Endpoint
231231
232-
You can modify Blocked Endpoints by configuring `blockedEndpoints` in your config:
232+
You can modify endpoints by configuring `access.endpoints` in your config:
233233

234234
```yaml
235235
settings:
236-
blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts]
236+
access:
237+
endpoints:
238+
- !/v1/register
239+
- !/v1/unregister
240+
- !/v1/qrcodelink
241+
- !/v1/contacts
242+
- /v2/send
237243
```
238244

239-
You can also override Blocked Endpoints by adding Allowed Endpoints to `allowedEndpoints`.
245+
By default adding an endpoint explictly allows access to it, use `!` to block it instead.
240246

241-
```yaml
242-
settings:
243-
allowedEndpoints: [/v2/send]
244-
```
245-
246-
| Config (Allow) | (Block) | Result | | | |
247-
| :------------------------------- | :---------------------------------- | :--------: | --- | :---------------: | --- |
248-
| `allowedEndpoints: ["/v2/send"]` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ |
249-
| `unset` | `blockedEndpoints: ["/v1/receive"]` | **all** | ✅ | **`/v1/receive`** | 🛑 |
250-
| `blockedEndpoints: ["/v2"]` | `allowedEndpoints: ["/v2/send"]` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ |
247+
| Config (Allow) | (Block) | Result | | | |
248+
| :------------- | :------------- | :--------: | --- | :---------------: | --- |
249+
| `/v2/send` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ |
250+
| `unset` | `!/v1/receive` | **all** | ✅ | **`/v1/receive`** | 🛑 |
251+
| `/v2` | `!/v2/send` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ |
251252

252253
### Variables
253254

@@ -260,35 +261,37 @@ See [Placeholders](#placeholders).
260261

261262
```yaml
262263
settings:
263-
variables:
264-
number: "+123400001",
265-
recipients: ["+123400002", "group.id", "user.id"]
264+
message:
265+
variables:
266+
number: "+123400001",
267+
recipients: ["+123400002", "group.id", "user.id"]
266268
```
267269

268270
### Message Templates
269271

270272
To customize the `message` attribute you can use **Message Templates** to build your message by using other Body Keys and Variables.
271-
Use `messageTemplate` to configure:
273+
Use `message.template` to configure:
272274

273275
```yaml
274276
settings:
275-
messageTemplate: |
276-
Your Message:
277-
{{@message}}.
278-
Sent with Secured Signal API.
277+
message:
278+
template: |
279+
Your Message:
280+
{{@message}}.
281+
Sent with Secured Signal API.
279282
```
280283

281284
Message Templates support [Standard Golang Templating](#templating).
282285
Use `@data.key` to reference Body Keys, `#Content_Type` for Headers and `.KEY` for Variables.
283286

284-
### Data Aliases
287+
### Field Mappings
285288

286-
To improve compatibility with other services Secured Signal API provides **Data Aliases** and a built-in `message` Alias.
289+
To improve compatibility with other services Secured Signal API provides **Field Mappings** and a built-in `message` Mapping.
287290

288291
<details>
289-
<summary><strong>Default `message` Aliases</strong></summary>
292+
<summary><strong>Default `message` Mapping</strong></summary>
290293

291-
| Alias | Score | Alias | Score |
294+
| Field | Score | Field | Score |
292295
| ------------ | ----- | ---------------- | ----- |
293296
| msg | 100 | data.content | 9 |
294297
| content | 99 | data.description | 8 |
@@ -300,23 +303,24 @@ To improve compatibility with other services Secured Signal API provides **Data
300303

301304
</details>
302305

303-
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.
306+
Secured Signal API will pick the best scoring Field (if available) to set the Key to the correct Value from the Request Body.
304307

305-
Data Aliases can be added by setting `dataAliases` in your config:
308+
Field Mappings can be added by setting `message.fieldMappings` in your config:
306309

307310
```yaml
308311
settings:
309-
dataAliases:
310-
"@message":
311-
[
312-
{ alias: "msg", score: 80 },
313-
{ alias: "data.message", score: 79 },
314-
{ alias: "array[0].message", score: 78 },
315-
]
316-
".NUMBER": [{ alias: "phone_number", score: 100 }]
312+
message:
313+
fieldMappings:
314+
"@message":
315+
[
316+
{ field: "msg", score: 80 },
317+
{ field: "data.message", score: 79 },
318+
{ field: "array[0].message", score: 78 },
319+
]
320+
".NUMBER": [{ field: "phone_number", score: 100 }]
317321
```
318322

319-
Use `@` for aliasing Body Keys and `.` for aliasing Variables.
323+
Use `@` for mapping to Body Keys and `.` for mapping to Variables.
320324

321325
## Contributing
322326

‎docs/configuration/data-aliases.md‎

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎docs/configuration/endpoints.md‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,22 +23,23 @@ but by default the following endpoints are **blocked**, because of Security Conc
2323
> [!NOTE]
2424
> Matching works by checking if the requested Endpoints starts with a Blocked or an Allowed Endpoint
2525
26-
You can modify Blocked Endpoints by configuring `blockedEndpoints` in your config:
26+
You can modify endpoints by configuring `access.endpoints` in your config:
2727

2828
```yaml
2929
settings:
30-
blockedEndpoints: [/v1/register, /v1/unregister, /v1/qrcodelink, /v1/contacts]
30+
access:
31+
endpoints:
32+
- !/v1/register
33+
- !/v1/unregister
34+
- !/v1/qrcodelink
35+
- !/v1/contacts
36+
- /v2/send
3137
```
3238
33-
You can also override Blocked Endpoints by adding Allowed Endpoints to `allowedEndpoints`.
39+
By default adding an endpoint explictly allows access to it, use `!` to block it instead.
3440

35-
```yaml
36-
settings:
37-
allowedEndpoints: [/v2/send]
38-
```
39-
40-
| Config (Allow) | (Block) | Result | | | |
41-
| :------------------------------- | :---------------------------------- | :--------: | --- | :---------------: | --- |
42-
| `allowedEndpoints: ["/v2/send"]` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ |
43-
| `unset` | `blockedEndpoints: ["/v1/receive"]` | **all** | ✅ | **`/v1/receive`** | 🛑 |
44-
| `blockedEndpoints: ["/v2"]` | `allowedEndpoints: ["/v2/send"]` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ |
41+
| Config (Allow) | (Block) | Result | | | |
42+
| :------------- | :------------- | :--------: | --- | :---------------: | --- |
43+
| `/v2/send` | `unset` | **all** | 🛑 | **`/v2/send`** | ✅ |
44+
| `unset` | `!/v1/receive` | **all** | ✅ | **`/v1/receive`** | 🛑 |
45+
| `/v2` | `!/v2/send` | **`/v2*`** | 🛑 | **`/v2/send`** | ✅ |

‎docs/configuration/examples/config.yml‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,21 @@ api:
99
logLevel: info
1010

1111
settings:
12-
messageTemplate: |
13-
You've got a Notification:
14-
{{@message}}
15-
At {{@data.timestamp}} on {{@data.date}}.
16-
Send using {{.NUMBER}}.
12+
message:
13+
template: |
14+
You've got a Notification:
15+
{{@message}}
16+
At {{@data.timestamp}} on {{@data.date}}.
17+
Send using {{.NUMBER}}.
1718
18-
variables:
19-
number: "+123400001"
20-
recipients: ["+123400002", "group.id", "user.id"]
19+
variables:
20+
number: "+123400001"
21+
recipients: ["+123400002", "group.id", "user.id"]
2122

22-
dataAliases:
23-
"@message": [{ alias: "msg", score: 100 }]
23+
fieldMappings:
24+
"@message": [{ field: "msg", score: 100 }]
2425

25-
blockedEndpoints:
26-
- /v1/about
27-
allowedEndpoints:
28-
- /v2/send
26+
access:
27+
endpoints:
28+
- !/v1/about
29+
- /v2/send

‎docs/configuration/examples/message-template.yml‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,27 @@
11
settings:
2-
messageTemplate: |
3-
{{- $greeting := "Hello" -}}
4-
{{ $greeting }}, {{ @name }}!
5-
{{ if @age -}}
6-
You are {{ @age }} years old.
7-
{{- else -}}
8-
Age unknown.
9-
{{- end }}
10-
Your friends:
11-
{{- range @friends }}
12-
- {{ . }}
13-
{{- else }}
14-
You have no friends.
15-
{{- end }}
16-
Profile details:
17-
{{- range $key, $value := @profile }}
18-
- {{ $key }}: {{ $value }}
19-
{{- end }}
20-
{{ define "footer" -}}
21-
This is the footer for {{ @name }}.
22-
{{- end }}
23-
{{ template "footer" . -}}
24-
------------------------------------
25-
Content-Type: {{ #Content_Type }}
26-
Redacted Auth Header: {{ #Authorization }}
2+
message:
3+
template: |
4+
{{- $greeting := "Hello" -}}
5+
{{ $greeting }}, {{ @name }}!
6+
{{ if @age -}}
7+
You are {{ @age }} years old.
8+
{{- else -}}
9+
Age unknown.
10+
{{- end }}
11+
Your friends:
12+
{{- range @friends }}
13+
- {{ . }}
14+
{{- else }}
15+
You have no friends.
16+
{{- end }}
17+
Profile details:
18+
{{- range $key, $value := @profile }}
19+
- {{ $key }}: {{ $value }}
20+
{{- end }}
21+
{{ define "footer" -}}
22+
This is the footer for {{ @name }}.
23+
{{- end }}
24+
{{ template "footer" . -}}
25+
------------------------------------
26+
Content-Type: {{ #Content_Type }}
27+
Redacted Auth Header: {{ #Authorization }}

‎docs/configuration/examples/token.yml‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
tokens: [LOOOONG_STRING]
22

33
overrides:
4-
variables: # Disable Placeholder
5-
blockedEndpoints: # Disable Sending
6-
- /v2/send
7-
dataAliases: # Disable Aliases
4+
message:
5+
fieldMappings: # Disable Mappings
6+
variables: # Disable Placeholder
7+
8+
access:
9+
endpoints: # Disable Sending
10+
- !/v2/send

‎docs/configuration/field-mappings.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Field Mappings
3+
---
4+
5+
# Field Mappings
6+
7+
A Compatibility Layer for **Secured Signal API**.
8+
9+
To improve compatibility with other services Secured Signal API provides **Field Mappings** and even a built-in `message` Mapping.
10+
11+
<details>
12+
<summary><strong>Default `message` Mapping</strong></summary>
13+
14+
| Field | Score | Field | Score |
15+
| ------------ | ----- | ---------------- | ----- |
16+
| msg | 100 | data.content | 9 |
17+
| content | 99 | data.description | 8 |
18+
| description | 98 | data.text | 7 |
19+
| text | 20 | data.summary | 6 |
20+
| summary | 15 | data.details | 5 |
21+
| details | 14 | body | 2 |
22+
| data.message | 10 | data | 1 |
23+
24+
</details>
25+
26+
Secured Signal API will pick the highest scoring **Field** (if available) to set the key to the correct value **using the request body**.
27+
28+
Field Mappings can be added by setting `message.fieldMappings` in your config:
29+
30+
```yaml
31+
settings:
32+
message:
33+
fieldMappings:
34+
"@message":
35+
[
36+
{ field: "msg", score: 80 },
37+
{ field: "data.message", score: 79 },
38+
{ field: "array[0].message", score: 78 },
39+
]
40+
".NUMBER": [{ field: "phone_number", score: 100 }]
41+
```
42+
43+
> [!IMPORTANT]
44+
> Use `@` for mapping to Body Keys and `.` for mapping to Variables.

‎docs/configuration/message-templates.md‎ renamed to ‎docs/configuration/message-template.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
2-
title: Message Templates
2+
title: Message Template
33
---
44

5-
# Message Templates
5+
# Message Template
66

77
Message Templates are the best way to **structure** and **customize** your messages and also very useful for **compatiblity** between different services.
88

9-
Configure them by using the `messageTemplates` attribute in you config.
9+
Configure them by using the `message.template` attribute in you config.
1010

11-
These support Go Templates (See [Usage](../usage/advanced)) and work by templating the `message` attribute in the request's body.
11+
These support Go Templates (See [Templates](../usage/formatting)) and work by templating the `message` attribute in the request's body.
1212

1313
Here is an example:
1414

@@ -17,5 +17,8 @@ Here is an example:
1717
```
1818

1919
> [!IMPORTANT]
20-
> Message Templates support [Standard Golang Templating](../usage/advanced).
20+
> Message Templates support [Standard Golang Templating](../usage/formatting).
2121
> Use `@data.key` to reference Body Keys, `#Content_Type` for Headers and `.KEY` for [Variables](./variables).
22+
23+
> [!WARNING]
24+
> Templating using the `Authorization` header results in a redacted string.

0 commit comments

Comments
 (0)