gorgias-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d789fee50053028836cd4a32424944eb403baa41cbdf9610d062446f3b7ba2d0
+  data.tar.gz: c58c53b9c328bb99b3de767a040528ac438aed475a946fffae2e3896426c5c48
+SHA512:
+  metadata.gz: 474da205ffa683947c0f5d2e4b8fac301a914bd6012e8a7ee4a86e2c9ed9d477af957f4b640a84ad97af462b50423e5857709d1f6c3043090c7475946e411d9b
+  data.tar.gz: 6ebb982d8e7b8e07e8a75aa9b64e6a13e422f9264986b6656a290a282689d0a19fe7e040c1b791b7143f6a77684ba65709d89a651445983d175a334728df5976

data/.rspec

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

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.1.0] - 2026-03-10
+
+### Added
+
+- Initial release of `gorgias-ruby`
+- `Gorgias::Client` with support for global and per-instance configuration
+- Resource classes for all major Gorgias API endpoints:
+  - Account, Customers, Events, Files, Integrations, Jobs, Macros, Rules
+  - Satisfaction Surveys, Search, Statistics, Tags, Tickets, Ticket Messages
+  - Users, Views, Widgets
+- `Gorgias::Object` for method-style and hash-style attribute access on API responses
+- Full error hierarchy (`APIError`, `AuthenticationError`, `NotFoundError`, `RateLimitError`, etc.)
+- Basic auth via domain + username + API key
+- Multipart file upload support via `faraday-multipart`

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Chayut Orapinpatipat
+
+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,256 @@
+# gorgias-ruby
+
+A professional-grade Ruby client for the [Gorgias REST API](https://developers.gorgias.com/).
+
+[![Gem Version](https://badge.fury.io/rb/gorgias-ruby.svg)](https://rubygems.org/gems/gorgias-ruby)
+[![Source](https://img.shields.io/badge/source-GitHub-blue)](https://github.com/Sentia/gorgias-ruby)
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "gorgias-ruby"
+```
+
+Or install directly:
+
+```bash
+gem install gorgias-ruby
+```
+
+## Configuration
+
+### Global (recommended for Rails apps)
+
+```ruby
+Gorgias.configure do |config|
+  config.domain   = "mycompany"          # your Gorgias subdomain
+  config.username = "me@mycompany.com"   # agent email
+  config.api_key  = ENV["GORGIAS_API_KEY"]
+end
+
+client = Gorgias.new   # uses global config
+```
+
+### Per-client
+
+```ruby
+client = Gorgias::Client.new(
+  domain:   "mycompany",
+  username: "me@mycompany.com",
+  api_key:  ENV["GORGIAS_API_KEY"]
+)
+```
+
+### Optional settings
+
+```ruby
+Gorgias.configure do |config|
+  config.timeout      = 30   # read timeout in seconds (default: 30)
+  config.open_timeout = 10   # connection timeout in seconds (default: 10)
+  config.logger       = Logger.new($stdout)
+end
+```
+
+## Usage
+
+All methods return `Gorgias::Object` instances (or arrays of them) that support
+both method-style and hash-style attribute access.
+
+### Account
+
+```ruby
+account = client.account.retrieve
+account.domain        # => "mycompany"
+account.status.status # => "active"
+```
+
+### Tickets
+
+```ruby
+tickets = client.tickets.list(status: "open", limit: 20)
+ticket  = client.tickets.retrieve(123)
+ticket.subject  # => "My order is late"
+
+client.tickets.create(
+  subject:  "Delivery issue",
+  channel:  "email",
+  customer: { email: "john@example.com" },
+  messages: [{ body_text: "Hi, my package hasn't arrived.", from_agent: false }]
+)
+
+client.tickets.update(123, status: "closed")
+client.tickets.close(123)
+client.tickets.mark_as_spam(123)
+client.tickets.delete(123)
+```
+
+### Ticket Messages
+
+```ruby
+messages = client.ticket_messages.list(123)
+message  = client.ticket_messages.retrieve(123, 456)
+
+client.ticket_messages.create(123, body_text: "Thanks!", from_agent: true, channel: "email")
+client.ticket_messages.update(123, 456, body_text: "Updated reply")
+client.ticket_messages.delete(123, 456)
+```
+
+### Customers
+
+```ruby
+customers = client.customers.list(email: "john@example.com")
+customer  = client.customers.retrieve(3924)
+
+client.customers.create(name: "John Smith", email: "john@example.com")
+client.customers.update(3924, name: "John Doe")
+client.customers.delete(3924)
+client.customers.delete_many([3924, 3925])
+```
+
+### Users (Agents)
+
+```ruby
+users = client.users.list
+client.users.create(name: "Alice", email: "alice@mycompany.com", role: "agent")
+client.users.update(7, name: "Alice B.")
+client.users.delete(7)
+```
+
+### Tags
+
+```ruby
+client.tags.list
+client.tags.create(name: "billing")
+client.tags.merge(3, target_id: 4)
+client.tags.delete(3)
+```
+
+### Events
+
+```ruby
+events = client.events.list(limit: 50)
+event  = client.events.retrieve(789)
+event.event_type  # => "ticket-created"
+```
+
+### Search
+
+```ruby
+client.search.tickets(query: "refund order")
+client.search.customers(query: "john smith")
+client.search.ticket_messages(query: "damaged")
+```
+
+### Statistics
+
+```ruby
+opts = { start_datetime: "2024-01-01T00:00:00Z", end_datetime: "2024-12-31T23:59:59Z" }
+
+client.statistics.tickets(**opts)
+client.statistics.customers(**opts)
+client.statistics.customer_satisfaction(**opts)
+```
+
+### Views
+
+```ruby
+client.views.list
+client.views.export(10)
+client.views.create(name: "Open VIP tickets", type: "ticket")
+```
+
+### Macros
+
+```ruby
+client.macros.list
+client.macros.create(name: "Refund approved", actions: [{ type: "assign-tag", value: "refunded" }])
+```
+
+### Rules
+
+```ruby
+client.rules.list
+rule = client.rules.retrieve(5)
+client.rules.create(name: "Auto-tag VIP", conditions: [], actions: [])
+client.rules.update(5, name: "Auto-tag VIP (updated)")
+client.rules.delete(5)
+```
+
+### Integrations / Jobs / Satisfaction Surveys / Widgets
+
+```ruby
+client.integrations.list
+client.jobs.cancel(8)
+client.satisfaction_surveys.accept(20, score: 5, body_text: "Great service!")
+client.widgets.list
+```
+
+### File Uploads
+
+```ruby
+files = client.files.upload(
+  "receipt.png" => File.open("/path/to/receipt.png", "rb"),
+  "invoice.pdf" => File.open("/path/to/invoice.pdf", "rb")
+)
+files.first.url  # => "https://gorgias.io/attachments/receipt.png"
+```
+
+## Response objects
+
+```ruby
+ticket = client.tickets.retrieve(1)
+
+ticket.id              # method access
+ticket[:id]            # hash-style access
+ticket.customer        # => #<Gorgias::Object ...>  (nested)
+ticket.customer.email  # => "john@example.com"
+ticket.tags            # => [#<Gorgias::Object ...>, ...]
+ticket.to_h            # plain Hash
+```
+
+## Error handling
+
+```ruby
+begin
+  client.tickets.retrieve(999)
+rescue Gorgias::NotFoundError => e
+  e.http_status   # => 404
+rescue Gorgias::RateLimitError => e
+  e.retry_after   # seconds until rate-limit resets
+rescue Gorgias::UnprocessableEntityError => e
+  e.errors        # => [{ "field" => "subject", ... }]
+rescue Gorgias::AuthenticationError
+  # bad credentials
+rescue Gorgias::APIError => e
+  # catch-all
+end
+```
+
+### Error hierarchy
+
+```
+Gorgias::Error
+├── Gorgias::ConfigurationError
+└── Gorgias::APIError
+    ├── Gorgias::BadRequestError          (400)
+    ├── Gorgias::AuthenticationError      (401)
+    ├── Gorgias::AuthorizationError       (403)
+    ├── Gorgias::NotFoundError            (404)
+    ├── Gorgias::ConflictError            (409)
+    ├── Gorgias::UnprocessableEntityError (422)
+    ├── Gorgias::RateLimitError           (429)
+    └── Gorgias::ServerError              (5xx)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/gorgias/client.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "base64"
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+module Gorgias
+  class Client
+    # @param options [Hash] Per-client overrides for any Configuration attribute.
+    #   If not provided, falls back to values from Gorgias.configuration.
+    def initialize(**options)
+      @config = build_config(options)
+      @config.validate!
+    end
+
+    # ── Resource accessors ────────────────────────────────────────────────── #
+
+    def account
+      @account ||= Resources::Account.new(self)
+    end
+
+    def customers
+      @customers ||= Resources::Customers.new(self)
+    end
+
+    def events
+      @events ||= Resources::Events.new(self)
+    end
+
+    def files
+      @files ||= Resources::Files.new(self)
+    end
+
+    def integrations
+      @integrations ||= Resources::Integrations.new(self)
+    end
+
+    def jobs
+      @jobs ||= Resources::Jobs.new(self)
+    end
+
+    def macros
+      @macros ||= Resources::Macros.new(self)
+    end
+
+    def rules
+      @rules ||= Resources::Rules.new(self)
+    end
+
+    def satisfaction_surveys
+      @satisfaction_surveys ||= Resources::SatisfactionSurveys.new(self)
+    end
+
+    def search
+      @search ||= Resources::Search.new(self)
+    end
+
+    def statistics
+      @statistics ||= Resources::Statistics.new(self)
+    end
+
+    def tags
+      @tags ||= Resources::Tags.new(self)
+    end
+
+    def tickets
+      @tickets ||= Resources::Tickets.new(self)
+    end
+
+    def ticket_messages
+      @ticket_messages ||= Resources::TicketMessages.new(self)
+    end
+
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+
+    def views
+      @views ||= Resources::Views.new(self)
+    end
+
+    def widgets
+      @widgets ||= Resources::Widgets.new(self)
+    end
+
+    # ── Low-level HTTP methods (used by Resource classes) ─────────────────── #
+
+    def get(path, params = {})
+      response = connection.get(path, compact(params))
+      handle_response(response)
+    end
+
+    def post(path, body = {}, headers: {})
+      response = connection.post(path) do |req|
+        if headers["Content-Type"] == "multipart/form-data"
+          # body is a Hash of label => IO — let Faraday::Multipart handle it
+          req.headers.merge!(headers)
+          req.body = body
+        else
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+      end
+      handle_response(response)
+    end
+
+    def put(path, body = {})
+      response = connection.put(path) do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      handle_response(response)
+    end
+
+    def delete(path, body = nil)
+      response = connection.delete(path) do |req|
+        if body
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+      end
+      handle_response(response)
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: @config.base_url) do |conn|
+        conn.request  :multipart
+        conn.adapter  Faraday.default_adapter
+
+        conn.options.timeout      = @config.timeout
+        conn.options.open_timeout = @config.open_timeout
+
+        conn.headers["Authorization"] = basic_auth_header
+        conn.headers["User-Agent"]    = "gorgias-ruby/#{Gorgias::VERSION} Ruby/#{RUBY_VERSION}"
+        conn.headers["Accept"]        = "application/json"
+
+        if @config.logger
+          conn.response :logger, @config.logger, bodies: true
+        end
+      end
+    end
+
+    def handle_response(response)
+      body = parse_body(response)
+
+      case response.status
+      when 200, 201
+        coerce(body)
+      when 204
+        true
+      when 400
+        raise BadRequestError.new(
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      when 401
+        raise AuthenticationError.new(
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      when 403
+        raise AuthorizationError.new(
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      when 404
+        raise NotFoundError.new(
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      when 409
+        raise ConflictError.new(
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      when 422
+        raise UnprocessableEntityError.new(
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      when 429
+        raise RateLimitError.new(
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      when 500..599
+        raise ServerError.new(
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      else
+        raise APIError.new(
+          "Unexpected HTTP status #{response.status}",
+          http_status: response.status, http_body: body, http_headers: response.headers
+        )
+      end
+    end
+
+    def parse_body(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def coerce(data)
+      case data
+      when Array then data.map { |item| item.is_a?(Hash) ? Gorgias::Object.new(item) : item }
+      when Hash  then Gorgias::Object.new(data)
+      else data
+      end
+    end
+
+    # Remove nil/blank values from query params so Faraday doesn't include them.
+    def compact(params)
+      params.reject { |_, v| v.nil? }
+    end
+
+    def basic_auth_header
+      encoded = Base64.strict_encode64("#{@config.username}:#{@config.api_key}")
+      "Basic #{encoded}"
+    end
+
+    def build_config(options)
+      config = Gorgias.configuration.dup
+      options.each { |key, value| config.public_send(:"#{key}=", value) }
+      config
+    end
+  end
+end