grafana 0.8.2 → 1.0.0

data/lib/grafana/tools.rb

@@ -3,43 +3,67 @@ module Grafana
 
   module Tools
 
+    # return a slugged string for Grafana Dashboards
+    #
+    # @param text [String] text
+    #
+    # @example
+    #    slug( 'test dashboard' )
+    #
+    # @retunr [String]
+    #
     def slug( text )
 
       raise ArgumentError.new(format('wrong type. \'text\' must be an String, given \'%s\'', text.class.to_s)) unless( text.is_a?(String) )
 
       begin
-      if( text =~ /\s/ && text =~ /-/ )
+        if( text =~ /\s/ && text =~ /-/ )
 #        if( text =~ /-/ )
           text = text.gsub( /\s+/, '' )
         else
           text = text.gsub( /\s+/, '-' )
 #        end
-      end
+        end
 
-      rescue => e
-        puts e
+      rescue => error
+        puts error
       end
 
       text.downcase
     end
 
-
+    # regenerate Row Ids in the Dashboard
+    # usefull for an automatic generated Dashboard
+    #
+    # @param params [Hash] params
+    #
+    # @example
+    #    params = {
+    #      dashboard: {
+    #        rows: [
+    #
+    #        ]
+    #      }
+    #    }
+    #    regenerate_template_ids( params )
+    #
+    # @return [Hash]
+    #
     def regenerate_template_ids( params )
 
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
 
       rows = params.dig('dashboard','rows')
+      # name   = validate( params, required: true, var: 'name', type: String )
 
       unless( rows.nil? )
 
         # counter = 1
         id_counter = 10
         rows.each_with_index do |r, _counter|
-
           panel = r.dig('panels')
-
           next if( panel.nil? )
-
           panel.each do |p|
             p['id']   = id_counter
             id_counter = id_counter +=1 # id_counter+1 # id_counter +=1 ??
@@ -50,17 +74,25 @@ module Grafana
       JSON.generate( params )
     end
 
-
+    # check, it an String a valid Json
+    #
+    # @param json [String] json
+    #
+    # @example
+    #   valid_json?( json )
+    #
+    # @return [Boolean]
+    #
     def valid_json?( json )
       begin
         JSON.parse( json )
         return true
-      rescue JSON::ParserError => e
-        @logger.error("json parse error: #{e}") if @debug
+      rescue JSON::ParserError => error
+        @logger.error("json parse error: #{error}") if @debug
         return false
       end
     end
 
-  end
 
+  end
 end

data/lib/grafana/user.rb

@@ -6,7 +6,12 @@ module Grafana
   module User
 
     # Actual User
-    # GET /api/user
+    #
+    # @example
+    #    current_user
+    #
+    # @return [Hash]
+    #
     def current_user
       endpoint = '/api/user'
       @logger.debug("Getting user current user (GET #{endpoint})") if @debug
@@ -14,36 +19,51 @@ module Grafana
     end
 
     # Change Password
-    # PUT /api/user/password
+    #
+    # @param [Hash] params
+    # @option params [String] old_password the old password
+    # @option params [String] new_password the new password
+    #
+    # @example
+    #    update_current_user_password( old_password: 'foo', new_password: 'FooBar' )
+    #
+    # @return [Hash]
+    #
     def update_current_user_password( params )
 
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
 
-      old_password = params.dig(:old_password)
-      new_password = params.dig(:new_password)
-
-      raise ArgumentError.new('missing old_password for update') if( old_password.nil? )
-      raise ArgumentError.new('missing new_password for update') if( new_password.nil? )
+      old_password   = validate( params, required: true, var: 'old_password', type: String )
+      new_password   = validate( params, required: true, var: 'new_password', type: String )
 
       endpoint = '/api/user/password'
+      payload = {
+        oldPassword: old_password,
+        newPassword: new_password,
+        confirmNew: new_password
+      }
       @logger.debug("Updating current user password (PUT #{endpoint})") if @debug
-      put( endpoint, { oldPassword: old_password, newPassword: new_password, confirmNew: new_password }.to_json )
+      put( endpoint, payload.to_json )
     end
 
     # Switch user context for signed in user
-    # POST /api/user/using/:organizationId
+    #
+    # @param organization [String ] organization
+    #
+    # @example
+    #    switch_current_user_organization( 'Main. Org' )
+    #
+    # @return [Hash]
+    #
     def switch_current_user_organization( organization )
 
-      raise ArgumentError.new('organization must be an String') unless( params.is_a?(String) )
+      raise ArgumentError.new(format('wrong type. \'organization\' must be an String, given \'%s\'', organization.class.to_s)) unless( organization.is_a?(String) )
+      raise ArgumentError.new('missing \'organization\'') if( organization.size.zero? )
 
       org = organization_by_name( organization )
 
-      if  org.nil? || org.dig('status').to_i != 200
-        return {
-          'status' => 404,
-          'message' => format('Organization \'%s\' not found', organization)
-        }
-      end
+      return { 'status' => 404, 'message' => format('Organization \'%s\' not found', organization) } if( org.nil? || org.dig('status').to_i != 200 )
 
       org_id = org.dig('id')
 
@@ -54,52 +74,71 @@ module Grafana
     end
 
     # Organisations of the actual User
-    # GET /api/user/orgs
+    #
+    # @example
+    #    current_user_oganizations
+    #
+    # @return [Hash]
+    #
     def current_user_oganizations
-
       endpoint = '/api/user/orgs'
       @logger.debug("Getting current user organizations (GET #{endpoint})") if @debug
       get(endpoint)
     end
 
     # Star a dashboard
-    # POST /api/user/stars/dashboard/:dashboardId
-    def add_dashboard_star( dashboard )
-
-      if( !dashboard.is_a?(String) && !dashboard.is_a?(Integer) )
-        raise ArgumentError.new('dashboard must be an String (for an Dashboard name) or an Integer (for an Dashboard ID)')
+    #
+    # @param [Mixed] dashboard_id Dashboard Name (String) or Dashboard Id (Integer) for add a star
+    #
+    # @example
+    #    add_dashboard_star( 1 )
+    #    add_dashboard_star( 'QA Graphite Carbon Metrics' )
+    #
+    # @return [Hash]
+    #
+    def add_dashboard_star( dashboard_id )
+
+      if( dashboard_id.is_a?(String) && dashboard_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'dashboard_id\' must be an String (for an Dashboard name) or an Integer (for an Dashboard Id), given \'%s\'', dashboard_id.class.to_s))
       end
+      raise ArgumentError.new('missing \'dashboard_id\'') if( dashboard_id.size.zero? )
 
-      dashboard_id = dashboard if(dashboard.is_a?(Integer))
+      dashboard_id = dashboard if(dashboard_id.is_a?(Integer))
 
-      if(dashboard.is_a?(String))
-        search = { query: dashboard }
-        r = search_dashboards( search )
+      if(dashboard_id.is_a?(String))
+        r = search_dashboards( query: dashboard_id )
         message = r.dig('message')
         dashboard_id = message.first.dig('id')
       end
 
-      raise format('Dashboard id can not be 0') if  dashboard_id.zero?
+      raise format('Dashboard Id can not be 0') if( dashboard_id.zero? )
 
       endpoint = format( '/api/user/stars/dashboard/%d', dashboard_id )
       @logger.debug("Adding star to dashboard id #{dashboard_id} (GET #{endpoint})") if @debug
-      post(endpoint, {}.to_json)
+      post( endpoint, {}.to_json )
     end
 
     # Unstar a dashboard
-    # DELETE /api/user/stars/dashboard/:dashboardId
-    def remove_dashboard_star( dashboard )
-
-      if( !dashboard.is_a?(String) && !dashboard.is_a?(Integer) )
-        raise ArgumentError.new('dashboard must be an String (for an Dashboard name) or an Integer (for an Dashboard ID)')
+    #
+    # @param [Mixed] dashboard_id Dashboard Name (String) or Dashboard Id (Integer) for delete a star
+    #
+    # @example
+    #    remove_dashboard_star( 1 )
+    #    remove_dashboard_star( 'QA Graphite Carbon Metrics' )
+    #
+    # @return [Hash]
+    #
+    def remove_dashboard_star( dashboard_id )
+
+      if( dashboard_id.is_a?(String) && dashboard_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'dashboard_id\' must be an String (for an Dashboard name) or an Integer (for an Dashboard Id), given \'%s\'', dashboard_id.class.to_s))
       end
+      raise ArgumentError.new('missing \'dashboard_id\'') if( dashboard_id.size.zero? )
 
-      dashboard_id = dashboard if(dashboard.is_a?(Integer))
-
-      if(dashboard.is_a?(String))
+      dashboard_id = dashboard( dashboard_id ) if(dashboard_id.is_a?(Integer))
 
-        search = { query: dashboard }
-        r = search_dashboards( search )
+      if(dashboard_id.is_a?(String))
+        r = search_dashboards( query: dashboard_id )
         message = r.dig('message')
         dashboard_id = message.first.dig('id')
       end

data/lib/grafana/users.rb

@@ -5,113 +5,164 @@ module Grafana
   #
   module Users
 
-    # Search Users
-    # GET /api/users
-    def all_users
+    # All Users
+    #
+    # @example
+    #    all_users
+    #
+    # @return [Hash]
+    #
+    def users
       endpoint = '/api/users'
       @logger.debug("Getting all users (GET #{endpoint})") if @debug
       get(endpoint)
     end
 
-    # Get single user by Id
-    # GET /api/users/:id
-    def user_by_id(id)
+    # Get a single user by Id or Name
+    #
+    # @param [Mixed] user_id Username (String) or Userid (Integer)
+    #
+    # @example
+    #    user( 1 )
+    #    user( 'foo' )
+    #
+    # @return [Hash]
+    #
+    def user( user_id )
+
+      if( user_id.is_a?(String) && user_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. user \'user_id\' must be an String (for an User name) or an Integer (for an User Id), given \'%s\'', user_id.class.to_s))
+      end
+      raise ArgumentError.new('missing \'user_id\'') if( user_id.size.zero? )
 
-      raise ArgumentError.new('id must be an Integer') unless( id.is_a?(Integer) )
+      if(user_id.is_a?(String))
+        usrs  = users
+        usrs  = JSON.parse(usrs) if(usrs.is_a?(String))
 
-      endpoint = format( '/api/users/%d', id )
-      @logger.debug("Getting user by Id #{id} (GET #{endpoint})") if @debug
-      get(endpoint)
-    end
+        status = usrs.dig('status')
+        return usrs if( status != 200 )
+
+        u = usrs.dig('message').detect { |v| v['login'] == user_id || v['email'] == user_id || v['name'] == user_id }
+
+        return { 'status' => 404, 'message' => format( 'No User \'%s\' found', user_id) } if( u.nil? )
+
+        user_id = u.dig('id') unless(u.nil?)
+      end
+
+      return { 'status' => 404, 'message' => format( 'No User \'%s\' found', user_id) } if( user_id.nil? )
 
-    # Get single user by Username(login) or Email
-    # GET /api/users/lookup?loginOrEmail=user@mygraf.com
-    def user_by_name( name )
+      endpoint = format( '/api/users/%s', user_id )
 
-      endpoint = format( '/api/users/lookup?loginOrEmail=%s', URI.escape( name ) )
-      @logger.debug("Get User by Name (GET #{endpoint})") if @debug
-      get( endpoint )
+      @logger.debug("Getting user by Id #{user_id} (GET #{endpoint})") if @debug
+      data = get(endpoint)
+      data['id'] = user_id
+      data
     end
 
+    # search users with parameters
     #
+    # @example
+    #    search_for_users_by( isAdmin: true )
+    #    search_for_users_by( login: 'foo' )
+    #
+    # @return [Array of Hashes] or false
     #
     def search_for_users_by( params )
 
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
 
-      all_users = self.all_users()
+      all_users = users
       key, value = params.first
 
       logger.debug("Searching for users matching '#{key}' = '#{value}'") if @debug
       users = []
-
       all_users.dig('message').each do |u|
         users.push(u) if u.select { |_k,v| v == value }.count >= 1
       end
 
-      (users.length >= 1 ? users : false)
+      (users.length >= 1 ? users : nil)
     end
 
     # User Update
+    #
+    # @param [Hash] params
+    # @option params [String] email
+    # @option params [String] user_name
+    # @option params [String] login_name
+    # @option params [String] theme
+    #
+    # @example
+    #    params = {
+    #      email:'user@mygraf.com',
+    #      user_name:'User2',
+    #      login_name:'user',
+    #      theme: 'light'
+    #    }
+    #    update_user( params )
+    #
+    # @return [Hash]
+    #
     # PUT /api/users/:id
-    def update_user( params = {} )
+    def update_user( params )
 
       raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
 
-      user_name   = params.dig(:user_name)
+      user_name  = validate( params, required: true , var: 'user_name' , type: String )
+      email      = validate( params, required: true , var: 'email'     , type: String )
+      login_name = validate( params, required: false, var: 'login_name', type: String ) || user_name
+      theme      = validate( params, required: false, var: 'theme'     , type: String )
 
-      raise ArgumentError.new('missing \'user_name\'') if( user_name.nil? )
-
-      if( !user_name.is_a?(String) && !user_name.is_a?(Integer) )
-        raise ArgumentError.new('user_name must be an String (for an Username) or an Integer (for an User Id)')
-      end
+      usr = user(user_name)
 
-      usr = user_by_id(user_name) if(user_name.is_a?(Integer))
-      usr = user_by_name(user_name) if(user_name.is_a?(String))
-
-      if  usr.nil? || usr.dig('status').to_i != 200
-        return {
-          'status' => 404,
-          'message' => format('User \'%s\' not found', user_name)
-        }
-      end
+      return { 'status' => 404, 'message' => format('User \'%s\' not found', user_name) } if( usr.nil? || usr.dig('status').to_i != 200 )
 
       user_id = usr.dig('id')
 
       endpoint = format( '/api/users/%d', user_id )
+      payload = {
+        email: email,
+        name: user_name,
+        login: login_name,
+        theme: theme
+      }
+      payload.reject!{ |_k, v| v.nil? }
 
       @logger.debug("Updating user with Id #{user_id}") if @debug
 
-      usr    = usr.deep_string_keys
-      params = params.deep_string_keys
+      usr     = usr.deep_string_keys
+      payload = payload.deep_string_keys
 
-      params = usr.merge(params)
+      payload = usr.merge(payload)
 
-      put( endpoint, params.to_json )
+      put( endpoint, payload.to_json )
     end
 
     # Get Organisations for user
-    # GET /api/users/:id/orgs
-    def user_organizations(user)
+    #
+    # @param [Mixed] user_id Username (String) or Userid (Integer)
+    #
+    # @example
+    #    user_organizations( 1 )
+    #    user_organizations( 'foo' )
+    #
+    # @return [Hash]
+    #
+    def user_organizations( user_id )
 
-      if( !user.is_a?(String) && !user.is_a?(Integer) )
-        raise ArgumentError.new('user must be an String (for an Dashboard name) or an Integer (for an Dashboard ID)')
+      if( user_id.is_a?(String) && user_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. user \'user_id\' must be an String (for an Username) or an Integer (for an Userid), given \'%s\'', user_id.class.to_s))
       end
+      raise ArgumentError.new('missing \'user_id\'') if( user_id.size.zero? )
 
-      usr = user_by_id(user) if(user.is_a?(Integer))
-      usr = user_by_name(user) if(user.is_a?(String))
+      usr = user(user_id)
 
-      if  usr.nil? || usr.dig('status').to_i != 200
-        return {
-          'status' => 404,
-          'message' => format('User \'%s\' not found', user)
-        }
-      end
+      return { 'status' => 404, 'message' => format('User \'%s\' not found', user_id) } if( usr.nil? || usr.dig('status').to_i != 200 )
 
       user_id = usr.dig('id')
 
       endpoint = format('/api/users/%d/orgs', user_id )
-      @logger.debug("Getting organizations for User #{user} (GET #{endpoint})") if @debug
+      @logger.debug("Getting organizations for User #{user_id} (GET #{endpoint})") if @debug
       get(endpoint)
     end