{"id":13507847,"url":"https://github.com/acutario/ravenx","last_synced_at":"2025-03-30T09:33:07.095Z","repository":{"id":57540487,"uuid":"73488674","full_name":"acutario/ravenx","owner":"acutario","description":"Notification dispatch library for Elixir applications","archived":false,"fork":false,"pushed_at":"2018-02-17T17:57:39.000Z","size":114,"stargazers_count":110,"open_issues_count":4,"forks_count":8,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-01T07:33:18.434Z","etag":null,"topics":["elixir","email","notification-dispatch-library","notifications","slack"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","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/acutario.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-11T15:26:30.000Z","updated_at":"2024-05-21T15:48:00.000Z","dependencies_parsed_at":"2022-09-26T22:20:18.024Z","dependency_job_id":null,"html_url":"https://github.com/acutario/ravenx","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acutario%2Fravenx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acutario%2Fravenx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acutario%2Fravenx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acutario%2Fravenx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acutario","download_url":"https://codeload.github.com/acutario/ravenx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301963,"owners_count":20755512,"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":["elixir","email","notification-dispatch-library","notifications","slack"],"created_at":"2024-08-01T02:00:40.888Z","updated_at":"2025-03-30T09:33:06.808Z","avatar_url":"https://github.com/acutario.png","language":"Elixir","funding_links":[],"categories":["Email"],"sub_categories":[],"readme":"# Ravenx\n\n\n[![Current Version](https://img.shields.io/hexpm/v/ravenx.svg)](https://hex.pm/packages/ravenx)\n[![Build Status](https://travis-ci.org/acutario/ravenx.svg?branch=master)](https://travis-ci.org/acutario/ravenx)\n\nNotification dispatch library for Elixir applications (WIP).\n\n## Installation\n\n1. The package can be installed as simply as adding `ravenx` to your list of dependencies in `mix.exs`:\n\n```elixir\n  def deps do\n    [{:ravenx, \"~\u003e 1.1.3\"}]\n  end\n```\n\n2. Add Ravenx to your list of applications in `mix.exs`. This step is only needed if you are using a version older than Elixir 1.4.0 or you already have some applications listed under the `applications` key. In any other case applications are automatically inferred from dependencies (explained in the [Application inference](http://elixir-lang.github.io/blog/2017/01/05/elixir-v1-4-0-released/) section):\n\n```elixir\ndef application do\n  [\n    applications: [\n      ...,\n      :ravenx\n    ]\n  ]\nend\n```\n\n## Strategies\n\nFrom version 2.0, strategies come in separate packages, so the dependencies\nneeded are not added by default.\n\nTo define strategies, just add their packages to your `mix.exs` file and add\nthem to Ravenx configuration as follows:\n\n```elixir\nconfig :ravenx,\n  strategies: [\n    email: Ravenx.Strategy.Email\n    slack: Ravenx.Strategy.Slack\n    my_strategy: MyApp.Ravenx.MyStrategy\n  ]\n```\n\nWe currently maintain two strategies:\n\n* **Slack**: [hex.pm](https://hex.pm/packages/ravenx_slack) | [GitHub](https://github.com/acutario/ravenx_slack)\n* **E-mail** (based on Bamboo): [hex.pm](https://hex.pm/packages/ravenx_email) | [GitHub](https://github.com/acutario/ravenx_email)\n\nAlso, 3rd party strategies are supported and listed below.\n\n### 3rd party strategies\n\nAmazing people created 3rd party strategies to use Ravenx with more services:\n\n* **Pusher** (thanks to [@behind-design](https://github.com/behind-design)): [hex.pm](https://hex.pm/packages/ravenx_pusher) | [GitHub](https://github.com/behind-design/ravenx-pusher)\n* **Telegram** (thanks to [@maratgaliev](https://github.com/maratgaliev)): [hex.pm](https://hex.pm/packages/ravenx_telegram) | [GitHub](https://github.com/maratgaliev/ravenx_telegram)\n\nAnyone can create a strategy that works with Ravenx, so if you have one, please let us know to add it to this list.\n\n### Custom strategies\n\nMaybe there is some internal service you need to call to send notifications, so there is a way to create custom strategies for yout projects.\n\nFirst of all, you need to create a module that meet the [required behaviour](https://github.com/acutario/ravenx/blob/master/lib/ravenx/strategy_behaviour.ex), like the example you can see [here](https://github.com/acutario/ravenx/blob/master/lib/ravenx/strategy/dummy.ex).\n\nThen you can define custom strategies in application configuration:\n\n```elixir\nconfig :ravenx,\n  strategies: [\n    my_strategy: YourApp.MyStrategy\n  ]\n```\n\nand start using your strategy to deliver notifications using the atom assigned (in the example, `my_strategy`).\n\n## Single notification\n\nSending a single notification is as simply as calling this method:\n\n```elixir\niex\u003e Ravenx.dispatch(strategy, payload)\n```\n\nIn which `strategy` is an atom indicating one of the defined strategies and the\n`payload` is a map with information to dispatch the notification.\n\nFor example:\n\n```elixir\niex\u003e Ravenx.dispatch(:slack, %{title: \"Hello world!\", body: \"Science is cool!\"})\n```\n\nOptionally, a third parameter containing a map of options (like URLs or\nsecrets) can be passed depending on strategy configuration needs.\n\n## Multiple notifications\n\nYou can implement notification modules that `Ravenx` can use to know which strategies should use to send a specific notification.\n\nTo do it, you just need to `use Ravenx.Notification` and implement a callback function:\n\n```elixir\ndefmodule YourApp.Notification.NotifyUser do\n  use Ravenx.Notification\n\n  def get_notifications_config(user) do\n    # In this function you can define which strategies use for your user (or\n    # whatever you want to pass as argument) and return something like:\n\n    [\n      slack: {:slack, %{title: \"Important notification!\", body: \"Wait...\"}, %{channel: user.slack_username}},\n      email_user: {:email, %{subject: \"Important notification!\", html_body: \"\u003ch1\u003eWait...\u003c/h1\u003e\", to: user.email_address}},\n      email_company: {:email, %{subject: \"Important notification about an user!\", html_body: \"\u003ch1\u003eWait...\u003c/h1\u003e\", to: user.company.email_address}},\n      other_notification: {:invalid_strategy, %{text: \"Important notification!\"}, %{option1: value2}},\n    ]\n  end\nend\n```\n\nAs seen above, strategies can be used multiple times in a notification list (to send multiple e-mails that have different payload, for example).\n\n**Note:** each notification entry in the returned list should include:\n\n1. Atom defining the notification ID.\n2. A two or three element tuple containing:\n    1. Atom defining which strategy should be used.\n    2. Payload map with the data of the notification.\n    3. (Optional) Options map for that strategy.\n\nAnd then you can dispatch your notification using:\n\n```elixir\niex\u003e YourApp.Notification.NotifyUser.dispatch(user)\n```\n\nor asynchronously:\n\n```elixir\niex\u003e YourApp.Notification.NotifyUser.dispatch_async(user)\n```\n\nBoth will return a list with the responses for each notification sent:\n\n```elixir\niex\u003e YourApp.Notification.NotifyUser.dispatch(user)\n[\n  slack: {:ok, ...},\n  email_user: {:ok, ...},\n  email_company: {:ok, ...},\n  other_notification: {:error, {:unknown_strategy, :invalid_strategy}}\n]\n```\n\n## Configuration\nStrategies usually needs configuration options. To solve that, there are three\nways in which you can configure a notification dispatch strategy:\n\n1. Passing the options in the dispatch call:\n\n  ```elixir\n  iex\u003e Ravenx.dispatch(:slack, %{title: \"Hello world!\", body: \"Science is cool!\"}, %{url: \"...\", icon: \":bird:\"})\n  ```\n\n2. Specifying a configuration module in your application config:\n\n  ```elixir\n  config :ravenx,\n    config: YourApp.RavenxConfig\n  ```\n\n  and creating that module:\n\n  ```elixir\n  defmodule YourApp.RavenxConfig do\n    def slack (_payload) do\n      %{\n        url: \"...\",\n        icon: \":bird:\"\n      }\n    end\n  end\n  ```\n\n  **Note:** the module should contain a function called as the strategy yopu are\n  configuring, receiving the payload and returning a configuration Keyword list.\n\n3. Specifying the configuration directly on your application config file:\n\n  ```elixir\n  config :ravenx, :slack,\n    url: \"...\",\n    icon: \":bird:\"\n  ```\n\n### Mixing configurations\nConfiguration can also be mixed by using the three methods:\n\n * Static configuration on application configuration.\n * Dynamic configuration common to more than one scenario using a configuration module.\n * Call-specific configuration sending a config Keyword list on `dispatch` method.\n\n## Contribute\n\nAll contributions are welcome, and we really hope this repo will serve for beginners as well for more advanced developers.\n\nIf you have any doubt, feel free to ask, but always respecting our [Code of Conduct](https://github.com/acutario/ravenx_slack/blob/master/CODE_OF_CONDUCT.md).\n\nTo contribute, create a fork of the repository, make your changes and create a PR. And remember, talking on PRs/issues is a must!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facutario%2Fravenx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facutario%2Fravenx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facutario%2Fravenx/lists"}