jabber_admin 0.1.1 → 1.0.0

data/lib/jabber_admin/commands/ban_account.rb

@@ -2,17 +2,18 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Ban an account: kick sessions and set random password
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#ban-account-ban-an-account-kick-sessions-and-set-random-password
+    # Ban an account by kicking sessions and set random password.
+    #
+    # @see https://bit.ly/2KW9xVt
     class BanAccount
-      # @param [user] The user
-      # @param [host] Server name
-      # @param [reason] Reason for banning user
-      def self.call(user:, host:, reason:)
-        JabberAdmin::ApiCall.perform(
-          'ban_account', user: user, host: host, reason: reason
-        )
+      # 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 reason [String] the banning reason (eg. +Spamming other users+)
+      def self.call(callable, user:, reason:)
+        uid, host = user.split('@')
+        callable.call('ban_account', user: uid, host: host, reason: reason)
       end
     end
   end

data/lib/jabber_admin/commands/create_room.rb

@@ -2,17 +2,22 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Create a MUC room name@service in host
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#create-room-create-a-muc-room-name-service-in-host
+    # Create a new room (MUC).
+    #
+    # @see https://bit.ly/2rB8DFR
     class CreateRoom
-      # @param [name] The room name
-      # @param [service] MUC service
-      # @param [host] Server host
-      def self.call(name:, service:, host:)
-        JabberAdmin::ApiCall.perform(
-          'create_room', name: name, service: service, host: host
-        )
+      # Pass the correct data to the given callable.
+      #
+      # *Note:* this command should not be used in the bang-variant, due to raw
+      # result string in the response. (the response body is not zero/one like
+      # on almost all commands)
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param room [String] room JID (eg. +room1@conference.localhost+)
+      # @param host [String] the jabber host (eg. +localhost+)
+      def self.call(callable, room:, host:)
+        name, service = room.split('@')
+        callable.call('create_room', name: name, service: service, host: host)
       end
     end
   end

data/lib/jabber_admin/commands/create_room_with_opts.rb

@@ -2,21 +2,27 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Create a MUC room name@service in host
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#create-room-with-opts-create-a-muc-room-name-service-in-host-with-given-options
+    # Create a new room (MUC) with additional options.
+    #
+    # @see https://bit.ly/2IBEfVO
     class CreateRoomWithOpts
-      # @param [name] The room name
-      # @param [service] MUC service
-      # @param [host] Server host
-      # @param [options] [{ Name::String, Value::String }] List of options
-      def self.call(name:, service:, host:, options:)
-        JabberAdmin::ApiCall.perform(
-          'create_room_with_opts', name: name,
-                                   service: service,
-                                   host: host,
-                                   options: options
-        )
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param room [String] room JID (eg. +room1@conference.localhost+)
+      # @param host [String] the jabber host (eg. +localhost+)
+      # @param options pass additional +symbol: value+ pairs
+      def self.call(callable, room:, host:, **options)
+        name, service = room.split('@')
+        options = options.map do |key, value|
+          Hash['name', key.to_s, 'value', value.to_s]
+        end
+
+        callable.call('create_room_with_opts',
+                      name: name,
+                      service: service,
+                      host: host,
+                      options: options)
       end
     end
   end

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 = JSON.parse(callable.call(meth, check_res_body: false,
+                                               user: uid,
+                                               host: host,
+                                               **args).body)
+
+          res.is_a?(Hash) ? res['content'] : res
+        rescue JabberAdmin::CommandError => 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'
+
+          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/muc_register_nick.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  module Commands
+    # Register a nick to a user JID in the MUC service of a server.
+    #
+    # *Note*: On ejabberd <= 18.01 this command always returns a error code,
+    # even when the command was successful under the hood. (See:
+    # https://bit.ly/2L1CpvE)
+    #
+    # @see https://bit.ly/2G9EBNQ
+    class MucRegisterNick
+      # 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 nick [String] the user nickname (eg. +TomTom+)
+      def self.call(callable, user:, nick:)
+        callable.call('muc_register_nick',
+                      nick: nick,
+                      jid: user,
+                      serverhost: user.split('@').last)
+      end
+    end
+  end
+end

data/lib/jabber_admin/commands/register.rb

@@ -2,18 +2,23 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Register a user
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#register-register-a-user
+    # Register a new user on the XMPP service.
+    #
+    # @see https://bit.ly/2wyhAox
     class Register
-      # @param [user] The username
-      # @param [host] Local vhost served by ejabberd
-      # @param [password] The password
-      def self.call(user:, host:, password:)
-        JabberAdmin::ApiCall.perform(
-          'register',
-          user: user, host: host, password: password
-        )
+      # 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 password [String] the new plain password for the user
+      #   (eg. +secret+)
+      def self.call(callable, user:, password:)
+        uid, host = user.split('@')
+        callable.call('register',
+                      check_res_body: false,
+                      user: uid,
+                      host: host,
+                      password: password)
       end
     end
   end

data/lib/jabber_admin/commands/registered_users.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  module Commands
+    # List all registered users on the ejabberd vhost.
+    #
+    # @see https://bit.ly/2KhwT6Z
+    class RegisteredUsers
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param host [String] the jabber vhost (eg. +localhost+)
+      def self.call(callable, host:)
+        callable.call('registered_users', check_res_body: false, host: host)
+      end
+    end
+  end
+end

data/lib/jabber_admin/commands/restart.rb

@@ -2,12 +2,15 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Restart ejabberd gracefully
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#restart-restart-ejabberd-gracefully
+    # Restart ejabberd service gracefully.
+    #
+    # @see https://bit.ly/2G7YEwd
     class Restart
-      def self.call
-        JabberAdmin::ApiCall.perform 'restart'
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      def self.call(callable)
+        callable.call('restart')
       end
     end
   end

data/lib/jabber_admin/commands/send_direct_invitation.rb

@@ -2,23 +2,26 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Password and Message can also be: none. Users JIDs are separated with :
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#send-direct-invitation-send-a-direct-invitation-to-several-destinations
+    # Send a direct invitation to several destinations.
+    #
+    # @see https://bit.ly/2wuTpr2
     class SendDirectInvitation
-      # @param [name] The room name
-      # @param [service] MUC service
-      # @param [password] Password, or none
-      # @param [reason] The reason text, or none
-      # @param [users] Users JIDs
-      def self.call(name:, service:, password:, reason:, users:)
-        joined_users = users.join(':')
-
-        JabberAdmin::ApiCall.perform(
-          'send_direct_invitation',
-          name: name, service: service, password: password, reason: reason,
-          users: joined_users
-        )
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param room [String] room JID (eg. +room1@conference.localhost+)
+      # @param users [Array<String>] user JIDs wo/ resource
+      #   (eg. +tom@localhost+)
+      # @param password [String] a optional room password
+      # @param reason [String] the reason for the invitation
+      def self.call(callable, room:, users:, password: '', reason: '')
+        name, service = room.split('@')
+        callable.call('send_direct_invitation',
+                      name: name,
+                      service: service,
+                      password: password,
+                      reason: reason,
+                      users: users.join(':'))
       end
     end
   end

data/lib/jabber_admin/commands/send_stanza.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  module Commands
+    # Send a stanza; provide From JID and valid To JID.
+    #
+    # @see https://bit.ly/2rzxyK1
+    class SendStanza
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param from [String] user JID wo/ resource (eg. +tom@localhost+)
+      # @param to [String] user/room JID wo/ resource (eg. +bob@localhost+)
+      # @param stanza [String] the XML stanz to send
+      #   (eg. <tt><message><ext attr='value'/></message></tt>)
+      def self.call(callable, from:, to:, stanza:)
+        callable.call('send_stanza', from: from, to: to, stanza: stanza)
+      end
+    end
+  end
+end

data/lib/jabber_admin/commands/send_stanza_c2s.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  module Commands
+    # Send a message (stanza) as if sent from a c2s session.
+    #
+    # @see https://bit.ly/2wwUcYr
+    class SendStanzaC2s
+      # 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/bot+)
+      # @param stanza [String] the XML stanz to send
+      #   (eg. <tt><message to='user1@localhost'>
+      #   <ext attr='value'/></message></tt>)
+      def self.call(callable, user:, stanza:)
+        uid, host = user.split('@')
+        host, resource = host.split('/')
+        resource ||= 'bot'
+        callable.call('send_stanza_c2s',
+                      user: uid,
+                      host: host,
+                      resource: resource,
+                      stanza: stanza)
+      end
+    end
+  end
+end

data/lib/jabber_admin/commands/set_nickname.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  module Commands
+    # Set nickname in a user's vCard.
+    #
+    # @see https://bit.ly/2rBdyqc
+    class SetNickname
+      # 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 nick [String] the user nickname (eg. +TomTom+)
+      def self.call(callable, user:, nick:)
+        uid, host = user.split('@')
+        callable.call(
+          'set_nickname', user: uid, host: host, nickname: nick
+        )
+      end
+    end
+  end
+end

data/lib/jabber_admin/commands/set_presence.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module JabberAdmin
+  module Commands
+    # Send a stanza; provide From JID and valid To JID.
+    #
+    # @see https://bit.ly/2rzxyK1
+    class SetPresence
+      # @param callable [Proc, #call] the callable to call
+      # @param user [String] user JID w/ resource (eg. +tom@localhost/bot+)
+      # @param type [String] the presence type
+      #   (eg. +available+, +error+, +probe+)
+      # @param show [String] the showed presence
+      #   (eg. +away+, +chat+, +dnd+, +xa+)
+      # @param status [String] the user status (eg. +I'm online+)
+      # @param priority [String] presence priority (eg. +7+)
+      #
+      # rubocop:disable Metrics/ParameterLists because of the mapping
+      # rubocop:disable Metrics/MethodLength because of the mapping
+      def self.call(callable, user:, type: 'available', show: 'chat',
+                    status: '', priority: '7')
+        uid, host = user.split('@')
+        host, resource = host.split('/')
+        resource ||= 'bot'
+        callable.call('set_presence',
+                      user: uid,
+                      host: host,
+                      resource: resource,
+                      type: type,
+                      show: show,
+                      status: status,
+                      priority: priority)
+      end
+      # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
+    end
+  end
+end