From a175f16eb7cab2583bbb036546bedf536a85f8e9 Mon Sep 17 00:00:00 2001 From: Chris Caron Date: Sun, 17 Dec 2023 11:57:04 -0500 Subject: [PATCH] httpSMS Support Added (#1017) --- KEYWORDS | 1 + README.md | 1 + apprise/plugins/NotifyHttpSMS.py | 330 +++++++++++++++++++++++++++ packaging/redhat/python-apprise.spec | 8 +- test/test_plugin_httpsms.py | 171 ++++++++++++++ 5 files changed, 507 insertions(+), 4 deletions(-) create mode 100644 apprise/plugins/NotifyHttpSMS.py create mode 100644 test/test_plugin_httpsms.py diff --git a/KEYWORDS b/KEYWORDS index f9c80b49..66775a23 100644 --- a/KEYWORDS +++ b/KEYWORDS @@ -26,6 +26,7 @@ Gotify Growl Guilded Home Assistant +httpSMS IFTTT Join JSON diff --git a/README.md b/README.md index 82a42aa9..36c29496 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,7 @@ The table below identifies the services this tool supports and some example serv | [DAPNET](https://github.com/caronc/apprise/wiki/Notify_dapnet) | dapnet:// | (TCP) 80 | dapnet://user:pass@callsign
dapnet://user:pass@callsign1/callsign2/callsignN | [D7 Networks](https://github.com/caronc/apprise/wiki/Notify_d7networks) | d7sms:// | (TCP) 443 | d7sms://token@PhoneNo
d7sms://token@ToPhoneNo1/ToPhoneNo2/ToPhoneNoN | [DingTalk](https://github.com/caronc/apprise/wiki/Notify_dingtalk) | dingtalk:// | (TCP) 443 | dingtalk://token/
dingtalk://token/ToPhoneNo
dingtalk://token/ToPhoneNo1/ToPhoneNo2/ToPhoneNo1/ + [httpSMS](https://github.com/caronc/apprise/wiki/Notify_httpsms) | httpsms:// | (TCP) 443 | httpsms://ApiKey@FromPhoneNo
httpsms://ApiKey@FromPhoneNo/ToPhoneNo
httpsms://ApiKey@FromPhoneNo/ToPhoneNo1/ToPhoneNo2/ToPhoneNoN/ | [Kavenegar](https://github.com/caronc/apprise/wiki/Notify_kavenegar) | kavenegar:// | (TCP) 443 | kavenegar://ApiKey/ToPhoneNo
kavenegar://FromPhoneNo@ApiKey/ToPhoneNo
kavenegar://ApiKey/ToPhoneNo1/ToPhoneNo2/ToPhoneNoN | [MessageBird](https://github.com/caronc/apprise/wiki/Notify_messagebird) | msgbird:// | (TCP) 443 | msgbird://ApiKey/FromPhoneNo
msgbird://ApiKey/FromPhoneNo/ToPhoneNo
msgbird://ApiKey/FromPhoneNo/ToPhoneNo1/ToPhoneNo2/ToPhoneNoN/ | [MSG91](https://github.com/caronc/apprise/wiki/Notify_msg91) | msg91:// | (TCP) 443 | msg91://TemplateID@AuthKey/ToPhoneNo
msg91://TemplateID@AuthKey/ToPhoneNo1/ToPhoneNo2/ToPhoneNoN/ diff --git a/apprise/plugins/NotifyHttpSMS.py b/apprise/plugins/NotifyHttpSMS.py new file mode 100644 index 00000000..ddbd2942 --- /dev/null +++ b/apprise/plugins/NotifyHttpSMS.py @@ -0,0 +1,330 @@ +# -*- coding: utf-8 -*- +# BSD 2-Clause License +# +# Apprise - Push Notification Library. +# Copyright (c) 2023, Chris Caron +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# 1. Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# +# 2. Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. + +# To use this service you will need a httpSMS account +# You will need credits (new accounts start with a few) +# https://httpsms.com +import requests +import json +from .NotifyBase import NotifyBase +from ..common import NotifyType +from ..utils import is_phone_no +from ..utils import parse_phone_no +from ..utils import validate_regex +from ..AppriseLocale import gettext_lazy as _ + + +class NotifyHttpSMS(NotifyBase): + """ + A wrapper for HttpSMS Notifications + """ + + # The default descriptive name associated with the Notification + service_name = 'httpSMS' + + # The services URL + service_url = 'https://httpsms.com' + + # All notification requests are secure + secure_protocol = 'httpsms' + + # A URL that takes you to the setup/help of the specific protocol + setup_url = 'https://github.com/caronc/apprise/wiki/Notify_httpsms' + + # HttpSMS uses the http protocol with JSON requests + notify_url = 'https://api.httpsms.com/v1/messages/send' + + # The maximum length of the body + body_maxlen = 160 + + # A title can not be used for SMS Messages. Setting this to zero will + # cause any title (if defined) to get placed into the message body. + title_maxlen = 0 + + # Define object templates + templates = ( + '{schema}://{apikey}@{from_phone}', + '{schema}://{apikey}@{from_phone}/{targets}', + ) + + # Define our template tokens + template_tokens = dict(NotifyBase.template_tokens, **{ + 'apikey': { + 'name': _('API Key'), + 'type': 'string', + 'private': True, + 'required': True, + }, + 'from_phone': { + 'name': _('From Phone No'), + 'type': 'string', + 'regex': (r'^\+?[0-9\s)(+-]+$', 'i'), + 'map_to': 'source', + 'required': True, + }, + 'target_phone': { + 'name': _('Target Phone No'), + 'type': 'string', + 'prefix': '+', + 'regex': (r'^[0-9\s)(+-]+$', 'i'), + 'map_to': 'targets', + }, + 'targets': { + 'name': _('Targets'), + 'type': 'list:string', + 'required': True, + }, + }) + + # Define our template arguments + template_args = dict(NotifyBase.template_args, **{ + 'key': { + 'alias_of': 'apikey', + }, + 'to': { + 'alias_of': 'targets', + }, + 'from': { + 'name': _('From Phone No'), + 'type': 'string', + 'regex': (r'^\+?[0-9\s)(+-]+$', 'i'), + 'map_to': 'source', + }, + }) + + def __init__(self, apikey=None, source=None, targets=None, **kwargs): + """ + Initialize HttpSMS Object + """ + super(NotifyHttpSMS, self).__init__(**kwargs) + + self.apikey = validate_regex(apikey) + if not self.apikey: + msg = 'An invalid API Key ({}) was specified.'.format(apikey) + self.logger.warning(msg) + raise TypeError(msg) + + result = is_phone_no(source) + if not result: + msg = 'The Account (From) Phone # specified ' \ + '({}) is invalid.'.format(source) + self.logger.warning(msg) + raise TypeError(msg) + + # Tidy source + self.source = result['full'] + + # Parse our targets + self.targets = list() + + has_error = False + for target in parse_phone_no(targets): + # Parse each phone number we found + result = is_phone_no(target) + if result: + self.targets.append(result['full']) + continue + + has_error = True + self.logger.warning( + 'Dropped invalid phone # ({}) specified.'.format(target), + ) + + if not targets and not has_error: + # Default the SMS Message to ourselves + self.targets.append(self.source) + + return + + def send(self, body, title='', notify_type=NotifyType.INFO, **kwargs): + """ + Perform HttpSMS Notification + """ + + if not self.targets: + # We have nothing to notify + self.logger.warning('There are no HttpSMS targets to notify') + return False + + # error tracking (used for function return) + has_error = False + + # Prepare our headers + headers = { + 'User-Agent': self.app_id, + 'x-api-key': self.apikey, + 'Content-Type': 'application/json', + } + + # Prepare our payload + payload = { + # The To gets populated in the loop below + 'from': '+' + self.source, + 'to': None, + 'content': body, + } + + # Prepare our targets + targets = list(self.targets) + while len(targets): + # Get our target to notify + target = targets.pop(0) + + # Prepare our user + payload['to'] = '+' + target + + # Some Debug Logging + self.logger.debug('HttpSMS POST URL: {} (cert_verify={})'.format( + self.notify_url, self.verify_certificate)) + self.logger.debug('HttpSMS Payload: {}' .format(payload)) + + # Always call throttle before any remote server i/o is made + self.throttle() + try: + r = requests.post( + self.notify_url, + data=json.dumps(payload), + headers=headers, + verify=self.verify_certificate, + timeout=self.request_timeout, + ) + + if r.status_code != requests.codes.ok: + # We had a problem + status_str = \ + NotifyBase.http_response_code_lookup(r.status_code) + + # set up our status code to use + status_code = r.status_code + + self.logger.warning( + 'Failed to send HttpSMS notification to {}: ' + '{}{}error={}.'.format( + target, + status_str, + ', ' if status_str else '', + status_code)) + + self.logger.debug( + 'Response Details:\r\n{}'.format(r.content)) + + # Mark our failure + has_error = True + continue + + else: + self.logger.info( + 'Sent HttpSMS notification to {}.'.format(target)) + + except requests.RequestException as e: + self.logger.warning( + 'A Connection error occurred sending HttpSMS: to %s ', + target) + self.logger.debug('Socket Exception: %s' % str(e)) + + # Mark our failure + has_error = True + continue + + return not has_error + + def url(self, privacy=False, *args, **kwargs): + """ + Returns the URL built dynamically based on specified arguments. + """ + + # Prepare our parameters + params = self.url_parameters(privacy=privacy, *args, **kwargs) + + # A nice way of cleaning up the URL length a bit + targets = [] if len(self.targets) == 1 \ + and self.targets[0] == self.source else self.targets + + return '{schema}://{apikey}@{source}/{targets}' \ + '?{params}'.format( + schema=self.secure_protocol, + source=self.source, + apikey=self.pprint(self.apikey, privacy, safe=''), + targets='/'.join([ + NotifyHttpSMS.quote('{}'.format(x), safe='+') + for x in targets]), + params=NotifyHttpSMS.urlencode(params)) + + def __len__(self): + """ + Returns the number of targets associated with this notification + """ + + return len(self.targets) if self.targets else 1 + + @staticmethod + def parse_url(url): + """ + Parses the URL and returns enough arguments that can allow + us to re-instantiate this object. + + """ + + results = NotifyBase.parse_url(url, verify_host=False) + if not results: + # We're done early as we couldn't load the results + return results + + # Get our API Key + results['apikey'] = NotifyHttpSMS.unquote(results['user']) + + # Support the 'from' and 'source' variable so that we can support + # targets this way too. + # The 'from' makes it easier to use yaml configuration + if 'from' in results['qsd'] and len(results['qsd']['from']): + results['source'] = \ + NotifyHttpSMS.unquote(results['qsd']['from']) + + # hostname will also be a target in this case + results['targets'] = [ + *NotifyHttpSMS.parse_phone_no(results['host']), + *NotifyHttpSMS.split_path(results['fullpath'])] + + else: + # store our source + results['source'] = NotifyHttpSMS.unquote(results['host']) + + # store targets + results['targets'] = NotifyHttpSMS.split_path(results['fullpath']) + + # Support the 'to' variable so that we can support targets this way too + # The 'to' makes it easier to use yaml configuration + if 'to' in results['qsd'] and len(results['qsd']['to']): + results['targets'] += \ + NotifyHttpSMS.parse_phone_no(results['qsd']['to']) + + if 'key' in results['qsd'] and len(results['qsd']['key']): + results['apikey'] = \ + NotifyHttpSMS.unquote(results['qsd']['key']) + + return results diff --git a/packaging/redhat/python-apprise.spec b/packaging/redhat/python-apprise.spec index 7f05a9f9..6e79d856 100644 --- a/packaging/redhat/python-apprise.spec +++ b/packaging/redhat/python-apprise.spec @@ -41,10 +41,10 @@ it easy to access: Apprise API, APRS, AWS SES, AWS SNS, Bark, Boxcar, Burst SMS, BulkSMS, ClickSend, DAPNET, DingTalk, Discord, E-Mail, Emby, Faast, FCM, Flock, -Google Chat, Gotify, Growl, Guilded, Home Assistant, IFTTT, Join, Kavenegar, -KODI, Kumulos, LaMetric, Line, MacOSX, Mailgun, Mastodon, Mattermost, -Matrix, MessageBird, Microsoft Windows, Microsoft Teams, Misskey, MQTT, -MSG91, MyAndroid, Nexmo, Nextcloud, NextcloudTalk, Notica, Notifiarr, +Google Chat, Gotify, Growl, Guilded, Home Assistant, httpSMS, IFTTT, Join, +Kavenegar, KODI, Kumulos, LaMetric, Line, MacOSX, Mailgun, Mastodon, +Mattermost,Matrix, MessageBird, Microsoft Windows, Microsoft Teams, Misskey, +MQTT, MSG91, MyAndroid, Nexmo, Nextcloud, NextcloudTalk, Notica, Notifiarr, Notifico, ntfy, Office365, OneSignal, Opsgenie, PagerDuty, PagerTree, ParsePlatform, PopcornNotify, Prowl, Pushalot, PushBullet, Pushjet, PushMe, Pushover, PushSafer, Pushy, PushDeer, Reddit, Rocket.Chat, RSyslog, SendGrid, diff --git a/test/test_plugin_httpsms.py b/test/test_plugin_httpsms.py new file mode 100644 index 00000000..45ac38ed --- /dev/null +++ b/test/test_plugin_httpsms.py @@ -0,0 +1,171 @@ +# -*- coding: utf-8 -*- +# BSD 2-Clause License +# +# Apprise - Push Notification Library. +# Copyright (c) 2023, Chris Caron +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# 1. Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# +# 2. Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. + +from unittest import mock + +import requests +from json import loads +from apprise import Apprise +from apprise.plugins.NotifyHttpSMS import NotifyHttpSMS +from helpers import AppriseURLTester +from apprise import NotifyType + +# Disable logging for a cleaner testing output +import logging +logging.disable(logging.CRITICAL) + +# Our Testing URLs +apprise_url_tests = ( + ('httpsms://', { + # Instantiated but no auth, so no notification can happen + 'instance': TypeError, + }), + ('httpsms://:@/', { + # invalid token + 'instance': TypeError, + }), + ('httpsms://{}:{}@{}'.format('u' * 10, 'p' * 10, '3' * 5), { + # invalid source number provided + 'instance': TypeError, + }), + ('httpsms://{}@{}/{}'.format('p' * 10, '1' * 10, 2 * '5'), { + # invalid target number provided + 'instance': NotifyHttpSMS, + # Expected notify() response because we have no one to notify + 'notify_response': False, + }), + ('httpsms://{}@{}'.format('p' * 10, '2' * 10), { + # default to ourselves + 'instance': NotifyHttpSMS, + }), + ('httpsms://{}@9876543210/{}/abcd/'.format( + 'b' * 10, '3' * 11), { + # included phone, short number (123) and garbage string (abcd) dropped + 'instance': NotifyHttpSMS, + 'privacy_url': 'httpsms://b...b@9876543210/33333333333' + }), + ('httpsms://{}@{}'.format('c' * 10, '4' * 11), { + 'instance': NotifyHttpSMS, + + # Our expected url(privacy=True) startswith() response: + 'privacy_url': 'httpsms://c...c@44444444444', + }), + ('httpsms://{}@{}'.format('b' * 10, '5' * 11), { + # using phone no with no target - we text ourselves in this case + 'instance': NotifyHttpSMS, + }), + ('httpsms://?key={}&from={}'.format( + 'y' * 10, '5' * 11), { + # use get args to acomplish the same thing + 'instance': NotifyHttpSMS, + }), + ('httpsms://?key={}&from={}&to={}'.format( + 'b' * 10, '5' * 11, '7' * 13), { + # use to= and key= + 'instance': NotifyHttpSMS, + }), + ('httpsms://{}@{}'.format('b' * 10, '5' * 11), { + 'instance': NotifyHttpSMS, + # throw a bizzare code forcing us to fail to look it up + 'response': False, + 'requests_response_code': 999, + }), + ('httpsms://{}@{}'.format('b' * 10, '5' * 11), { + 'instance': NotifyHttpSMS, + # Throws a series of connection and transfer exceptions when this flag + # is set and tests that we gracfully handle them + 'test_requests_exceptions': True, + }), +) + + +def test_plugin_httpsms_urls(): + """ + NotifyTemplate() Apprise URLs + + """ + + # Run our general tests + AppriseURLTester(tests=apprise_url_tests).run_all() + + +@mock.patch('requests.post') +def test_plugin_httpsms_edge_cases(mock_post): + """ + NotifyHttpSMS() Edge Cases + + """ + + # Initialize some generic (but valid) tokens + apikey = 'mykey123' + source = "1 (405) 123 1234" + targets = [ + '+1(555) 123-1234', + '1555 5555555', + # A garbage entry + '12', + # NOw a valid one because a group was implicit + '@12', + ] + + # Prepare our response + response = requests.Request() + response.status_code = requests.codes.ok + + # Prepare Mock + mock_post.return_value = response + + # Instantiate our object + obj = Apprise.instantiate( + 'httpsms://{}@{}/{}'.format(apikey, source, '/'.join(targets))) + + assert obj.notify( + body='body', title='title', notify_type=NotifyType.INFO) is True + + # We know there are 2 targets + assert len(obj) == 2 + + # Test our call count + assert mock_post.call_count == 2 + + # Test + details = mock_post.call_args_list[0] + payload = loads(details[1]['data']) + assert payload['from'] == '+14051231234' + assert payload['to'] == '+15551231234' + assert payload['content'] == 'title\r\nbody' + + details = mock_post.call_args_list[1] + payload = loads(details[1]['data']) + assert payload['from'] == '+14051231234' + assert payload['to'] == '+15555555555' + assert payload['content'] == 'title\r\nbody' + + # Verify our URL looks good + assert obj.url().startswith( + 'httpsms://mykey123@14051231234/15551231234/15555555555')