jabber_admin 0.2.0 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7595ac9bd9cd6f045626d75d5198e65515b6a1c81b5dd2ff98d71067f66a8b1a
-  data.tar.gz: 344565013c98a99b5aa6a58e4ae1292fcece4a24d19fc9b3a7366bfbb95af80a
+  metadata.gz: 1c3c8dc6ddbbea8d817376ab6c870b2b5590a72e69f4e954cf118cad0a54088f
+  data.tar.gz: 71306c24bf91350ee2597cd7608e0e77787fdc498d308bf70f1bb081625f55c7
 SHA512:
-  metadata.gz: 1aad50ff432b9e24ac56ea25e3394cc601e3acf610a809944f301043cdd3a7fa407f4fd7ed962b6413364588caa5f4616d1a90e28b5e540a80ad22a462c02594
-  data.tar.gz: c6b3547c3dd1adb0728cc592743a46c9d012f708e881370d36da63be8d5b8148ed5a76975c25696d7d1a3b2dca501142cde24e01c435730ae9e803e636f37ccf
+  metadata.gz: 8668df2cbce010b8978ac1ca4f3e4f496642b30888059b9e098d9eae984b3968e55a349ac082f666977b66b8306feb72fbc5e9696e1d2be6c14170dc22cf7c01
+  data.tar.gz: 82c2c8be4ca79ae695fc31a30bea1634d482b9797fb0c9e26e6521f6c53a9fe68647f9542cb077167c4c9bdae8d67883c0894af1907508b6a512bac46ab67fcf

data/.github/workflows/documentation.yml

@@ -0,0 +1,38 @@
+name: Build Documentation
+on:
+  repository_dispatch:
+    types: [documentation]
+
+concurrency:
+  group: 'docs'
+
+jobs:
+  docs:
+    name: Build gem documentation
+    runs-on: ubuntu-20.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install the correct Ruby version
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.5
+          bundler-cache: true
+
+      - name: Prepare the virtual environment
+        uses: hausgold/actions/ci@master
+        with:
+          clone_token: '${{ secrets.CLONE_TOKEN }}'
+          settings: '${{ github.repository }}'
+          target: ci/gem-test
+
+      - name: Build gem documentation
+        run: make docs
+
+      - name: Upload the code coverage report
+        run: coverage
+
+      - name: Add this job to the commit status
+        run: commit-status '${{ job.status }}'
+        if: always()

data/.github/workflows/test.yml

@@ -0,0 +1,59 @@
+name: Test
+on:
+  push:
+    branches:
+      - '**'
+  schedule:
+    - cron: '0 0 * * MON'
+
+concurrency:
+  group: '${{ github.ref }}'
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: 'Test the gem (Ruby ${{ matrix.ruby }})'
+    runs-on: ubuntu-20.04
+    timeout-minutes: 5
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.5, 2.6, 2.7]
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install the correct Ruby version
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Prepare the virtual environment
+        uses: hausgold/actions/ci@master
+        with:
+          clone_token: '${{ secrets.CLONE_TOKEN }}'
+          settings: '${{ github.repository }}'
+          target: ci/gem-test
+
+      - name: Run the gem tests
+        run: make test
+
+      - name: Upload the code coverage report
+        run: coverage
+
+  trigger-docs:
+    name: Trigger the documentation upload
+    runs-on: ubuntu-20.04
+    timeout-minutes: 2
+    needs: test
+    if: github.ref == 'refs/heads/master'
+    steps:
+      - name: Prepare the virtual environment
+        uses: hausgold/actions/ci@master
+        with:
+          clone_token: '${{ secrets.CLONE_TOKEN }}'
+          settings: '${{ github.repository }}'
+          target: ci/noop
+
+      - name: Trigger the documentation upload
+        run: workflow documentation

data/.gitignore

@@ -3,7 +3,7 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
-/doc/
+/doc/api/
 /pkg/
 /spec/reports/
 /tmp/

data/.rubocop.yml

@@ -1,14 +1,11 @@
 require: rubocop-rspec
 
-Rails:
-  Enabled: true
-
 Documentation:
   Enabled: true
 
 AllCops:
   DisplayCopNames: true
-  TargetRubyVersion: 2.2
+  TargetRubyVersion: 2.5
 
 Metrics/BlockLength:
   Exclude:
@@ -31,3 +28,8 @@ RSpec/MessageSpies:
 # bang/non-bang cases.
 RSpec/NestedGroups:
   Max: 4
+
+# We stay at 80 characters per line.
+# See: https://rubystyle.guide/#max-line-length
+Metrics/LineLength:
+  Max: 80

data/.simplecov

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 SimpleCov.start 'test_frameworks' do
   add_filter '/vendor/bundle/'
 end

data/.yardopts

@@ -1,4 +1,6 @@
---output-dir=doc/app
+--output-dir=doc/api
+--plugin activesupport-concern
+--markup=rdoc
 -
 README.md
 lib/**/*.rb

data/CHANGELOG.md

@@ -1,17 +1,51 @@
+### 1.0.3
+
+* Migrated to Github Actions
+* Migrated to our own coverage reporting
+* Added the code statistics to the test process
+
+### 1.0.2
+
+* Corrected the GNU Make release target
+* Corrected the empty arguments check
+
+### 1.0.1
+
+* Gracefully handle a missing vCard when a vCard field is queried (#7)
+
+### 1.0.0
+
+* All `JabberAdmin` errors `[UnknownCommandError, CommandError, RequestError]`
+  now ship the response object correctly (was always set to `nil` previously)
+  (#6)
+* Improved the default exceptions messages with the response body (#6)
+* Added support for setting/fetching vCard details (`JabberAdmin.set_vcard`,
+  `JabberAdmin.get_vcard`) (#6)
+* Dropped support for Ruby <2.5 (#6)
+* Added some versioning helpers (eg. `JabberAdmin.version`)
+
 ### 0.2.0
 
 * [BC] The configuration has changed
-  * `api_host` => `url`, we require now the full base URL of the REST API, this allows custom mod_http_api paths (See: https://bit.ly/2rBxatJ)
-  * `admin` => `username`, we want to be use common sense API client jargon here
-* We support from now on predefined AND freestyle commands on the `JabberAdmin` module
-* We support from now on bang and non-bang command variants (for both predefined and freestyle commands) which allows the client to use builtin error handling or not
-* [BC] Previously only bang variants were possible, without response checking, look out for more exceptions when you migrate
+  * `api_host` => `url`, we require now the full base URL of the REST API, this
+    allows custom mod_http_api paths (See: https://bit.ly/2rBxatJ)
+  * `admin` => `username`, we want to be use common sense API client jargon
+    here
+* We support from now on predefined AND freestyle commands on the `JabberAdmin`
+  module
+* We support from now on bang and non-bang command variants (for both
+  predefined and freestyle commands) which allows the client to use builtin
+  error handling or not
+* [BC] Previously only bang variants were possible, without response checking,
+  look out for more exceptions when you migrate
 * New predefined commands:
   * muc_register_nick
   * send_stanza_c2s
   * set_nickname
+  * set_presence
 * The documentation was greatly improved
-* The testcases were rewritten and tested with VCR against a real ejabberd server (18.01)
+* The testcases were rewritten and tested with VCR against a real ejabberd
+  server (18.01)
 
 ### 0.1.4
 

data/Makefile

@@ -27,16 +27,24 @@ SORT ?= sort
 # Container binaries
 BUNDLE ?= bundle
 RAKE ?= rake
+RUBOCOP ?= rubocop
+YARD ?= yard
 
 all:
 	# jabber_admin
 	#
-	# install                  Install the dependencies
-	# test                     Run the whole test suite
-	# clean                    Clean the dependencies
+	# install            Install the dependencies
+	# test               Run the whole test suite
+	# test-style         Check the coding styles
+	# clean              Clean the dependencies
 	#
-	# shell                    Run an interactive shell on the container
-	# shell-irb                Run an interactive IRB shell on the container
+	# docs               Generate the Ruby documentation of the library
+	# stats              Print the code statistics (library and test suite)
+	# notes              Print all the notes from the code
+	# release            Release a new Gem version (maintainers only)
+	#
+	# shell              Run an interactive shell on the container
+	# shell-irb          Run an interactive IRB shell on the container
 	#
 	# supported-commands-list  Generate the supported commands list
 
@@ -60,9 +68,19 @@ install:
 	@$(MKDIR) -p $(VENDOR_DIR)
 	@$(call run-shell,$(BUNDLE) check || $(BUNDLE) install --path $(VENDOR_DIR))
 
-test: install
+test: \
+	test-specs \
+	test-style
+
+test-specs:
 	# Run the whole test suite
-	@$(call run-shell,$(BUNDLE) exec $(RAKE))
+	@$(call run-shell,$(BUNDLE) exec $(RAKE) stats spec)
+
+test-style: test-style-ruby
+
+test-style-ruby:
+	# Run the static code analyzer (rubocop)
+	@$(call run-shell,$(BUNDLE) exec $(RUBOCOP) -a)
 
 clean:
 	# Clean the dependencies
@@ -76,17 +94,30 @@ endif
 
 distclean: clean clean-containers
 
-shell: install
+shell:
 	# Run an interactive shell on the container
 	@$(call run-shell,$(BASH) -i)
 
-shell-irb: install
+shell-irb:
 	# Run an interactive IRB shell on the container
 	@$(call run-shell,bin/console)
 
+docs:
+	# Build the API documentation
+	@$(call run-shell,$(BUNDLE) exec $(YARD) -q && \
+		$(BUNDLE) exec $(YARD) stats --list-undoc --compact)
+
+notes:
+	# Print the code statistics (library and test suite)
+	@$(call run-shell,$(BUNDLE) exec $(RAKE) notes)
+
+stats:
+	# Print all the notes from the code
+	@$(call run-shell,$(BUNDLE) exec $(RAKE) stats)
+
 release:
 	# Release a new gem version
-	@$(RAKE) release
+	@$(BUNDLE) exec $(RAKE) release
 
 supported-commands-list:
 	# Generate the supported commands list

data/README.md

@@ -1,10 +1,10 @@
-![jabber_admin](doc/assets/project.png)
+![jabber_admin](doc/assets/project.svg)
 
-[![Build Status](https://travis-ci.org/hausgold/jabber_admin.svg?branch=master)](https://travis-ci.org/hausgold/jabber_admin)
+[![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)
 [![Gem Version](https://badge.fury.io/rb/jabber_admin.svg)](https://badge.fury.io/rb/jabber_admin)
-[![Maintainability](https://api.codeclimate.com/v1/badges/0b3c444d8db8acaaba97/maintainability)](https://codeclimate.com/github/hausgold/jabber_admin/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/0b3c444d8db8acaaba97/test_coverage)](https://codeclimate.com/github/hausgold/jabber_admin/test_coverage)
-[![API docs](https://img.shields.io/badge/docs-API-blue.svg)](https://www.rubydoc.info/gems/jabber_admin)
+[![Test Coverage](https://automate-api.hausgold.de/v1/coverage_reports/jabber_admin/coverage.svg)](https://knowledge.hausgold.de/coverage)
+[![Test Ratio](https://automate-api.hausgold.de/v1/coverage_reports/jabber_admin/ratio.svg)](https://knowledge.hausgold.de/coverage)
+[![API docs](https://automate-api.hausgold.de/v1/coverage_reports/jabber_admin/documentation.svg)](https://www.rubydoc.info/gems/jabber_admin)
 
 jabber_admin is a small library to easily communicate with the [ejabberd
 admin API](https://docs.ejabberd.im/developer/ejabberd-api/admin-api).
@@ -34,7 +34,7 @@ $ bundle
 Or install it yourself as:
 
 ```bash
-$ gem inst.object_idall jabber_admin
+$ gem install jabber_admin
 ```
 
 ## Configuration
@@ -87,7 +87,7 @@ JabberAdmin.register(user: 'peter@example.com', password: '123')
 
 Have a close look at the method names. We support bang and non-bang variants.
 The bang variants perform in-deep response validation and raise children of
-+JabberAdmin::Error+ in case of detected issues. These issues can be
+`JabberAdmin::Error` in case of detected issues. These issues can be
 unpermitted API requests, or invalid payload values, etc. The predefined
 commands also perform response body checks when it is appropriate. (Eg. many
 commands respond a single zero as a success indicator)

data/Rakefile

@@ -2,7 +2,75 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rails/code_statistics'
+require 'pp'
 
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+# Load some railties tasks
+load 'rails/tasks/statistics.rake'
+load 'rails/tasks/annotations.rake'
+
+# Clear the default statistics directory constant
+#
+# rubocop:disable Style/MutableConstant because we define it
+Object.send(:remove_const, :STATS_DIRECTORIES)
+::STATS_DIRECTORIES = []
+# rubocop:enable Style/MutableConstant
+
+# Monkey patch the Rails +CodeStatistics+ class to support configurable
+# patterns per path. This is reuqired to support top-level only file matches.
+class CodeStatistics
+  DEFAULT_PATTERN = /^(?!\.).*?\.(rb|js|coffee|rake)$/.freeze
+
+  # Pass the possible +pattern+ argument down to the
+  # +calculate_directory_statistics+ method call.
+  def calculate_statistics
+    Hash[@pairs.map do |pair|
+      [pair.first, calculate_directory_statistics(*pair[1..-1])]
+    end]
+  end
+
+  # Match the pattern against the individual file name and the relative file
+  # path. This allows top-level only matches.
+  def calculate_directory_statistics(directory, pattern = DEFAULT_PATTERN)
+    stats = CodeStatisticsCalculator.new
+
+    Dir.foreach(directory) do |file_name|
+      path = "#{directory}/#{file_name}"
+
+      if File.directory?(path) && (/^\./ !~ file_name)
+        stats.add(calculate_directory_statistics(path, pattern))
+      elsif file_name =~ pattern || path =~ pattern
+        stats.add_by_file_path(path)
+      end
+    end
+
+    stats
+  end
+end
+
+# Configure all code statistics directories
+vendors = [
+  [:unshift, 'Top-levels', 'lib', %r{lib(/jabber_admin)?/[^/]+\.rb$}],
+  [:unshift, 'Top-levels specs', 'spec',
+   %r{spec/jabber_admin(_spec\.rb|/[^/]+\.rb$)}],
+
+  [:unshift, 'Commands', 'lib/jabber_admin/commands'],
+  [:unshift, 'Commands specs', 'spec/jabber_admin/commands']
+].reverse
+
+vendors.each do |method, type, dir, pattern|
+  ::STATS_DIRECTORIES.send(method, [type, dir, pattern].compact)
+  ::CodeStatistics::TEST_TYPES << type if type.include? 'specs'
+end
+
+# Setup annotations
+ENV['SOURCE_ANNOTATION_DIRECTORIES'] = 'spec,doc'
+
+desc 'Enumerate all annotations'
+task :notes do
+  SourceAnnotationExtractor.enumerate '@?OPTIMIZE|@?FIXME|@?TODO', tag: true
+end

data/bin/config.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+$VERBOSE = nil
+require 'bundler/setup'
+require 'jabber_admin'
+
+JabberAdmin.configure do |conf|
+  conf.username = 'admin@jabber.local'
+  conf.password = 'defaultpw'
+  conf.url = 'http://jabber.local/api'
+end

data/bin/console

@@ -1,8 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'jabber_admin'
+require_relative 'config'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/doc/assets/project.svg

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   version="1.1"
+   id="Ebene_1"
+   x="0px"
+   y="0px"
+   viewBox="0 0 800 200"
+   xml:space="preserve"
+   width="800"
+   height="200"><metadata
+   id="metadata33"><rdf:RDF><cc:Work
+       rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
+         rdf:resource="http://purl.org/dc/dcmitype/StillImage" /><dc:title></dc:title></cc:Work></rdf:RDF></metadata><defs
+   id="defs31" />
+<style
+   type="text/css"
+   id="style2">
+    .st0{fill-rule:evenodd;clip-rule:evenodd;fill:#E73E11;}
+    .st1{fill-rule:evenodd;clip-rule:evenodd;fill:#0371B9;}
+    .st2{fill:#132E48;}
+    .st3{font-family:'OpenSans-Bold';}
+    .st4{font-size:29.5168px;}
+    .st5{fill-rule:evenodd;clip-rule:evenodd;fill:none;}
+    .st6{opacity:0.5;fill:#132E48;}
+    .st7{font-family:'OpenSans';}
+    .st8{font-size:12px;}
+</style>
+<g
+   transform="translate(0,1.53584)"
+   id="g828"><g
+   transform="translate(35.93985,35.66416)"
+   id="g8">
+    <path
+   style="clip-rule:evenodd;fill:#e73e11;fill-rule:evenodd"
+   id="path4"
+   d="m -0.1,124.4 c 0,0 33.7,-123.2 66.7,-123.2 12.8,0 26.9,21.9 38.8,47.2 -23.6,27.9 -66.6,59.7 -94,76 -7.1,0 -11.5,0 -11.5,0 z"
+   class="st0" />
+    <path
+   style="clip-rule:evenodd;fill:#0371b9;fill-rule:evenodd"
+   id="path6"
+   d="m 88.1,101.8 c 13.5,-10.4 18.4,-16.2 27.1,-25.4 10,25.7 16.7,48 16.7,48 0,0 -41.4,0 -78,0 14.6,-7.9 18.7,-10.7 34.2,-22.6 z"
+   class="st1" />
+</g><text
+   y="106.40316"
+   x="192.43155"
+   style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:29.51733398px;font-family:'Open Sans', sans-serif;-inkscape-font-specification:'OpenSans-Bold, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#132e48"
+   id="text10"
+   class="st2 st3 st4">jabber_admin</text>
+<rect
+   style="clip-rule:evenodd;fill:none;fill-rule:evenodd"
+   id="rect12"
+   height="24"
+   width="314.5"
+   class="st5"
+   y="118.06416"
+   x="194.23985" /><text
+   y="127.22146"
+   x="194.21715"
+   style="font-size:12px;font-family:'Open Sans', sans-serif;opacity:0.5;fill:#132e48;-inkscape-font-specification:'Open Sans, sans-serif, Normal';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;"
+   id="text14"
+   class="st6 st7 st8">A Ruby library for the ejabberd RESTful admin API </text>
+</g>
+</svg>

data/docker-compose.yml

@@ -6,7 +6,7 @@ services:
     ports: ["4560", "5222", "5269", "5280", "5443"]
 
   test:
-    image: ruby:2.3
+    image: ruby:2.5
     network_mode: bridge
     working_dir: /app
     volumes:

data/jabber_admin.gemspec

@@ -25,6 +25,8 @@ Gem::Specification.new do |spec|
       'public gem pushes.'
   end
 
+  spec.required_ruby_version = '~> 2.5'
+
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
@@ -32,17 +34,19 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'activesupport', '>= 4.2.5'
+  spec.add_dependency 'activesupport', '>= 5.2.0'
   spec.add_dependency 'rest-client', '~> 2.0', '>= 2.0.2'
 
-  spec.required_ruby_version = '>= 2.2'
-
-  spec.add_development_dependency 'bundler', '~> 1.16'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop'
-  spec.add_development_dependency 'rubocop-rspec'
-  spec.add_development_dependency 'simplecov', '~> 0.15'
-  spec.add_development_dependency 'vcr', '~> 3.0'
+  spec.add_development_dependency 'bundler', '>= 1.16', '< 3'
+  spec.add_development_dependency 'irb', '~> 1.2'
+  spec.add_development_dependency 'railties', '>= 4.2.0', '< 6.1'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.9'
+  spec.add_development_dependency 'rubocop', '~> 0.93'
+  spec.add_development_dependency 'rubocop-rspec', '~> 1.43'
+  spec.add_development_dependency 'simplecov', '< 0.18'
+  spec.add_development_dependency 'vcr', '~> 6.0'
   spec.add_development_dependency 'webmock', '~> 3.0'
+  spec.add_development_dependency 'yard', '~> 0.9.18'
+  spec.add_development_dependency 'yard-activesupport-concern', '~> 0.0.1'
 end

data/lib/jabber_admin/api_call.rb

@@ -41,8 +41,8 @@ module JabberAdmin
         password: JabberAdmin.configuration.password,
         payload: payload.to_json
       )
-    rescue RestClient::Exception => err
-      @response = err.response
+    rescue RestClient::Exception => e
+      @response = e.response
     end
 
     # Check if the response was successful. Otherwise raise exceptions with
@@ -52,22 +52,25 @@ module JabberAdmin
     # @raise JabberAdmin::CommandError
     #
     # rubocop:disable Metrics/AbcSize because its the bundled check logic
+    # rubocop:disable Metrics/MethodLength dito
     def check_response
       # The REST API responds a 404 status code when the command is not known.
-      raise UnknownCommandError, "Command '#{command}' is not known", response \
-        if response.code == 404
+      if response.code == 404
+        raise UnknownCommandError.new("Command '#{command}' is not known",
+                                      response)
+      end
 
       # In case we send commands with missing data or any other validation
       # issues, the REST API will respond with a 400 Bad Request status
       # code.
-      raise CommandError, 'Invalid arguments for command', response \
+      raise CommandError.new('Invalid arguments for command', response) \
         if response.code == 400
 
       # Looks like the ejabberd REST API is returning 200 OK in case the
       # request was valid and permitted. But it does not indicate that the
       # request was successful handled. This is indicated on the response body
       # as a one (1) or a zero (0). (0 on success, 1 otherwise)
-      raise RequestError, 'Response code was not 200', response \
+      raise RequestError.new('Response code was not 200', response) \
         unless response.code == 200
 
       # Stop the check, when we should not check the response body
@@ -76,10 +79,11 @@ module JabberAdmin
       # The command was not successful, for some reason. Unfortunately we do
       # not get any further information here, which makes error debugging a
       # struggle.
-      raise CommandError, 'Command was not successful', response \
+      raise CommandError.new('Command was not successful', response) \
         unless response.body == '0'
     end
     # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
 
     # Just a simple DSL wrapper for the response method.
     #

data/lib/jabber_admin/commands/get_vcard.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  module Commands
+    # Get content from a vCard.
+    #
+    # Examples:
+    #
+    #   JabberAdmin.get_vcard!(
+    #     :fn, 'n.given', 'org.orgunit[]', 'u.known[]',
+    #     user: 'ac865680-9681-45da-8fee-8584053dde5b@jabber.local'
+    #   )
+    #   # => {:fn=>"Max Mustermann",
+    #   #     "n.given"=>"Max",
+    #   #     "org.orgunit"=>["Marketing", "Production"],
+    #   #     "u.known"=>nil}
+    #
+    # **Heads up!** ejabberd version 18.01 has a bug at the +get_vcard2_multi+
+    # command, which just returns the first element of possible multiple
+    # values. (in an array)
+    #
+    # @see https://bit.ly/2SLkEWi
+    # @see https://bit.ly/34T71dm
+    # @see https://bit.ly/3nKqiGL
+    class GetVcard
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param keys [Array<String, Symbol>, String, Symbol] name of the
+      #   vCard field (+n.family+ for multiple levels)
+      # @param user [String] user JID wo/ resource (eg. +tom@localhost+)
+      # @return [Hash] the vCard details
+      #
+      # rubocop:disable Metrics/MethodLength because the ejabberd REST API is
+      #   hard to use in complex scenarios, so we have to work around it
+      # rubocop:disable Metrics/AbcSize dito
+      # rubocop:disable Metrics/CyclomaticComplexity dito
+      # rubocop:disable Metrics/PerceivedComplexity dito
+      def self.call(callable, *keys, user:)
+        uid, host = user.split('@')
+        val = proc do |key|
+          parts = key.to_s.upcase.split('.')
+          args = { name: parts.shift }
+          meth = 'get_vcard'
+
+          unless parts.empty?
+            args[:subname] = parts.shift
+            meth = 'get_vcard2'
+
+            if args[:subname].end_with? '[]'
+              meth += '_multi'
+              args[:subname].delete_suffix!('[]')
+            end
+          end
+
+          res = callable.call(meth, check_res_body: false,
+                                    user: uid, host: host, **args)
+          body = (200..299).cover?(res.code) ? JSON.parse(res.body) : nil
+          body.is_a?(Hash) ? body['content'] : body
+        rescue JabberAdmin::Error => e
+          # When ejabberd tells us there was no value, it does this the hard way
+          next if e.response.body.include? 'error_no_value_found_in_vcard'
+          # Same for the case when there is no vCard at all
+          next if e.response.body.include? 'error_no_vcard_found'
+
+          raise e
+        end
+
+        # When just one key is requested, we return the value directly
+        return val[keys.first] if keys.count == 1
+
+        # When multiple keys are requested, we assemble a hash
+        keys.map do |key|
+          res_key = key.is_a?(String) ? key.delete_suffix('[]') : key
+          [res_key, val[key]]
+        end.to_h
+      end
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+    end
+  end
+end

data/lib/jabber_admin/commands/set_vcard.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  module Commands
+    # Set contents in a vCard.
+    #
+    # Examples:
+    #
+    #   JabberAdmin.set_vcard!(
+    #     user: 'ac865680-9681-45da-8fee-8584053dde5b@jabber.local',
+    #     'org.orgunit[]' => %w[Marketing Production],
+    #     fn: 'Max Mustermann',
+    #     'n.given': 'Max',
+    #     'n.family' => 'Mustermann'
+    #   )
+    #   # => {"org.orgunit[]"=>["Marketing", "Production"],
+    #   #     "n.family"=>"Mustermann",
+    #   #     :fn=>"Max Mustermann",
+    #   #     :"n.given"=>"Max"}
+    #
+    # @see https://bit.ly/2ZB9S6y
+    # @see https://bit.ly/3lAIGzO
+    # @see https://bit.ly/34MiviZ
+    class SetVcard
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param args [Hash] the keys/values to set to the vCard
+      #   (eg. +n.family+ for multiple levels)
+      # @param user [String] user JID wo/ resource (eg. +tom@localhost+)
+      # @param sym_args [Hash{Symbol => Mixed}] additional keys/values to
+      #   set to the vCard
+      # @return [Hash] the vCard details
+      #
+      # rubocop:disable Metrics/MethodLength because the ejabberd REST API is
+      #   hard to use in complex scenarios, so we have to work around it
+      # rubocop:disable Metrics/AbcSize dito
+      def self.call(callable, args = {}, user:, **sym_args)
+        args = args.merge(sym_args)
+        uid, host = user.split('@')
+
+        set = proc do |key, val|
+          parts = key.to_s.upcase.split('.')
+          body = { name: parts.shift, content: val }
+          meth = 'set_vcard'
+
+          unless parts.empty?
+            body[:subname] = parts.shift
+            meth = 'set_vcard2'
+
+            if body[:subname].end_with? '[]'
+              meth += '_multi'
+              body[:subname].delete_suffix!('[]')
+              body[:contents] = body.delete(:content)
+            end
+          end
+
+          callable.call(meth, user: uid, host: host, **body)
+        end
+
+        args.each { |key, val| set[key, val] }
+        args
+      end
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize
+    end
+  end
+end

data/lib/jabber_admin/commands.rb

@@ -6,6 +6,6 @@ module JabberAdmin
 end
 
 # Require all commands from the commands subfolder
-Dir[Pathname.new(__dir__).join('commands', '**', '*.rb')].each do |file|
+Dir[Pathname.new(__dir__).join('commands', '**', '*.rb')].sort.each do |file|
   require file
 end

data/lib/jabber_admin/exceptions.rb

@@ -19,6 +19,7 @@ module JabberAdmin
     # @param response [RestClient::Response] the response when available
     def initialize(msg, response = nil)
       @response = response
+      msg += " => #{response.body}" if response&.body
       super(msg)
     end
   end

data/lib/jabber_admin/version.rb

@@ -1,7 +1,24 @@
 # frozen_string_literal: true
 
+# The gem module.
 module JabberAdmin
   # The version constant of the gem. Increase this value
   # in case of a gem release.
-  VERSION = '0.2.0'.freeze
+  VERSION = '1.0.3'
+
+  class << self
+    # Returns the version of gem as a string.
+    #
+    # @return [String] the gem version as string
+    def version
+      VERSION
+    end
+
+    # Returns the version of the gem as a +Gem::Version+.
+    #
+    # @return [Gem::Version] the gem version as object
+    def gem_version
+      Gem::Version.new VERSION
+    end
+  end
 end

data/lib/jabber_admin.rb

@@ -84,14 +84,11 @@ module JabberAdmin
   # @param method [Symbol, String, #to_s] the name of the command to run
   # @param args all additional payload to pass down to the API call
   # @return [RestClient::Response] the actual response of the command
-  #
-  # rubocop:disable Style/MethodMissing we support all given methods
   def self.method_missing(method, *args)
     predefined_command(method).call(predefined_callable(method), *args)
   rescue NameError
     predefined_callable(method).call(method.to_s.chomp('!'), *args)
   end
-  # rubocop:enable Style/MethodMissing
 
   # Try to find the given name as a predefined command. When there is no such
   # predefined command, we raise a +NameError+.

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: jabber_admin
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.3
 platform: ruby
 authors:
 - Henning Vogt
 - Hermann Mayer
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2018-05-14 00:00:00.000000000 Z
+date: 2021-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.2.5
+        version: 5.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.2.5
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
@@ -49,100 +49,140 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.93'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.93'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.43'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.43'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.18'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -157,6 +197,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.18
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.18
+- !ruby/object:Gem::Dependency
+  name: yard-activesupport-concern
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
 description: Library for the ejabberd RESTful admin API
 email:
 - henning.vogt@hausgold.de
@@ -166,11 +234,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
+- ".github/workflows/documentation.yml"
+- ".github/workflows/test.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".simplecov"
-- ".travis.yml"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile
@@ -178,11 +247,10 @@ files:
 - Makefile
 - README.md
 - Rakefile
+- bin/config.rb
 - bin/console
 - bin/setup
-- doc/assets/logo.png
-- doc/assets/project.png
-- doc/assets/project.xcf
+- doc/assets/project.svg
 - docker-compose.yml
 - jabber_admin.gemspec
 - lib/jabber_admin.rb
@@ -191,6 +259,7 @@ files:
 - lib/jabber_admin/commands/ban_account.rb
 - lib/jabber_admin/commands/create_room.rb
 - lib/jabber_admin/commands/create_room_with_opts.rb
+- lib/jabber_admin/commands/get_vcard.rb
 - lib/jabber_admin/commands/muc_register_nick.rb
 - lib/jabber_admin/commands/register.rb
 - lib/jabber_admin/commands/registered_users.rb
@@ -201,6 +270,7 @@ files:
 - lib/jabber_admin/commands/set_nickname.rb
 - lib/jabber_admin/commands/set_presence.rb
 - lib/jabber_admin/commands/set_room_affiliation.rb
+- lib/jabber_admin/commands/set_vcard.rb
 - lib/jabber_admin/commands/subscribe_room.rb
 - lib/jabber_admin/commands/unregister.rb
 - lib/jabber_admin/commands/unsubscribe_room.rb
@@ -212,24 +282,23 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '2.2'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 3.2.16
+signing_key:
 specification_version: 4
 summary: Library for the ejabberd RESTful admin API
 test_files: []

data/.travis.yml

@@ -1,20 +0,0 @@
-sudo: false
-
-env:
-  global:
-    - CC_TEST_REPORTER_ID=02d696c72627e730a3db553884276acf15672466e32e66a788672d3b167629ca
-
-language: ruby
-rvm:
-  - 2.5
-  - 2.4
-  - 2.3
-  - 2.2
-
-before_install: gem install bundler -v 1.15.1
-before_script:
-  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
-  - chmod +x ./cc-test-reporter
-  - ./cc-test-reporter before-build
-after_script:
-  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT