roistat 0.1.0

data/Rakefile

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

data/docs/ru/README.md

@@ -0,0 +1,142 @@
+# Roistat — документация на русском
+
+How-to для разработчиков, которые подключают гем `roistat` к приложению на Ruby или Rails.
+
+**Предпосылки:** Ruby 3+, ключ API Roistat, id проекта. Полные таблицы методов — в [корневом README](../../README.md) (английский).
+
+Официальные справочники Roistat:
+
+- [help-ru](https://help-ru.roistat.com/API/methods/about/) — основная инвентаризация путей
+- [help-en](https://help.roistat.com/API/methods/about/) — дашборды, виджеты и часть путей access/counter
+
+## Содержание
+
+- [Установка](#установка)
+- [Конфигурация](#конфигурация)
+- [Клиенты](#клиенты)
+- [Группы ресурсов](#группы-ресурсов)
+- [Ответы и ошибки](#ответы-и-ошибки)
+- [Разработка](#разработка)
+
+## Установка
+
+Добавьте гем в Gemfile:
+
+```ruby
+gem "roistat"
+```
+
+Затем:
+
+```fish
+bundle install
+```
+
+### Rails
+
+```fish
+bundle exec rails generate roistat:install
+```
+
+Генератор создаёт `config/initializers/roistat.rb` со всеми опциями и привязкой к ENV.
+
+## Конфигурация
+
+### Глобальная (удобно для Rails)
+
+```ruby
+Roistat.configure do |config|
+  config.api_key = ENV.fetch("ROISTAT_API_KEY")
+  config.project = ENV.fetch("ROISTAT_PROJECT_ID")
+end
+
+Roistat.client.projects.list
+```
+
+### Опции
+
+| Опция | Обязательна | По умолчанию | Назначение |
+|-------|-------------|--------------|------------|
+| `api_key` | да | — | ключ в заголовке `Api-key` |
+| `project` | для project-scoped вызовов | — | query `project` |
+| `base_url` | нет | `https://cloud.roistat.com/api/v1` | базовый URL |
+| `timeout` | нет | `30` | таймаут запроса (сек) |
+| `open_timeout` | нет | `10` | таймаут открытия соединения |
+| `binary_tempfile_threshold` | нет | `1048576` (1 MiB) | порог для `Tempfile` |
+
+Каждый запрос уходит с заголовком `Api-key`. Параметр `key` в query гем не использует.
+
+## Клиенты
+
+### Общий клиент
+
+`Roistat.client` собирается из глобальной конфигурации.
+
+### Отдельный клиент
+
+Удобно для нескольких проектов, джобов и скриптов:
+
+```ruby
+client = Roistat::Client.new(
+  api_key: ENV.fetch("ROISTAT_API_KEY"),
+  project: "12345"
+)
+client.orders.list(limit: 10)
+```
+
+### Низкоуровневый HTTP
+
+Если для пути ещё нет resource-метода:
+
+```ruby
+client.get("project/calltracking/phone/list", params: {limit: 10})
+client.post("project/events/send", body: {name: "purchase"})
+```
+
+## Группы ресурсов
+
+Ниже — точки входа. Сигнатуры и примеры смотрите в [английском README](../../README.md#resource-apis).
+
+| Группа | Клиент | Примеры задач |
+|--------|--------|---------------|
+| Projects | `client.projects` | список проектов, модули / counter list |
+| Access | `client.access` | права пользователей (RU и EN пути) |
+| Dashboards / Widgets | `client.dashboards`, `client.widgets` | дашборды и данные виджетов (EN) |
+| Billing | `client.billing` | транзакции и Excel-экспорт |
+| Calltracking | `client.calltracking` | скрипты, номера, звонки |
+| Orders / proxy / leads | `client.orders`, `client.proxy_leads`, `client.leads` | сделки и лиды |
+| Managers / lead hunter | `client.managers`, `client.lead_hunter` | менеджеры и охотник за лидами |
+| Clients / visits / events | `client.clients`, `client.visits`, `client.events` | клиенты, визиты, события |
+| Analytics / channels | `client.analytics`, `client.channels` | отчёты и источники |
+| Statistics / indicators | `client.statistics`, `client.indicators` | дневная статистика и индикаторы |
+| Email / SMS / mediaplan | `client.emailtracking`, `client.sms`, `client.mediaplan` | почта, SMS-отчёт, медиаплан |
+| Speech / VPBX | `client.speech`, `client.vpbx` | речевая аналитика и облачная АТС |
+
+Мутирующие методы (create / update / delete / buy / send) меняют данные в Roistat. Используйте их осознанно.
+
+## Ответы и ошибки
+
+- JSON-эндпоинты возвращают разобранный Hash (строковые ключи).
+- Бинарные ответы: `String`, если тело ≤ 1 MiB; иначе `Tempfile` (закройте и удалите файл после использования).
+
+| Код Roistat `error` | Исключение |
+|---------------------|------------|
+| `authentication_failed` | `Roistat::AuthenticationError` |
+| `authorization_failed` | `Roistat::AuthorizationError` |
+| `access_denied` | `Roistat::AccessDeniedError` |
+| `request_limit_error` | `Roistat::RateLimitError` |
+| прочее | `Roistat::Error` |
+
+Ошибки конфигурации (пустой ключ или project) поднимают `Roistat::ConfigurationError` до HTTP.
+
+## Разработка
+
+```fish
+bin/setup
+bundle exec rake
+# или: mise test ; and mise lint
+```
+
+Интерактивная консоль гема: `bin/console`.
+
+Багрепорты и PR: https://github.com/alec-c4/roistat

data/lefthook.yml

@@ -0,0 +1,8 @@
+pre-commit:
+  parallel: true
+  commands:
+    rubocop:
+      glob: "*.rb"
+      run: bundle exec rubocop --force-exclusion {staged_files}
+    rspec:
+      run: bundle exec rspec

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+class Roistat::Generators::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  desc "Creates a Roistat initializer with all configuration options"
+
+  def create_initializer_file
+    template "roistat.rb", "config/initializers/roistat.rb"
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Roistat.configure do |config|
+  # Required for project-scoped API calls.
+  config.api_key = ENV.fetch("ROISTAT_API_KEY")
+  config.project = ENV.fetch("ROISTAT_PROJECT_ID")
+
+  # Optional overrides.
+  # config.base_url = ENV.fetch("ROISTAT_BASE_URL", "https://cloud.roistat.com/api/v1")
+  # config.timeout = ENV.fetch("ROISTAT_TIMEOUT", 30).to_i
+  # config.open_timeout = ENV.fetch("ROISTAT_OPEN_TIMEOUT", 10).to_i
+  # config.binary_tempfile_threshold = ENV.fetch("ROISTAT_BINARY_TEMPFILE_THRESHOLD", 1_048_576).to_i
+end

data/lib/roistat/client.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "httpx"
+require "json"
+
+class Roistat::Client
+  attr_reader :api_key, :project, :base_url, :timeout, :open_timeout, :binary_tempfile_threshold
+
+  def initialize(
+    api_key:,
+    project: nil,
+    project_required: true,
+    base_url: nil,
+    timeout: nil,
+    open_timeout: nil,
+    binary_tempfile_threshold: nil
+  )
+    config = Roistat.configuration
+
+    @api_key = api_key
+    @project = project
+    @project_required = project_required
+    @base_url = base_url || config.base_url
+    @timeout = timeout || config.timeout
+    @open_timeout = open_timeout || config.open_timeout
+    @binary_tempfile_threshold = binary_tempfile_threshold || config.binary_tempfile_threshold
+
+    validate_credentials!
+  end
+
+  def get(path, params: {}, parse: :json)
+    request(:get, path, params: params, parse: parse)
+  end
+
+  def post(path, params: {}, body: nil, parse: :json)
+    request(:post, path, params: params, body: body, parse: parse)
+  end
+
+  def post_multipart(path, params: {}, form: {}, parse: :json)
+    validate_project! if @project_required
+
+    query = params.dup
+    query[:project] = project if project && !query.key?(:project) && !query.key?("project")
+
+    headers = {
+      "Api-key" => api_key,
+      "Accept" => "application/json"
+    }
+
+    http_response = session.request(
+      "POST",
+      url_for(path),
+      params: stringify_keys(query),
+      headers: headers,
+      form: normalize_multipart_form(form)
+    )
+    Roistat::Response.parse(
+      http_response,
+      parse: parse,
+      binary_tempfile_threshold: binary_tempfile_threshold
+    )
+  end
+
+  def request(method, path, params: {}, body: nil, parse: :json)
+    validate_project! if @project_required
+
+    query = params.dup
+    query[:project] = project if project && !query.key?(:project) && !query.key?("project")
+
+    headers = {
+      "Api-key" => api_key,
+      "Accept" => "application/json"
+    }
+
+    options = {params: stringify_keys(query), headers: headers}
+    if body
+      headers["Content-Type"] = "application/json"
+      options[:json] = body
+    end
+
+    http_response = session.request(method.to_s.upcase, url_for(path), **options)
+    Roistat::Response.parse(
+      http_response,
+      parse: parse,
+      binary_tempfile_threshold: binary_tempfile_threshold
+    )
+  end
+
+  def projects
+    @projects ||= Roistat::Resources::Projects.new(self)
+  end
+
+  def access
+    @access ||= Roistat::Resources::Access.new(self)
+  end
+
+  def dashboards
+    @dashboards ||= Roistat::Resources::Dashboards.new(self)
+  end
+
+  def widgets
+    @widgets ||= Roistat::Resources::Widgets.new(self)
+  end
+
+  def billing
+    @billing ||= Roistat::Resources::Billing.new(self)
+  end
+
+  def calltracking
+    @calltracking ||= Roistat::Resources::Calltracking.new(self)
+  end
+
+  def orders
+    @orders ||= Roistat::Resources::Orders.new(self)
+  end
+
+  def proxy_leads
+    @proxy_leads ||= Roistat::Resources::ProxyLeads.new(self)
+  end
+
+  def leads
+    @leads ||= Roistat::Resources::Leads.new(self)
+  end
+
+  def managers
+    @managers ||= Roistat::Resources::Managers.new(self)
+  end
+
+  def clients
+    @clients ||= Roistat::Resources::Clients.new(self)
+  end
+
+  def visits
+    @visits ||= Roistat::Resources::Visits.new(self)
+  end
+
+  def events
+    @events ||= Roistat::Resources::Events.new(self)
+  end
+
+  def analytics
+    @analytics ||= Roistat::Resources::Analytics.new(self)
+  end
+
+  def channels
+    @channels ||= Roistat::Resources::Channels.new(self)
+  end
+
+  def statistics
+    @statistics ||= Roistat::Resources::Statistics.new(self)
+  end
+
+  def indicators
+    @indicators ||= Roistat::Resources::Indicators.new(self)
+  end
+
+  def lead_hunter
+    @lead_hunter ||= Roistat::Resources::LeadHunter.new(self)
+  end
+
+  def emailtracking
+    @emailtracking ||= Roistat::Resources::Emailtracking.new(self)
+  end
+
+  def sms
+    @sms ||= Roistat::Resources::Sms.new(self)
+  end
+
+  def mediaplan
+    @mediaplan ||= Roistat::Resources::Mediaplan.new(self)
+  end
+
+  def speech
+    @speech ||= Roistat::Resources::Speech.new(self)
+  end
+
+  def vpbx
+    @vpbx ||= Roistat::Resources::Vpbx.new(self)
+  end
+
+  private
+
+  def validate_credentials!
+    raise Roistat::ConfigurationError, "api_key must be present" if blank?(api_key)
+    validate_project! if @project_required
+  end
+
+  def validate_project!
+    raise Roistat::ConfigurationError, "project must be present" if blank?(project)
+  end
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  def url_for(path)
+    "#{base_url.to_s.chomp("/")}/#{path.to_s.delete_prefix("/")}"
+  end
+
+  def session
+    @session ||= HTTPX.with(
+      timeout: {
+        request_timeout: timeout,
+        connect_timeout: open_timeout
+      }
+    )
+  end
+
+  def stringify_keys(hash)
+    hash.transform_keys(&:to_s)
+  end
+
+  def normalize_multipart_form(form)
+    form.transform_keys(&:to_s).transform_values do |value|
+      next value if value.respond_to?(:read) || value.is_a?(String)
+
+      value.to_s
+    end
+  end
+end

data/lib/roistat/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Roistat::Configuration
+  DEFAULT_BASE_URL = "https://cloud.roistat.com/api/v1"
+  DEFAULT_TIMEOUT = 30
+  DEFAULT_OPEN_TIMEOUT = 10
+  DEFAULT_BINARY_TEMPFILE_THRESHOLD = 1 * 1024 * 1024
+
+  attr_accessor :api_key, :project, :base_url, :timeout, :open_timeout, :binary_tempfile_threshold
+
+  def initialize
+    @base_url = DEFAULT_BASE_URL
+    @timeout = DEFAULT_TIMEOUT
+    @open_timeout = DEFAULT_OPEN_TIMEOUT
+    @binary_tempfile_threshold = DEFAULT_BINARY_TEMPFILE_THRESHOLD
+  end
+end

data/lib/roistat/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class Roistat::Error < StandardError
+  attr_reader :code, :http_status, :response_body
+
+  def initialize(message = nil, code: nil, http_status: nil, response_body: nil)
+    @code = code
+    @http_status = http_status
+    @response_body = response_body
+    super(message || code || self.class.name)
+  end
+end
+
+class Roistat::ConfigurationError < Roistat::Error; end
+class Roistat::AuthenticationError < Roistat::Error; end
+class Roistat::AuthorizationError < Roistat::Error; end
+class Roistat::AccessDeniedError < Roistat::Error; end
+class Roistat::RateLimitError < Roistat::Error; end

data/lib/roistat/resources/access.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Roistat::Resources::Access < Roistat::Resources::Base
+  # GET /project/permissions/user/list — help-ru.
+  def user_list
+    client.get("project/permissions/user/list")
+  end
+
+  # GET|POST /project/access/get-authorized-users — help-en.
+  def authorized_users(method: :get)
+    case method.to_sym
+    when :get
+      client.get("project/access/get-authorized-users")
+    when :post
+      client.post("project/access/get-authorized-users")
+    else
+      raise ArgumentError, "method must be :get or :post"
+    end
+  end
+
+  # POST /project/access/change — help-en.
+  def change(**body)
+    client.post("project/access/change", body: body)
+  end
+end

data/lib/roistat/resources/analytics.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+class Roistat::Resources::Analytics < Roistat::Resources::Base
+  # POST /project/analytics/data
+  def data(**body)
+    post_optional_body("project/analytics/data", body)
+  end
+
+  # POST /project/analytics/data/export/excel
+  def data_export_excel(**body)
+    client.post("project/analytics/data/export/excel", body: body, parse: :binary)
+  end
+
+  # POST /project/analytics/metrics-new
+  def metrics_new(**body)
+    post_optional_body("project/analytics/metrics-new", body)
+  end
+
+  # POST /project/analytics/dimensions
+  def dimensions(**body)
+    post_optional_body("project/analytics/dimensions", body)
+  end
+
+  # POST /project/analytics/dimension-values
+  def dimension_values(**body)
+    post_optional_body("project/analytics/dimension-values", body)
+  end
+
+  # POST /project/analytics/attribution-models
+  def attribution_models(**body)
+    post_optional_body("project/analytics/attribution-models", body)
+  end
+
+  # POST /project/analytics/list-orders
+  def list_orders(**body)
+    post_optional_body("project/analytics/list-orders", body)
+  end
+
+  # GET /project/analytics/metrics/custom/list
+  def custom_metrics_list(**params)
+    client.get("project/analytics/metrics/custom/list", params: params)
+  end
+
+  # POST /project/analytics/metrics/custom/manual/value/list
+  def custom_manual_value_list(**body)
+    post_optional_body("project/analytics/metrics/custom/manual/value/list", body)
+  end
+
+  # POST /project/analytics/metrics/custom/manual/value/add
+  def custom_manual_value_add(**body)
+    client.post("project/analytics/metrics/custom/manual/value/add", body: body)
+  end
+
+  # POST /project/analytics/metrics/custom/manual/value/delete
+  def custom_manual_value_delete(**body)
+    client.post("project/analytics/metrics/custom/manual/value/delete", body: body)
+  end
+
+  # POST /project/reports/funnel/data
+  def funnel_data(**body)
+    post_optional_body("project/reports/funnel/data", body)
+  end
+
+  # POST /project/analytics/event/add
+  def event_add(**body)
+    client.post("project/analytics/event/add", body: body)
+  end
+end

data/lib/roistat/resources/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class Roistat::Resources::Base
+  attr_reader :client
+
+  def initialize(client)
+    @client = client
+  end
+
+  private
+
+  def api_key_client
+    @api_key_client ||= Roistat::Client.new(
+      api_key: client.api_key,
+      project: nil,
+      project_required: false,
+      base_url: client.base_url,
+      timeout: client.timeout,
+      open_timeout: client.open_timeout,
+      binary_tempfile_threshold: client.binary_tempfile_threshold
+    )
+  end
+
+  def post_optional_body(path, body)
+    if body.nil? || body.empty?
+      client.post(path)
+    else
+      client.post(path, body: body)
+    end
+  end
+end

data/lib/roistat/resources/billing.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Roistat::Resources::Billing < Roistat::Resources::Base
+  # POST /user/billing/transactions/list
+  def transactions_list(period:)
+    client.post("user/billing/transactions/list", body: {period: period})
+  end
+
+  # POST /user/billing/transactions/list/export/excel
+  def transactions_export_excel(period:)
+    client.post(
+      "user/billing/transactions/list/export/excel",
+      body: {period: period},
+      parse: :binary
+    )
+  end
+end

data/lib/roistat/resources/calltracking.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+class Roistat::Resources::Calltracking < Roistat::Resources::Base
+  # POST /project/calltracking/script/list
+  def script_list(**body)
+    post("project/calltracking/script/list", body: body)
+  end
+
+  # POST /project/calltracking/script/create
+  def script_create(**body)
+    client.post("project/calltracking/script/create", body: body)
+  end
+
+  # POST /project/calltracking/script/update
+  def script_update(**body)
+    client.post("project/calltracking/script/update", body: body)
+  end
+
+  # POST /project/calltracking/script/delete
+  def script_delete(id:)
+    client.post("project/calltracking/script/delete", body: {id: id})
+  end
+
+  # POST /project/calltracking/phone/list
+  def phone_list(**body)
+    post("project/calltracking/phone/list", body: body)
+  end
+
+  # POST /project/calltracking/phone/prefix/list
+  def phone_prefix_list(**body)
+    post("project/calltracking/phone/prefix/list", body: body)
+  end
+
+  # POST /project/calltracking/phone/create
+  def phone_create(phones:)
+    client.post("project/calltracking/phone/create", body: {phones: phones})
+  end
+
+  # POST /project/calltracking/phone/buy
+  def phone_buy(prefix:, count:)
+    client.post("project/calltracking/phone/buy", body: {prefix: prefix, count: count})
+  end
+
+  # POST /project/calltracking/phone/update
+  def phone_update(**body)
+    client.post("project/calltracking/phone/update", body: body)
+  end
+
+  # POST /project/calltracking/phone/delete
+  def phone_delete(phones:)
+    client.post("project/calltracking/phone/delete", body: {phones: phones})
+  end
+
+  # POST /project/calltracking/call/list
+  def call_list(**body)
+    post("project/calltracking/call/list", body: body)
+  end
+
+  # POST /project/calltracking/call/update
+  def call_update(**body)
+    client.post("project/calltracking/call/update", body: body)
+  end
+
+  # POST /project/calltracking/call/delete
+  def call_delete(ids:)
+    client.post("project/calltracking/call/delete", body: {ids: ids})
+  end
+
+  # POST /project/calltracking/call/{callId}/file
+  def call_file(call_id:)
+    client.post("project/calltracking/call/#{call_id}/file", parse: :binary)
+  end
+
+  # POST /project/calltracking/call/xls/export
+  def call_xls_export(period:)
+    client.post(
+      "project/calltracking/call/xls/export",
+      body: {period: period},
+      parse: :binary
+    )
+  end
+
+  # POST /project/calltracking/data
+  def data(period:)
+    client.post("project/calltracking/data", body: {period: period})
+  end
+
+  # POST /project/phone-call
+  def phone_call(**body)
+    client.post("project/phone-call", body: body)
+  end
+
+  private
+
+  def post(path, body:)
+    if body.nil? || body.empty?
+      client.post(path)
+    else
+      client.post(path, body: body)
+    end
+  end
+end