npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

assistant

v0.1.1

Published

A bot to assist with day-to-day operations

Downloads

12

Readme

Hello there

Assistant

A bot to assist with day-to-day operations

This is a self-hosted bot service similar to Hubot (except it's not written in coffeescript!) that executes arbitrary commands to perform certain actions with a variety of adapters to allow it to run on any platform, simultaneously.

Why?

Hubot is great. The concept of knocking together a quick script to perform simple tasks, perfect! But Hubot is not. Ignoring the coffeescript source (because when did we start labelling a project as "bad" because of the source language?) it can't function across multiple adapters, and in order to get around this problem you are forced to run multiple Hubot processes per adapter. That's where Assistant comes in.

Installation

$ npm install --save assistant

The default installation doesn't come with any adapters but it does come with a selection of scripts to help you test your bot, and hey who doesn't love an automated service that replies to your "Hello" :wink:

Usage

Most of the configuration for the Assistant can be in your package.json file, although you can specify additional config files as you see fit. A typical package.json file would look like:

{
  "name": "Baymax",
  "version": "0.1.0",
  "description": "Your personal healthcare companion",
  "private": true,
  "scripts": {
    "start": "assistant-server"
  },
  "dependencies": {
    "assistant": "^0.1.0"
  },
  "assistant-adapters": {
    "telegram": "assistant-adapter-telegram"
  },
  "assistant-config": {
    "adapters": {
      "telegram": {
        "token": "1926482dcb7fac2585775a65a7b98611ed969af"
      }
    },
    "http": {
      "hostname": "0.0.0.0",
      "port": 4000
    }
  }
}

And to boot the server you would use:

$ npm start

That just boots an empty bot. Now we can add some adapters and start plugging your bot into your services!

Adapters

To add adapters, install the relevant adapter and add it to your package.json file under assistant-adapters:

{
  "assistant-adapters": {
    "telegram": "assistant-adapter-telegram"
  },
  "assistant-config": {
    "adapters": {
      "telegram": {
        "token": "1926482dcb7fac2585775a65a7b98611ed969af"
      }
    }
  }
}

Configuration for adapters goes under assistant-config.adapters, and the key should match the key in the assistant-adapters. Assistant doesn't come bundled with any adapters, so you need to install enough adapters to suit each of your service. For now I've written two, one for Telegram and one for a shell, although I plan to make one for various Slack interactions very soon!

Known Adapters

If you're interested in writing your own services interaction, check out the Adapters wiki page.

Scripts

Now onto the cool stuff! Scripts are individual files that you use to give power to your bot! All you have to do is register listeners to your assistant based on regular expressions (just like Hubot - if it isn't broken don't fix it). To demonstrate, here's the hello.js script that's included with Assistant:

module.exports = function (assistant) {
  var hellos = [
    'Well hello there, NAME',
    'Hey NAME, hello!',
    'Whaddup NAME',
    'Good day, NAME',
    'How\'s it going, NAME',
    'How can I help, NAME?'
  ];

  var mornings = [
    'Good morning, NAME!',
    'Good morning to you too, NAME!',
    'Good day, NAME',
    'Good \'aye, NAME'
  ];

  assistant.hear(/(^hello|good( [d'])?ay(e)?)/i, function (message) {
    message.reply(message.random(hellos).replace('NAME', message.author.name));
  });

  assistant.hear(/(^(good )?m(a|o)rnin(g)?)/i, function (message) {
    message.reply(message.random(mornings).replace('NAME', message.author.name));
  });
};

This script demonstrates some of the features of the assistant:

  • Attach functions to listeners based on regular expressions
  • Functions take a single (message) argument for synchronous functions, and two arguments (message, callback) for asynchronous functions.
  • Because regular expressions, there may be a chance your function will run with other listeners, so be wary :wink:
  • For ease of variance, each message has a random function that will return a random element from an array of responses, so you can make your assistant sound more life-like!

Messages have the following properties:

{
  name: 'The name of the Assistant, defaults to {name} from package.json',
  identifier: 'An identifier for this bot, defaults to {name-version} from package.json',
  environment: 'The Node-JS environment, in lowercase',

  // The author object comes from the adapter, detailing who this person is
  // At a minimum, an ID and a Name is present. More properties may be present depending on the adapter, but always
  //   have some defaults at the ready!
  author: {
    id: 'some-unique-id',
    name: 'Some Relevant Name'
  },

  // A source object detailing the original request that hit the adapter
  source: {
    name: 'Telegram',
    slug: 'telegram',
    update_id: 1232942,
    message: { '...': '...' }
  },

  // The raw message from the adapter
  message: req.message.message,

  // An array of matches returned from `regex.exec` so you can capture input for your script
  matches: [ 'hello', 'hello', undefined, undefined, index: 0, input: 'hello' ],

  // Adds each string argument to the immediate response
  reply: function reply(string[, string[, ...]]) { },
  // For delayed responses, you can call `adapter.send` directly (aliased as `message.send`)
  send: function send(messages, callback) { }
}

Questions