niazpardaz_sms 1.0.2

data/lib/generators/niazpardaz_sms/install/templates/README

@@ -0,0 +1,36 @@
+===============================================================================
+
+  NiazpardazSms با موفقیت نصب شد!
+
+===============================================================================
+
+  مراحل بعدی:
+
+  1. فایل config/initializers/niazpardaz_sms.rb را باز کنید
+
+  2. کلید API خود را تنظیم کنید:
+     - از متغیر محیطی NIAZPARDAZ_API_KEY استفاده کنید
+     - یا مستقیماً در فایل وارد کنید (توصیه نمی‌شود)
+
+  3. نمونه استفاده:
+
+     # ارسال پیامک
+     client = NiazpardazSms.client
+     result = client.send_sms(
+       from_number: '10001234',
+       to_number: '09123456789',
+       message: 'سلام!'
+     )
+
+     if result.success?
+       puts "ارسال موفق! شناسه: #{result.batch_sms_id}"
+     else
+       puts "خطا: #{result.result_description}"
+     end
+
+===============================================================================
+
+  مستندات کامل:
+  https://github.com/NiazpardazSms/niazpardaz-sms-ruby
+
+===============================================================================

data/lib/generators/niazpardaz_sms/install/templates/niazpardaz_sms.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# پیکربندی NiazpardazSms
+#
+# برای اطلاعات بیشتر به مستندات مراجعه کنید:
+# https://github.com/NiazpardazSms/niazpardaz-sms-ruby
+
+NiazpardazSms.configure do |config|
+  # کلید API دریافتی از پنل نیازپرداز
+  # می‌توانید از متغیر محیطی استفاده کنید:
+  config.default_api_key = ENV.fetch('NIAZPARDAZ_API_KEY', nil)
+
+  # زمان انتظار برای درخواست‌ها (ثانیه)
+  # config.default_timeout = 30
+
+  # آدرس پایه API (فقط در صورت نیاز تغییر دهید)
+  # config.default_base_url = 'https://login.niazpardaz.ir/api/v2/RestWebApi'
+end

data/lib/niazpardaz_sms/client.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'time'
+
+module NiazpardazSms
+  # کلاینت اصلی برای کار با API پیامکی نیازپرداز
+  class Client
+    DEFAULT_BASE_URL = 'https://login.niazpardaz.ir/api/v2/RestWebApi'
+    DEFAULT_TIMEOUT = 30
+
+    attr_reader :api_key
+    attr_accessor :base_url, :timeout
+
+    # سازنده با کلید API
+    #
+    # @param api_key [String] کلید API دریافتی از پنل
+    # @param options [Hash] تنظیمات اختیاری
+    # @option options [String] :base_url آدرس پایه API
+    # @option options [Integer] :timeout زمان انتظار (ثانیه)
+    # @option options [Faraday::Connection] :connection اتصال سفارشی Faraday
+    def initialize(api_key, options = {})
+      raise Errors::ValidationError, 'کلید API نمی‌تواند خالی باشد' if api_key.nil? || api_key.strip.empty?
+
+      @api_key = api_key
+      @base_url = options[:base_url] || DEFAULT_BASE_URL
+      @timeout = options[:timeout] || DEFAULT_TIMEOUT
+      @connection = options[:connection]
+    end
+
+    # ========== ارسال پیامک ==========
+
+    # ارسال پیامک تکی
+    #
+    # @param from_number [String] شماره فرستنده
+    # @param to_number [String] شماره گیرنده
+    # @param message [String] متن پیامک
+    # @param is_flash [Boolean] آیا فلش باشد؟
+    # @param send_delay [Integer, nil] تاخیر ارسال (ثانیه)
+    # @return [Models::SendBatchSmsResult] نتیجه ارسال
+    def send_sms(from_number:, to_number:, message:, is_flash: false, send_delay: nil)
+      validate_presence!(from_number: from_number, to_number: to_number, message: message)
+
+      send_bulk_sms(
+        from_number: from_number,
+        to_numbers: [to_number],
+        message: message,
+        is_flash: is_flash,
+        send_delay: send_delay
+      )
+    end
+
+    # ارسال پیامک گروهی (یک متن به چند شماره)
+    #
+    # @param from_number [String] شماره فرستنده
+    # @param to_numbers [Array<String>] لیست شماره گیرندگان
+    # @param message [String] متن پیامک
+    # @param is_flash [Boolean] آیا فلش باشد؟
+    # @param send_delay [Integer, nil] تاخیر ارسال
+    # @return [Models::SendBatchSmsResult] نتیجه ارسال
+    def send_bulk_sms(from_number:, to_numbers:, message:, is_flash: false, send_delay: nil)
+      validate_presence!(from_number: from_number, to_numbers: to_numbers, message: message)
+
+      payload = {
+        fromNumber: from_number,
+        messageContent: message,
+        toNumbers: Array(to_numbers).join(','),
+        isFlash: is_flash,
+        sendDelay: send_delay
+      }
+
+      result = post('/SendBatchSms', payload)
+      Models::SendBatchSmsResult.new(result)
+    end
+
+    # ارسال پیامک LikeToLike (هر شماره پیام مخصوص خودش)
+    #
+    # @param from_number [String] شماره فرستنده
+    # @param to_numbers [Array<String>] لیست شماره گیرندگان
+    # @param messages [Array<String>] لیست پیام‌ها (هم‌طول با گیرندگان)
+    # @param is_flash [Boolean] آیا فلش باشد؟
+    # @return [Models::SendLikeToLikeResult] نتیجه ارسال
+    def send_sms_like_to_like(from_number:, to_numbers:, messages:, is_flash: false)
+      validate_presence!(from_number: from_number, to_numbers: to_numbers, messages: messages)
+
+      payload = {
+        fromNumber: from_number,
+        messageContents: Array(messages).join(','),
+        toNumbers: Array(to_numbers).join(','),
+        isFlash: is_flash
+      }
+
+      result = post('/SendSmsLikeToLike', payload)
+      Models::SendLikeToLikeResult.new(result)
+    end
+
+    # ارسال پیامک صوتی OTP
+    #
+    # @param from_number [String] شماره فرستنده
+    # @param to_number [String] شماره گیرنده
+    # @param otp [String] کد OTP
+    # @param is_flash [Boolean] آیا فلش باشد؟
+    # @param send_delay [Integer, nil] تاخیر ارسال
+    # @return [Models::SendBatchSmsResult] نتیجه ارسال
+    def send_voice_otp(from_number:, to_number:, otp:, is_flash: false, send_delay: nil)
+      validate_presence!(from_number: from_number, to_number: to_number, otp: otp)
+
+      payload = {
+        fromNumber: from_number,
+        messageContent: otp,
+        toNumbers: to_number,
+        sendDelay: send_delay,
+        isFlash: is_flash
+      }
+
+      result = post('/SendVoiceOtp', payload)
+      Models::SendBatchSmsResult.new(result)
+    end
+
+    # ========== گزارش تحویل ==========
+
+    # گزارش تحویل پیامک گروهی
+    #
+    # @param batch_sms_id [Integer] شناسه ارسال گروهی
+    # @param page_index [Integer] شماره صفحه
+    # @param page_size [Integer] تعداد رکورد در صفحه
+    # @return [Models::BatchDeliveryResult] نتیجه گزارش
+    def get_batch_delivery(batch_sms_id:, page_index: 1, page_size: 100)
+      payload = {
+        batchSmsId: batch_sms_id,
+        index: page_index,
+        count: page_size
+      }
+
+      result = post('/GetBatchDelivery', payload)
+      Models::BatchDeliveryResult.new(result)
+    end
+
+    # گزارش تحویل پیامک LikeToLike
+    #
+    # @param sms_id [Integer] شناسه پیامک
+    # @return [Models::BatchDeliveryResult] نتیجه گزارش
+    def get_delivery_like_to_like(sms_id:)
+      payload = { smsId: sms_id }
+
+      result = post('/GetDeliveryLikeToLike', payload)
+      Models::BatchDeliveryResult.new(result)
+    end
+
+    # ========== حساب کاربری ==========
+
+    # دریافت اعتبار حساب
+    #
+    # @return [Models::CreditResult] نتیجه اعتبار
+    def get_credit
+      result = post('/GetCredit', {})
+      Models::CreditResult.new(result)
+    end
+
+    # دریافت لیست شماره‌های فرستنده
+    #
+    # @return [Models::SenderNumbersResult] نتیجه شماره‌ها
+    def get_sender_numbers
+      result = post('/GetSenderNumbers', {})
+      Models::SenderNumbersResult.new(result)
+    end
+
+    # ========== صندوق ورودی ==========
+
+    # دریافت تعداد پیامک‌های دریافتی
+    #
+    # @param is_read [Boolean] فقط خوانده شده‌ها؟
+    # @return [Models::InboxCountResult] نتیجه تعداد
+    def get_inbox_count(is_read: false)
+      payload = { isRead: is_read }
+
+      result = post('/GetInboxCount', payload)
+      Models::InboxCountResult.new(result)
+    end
+
+    # دریافت پیامک‌ها
+    #
+    # @param message_type [Integer] نوع پیامک
+    # @param from_numbers [String] شماره‌های فرستنده (با کاما جدا شده)
+    # @param page_index [Integer] شماره صفحه
+    # @param page_size [Integer] تعداد رکورد در صفحه
+    # @return [Models::MessagesResult] نتیجه پیامک‌ها
+    def get_messages(message_type:, from_numbers:, page_index: 1, page_size: 100)
+      payload = {
+        messageType: message_type,
+        fromNumbers: from_numbers,
+        index: page_index,
+        count: page_size
+      }
+
+      result = post('/GetMessages', payload)
+      Models::MessagesResult.new(result)
+    end
+
+    # دریافت پیامک‌ها بر اساس بازه زمانی
+    #
+    # @param message_type [Integer] نوع پیامک
+    # @param from_numbers [String] شماره‌های فرستنده (با کاما جدا شده)
+    # @param from_date [Time, DateTime, String] تاریخ شروع
+    # @param to_date [Time, DateTime, String] تاریخ پایان
+    # @return [Models::MessagesResult] نتیجه پیامک‌ها
+    def get_messages_by_date_range(message_type:, from_numbers:, from_date:, to_date:)
+      payload = {
+        messageType: message_type,
+        fromNumbers: from_numbers,
+        fromDate: format_datetime(from_date),
+        toDate: format_datetime(to_date)
+      }
+
+      result = post('/GetMessagesByDateRange', payload)
+      Models::MessagesResult.new(result)
+    end
+
+    # ========== لیست سیاه ==========
+
+    # استخراج شماره‌های لیست سیاه مخابرات
+    #
+    # @param numbers [Array<String>] لیست شماره‌ها
+    # @return [Models::BlacklistNumbersResult] نتیجه
+    def extract_telecom_blacklist_numbers(numbers:)
+      validate_presence!(numbers: numbers)
+
+      payload = { numbers: Array(numbers).join(',') }
+
+      result = post('/ExtractTelecomBlacklistNumbers', payload)
+      Models::BlacklistNumbersResult.new(result)
+    end
+
+    # بررسی اینکه آیا شماره در لیست سیاه مخابرات هست؟
+    #
+    # @param number [String] شماره موبایل
+    # @return [Models::IsBlacklistResult] نتیجه
+    def number_is_in_telecom_blacklist(number:)
+      validate_presence!(number: number)
+
+      payload = { number: number }
+
+      result = post('/NumberIsInTelecomBlacklist', payload)
+      Models::IsBlacklistResult.new(result)
+    end
+
+    # ========== اعتبارسنجی ==========
+
+    # بررسی محتوای پیامک (فیلتر کلمات)
+    #
+    # @param message [String] متن پیامک
+    # @return [Models::CheckContentResult] نتیجه
+    def check_sms_content(message:)
+      validate_presence!(message: message)
+
+      payload = { message: message }
+
+      result = post('/CheckSmsContent', payload)
+      Models::CheckContentResult.new(result)
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: @base_url) do |faraday|
+        faraday.request :json
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+        faraday.options.timeout = @timeout
+        faraday.options.open_timeout = @timeout
+      end
+    end
+
+    def post(endpoint, payload)
+      response = connection.post(endpoint) do |req|
+        req.headers['Content-Type'] = 'application/json'
+        req.headers['X-API-Key'] = @api_key
+        req.body = payload.to_json
+      end
+
+      handle_response(response)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise Errors::NetworkError, "خطا در ارتباط با سرور: #{e.message}"
+    end
+
+    def handle_response(response)
+      unless response.success?
+        raise Errors::ApiError.new(
+          "خطا در ارتباط با سرور: #{response.status}",
+          response.status,
+          http_status: response.status,
+          response_body: response.body
+        )
+      end
+
+      body = response.body
+      body = JSON.parse(body) if body.is_a?(String)
+
+      if body.nil?
+        raise Errors::ApiError.new('پاسخ نامعتبر از سرور')
+      end
+
+      unless body['success']
+        error_message = body['errorMessage'] || 'خطای نامشخص'
+        raise Errors::ApiError.new(error_message)
+      end
+
+      body['result']
+    end
+
+    def validate_presence!(**params)
+      params.each do |key, value|
+        if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+          raise Errors::ValidationError, "پارامتر #{key} نمی‌تواند خالی باشد"
+        end
+      end
+    end
+
+    def format_datetime(value)
+      case value
+      when Time, DateTime
+        value.iso8601
+      when String
+        value
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/lib/niazpardaz_sms/errors/niazpardaz_api_error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module NiazpardazSms
+  module Errors
+    # خطای پایه برای تمام خطاهای نیازپرداز
+    class NiazpardazError < StandardError
+      attr_reader :error_code
+
+      def initialize(message = nil, error_code = nil)
+        @error_code = error_code
+        super(message)
+      end
+    end
+
+    # خطای مربوط به API نیازپرداز
+    class ApiError < NiazpardazError
+      attr_reader :http_status, :response_body
+
+      def initialize(message = nil, error_code = nil, http_status: nil, response_body: nil)
+        @http_status = http_status
+        @response_body = response_body
+        super(message, error_code)
+      end
+    end
+
+    # خطای اعتبارسنجی پارامترها
+    class ValidationError < NiazpardazError; end
+
+    # خطای شبکه
+    class NetworkError < NiazpardazError; end
+
+    # خطای احراز هویت
+    class AuthenticationError < ApiError; end
+
+    # خطای محدودیت درخواست
+    class RateLimitError < ApiError; end
+
+    # خطای سرور
+    class ServerError < ApiError; end
+  end
+end

data/lib/niazpardaz_sms/models/responses.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module NiazpardazSms
+  module Models
+    # کلاس پایه برای تمام پاسخ‌ها
+    class BaseResponse
+      attr_reader :raw_response
+
+      def initialize(data = {})
+        @raw_response = data
+      end
+
+      def success?
+        false
+      end
+    end
+
+    # نتیجه ارسال پیامک گروهی
+    class SendBatchSmsResult < BaseResponse
+      attr_reader :batch_sms_id, :result_code
+
+      def initialize(data = {})
+        super
+        @batch_sms_id = data['batchSmsId']
+        @result_code = data['resultCode']
+      end
+
+      def success?
+        SendResultCode.success?(@result_code)
+      end
+
+      def result_description
+        SendResultCode.description(@result_code)
+      end
+    end
+
+    # نتیجه ارسال پیامک LikeToLike
+    class SendLikeToLikeResult < BaseResponse
+      attr_reader :sms_id, :result_code
+
+      def initialize(data = {})
+        super
+        @sms_id = data['smsId']
+        @result_code = data['resultCode']
+      end
+
+      def success?
+        SendResultCode.success?(@result_code)
+      end
+
+      def result_description
+        SendResultCode.description(@result_code)
+      end
+    end
+
+    # نتیجه گزارش تحویل
+    class BatchDeliveryResult < BaseResponse
+      attr_reader :result_code, :numbers, :delivery_status
+
+      def initialize(data = {})
+        super
+        @result_code = data['resultCode']
+        @numbers = data['numbers'] || []
+        @delivery_status = data['deliveryStatus'] || []
+      end
+
+      def success?
+        DeliveryResultCode.success?(@result_code)
+      end
+
+      def result_description
+        DeliveryResultCode.description(@result_code)
+      end
+
+      # برگرداندن وضعیت تحویل به صورت hash
+      def delivery_hash
+        @numbers.zip(@delivery_status).to_h
+      end
+    end
+
+    # نتیجه دریافت اعتبار
+    class CreditResult < BaseResponse
+      attr_reader :credit, :result_code
+
+      def initialize(data = {})
+        super
+        @credit = data['credit']&.to_f
+        @result_code = data['resultCode']
+      end
+
+      def success?
+        CreditResultCode.success?(@result_code)
+      end
+
+      def result_description
+        CreditResultCode.description(@result_code)
+      end
+    end
+
+    # نتیجه دریافت شماره‌های فرستنده
+    class SenderNumbersResult < BaseResponse
+      attr_reader :senders, :result_code
+
+      def initialize(data = {})
+        super
+        @senders = data['senders'] || []
+        @result_code = data['resultCode']
+      end
+
+      def success?
+        SenderNumbersResultCode.success?(@result_code)
+      end
+
+      def result_description
+        SenderNumbersResultCode.description(@result_code)
+      end
+    end
+
+    # نتیجه دریافت تعداد پیامک‌های دریافتی
+    class InboxCountResult < BaseResponse
+      attr_reader :inbox_count, :result_code
+
+      def initialize(data = {})
+        super
+        @inbox_count = data['inboxCount']
+        @result_code = data['resultCode']
+      end
+
+      def success?
+        InboxCountResultCode.success?(@result_code)
+      end
+
+      def result_description
+        InboxCountResultCode.description(@result_code)
+      end
+    end
+
+    # اطلاعات پیامک
+    class MessageInfo
+      attr_reader :message_id, :user_id, :tariff, :content, :action_date_time,
+                  :message_type, :sender, :receiver, :flash, :pages, :lang,
+                  :status, :send_status, :send_method, :cost, :title, :count,
+                  :sent, :desc, :not_sent, :money_is_refunded, :is_read
+
+      def initialize(data = {})
+        @message_id = data['messageId']
+        @user_id = data['userId']
+        @tariff = data['tariff']&.to_f
+        @content = data['content']
+        @action_date_time = parse_datetime(data['actionDateTime'])
+        @message_type = data['messageType']
+        @sender = data['sender']
+        @receiver = data['receiver']
+        @flash = data['flash']
+        @pages = data['pages']
+        @lang = data['lang']
+        @status = data['status']
+        @send_status = data['sendStatus']
+        @send_method = data['sendMethod']
+        @cost = data['cost']&.to_f
+        @title = data['title']
+        @count = data['count']
+        @sent = data['sent']
+        @desc = data['desc']
+        @not_sent = data['notSent']
+        @money_is_refunded = data['moneyIsRefunded']
+        @is_read = data['isRead']
+      end
+
+      private
+
+      def parse_datetime(value)
+        return nil if value.nil?
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # نتیجه دریافت پیامک‌ها
+    class MessagesResult < BaseResponse
+      attr_reader :messages, :result_code
+
+      def initialize(data = {})
+        super
+        @result_code = data['resultCode']
+        @messages = (data['messages'] || []).map { |m| MessageInfo.new(m) }
+      end
+
+      def success?
+        @result_code.zero?
+      end
+    end
+
+    # نتیجه استخراج شماره‌های لیست سیاه
+    class BlacklistNumbersResult < BaseResponse
+      attr_reader :blacklist_numbers, :result_code
+
+      def initialize(data = {})
+        super
+        @blacklist_numbers = data['blackListNumbers'] || []
+        @result_code = data['resultCode']
+      end
+
+      def success?
+        BlacklistResultCode.success?(@result_code)
+      end
+
+      def result_description
+        BlacklistResultCode.description(@result_code)
+      end
+    end
+
+    # نتیجه بررسی شماره در لیست سیاه
+    class IsBlacklistResult < BaseResponse
+      attr_reader :is_black, :result_code
+
+      def initialize(data = {})
+        super
+        @is_black = data['isBlack']
+        @result_code = data['resultCode']
+      end
+
+      def success?
+        BlacklistResultCode.success?(@result_code)
+      end
+
+      def result_description
+        BlacklistResultCode.description(@result_code)
+      end
+
+      def blacklisted?
+        @is_black == true
+      end
+    end
+
+    # نتیجه بررسی محتوای پیامک
+    class CheckContentResult < BaseResponse
+      attr_reader :is_valid, :result_code
+
+      def initialize(data = {})
+        super
+        @is_valid = data['isValid']
+        @result_code = data['resultCode']
+      end
+
+      def success?
+        CheckContentResultCode.success?(@result_code)
+      end
+
+      def result_description
+        CheckContentResultCode.description(@result_code)
+      end
+
+      def valid?
+        @is_valid == true
+      end
+    end
+  end
+end