juvet / juvet Goto Github PK

The MVC framework for chat apps built on a platform designed for communication systems.

THIS IS A WORK IN PROGRESS AND NOT READY FOR ANYTHING REAL YET

Build chat bot applications for the major chat bot application platforms using familiar model-view-controller architecture patterns that developers have been using for decades.

Juvet is an application framework that includes everything you need to build a chat application for all the major messaging platforms including:

• Slack RTM
• Slack Events API
• Slack Incoming Webhook (coming soon)
• Amazon Alexa
• Facebook Messenger
• Twillio SMS
• Custom...

Juvet offers all the features you need to build a scalable and maintainable chat application, including

• API Wrappers
• Message Queuing
• Middleware and Plugins
• Conversation Support
• NLP Support
• more to come...

The ROADMAP describes major upcoming features within each release.

This repository is available for sponsorship via GitHub Sponsors at https://github.com/sponsors/jwright.

If you or your company will benefit from a well-maintained and easy to use chat application framework, please consider a sponsorship. Your sponsorship will help with this development.

Thank you for the support! 💓

• Add the Juvet dependencies to your mix.exs file

# mix.exs

def deps do
  [{:juvet, "~> 0.0.1"}]
end

• Install the depedencies

mix deps.get

• Ensure Juvet is started before your application

# mix.exs

def application do
  [extra_applications: [:juvet]]
end

When Juvet starts, the following is what that process tree should look like.

                                            +------------------+     +-------------------+
                                            |                  |-----| ViewStateRegistry |
                                         +--| ViewStateManager |     +-------------------+
                                         |  |                  |     +---------------------+
                                         |  +------------------+-----| ViewStateSupervisor |
  +---------------+    +--------------+--+  +----------------+       +---------------------+
  |               |    |              |     |                |
  |     Juvet     |----|  BotFactory  |-----| Superintendent |
  | (application) |    |              |     |                |
  |               |    +--------------+--+  +----------------+
  +---------------+                      |  +-------------------+
                                         |  |                   |
                                         +--| FactorySupervisor |
                                            |                   |
                                            +-------------------+
                                             |                 |
                                             |                 |
                                      +---------------+ +---------------+
                                      |               | |               |
                                      | BotSupervisor | | BotSupervisor |
                                      |               | |               |
                                      +---------------+ +---------------+
                                               |                |
                                               |                |
                                            +-----+          +-----+
                                            | Bot |          | Bot |
                                            +-----+          +-----+

• Juvet - Application that starts the Juvet.BotFactory supervisor
• BotFactory - Supervisor that starts the Juvet.Superintendent and Juvet.ViewStateManager processes.
• ViewStateManager - Supervisor that can manage the storage of any arbitray piece of data for a given set of keys. Starts the Juvet.ViewStateRegistry and a dynamic supervisor for Juvet.ViewState processes.
• ViewStateRegistry - Server to act as a registry service to convert keys (as Tuples) into pids in order to identify Juvet.ViewState processes.
• Superintdendent - The brains of the operation. Process checks the validity of the configuration and if it is configured correctly, it starts the Juvet.Endpoint process and the Juvet.FactorySupervisor
• FactorySupervisor - Supervisor over all of the Juvet.BotSupervisor processes.
• BotSupervisor - Supervisor over one Juvet.Bot process as well as any additional supporting processes (like Juvet.Receivers.SlackRTMReceiver)
• Bot - Receives messages from the chat providers. It is responsible for processing messages and generating responses

You need to tell Juvet what bot module should be created when a new connection is made. You can do that with the following configuration.

# config/config.exs

config :juvet,
  bot: MyBot,
  slack: [
    actions_endpoint: "/slack/actions",
    commands_endpoint: "/slack/commands",
    events_endpoint: "/slack/events",
    options_load_endpoint: "/slack/options"
  ]

The client application that is using Juvet can use the router from your client application. You just need to mount the Juvet.Plug.

The router can be mounted inside the Phoenix endpoint by just adding:

# lib/my_phoenix_app_web/endpoint.ex

defmodule MyPhoenixAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_phoenix_app

  # ...

  plug Juvet.Plug
end

Currently Juvet does not perform any oauth functionality. That will be coming soon so it is up to your application to connect your app to Slack via OAuth. If you are using ueberauth, then ueberauth_slack is a good choice to get your users authorized with Slack.

Once your get the bot access token for your team, you are ready to go.

Once you have a bot access token for your team, you can connect to Slack via:

{:ok, bot} = Juvet.create_bot("MyBot")

You can handle messages from Slack by overriding the handle_event/3 function on your bot. This function can use pattern matching in order to handle various events from Slack.

defmodule MyBot do
  use Juvet.Bot

  def handle_event(platform, %{type: "message"} = message, state) do
    # Add your logic here on how to handle a message event

    {:ok, state}
  end

  def handle_event(platform, %{type: "file_created"} = message, state) do
    # Add your logic here on how to handle a file_created event

    {:ok, state}
  end
end

You can send messages back to Slack from your bot by overridding the send_message/3 function on your bot. The second argument (state) should contain an (id) key which will be used to send the message to the correct team.

defmodule MyBot do
  use Juvet.Bot

  def handle_event(platform, %{type: "message", text: "Hello"} = message, %{id: id, channel: channel} = state) do
    send_message(platform, state, %{type: "message", channel: channel, message: "Right back at cha!"})

    {:ok, state}
  end
end

You can run the tasks with the standard mix command:

mix test

You can re-record the responses from Slack with the following mix command:

MIX_ENV=test mix record token:<slack token here> channel:<slack channel id here> text:"<Welcome from Juvet!>" ts:<valid message timestamp here> user:<slack user id here> users:<slack user id here>,<another slack user id here>

You can record the casettes for just one method by adding a method parameter above (i.e. method:chat.update) and it will just re-record that one method.

You can create a Slack token for any of your teams by visiting the OAuth & Permissions area in your Slack API Apps.

1. Clone the repository git clone https://github.com/juvet/juvet
2. Create a feature branch git checkout -b my-awesome-feature
3. Codez!
4. Commit your changes (small commits please)
5. Push your new branch git push origin my-awesome-feature
6. Create a pull request hub pull-request -b juvet:main -h juvet:my-awesome-feature

Copyright (c) 2018, Jamie Wright.

Juvet source code is licensed under the MIT License.