Numerous Pulsating Martians

    @nearform/commentami-backend-hapi-plugin

    1.0.7 • Public • Published

    @nearform/commentami-backend-hapi-plugin

    @nearform/commentami-backend-hapi-plugin is a plugin to add the commentami REST API and (if specified) Websockets to a Hapi (17+) server. It relies on the @nearform/commentami-backend-core module.

    Install

    To install via npm:

    npm install @nearform/commentami-backend-hapi-plugin
    

    Usage

    @nearform/commentami-backend-hapi-plugin has some options you can specifiy to customize it

    options.pg [optional]

    It should contain an object with the postgres connection parameters.

    options.pg = {
      host: '127.0.0.1',
      port: 9876
    }

    Any parameter in this object will override whatever comes from @nearform/commentami-backend-core config.pg.

    options.routes [optional]

    Through the routes option you can configure @nearform/commentami-backend-hapi-plugin to have it's routes protected behind an authentication strategy and add the cors handling by Hapi:

    options.routes = {
      cors: true,
      auth: 'myauth'
    }

    If you want @nearform/commentami-backend-hapi-plugin to populate the author field when adding a comment, you can provide the following function:

    options.routes = {
      auth: 'myauth',
      getUserFromRequest: async (request, payload) => {
        // ...
        return user
      }
    }

    The getUserFromRequest function will need to return a promise that will yield either null or an object with the property username (ie : { username: 'test', ... }). We will store that username value as the author identifier. Beware that author will be stored as a string.

    options.hooks [optional]

    It should contain the hooks to decorate a single comment, a list of comments or the involved users when fetched from the database.

    An example could be adding users data to each comment based on its author or populating the users data when loading all the users involved in a discusssion.

    options.hooks = {
      fetchedComment: async (comment) => {
        // ... fetch user data
     
        return augmentedComment
      },
      fetchedComments: async (comments) => {
        // ... fetch users data
     
        return augmentedComments
      },
      involvedUsers: [async] users => {
        // add your data to the involved users ...
        return users
      }
    }

    Note: A user will be always represented as an object { username: '...' }.

    options.multines [optional]

    By default the server will start with only the http endpoints available. If you also want to interact through websocket you should provide a multines option.

    The option should be an object with the following format

    multines: {
      type: 'redis', // only "redis" or "mongo"
     
      // specific configurations for redis/mongo
      host: '127.0.0.1',
      port: 6379
    }

    Note: if you pass options.multines = {} the websockets will be active but the pub/sub system will work only for the single server and not between multiple servers.

    options.nes [optional]

    If you want to customize the nes plugin you can pass its options through options.nes.

    An example of what you may want to do is settig up nes to use an authentication strategy that you have already added to you server

    nes: {
      auth: {
        type: 'token',
        route: 'myauth'
      }
    }

    options.resolvers.resolveUrl [optional]

    The commentami library requires the url of a resource to build the deeplink. A resultUrl(comment) should be provided if you want to use the deep link functionality.

    options.resolvers = {
      resolveUrl: async (comment) => {
        // resource = comment.resource
        // ... resolve the page that contains the specific resource
     
        return baseUrl
      }
    }

    Events

    Under the hood @nearform/commentami-backend-hapi-plugin add a commentsService object to both server and request.

    If you need to be notified when a comment is added, deleted or updated you can use this object to add your listeners.

    server.commentsService.on('add', (comment) => { /*...*/ })
    server.commentsService.on('update', (comment) => { /*...*/ })
    server.commentsService.on('delete', (comment) => { /*...*/ })

    All together

    An example on how to install the plugin with all the options and events listeners:

    const main = async function() {
      const server = require('hapi').Server({ host: 'localhost', port: 80 })
     
      const options = {
        hooks: {
          fetchedComment: async comment => {
            // ...
            return augmentedComment
          },
          fetchedComments: async comments => {
            //...
            return augmentedComments
          },
          involvedUsers: async users => {
            // add your data to the involved users ...
            return users
          }
        },
        pg: {
          host: '127.0.0.1',
          port: 5432
        },
        multines: {
          type: 'redis',
          host: '127.0.0.1',
          port: 6379
        },
        nes: {
          auth: {
            type: 'token',
            route: 'myauth'
          }
        },
        routes: {
          auth: 'myauth',
          getUserFromRequest: async (request, payload) => {
            // ...
            return user
          }
        },
        resolvers: {
          resolveUrl: async (comment) => {
            // ...
            return baseUrl
          }
        }
      }
     
      await server.register([
        {
          plugin: require('@nearform/commentami-backend-hapi-plugin', options)
        }
      ])
     
      server.commentsService.on('add', comment => {
        /* send sms */
      })
      server.commentsService.on('add', comment => {
        /* send email */
      })
      server.commentsService.on('delete', comment => {
        /* store deleted comments somewhere else */
      })
      server.commentsService.on('update', comment => {
        /* log the updated comment somewhere */
      })
     
      await server.start()
      logMessage(`Server running at: ${server.info.uri}`)
    }
     
    main().catch(console.error)

    HTTP APIs

    The plugin mounts the following endpoints

    GET /comments-references/{resource*}

    This endpoint will return the list of references linked to a resource.

    GET /comments-references/some-resource
    
    {
      resource: `some-resource`,
      references: [ 'ref1', 'ref2', ... ]
    }
    

    GET /comments?resource={resource}[&reference={reference}][&limit={limit}][&offset={offset}]

    This endpoint will return a paginated list of comments relative to a resource (this parameter is required) and a reference (when specified)

    GET /comments?resource=some-resource
    
    {
      comments: [ ... ],
      total: 10,
      limit: 100
      offset: 0
    }
    

    The list is paginated based on limit (default 100) and offset (default 0) parameters.

    GET /comments{id}

    This endpoint will return a single comment

    GET /comments/1234
    
    {
      id: 1234,
      resource: 'some-resource',
      reference: 'some-reference',
      content: 'some content',
      author: { username: 'author' },
      mentions: []
      createdAt: 2018-05-31T08:01:25.296Z
    }
    

    The list is paginated based on limit (default 100) and offset (default 0) parameters.

    POST /comments

    This endpoint will create a new comment.

    The body of the request is as follow and all parameters but author are required

    POST /comments
    
    {
      resource: 'some-resource',
      reference: 'some-reference',
      content: 'some content',
      author: { username: 'author' }
    }
    

    PUT /comments/{id}

    This endpoint will update the content of a comment

    POST /comments/{id}
    
    {
      content: 'some new content'
    }
    

    DELETE /comments/{id}

    This endpoint will delete a comment

    POST /comments/{id}
    

    Websockets

    If you enabled multines on the server (see options) you will be able to use a nes client to communicate with it through websocket.

    A nes client will map all the server HTTP API enpoints

    client = new Nes.Client('ws://<my-server>')
    await client.connect()
    const response = await client.request(`/comments-references/${this.resource}`) // list comments
     
    // or
     
    const response = await client.request({ // create a new comment
      method: 'POST',
      path: `/comments`,
      payload: {
        resource: 'URL',
        reference: 'UUID',
        content: 'MESSAGE'
      }
    })

    Subscriptions

    Resource and reference

    When a comment is added/updated/deleted, clients subscribed to receive updates on its resource and optionally reference will be notified.

    client = new Nes.Client('ws://127.0.0.1:8281')
    await client.connect()
     
    await client.subscribe(`/resources/some-resource`, (event) => {
      // do something
    })
     
    await client.subscribe(`/resources-reference/some-reference/some-resource`, (event) => {
      // do something
    })

    The event object will have the following format

    {
      comment: {
        id: 1234,
        resource: 'URL',
        reference: 'UUID',
        content: 'MESSAGE',
        author: { username: 'AUTHOR' },
        createdAt: 2018-05-31T08:01:25.296Z,
        mentions: []
      },
      action: 'add'
    }

    The action property can have one of the following values: add, delete or update.

    Users

    If a user is involved in the discussion (posted a comment on the same resource/reference) it will be notified of new comments posted on the same resource/reference. If a user is mentioned (@<username>) in a comment content, it will be notified.

    If the plugin has been configured with the resolveUrl function, the notification objects will also have a url paramenter with the deep link to the comment.

    client = new Nes.Client('ws://127.0.0.1:8281')
    await client.connect()
     
    await client.subscribe(`/users/some-username`, (event) => {
      // do something
    })

    The event object will have the following format

    {
      comment: {
        id: 1234,
        resource: 'RESOURCE-ID',
        reference: 'UUID',
        content: 'MESSAGE',
        author: { username: 'AUTHOR' },
        createdAt: 2018-05-31T08:01:25.296Z,
        mentions: []
      },
      action: 'mention',
      url: 'http://someurl.com/the-path-to-the-resource?resource=RESOURCE-ID&reference=UUID&comment=1234'
    }

    The action property can have one of the following values: mention, involve.

    Development

    Run tests

    You will need a postgres server up and running.

    To create the db needed for the tests you can use the following command

    npm run pg:test:init
    

    and the run

    npm test
    

    To run a single test you can use the following command

    npx lab <test/to/run.js> // (ie: npx lab test/index.test.js)
    

    License

    Copyright nearForm Ltd 2018. Licensed under Apache 2.0 license.

    Keywords

    none

    Install

    npm i @nearform/commentami-backend-hapi-plugin

    DownloadsWeekly Downloads

    2

    Version

    1.0.7

    License

    Apache-2.0

    Unpacked Size

    55.1 kB

    Total Files

    16

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar