{"id":13879814,"url":"https://github.com/fnando/boppers","last_synced_at":"2025-04-17T00:50:35.832Z","repository":{"id":66031414,"uuid":"109628209","full_name":"fnando/boppers","owner":"fnando","description":"A simple bot framework for individuals.","archived":false,"fork":false,"pushed_at":"2022-12-30T08:31:36.000Z","size":226,"stargazers_count":29,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T05:51:12.482Z","etag":null,"topics":["boppers","bot","bot-framework","bots","notifications"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fnando.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-06T00:20:55.000Z","updated_at":"2023-02-24T18:21:57.000Z","dependencies_parsed_at":"2023-04-27T20:15:46.584Z","dependency_job_id":null,"html_url":"https://github.com/fnando/boppers","commit_stats":{"total_commits":31,"total_committers":2,"mean_commits":15.5,"dds":"0.19354838709677424","last_synced_commit":"35601f418fea9e7f6eedce5167b9572d21f4a14c"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fboppers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fboppers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fboppers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fboppers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fnando","download_url":"https://codeload.github.com/fnando/boppers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249294743,"owners_count":21245993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boppers","bot","bot-framework","bots","notifications"],"created_at":"2024-08-06T08:02:34.329Z","updated_at":"2025-04-17T00:50:35.815Z","avatar_url":"https://github.com/fnando.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"![Boppers](https://github.com/fnando/boppers/raw/main/images/logo.png)\n\n[![Gem](https://img.shields.io/gem/v/boppers.svg)](https://rubygems.org/gems/boppers)\n[![Gem](https://img.shields.io/gem/dt/boppers.svg)](https://rubygems.org/gems/boppers)\n\n# Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"boppers\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install boppers\n\n# Usage\n\n## Using the CLI\n\nTo create a new app, use `boppers app [YOUR APP NAME]`. This will generate a\nstructure so you can just configure your boppers and notifiers.\n\n## Boppers\n\nA bopper is a bot. Basically is a class that responds to `#call`. For instance,\na lambda.\n\n```ruby\nBoppers.configure do |config|\n  config.boppers \u003c\u003c lambda do\n    Boppers.notify(:clock, title: \"Clock\", message: \"Now is #{Time.now}\")\n  end\nend\n```\n\nBy default, boppers are executed every 60 seconds. If you create a class, you\ncan define your custom interval by creating a method `#interval`. The following\nexample changes the interval to `15 seconds`.\n\n```ruby\nclass Clock\n  def call\n    Boppers.notify(:clock, title: \"Clock\", message: \"Now is #{Time.now}\")\n  end\n\n  def interval\n    15\n  end\nend\n\nBoppers.configure do |config|\n  config.boppers \u003c\u003c Clock.new\nend\n```\n\nThe `Boppers.notify(event_name, title: message: options: {})` method expects a\nevent name (the recommended value is the bot's name), a title, message and a\nhash of options (it's up to the notifier to use the options).\n\n### Distributing boppers\n\nI encourage you to share your boppers. I even added a command to generate a\ncommon structure, so you don't have to think about how to organize it. Let's say\nyou want to distribute the clock bopper above.\n\n```\n$ boppers plugin clock --type bopper\n      create  boppers-clock.gemspec\n      create  gems.rb\n      create  .gitignore\n      create  .rubocop.yml\n      create  .travis.yml\n      create  CODE_OF_CONDUCT.md\n      ...\n```\n\nNow add your bopper code to `lib/boppers/clock.rb`.\n\n```ruby\n# frozen_string_literal: true\n\nrequire \"boppers/clock/version\"\n\nmodule Boppers\n  class Clock\n    def call\n      Boppers.notify(\n        :clock,\n        title: \"Clock\",\n        message: \"Now is #{Time.now}\"\n      )\n    end\n  end\nend\n```\n\nChange the `boppers-clock.gemspec` file accordingly (add a description, author\nname and email).\n\nIf you're writing tests, use `Boppers::Testing::BopperLinter` to lint your\nbopper (some basic validations will be made).\n\n```ruby\n# frozen_string_literal: true\n\nrequire \"test_helper\"\n\nclass BoppersClockTest \u003c Minitest::Test\n  test \"lint bopper\" do\n    bopper = Boppers::Clock.new\n    Boppers::Testing::BopperLinter.call(bopper)\n  end\nend\n```\n\nThen make a commit and run `rake release` to distribute it (I'm assuming your\nRubygems account is already configured).\n\n## Notifiers\n\nA notifier is basically a class that responds to\n`#call(title, message, options)`. The following example implements a `stderr`\nnotifier.\n\n```ruby\nclass Stderr\n  attr_reader :subscribe\n\n  def initialize(subscribe: nil)\n    @subscribe = subscribe\n  end\n\n  def call(title, message, _options)\n    $stderr \u003c\u003c \"== #{title}\\n\"\n    $stderr \u003c\u003c message.gsub(/^/m, \"   \")\n    $stderr \u003c\u003c \"\\n\\n\"\n  end\nend\n\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Stderr.new\nend\n```\n\nYou can specify which messages a notifier will receive by setting `subscribe:`,\nlike the following:\n\n```ruby\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Stderr.new(subscribe: %i[clock])\nend\n```\n\nNow this notifier will only be triggered when `Boppers.notify(:clock, **kargs)`\nis called, ignoring other boppers.\n\n### Distributing notifiers\n\nThe idea is pretty much the same as creating a bopper. Use the command\n`boppers plugin [NAME] --type notifier` to generate a file structure. Then\nconfigure the plugin accordingly. There's a a linter for notifiers:\n`Boppers::Testing::NotifierLinter`.\n\n### Available notifiers\n\nBy default, Boppers comes with the following notifiers.\n\n- [Hipchat](https://www.hipchat.com/sign_in)\n- [Pushover](https://pushover.net)\n- [Sendgrid](https://sendgrid.com)\n- [Slack](https://slack.com)\n- stdout\n- [Telegram](https://telegram.org)\n- [Twitter](https://twitter.com)\n\n#### Hipchat\n\n1. Create a \"Send Notification\" room API token at\n   `https://[SUBDOMAIN].hipchat.com/rooms`.\n2. The room id is available at the \"Summary\" section as \"API ID\".\n\n```ruby\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Boppers::Notifier::Hipchat.new(\n    api_token: \"API_TOKEN,\n    room: \"ROOM\"\n  )\nend\n```\n\n#### Pushover\n\n```ruby\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Boppers::Notifier::Pushover.new(\n    app_token: \"APP_TOKEN\",\n    user_token: \"USER_TOKEN\"\n  )\nend\n```\n\n#### Slack\n\n1. Create a new bot user at https://my.slack.com/services/new/bot\n2. Set the API token as the `api_token:`.\n3. Set the channel as the `channel:`.\n\n```ruby\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Boppers::Notifier::Slack.new(\n    api_token: \"API_TOKEN\",\n    channel: \"#core\"\n  )\nend\n```\n\n#### Sendgrid\n\n```ruby\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Boppers::Notifier::Sendgrid.new(\n    username: \"USERNAME\",\n    password: \"PASSWORD\",\n    domain: \"DOMAIN\",\n    email: \"your@email.com\"\n  )\nend\n```\n\n#### Stdout\n\n```ruby\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Boppers::Notifier::Stdout.new\nend\n```\n\n#### Telegram\n\n1. [Create a bot](https://core.telegram.org/bots#6-botfather). The returned API\n   token must be defined as `api_token:`.\n2. Send a message to the bot.\n3. Run `ruby setup/telegram.rb` locally to get the channel id. You may need to\n   install the dependencies with `bundle install` before doing it so.\n4. Set the channel as `channel_id: \u003cchannel id\u003e`. Sometimes id can be a negative\n   number and this is important.\n\n```ruby\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Boppers::Notifer::Telegram.new(\n    api_token: \"API_TOKEN\",\n    channel_id: \"CHANNEL_ID\"\n  )\nend\n```\n\nYou can run `boppers setup telegram`, which will basically guide like those\nsteps above. No tokens will be saved locally or remotely in any form.\n\n#### Twitter\n\n1. Create an user for your bot.\n2. Follow your bot, and make your bot follow you.\n3. Create a new Twitter application under your bot's account at\n   https://apps.twitter.com/app/new\n4. Go to \"Keys and Access Tokens\" and create a new access token.\n5. Set `consumer_key:`, `consumer_secret:`, `access_token:` and `access_secret:`\n   named arguments, all available under \"Keys and Access Token\".\n6. Set the user that'll receive the notification as `user: \u003cusername\u003e`.\n\n```ruby\nBoppers.configure do |config|\n  config.notifiers \u003c\u003c Boppers::Notifer::Twitter.new(\n    consumer_key: \"CONSUMER_KEY\",\n    consumer_secret: \"CONSUMER_SECRET\",\n    access_token: \"ACCESS_TOKEN\",\n    access_secret: \"ACCESS_SECRET\",\n    user: \"someuser\"\n  )\nend\n```\n\n## Deploying to Heroku\n\nI'm assuming you installed the gem with `gem install boppers` and generated your\napp.\n\nAdd your configuration to `config/boppers.rb`. Also make sure you don't hardcode\nany sensitive value, like API tokens or passwords. Use\n[superconfig](https://rubygems.org/gems/superconfig) to manage access to your\nenvironment variables.\n\nNow, configure Heroku. Create a new app for this.\n\n```\nheroku create\n```\n\nIf you're going to send e-mail notification, you'll need Sendgrid.\n\n```\nheroku addons:create sendgrid:starter\n```\n\nYou also need to set the buildpack:\n\n```\nheroku buildpacks:set heroku/ruby\n```\n\nMake a commit and deploy to your Heroku account.\n\n```\ngit add .\ngit commit -m \"Initial commit\"\ngit push heroku main\n```\n\nScale up the boppers worker:\n\n```\nheroku ps:scale worker=1\n```\n\nTo make your worker run 24/7 (will cost you $7/month):\n\n```\nheroku dyno:type worker=hobby\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`rake test` to run the tests. You can also run `bin/console` for an interactive\nprompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To\nrelease a new version, update the version number in `version.rb`, and then run\n`bundle exec rake release`, which will create a git tag for the version, push\ngit commits and tags, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/fnando/boppers. This project is intended to be a safe,\nwelcoming space for collaboration, and contributors are expected to adhere to\nthe [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Boppers project’s codebases, issue trackers, chat\nrooms and mailing lists is expected to follow the\n[code of conduct](https://github.com/fnando/boppers/blob/main/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnando%2Fboppers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffnando%2Fboppers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnando%2Fboppers/lists"}