jabber_admin 0.1.2 → 1.0.1

data/lib/jabber_admin/commands/set_room_affiliation.rb

@@ -2,19 +2,24 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Change an affiliation in a MUC room
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#set-room-affiliation-change-an-affiliation-in-a-muc-room
+    # Change a user affiliation in a MUC room. (eg. allow him to enter a
+    # members-only room)
+    #
+    # @see https://bit.ly/2G5MfbW
     class SetRoomAffiliation
-      # @param [name] Room name
-      # @param [service] MUC service
-      # @param [jid] User JID
-      # @param [affiliation] Affiliation to set
-      def self.call(name:, service:, jid:, affiliation:)
-        JabberAdmin::ApiCall.perform(
-          'set_room_affiliation',
-          name: name, service: service, jid: jid, affiliation: affiliation
-        )
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param user [String] user JID wo/ resource (eg. +tom@localhost+)
+      # @param room [String] room JID (eg. +room1@conference.localhost+)
+      # @param affiliation [String] the MUC/user affiliation (eg. +member+)
+      def self.call(callable, user:, room:, affiliation: 'member')
+        name, service = room.split('@')
+        callable.call('set_room_affiliation',
+                      name: name,
+                      service: service,
+                      jid: user,
+                      affiliation: affiliation)
       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/subscribe_room.rb

@@ -2,19 +2,26 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Subscribe to a MUC conference
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#subscribe-room-subscribe-to-a-muc-conference
+    # Subscribe to a MUC conference, via the mucsub feature.
+    #
+    # @see https://bit.ly/2Ke7Zoy
     class SubscribeRoom
-      # @param [user] Full JID, including some resource
-      # @param [nick] A user's nick
-      # @param [room] The room to subscribe
-      # @param [nodes] nodes
-      def self.call(user:, nick:, room:, nodes:)
-        JabberAdmin::ApiCall.perform(
-          'subscribe_room',
-          user: user, nick: nick, room: room, nodes: nodes
-        )
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param user [String] user JID w/ resource (eg. +tom@localhost/dummy+)
+      # @param nick [String] the user nickname (eg. +TomTom+)
+      # @param room [String] room JID (eg. +room1@conference.localhost+)
+      # @param nodes [Array<String>] nodes comma separated
+      #   (eg. +urn:xmpp:mucsub:nodes:messages+,
+      #   +urn:xmpp:mucsub:nodes:affiliations+)
+      def self.call(callable, user:, nick:, room:, nodes: [])
+        callable.call('subscribe_room',
+                      check_res_body: false,
+                      user: user,
+                      nick: nick,
+                      room: room,
+                      nodes: nodes.join(','))
       end
     end
   end

data/lib/jabber_admin/commands/unregister.rb

@@ -2,14 +2,20 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Unregister a user
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#unregister-unregister-a-user
+    # Unregister (delete) a user from the XMPP service.
+    #
+    # @see https://bit.ly/2wwYnDE
     class Unregister
-      # @param [user] The username
-      # @param [host] Local vhost served by ejabberd
-      def self.call(user:, host:)
-        JabberAdmin::ApiCall.perform 'unregister', user: user, host: host
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param user [String] user JID wo/ resource (eg. +tom@localhost+)
+      def self.call(callable, user:)
+        uid, host = user.split('@')
+        callable.call('unregister',
+                      check_res_body: false,
+                      user: uid,
+                      host: host)
       end
     end
   end

data/lib/jabber_admin/commands/unsubscribe_room.rb

@@ -2,14 +2,17 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Subscribe to a MUC conference
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#unsubscribe-room-unsubscribe-from-a-muc-conference
+    # Subscribe to a MUC conference, via the mucsub feature.
+    #
+    # @see https://bit.ly/2G5zcrj
     class UnsubscribeRoom
-      # @param [user] Full JID, including some resource
-      # @param [room] The room to subscribe
-      def self.call(user:, room:)
-        JabberAdmin::ApiCall.perform 'unsubscribe_room', user: user, room: room
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param user [String] user JID w/ resource (eg. +tom@localhost/dummy+)
+      # @param room [String] room JID (eg. +room1@conference.localhost+)
+      def self.call(callable, user:, room:)
+        callable.call('unsubscribe_room', user: user, room: room)
       end
     end
   end

data/lib/jabber_admin/configuration.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module JabberAdmin
+  # A JabberAdmin configuration definition. It is directly accessible via
+  # +JabberAdmin.configuration+ or
+  # +JabberAdmin.configure(&block(configuration))+ in a tapped variant.
+  #
+  # See the +JabberAdmin+ documentation for further details.
   class Configuration
-    attr_accessor :admin, :password, :api_host
+    attr_accessor :username, :password, :url
   end
 end

data/lib/jabber_admin/exceptions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  # The base exception which all other exceptions inherit. In case you want to
+  # use our error handling with the bang variants, you can rescue all
+  # exceptions like this:
+  #
+  #   begin
+  #     JabberAdmin.COMMAND!
+  #   rescue JabberAdmin::Error => err
+  #     # Do your error handling here
+  #   end
+  class Error < StandardError
+    attr_accessor :response
+
+    # Create a new exception.
+    #
+    # @param msg [String] the excpetion message
+    # @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
+
+  # This exception is raised when the request was denied due to premission
+  # issues or a general unavaliability of the command on the REST API. This
+  # simply means the response code from ejabberd was not 200 OK.
+  class RequestError < Error; end
+
+  # This exception is raised when the response from the ejabberd REST API
+  # indicated that the status of the command was not successful. In this case
+  # the response body includes a one (1). In case everything was fine, it
+  # includes a zero (0).
+  class CommandError < Error; end
+
+  # This exception is raised when we send an unknown command to the REST API.
+  # It will respond with a 404 status code in this case.
+  class UnknownCommandError < Error; end
+end

data/lib/jabber_admin/version.rb

@@ -1,5 +1,24 @@
 # frozen_string_literal: true
 
+# The gem module.
 module JabberAdmin
-  VERSION = "0.1.2"
+  # The version constant of the gem. Increase this value
+  # in case of a gem release.
+  VERSION = '1.0.1'
+
+  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

metadata

@@ -1,15 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: jabber_admin
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.1
 platform: ruby
 authors:
 - Henning Vogt
-autorequire: 
+- Hermann Mayer
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2018-01-17 00:00:00.000000000 Z
+date: 2020-10-13 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
@@ -31,91 +46,163 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 2.0.2
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
-  type: :runtime
+        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: '5'
+        version: '1.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: irb
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '1.2'
 - !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.93'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.93'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.43'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.43'
 - !ruby/object:Gem::Dependency
   name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
-description: Library for the Ejabberd RESTful admin API
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Library for the ejabberd RESTful admin API
 email:
 - henning.vogt@hausgold.de
+- hermann.mayer@hausgold.de
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".editorconfig"
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
+- ".simplecov"
 - ".travis.yml"
+- ".yardopts"
+- CHANGELOG.md
 - Gemfile
 - LICENSE
+- Makefile
 - README.md
 - Rakefile
+- bin/config.rb
 - bin/console
 - bin/setup
+- doc/assets/project.svg
+- docker-compose.yml
 - jabber_admin.gemspec
 - lib/jabber_admin.rb
 - lib/jabber_admin/api_call.rb
@@ -123,39 +210,46 @@ 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
 - lib/jabber_admin/commands/restart.rb
 - lib/jabber_admin/commands/send_direct_invitation.rb
+- lib/jabber_admin/commands/send_stanza.rb
+- lib/jabber_admin/commands/send_stanza_c2s.rb
+- 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
 - lib/jabber_admin/configuration.rb
-- lib/jabber_admin/initializer.rb
+- lib/jabber_admin/exceptions.rb
 - lib/jabber_admin/version.rb
 homepage: https://github.com/hausgold/jabber_admin
 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.6.11
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
-summary: Library for the Ejabberd RESTful admin API
+summary: Library for the ejabberd RESTful admin API
 test_files: []