Nocks SDK Node
Nocks Node SDK is a node package arround the Nocks API. It can be used in any (>=7.0.0
) Node environment and, because it doesn't use any core Node JS modules
, it is also compatible with a browser environment, so it can, for example, be used in React(-native).
Installation
Installation requires no more than just a simple install of the npm package with npm
(or yarn
):
npm install nocks-sdk-node --save
Getting Started
The SDK
supports both the calls to the Nocks api
endpoints (api context
) as well to the oauth
endpoints (oauth context
). All oauth
calls can directly be used from the oauth context
. The api
calls are divided at resource level
in the api context
(e.g. api.user.findAuthenticated
).
Each call will return a javascript native promise, which is resolved with the result or rejected with an error. With an exception of the getOauthUri
call in the oauth
context, this will return the result directly (or throw an error) instead of a promise.
For the most calls authentication is required. Checkout the docs to see what is required for every call.
Oauth
The oauth
context provides the following methods:
- getOauthUri (
will not return a promise
) - requestToken
- refreshToken
- passwordGrantToken
- scopes
- tokenScopes
Example
// es6; const oauth = NocksOauth; // Use the oauth methods. For more, check examplesconst oauthUri = oauth; // At Nocks oauth redirectconst code = 'code_from_nocks_oauth_redirect'; return oauth ;
Please checkout the oauth docs and examples to see how the oauth
methods can be used.
API
The api
context provides all the Nocks
resources. Please checkout the resources docs and examples.
// es6; const api = NocksApi; // Use the api methods. For more, check examplesreturn apiuser ;
Request/Response Transformers
The SDK uses transformers
to transform the requests
to the api
and the responses
from the api
. This means that there is not always a 1-1 mapping between the api
and the sdk
. Most of the time there is, but there are some exceptions:
Data property
A typical
response from the api
looks like the following:
"data": ... // or "data": [...] "status": 200
However the promise
returned from a call with the SDK
will only resolve the data
part or the data
and pagination
part. See examples and pagination.
Also the data
property is removed in nested
resources. For example a transaction
with payments
looks like:
... "payments": ... // instead of "payments": { "data": [{...}] }
Date
A date
in a api response
is auto converted to a javascript date
(or to null
).
The SDK
makes it also possible to use a javascript date
while making a request
to the api
. The SDK
will then convert the provided date to a string
that is accepted by the api
.
Note that the Nocks api dates are always UTC +2, the SDK will auto convert the provided dates to UTC +2 with date.getTimezoneOffset()
Numbers
A number
returned from the API
is auto converted to a javascript number
.
Money is handled a bit different. In money
objects the SDK will add an additional value
property which holds the number
representation of the amount
in responses. When making a request, the value
property can also be used, the SDK will then set the amount
based on the value
property.
"amount": "amount": "250" // Can be omitted when doing a request "currency": "NLG" "value": 250
Additional properties
To some responses
the SDK will add additional properties for convenient. For example a merchant
response will have a method findInvoices
to retreive all the invoices for that merchant
.
In each example the additional propterties
are listed.
Pagination
For all get
endpoints that may return a list of results the api
uses pagination. These calls in the SDK (typically the .find
methods) return an object with the properties pagination
and data
. Where the data
property is the result array
and the pagination
property is an object
with the pagination info. An example of a pagination
object:
"total": 56 "count": 25 "per_page": 25 "current_page": 1 "total_pages": 3 "links": "next": "https://api.nocks.com/api/v2/transaction?page=2" // Additional helper functions boolean boolean integer integer
Example call with pagination
:
// es6; const api = NocksApi; return apitransaction ;
Errors
The SDK uses two types of errors: ConfigurationError
and ValidationError
. (These types can be imported from nocks-sdk-node/errors
).
// es6;
Configuration Errors
A ConfigurationError
may occur when calling .context
or doing any other call inside the oauth
or api
context. The ConfigurationError
simply means that there is something wrong with your .context
configuration. Each ConfigurationError
will have a clear message with what is wrong.
Validation Errors
A ValidationError
will occur when trying to make a call to Nocks
but there is something wrong with the parameters you provided to the method call. Each ValidationError
will have a clear message with what is wrong.
Note that the SDK doesn't check your request data that is send to the api, if there is something wrong with your data the api call will be rejected with a js error
Response Errors
When a call to Nocks
fails the promise will be rejected with a regular js error. This error may contain a status
and a code
property. For example:
"status": 400 "message": "An error occurred" "code": 400
Examples
In the examples directory you will find examples for each call that is supported in this SDK.
Support
Need help or support? Please check https://www.nocks.com/support.
Found a bug? Please check the existing GitHub issues and open a new issue if necessary. Or even better, create a pull request to directly resolve the issue you have found!