jabber_admin 0.1.4 → 0.2.0

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/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

@@ -2,14 +2,16 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # List all registered users in HOST
+    # List all registered users on the ejabberd vhost.
     #
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#registered-users-list-all-registered-users-in-host
+    # @see https://bit.ly/2KhwT6Z
     class RegisteredUsers
-      # @param [host] The Local vhost
-      def self.call(host:)
-        JabberAdmin::ApiCall.perform 'registered_users', host: host
+      # 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

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

@@ -2,17 +2,19 @@
 
 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 stanza; provide From JID and valid To JID.
+    #
+    # @see https://bit.ly/2rzxyK1
     class SendStanza
-      # @param [from] Sender JID
-      # @param [to] Receiver JID
-      # @param [stanza] Stanza
-      def self.call(from:, to:, stanza:)
-        JabberAdmin::ApiCall.perform(
-          'send_stanza', to: to, from: from, stanza: stanza
-        )
+      # 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

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

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/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