nexmo / server-sdk-specification Goto Github PK

5.0 5.0 6.0 153 KB

Nexmo Client Library Guide

server-sdk-specification's Introduction

Vonage Server SDK for Node.js

This is the Node.JS Server SDK for Vonage APIs. To use it you will need a Vonage account. Sign up for free at vonage.com.

For full API documentation refer to developer.vonage.com.

Installation
Constructor
Promises
Testing
Examples
References

Installation

With NPM

npm install @vonage/server-sdk

With Yarn

yarn add @vonage/server-sdk

Constructor

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage(credentials, options);

Where credentials is any option from @vonage/auth, and options is any option from @vonage/server-client

Promises

Most methods that interact with the Vonage API uses Promises. You can either resolve these yourself, or use await to wait for a response.

const resp = await vonage.sms.send({
    to: '15552220000',
    from: '15559992222',
    text: 'This is a test',
});

Testing

Run:

npm run test

Or to continually watch and run tests as you change the code:

npm run test-watch

Examples

See the Vonage Node Quickstarts repo.

References

You can find more information for each product below:

Supported APIs

The following is a list of Vonage APIs and whether the Node Server SDK provides support for them:

API	API Release Status	Supported?
Account API	General Availability	✅
Alerts API	General Availability	✅
Application API	General Availability	✅
Audit API	Beta	✅
Conversation API	Beta	❌
Dispatch API	Beta	❌
External Accounts API	Beta	❌
Media API	Beta	❌
Messages API	Beta	✅
Number Insight V2 API	Beta	✅
Number Insights API	General Availability	✅
Number Management API	General Availability	✅
Pricing API	General Availability	✅
Proactive Connect API	Beta	✅
Redact API	Developer Preview	✅
Reports API	Beta	❌
SMS API	General Availability	✅
Sub Accounts	Beta	✅
Users	General Availability	✅
Verify API	General Availability	✅
Verify v2 API	General Availability	✅
Video API	General Availability	✅
Voice API	General Availability	✅

V2 Migrations

While most of the V2 functions have been ported into their own package, some of the functions have not been ported or were removed. Below is a list of those changes:

V2 Function	Status	Note
`vonage.conversion`	REMOVED
`vonage.conversation`	Not Implemented	This was only released as a beta package
`vonage.app`	Moved	Moved to Applications
`vonage.files`	Moved	Move to ServerClient
`vonage.message`	Moved	Moved to SMS
`vonage.generateJwt`	Moved	Was moved to JWT
`vonage.generateSignature`	Moved	Was moved to SMS and Voice
`vonage.calls`	Moved	Was moved to Voice
`vonage.credentials`	Updated	Options can be found in Server Client
`vonage.options`	Updated	Options can be found in Server Client
`vonage.options.httpClient`	Removed
`vonage.options.userAgent`	Moved	Options can be found in Server Client

For more information, check out each packages migration guide.

server-sdk-specification's People

Contributors

Stargazers

Watchers

Forkers

pvela tatky tjlytle superdiana alphacentauri82

server-sdk-specification's Issues

Add proxy support requirement to spec

I've seen this so many times in support and via GitHub requests that making it very clear how to set up a proxy is an essential requirement. We should have a "How to set a Proxy" in the README too.

I'd generally make it part of the initialization for the library. If you can pass in custom HTTP clients then I'd have a standard interface that all custom clients must implement which includes setting a proxy.

Document the correct encoding to use based on what is supported by the API

Encoding on client library requirement should be documented based on the functionality of API. This is to ensure all characters in the text are sent successfully like for ex accented characters, extended characters from GSM Spec and unicode characters.

Is this universal for all entities like sms, voice etc.

Does nexmo API support unicode characters? If yes should the client library encode them in certain characterset? My assumption is to encode all text by UTF-8 only if the incoming text do not contain unicode characters - needs confirmation from the core eng team.

Add details for file downloading via /v1/files to specification

See https://github.com/Nexmo/nexmo-node/issues/85

Should transfer the error message and error code returned by the API

Error response from API’s be translated to language specific error objects with same error codes and messages sent by API

[Discuss] It should be possible to append additional information to the user agent

If a library uses a Nexmo client library it should be possible for that client to add additional information to the library user agent.

e.g. if the library user agent is nexmo-node/1.0.0/5.0 it should be possible to append information to that. For the Nexmo Command Line interface 1.0 release this may result in the user agent being nexmo-node/1.0.0/5.0/nexmo-cli/1.0.0.

Related: Nexmo/nexmo-cli#38

User-Agent: nexmo-dotnet/1.0 dotnet/1.0

I ran into this because .NET parses and validates the user-agent string before adding it to the request. It will not allow the string as required in the Nexmo client-library-specification.

Add logging to specification

Essential logging for me are:

The raw request going from the library to the Nexmo API
The raw response coming back from the Nexmo API

These can be invaluable when debugging or when handling support queries.

Code of conduct template

Any thoughts on adopting a code of conduct for all the libraries?

Examples: http://contributor-covenant.org

Update specification to state libraries should support full JSON structures when generating JWTs

It should be possible to generate a JWT with numerous and nested claims e.g.

{
  "application_id": "dfsdf-sdfsd-sdf-sdfs-dfsfd-dfsdsd",
  "nbf": 1483315200,
  "exp": 1514764800,
  "iat": 1483228800,
  "acl": {
    "paths": {
      "/messages": {
        "methods": ["POST"],
        "filters": {
          "from": "55555555555"
        }
      }
    }
  }
}

Please also note that application_id may not always be a claim.