namabar 0.1.0

data/README.md

@@ -0,0 +1,183 @@
+# Namabar Ruby SDK
+
+A lightweight Ruby SDK for interacting with the Namabar OTP & Messaging API. Provides simple, well-documented methods for each API endpoint with seamless HTTParty integration.
+
+## Features
+
+- **Easy Setup**: Configure API credentials once, use everywhere
+- **Complete API Coverage**: All OTP verification and messaging endpoints
+- **Type Safety**: Full RBS type definitions included
+- **Zero Heavy Dependencies**: Just HTTParty and that's it!
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'namabar'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install namabar
+```
+
+## Configuration
+
+Configure your API credentials before using the client:
+
+```ruby
+Namabar.configure do |config|
+  config.api_key = ENV.fetch('NAMABAR__API_KEY')
+end
+```
+
+## Usage
+
+Create a client and start making API calls:
+
+```ruby
+client = Namabar.client
+```
+
+### OTP Verification
+
+**Create and send a verification code:**
+
+```ruby
+response = client.create_verification_code(
+  to: '+964751234567',
+  service_id: 'your-service-id',
+  locale: 'en',                    # optional
+  external_id: 'user-123',         # optional
+  template_data: { name: 'John' }  # optional
+)
+
+if response.success?
+  verification_id = response.parsed_response['id']
+  puts "Verification code sent! ID: #{verification_id}"
+end
+```
+
+**Verify the code:**
+
+```ruby
+response = client.verify_verification_code(
+  id: verification_id,
+  code: '123456'
+)
+
+if response.success?
+  puts "Code verified successfully!"
+else
+  puts "Verification failed: #{response.parsed_response['message']}"
+end
+```
+
+**Get verification code details:**
+
+```ruby
+response = client.get_verification_code_by_id(id: verification_id)
+puts response.parsed_response
+```
+
+### Messaging
+
+**Send a message:**
+
+```ruby
+response = client.send_message(
+  type: 'Text',
+  to: '+964751234567',
+  service_id: 'your-service-id',
+  text: 'Hello from Namabar!',      # optional (for custom text)
+  template: 'welcome_template',     # optional (for templates)
+  external_id: 'msg-456'           # optional
+)
+
+if response.success?
+  message_id = response.parsed_response['id']
+  puts "Message sent! ID: #{message_id}"
+end
+```
+
+**Get message details:**
+
+```ruby
+response = client.get_message(id: message_id)
+puts response.parsed_response
+```
+
+**Check message status:**
+
+```ruby
+response = client.get_message_status(id: message_id)
+status = response.parsed_response['status']
+puts "Message status: #{status}"
+```
+
+### Response Handling
+
+All methods return `HTTParty::Response` objects:
+
+```ruby
+response = client.create_verification_code(...)
+
+# Check success
+if response.success?
+  data = response.parsed_response
+  puts "Success: #{data}"
+else
+  puts "Error #{response.code}: #{response.parsed_response['message']}"
+end
+
+# Access raw response
+puts response.body
+puts response.headers
+puts response.code
+```
+
+### Error Handling
+
+```ruby
+begin
+  response = client.create_verification_code(...)
+rescue Namabar::Error => e
+  puts "Namabar SDK error: #{e.message}"
+rescue => e
+  puts "General error: #{e.message}"
+end
+```
+
+## API Reference
+
+The SDK provides these methods corresponding to Namabar API endpoints:
+
+**OTP Verification:**
+
+- `create_verification_code(to:, service_id:, **options)` - Create and send OTP
+- `verify_verification_code(id:, code:)` - Verify OTP code  
+- `get_verification_code_by_id(id:)` - Get verification details
+
+**Messaging:**
+
+- `send_message(type:, to:, service_id:, **options)` - Send message
+- `get_message(id:)` - Get message details
+- `get_message_status(id:)` - Get message status
+
+All methods return `HTTParty::Response` objects with the API response.
+
+## Development & Contributing
+
+Please refer to the [Development](/helpers/README.md) file for more information.
+
+## License
+
+Released under the MIT License. See [LICENSE](LICENSE.txt) for details.

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

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'namabar'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/namabar/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require_relative 'configuration'
+require_relative 'endpoints'
+
+module Namabar
+  # HTTP client for interacting with the Namabar API
+  #
+  # This class provides the core HTTP functionality for making requests to the Namabar API.
+  # It uses HTTParty for HTTP operations and includes all endpoint methods from the Endpoints module.
+  #
+  # The client automatically handles:
+  # - Base URI configuration
+  # - Authentication via API key headers
+  # - Content-Type and Accept headers
+  # - JSON request/response handling
+  #
+  # @example Basic usage
+  #   # Configure globally first
+  #   Namabar.configure do |config|
+  #     config.api_key = 'your-api-key'
+  #   end
+  #
+  #   # Create and use client
+  #   client = Namabar::Client.new
+  #   response = client.send_message(
+  #     type: 'sms',
+  #     to: '+1234567890',
+  #     text: 'Hello from Namabar!',
+  #     service_id: 'sms-service'
+  #   )
+  #   puts response.code # => 200
+  #   puts response.body # => parsed JSON response
+  #
+  # @see Endpoints
+  # @see Configuration
+  class Client
+    include HTTParty
+    include Endpoints
+
+    base_uri 'https://api.namabar.krd'
+
+    # Initialize a new Namabar API client
+    #
+    # Creates a new client instance using the global Namabar configuration.
+    # The client will be configured with the API key and default headers
+    # required for authentication and proper JSON communication.
+    #
+    # @raise [StandardError] if Namabar.configuration is nil or api_key is not set
+    #
+    # @example Create a client
+    #   client = Namabar::Client.new
+    #
+    # @see Namabar.configure
+    def initialize
+      @config = Namabar.configuration
+      self.class.headers(
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json',
+        'X-API-Key' => @config.api_key
+      )
+    end
+
+    # Get default HTTP options for requests
+    #
+    # Returns a hash containing the default options that should be included
+    # with every HTTP request, including headers for authentication and content type.
+    #
+    # @return [Hash] hash containing default headers and options
+    #
+    # @example Using default options
+    #   opts = client.default_options
+    #   opts = opts.merge(query: { limit: 10 })
+    #   response = HTTParty.get('/endpoint', opts)
+    def default_options
+      { headers: self.class.headers }
+    end
+  end
+end

data/lib/namabar/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Namabar
+  # Configuration class for storing Namabar API credentials and settings
+  #
+  # This class holds the configuration options required to authenticate
+  # and interact with the Namabar API. It's typically configured once
+  # globally and then used by all Client instances.
+  #
+  # @example Configure with API credentials
+  #   config = Namabar::Configuration.new
+  #   config.api_key = ENV.fetch('NAMABAR__API_KEY', nil)
+  #
+  # @example Configure using the global configuration
+  #   Namabar.configure do |config|
+  #     config.api_key = 'your-api-key'
+  #   end
+  #
+  # @see Namabar.configure
+  class Configuration
+    # @return [String, nil] the API key for authenticating with the Namabar API
+    # @example Set API key
+    #   config.api_key = '1234567890abcdef'
+    attr_accessor :api_key
+  end
+
+  class << self
+    # @return [Configuration, nil] the global configuration instance
+    attr_accessor :configuration
+
+    # Configure the Namabar gem with API credentials and settings
+    #
+    # This method provides a convenient way to set up the global configuration
+    # that will be used by all Client instances. The configuration object is
+    # yielded to the provided block for modification.
+    #
+    # @yield [config] Yields the configuration object for modification
+    # @yieldparam config [Configuration] the configuration instance to modify
+    # @return [Configuration] the configured Configuration instance
+    #
+    # @example Basic configuration
+    #   Namabar.configure do |config|
+    #     config.api_key = ENV.fetch('NAMABAR__API_KEY', nil)
+    #   end
+    #
+    # @example Configuration with validation
+    #   Namabar.configure do |config|
+    #     config.api_key = ENV.fetch('NAMABAR_API_KEY') { raise 'API key required' }
+    #   end
+    #
+    # @see Configuration
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+      configuration
+    end
+  end
+end

data/lib/namabar/endpoints.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Namabar
+  # One to one mapping of API endpoint methods from OpenAPI specification
+  #
+  # This module contains methods that correspond to API endpoints defined
+  # in the OpenAPI spec. Each method provides a convenient Ruby interface to the HTTP endpoints.
+  #
+  # All methods return HTTParty::Response objects which can be used to
+  # access response data, status codes, headers, etc.
+  #
+  # @example Basic usage
+  #   client = Namabar::Client.new
+  #   response = client.some_endpoint(param: 'value')
+  #   puts response.code
+  #   puts response.body
+  module Endpoints
+    # Create Verification Code
+    #
+    # Generates and sends a new verification code to the specified recipient using the configured verify service.
+    #
+    # @param to [string]  (required)
+    # @param locale [String]  (optional)
+    # @param external_id [string]  (optional)
+    # @param code [string]  (optional)
+    # @param service_id [String]  (required)
+    # @param template_data [object]  (optional)
+    # @return [HTTParty::Response] the HTTP response object
+    #
+    # @example
+    #   response = create_verification_code(to: 'value', service_id: 'value')
+    #   puts response.code
+    def create_verification_code(to:, service_id:, locale: nil, external_id: nil, code: nil, template_data: nil)
+      url = '/verification-codes'
+      opts = default_options
+
+      body_data = {
+        'to' => to,
+        'locale' => locale,
+        'externalId' => external_id,
+        'code' => code,
+        'serviceId' => service_id,
+        'templateData' => template_data
+      }.compact
+
+      unless body_data.empty?
+        opts = opts.merge(body: body_data.to_json)
+        opts[:headers] ||= {}
+        opts[:headers]['Content-Type'] = 'application/json'
+      end
+
+      self.class.post(url, opts)
+    end
+
+    # Verify OTP Code
+    #
+    # Verifies a previously sent verification code. Returns the verification status and any associated data.
+    #
+    # @param id [string] The id of the verification code to verify. (required)
+    # @param code [string]  (required)
+    # @return [HTTParty::Response] the HTTP response object
+    #
+    # @example
+    #   response = verify_verification_code(id: 'value', code: 'value')
+    #   puts response.code
+    def verify_verification_code(id:, code:)
+      url = '/verification-codes/{id}/verify'
+      url = url.gsub('{id}', id.to_s)
+      opts = default_options
+
+      body_data = {
+        'code' => code
+      }.compact
+
+      unless body_data.empty?
+        opts = opts.merge(body: body_data.to_json)
+        opts[:headers] ||= {}
+        opts[:headers]['Content-Type'] = 'application/json'
+      end
+
+      self.class.post(url, opts)
+    end
+
+    # Get Verification Code
+    #
+    # Retrieves details about a specific verification code.
+    #
+    # @param id [string] The ID of the verification code to retrieve (required)
+    # @return [HTTParty::Response] the HTTP response object
+    #
+    # @example
+    #   response = get_verification_code_by_id(id: 'value')
+    #   puts response.code
+    def get_verification_code_by_id(id:)
+      url = '/verification-codes/{id}'
+      url = url.gsub('{id}', id.to_s)
+      opts = default_options
+
+      self.class.get(url, opts)
+    end
+
+    # Send New Message
+    #
+    # Creates and sends a new message through the specified messaging service. Requires the CreateMessage permission.
+    #
+    # @param type [String]  (required)
+    # @param to [string]  (required)
+    # @param external_id [string]  (optional)
+    # @param service_id [String]  (required)
+    # @param text [string]  (optional)
+    # @param template [String]  (optional)
+    # @return [HTTParty::Response] the HTTP response object
+    #
+    # @example
+    #   response = send_message(type: 'value', to: 'value', service_id: 'value')
+    #   puts response.code
+    def send_message(type:, to:, service_id:, external_id: nil, text: nil, template: nil)
+      url = '/messages'
+      opts = default_options
+
+      body_data = {
+        'type' => type,
+        'to' => to,
+        'externalId' => external_id,
+        'serviceId' => service_id,
+        'text' => text,
+        'template' => template
+      }.compact
+
+      unless body_data.empty?
+        opts = opts.merge(body: body_data.to_json)
+        opts[:headers] ||= {}
+        opts[:headers]['Content-Type'] = 'application/json'
+      end
+
+      self.class.post(url, opts)
+    end
+
+    # Get Message Details
+    #
+    # Retrieves detailed information about a specific message including its status, cost, and delivery information.
+    #
+    # @param id [string] The ID of the message to get. (required)
+    # @return [HTTParty::Response] the HTTP response object
+    #
+    # @example
+    #   response = get_message(id: 'value')
+    #   puts response.code
+    def get_message(id:)
+      url = '/messages/{id}'
+      url = url.gsub('{id}', id.to_s)
+      opts = default_options
+
+      self.class.get(url, opts)
+    end
+
+    # Get Message Status
+    #
+    # Retrieves the status of a specific message, can be used for polling message delivery status.
+    #
+    # @param id [string] The ID of the message to get. (required)
+    # @return [HTTParty::Response] the HTTP response object
+    #
+    # @example
+    #   response = get_message_status(id: 'value')
+    #   puts response.code
+    def get_message_status(id:)
+      url = '/messages/{id}/status'
+      url = url.gsub('{id}', id.to_s)
+      opts = default_options
+
+      self.class.get(url, opts)
+    end
+  end
+end

data/lib/namabar/version.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Namabar
+  # The current version of the Namabar gem
+  #
+  # This constant follows semantic versioning (SemVer) conventions:
+  # - MAJOR: Incompatible API changes
+  # - MINOR: Backwards-compatible functionality additions
+  # - PATCH: Backwards-compatible bug fixes
+  #
+  # @return [String] the current version string
+  # @example Check the version
+  #   puts Namabar::VERSION # => "0.1.0"
+  #
+  # @see https://semver.org/ Semantic Versioning specification
+  VERSION = '0.1.0'
+end

data/lib/namabar.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'namabar/version'
+require 'namabar/configuration'
+require 'namabar/client'
+require 'namabar/endpoints'
+
+# The main Namabar module providing convenient access to the Namabar API
+#
+# This module serves as the primary entry point for the Namabar gem, offering:
+# - Global configuration management
+# - Client creation and management
+# - Error handling for the entire gem
+#
+# @example Basic usage
+#   Namabar.configure do |config|
+#     config.api_key = 'your-api-key'
+#   end
+#
+#   client = Namabar.client
+#   response = client.send_message(...)
+#
+# @see Client
+# @see Configuration
+module Namabar
+  # Base error class for all Namabar-related errors
+  #
+  # All errors raised by the Namabar gem inherit from this class,
+  # making it easy to rescue all gem-related errors with a single rescue clause.
+  #
+  # @example Rescuing all Namabar errors
+  #   begin
+  #     client.send_message(...)
+  #   rescue Namabar::Error => e
+  #     puts "Namabar error: #{e.message}"
+  #   end
+  class Error < StandardError; end
+
+  class << self
+    # @return [Configuration, nil] the current global configuration instance
+    attr_accessor :configuration
+  end
+
+  # Configure the Namabar gem globally
+  #
+  # This method allows you to set global configuration options that will be
+  # used by all Client instances unless overridden. The configuration is
+  # yielded to the provided block for modification.
+  #
+  # @yield [config] Yields the configuration object for modification
+  # @yieldparam config [Configuration] the configuration instance to modify
+  # @return [Configuration] the configured Configuration instance
+  #
+  # @example Configure API credentials
+  #   Namabar.configure do |config|
+  #     config.api_key = ENV['NAMABAR_API_KEY']
+  #   end
+  #
+  # @see Configuration
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+    configuration
+  end
+
+  # Create a new Namabar API client
+  #
+  # Creates and returns a new Client instance using the global configuration.
+  # This is a convenience method equivalent to calling Client.new directly.
+  #
+  # @param args [Array] arguments to pass to the Client constructor (currently none accepted)
+  # @return [Client] a new configured client instance
+  #
+  # @example Create a client
+  #   client = Namabar.client
+  #   response = client.send_message(...)
+  #
+  # @see Client#initialize
+  def self.client(*args)
+    Client.new(*args)
+  end
+end

data/namabar.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'lib/namabar/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'namabar'
+  spec.version       = Namabar::VERSION
+  spec.authors       = ['Muhammad Nawzad']
+  spec.email         = ['hama127n@gmail.com']
+
+  spec.summary       = 'Ruby SDK for Namabar OTP verification and messaging API'
+  spec.description   = 'A lightweight Ruby SDK providing HTTParty-based client with type definitions for the Namabar OTP verification and messaging platform.'
+  spec.homepage      = 'https://github.com/muhammadnawzad/namabar-ruby-sdk'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['homepage_uri']       = spec.homepage
+  spec.metadata['changelog_uri']      = 'https://github.com/muhammadnawzad/namabar-ruby-sdk/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri']  = 'https://rubydoc.info/gems/namabar'
+  spec.metadata['bug_tracker_uri']    = 'https://github.com/muhammadnawzad/namabar-ruby-sdk/issues'
+  spec.metadata['allowed_push_host']  = 'https://rubygems.org'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:(?:test|spec|features|helpers)/|\.(?:git|github|DS_Store))})
+    end
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'httparty', '~> 0.2', '>= 0.2.0'
+end