gorgias-ruby 0.1.0

data/lib/gorgias/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Gorgias
+  class Configuration
+    # Gorgias account domain (e.g., "mycompany" for mycompany.gorgias.com)
+    attr_accessor :domain
+
+    # Agent email address used for Basic auth
+    attr_accessor :username
+
+    # API token / password used for Basic auth
+    attr_accessor :api_key
+
+    # HTTP read timeout in seconds
+    attr_accessor :timeout
+
+    # HTTP connection open timeout in seconds
+    attr_accessor :open_timeout
+
+    # Optional logger — must respond to #debug, #info, #warn, #error
+    attr_accessor :logger
+
+    def initialize
+      @timeout      = 30
+      @open_timeout = 10
+    end
+
+    # Returns the base URL for the configured domain.
+    # @raise [ConfigurationError] if domain is blank
+    def base_url
+      raise ConfigurationError, "Gorgias domain is required" if domain.nil? || domain.strip.empty?
+
+      "https://#{domain.strip}.gorgias.com"
+    end
+
+    # Raises if any required field is missing.
+    def validate!
+      raise ConfigurationError, "domain is required"   if domain.nil?   || domain.strip.empty?
+      raise ConfigurationError, "username is required" if username.nil? || username.strip.empty?
+      raise ConfigurationError, "api_key is required"  if api_key.nil?  || api_key.strip.empty?
+    end
+  end
+end

data/lib/gorgias/error.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Gorgias
+  # Base error class for all Gorgias errors
+  class Error < StandardError; end
+
+  # Raised when the client is misconfigured (missing domain, credentials, etc.)
+  class ConfigurationError < Error; end
+
+  # Base class for all API-level errors
+  class APIError < Error
+    attr_reader :http_status, :http_body, :http_headers, :error_message
+
+    def initialize(message = nil, http_status: nil, http_body: nil, http_headers: nil)
+      @http_status   = http_status
+      @http_body     = http_body
+      @http_headers  = http_headers
+      @error_message = extract_message(http_body)
+      super(message || @error_message || "API error (HTTP #{http_status})")
+    end
+
+    private
+
+    def extract_message(body)
+      return unless body.is_a?(Hash)
+
+      body["error"] || body["message"] || body.dig("errors", 0, "message")
+    end
+  end
+
+  # 400 Bad Request
+  class BadRequestError < APIError; end
+
+  # 401 Unauthorized — invalid credentials
+  class AuthenticationError < APIError; end
+
+  # 403 Forbidden — valid credentials but insufficient permissions
+  class AuthorizationError < APIError; end
+
+  # 404 Not Found
+  class NotFoundError < APIError; end
+
+  # 409 Conflict
+  class ConflictError < APIError; end
+
+  # 422 Unprocessable Entity — validation errors
+  class UnprocessableEntityError < APIError
+    attr_reader :errors
+
+    def initialize(message = nil, http_status: nil, http_body: nil, http_headers: nil)
+      super
+      @errors = http_body.is_a?(Hash) ? (http_body["errors"] || []) : []
+    end
+  end
+
+  # 429 Too Many Requests
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message = nil, http_status: nil, http_body: nil, http_headers: nil)
+      super
+      @retry_after = http_headers&.[]("retry-after")&.to_i
+    end
+  end
+
+  # 5xx Server Errors
+  class ServerError < APIError; end
+end

data/lib/gorgias/object.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Gorgias
+  # Wraps a Gorgias API response hash providing convenient attribute-style
+  # access, nested object wrapping, and predicate helpers.
+  #
+  # @example
+  #   ticket = Gorgias::Object.new({ "id" => 1, "status" => "open", "customer" => { "email" => "a@b.com" } })
+  #   ticket.id        # => 1
+  #   ticket.status    # => "open"
+  #   ticket.customer  # => #<Gorgias::Object ...>
+  #   ticket.customer.email  # => "a@b.com"
+  #   ticket[:id]      # => 1
+  #   ticket.to_h      # => { "id" => 1, ... }
+  class Object
+    attr_reader :data
+
+    def initialize(data = {})
+      @data = stringify_keys(data)
+    end
+
+    # Hash-style key access.
+    def [](key)
+      val = @data[key.to_s]
+      coerce(val)
+    end
+
+    def []=(key, value)
+      @data[key.to_s] = value
+    end
+
+    # Checks if the key is present.
+    def key?(key)
+      @data.key?(key.to_s)
+    end
+
+    alias_method :has_key?, :key?
+
+    # Returns all keys as symbols.
+    def keys
+      @data.keys.map(&:to_sym)
+    end
+
+    # Returns a plain Ruby Hash with nested objects recursively converted.
+    def to_h
+      deep_to_h(@data)
+    end
+
+    alias_method :to_hash, :to_h
+
+    def to_s
+      inspect
+    end
+
+    def inspect
+      attrs = @data.map { |k, v| "#{k}=#{v.inspect}" }.join(", ")
+      "#<#{self.class.name} #{attrs}>"
+    end
+
+    def ==(other)
+      case other
+      when Gorgias::Object then @data == other.data
+      when Hash            then @data == stringify_keys(other)
+      else false
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      key = attribute_key(name)
+      @data.key?(key) || super
+    end
+
+    def method_missing(name, *args, &block)
+      key = attribute_key(name)
+
+      if @data.key?(key)
+        val = @data[key]
+        name.to_s.end_with?("?") ? !!val : coerce(val)
+      else
+        super
+      end
+    end
+
+    private
+
+    # Strip trailing "?" for predicate methods
+    def attribute_key(name)
+      name.to_s.delete_suffix("?")
+    end
+
+    def coerce(val)
+      case val
+      when ::Hash  then self.class.new(val)
+      when ::Array then val.map { |e| e.is_a?(::Hash) ? self.class.new(e) : e }
+      else val
+      end
+    end
+
+    def stringify_keys(hash)
+      hash.transform_keys(&:to_s)
+    rescue NoMethodError
+      hash
+    end
+
+    def deep_to_h(obj)
+      case obj
+      when ::Hash  then obj.transform_values { |v| deep_to_h(v) }
+      when ::Array then obj.map { |v| deep_to_h(v) }
+      else obj
+      end
+    end
+  end
+end

data/lib/gorgias/resources/account.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Account < Base
+      # Retrieve the account associated with the configured domain.
+      #
+      # @return [Gorgias::Object]
+      def retrieve
+        get("/api/account")
+      end
+    end
+  end
+end

data/lib/gorgias/resources/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def get(path, params = {})
+        @client.get(path, params)
+      end
+
+      def post(path, body = {}, headers: {})
+        @client.post(path, body, headers: headers)
+      end
+
+      def put(path, body = {})
+        @client.put(path, body)
+      end
+
+      def delete(path, body = nil)
+        @client.delete(path, body)
+      end
+    end
+  end
+end

data/lib/gorgias/resources/customers.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Customers < Base
+      # Create a new customer.
+      #
+      # @param params [Hash] Customer attributes:
+      #   - :name [String] Full name
+      #   - :email [String] Primary email address
+      #   - :external_id [String] ID in a foreign system
+      #   - :language [String] ISO 639-1 language code
+      #   - :timezone [String] IANA timezone name
+      #   - :channels [Array<Hash>] Communication channels
+      #   - :data [Hash] Custom data fields
+      # @return [Gorgias::Object] The created customer
+      def create(**params)
+        post("/api/customers", params)
+      end
+
+      # List customers (paginated, ordered alphabetically by name).
+      #
+      # @param params [Hash] Filter/pagination options:
+      #   - :email [String]
+      #   - :name [String]
+      #   - :external_id [String]
+      #   - :language [String]
+      #   - :timezone [String]
+      #   - :view_id [Integer]
+      #   - :cursor [String] Pagination cursor
+      #   - :limit [Integer] Max objects per page (default 30)
+      # @return [Array<Gorgias::Object>]
+      def list(**params)
+        get("/api/customers", params)
+      end
+
+      # Retrieve a single customer by ID.
+      #
+      # @param id [Integer, String] Customer ID
+      # @return [Gorgias::Object]
+      def retrieve(id)
+        get("/api/customers/#{id}/")
+      end
+
+      # Update a customer.
+      #
+      # @param id [Integer, String] Customer ID
+      # @param params [Hash] Attributes to update
+      # @return [Gorgias::Object]
+      def update(id, **params)
+        put("/api/customers/#{id}/", params)
+      end
+
+      # Delete a single customer.
+      #
+      # @param id [Integer, String] Customer ID
+      # @return [true]
+      def delete(id)
+        super("/api/customers/#{id}/")
+      end
+
+      # Bulk-delete multiple customers by ID.
+      #
+      # @param ids [Array<Integer>] Customer IDs to delete
+      # @return [true]
+      def delete_many(ids)
+        @client.delete("/api/customers", { ids: ids })
+      end
+    end
+  end
+end

data/lib/gorgias/resources/events.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Events < Base
+      # List events (paginated).
+      #
+      # @param params [Hash] Filter/pagination options:
+      #   - :cursor [String]
+      #   - :limit [Integer]
+      # @return [Array<Gorgias::Object>]
+      def list(**params)
+        get("/api/events", params)
+      end
+
+      # Retrieve a single event by ID.
+      #
+      # @param id [Integer, String] Event ID
+      # @return [Gorgias::Object]
+      def retrieve(id)
+        get("/api/events/#{id}/")
+      end
+    end
+  end
+end

data/lib/gorgias/resources/files.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Files < Base
+      # Upload one or more files.
+      #
+      # Each key in +files+ becomes the label (filename) of the uploaded file,
+      # and the value should be a readable IO object or a file path string.
+      #
+      # @example
+      #   client.files.upload("receipt.png" => File.open("/path/to/receipt.png"))
+      #
+      # @param files [Hash{String => IO, String}] label => file content
+      # @return [Array<Gorgias::Object>] Uploaded file objects
+      def upload(files)
+        payload = files.transform_values do |file|
+          next file if file.respond_to?(:read)
+
+          ::File.open(file, "rb")
+        end
+
+        post("/api/upload", payload, headers: { "Content-Type" => "multipart/form-data" })
+      end
+    end
+  end
+end

data/lib/gorgias/resources/integrations.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Integrations < Base
+      # Create a new integration.
+      #
+      # @param params [Hash] Integration attributes
+      # @return [Gorgias::Object]
+      def create(**params)
+        post("/api/integrations", params)
+      end
+
+      # List integrations.
+      #
+      # @param params [Hash] Filter/pagination options
+      # @return [Array<Gorgias::Object>]
+      def list(**params)
+        get("/api/integrations", params)
+      end
+
+      # Retrieve a single integration by ID.
+      #
+      # @param id [Integer, String]
+      # @return [Gorgias::Object]
+      def retrieve(id)
+        get("/api/integrations/#{id}/")
+      end
+
+      # Update an integration.
+      #
+      # @param id [Integer, String]
+      # @param params [Hash] Attributes to update
+      # @return [Gorgias::Object]
+      def update(id, **params)
+        put("/api/integrations/#{id}/", params)
+      end
+
+      # Delete an integration.
+      #
+      # @param id [Integer, String]
+      # @return [true]
+      def delete(id)
+        super("/api/integrations/#{id}/")
+      end
+    end
+  end
+end

data/lib/gorgias/resources/jobs.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Jobs < Base
+      # Create a new job.
+      #
+      # @param params [Hash] Job attributes
+      # @return [Gorgias::Object]
+      def create(**params)
+        post("/api/jobs", params)
+      end
+
+      # List jobs.
+      #
+      # @param params [Hash] Filter/pagination options
+      # @return [Array<Gorgias::Object>]
+      def list(**params)
+        get("/api/jobs", params)
+      end
+
+      # Retrieve a single job by ID.
+      #
+      # @param id [Integer, String]
+      # @return [Gorgias::Object]
+      def retrieve(id)
+        get("/api/jobs/#{id}/")
+      end
+
+      # Update a job.
+      #
+      # @param id [Integer, String]
+      # @param params [Hash] Attributes to update
+      # @return [Gorgias::Object]
+      def update(id, **params)
+        put("/api/jobs/#{id}/", params)
+      end
+
+      # Cancel a job.
+      #
+      # @param id [Integer, String]
+      # @return [true]
+      def cancel(id)
+        delete("/api/jobs/#{id}/")
+      end
+    end
+  end
+end

data/lib/gorgias/resources/macros.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Macros < Base
+      # Create a new macro.
+      #
+      # @param params [Hash] Macro attributes (name, actions, etc.)
+      # @return [Gorgias::Object]
+      def create(**params)
+        post("/api/macros", params)
+      end
+
+      # List macros.
+      #
+      # @param params [Hash] Filter/pagination options
+      # @return [Array<Gorgias::Object>]
+      def list(**params)
+        get("/api/macros", params)
+      end
+
+      # Retrieve a single macro by ID.
+      #
+      # @param id [Integer, String]
+      # @return [Gorgias::Object]
+      def retrieve(id)
+        get("/api/macros/#{id}/")
+      end
+
+      # Update a macro.
+      #
+      # @param id [Integer, String]
+      # @param params [Hash] Attributes to update
+      # @return [Gorgias::Object]
+      def update(id, **params)
+        put("/api/macros/#{id}/", params)
+      end
+
+      # Delete a macro.
+      #
+      # @param id [Integer, String]
+      # @return [true]
+      def delete(id)
+        super("/api/macros/#{id}/")
+      end
+    end
+  end
+end

data/lib/gorgias/resources/rules.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Rules < Base
+      # Create a new rule.
+      #
+      # @param params [Hash] Rule attributes
+      # @return [Gorgias::Object]
+      def create(**params)
+        post("/api/rules", params)
+      end
+
+      # List rules.
+      #
+      # @param params [Hash] Filter/pagination options
+      # @return [Array<Gorgias::Object>]
+      def list(**params)
+        get("/api/rules", params)
+      end
+
+      # Retrieve a single rule by ID.
+      #
+      # @param id [Integer, String]
+      # @return [Gorgias::Object]
+      def retrieve(id)
+        get("/api/rules/#{id}/")
+      end
+
+      # Update a rule.
+      #
+      # @param id [Integer, String]
+      # @param params [Hash] Attributes to update
+      # @return [Gorgias::Object]
+      def update(id, **params)
+        put("/api/rules/#{id}/", params)
+      end
+
+      # Delete a rule.
+      #
+      # @param id [Integer, String]
+      # @return [true]
+      def delete(id)
+        super("/api/rules/#{id}/")
+      end
+    end
+  end
+end

data/lib/gorgias/resources/satisfaction_surveys.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class SatisfactionSurveys < Base
+      # Create a satisfaction survey.
+      #
+      # @param params [Hash] Survey attributes (ticket_id, etc.)
+      # @return [Gorgias::Object]
+      def create(**params)
+        post("/api/satisfaction-surveys", params)
+      end
+
+      # Retrieve a satisfaction survey by ID.
+      #
+      # @param id [Integer, String]
+      # @return [Gorgias::Object]
+      def retrieve(id)
+        get("/api/satisfaction-surveys/#{id}/")
+      end
+
+      # Update a satisfaction survey.
+      #
+      # @param id [Integer, String]
+      # @param params [Hash] Attributes to update
+      # @return [Gorgias::Object]
+      def update(id, **params)
+        put("/api/satisfaction-surveys/#{id}/", params)
+      end
+
+      # Accept (submit a response to) a satisfaction survey.
+      #
+      # @param id [Integer, String]
+      # @param params [Hash] Response payload (score, body_text, etc.)
+      # @return [Gorgias::Object]
+      def accept(id, **params)
+        post("/api/satisfaction-surveys/#{id}/accept", params)
+      end
+    end
+  end
+end

data/lib/gorgias/resources/search.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Search < Base
+      # Search customers.
+      #
+      # @param params [Hash] Search parameters (query, filters, etc.)
+      # @return [Array<Gorgias::Object>]
+      def customers(**params)
+        post("/api/search/customers", params)
+      end
+
+      # Search tickets.
+      #
+      # @param params [Hash] Search parameters
+      # @return [Array<Gorgias::Object>]
+      def tickets(**params)
+        post("/api/search/tickets", params)
+      end
+
+      # Search ticket messages.
+      #
+      # @param params [Hash] Search parameters
+      # @return [Array<Gorgias::Object>]
+      def ticket_messages(**params)
+        post("/api/search/ticket-messages", params)
+      end
+    end
+  end
+end

data/lib/gorgias/resources/statistics.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gorgias
+  module Resources
+    class Statistics < Base
+      # Get customer statistics.
+      #
+      # @param params [Hash] Query parameters (start_datetime, end_datetime, etc.)
+      # @return [Gorgias::Object]
+      def customers(**params)
+        post("/api/statistics/customers", params)
+      end
+
+      # Get ticket statistics.
+      #
+      # @param params [Hash] Query parameters (start_datetime, end_datetime, etc.)
+      # @return [Gorgias::Object]
+      def tickets(**params)
+        post("/api/statistics/tickets", params)
+      end
+
+      # Get customer satisfaction statistics.
+      #
+      # @param params [Hash] Query parameters (start_datetime, end_datetime, etc.)
+      # @return [Gorgias::Object]
+      def customer_satisfaction(**params)
+        post("/api/statistics/customer-satisfaction", params)
+      end
+    end
+  end
+end