Built in Apprise URL "builder"

Casvt commented 1 year ago

Is your feature request related to a problem? Please describe.

You currently have to go to the Apprise documentation to learn how to "build" the URL.

Describe the solution you'd like

There should be a built-in builder that allows you to create this URL automatically using nice input fields

Additional context

Should look something like this:

caronc commented 1 year ago

I would love to see where you go with this. This is something I've wanted to build myself dynamically. I took a lot of time and effort to make it so Apprise.details() returns all of the information needed to automate this (and support new plugins as the come).

Casvt commented 1 year ago

Thanks for the tip. I didn't know about Apprise.details(). I'm pretty sure it will make the process easier.

Casvt commented 1 year ago

@caronc It's going really well with implementing this feature. There is one problem I found though.

For "AWS Simple Email Service (SES)", the output of Apprise.details() says that the token "region" is not required (see selected line in image). However, in the wiki, it says that it's required. The templates in the image above at the top also suggest that it's required because there are no templates without the region token.

The result is that the region field is not required for adding SES as a notification service (as reported in the output of the details function) but the JS will fail to transform all the input fields into an apprise URL because the region token value can be missing and it's required in each template.

TL;DR The token "region" for SES should be set to required in the details output.

caronc commented 1 year ago

I love that you're going through the entries and vetting this! Please do not stop. I would agree that the docs are correct, and the JSON response is not. The region is required; I'll create a ticket and fix this.

Casvt commented 1 year ago

@caronc Another problem:

The "From Email" token maps to "from_addr" (selected line), but in the template it's called "from_email".

Casvt commented 1 year ago

@caronc Found another problem. Do you want me to make a new ticket for each finding, or should we use the ticket you already made to include all my findings?

AWS Simple Email Service (SES)

1) Same problem as error 18. 67) The token "From Email" is set as not required, but it is.

AWS Simple Notification Service (SNS)

2) The token "Region" maps to "region_name" but in the template it's called "region". 3) A / is missing between {secret_access_key} and {region} in the template.

Bark

4) Index 1 and 3 are the same. 5) Also, index 1 suggests that the port isn't required, and in the token list the port is also not marked as required, but there is no template with just the host and targets ({schema}://{host}/{targets}). 68) The token "targets" is set as not required, but it is. 69) Resulting from 68, following 10, the token "Target Device" should be set as required.

Boxcar

6) The token with the name "Access Key" maps to "access", but in the templates it's called "access_key". 7) The token with the name "Secret Key" maps to "secret", but in the templates it's called "secret_key".

BulkSMS

8) All tokens are marked as not required, but they're all required.

ClickSend

9) In the wiki, the first syntax should have it's last / removed. It should be clicksend://{user}:{password}@{PhoneNo} 10) The wiki says that PhoneNo (targets) needs at least one value. That's why the token "targets" is set as required, but the token "Target Phone No", which is what "targets" consists of, should also be set as required then.

D7 Networks

11) Same problem as error 9, but for both syntaxes. 12) The token "Target Phone No" is marked as not required, even though it is (similar to error 10). 13) The token "targets" is marked as not required, even though it is.

Dapnet

14) Same problem as error 10.

DingTalk

15) Both tokens have the name "Token", which is confusing. The second token should have the name "Secret". 16) Same problem as error 18.

Discord

17) The token with the name "Bot Name" maps to "user", but in the templates it's called "botname".

E-Mail

18) The following:

"targets": {
    "name": "Target Emails",
    "type": "list:string",
    "map_to": "targets",
    "delim": ("/",),
    "required": False,
    "private": False,
},

should become:

"target_email": {
    "name": "Target E-Mail",
    "type": "string",
    "map_to": "targets",
    "required": False,
    "private": False,
},
"targets": {
    "name": "Targets",
    "type": "list:string",
    "map_to": "targets",
    "delim": ("/",),
    "required": False,
    "private": False,
},

Emby

19) In the wiki, the syntax emby://{userid}:{password}@{hostname} is missing. 20) In the wiki, the syntax embys://{userid}:{password}@{hostname} is missing.

Enigma2

21) All the following templates are not present in the wiki (but there isn't any docs about the "fullpath" token so maybe it's reversed and instead you should remove those templates from the details() output?):

Firebase Cloud Messaging

22) The token "project" is set as required but the second template doesn't require it, so it should not be required. 23) The token "targets" is set as not required, but all templates require it, so it should be required.

Flock

24) The token "Bot Name" maps to "user". This is correct because in the templates, the name "{user}" is used. So it's correct but a bit strange... why not "{botname}"? The wiki also uses "{botname}".

Form

25) The wiki doesn't have the templates {schema}://{user}@{host} and {schema}://{user}@{host}:{port}.

Gitter

26) The token "targets" is set as not required but actually is required. 27) Same problem as error 18.

Gotify

28) The token "Path" maps to "fullpath" but in the templates the variable is "{path}". 29) The token "Path" is marked as required but it isn't.

Guilded

30) The token "Bot Name" maps to "user" but in the templates the variable is "{botname}".

IFTTT

31) Same problem as error 18.

Join

32) According to the wiki, the token "Targets" is not required, but it is marked as required in the details output. 33) I've never used Join before so I'm not sure if I'm correct but the token "Group" gives select options for a platform while the wiki makes it seem to me that you need to supply an ID.

Kavenegar

34) Same problem as error 10.

Kodi

35) The following template is missing in the wiki: {schema}://{user}:{password}@{host}.

LaMetric

36) The following template is missing in the details output: {schema}://{user}:{apikey}@{host}. 37) The token "Hostname" is marked as required, but isn't.

Line

38) The token "targets" is not marked as required, but it is. 39) Resulting from 38, following 10, the token "Target User" should be set as required.

Mailgun

40) Same problem as error 18.

Matrix

41) (Not completely sure) The token "Access Token" should map to "token", not "password". 42) The token "host" is set as required, but isn't.

Mattermost

43) The templates with indexes 1 and 5 have the "port" token at the wrong place. 44) A / is missing at index 5 between "fullpath" and "token". 45) The token "Bot Name" maps to "user" but should instead map to "botname".

MSG91

46) Same problem as error 38. 47) Same problem as error 39.

MSTeams

48) The token "Team Name" is set as required but isn't.

NextCloud

49) Same problem as error 10. 50) Templates that don't contain the "user" token and "password" token are missing.

NextCloud Talk

51) Same problem as error 18.

Notica

52) The token "Path" maps to "fullpath" but should map to "path". However, the wiki doesn't mention this variable so maybe it's not supported anymore and should be removed from the details output? 53) Should there be a / between the "path" token and the "token" token in the templates?

Office 365

54) Same problem as error 18

OneSignal

55) The token "targets" is set as not required, even though it is.

Pager Duty

56) Maybe rename the token "Routing Key" to "Integration Key"?

PopcornNotify

57) The token "targets" is set as not required, but it is.

Pushjet

58) The wiki is missing the template {schema}://{user}:{password}@{host}:{port}/{secret_key}

59) The token "targets" should be required. 60) Resulting from 59, following 10, the token "Target Subreddit" should be required.

Ryver

61) Same problem as error 24.

ServerChan

62) Both in the wiki and in the details output, the trailing / in the template can be removed.

Signal API

63) The token "From Phone No" maps to "source" but should instead map to "from_phone".

SimplePush

64) The token "Encrypted Salt" maps to "user" but should instead map to "salt". 65) It's unclear in the wiki if the password and salt are used for encryption or if they're encrypted themselves. 66) In the wiki -> Parameter Breakdown -> Variable = password -> Description is a typo ppassword -> password.

Sinch

70) The token "From Phone No" maps to "source" but should instead map to "from_phone".

Slack

71) A / is missing in the templates between the tokens "token_b" and "token_c". 72) The tokens "token_a", "token_b" and "token_c" are marked as required, but actually aren't. 73) The token "Bot Name" maps to "user" but should instead map to "botname".

SMS Eagle

74) The token "token" is set as not required, but it is. 75) The token "targets" is set as not required, but it is. 76) Resulting from 75, following 10, the tokens "Target Phone No", "Target Group ID" and "Target Contact" should also be set as required.

SMTP2Go

77) Same problem as error 18.

SparkPost

78) Same problem as error 18.

Spontit

79) The token "targets" is marked as required but isn't.

Syslog

80) The token "host" is set as required, but isn't.

Twilio

81) The token "From Phone No" maps to "source" but should instead map to "from_phone".

Twist

82) The token "password" is set as not required, but it is. 83) The token "email" is set as not required, but it is. 84) The following is not present in the details output:

Twitter

85) The token "targets" can not be found in the wiki.

VolPms

86) At the parameter breakdown -> Variable = to | from -> Required, the star is never explained. It references nothing.\ 87) In the wiki, "fromPhoneNo" ("from_phone") is required in each template, but in the details output there is a template without it. 88) The token "From Phone No" maps to "source" but should instead map to "from_phone".

Vonage

89) The token "From Phone No" maps to "source" but should instead map to "from_phone".

Zulip

90) The token "botname" is set as not required, but it is.

caronc commented 1 year ago

This is great; i did start a ticket you can cross reference. Either way, the ticket points back here anyway, so it's all linked at the end of the day.

caronc commented 1 year ago

@caronc Another problem:

The "From Email" token maps to "from_addr" (selected line), but in the template it's called "from_email".

I started tackling the issues you pointed out. so the map_to is more of an internal thing. Perhaps it shouldn't be part of the API output. It maps to the actual object initialization (the __init__ one). It mitigates cases where the arguments and class initialization don't align (but are aliases of one another). for the API, you probably only need to pay attention to the alias_of which is when 2 variables can be set by 2 different means...

so in this case...

class NotifySES(...):
   # ...
    # Define our template tokens
    template_tokens = dict(NotifyBase.template_tokens, **{
        'from_email': {
            'name': _('From Email'),
            'type': 'string',
           # Map to __init__() call
            'map_to': 'from_addr',
        },
        #....
    }

    # Define our template arguments
    # Thesse are your Apprise://url/?kwargs
    template_args = dict(NotifyBase.template_args, **{
        'to': {
            'alias_of': 'targets',
        },
        'from': {
           # Maps to our token 'from_email'
            'alias_of': 'from_email',
        },
        # ....
    }

    def __init__(self, ...<content>,  from_addr=None, **kwargs):
         #                                     ^
         #                      = from_email, but the external users don't need to really know this

Thus the URL could be written like:

{schema}://{from_email}/{access_key_id}/{secret_access_key}/
{schema}://?from={from_email}&access={access_key_id}&secret={secret_access_key}

You might be wondering why anyone would do this, it's actually because if you make use of Apprise .YAML files, you can build very powerful and easy to read configuration like:

urls:
 # The below defines 2 SNS URLs dynamically built when Apprise reads in the configuration
  - "sns://":
      - from: {from_email}
        access: {access_key_id}
        secret: {secret_access_key}

      - from: {another_from_email}
        access: {another_access_key_id}
        secret: {another_secret_access_key}

kwarg's allow you to detach the entry from the Apprise URL completely and still have their value parsed. It is even more powerful wit things like emails where you may wish to define your Email Apprise URL once, but define a ton of end users to notify by different tags:

urls:
 # The below defines 2 SNS URLs dynamically built when Apprise reads in the configuration
  - "mailtos:/myuser:password@gmail.com/":
      - to: joe@test.com, jack@test.com
        tags: friends

      - to: sales@test.com, mgmt@test.com
       tags: work

All that said.. there still might be some inconsistencies you find... I'm going through your list now and updating what i can. Great work on your part btw doing all this!

Casvt commented 1 year ago

See this example:

"target_email": {
    "name": "Target E-Mail",
    "type": "string",
    "map_to": "targets",
    "required": False,
    "private": False,
},
"targets": {
    "name": "Targets",
    "type": "list:string",
    "map_to": "targets",
    "delim": ("/",),
    "required": False,
    "private": False,
},

By removing the map_to key, how would one know that target_email is linked to targets (targets consists of target_email's)?

caronc commented 1 year ago

By removing the map_to key, how would one know that target_email is linked to targets (targets consists of target_email's)?

It's a good point; map_to maps to the under-lining object initialization. alias_of is more of a symbolic link across all of the definitions and inherits all of the details from wherever the link points to.

Maybe I should introduce a third state to allow for grouping?..... maybe for the target lists, each element in it could have a group keyword instead... or perhaps the reuse of alias_of instead?

Casvt commented 1 year ago

A group key sounds good. Clear and simple.

It's clear that my code shouldn't look at the map_to key when mapping to the variables in the templates. Is the key of a token in the dict of tokens the mapping to the variable in the template? Because I need a reliable way to fill in the template with the values of the tokens.

caronc commented 1 year ago

group added and all of your items identified above (i believe) were addressed. I think the group keyword will allow you to ignore the map_to entries.

If you find more things i can clean up; i'll be more than happy to oblige!

I really appreciate all the effort you put into building that list above. :rocket:

Casvt commented 1 year ago

@caronc When are you planning on releasing a new version, where these changes are included? Because I can't release my URL builder without the new changes.

Casvt / MIND

Built in Apprise URL "builder" #3