sadad 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 54fb49202126ef2f736a0b0453132aacd8ec0c38ffdce64eb77b66e3cff580d7
+  data.tar.gz: 4bceae03cebf3de09de544649eb603c5e20eda8371dd28004a09768fa90a104c
+SHA512:
+  metadata.gz: c19a0cba2a92d66c03741d4183167c18659d56c7f07a1ebd1852485fc2561b024fab8273cde210f4740d8a24903bc9bf15da1c75d1b7d9853f95a140d1a7776b
+  data.tar.gz: db66ce797a97366442ce423da19b6ac28cc16a69a503f23b4d6bbd573fd80b249af51ab3ea1a9830841fa0d348f392e257a2d1dae6e7c766dd7ef5e35ca32789

data/README.md

@@ -0,0 +1,209 @@
+# Sadad Payments Gem
+
+Ruby gem for integrating with Sadad payment gateway. This gem provides complete functionality for creating and managing bills through Sadad's API.
+
+## Table of Contents
+1. [Installation](#installation)
+2. [Configuration](#configuration)
+3. [API Usage](#api-usage)
+    1. [Single Bill Operations](#single-bill-operations)
+        1. [Create Bill](#create-bill)
+        2. [Update Bill](#update-bill)
+        3. [Inquiry Bill](#inquiry-bill)
+        4. [Expire Bill](#expire-bill)
+    2. [Multiple Bills Operations](#multiple-bills-operations)
+        1. [Create Bills](#create-bills) 
+        2. [Deactivate Bill](#deactivate-bill) 
+4. [Error Handling](#error-handling)
+5. [Contributing](#contributing)
+6. [License](#license)
+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add sadad
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install sadad
+
+
+Next, you need to run the generator:
+
+    $ rails generate sadad:install
+
+**Note:** This will create a `config/initializers/sadad.rb` file with the default configuration.
+
+
+## Configuration
+
+Configure the gem with your configuration
+
+```ruby
+Sadad.configure do |config|
+  config.merchant_id = "merchant_id"
+  config.program_id = "program_id"
+  config.client_certificate_pem_file = "client_certificate_pem_file"
+end
+```
+
+For `merchant_id`, `program_id`, and `client_certificate_pem_file`, you can set its value in 3 ways
+- Global across whole application (through initializer and configuration)
+  ```ruby
+  Sadad.configure do |config|
+    config.merchant_id = "merchant_id"
+    config.program_id = "program_id"
+    config.client_certificate_pem_file = "client_certificate_pem_file"
+  end
+  ```
+
+- Per method or block (through the application variables). All consecutive requests will use that token until it is set to a different value
+  ```ruby
+  Sadad.merchant_id = "merchant_id"
+  Sadad.program_id = "program_id"
+  Sadad.client_certificate_pem_file = "client_certificate_pem_file"
+  ```
+
+- Per request (through opts parameter)  
+  ```ruby
+  Sadad::Bills.create(opts: { merchant_id: "merchant_id", program_id: "program_id", client_certificate_pem_file: "client_certificate_pem_file" })
+  ```
+
+
+## API Usage
+
+Any API call will return an object with following methods: 
+
+```ruby
+result = Sadad.doSomething
+result.success?
+result.failure?
+result.payload
+result.error
+```
+
+### Single Bill Operations
+
+#### Create Bill
+
+```ruby
+Sadad::SingleBill.create(
+  user_national_id: "1133331101",
+  user_first_name: "Khaled",
+  user_last_name: "Ahmed",
+  invoice_id: "1998654321",
+  bill_type: "OneTime",
+  display_info: "Details of the invoice issued",
+  amount_due: 275.25,
+  invoice_created_date: "2025-02-23T10:46:37",
+  expiry_date: "2025-03-23T10:46:37"
+  opts: {}
+)
+```
+
+#### Update Bill
+
+```ruby
+Sadad::SingleBill.update(
+  user_national_id: "1133331101",
+  user_first_name: "Khaled",
+  user_last_name: "Ahmed",
+  invoice_id: "1998654321",
+  bill_type: "OneTime",
+  display_info: "Details of the invoice issued",
+  amount_due: 275.25,
+  invoice_created_date: "2025-02-23T10:46:37",
+  expiry_date: "2025-03-23T10:46:37",
+  opts: {}
+)
+```
+
+#### Expire Bill
+
+```ruby
+Sadad::SingleBill.expire(
+  user_national_id: "1133331101",
+  user_first_name: "Khaled",
+  user_last_name: "Ahmed",
+  invoice_id: "1998654321",
+  bill_type: "OneTime",
+  display_info: "Details of the invoice issued",
+  amount_due: 275.25,
+  invoice_created_date: "2025-02-23T10:46:37",
+  expiry_date: "2025-03-23T10:46:37",
+  opts: {}
+) 
+```
+
+#### Inquiry Bill
+
+```ruby
+Sadad::SingleBill.inquiry(
+  sadad_number: "1998654321",
+  opts: {}
+)
+```
+
+
+### Multiple Bills Operations
+
+#### Create Bills
+
+```ruby
+invoices = [
+  {
+    user_national_id: "1133331101",
+    user_first_name: "Khaled",
+    user_last_name: "Ahmed",
+    invoice_id: "1998054111",
+    invoice_status: "BillNew",
+    bill_type: "OneTime",
+    display_info: "Details of the invoice issued",
+    amount_due: 275.25,
+    invoice_created_date: "2025-02-23T10:46:37",
+    expiry_date: "2025-03-23T10:46:37"
+  },
+  {
+    user_national_id: "1983331102",
+    user_first_name: "Ahmed",
+    user_last_name: "Ali",
+    invoice_id: "1998254321",
+    invoice_status: "BillNew",
+    bill_type: "Recurring",
+    display_info: "Monthly subscription payment",
+    amount_due: 5000.00,
+    invoice_created_date: "2025-02-23T10:46:37",
+    expiry_date: "2025-03-23T10:46:37",
+    minimum_partial_amount: 500
+  }
+]
+
+Sadad::MultipleBills.create(invoices, opts: {})
+```
+
+#### Deactivate Bill
+
+```ruby
+Sadad::MultipleBills.deactivate(sadad_numbers: ["1998654321", "1998654322"], opts: {})
+```
+
+## Errors:
+Errors could be one of the following:
+
+```ruby
+Sadad::ForbiddenError
+Sadad::APIConnectionError
+Sadad::APIError
+Sadad::InvalidRequestError (With `param` attribute)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/lib/generators/sadad/install_generator.rb

@@ -0,0 +1,15 @@
+require "rails/generators"
+
+module Sadad
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Sadad initializers file."
+
+      def copy_initializer
+        copy_file "sadad.rb", "config/initializers/sadad.rb"
+      end
+    end
+  end
+end

data/lib/generators/sadad/templates/sadad.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+Sadad.configure do |config|
+  # config.merchant_id = ""
+  # config.program_id = ""
+  # config.client_certificate_pem_file = ""
+end

data/lib/sadad/api/api_base.rb

@@ -0,0 +1,54 @@
+module Sadad
+  class ApiBase
+    include Sadad::Request
+    include Sadad::JsonSchemas::Validator
+
+    Response = Struct.new(:success?, :payload, :error) do
+      def failure?
+        !success?
+      end
+    end
+
+    def initialize(**params)
+      @params = params
+      @opts   = filtered_opts(params[:opts])
+    end
+
+    def call
+      validate_params!
+      @response = call_api
+      handle_response_error
+      handle_sadad_response
+    rescue StandardError => e
+      failure(e)
+    end
+
+    private
+
+    def filtered_opts(opts)
+      opts&.reject { |_k, v| v&.empty? } || {}
+    end
+
+    def call_api
+      ::Faraday
+        .new(Sadad.base_uri, ssl: ssl_client_certificate)
+        .post(uri_path, api_params, headers)
+    end
+
+    def uri_path
+      raise NotImplementedError, "Subclasses must implement uri_path"
+    end
+
+    def request_body
+      raise NotImplementedError, "Subclasses must implement request_body"
+    end
+
+    def success(payload = nil)
+      Response.new(true, payload)
+    end
+
+    def failure(exception)
+      Response.new(false, nil, exception)
+    end
+  end
+end

data/lib/sadad/api/bill.rb

@@ -0,0 +1,37 @@
+module Sadad
+  module Api
+    class Bill
+      def self.request_body(params)
+        sanity_checks!(params)
+
+        {
+          Beneficiary: {
+            Id: params[:user_national_id],
+            FirstName: params[:user_first_name],
+            LastName: params[:user_last_name]
+          },
+          InvoiceId: params[:invoice_id],
+          InvoiceStatus: params[:invoice_status],
+          BillType: params[:bill_type],
+          DisplayInfo: params[:display_info] || "Details of invoice number: #{params[:invoice_id]}",
+          AmountDue: params[:amount_due],
+          CreateDate: format_time(params[:invoice_created_date]),
+          ExpiryDate: format_time(params[:expiry_date]),
+          PaymentRange: payment_range(params)
+        }.compact
+      end
+
+      def self.format_time(time_string)
+        Time.parse(time_string).strftime("%Y-%m-%dT%H:%M:%S") if time_string
+      end
+
+      def self.payment_range(params)
+        { MinPartialAmount: params[:minimum_partial_amount] } if params[:minimum_partial_amount]
+      end
+
+      def self.sanity_checks!(params)
+        raise Sadad::InvalidRequestError.new("params cannot be empty", params) if params.empty?
+      end
+    end
+  end
+end

data/lib/sadad/api/multiple_bills/create.rb

@@ -0,0 +1,25 @@
+module Sadad
+  module MultipleBills
+    class Create < ApiBase
+      include Sadad::JsonSchemas::MultipleBills
+
+      def self.call(invoices:, opts: {})
+        new(invoices: invoices, opts: opts).call
+      end
+
+      def uri_path
+        "#{BILL_API_PREFIX}/ProcessMultiBills"
+      end
+
+      private
+
+      def request_body
+        {
+          Invoices: @params[:invoices].map do |invoice|
+            Sadad::Api::Bill.request_body(invoice)
+          end
+        }
+      end
+    end
+  end
+end

data/lib/sadad/api/multiple_bills/deactivate.rb

@@ -0,0 +1,28 @@
+module Sadad
+  module MultipleBills
+    class Deactivate < ApiBase
+      include Sadad::JsonSchemas::DeactivateBill
+
+      def self.call(sadad_numbers:, opts: {})
+        new(sadad_numbers: sadad_numbers, opts: opts).call
+      end
+
+      def uri_path
+        "#{BILL_API_PREFIX}/DeactivateBill"
+      end
+
+      private
+
+      def request_body
+        {
+          Invoices: @params[:sadad_numbers].map do |sadad_number|
+            {
+              SADADNumber: sadad_number,
+              InvoiceStatus: BILL_DEACTIVATED
+            }
+          end
+        }
+      end
+    end
+  end
+end

data/lib/sadad/api/multiple_bills.rb

@@ -0,0 +1,11 @@
+module Sadad
+  module MultipleBills
+    def self.create(invoices:, opts: {})
+      Sadad::MultipleBills::Create.call(invoices: invoices, opts: opts)
+    end
+
+    def self.deactivate(sadad_numbers:, opts: {})
+      Sadad::MultipleBills::Deactivate.call(sadad_numbers: sadad_numbers, opts: opts)
+    end
+  end
+end

data/lib/sadad/api/request.rb

@@ -0,0 +1,152 @@
+module Sadad
+  module Request
+    def headers
+      @headers = {
+        "Content-Type": "application/json"
+      }
+    end
+
+    def ssl_client_certificate
+      @ssl_client_certificate = {
+        client_cert: OpenSSL::X509::Certificate.new(File.read(client_certificate_pem_file)),
+        client_key: OpenSSL::PKey::RSA.new(File.read(client_certificate_pem_file))
+      }
+    rescue StandardError
+      {}
+    end
+
+    def api_params
+      merchant_api_params.merge(request_body).to_json
+    end
+
+    def merchant_api_params
+      {
+        UUID: SecureRandom.uuid,
+        Timestamp: Time.now.strftime("%Y-%m-%dT%H:%M:%S"), ## formats to "2018-08-18T17:46:37"
+        MerchantId: merchant_id,
+        ProgramId: program_id
+      }
+    end
+
+    def program_id
+      @opts[:program_id] || Sadad.program_id || Sadad.configuration.program_id
+    end
+
+    def merchant_id
+      @opts[:merchant_id] || Sadad.merchant_id || Sadad.configuration.merchant_id
+    end
+
+    def client_certificate_pem_file
+      @opts[:client_certificate_pem_file] ||
+        Sadad.client_certificate_pem_file ||
+        Sadad.configuration.client_certificate_pem_file
+    end
+
+    def parsed_response
+      @parsed_response = begin
+        JSON.parse(@response.body)
+      rescue StandardError
+        {}
+      end
+    end
+
+    def error_message
+      parsed_response.is_a?(Array) ? array_error_message : single_error_message
+    end
+
+    def error_code
+      if parsed_response.is_a?(Array)
+        error_item = parsed_response.select { |item| item["Status"] && item["Status"]["Code"] != 0 }
+        error_item&.map { |item| item["Status"]["Code"] }
+      else
+        parsed_response.dig("errors", 0, "error_code") || parsed_response.dig("Status", "Code")
+      end
+    end
+
+    def handle_response_error
+      case response_status
+      when 400
+        raise_invalid_request_error
+      when 403
+        raise_forbidden_error
+      when 404
+        raise_not_found_error
+      when (400..599)
+        raise_api_error
+      end
+    end
+
+    def handle_sadad_response
+      internal_error? ? failure(build_internal_error) : success(parsed_response)
+    end
+
+    private
+
+    def response_status
+      @response_status = @response.status
+    end
+
+    def response_body
+      @response_body = @response.body
+    end
+
+    def array_error_message
+      error_items = parsed_response.select { |item| item["Status"] && item["Status"]["Code"] != 0 }
+      error_items&.map { |item| item["Status"]["Description"] }&.join(", ")
+    end
+
+    def single_error_message
+      parsed_response["message"] || parsed_response.dig("Status", "Description")
+    end
+
+    def internal_error?
+      return false unless parsed_response.is_a?(Hash)
+
+      status = parsed_response["Status"] || {}
+      status["Code"].to_i != 0 || status["Severity"]&.downcase == "error"
+    end
+
+    def build_internal_error
+      status = parsed_response["Status"] || {}
+      APIError.new(
+        status["Description"],
+        http_status: response_status,
+        http_body: response_body,
+        error_code: status["Code"]
+      )
+    end
+
+    def raise_invalid_request_error
+      raise InvalidRequestError.new(
+        error_message,
+        error_code,
+        http_status: response_status,
+        http_body: response_body
+      )
+    end
+
+    def raise_forbidden_error
+      raise ForbiddenError.new(
+        "Invalid Credentials",
+        http_status: response_status,
+        http_body: response_body
+      )
+    end
+
+    def raise_not_found_error
+      raise APIError.new(
+        "Resource not found",
+        http_status: response_status,
+        http_body: response_body
+      )
+    end
+
+    def raise_api_error
+      raise APIError.new(
+        error_message,
+        http_status: response_status,
+        http_body: response_body
+      )
+    end
+  end
+end

data/lib/sadad/api/single_bill/create.rb

@@ -0,0 +1,37 @@
+module Sadad
+  module SingleBill
+    class Create < ApiBase
+      include Sadad::JsonSchemas::SingleBill
+
+      def self.call(user_national_id:, user_first_name:, user_last_name:,
+                    invoice_id:, invoice_status:, amount_due:, bill_type:,
+                    invoice_created_date:, expiry_date:, display_info: nil,
+                    minimum_partial_amount: nil, opts: {})
+        new(
+          user_national_id: user_national_id,
+          user_first_name: user_first_name,
+          user_last_name: user_last_name,
+          invoice_id: invoice_id,
+          invoice_status: invoice_status,
+          display_info: display_info,
+          amount_due: amount_due,
+          bill_type: bill_type,
+          invoice_created_date: invoice_created_date,
+          expiry_date: expiry_date,
+          minimum_partial_amount: minimum_partial_amount,
+          opts: opts
+        ).call
+      end
+
+      def uri_path
+        "#{BILL_API_PREFIX}/CreateSingleBill"
+      end
+
+      def request_body
+        {
+          Invoice: Sadad::Api::Bill.request_body(@params)
+        }
+      end
+    end
+  end
+end

data/lib/sadad/api/single_bill/inquire.rb

@@ -0,0 +1,23 @@
+module Sadad
+  module SingleBill
+    class Inquire < ApiBase
+      include Sadad::JsonSchemas::InquireBill
+
+      def self.call(sadad_number:, opts: {})
+        new(sadad_number: sadad_number, opts: opts).call
+      end
+
+      def uri_path
+        "#{BILL_API_PREFIX}/InquireBill"
+      end
+
+      private
+
+      def request_body
+        {
+          SADADNumber: @params[:sadad_number]
+        }
+      end
+    end
+  end
+end

data/lib/sadad/api/single_bill.rb

@@ -0,0 +1,29 @@
+module Sadad
+  module SingleBill
+    class << self
+      def create(params)
+        create_with_status(params, BILL_NEW)
+      end
+
+      def update(params)
+        create_with_status(params, BILL_UPDATED)
+      end
+
+      def expire(params)
+        create_with_status(params, BILL_EXPIRED)
+      end
+
+      def inquire(sadad_number:, opts: {})
+        Sadad::SingleBill::Inquire.call(sadad_number: sadad_number, opts: opts)
+      end
+
+      private
+
+      def create_with_status(params, invoice_status)
+        Sadad::SingleBill::Create.call(
+          **params, invoice_status: invoice_status
+        )
+      end
+    end
+  end
+end

data/lib/sadad/configuration.rb

@@ -0,0 +1,5 @@
+module Sadad
+  class Configuration
+    attr_accessor :merchant_id, :program_id, :client_certificate_pem_file
+  end
+end

data/lib/sadad/errors.rb

@@ -0,0 +1,71 @@
+module Sadad
+  # SadadError is the base error from which all other more specific Sadad
+  # errors derive.
+  class SadadError < StandardError
+    attr_reader :message, :error, :http_body, :http_headers, :http_status, :json_body
+
+    # Initializes a SadadError.
+    def initialize(message = nil, http_status: nil, http_body: nil)
+      @message = message || http_body
+      @http_status = http_status
+      @http_body = http_body
+      begin
+        @json_body = JSON.parse(http_body)
+      rescue StandardError
+        @json_body = nil
+      end
+    end
+
+    def to_s
+      status_string = @http_status.nil? ? "" : "(Status #{@http_status}) "
+      "#{status_string}#{@message}"
+    end
+  end
+
+  # ForbiddenError is raised when invalid merchant credentials are used to connect
+  # to Sadad's servers. Invalid merchant credentials includes:
+  # - Invalid Merchant ID
+  # - Invalid Program ID
+  # - Invalid Client Certificate file
+  class ForbiddenError < SadadError
+  end
+
+  # APIConnectionError is raised in the event that the SDK can't connect to
+  # Sadad's servers. That can be for a variety of different reasons from a
+  # downed network to a bad TLS certificate.
+  class APIConnectionError < SadadError
+  end
+
+  # APIError is raised when Sadad's API returns an error response. These errors
+  # can be caused by various issues like invalid parameters, authentication failures,
+  # rate limiting, or internal server errors. The error includes:
+  # - message: Human readable error description
+  # - http_status: HTTP status code (e.g. 400, 401, 429, 500)
+  # - http_body: Raw response body from the API
+  # - error_code: Sadad-specific error code for more granular error handling
+  class APIError < SadadError
+    attr_reader :error_code
+
+    def initialize(message = nil, http_status: nil, http_body: nil, error_code: nil)
+      super(message, http_status: http_status, http_body: http_body)
+      @error_code = error_code
+    end
+
+    def to_s
+      error_code_string = @error_code ? "(Error Code #{@error_code}) " : ""
+      status_string = @http_status ? "(Status #{@http_status}) " : ""
+      "#{status_string}#{error_code_string}#{@message}"
+    end
+  end
+
+  # InvalidRequestError is raised when a request is initiated with invalid
+  # parameters.
+  class InvalidRequestError < SadadError
+    attr_accessor :param
+
+    def initialize(message, param, http_status: nil, http_body: nil)
+      super(message, http_status: http_status, http_body: http_body)
+      @param = param
+    end
+  end
+end

data/lib/sadad/json_schemas/beneficiary.rb

@@ -0,0 +1,20 @@
+module Sadad
+  module JsonSchemas
+    module Beneficiary
+      include Validator
+
+      def self.schema
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: {
+            Id: Types::Identifier.schema(min_length: 10, max_length: 10),
+            FirstName: Types::String.schema,
+            LastName: Types::String.schema
+          },
+          required: %w[Id FirstName LastName]
+        }
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/deactivate_bill.rb

@@ -0,0 +1,32 @@
+module Sadad
+  module JsonSchemas
+    module DeactivateBill
+      include Validator
+
+      private
+
+      def schema
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: {
+            UUID: Types::Uuid.schema,
+            Timestamp: Types::Timestamp.schema,
+            MerchantId: Types::Identifier.schema,
+            ProgramId: Types::Identifier.schema,
+            Invoices: {
+              type: "array",
+              items: DeactivateInvoice.schema,
+              minItems: 1
+            }
+          },
+          required: required_fields
+        }
+      end
+
+      def required_fields
+        %w[UUID Timestamp MerchantId ProgramId Invoices]
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/deactivate_invoice.rb

@@ -0,0 +1,19 @@
+module Sadad
+  module JsonSchemas
+    module DeactivateInvoice
+      include Validator
+
+      def self.schema
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: {
+            SADADNumber: Types::Identifier.schema,
+            InvoiceStatus: Types::Enum.schema(values: [BILL_DEACTIVATED])
+          },
+          required: %w[SADADNumber InvoiceStatus]
+        }
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/inquire_bill.rb

@@ -0,0 +1,24 @@
+module Sadad
+  module JsonSchemas
+    module InquireBill
+      include Validator
+
+      private
+
+      def schema
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: {
+            UUID: Types::Uuid.schema,
+            Timestamp: Types::Timestamp.schema,
+            MerchantId: Types::Identifier.schema,
+            ProgramId: Types::Identifier.schema,
+            SADADNumber: Types::Identifier.schema
+          },
+          required: %w[UUID Timestamp MerchantId ProgramId SADADNumber]
+        }
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/invoice.rb

@@ -0,0 +1,26 @@
+module Sadad
+  module JsonSchemas
+    module Invoice
+      include Validator
+
+      def self.schema
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: {
+            Beneficiary: Beneficiary.schema,
+            InvoiceId: Types::Identifier.schema,
+            InvoiceStatus: Types::Enum.schema(values: INVOICE_STATUSES),
+            BillType: Types::Enum.schema(values: BILL_TYPES),
+            DisplayInfo: Types::String.schema(allows_null: true),
+            AmountDue: Types::Decimal.schema,
+            CreateDate: Types::Timestamp.schema,
+            ExpiryDate: Types::Timestamp.schema(allows_null: true),
+            PaymentRange: PaymentRange.schema(allows_null: true)
+          },
+          required: %w[Beneficiary InvoiceId InvoiceStatus BillType AmountDue CreateDate]
+        }
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/multiple_bills.rb

@@ -0,0 +1,28 @@
+module Sadad
+  module JsonSchemas
+    module MultipleBills
+      include Validator
+
+      private
+
+      def schema
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: {
+            UUID: Types::Uuid.schema,
+            Timestamp: Types::Timestamp.schema,
+            MerchantId: Types::Identifier.schema,
+            ProgramId: Types::Identifier.schema,
+            Invoices: {
+              type: "array",
+              items: Invoice.schema,
+              minItems: 1
+            }
+          },
+          required: %w[UUID Timestamp MerchantId ProgramId Invoices]
+        }
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/payment_range.rb

@@ -0,0 +1,18 @@
+module Sadad
+  module JsonSchemas
+    module PaymentRange
+      include Validator
+
+      def self.schema(allows_null: false)
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: ["object", (allows_null ? "null" : nil)].compact,
+          properties: {
+            MinPartialAmount: Types::Decimal.schema(allows_null: allows_null)
+          },
+          required: ["MinPartialAmount"]
+        }
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/single_bill.rb

@@ -0,0 +1,32 @@
+module Sadad
+  module JsonSchemas
+    module SingleBill
+      include Validator
+
+      private
+
+      def schema
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: bill_properties,
+          required: required_fields
+        }
+      end
+
+      def bill_properties
+        {
+          UUID: Types::Uuid.schema,
+          Timestamp: Types::Timestamp.schema,
+          MerchantId: Types::Identifier.schema,
+          ProgramId: Types::Identifier.schema,
+          Invoice: Invoice.schema
+        }
+      end
+
+      def required_fields
+        %w[UUID Timestamp MerchantId ProgramId Invoice]
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/types/decimal.rb

@@ -0,0 +1,17 @@
+module Sadad
+  module JsonSchemas
+    module Types
+      module Decimal
+        def self.schema(allows_null: false, min: 0, max: nil)
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: ["number", (allows_null ? "null" : nil)].compact,
+            minimum: min,
+            maximum: max,
+            multipleOf: 0.01
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/types/enum.rb

@@ -0,0 +1,15 @@
+module Sadad
+  module JsonSchemas
+    module Types
+      module Enum
+        def self.schema(values:, default: nil, allows_null: false)
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            enum: allows_null ? [*values, nil] : values,
+            default: default
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/types/identifier.rb

@@ -0,0 +1,21 @@
+module Sadad
+  module JsonSchemas
+    module Types
+      module Identifier
+        def self.schema(min_length: 1, max_length: nil)
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: "string",
+            pattern: "^\\d+$",
+            minLength: min_length,
+            maxLength: max_length
+          }.compact
+        end
+
+        def schema
+          Sadad::JsonSchemas::Types::Identifier.schema
+        end
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/types/string.rb

@@ -0,0 +1,21 @@
+module Sadad
+  module JsonSchemas
+    module Types
+      module String
+        def self.schema(allows_null: false, max_length: nil, default: nil)
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: ["string", (allows_null ? "null" : nil)].compact,
+            minLength: allows_null ? 0 : 1,
+            maxLength: max_length,
+            default: default
+          }.compact
+        end
+
+        def schema
+          Sadad::JsonSchemas::Types::String.schema
+        end
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/types/timestamp.rb

@@ -0,0 +1,19 @@
+module Sadad
+  module JsonSchemas
+    module Types
+      module Timestamp
+        def self.schema(allows_null: false)
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: ["string", (allows_null ? "null" : nil)].compact,
+            pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
+          }
+        end
+
+        def schema
+          Sadad::JsonSchemas::Types::Timestamp.schema
+        end
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/types/uuid.rb

@@ -0,0 +1,19 @@
+module Sadad
+  module JsonSchemas
+    module Types
+      module Uuid
+        def self.schema(allows_null: false)
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: ["string", (allows_null ? "null" : nil)].compact,
+            pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+          }
+        end
+
+        def schema
+          Sadad::JsonSchemas::Types::Uuid.schema
+        end
+      end
+    end
+  end
+end

data/lib/sadad/json_schemas/validator.rb

@@ -0,0 +1,63 @@
+module Sadad
+  module JsonSchemas
+    module Validator
+      ERROR_MESSAGES = {
+        Pattern: "%<property>s has invalid format",
+        Type: "%<property>s must be a %<type>s",
+        Required: "%<property>s is required",
+        Minimum: "%<property>s is too small",
+        Maximum: "%<property>s is too large",
+        Format: "%<property>s has invalid format",
+        Enum: "%<property>s must be one of: %<allowed_values>s"
+      }.freeze
+
+      def validate_params!
+        JSON::Validator.validate!(schema, api_params)
+      rescue JSON::Schema::ValidationError => e
+        handle_validation_error(e)
+      end
+
+      private
+
+      def handle_validation_error(error)
+        error_key = normalize_error_key(error)
+        property = extract_property_name(error)
+        error_params = extract_error_params(error)
+
+        raise InvalidRequestError.new(
+          format_error_message(error_key, property, error_params),
+          error.message
+        )
+      end
+
+      def normalize_error_key(error)
+        error.failed_attribute.to_s
+          .split("::")
+          .last
+          .delete_suffix("Attribute")
+      end
+
+      def extract_property_name(error)
+        path = error.message[/'#\/([^']+)'/i, 1]
+        path&.humanize || "Field"
+      end
+
+      def extract_error_params(error)
+        schema_data = error.schema.instance_variable_get(:@schema)
+        {
+          type: schema_data["type"],
+          pattern: schema_data["pattern"],
+          allowed_values: Array(schema_data["enum"])&.join(", ")
+        }.compact
+      end
+
+      def format_error_message(error_key, property, error_params)
+        format(
+          ERROR_MESSAGES.fetch(error_key.to_sym, "%<property>s is invalid"),
+          property: property,
+          **error_params
+        )
+      end
+    end
+  end
+end

data/lib/sadad/version.rb

@@ -0,0 +1,3 @@
+module Sadad
+  VERSION = "0.1.0".freeze
+end

data/lib/sadad.rb

@@ -0,0 +1,75 @@
+require "logger"
+require "active_support"
+require "active_support/core_ext/module"
+require "active_support/core_ext/numeric/time"
+require "faraday"
+require "json-schema"
+require "securerandom"
+require "openssl"
+require "json"
+
+require_relative "sadad/version"
+require_relative "sadad/errors"
+
+# JSON Schemas
+require "sadad/json_schemas/validator"
+require "sadad/json_schemas/types/identifier"
+require "sadad/json_schemas/types/uuid"
+require "sadad/json_schemas/types/timestamp"
+require "sadad/json_schemas/types/string"
+require "sadad/json_schemas/types/decimal"
+require "sadad/json_schemas/types/enum"
+require "sadad/json_schemas/beneficiary"
+require "sadad/json_schemas/invoice"
+require "sadad/json_schemas/single_bill"
+require "sadad/json_schemas/payment_range"
+require "sadad/json_schemas/multiple_bills"
+require "sadad/json_schemas/deactivate_bill"
+require "sadad/json_schemas/deactivate_invoice"
+require "sadad/json_schemas/inquire_bill"
+
+# API
+require "sadad/api/request"
+require "sadad/configuration"
+require "sadad/api/api_base"
+require "sadad/api/bill"
+require "sadad/api/single_bill/create"
+require "sadad/api/single_bill/inquire"
+require "sadad/api/single_bill"
+require "sadad/api/multiple_bills/create"
+require "sadad/api/multiple_bills/deactivate"
+require "sadad/api/multiple_bills"
+
+module Sadad
+  SANDBOX_URI     = "https://rosomtest.brightware.com.sa/RosomAPI/".freeze
+  PRODUCTION_URI  = "".freeze ## TODO: add production URI
+
+  BILL_API_PREFIX = "api/Bill".freeze
+
+  INVOICE_STATUSES = %w[BillNew BillUpdated BillExpired].freeze
+  BILL_TYPES       = %w[OneTime Recurring].freeze
+  BILL_DEACTIVATED = "BillDeactivated".freeze
+  BILL_NEW         = "BillNew".freeze
+  BILL_UPDATED     = "BillUpdated".freeze
+  BILL_EXPIRED     = "BillExpired".freeze
+
+  class << self
+    attr_accessor :merchant_id, :program_id, :client_certificate_pem_file
+
+    def base_uri
+      if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+        PRODUCTION_URI
+      else
+        SANDBOX_URI
+      end
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: sadad
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shimaa Marzouk Ali
+- Elaraby Elaidy
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-04-22 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'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.3
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.3.1
+description: Integration with Sadad API! All required resources are included to make
+  your payment with Sadad
+email:
+- eng.shimaa1985@gmail.com
+- elarabyelaidy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/generators/sadad/install_generator.rb
+- lib/generators/sadad/templates/sadad.rb
+- lib/sadad.rb
+- lib/sadad/api/api_base.rb
+- lib/sadad/api/bill.rb
+- lib/sadad/api/multiple_bills.rb
+- lib/sadad/api/multiple_bills/create.rb
+- lib/sadad/api/multiple_bills/deactivate.rb
+- lib/sadad/api/request.rb
+- lib/sadad/api/single_bill.rb
+- lib/sadad/api/single_bill/create.rb
+- lib/sadad/api/single_bill/inquire.rb
+- lib/sadad/configuration.rb
+- lib/sadad/errors.rb
+- lib/sadad/json_schemas/beneficiary.rb
+- lib/sadad/json_schemas/deactivate_bill.rb
+- lib/sadad/json_schemas/deactivate_invoice.rb
+- lib/sadad/json_schemas/inquire_bill.rb
+- lib/sadad/json_schemas/invoice.rb
+- lib/sadad/json_schemas/multiple_bills.rb
+- lib/sadad/json_schemas/payment_range.rb
+- lib/sadad/json_schemas/single_bill.rb
+- lib/sadad/json_schemas/types/decimal.rb
+- lib/sadad/json_schemas/types/enum.rb
+- lib/sadad/json_schemas/types/identifier.rb
+- lib/sadad/json_schemas/types/string.rb
+- lib/sadad/json_schemas/types/timestamp.rb
+- lib/sadad/json_schemas/types/uuid.rb
+- lib/sadad/json_schemas/validator.rb
+- lib/sadad/version.rb
+homepage: https://gitlab.com/autocloud/sadad_rails
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Integration with Sadad API
+test_files: []