{"id":19206769,"url":"https://github.com/hausgold/jabber_admin","last_synced_at":"2025-07-02T13:06:12.105Z","repository":{"id":28239470,"uuid":"117576037","full_name":"hausgold/jabber_admin","owner":"hausgold","description":"Ruby library for the ejabberd RESTful admin API","archived":false,"fork":false,"pushed_at":"2025-06-23T07:19:04.000Z","size":194,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-06-23T08:26:38.043Z","etag":null,"topics":["api","client","ejabberd","gem","http","jabber","oss","rest","ruby","ruby-gem"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/jabber_admin","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/hausgold.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2018-01-15T17:39:58.000Z","updated_at":"2025-06-23T07:19:07.000Z","dependencies_parsed_at":"2025-01-12T09:22:06.043Z","dependency_job_id":"22e1028d-e70b-48d6-8f28-7967859c9d28","html_url":"https://github.com/hausgold/jabber_admin","commit_stats":{"total_commits":50,"total_committers":5,"mean_commits":10.0,"dds":"0.43999999999999995","last_synced_commit":"6c47ac6e20514e9f64c4d313fad41ff39029d142"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/hausgold/jabber_admin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hausgold%2Fjabber_admin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hausgold%2Fjabber_admin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hausgold%2Fjabber_admin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hausgold%2Fjabber_admin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hausgold","download_url":"https://codeload.github.com/hausgold/jabber_admin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hausgold%2Fjabber_admin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261446607,"owners_count":23159469,"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":["api","client","ejabberd","gem","http","jabber","oss","rest","ruby","ruby-gem"],"created_at":"2024-11-09T13:16:55.833Z","updated_at":"2025-07-02T13:06:12.054Z","avatar_url":"https://github.com/hausgold.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"![jabber_admin](doc/assets/project.svg)\n\n[![Continuous Integration](https://github.com/hausgold/jabber_admin/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/hausgold/jabber_admin/actions/workflows/test.yml)\n[![Gem Version](https://badge.fury.io/rb/jabber_admin.svg)](https://badge.fury.io/rb/jabber_admin)\n[![Test Coverage](https://automate-api.hausgold.de/v1/coverage_reports/jabber_admin/coverage.svg)](https://knowledge.hausgold.de/coverage)\n[![Test Ratio](https://automate-api.hausgold.de/v1/coverage_reports/jabber_admin/ratio.svg)](https://knowledge.hausgold.de/coverage)\n[![API docs](https://automate-api.hausgold.de/v1/coverage_reports/jabber_admin/documentation.svg)](https://www.rubydoc.info/gems/jabber_admin)\n\njabber_admin is a small library to easily communicate with the [ejabberd\nadmin API](https://docs.ejabberd.im/developer/ejabberd-api/admin-api).\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n  - [Predefined commands](#predefined-commands)\n  - [Freestyle commands](#freestyle-commands)\n- [Development](#development)\n- [Code of Conduct](#code-of-conduct)\n- [Contributing](#contributing)\n- [Releasing](#releasing)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'jabber_admin'\n```\n\nAnd then execute:\n\n```bash\n$ bundle\n```\n\nOr install it yourself as:\n\n```bash\n$ gem install jabber_admin\n```\n\n## Configuration\n\nYou can configure the jabber_admin gem in a global initializer way with the\n`JabberAdmin.configure` method which yields the configuration directly.\n\n```ruby\nJabberAdmin.configure do |config|\n  # The ejabberd REST API endpoint as a full URL.\n  # Take care of the path part, because this is individually\n  # configured on ejabberd. (See: https://bit.ly/2rBxatJ)\n  config.url = 'http://jabber.local/api'\n  # Provide here the full user JID in order to authenticate as\n  # a administrator.\n  config.username = 'admin@jabber.local'\n  # The password of the administrator account.\n  config.password = 'password'\nend\n```\n\nIn case this is not cool for you, you can get and modify the configuration\ndirectly with the help of the `JabberAdmin.configuration` getter.\n\n```ruby\nJabberAdmin.configuration.url = 'http://jabber.local/api'\nJabberAdmin.configuration.username = 'admin@jabber.local'\nJabberAdmin.configuration.password = 'password'\n```\n\n## Usage\n\n### Predefined commands\n\nWe support some handy predefined commands out of the box which ease the quick\nstart usage. These predefined commands comes with a good documentation\n(including valid example data) and a nifty interface. When it is possible to\nfill up missing data from a full user/room JID we do so. Say while sending a\ndirect invitation, you just pass the full room JID and we take care of\nsplitting it up to fulfill the separate room name and the separate MUC service\ndomain.\n\nAll our predefined commands are available directly underneath the `JabberAdmin`\nmodule as methods. Just call them like this:\n\n```ruby\nJabberAdmin.restart!\nJabberAdmin.register(user: 'peter@example.com', password: '123')\n```\n\nHave a close look at the method names. We support bang and non-bang variants.\nThe bang variants perform in-deep response validation and raise children of\n`JabberAdmin::Error` in case of detected issues. These issues can be\nunpermitted API requests, or invalid payload values, etc. The predefined\ncommands also perform response body checks when it is appropriate. (Eg. many\ncommands respond a single zero as a success indicator)\n\nThe non-bang variants will just fire the request and do not perform any checks\non the response. You can implement your own error handling or response analysis\nif you like. You could also just fire and forget them. It's up to you.\n\nHere comes a list of all supported predefined commands:\n\n- [ban_account](https://bit.ly/2KW9xVt)\n- [create_room](https://bit.ly/2rB8DFR)\n- [create_room_with_opts](https://bit.ly/2IBEfVO)\n- [muc_register_nick](https://bit.ly/2G9EBNQ)\n- [registered_users](https://bit.ly/2KhwT6Z)\n- [register](https://bit.ly/2wyhAox)\n- [restart](https://bit.ly/2G7YEwd)\n- [send_direct_invitation](https://bit.ly/2wuTpr2)\n- [send_stanza_c2s](https://bit.ly/2wwUcYr)\n- [send_stanza](https://bit.ly/2rzxyK1)\n- [set_nickname](https://bit.ly/2rBdyqc)\n- [set_presence](https://bit.ly/2rzxyK1)\n- [set_room_affiliation](https://bit.ly/2G5MfbW)\n- [subscribe_room](https://bit.ly/2Ke7Zoy)\n- [unregister](https://bit.ly/2wwYnDE)\n- [unsubscribe_room](https://bit.ly/2G5zcrj)\n- [destroy_room](https://bit.ly/31CtqxB)\n- [get_room_affiliations](https://bit.ly/3qI9Nyq)\n\nIf you want to contribute more, we accept pull requests!\n\n### Freestyle commands\n\nIn case you want to send commands easily without delivering new predefined\ncommands with documentation and some nifty tricks, you can simply call the\nejabberd REST API with your custom commands like this:\n\n```ruby\nJabberAdmin.status\nJabberAdmin.get_last(user: 'tom', host: 'ejabberd.local')\nJabberAdmin.set_presence!(...)\n```\n\nThe `JabberAdmin` is smart enough to detect that the given command is not a\npredefined command and therefore it assembles a new `JabberAdmin::ApiCall`\ninstance and passes down all arguments. If you look closely you see again that\nwe support a bang and non-bang variant. The error handling works the same as on\npredefined commands.\n\nBy default the `JabberAdmin::ApiCall` instance assumes it should perform body\nchecks on the response which is not clever on data fetching commands, due to\nthe fact that they do not deliver `0` as body. The body validation can be\nturned off with the additional `check_res_body: false` argument.\n\n```ruby\nJabberAdmin.get_last! \\\n  check_res_body: false, user: 'tom', host: 'ejabberd.local'\n```\n\nIn case you want to make use of the memorize feature of each\n`JabberAdmin::ApiCall` instance, just build it up directly.\n\n```ruby\ncommand = JabberAdmin::ApiCall.new('get_last'\n                                   user: 'tom',\n                                   host: 'ejabberd.local')\n# Get the response and memorize it\ncommand.response.object_id # =\u003e 21934400\n# A second call to the response method will not perform a request again\ncommand.response.object_id # =\u003e 21934400\n```\n\n## Development\n\nAfter checking out the repo, run `make install` to install dependencies. Then,\nrun `make test` to run the tests. You can also run `make shell-irb` for an\ninteractive prompt that will allow you to experiment.\n\n## Code of Conduct\n\nEveryone interacting in the project codebase, issue tracker, chat\nrooms and mailing lists is expected to follow the [code of\nconduct](./CODE_OF_CONDUCT.md).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/hausgold/jabber_admin. Make sure that every pull request adds\na bullet point to the [changelog](./CHANGELOG.md) file with a reference to the\nactual pull request.\n\n## Releasing\n\nThe release process of this Gem is fully automated. You just need to open the\nGithub Actions [Release\nWorkflow](https://github.com/hausgold/jabber_admin/actions/workflows/release.yml)\nand trigger a new run via the **Run workflow** button. Insert the new version\nnumber (check the [changelog](./CHANGELOG.md) first for the latest release) and\nyou're done.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhausgold%2Fjabber_admin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhausgold%2Fjabber_admin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhausgold%2Fjabber_admin/lists"}