zkt_client 0.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/generators/zkt_client/USAGE

@@ -0,0 +1 @@
+rails generate zkt_client:install

data/lib/generators/zkt_client/install_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "zkt_client"
+
+module ZktClient
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "This generator creates an initializer file at config/initializers, " \
+           "with the default configuration options for ZktClient."
+      source_root File.expand_path("templates", __dir__)
+
+      # copy rake tasks
+      def copy_tasks
+        template "configure_template.rake", "config/initializers/zkt_client.rb"
+      end
+    end
+  end
+end

data/lib/generators/zkt_client/templates/configure_template.rake

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+ZktClient.configure do |config|
+  # ZktClient configurations
+  # config.host = 'http://localhost:3000'     # Required
+  # config.username = 'admin'                 # Required unless access_token is set
+  # config.password = 'admin'                 # Required unless access_token is set
+  # config.access_token = 'YOUR_ACCESS_TOKEN' # Required unless username and password are set
+  # config.is_object_response_enabled = true  # Optional default is false
+end

data/lib/zkt_client/access_token.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# require_relative "zkt_client/http_client"
+
+module ZktClient
+  # AccessToken class handles the retrieval of access token
+  class AccessToken
+    BASE_URL = "/api-token-auth/"
+
+    # Calls the access token retrieval
+    #
+    # @return [String] the access token prefixed with "Token "
+    def call
+      "Token #{access_token}"
+    end
+
+    private
+
+    # Retrieves the access token from the server
+    #
+    # @return [String] the access token
+    def access_token
+      HttpClient.post(url: BASE_URL, params:)["token"]
+    end
+
+    # Constructs the parameters for the access token request
+    #
+    # @return [Hash] the parameters including username and password
+    def params
+      {
+        username: ZktClient.username,
+        password: ZktClient.password
+      }
+    end
+  end
+end

data/lib/zkt_client/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module ZktClient
+  # Configuration class handles the configuration settings for ZktClient
+  class Configuration
+    include Singleton
+
+    attr_writer :host, :username, :password, :access_token, :is_object_response_enabled
+
+    # Retrieves the host configuration
+    #
+    # @return [String, nil] the host or nil if not set
+    def host
+      @host || ENV["ZKT_CLIENT_HOST"]
+    end
+
+    # Retrieves the username configuration
+    #
+    # @return [String, nil] the username or nil if not set
+    def username
+      @username || ENV["ZKT_CLIENT_USERNAME"]
+    end
+
+    # Retrieves the password configuration
+    #
+    # @return [String, nil] the password or nil if not set
+    def password
+      @password || ENV["ZKT_CLIENT_PASSWORD"]
+    end
+
+    # Retrieves the access token configuration
+    #
+    # @return [String, nil] the access token or nil if not set
+    def access_token
+      @access_token || ENV["ZKT_CLIENT_ACCESS_TOKEN"]
+    end
+
+    # Checks if object response is enabled
+    #
+    # @return [Boolean] true if object response is enabled, false otherwise
+    def with_object_response?
+      @is_object_response_enabled || ENV["ZKT_OBJECT_RESPONSE_ENABLED"] || false
+    end
+
+    # Checks if the client is configured
+    #
+    # @return [Boolean] true if the client is configured, false otherwise
+    def configured?
+      host.present? &&
+        (access_token.present? || (username.present? && password.present?))
+    end
+  end
+end

data/lib/zkt_client/exceptions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ZktClient
+  class Error < StandardError; end
+  class MissingConfigurationError < Error; end
+  class RecordNotFound < Error; end
+  class BadRequestError < Error; end
+  class UnprocessableEntityError < Error; end
+  class ServerError < Error; end
+  class RequestFailedError < Error; end
+end

data/lib/zkt_client/http_client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module ZktClient
+  # HttpClient class handles HTTP requests for ZktClient
+  class HttpClient
+    class << self
+      # Makes a GET HTTP request
+      #
+      # @param url [String] the URL to send the request to
+      # @param headers [Hash] the headers to include in the request
+      # @param params [Hash] the query parameters to include in the request
+      # @return [Hash] the response body
+      def get(url:, headers:, params: {})
+        do_request(:get, url, params:, headers:)
+      end
+
+      # Makes a POST HTTP request
+      #
+      # @param url [String] the URL to send the request to
+      # @param params [Hash] the body of the request
+      # @param headers [Hash] the headers to include in the request
+      # @return [Hash] the response body
+      def post(url:, params:, headers: {})
+        do_request(:post, url, body: params, headers:)
+      end
+
+      # Makes a PUT HTTP request
+      #
+      # @param url [String] the URL to send the request to
+      # @param params [Hash] the body of the request
+      # @param headers [Hash] the headers to include in the request
+      # @return [Hash] the response body
+      def put(url:, params:, headers:)
+        do_request(:put, url, body: params, headers:)
+      end
+
+      # Makes a DELETE HTTP request
+      #
+      # @param url [String] the URL to send the request to
+      # @param headers [Hash] the headers to include in the request
+      # @return [Hash] the response body
+      def delete(url:, headers:)
+        do_request(:delete, url, headers:)
+      end
+
+      private
+
+      # Makes an HTTP request
+      #
+      # @param method [Symbol] the HTTP method to use (:get, :post, :put, :delete)
+      # @param url [String] the URL to send the request to
+      # @param params [Hash] the query parameters to include in the request
+      # @param body [Hash] the body of the request
+      # @param headers [Hash] the headers to include in the request
+      # @return [Hash] the response body
+      def do_request(method, url, params: {}, body: {}, headers: {})
+        uri = ZktClient.host + url
+
+        request = connection.public_send(method, uri) do |req|
+          req.headers = headers if headers.present?
+          req.body = body if body.present?
+          req.body = req.body.to_json if headers.present?
+          req.params = params if params.present?
+        end
+
+        validate_status!(request) unless request.success?
+        request.body
+      end
+
+      # Establishes a Faraday connection
+      #
+      # @return [Faraday::Connection] the Faraday connection
+      def connection
+        Faraday.new do |conn|
+          conn.request :url_encoded
+          conn.response :json
+          # conn.options[:timeout] = ZktClient.timeout
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # Validates the status of the HTTP response
+      #
+      # @param request [Faraday::Response] the HTTP response
+      # @raise [ZktClient::RecordNotFound] if the response status is 404
+      # @raise [ZktClient::BadRequestError] if the response status is 400
+      # @raise [ZktClient::UnprocessableEntityError] if the response status is 422
+      # @raise [ZktClient::ServerError] if the response status is 500-599
+      # @raise [ZktClient::RequestFailedError] for other response statuses
+      def validate_status!(request)
+        response = request.body
+
+        case request.status
+        when 404
+          raise(ZktClient::RecordNotFound, response)
+        when 400
+          raise(ZktClient::BadRequestError, response)
+        when 422
+          raise(ZktClient::UnprocessableEntityError, response)
+        when 500..599
+          raise(ZktClient::ServerError, response)
+        else
+          raise(ZktClient::RequestFailedError, response)
+        end
+      end
+    end
+  end
+end
+

data/lib/zkt_client/models/area.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ZktClient
+  # Area class handles operations related to areas in the ZktClient
+  class Area < Base
+    # URL endpoints for the Area resource
+    URLS = { base: "/personnel/api/areas/" }.freeze
+
+    # Required fields for creating or updating an Area resource
+    REQUIRED_FEILDS = %i[area_code area_name].freeze
+  end
+end

data/lib/zkt_client/models/base.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../models/concerns/helperable"
+require_relative "../models/concerns/validatable"
+
+module ZktClient
+  # Base class for ZktClient module
+  class Base
+    extend Helperable
+    extend Validatable
+
+    class << self
+      # Shows the details of a specific resource by ID
+      #
+      # @param id [Integer] the ID of the resource
+      # @return [Hash] the response from the server
+      def show(id)
+        response = HttpClient.get(url: url_with_id(id), headers:)
+
+        build_response(response)
+      end
+
+      # Lists all resources with optional parameters
+      #
+      # @param params [Hash] optional parameters for filtering the list
+      # @return [Array<Hash>] the list of resources
+      def list(**params)
+        response = HttpClient.get(url: self::URLS[:base], headers:, params:)
+
+        build_response(response)
+      end
+
+      # Creates a new resource with the given parameters
+      #
+      # @param params [Hash] the parameters for creating the resource
+      # @return [Hash] the response from the server
+      def create(params)
+        validate_create_params!(params)
+        response = HttpClient.post(url: self::URLS[:base], headers:, params:)
+
+        build_response(response)
+      end
+
+      # Updates an existing resource by ID with the given parameters
+      #
+      # @param id [Integer] the ID of the resource
+      # @param params [Hash] the parameters for updating the resource
+      # @return [Hash] the response from the server
+      def update(id, params)
+        validate_update_params!(params)
+        response = HttpClient.put(url: url_with_id(id), headers:, params:)
+
+        build_response(response)
+      end
+
+      # Deletes a resource by ID
+      #
+      # @param id [Integer] the ID of the resource
+      # @return [Boolean] true if the resource was successfully deleted
+      def delete(id)
+        HttpClient.delete(url: url_with_id(id), headers:)
+
+        true
+      end
+    end
+  end
+end

data/lib/zkt_client/models/concerns/helperable.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module ZktClient
+  # Helperable module provides utility methods for ZktClient
+  module Helperable
+    private
+
+    # Validates the parameters for creating a resource
+    #
+    # @param params [Hash] the parameters to validate
+    # @raise [ArgumentError] if required fields are missing or blank
+    def validate_create_params!(params)
+      self::REQUIRED_FEILDS.each do |field|
+        validate!(params, field, required: true, blank: false)
+      end
+
+      params.except(*self::REQUIRED_FEILDS).each_key do |field|
+        validate!(params, field.to_sym, blank: false)
+      end
+    end
+
+    # Validates the parameters for updating a resource
+    #
+    # @param params [Hash] the parameters to validate
+    # @raise [ArgumentError] if any fields are blank
+    def validate_update_params!(params)
+      params.each_key do |field|
+        validate!(params, field.to_sym, blank: false)
+      end
+    end
+
+    # Builds the response from the server
+    #
+    # @param response [Hash] the response from the server
+    # @return [Array<OpenStruct>, Hash] the processed response
+    def build_response(response)
+      return response unless ZktClient.with_object_response?
+
+      if response["data"].is_a?(Array)
+        response["data"].map { |hash| init_object(hash) }
+      else
+        init_object(response)
+      end
+    end
+
+    # Initializes an OpenStruct object from a hash
+    #
+    # @param hash [Hash] the hash to convert to an OpenStruct object
+    # @return [OpenStruct] the initialized OpenStruct object
+    def init_object(hash)
+      OpenStruct.new(hash)
+    end
+
+    # Retrieves the access token for the API
+    #
+    # @raise [ZktClient::MissingConfigurationError] if the client is not configured
+    # @return [String] the access token
+    def access_token
+      raise(ZktClient::MissingConfigurationError, "Configurations are missing!") unless ZktClient.configured?
+
+      ZktClient.access_token || AccessToken.new.call
+    end
+
+    # Constructs a URL with the given resource ID
+    #
+    # @param id [Integer] the ID of the resource
+    # @return [String] the constructed URL
+    def url_with_id(id)
+      "#{self::URLS[:base]}#{id}/"
+    end
+
+    # Generates the headers for the HTTP request
+    #
+    # @return [Hash] the headers for the request
+    def headers
+      {
+        "Content-Type" => "application/json",
+        "Authorization" => access_token
+      }
+    end
+  end
+end

data/lib/zkt_client/models/concerns/validatable.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ZktClient
+  # Validatable module provides validation methods for ZktClient
+  module Validatable
+    private
+
+    # Validates the given parameters based on the provided options
+    #
+    # @param params [Hash] the parameters to validate
+    # @param attribute [Symbol] the attribute to validate
+    # @param options [Hash] the validation options
+    # @option options [Boolean] :required whether the attribute is required
+    # @option options [Boolean] :blank whether the attribute can be blank
+    # @option options [Class] :type the expected type of the attribute
+    # @option options [Array] :in the allowed values for the attribute
+    # @raise [ArgumentError] if validation fails
+    # @return [void]
+    def validate!(params, attribute, **options)
+      raise(ArgumentError, "Params must be hash") unless params.is_a?(Hash)
+
+      validate_required!(params, attribute, options)
+      validate_blank!(params, attribute, options)
+      validate_value!(params, attribute, options)
+      validate_type!(params, attribute, options)
+    end
+
+    # Validates that the attribute is present if required
+    #
+    # @param params [Hash] the parameters to validate
+    # @param attribute [Symbol] the attribute to validate
+    # @param options [Hash] the validation options
+    # @option options [Boolean] :required whether the attribute is required
+    # @raise [ArgumentError] if the attribute is required but not present
+    # @return [void]
+    def validate_required!(params, attribute, options)
+      return unless options[:required] && !params.key?(attribute)
+
+      raise(ArgumentError, "#{attribute} is required")
+    end
+
+    # Validates that the attribute is not blank if blank is not allowed
+    #
+    # @param params [Hash] the parameters to validate
+    # @param attribute [Symbol] the attribute to validate
+    # @param options [Hash] the validation options
+    # @option options [Boolean] :blank whether the attribute can be blank
+    # @raise [ArgumentError] if the attribute is blank but blank is not allowed
+    # @return [void]
+    def validate_blank!(params, attribute, options)
+      return unless !options[:blank] && (params.key?(attribute) && params[attribute].blank?)
+
+      raise(ArgumentError, "#{attribute} can't be blank")
+    end
+
+    # Validates that the attribute is of the expected type
+    #
+    # @param params [Hash] the parameters to validate
+    # @param attribute [Symbol] the attribute to validate
+    # @param options [Hash] the validation options
+    # @option options [Class] :type the expected type of the attribute
+    # @raise [ArgumentError] if the attribute is not of the expected type
+    # @return [void]
+    def validate_type!(params, attribute, options)
+      klass_type = options[:type]
+
+      return unless klass_type.to_s.present? && !params[attribute].is_a?(klass_type)
+
+      raise(ArgumentError, "#{attribute} must be #{klass_type}")
+    end
+
+    # Validates that the attribute's value is within the allowed values
+    #
+    # @param params [Hash] the parameters to validate
+    # @param attribute [Symbol] the attribute to validate
+    # @param options [Hash] the validation options
+    # @option options [Array] :in the allowed values for the attribute
+    # @raise [ArgumentError] if the attribute's value is not within the allowed values
+    # @return [void]
+    def validate_value!(params, attribute, options)
+      return unless params[attribute].to_s.present? && options[:in]&.exclude?(params[attribute])
+
+      raise(ArgumentError, "#{attribute} must be in #{options[:in]}")
+    end
+  end
+end

data/lib/zkt_client/models/department.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ZktClient
+  # Department class handles operations related to departments in the ZktClient
+  class Department < Base
+    # URL endpoints for the Department resource
+    URLS = { base: "/personnel/api/departments/" }.freeze
+
+    # Required fields for creating or updating a Department resource
+    REQUIRED_FEILDS = %i[dept_code dept_name].freeze
+  end
+end

data/lib/zkt_client/models/device.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ZktClient
+  # Department class handles operations related to devices in the ZktClient
+  class Device < Base
+    # URL endpoints for the device resource
+    URLS = { base: "/iclock/api/terminals/" }.freeze
+
+    # Required fields for creating or updating a device resource
+    REQUIRED_FEILDS = %i[sn alias ip_address].freeze
+  end
+end

data/lib/zkt_client/models/employee.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ZktClient
+  # Employee class handles operations related to employees in the ZktClient
+  class Employee < Base
+    # URL endpoints for the Employee resource
+    URLS = {
+      base: "/personnel/api/employees/"
+    }.freeze
+
+    # Required fields for creating or updating an Employee resource
+    REQUIRED_FEILDS = %i[emp_code department area].freeze
+
+    class << self
+      private
+
+      # Validates the parameters for creating an Employee resource
+      #
+      # @param params [Hash] the parameters to validate
+      # @raise [ArgumentError] if required fields are missing or invalid
+      def validate_create_params!(params)
+        super(params)
+        validate!(params, :app_status, in: [1, 0, "Enable", "Disable"])
+        validate!(params, :area, type: Array)
+      end
+
+      # Validates the parameters for updating an Employee resource
+      #
+      # @param params [Hash] the parameters to validate
+      # @raise [ArgumentError] if required fields are missing or invalid
+      def validate_update_params!(params)
+        super(params)
+        validate!(params, :gender, in: %w[F M])
+        validate!(params, :app_status, in: [1, 0, "Enable", "Disable"])
+      end
+    end
+  end
+end

data/lib/zkt_client/models/position.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ZktClient
+  # Position class handles operations related to positions in the ZktClient
+  class Position < Base
+    # URL endpoints for the Position resource
+    URLS = { base: "/personnel/api/positions/" }.freeze
+
+    # Required fields for creating or updating a Position resource
+    REQUIRED_FEILDS = %i[position_code position_name].freeze
+  end
+end

data/lib/zkt_client/models/transaction.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ZktClient
+  # Transaction class handles operations related to transactions in the ZktClient
+  class Transaction < Base
+    # URL endpoints for the Transaction resource
+    URLS = {
+      base: "/iclock/api/transactions/"
+    }.freeze
+
+    # Required fields for creating or updating a Transaction resource
+    REQUIRED_FEILDS = [].freeze
+  end
+end

data/lib/zkt_client/monky_patcher/array.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+# Extends the Array class with additional methods
+class Array
+  include Base
+
+  # Wraps the given object in an array.
+  #
+  # @param object [Object] the object to wrap
+  # @return [Array] the wrapped object as an array
+  def self.wrap(object)
+    if object.respond_to?(:to_a)
+      object.to_a
+    else
+      [object]
+    end
+  end
+
+  # Checks if the array excludes the given value.
+  #
+  # @param value [Object] the value to check
+  # @return [Boolean] true if the array does not include the value, false otherwise
+  def exclude?(value)
+    !include?(value)
+  end
+end

data/lib/zkt_client/monky_patcher/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Base
+  # Checks if the object is blank (empty)
+  #
+  # @return [Boolean] true if the object is empty, false otherwise
+  def blank?
+    empty?
+  end
+
+  # Checks if the object is present (not blank)
+  #
+  # @return [Boolean] true if the object is not empty, false otherwise
+  def present?
+    !blank?
+  end
+end

data/lib/zkt_client/monky_patcher/false.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+# Extends the FalseClass with additional methods
+class FalseClass
+  include Base
+
+  # Checks if the object is blank (always true for FalseClass)
+  #
+  # @return [Boolean] true, since false is considered blank
+  def blank?
+    true
+  end
+end