Pine Notification Service

REST API to send push notifications to Pine users.

Table of Contents

• Dependencies
• Getting started
• API documentation
  • Endpoints
  • Authentication
    • Obtaining an API key
    • Authenticating
  • Error handling
  • Notification types
  • Rate limiting
• Contributing
• Licensing

Dependencies

• Node.js and Restify for creating the REST API
• APN for sending push notifications to iOS devices

Getting started

1. Clone this repo:

   $ git clone https://github.com/blockfirm/pine-notification-service.git
   $ cd pine-notification-service
   

2. Install dependencies:

   $ npm install
   

3. Rename src/config.template.js to src/config.js

4. Create a new key in your Apple Developer account to be used with the Apple Push Notifications Service

5. Open src/config.js

6. Enter your key credentials (key path, key ID, and team ID) in apn.token

7. Enter your app's bundle ID in apn.bundleId

8. Generate a key pair for authentication:

   $ mkdir certs
   $ ssh-keygen -t rsa -b 4096 -m PEM -f certs/private.key
   $ openssl rsa -in certs/private.key -pubout -outform PEM -out certs/public.key
   

   Note: Only the public key should be deployed to the server.

9. Create a log directory:

   $ mkdir /var/log/pine
   

10. Start the API server in development mode:

    $ npm run dev
    

11. Or build it and run in production mode:

    $ npm run build
    $ npm start
    

API documentation

Endpoints

Endpoints for retrieving and submitting information to the bitcoin blockchain and network.

Method	Endpoint	Description
GET	/v1/info	Get information about the server
POST	/v1/notifications	Send a push notification

GET /v1/info

Returns information about the server.

Returns

{
  "ok": true (boolean) Indicates that the server is up and running (used for monitoring purposes)
}

POST /v1/notifications

Sends a push notification to an iOS device using the specified device token.

Body

Encoded as JSON.

Name	Type	Description
deviceToken	string	Device token to send the notification to
type	string	Type of notification to send. See Notification types
context	object	Optional. Context to use when rendering the message (see src/config.js)

Returns

The response from apn.Provider#send().

Example of a successful response:

{
    "sent": [
        {
            "device": "<device-token>"
        }
    ],
    "failed": []
}

Example of an unsuccessful response:

{
    "sent": [],
    "failed": [
        {
            "device": "<bad-device-token>",
            "status": "400",
            "response": {
                "reason": "BadDeviceToken"
            }
        }
    ]
}

Authentication

Obtaining an API key

Generate a new API key by using the private key of the public key that has been deployed on the server.

$ node scripts/cli generate-key <domain> <private-key>

domain: Domain name of the server that will use the API key
private-key: Path to private key to use for generating the API key

Authenticating

When requesting the API, authenticate using the Authorization header:

Authorization: Bearer <key-secret>

key-secret: The API key that was generated using the instructions above

Error handling

Errors are returned as JSON in the following format:

{
    "code": "<error code>",
    "message": "<error message>"
}

Notification types

Only a predefined set of notifications can be sent. The following notification types are supported at the moment:

Type	Title	Message	Variables
incomingPayment	$address	sent you a payment	address
contactRequest	$address	wants to add you as a contact	address
contactRequestAccepted	$address	accepted your contact request	address
channelOpened	Pine	Pine is now ready to be used with Lightning	N/A

Rate limiting

The API is rate limited to 1 request per second with bursts up to 5 requests. The rate limiting is based on the Token Bucket algorithm and can be configured in src/config.js at api.rateLimit.

The limit is per IP number, so if your server is behind a reverse proxy or similar you must change the config to rate limit by the X-Forwarded-For header instead of the actual IP:

rateLimit: {
  ...
  ip: false,
  xff: true
  ...
}

Contributing

Want to help us making Pine better? Great, but first read the CONTRIBUTING.md file for instructions.

Licensing

Pine is licensed under the Apache License, Version 2.0. See LICENSE for full license text.