niazpardaz_sms 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4793bbddd7bbaceef2d5959e0233c90292f5e11230cb4e94613bf0db9fb1c55
+  data.tar.gz: dbe84c58e2dc06902b28c422b4d12599c51d584499cf4b79b0ddd9cbb6ba6a28
+SHA512:
+  metadata.gz: 80a7f4826ab2c93234005507de892437dc88f11161bdc000be3f55c2fa338d112de0e622ff3dca45aa0f85b693c87ef0d4cbba4156da09aaf86d6e26f512bed5
+  data.tar.gz: 56e777cbe89886f6d6dfc3ea1aa04da9b5faa653b23e9f65572b9281ae178ef5a83948c89a309cd1ce89488c6613933322bc2833c4c09582a3480ff7d7a1603d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,35 @@
+# .rubocop.yml
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.6
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+
+Metrics/ClassLength:
+  Max: 200  
+
+Metrics/MethodLength:
+  Max: 25  
+
+Metrics/AbcSize:
+  Max: 35   
+
+Layout/LineLength:
+  Max: 250  
+
+Naming/AccessorMethodName:
+  Enabled: false 
+
+Style/HashSyntax:
+  EnforcedStyle: ruby19_no_mixed_keys
+
+Style/RaiseArgs:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Gemspec/OrderedDependencies:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+تمام تغییرات قابل توجه این پروژه در این فایل مستند می‌شود.
+
+فرمت بر اساس [Keep a Changelog](https://keepachangelog.com/fa/1.0.0/) است
+و این پروژه از [Semantic Versioning](https://semver.org/lang/fa/) پیروی می‌کند.
+
+## [Unreleased]
+
+## [1.0.2] - 2025-02-16
+
+### اضافه شده
+- کلاینت اصلی `NiazpardazSms::Client` برای ارتباط با API
+- ارسال پیامک تکی (`send_sms`)
+- ارسال پیامک گروهی (`send_bulk_sms`)
+- ارسال پیامک LikeToLike (`send_sms_like_to_like`)
+- ارسال پیامک صوتی OTP (`send_voice_otp`)
+- گزارش تحویل پیامک گروهی (`get_batch_delivery`)
+- گزارش تحویل پیامک LikeToLike (`get_delivery_like_to_like`)
+- دریافت اعتبار حساب (`get_credit`)
+- دریافت شماره‌های فرستنده (`get_sender_numbers`)
+- دریافت تعداد پیامک‌های دریافتی (`get_inbox_count`)
+- دریافت پیامک‌ها (`get_messages`)
+- دریافت پیامک‌ها بر اساس بازه زمانی (`get_messages_by_date_range`)
+- استخراج شماره‌های لیست سیاه (`extract_telecom_blacklist_numbers`)
+- بررسی شماره در لیست سیاه (`number_is_in_telecom_blacklist`)
+- بررسی محتوای پیامک (`check_sms_content`)
+- پشتیبانی از Rails با Railtie و Generator
+- پشتیبانی از Sinatra
+- پشتیبانی از Hanami
+- پشتیبانی از سایر فریم‌ورک‌های Ruby
+- مدل‌های کامل برای تمام پاسخ‌های API
+- کدهای نتیجه با توضیحات فارسی
+- مدیریت خطا با کلاس‌های اختصاصی
+- مستندات کامل به زبان فارسی
+
+[Unreleased]: https://github.com/NiazpardazSms/niazpardaz-sms-ruby/compare/v1.0.2...HEAD
+[1.0.0]: https://github.com/NiazpardazSms/niazpardaz-sms-ruby/releases/tag/v1.0.2

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in niazpardaz_sms.gemspec
+gemspec
+
+group :development, :test do
+  gem 'bundler', '>= 2.0', '< 5.0'
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.0'
+  gem 'vcr', '~> 6.0'
+  gem 'webmock', '~> 3.0'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Niazpardaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,518 @@
+# NiazpardazSms SDK for Ruby
+
+کتابخانه رسمی Ruby برای کار با API پیامکی نیازپرداز
+
+[![Gem Version](https://badge.fury.io/rb/niazpardaz_sms.svg)](https://badge.fury.io/rb/niazpardaz_sms)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## نصب
+
+### Bundler (توصیه شده)
+
+به فایل `Gemfile` اضافه کنید:
+
+```ruby
+gem 'niazpardaz_sms'
+```
+
+سپس اجرا کنید:
+
+```bash
+bundle install
+```
+
+### نصب مستقیم
+
+```bash
+gem install niazpardaz_sms
+```
+
+## پیکربندی
+
+### Ruby خالص
+
+```ruby
+require 'niazpardaz_sms'
+
+# روش 1: ایجاد مستقیم کلاینت
+client = NiazpardazSms::Client.new('YOUR_API_KEY')
+
+# روش 2: پیکربندی سراسری
+NiazpardazSms.configure do |config|
+  config.default_api_key = 'YOUR_API_KEY'
+  config.default_timeout = 30
+end
+
+client = NiazpardazSms.client
+```
+
+### Rails
+
+1. اجرای generator:
+
+```bash
+rails generate niazpardaz_sms:install
+```
+
+2. ویرایش فایل `config/initializers/niazpardaz_sms.rb`:
+
+```ruby
+NiazpardazSms.configure do |config|
+  config.default_api_key = ENV.fetch('NIAZPARDAZ_API_KEY', nil)
+end
+```
+
+3. یا استفاده از Rails credentials:
+
+```bash
+rails credentials:edit
+```
+
+```yaml
+niazpardaz_sms:
+  api_key: YOUR_API_KEY
+```
+
+### Sinatra
+
+```ruby
+require 'sinatra'
+require 'niazpardaz_sms'
+
+configure do
+  NiazpardazSms.configure do |config|
+    config.default_api_key = ENV['NIAZPARDAZ_API_KEY']
+  end
+end
+
+post '/send_sms' do
+  client = NiazpardazSms.client
+  result = client.send_sms(
+    from_number: params[:from],
+    to_number: params[:to],
+    message: params[:message]
+  )
+  
+  json result.success? ? { status: 'ok', id: result.batch_sms_id } : { status: 'error' }
+end
+```
+
+### Hanami
+
+```ruby
+# config/providers/niazpardaz_sms.rb
+Hanami.app.register_provider :niazpardaz_sms do
+  start do
+    require 'niazpardaz_sms'
+    
+    NiazpardazSms.configure do |config|
+      config.default_api_key = ENV['NIAZPARDAZ_API_KEY']
+    end
+    
+    register 'niazpardaz_sms.client', NiazpardazSms.client
+  end
+end
+```
+
+## شروع سریع
+
+```ruby
+require 'niazpardaz_sms'
+
+# ساخت کلاینت با API Key
+client = NiazpardazSms::Client.new('YOUR_API_KEY')
+
+# ارسال پیامک
+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
+```
+
+## امکانات
+
+### ارسال پیامک تکی
+
+```ruby
+result = client.send_sms(
+  from_number: '10001234',
+  to_number: '09123456789',
+  message: 'متن پیامک',
+  is_flash: false,
+  send_delay: nil
+)
+
+puts "شناسه ارسال: #{result.batch_sms_id}"
+puts "وضعیت: #{result.result_description}"
+```
+
+### ارسال گروهی (یک متن به چند شماره)
+
+```ruby
+result = client.send_bulk_sms(
+  from_number: '10001234',
+  to_numbers: ['09123456789', '09198765432'],
+  message: 'پیام گروهی',
+  is_flash: false
+)
+
+puts "شناسه ارسال: #{result.batch_sms_id}"
+puts "وضعیت: #{result.result_description}"
+```
+
+### ارسال LikeToLike (هر شماره پیام مخصوص خودش)
+
+```ruby
+result = client.send_sms_like_to_like(
+  from_number: '10001234',
+  to_numbers: ['09123456789', '09198765432'],
+  messages: ['سلام علی جان', 'سلام رضا جان']
+)
+
+puts "SmsId: #{result.sms_id}"
+```
+
+### ارسال پیامک صوتی OTP
+
+```ruby
+result = client.send_voice_otp(
+  from_number: '10001234',
+  to_number: '09123456789',
+  otp: '12345'
+)
+
+puts "شناسه ارسال: #{result.batch_sms_id}"
+puts "وضعیت: #{result.result_description}"
+```
+
+### گزارش تحویل ارسال گروهی
+
+```ruby
+delivery = client.get_batch_delivery(
+  batch_sms_id: 123456,
+  page_index: 1,
+  page_size: 100
+)
+
+if delivery.success?
+  delivery.delivery_hash.each do |number, status|
+    puts "#{number}: #{NiazpardazSms::Models::SmsDeliveryStatus.description(status)}"
+  end
+end
+```
+
+### گزارش تحویل ارسال LikeToLike
+
+```ruby
+delivery = client.get_delivery_like_to_like(sms_id: 789)
+
+if delivery.success?
+  delivery.numbers.each_with_index do |number, i|
+    puts "#{number}: #{delivery.delivery_status[i]}"
+  end
+end
+```
+
+### اعتبار
+
+```ruby
+credit = client.get_credit
+
+if credit.success?
+  puts "اعتبار: #{credit.credit}"
+end
+```
+
+### شماره‌های فرستنده
+
+```ruby
+senders = client.get_sender_numbers
+
+senders.senders.each do |sender|
+  puts sender
+end
+```
+
+### تعداد پیامک‌های دریافتی
+
+```ruby
+inbox_count = client.get_inbox_count(is_read: false)
+puts "تعداد: #{inbox_count.inbox_count}"
+```
+
+### لیست پیامک‌ها
+
+```ruby
+messages = client.get_messages(
+  message_type: 1,
+  from_numbers: '10001234',
+  page_index: 1,
+  page_size: 50
+)
+
+if messages.success?
+  messages.messages.each do |message|
+    puts "متن پیامک: #{message.content}"
+  end
+end
+```
+
+### دریافت پیامک‌ها بر اساس بازه زمانی
+
+```ruby
+messages = client.get_messages_by_date_range(
+  message_type: 1,
+  from_numbers: '10001234',
+  from_date: Time.now - 86400, # دیروز
+  to_date: Time.now
+)
+
+if messages.success?
+  messages.messages.each do |message|
+    puts "متن پیامک: #{message.content}"
+  end
+end
+```
+
+### لیست سیاه مخابرات (بررسی یک شماره)
+
+```ruby
+result = client.number_is_in_telecom_blacklist(number: '09123456789')
+puts "در لیست سیاه: #{result.blacklisted?}"
+```
+
+### لیست سیاه مخابرات (استخراج شماره‌های لیست سیاه از یک لیست)
+
+```ruby
+blacklist = client.extract_telecom_blacklist_numbers(
+  numbers: ['09123456789', '09198765432', '09351234567']
+)
+
+if blacklist.success?
+  blacklist.blacklist_numbers.each do |number|
+    puts number
+  end
+end
+```
+
+### بررسی محتوای پیامک
+
+```ruby
+check = client.check_sms_content(message: 'متن پیامک تست')
+puts "متن معتبر است: #{check.valid?}"
+```
+
+---
+
+## کدهای نتیجه
+
+### کدهای نتیجه ارسال (SendResultCode)
+
+| کد | مقدار | توضیحات |
+|---:|-------|--------:|
+| 0 | SEND_WAS_SUCCESSFUL | ارسال موفق ✅ |
+| 1 | INVALID_USER_NAME_OR_PASSWORD | نام کاربر یا رمز نامعتبر |
+| 2 | USER_BLOCKED | کاربر مسدود |
+| 3 | INVALID_SENDER_NUMBER | شماره فرستنده نامعتبر |
+| 4 | LIMITATION_IN_DAILY_SEND | محدودیت روزانه |
+| 5 | LIMITATION_IN_RECEIVER_COUNT | حداکثر 1000 گیرنده |
+| 6 | SENDER_LINE_IS_INACTIVE | خط غیرفعال |
+| 7 | SMS_CONTENT_FILTERED_WORDS_IS_INCLUDED | کلمات فیلتر شده |
+| 8 | NO_CREDIT | اعتبار ناکافی |
+| 9 | SYSTEM_BEING_UPDATED | در حال بروزرسانی |
+| 10 | WEB_SERVICE_NOT_ACTIVE | وب سرویس غیرفعال |
+| 11 | NOT_IMPLEMENTED | پیاده سازی نشده |
+| 12 | LIKE_TO_LIKE_RECEIVER_AND_MESSAGE_COUNT_SHOULD_EQUAL | تعداد پیام و شماره نابرابر |
+| 13 | LIMITATION_IN_MESSAGE_CONTENT_COUNT | حداکثر 100 پیام |
+| 14 | USER_TARIFF_NOT_DETERMINED | تعرفه تعریف نشده |
+| 15 | DUPLICATE_SEND_SMS | ارسال تکراری |
+| 16 | INVALID_NUMBER_EMPTY_OR_BLACKLIST | شماره نامعتبر یا بلاک لیست |
+| 17 | TEXT_NOT_FOUND | متن خالی |
+| 18 | NOT_VALID_TEMPLATE_FOUND | مغایرت با قالب |
+| 19 | USER_EXPIRED | کاربر منقضی |
+| 20 | USER_IS_NOT_ACTIVE | کاربر غیرفعال |
+| 21 | INVALID_PARAMETERS | پارامتر نامعتبر |
+| 22 | IP_BLOCKED | آی پی بلاک شده |
+| 23 | ENQUEUE_FAILED | خطا در صف ارسال |
+| 24 | DUPLICATE_REQUEST_THRESHOLD | درخواست تکراری |
+| 25 | INVALID_API_KEY | ApiKey نامعتبر |
+| 26 | ERROR_CREATE_VOICE_FILE | خطا در ساخت فایل صوتی |
+
+### کدهای نتیجه گزارش تحویل (DeliveryResultCode)
+
+| کد | مقدار | توضیحات |
+|---:|-------|--------:|
+| 0 | SUCCESS | موفق ✅ |
+| -1 | SERVICE_CONNECTION_ERROR | خطا در ارتباط با سرویس دهنده |
+| -2 | INVALID_BATCH_SMS_ID | پیام با این کد وجود ندارد |
+| -3 | REPORT_EXPIRED | مهلت یک هفته ای گزارش پایان یافته |
+| -4 | MESSAGE_IN_QUEUE | پیام در صف ارسال مخابرات است |
+| -5 | TOO_EARLY | حداقل یک دقیقه بعد از ارسال اقدام نمایید |
+| -6 | IP_BLOCKED | آی پی بلاک شده |
+| -7 | INVALID_API_KEY | ApiKey نامعتبر |
+
+### وضعیت تحویل پیامک (SmsDeliveryStatus)
+
+| کد | مقدار | توضیحات |
+|---:|-------|--------:|
+| 0 | SENT_TO_TELECOM | ارسال شده به مخابرات |
+| 1 | DELIVERED | رسیده به گوشی ✅ |
+| 2 | NOT_DELIVERED | نرسیده به گوشی |
+| 3 | SMS_FAILED | خطای مخابراتی |
+| 4 | UNKNOWN_ERROR | خطای نامشخص |
+| 5 | RECEIVED_BY_TELECOM | رسیده به مخابرات |
+| 6 | NOT_RECEIVED_BY_TELECOM | نرسیده به مخابرات |
+| 7 | BLACKLISTED | مسدود شده توسط مقصد |
+| 8 | UNKNOWN | نامشخص |
+| 9 | REJECTED_BY_TELECOM | مخابرات پیام را مردود اعلام کرد |
+| 10 | CANCELED | کنسل شده توسط اپراتور |
+| 11 | NOT_SENT | ارسال نشده |
+| 12 | NO_TELEGRAM | تلگرام ندارد |
+| 13 | IN_QUEUE | در صف ارسال |
+
+---
+
+## مدیریت خطا
+
+```ruby
+begin
+  result = client.send_sms(
+    from_number: '10001234',
+    to_number: '09123456789',
+    message: 'تست'
+  )
+  
+  unless result.success?
+    puts "خطا: #{result.result_description}"
+  end
+rescue NiazpardazSms::Errors::ValidationError => e
+  puts "خطای اعتبارسنجی: #{e.message}"
+rescue NiazpardazSms::Errors::ApiError => e
+  puts "خطای API: #{e.message}"
+  puts "کد خطا: #{e.error_code}"
+  puts "وضعیت HTTP: #{e.http_status}"
+rescue NiazpardazSms::Errors::NetworkError => e
+  puts "خطای شبکه: #{e.message}"
+end
+```
+
+---
+
+## تنظیمات پیشرفته
+
+### استفاده از Faraday سفارشی
+
+```ruby
+require 'faraday'
+
+connection = Faraday.new do |faraday|
+  faraday.request :json
+  faraday.response :json
+  faraday.adapter :net_http
+  faraday.options.timeout = 60
+  faraday.options.open_timeout = 10
+end
+
+client = NiazpardazSms::Client.new('YOUR_API_KEY', connection: connection)
+```
+
+### تنظیم Timeout
+
+```ruby
+client = NiazpardazSms::Client.new('YOUR_API_KEY', timeout: 60)
+```
+
+### تغییر Base URL
+
+```ruby
+client = NiazpardazSms::Client.new(
+  'YOUR_API_KEY',
+  base_url: 'https://custom-url.example.com/api'
+)
+```
+
+---
+
+## استفاده در Background Jobs
+
+### Sidekiq
+
+```ruby
+class SendSmsJob
+  include Sidekiq::Job
+
+  def perform(to_number, message)
+    client = NiazpardazSms.client
+    result = client.send_sms(
+      from_number: ENV['SMS_FROM_NUMBER'],
+      to_number: to_number,
+      message: message
+    )
+    
+    unless result.success?
+      raise "SMS failed: #{result.result_description}"
+    end
+  end
+end
+
+# استفاده
+SendSmsJob.perform_async('09123456789', 'سلام!')
+```
+
+### ActiveJob (Rails)
+
+```ruby
+class SendSmsJob < ApplicationJob
+  queue_as :default
+
+  def perform(to_number, message)
+    client = NiazpardazSms.client
+    result = client.send_sms(
+      from_number: ENV['SMS_FROM_NUMBER'],
+      to_number: to_number,
+      message: message
+    )
+    
+    unless result.success?
+      raise "SMS failed: #{result.result_description}"
+    end
+  end
+end
+
+# استفاده
+SendSmsJob.perform_later('09123456789', 'سلام!')
+```
+
+---
+
+## سازگاری
+
+- Ruby 2.6+
+- Ruby 3.0+
+- Rails 5.2+
+- Rails 6.x
+- Rails 7.x
+- Sinatra
+- Hanami
+- Grape
+- و سایر فریم‌ورک‌های Ruby
+
+## وابستگی‌ها
+
+- faraday (>= 1.0, < 3.0)
+
+## مجوز
+
+MIT License
+
+## پشتیبانی
+
+- 📚 مستندات: https://niazpardaz-sms.com/webservice
+- 🐛 گزارش باگ: [GitHub Issues](https://github.com/NiazpardazSms/niazpardaz-sms-ruby/issues)

data/Rakefile

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc 'Open an interactive console'
+task :console do
+  require 'irb'
+  require 'niazpardaz_sms'
+  ARGV.clear
+  IRB.start
+end
+
+namespace :gem do
+  desc 'Build the gem'
+  task :build do
+    system 'gem build niazpardaz_sms.gemspec'
+  end
+
+  desc 'Install the gem locally'
+  task install: :build do
+    system 'gem install niazpardaz_sms-*.gem'
+  end
+
+  desc 'Push the gem to RubyGems'
+  task push: :build do
+    system 'gem push niazpardaz_sms-*.gem'
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module NiazpardazSms
+  module Generators
+    # Generator برای نصب و پیکربندی NiazpardazSms در Rails
+    #
+    # @example اجرای generator
+    #   rails generate niazpardaz_sms:install
+    #
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'ایجاد فایل پیکربندی NiazpardazSms برای Rails'
+
+      def create_initializer_file
+        template 'niazpardaz_sms.rb', 'config/initializers/niazpardaz_sms.rb'
+      end
+
+      def show_readme
+        readme 'README' if behavior == :invoke
+      end
+    end
+  end
+end