Add Voxbone as a carrier module (2600hz#5884)

- iso3166 utilities for a2 to a3 conversion - auto generate knm_iso3166_util - Updated system configuration section `carrier_modules` example to include more thorough real world config block. - Add http_method type to enumerate supported HTTP methods by Voxbone API - Fixup spec on build_uri/2 - Fixed erroroneous binary creation in to_voxbone_pattern/1 - Add tickies to showEmpty value in required_params/0 - Fixed voxbone_request/3, voxbone_request/4 to use http_method in spec - Added addtional doc headers and reformatting - Added handler for HTTP 500 - Add knm_voxbone to number provider quantifiers - number release / disconnect implemented - fetch_did API request implemented - missing period in handle_error - added voxbone number find test fixtures - added inital voxbone test suite with number find - wrapped voxbone_request in preprocessor to wire up fixtures for test
kagesys · Sep 12, 2019 · abbffd8 · abbffd8
1 parent 171efb6
commit abbffd8
Show file tree

Hide file tree

Showing 26 changed files with 2,866 additions and 2 deletions.
diff --git a/.gitignore b/.gitignore
@@ -40,6 +40,7 @@ core/sup/sup
 
 core/kazoo_number_manager/dialcodes.json
 core/kazoo_number_manager/src/knm_iso3166a2_itu.erl
+core/kazoo_number_manager/src/knm_iso3166_util.erl
 
 make/erlang-formatter/
 /TAGS

diff --git a/applications/crossbar/priv/api/swagger.json b/applications/crossbar/priv/api/swagger.json
@@ -34161,6 +34161,37 @@
             },
             "type": "object"
         },
+        "system_config.number_manager.voxbone": {
+            "description": "Schema for number_manager.voxbone system_config",
+            "properties": {
+                "api_password": {
+                    "default": "",
+                    "description": "number_manager voxbone api_password",
+                    "type": "string"
+                },
+                "api_username": {
+                    "default": "",
+                    "description": "number_manager voxbone api_username",
+                    "type": "string"
+                },
+                "environment": {
+                    "default": "sandbox",
+                    "description": "number_manager voxbone environment",
+                    "enum": [
+                        "sandbox",
+                        "production",
+                        "beta"
+                    ],
+                    "type": "string"
+                },
+                "max_page_size": {
+                    "default": 20,
+                    "description": "number_manager voxbone max_page_size",
+                    "type": "integer"
+                }
+            },
+            "type": "object"
+        },
         "system_config.omnipresence": {
             "description": "Schema for omnipresence system_config",
             "properties": {

diff --git a/applications/crossbar/priv/couchdb/schemas/system_config.number_manager.voxbone.json b/applications/crossbar/priv/couchdb/schemas/system_config.number_manager.voxbone.json
@@ -0,0 +1,33 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "_id": "system_config.number_manager.voxbone",
+    "description": "Schema for number_manager.voxbone system_config",
+    "properties": {
+        "api_password": {
+            "default": "",
+            "description": "number_manager voxbone api_password",
+            "type": "string"
+        },
+        "api_username": {
+            "default": "",
+            "description": "number_manager voxbone api_username",
+            "type": "string"
+        },
+        "environment": {
+            "default": "sandbox",
+            "description": "number_manager voxbone environment",
+            "enum": [
+                "sandbox",
+                "production",
+                "beta"
+            ],
+            "type": "string"
+        },
+        "max_page_size": {
+            "default": 20,
+            "description": "number_manager voxbone max_page_size",
+            "type": "integer"
+        }
+    },
+    "type": "object"
+}
diff --git a/applications/crossbar/priv/oas3/oas3-schemas.yml b/applications/crossbar/priv/oas3/oas3-schemas.yml
@@ -12454,6 +12454,30 @@
       'description': number_manager.voip_innovations sandbox provisioning
       'type': boolean
   'type': object
+'system_config.number_manager.voxbone':
+  'description': Schema for number_manager.voxbone system_config
+  'properties':
+    'api_password':
+      'default': ''
+      'description': number_manager voxbone api_password
+      'type': string
+    'api_username':
+      'default': ''
+      'description': number_manager voxbone api_username
+      'type': string
+    'environment':
+      'default': sandbox
+      'description': number_manager voxbone environment
+      'enum':
+        - sandbox
+        - production
+        - beta
+      'type': string
+    'max_page_size':
+      'default': 20
+      'description': number_manager voxbone max_page_size
+      'type': integer
+  'type': object
 'system_config.omnipresence':
   'description': Schema for omnipresence system_config
   'properties':

diff --git a/core/kazoo_number_manager/Makefile b/core/kazoo_number_manager/Makefile
@@ -7,6 +7,11 @@ ITU = src/knm_iso3166a2_itu.erl
 ITU_SRC = src/knm_iso3166a2_itu.erl.src
 ITU_FILE = dialcodes.json
 ITU_URL = https://raw.githubusercontent.com/mledoze/countries/c212082894e48e8be123dad5dea7d9e6abc0c1b9/countries.json
+
+# ISO3166_utils module generator.
+ISO3166 =  src/knm_iso3166_util.erl
+ISO3166_SRC =  src/knm_iso3166_util.erl.src
+
 # official list https://www.itu.int/pub/T-SP-E.164D
 # but there are newer ones… https://www.itu.int/pub/T-SP-OB
 #
@@ -23,8 +28,8 @@ ITU_URL = https://raw.githubusercontent.com/mledoze/countries/c212082894e48e8be1
 # https://countrycode.org/
 # https://en.wikipedia.org/wiki/List_of_country_calling_codes
 
-COMPILE_MOAR = $(ITU)
-SOURCES = $(ITU) $(wildcard src/*.erl) $(wildcard src/*/*.erl)
+COMPILE_MOAR = $(ITU) $(ISO3166)
+SOURCES = $(ITU) $(ISO3166) $(wildcard src/*.erl) $(wildcard src/*/*.erl)
 
 CLEAN_MOAR = clean-generated
 
@@ -36,6 +41,7 @@ include $(ROOT)/make/kz.mk
 
 clean-generated:
 	$(if $(wildcard $(ITU)), @rm $(ITU))
+	$(if $(wildcard $(ISO3166)), @rm $(ISO3166))
 
 $(ITU_FILE):
 	wget -qO $@ $(ITU_URL)
@@ -46,3 +52,10 @@ $(ITU): $(ITU_SRC)
 	@cat $(ITU_SRC) >$(ITU)
 	@python -c 'from __future__ import print_function; import json; [print("to_itu(<<\"", l["cca2"], "\">>) -> <<\"+", l["callingCode"][0], "\">>;", sep="") for l in sorted(json.load(open("dialcodes.json")), key=lambda l: l["cca2"]) if len(l["callingCode"]) > 0]' >>$(ITU)
 	@echo 'to_itu(_) -> <<>>.' >>$(ITU)
+
+$(ISO3166_SRC): $(ITU_FILE)
+
+$(ISO3166): $(ISO3166_SRC)
+	@cat $(ISO3166_SRC) >$(ISO3166)
+	@python -c 'from __future__ import print_function; import json; [print("country(<<\"", l["cca2"], "\">>) -> country(<<\"", l["cca3"], "\">>);\ncountry(<<\"", l["cca3"], "\">>) -> #{a2 =>  <<\"", l["cca2"], "\">>, a3 => <<\"", l["cca3"], "\">>, itu => <<\"+", l["callingCode"][0], "\">>};", sep="") for l in sorted(json.load(open("dialcodes.json")), key=lambda l: l["cca2"]) if len(l["callingCode"]) > 0]' >>$(ISO3166)
+	@echo 'country(_) -> {error, invalid_country}.' >>$(ISO3166)
diff --git a/core/kazoo_number_manager/doc/knm_voxbone.md b/core/kazoo_number_manager/doc/knm_voxbone.md
@@ -0,0 +1,85 @@
+
+# knm_voxbone integration
+
+## Documentation
+* [voxbone Inventory API Reference](https://docs.voxbone.com/#/reference/inventory)
+* [voxbone Invetory Ordering API Reference](https://docs.voxbone.com/#/reference/ordering/get-update-or-delete-carts/list-number-inventory)
+
+## system_config
+#### Configuring number manager
+
+To enable kazoo number manager to use the voxbone module you will need to first update the `number_manager` document in the `system_config` database.
+
+In the configuration section that applies to your crossbar servers (or the default) add `"knm_voxbone"` to the `carrier_modules` parameter.
+
+For example:
+
+```json
+       "carrier_modules": [
+           "knm_local",
+           "knm_inventory",
+           "knm_managed",
+           "knm_reserved",
+           "knm_reserved_reseller"
+           "knm_voxbone"
+       ]
+```
+
+The voxbone integration requires making multiple requests to the customer portal so you experience search timeouts you may want to tune the `number_search_timeout_ms` value in `number_manager` document as well.
+
+```json
+    "number_search_timeout_ms": 10000,
+```
+
+### Configuring the voxbone module
+```json
+{
+    "default": {
+        "username": "{USERNAME}",
+        "password": "{PASSWORD}",
+        "api_key": "{API KEY}",
+        "environment": "production | sandbox | beta",
+        "page_size": 20
+    },
+    "pvt_type": "config",
+    "pvt_account_id": "system_config",
+    "pvt_account_db": "system_config"
+}
+```
+
+## Integration
+### Environments
+
+#### Production
+Interacts with the production Voxbone platform. Uses Basic Authentication.
+
+#### Sandbox
+Intended for simulating ordering and address verification specifically. You can test ordering without being charged and the sandbox resets and resyncs to your production data each night.
+
+#### Beta(Coming Soon)
+Intended for new and upcoming functionality on Voxbone platform. APIs coming soon are : Emergency Service Activation, Number Porting, real-time CDRs. These endpoints use key based authentication.
+
+
+#### URIs
+
+BaseURL = https://{ENVIRONMENT_URI}/ws-voxbone/services/rest/
+
+* Production - api.voxbone.com
+* Sandbox - sandbox.voxbone.com
+* Beta - beta.voxbone.com
+
+#### Sample Request
+
+```shell
+curl -u username:password -H "Content-type: application/json" -H "Accept: application/json" "https://api.voxbone.com/ws-voxbone/services/rest/inventory/country?countryCodeA3=BEL&pageNumber=0&pageSize=1"
+
+```
+
+
+### Error Codes
+#### HTTP Error Codes
+
+voxbone rate limits to 20 req/s by IP Address and will return one of the following codes on limit:
+
+* 509 - Bandwidth Exceeded
+* 429 - Too Many Requests
diff --git a/core/kazoo_number_manager/priv/fixtures/voxbone_account_balance.json b/core/kazoo_number_manager/priv/fixtures/voxbone_account_balance.json
@@ -0,0 +1,8 @@
+{
+    "accountBalance": {
+        "active": true,
+        "balance": 500.0,
+        "currency": "USD",
+        "threshold": 100.0
+    }
+}
diff --git a/core/kazoo_number_manager/priv/fixtures/voxbone_add_to_cart.json b/core/kazoo_number_manager/priv/fixtures/voxbone_add_to_cart.json
@@ -0,0 +1,3 @@
+{
+    "status": "SUCCESS"
+}
diff --git a/core/kazoo_number_manager/priv/fixtures/voxbone_cart_detail.json b/core/kazoo_number_manager/priv/fixtures/voxbone_cart_detail.json
@@ -0,0 +1,20 @@
+{
+    "carts": [
+        {
+            "cartIdentifier": 3312757,
+            "customerReference": "{ACCOUNT-ID}",
+            "dateAdded": "2019-07-22 17:16:37",
+            "description": "DID Order",
+            "orderProducts": [
+                {
+                    "didgroupId": 1196,
+                    "orderProductId": 4410885,
+                    "productDescription": "[UNITED STATES] BIRMINGHAM (205)",
+                    "productType": "DID",
+                    "quantity": 15
+                }
+            ]
+        }
+    ],
+    "resultCount": 1
+}
diff --git a/core/kazoo_number_manager/priv/fixtures/voxbone_checkout.json b/core/kazoo_number_manager/priv/fixtures/voxbone_checkout.json
@@ -0,0 +1,11 @@
+{
+    "productCheckoutList": [
+        {
+            "message": null,
+            "orderReference": "50898DS3919643",
+            "productType": "DID",
+            "status": "SUCCESS"
+        }
+    ],
+    "status": "SUCCESS"
+}
diff --git a/core/kazoo_number_manager/priv/fixtures/voxbone_delete_cart.json b/core/kazoo_number_manager/priv/fixtures/voxbone_delete_cart.json
@@ -0,0 +1,3 @@
+{
+    "status": "SUCCESS"
+}
diff --git a/core/kazoo_number_manager/priv/fixtures/voxbone_disconnect.json b/core/kazoo_number_manager/priv/fixtures/voxbone_disconnect.json
@@ -0,0 +1,3 @@
+{
+    "numberCancelled": 1
+}