station 0.0.0 → 0.0.93

data/lib/nexmo_developer/app/views/code_languages/_icon.html.erb

@@ -0,0 +1,11 @@
+<% if code_language %>
+  <% language = Nexmo::Markdown::CodeLanguage.find(code_language) %>
+  <% if language.label == 'Kotlin' %>
+    <img class="Vlt-gray-darker <%= local_assigns[:css_classes] %>" src="<%= "/assets/images/brands/#{language.icon}#{local_assigns[:dark] ? '-dark' : '-color'}.svg" %>"/>
+  <% else %>
+    <svg class="Vlt-icon Vlt-gray-darker <%= local_assigns[:css_classes] %>" >
+      <use xlink:href="<%= asset_pack_path("media/symbol/volta-brand-icons.svg")%><%="#Brand-icon-#{language.icon}" %>"></use>
+    </svg>
+  <% end %>
+  <span><%= language.label %></span>
+<% end %>

data/lib/nexmo_developer/app/views/contribute/administration/page-links.md

@@ -0,0 +1,179 @@
+---
+title: Page Links
+---
+
+# Page Link Reporting
+
+Nexmo Developer supports some reporting `rake` commands for showing links in to, and out from pages. This helps us visualise where our heavily linked pages are, and which pages we need to link to more. You can output the data as a table, plain text or as a Graphviz digraph.
+
+This information can be used to improve cross-linking between pages, or identify content that is isolated and potentially unused
+
+## Usage
+
+> [partial_url] can be any string e.g. /voice/voice-api and only
+matching source URLs will be returned. (`from` for _outbound and `to`
+for _inbound)
+
+* `rake links:report_outbound [partial_url]` - Generate a table containing
+a list of pages, and all pages that they link to
+
+* `rake links:report_inbound [partial_url]` - Generate a table containing
+a list of pages, and all pages that link to it
+
+* `rake links:no_links_outbound` - Show all pages with no outbound links
+
+* `rake links:no_links_inbound` - Show all pages with no inbound links
+
+* `rake links:graph_outbound [partial_url]` - Generate a Graphviz Digraph
+containing all pages that match [partial_url]
+
+* `rake links:graph_inbound [partial_url]` - Generate a Graphviz Digraph
+containing all pages that link to [partial_url]
+
+
+### Examples 
+
+#### Outbound links from urls containing `/voice/voice-api/guides`
+
+```
+$ bundle exec rake links:report_outbound /voice/voice-api/guides
+
++--------------------------------------------+--------------------------------------------------------------------+
+| From                                       | To                                                                 |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/legs-conversations | /voice/voice-api/guides/endpoints                                  |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/ncco               | /voice/voice-api/ncco-reference#record                             |
+|                                            | /voice/voice-api/ncco-reference#conversation                       |
+|                                            | /voice/voice-api/ncco-reference#connect                            |
+|                                            | /voice/voice-api/ncco-reference#talk                               |
+|                                            | /voice/voice-api/ncco-reference#stream                             |
+|                                            | /voice/voice-api/ncco-reference#input                              |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/lex-connector      | /voice/voice-api/guides/websockets                                 |
+|                                            | /voice/voice-api/guides/text-to-speech#voice-names                 |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/troubleshooting    |                                                                    |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/endpoints          |                                                                    |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/dtmf               | /voice/voice-api/ncco-reference#input                              |
+|                                            | /api/voice#createCall                                              |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/call-flow          | /voice/voice-api/ncco-reference                                    |
+|                                            | /voice/voice-api/webhook-reference#event-webhook                   |
+|                                            | /concepts/guides/webhooks                                          |
+|                                            | /voice/voice-api/guides/legs-conversations                         |
+|                                            | /voice/voice-api/webhook-reference                                 |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/recording          | /voice/voice-api/ncco-reference#conversation                       |
+|                                            | /voice/voice-api/ncco-reference#record                             |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/text-to-speech     | /api/voice#startTalk                                               |
+|                                            | /voice/voice-api/ncco-reference                                    |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/numbers            |                                                                    |
++--------------------------------------------+--------------------------------------------------------------------+
+| /voice/voice-api/guides/websockets         | /voice/voice-api/guides/ncco                                       |
+|                                            | /voice/voice-api/guides/call-flow#answer-url-payload               |
+|                                            | /voice/voice-api/code-snippets/play-an-audio-stream-into-a-call/ |
++--------------------------------------------+--------------------------------------------------------------------+
++--------------------------------------------+--------------------------------------------------------------------+
+
+```
+
+#### No outbound links from these pages
+```
+$ bundle exec rake links:no_links_outbound
+
+/messages/external-accounts/api-reference
+/messages/tutorials
+/messages/concepts/facebook
+/messages/concepts/viber
+/messages/concepts/whatsapp
+/messages/api-reference
+/messages/code-snippets/client-library
+/messages/code-snippets/create-an-application
+/messages/code-snippets/install-cli
+/verify/tutorials
+/verify/api-reference
+/dispatch/external-accounts/api-reference
+/dispatch/tutorials
+/dispatch/concepts/workflows
+/dispatch/api-reference
+/dispatch/code-snippets/client-library
+/dispatch/code-snippets/create-an-application
+/dispatch/code-snippets/install-cli
+/redact/api-reference
+/redact/code-snippets/redact-using-id
+/audit/tutorials
+/audit/api-reference
+/voice/sip/configure/freeswitch
+/voice/sip/configure/asterisk
+/voice/sip/configure/freepbx
+/voice/voice-api/tutorials
+/voice/voice-api/guides/troubleshooting
+/voice/voice-api/guides/endpoints
+/voice/voice-api/guides/numbers
+/voice/voice-api/api-reference
+/voice/voice-api/code-snippets/mute-a-call
+/voice/voice-api/code-snippets/play-text-to-speech-into-a-call
+/voice/voice-api/code-snippets/retrieve-info-for-a-call
+/voice/voice-api/code-snippets/earmuff-a-call
+/voice/voice-api/code-snippets/play-dtmf-into-a-call
+/voice/voice-api/code-snippets/play-an-audio-stream-into-a-call
+/voice/voice-api/code-snippets/transfer-a-call
+/voice/voice-api/code-snippets/retrieve-info-for-all-calls
+/stitch/concepts/mos
+/stitch/concepts/jwt-acl
+/stitch/in-app-voice/call-statuses
+/stitch/api-reference
+/account/secret-management/api-reference
+/account/secret-management/code-snippets/list-all-secrets
+/account/secret-management/code-snippets/revoke-a-secret
+/account/secret-management/code-snippets/create-a-secret
+/account/secret-management/code-snippets/fetch-a-secret
+/messaging/sms/tutorials
+/messaging/sms/guides/SMPP-access
+/messaging/sms/api-reference
+/number-insight/tutorials
+/number-insight/guides/cnam
+/number-insight/api-reference
+/conversation/tutorials
+/conversation/concepts/event
+/conversation/concepts/user
+/conversation/cli-reference
+/conversation/api-reference
+/conversation/code-snippets/member/get-member
+/conversation/code-snippets/member/create-member
+/conversation/code-snippets/member/update-member
+/conversation/code-snippets/member/list-members
+/conversation/code-snippets/member/delete-member
+/conversation/code-snippets/user/update-user
+/conversation/code-snippets/user/delete-user
+/conversation/code-snippets/user/get-user
+/conversation/code-snippets/user/list-user-conversations
+/conversation/code-snippets/user/list-users
+/conversation/code-snippets/user/create-user
+/conversation/code-snippets/leg/delete-leg
+/conversation/code-snippets/leg/list-legs
+/conversation/code-snippets/event/get-event
+/conversation/code-snippets/event/create-event
+/conversation/code-snippets/event/list-events
+/conversation/code-snippets/event/delete-event
+/conversation/code-snippets/conversation/list-conversations
+/conversation/code-snippets/conversation/update-conversation
+/conversation/code-snippets/conversation/get-conversation
+/conversation/code-snippets/conversation/delete-conversation
+
+```
+
+### Render Graphviz digraphs
+
+This example will render a digraph containing all outbound links from `/voice/voice-api/guides` as a file named `voice-graph.png`
+
+```
+bundle exec rake links:graph_outbound /voice/voice-api/guides > voice-graph
+dot -Tpng voice-graph > voice-graph.png
+```
+

data/lib/nexmo_developer/app/views/contribute/code-snippets/how-to-update-code-snippets.md

@@ -0,0 +1,89 @@
+---
+title: How to update code snippets
+description: This topic describes a method for updating code snippets in GitHub
+---
+
+# How to update code snippets
+
+## Introduction
+
+Updating code snippets and testing thoroughly can catch people out. You might end up with errors while trying to build NDP, or while running it locally. Here’s the procedure the tech writing team uses, which is not the only one, but it provides a good starting point for developing your own methods.
+
+> Remember: code snippet repos are in submodules as far as NDP is concerned. If you are not familiar with submodules it’s probably worth doing a little background reading on them first.
+
+This technique assumes you have NDP cloned locally, and you have checked out and updated all code snippet repo modules. At some point you should have run the following:
+
+```shell
+git submodule init && git submodule update
+git config --global submodule.recurse true
+```
+
+This intializes your submodules, updates them, and sets the Git global configuration.
+
+To a certain extent the procedure you use will depend on the type of change you are making to code snippets. With experience you will see various shortcuts. For example, changes to code snippets that do not change line numbers, generally do not require code snippet configuration to be changed, which simplifies the process.
+
+## Code snippet structure
+
+Code snippets have several parts to them:
+
+1. The actual code in the submodule repos (for example, https://github.com/Nexmo/nexmo-curl-code-snippets/blob/master/messages/messenger/send-text.sh)
+2. The documentation pages that contain the tabbed code snippets in different programming languages (for example, https://developer.nexmo.com/messages/code-snippets/messenger/send-text)
+3. The code snippet configuration (for example, `_examples/messages/messenger/send-text/curl.yml`)
+
+Code snippets are described in more detail [here](/contribute/structure/guides/code-snippets).
+
+## Updating code snippets
+
+The tech writing team usually recommends coding and testing the code snippet code separately from NDP. This usually means you check out the relevant code snippet repo in a separate directory structure. This allows you to have local data such as private key, local config and so on for an app you can use for testing this repo. You can then run your test scripts locally to make sure everything works. See [Curl code snippet repo](https://github.com/Nexmo/nexmo-curl-code-snippets) for a good example of this set up.
+
+1. Go to the code snippet repo directory and make your code changes in a branch. Test code changes locally.
+
+2. If everything is OK, push up the branch to create a PR. Request a review. While waiting for a review you can work on the NDP side of things. Remember, as your changes have not been merged yet they will not be visible in  NDP, so if, for example, you’ve deleted a code snippet, NDP won’t be affected.
+
+Here’s what some people do at this point - they merge their code snippet changes to master in the code snippet repo. If you deleted a code snippet or modified an existing one you just broke NDP - at least - those code snippet pages in NDP. The line number will be out, or worst case the code snippet has now gone completely. However, if you only added a code snippet you’re still good (although as yet the docs won't display it).
+
+## Automatic NDP PR creation
+
+If you added a new code snippet and merged it into master of the code snippet repo, an NDP PR will **automatically** be created for you at this point. This is because at the least, NDP will need to be updated to point to the latest master of the code snippet repo, not the previous commit.
+
+You won't always use the automated PR though. If you're only updating a single snippet or not affecting the display of snippets in NDP, it's a nice shortcut. **Usually, you want to make sure that all the required changes are in place before creating a PR to point NDP at the latest version of the code snippet submodule repos.** In that case, you can delete the automatic update PRs with a note saying that you'll be pushing under a separate PR. 
+
+If you're not ready for the Automated PR to be merged then flag it as 'Do not merge', or if you are not going to use it close with a suitable note.
+
+## NDP side of the code snippet
+
+Now, while waiting for a review of your code snippet code you can do the NDP part.
+
+1. Go to the root directory of your NDP clone.
+2. Checkout master branch, `git checkout master`.
+3. Do a `git pull` to update.
+4. Go to the sub-directory for the code snippets you’re working on. For example, `.repos/nexmo/nexmo-node-code-snippets` and `git checkout master` then `git pull`. This ensures the local code snippet repo is up to date.
+
+At this point everything local is master and up to date. You are now ready to make your changes to NDP.
+
+1. Create a new branch in NDP e.g. `tony-update-snips`.
+2. Checkout the new branch.
+3. Now you want to check out the branch with your code snippet repo changes (which are still in review). Go to `.repos/nexmo/nexmo-node-code-snippets`.
+4. Checkout the branch with your code snippet changes.
+5. Go back up to NDP directory and make the required changes to NDP, for example, add or update configuration for the code snippets (especially if line numbers have changed), add new stub pages and so on.
+6. Now run NDP locally and check your changes display correctly
+7. Do a `git status` to make sure you have only affected the desired files.
+8. You can now push up your branch to create a PR (and please do fill out the PR description).
+9. A review app will be built for you. Go into Heroku and check the review app displays as required. You can use your PR number to identify the correct review app.
+
+At this point you have tested your changes (both code snippet and NDP changes) but you’re not quite finished. Hopefully, by now your code snippet repo PR has been reviewed. If everything is good at this stage you can now merge these code snippet changes into the code snippet repo.
+
+But you still need to make one more change, and that is to align your NDP PR with the master of the code snippet repo:
+
+1. Back in NDP you need to change down into `.repos/nexmo/nexmo-node-code-snippets` and do a `git checkout master` and git pull to pull down the latest code snippet repo changes that just got merged.
+2. Running NDP locally, check that the affected code snippets display correctly. This is very important!
+3. Change back up into root of NDP and do `git status` - you will see your branch has changes that will need to be pushed up, due to the fact you are referencing the master of the code snippet repo.
+4. Commit with a message of something like ‘point at latest master’ and push.
+5. Let the new review app build.
+6. Check review app via Heroku.
+7. If everything looks good in the review app you can now get your PR reviewed and merged!
+8. You can now close any auto-generated NDP PR, as in this case you didn’t use it.
+
+## Summary
+
+There are many moving parts to code snippets with the added issue that the code is stored in submodules. The full process described above is not always required. For example, if you make a code change that does not affect the line numbering in your code snippet, then there are no changes required on the NDP side. If however, you delete a code snippet, or add a new code snippet, or the number of lines changes, then you'll need to reflect those code changes on NDP, otherwise the code snippet will not display correctly.

data/lib/nexmo_developer/app/views/contribute/code-snippets/sample-code-snippet.md

@@ -0,0 +1,42 @@
+---
+title: Quick howto on a simple thing
+navigation_weight: 5
+---
+
+# How to do this simple thing
+
+This section introduces what the code snippet does. Bear in mind a user could
+land here from a search result so we may need to add a little context, redefine
+abbreviations, or otherwise help them orient themselves.
+
+## Example
+
+Introduce the example, what are we about to do or see?
+
+Before diving into the code samples, define the placeholders used by the code samples that will follow.  These should follow our [guidelines for placeholders](/contribute/guides/code-examples#placeholders) used throughout Nexmo Developer.
+
+Key |	Description
+-- | --
+`NEXMO_NUMBER` | Nexmo Number to call.
+
+
+```code_snippets
+source: '_examples/concepts/sample-code-snippet'
+application:
+  name: 'Example Application'
+```
+
+Note the `application` section of the `building_blocks` construct is optional. If not used there will be no prerequisite section in the rendered block.
+
+## Try it out
+
+What did the user just build?  How should they use it?  Add the instructions
+for how to demo the masterpiece the user has just created.
+
+## Further reading
+
+Add resources for a user such as:
+
+* A tutorial where this technique is used.
+* Reference to either our own or external tools that might be handy.
+* A guide for a similar topic (especially if that guide links to this code snippet).

data/lib/nexmo_developer/app/views/contribute/guides/code-examples.md

@@ -0,0 +1,190 @@
+---
+title: Code Examples
+navigation_weight: 4
+---
+
+# Contributing Code Examples
+
+Nexmo Developer hosts many code examples, and endeavours to make them as consistent as possible. You should follow this guide when contributing code examples to the code snippets repositories or directly to Nexmo Developer.
+
+## Use the library
+
+If an existing Nexmo-supported API library supports the functionality, you should use that library for code samples.
+
+### Principle of Least Astonishment
+
+Code samples should match the expectations and experience of a median-level competent developer in a language and try hard to not surprise or confuse them. Code samples for APIs are not a place to use flashy, experimental or cutting-edge techniques, but to try to maximise compatibility, and reduce ambiguity.
+
+Code samples **MUST NOT** use any technique widely considered to be insecure, badly designed or likely to cause harm or confusion to the user.
+
+## Placeholders
+
+The following values should be used as placeholders in code examples. They can be specified assigned as constants out of the range of view of the rendered code to allow the code to be executed whist providing an obvious placeholders for the reader.
+
+Key | Description | User customisation (future)
+-- | -- | --
+`NEXMO_API_KEY` | The users Nexmo API Key | ✅
+`NEXMO_API_SECRET` | The users Nexmo API Key | ✅
+`NEXMO_NUMBER` | The virtual number that the user holds with Nexmo | ❓
+`TO_NUMBER` for outbound §§ `YOUR_NUMBER` for inbound | The number that the user owns or wants to communicate with | ❓
+`NEXMO_APPLICATION_PRIVATE_KEY` | Represents a string of the actual private key | ❎
+`NEXMO_APPLICATION_PRIVATE_KEY_PATH` | Represents a string that relates to the private key directory | ❎
+
+See also: [our replaceable values](/contribute/guides/writing-style-guide#replaceable-values) listed in the writing style guide.
+
+### Future auto-magical user customisation
+
+In the future we will customise code examples to the logged in user for example by adding API key and secret to the examples. To do this we need to be careful about how we use placeholders.
+
+#### ✅ Good
+
+{column:1/2}
+This input:
+
+```javascript
+const nexmo = new Nexmo({
+  apiKey: NEXMO_API_KEY,
+  apiSecret: NEXMO_API_SECRET
+})
+```
+{end}
+{column:2/2}
+Or this input:
+
+```javascript
+const nexmo = new Nexmo({
+  apiKey: 'NEXMO_API_KEY',
+  apiSecret: 'NEXMO_API_SECRET'
+})
+```
+{end}
+
+
+Would be converted to this into something like:
+
+```javascript
+const nexmo = new Nexmo({
+  apiKey: 'abc123',
+  apiSecret: 'abcdef123456789'
+})
+```
+
+#### ❎ Bad
+
+This input:
+
+```javascript
+NEXMO_API_KEY = process.env.NEXMO_API_KEY
+NEXMO_API_SECRET = process.env.NEXMO_API_SECRET
+
+// Something else
+```
+
+Would be converted to this invalid example:
+
+```javascript
+'abc123' =  process.env.'abc123'
+'abcdef123456789' = process.env.'abcdef123456789'
+
+// Something else
+```
+
+### SMS Specific
+
+#### Message Body
+
+```
+A test SMS sent [demonstrating <feature>] using  the Nexmo SMS API
+```
+
+#### SenderID
+
+```
+Acme Inc
+```
+
+### Webhooks
+
+The following URL paths should be used in examples that use Webhooks.
+
+Path | Description
+-- | --
+`/webhooks/answer` | The application `answer` event URL
+`/webhooks/event` | The application `event` event URL
+
+Example code should always accept query string parameters for `GET` and `POST` requests.
+
+Example code should always accept JSON for `POST` requests.
+
+### NCCO examples
+
+Below you can find static NCCO's that can be used in code examples. The source of these can be found in the `/public/ncco` directory of Nexmo Developer.
+
+Example | URL
+-- | --
+Basic text-to-speech | <https://developer.nexmo.com/ncco/tts.json>
+
+## Code
+
+### Length
+
+Where possible code should be kept to a maximum of 80 characters per-line.
+
+The capacity before scrolling occurs is 101 characters however not all code examples are as wide as this.
+
+```
+----------------------- I am a line with 80 characters ------------------------
+--------------------------------- I am a line with 101 characters ----------------------------------
+```
+
+### Code blocks
+
+Normal code blocks are specified using three backticks at the start and end.
+
+```
+This is a normal code block.
+
+It does not specify a language so is not syntax highlighted.
+```
+
+Here is some Ruby:
+
+```ruby
+def print_hi(name)
+  puts "Hi #{name}"
+end
+
+print_hi('Adam')
+#=> prints 'Hi Adam' to STDOUT.
+```
+
+### Tabbed examples
+
+Tabbed examples via the use of the `tabbed_examples` construct should no longer be used. Instead use [code snippets](/contribute/code-snippets/sample-code-snippet).
+
+> Note: There are two formats of the `tabbed_examples` construct in current use, both of which are now deprecated.
+
+### Linters, Formatters & Code Style Guides
+
+Code throughout Nexmo Developer should be consistent. To help achieve this code examples should be tested with the following tools and against guides on their default configuration:
+
+Language | Resource | Configuration
+-- | -- | --
+Node | [Standard JS](https://standardjs.com/) | Non configurable
+Java | - | -
+.NET | - | -
+PHP | [PHPCS](https://github.com/squizlabs/PHP_CodeSniffer#installation) | [PSR-2](https://github.com/Nexmo/nexmo-php/blob/master/phpcs.xml)
+Python | [YAPF](https://github.com/google/yapf) | Default
+Ruby| [Rubocop](https://github.com/bbatsov/rubocop) | Default
+
+### Languages
+
+#### JavaScript
+
+Documentation should be clear whether JavaScript code is intended to run on the server (using, say, node.js), the client, or both.
+
+#### Python
+
+Avoid code that is significantly different in Python 2 and 3. When this is unavoidable, abstract away the incompatible code to the smallest area possible and use [`__future__`](https://docs.python.org/2/library/__future__.html) to ensure backwards compatibility with Python 2.
+
+Inbound HTTP calls should use a WSGI-compatible web framework, preferably the [Flask](http://flask.pocoo.org/) micro-framework. Explanations of how to integrate Nexmo APIs with [Django](https://www.djangoproject.com/) are sensible too.