lokalise-api-next 0.0.2

data/lib/lokalise_api_next/error.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  # Represents an error returned by the Vantage API.
+  class Error < StandardError
+    attr_reader :code, :details, :status, :validation_errors
+
+    VALIDATION_ERROR_FIELDS = %w[keyword instancePath schemaPath].freeze
+
+    def initialize(message, code:, details: nil, status: nil)
+      super(message)
+
+      @code = code
+      @details = details
+      @status = status
+      @validation_errors = extract_validation_errors
+    end
+
+    class << self
+      def from_response(body, status:)
+        raw_errors = body.is_a?(Hash) ? body['errors'] : nil
+
+        if raw_errors.is_a?(Array)
+          errors = raw_errors.filter_map { |item| parse(item, status: status) }
+          return Aggregate.new(errors, status: status) unless errors.empty?
+        end
+
+        parse(body, status: status) || generic_error_for(status)
+      end
+
+      def generic_error_for(status)
+        new(
+          'An unknown error occurred',
+          code: 'unknown_error',
+          status: status,
+          details: {
+            'status' => status,
+            'reason' => 'unexpected response format'
+          }
+        )
+      end
+
+      private
+
+      def parse(value, status:)
+        return unless value.is_a?(Hash)
+
+        message = value['message']
+        code = value['errorCode']
+
+        return unless message.is_a?(String) && code.is_a?(String)
+
+        details = value['details']
+
+        new(
+          message,
+          code: code,
+          details: details.is_a?(Hash) ? details : nil,
+          status: status
+        )
+      end
+    end
+
+    def detailed_message
+      result = "#{message} (Code: #{code})"
+      result += " | Details: #{Oj.dump(details)}" if details
+      result
+    end
+
+    private
+
+    def extract_validation_errors
+      return unless code.casecmp?('VALIDATION_ERROR')
+      return unless details.is_a?(Hash)
+
+      error_details = details['error']
+      return unless error_details.is_a?(Array)
+
+      error_details.select { |issue| validation_fields?(issue) }
+    end
+
+    # :reek:UtilityFunction
+    def validation_fields?(issue)
+      issue.is_a?(Hash) &&
+        VALIDATION_ERROR_FIELDS.all? { |key| issue[key].is_a?(String) } &&
+        issue['params'].is_a?(Hash) &&
+        (!issue.key?('message') || issue['message'].is_a?(String))
+    end
+
+    # Represents multiple errors returned in a single response.
+    class Aggregate < Error
+      attr_reader :errors
+
+      def initialize(errors, status:)
+        @errors = errors.freeze
+
+        super(
+          "Vantage API returned #{errors.size} error(s)",
+          code: 'multiple_errors',
+          status: status
+        )
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    # Base class for mapping API responses to model attributes.
+    class Base
+      attr_reader :warnings
+
+      class << self
+        def from_response(response)
+          new(
+            response.fetch('data'),
+            warnings: response.fetch('warnings', [])
+          )
+        end
+
+        def attributes(fields)
+          const_set(:ATTRIBUTES, fields.freeze)
+          attr_reader(*fields)
+        end
+      end
+
+      def initialize(json, warnings: [])
+        @warnings = warnings
+
+        self.class::ATTRIBUTES.each do |name|
+          json_key = name.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+
+          instance_variable_set(:"@#{name}", json[json_key])
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/content_unit.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a content unit in a Vantage project.
+      class ContentUnit < Base
+        attributes %i[
+          id
+          project_id
+          type
+          key
+          position
+          source_segments_count
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/export.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a Vantage export operation and its status.
+      class Export < Base
+        attributes %i[
+          export_id
+          status
+          created_at
+          total_items_count
+          processed_items_count
+          fail_reason
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/export_download_url.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a download URL for a completed Vantage export.
+      class ExportDownloadUrl < Base
+        attributes %i[download_url]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/import.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a Vantage project import.
+      class Import < Base
+        attributes %i[import_id]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/project.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a Vantage project.
+      class Project < Base
+        attributes %i[
+          project_id
+          team_id
+          name
+          description
+          base_language
+          target_languages
+          translation_settings
+          content_source_type
+          content_source_name
+          project_type
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/project_item.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents an item belonging to a Vantage project.
+      class ProjectItem < Base
+        attributes %i[
+          id
+          project_id
+          name
+          created_at
+          updated_at
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/project_language.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a language configured for a Vantage project.
+      class ProjectLanguage < Base
+        attributes %i[
+          language_id
+          locale
+          language_name
+          is_rtl
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/segment.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a segment belonging to a Vantage content unit.
+      class Segment < Base
+        attributes %i[
+          id
+          number
+          value
+          status
+          last_change_source
+          content_language_id
+          content_unit_id
+          project_id
+          metadata
+          created_at
+          updated_at
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/task.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a task in a Vantage project.
+      class Task < Base
+        attributes %i[
+          id
+          public_id
+          title
+          type
+          status
+          description
+          task_assignments
+          due_date
+          created_at
+          requested_by
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/translation_status.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents the translation status of a Vantage import.
+      class TranslationStatus < Base
+        attributes %i[
+          project_id
+          import_id
+          status
+          languages
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/upload.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a file upload in a Vantage project.
+      class Upload < Base
+        attributes %i[
+          upload_id
+          batch_id
+          file_name
+          size
+          created_at
+          status
+          word_count
+          locale
+          item_id
+          error
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/models/vantage/upload_batch.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Models
+    module Vantage
+      # Represents a batch of staged Vantage uploads.
+      class UploadBatch < Base
+        attributes %i[
+          batch_id
+          uploads
+        ]
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/request.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  # Performs HTTP requests.
+  module Request
+    private
+
+    def get(uri, params: {})
+      Response.new(connection.get(uri, params: params)).body
+    end
+
+    def post(uri, body:)
+      response = connection.post(
+        uri,
+        body: Oj.dump(body, mode: :strict),
+        headers: { 'Content-Type' => 'application/json' }
+      )
+
+      Response.new(response).body
+    end
+
+    def patch(uri, body:)
+      response = connection.patch(
+        uri,
+        body: Oj.dump(body, mode: :strict),
+        headers: { 'Content-Type' => 'application/json' }
+      )
+
+      Response.new(response).body
+    end
+  end
+end

data/lib/lokalise_api_next/response.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  # Parses HTTP responses and handles API errors.
+  class Response
+    def initialize(http_response)
+      @http_response = http_response
+    end
+
+    def body
+      @http_response.raise_for_status if @http_response.is_a?(HTTPX::ErrorResponse)
+
+      parsed_body = parse_body
+      status = @http_response.status
+
+      raise Error.from_response(parsed_body, status: status) unless status.between?(200, 299)
+
+      parsed_body
+    end
+
+    private
+
+    def parse_body
+      raw = @http_response.body.to_s
+      return nil if raw.empty?
+
+      Oj.load(raw, mode: :strict)
+    rescue Oj::ParseError
+      raise if @http_response.status.between?(200, 299)
+
+      raw
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/content_units.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides project API operations.
+      module ContentUnits
+        ENDPOINT = Endpoints::Vantage::ContentUnits
+        COLLECTION = Collections::Vantage::ContentUnits
+
+        def content_units(project_id, item_id, params = {})
+          uri = ENDPOINT.list(project_id: project_id, item_id: item_id)
+
+          COLLECTION.from_response(get(uri, params: params))
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/exports.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides project export API operations.
+      module Exports
+        ENDPOINT = Endpoints::Vantage::Exports
+        COLLECTION = Collections::Vantage::Exports
+        MODEL = COLLECTION::MODEL
+        DOWNLOAD_URL_MODEL = Models::Vantage::ExportDownloadUrl
+
+        def exports(project_id, params = {})
+          uri = ENDPOINT.list(project_id: project_id)
+
+          COLLECTION.from_response(get(uri, params: params))
+        end
+
+        def export(project_id, export_id)
+          uri = ENDPOINT.fetch(project_id: project_id, export_id: export_id)
+
+          MODEL.from_response(get(uri))
+        end
+
+        def create_export(project_id, params = {})
+          uri = ENDPOINT.create(project_id: project_id)
+
+          MODEL.from_response(post(uri, body: params))
+        end
+
+        def export_download_url(project_id, export_id)
+          uri = ENDPOINT.download_url(project_id: project_id, export_id: export_id)
+
+          DOWNLOAD_URL_MODEL.from_response(get(uri))
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/imports.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides project import API operations.
+      module Imports
+        ENDPOINT = Endpoints::Vantage::Imports
+        MODEL = Models::Vantage::Import
+
+        def create_import(project_id, params)
+          uri = ENDPOINT.create(project_id: project_id)
+
+          MODEL.from_response(post(uri, body: params))
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/project_items.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides project API operations.
+      module ProjectItems
+        ENDPOINT = Endpoints::Vantage::ProjectItems
+        COLLECTION = Collections::Vantage::ProjectItems
+
+        def project_items(project_id, params = {})
+          uri = ENDPOINT.list(project_id: project_id)
+
+          COLLECTION.from_response(get(uri, params: params))
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/project_languages.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides project languages API operations.
+      module ProjectLanguages
+        ENDPOINT = Endpoints::Vantage::ProjectLanguages
+        COLLECTION = Collections::Vantage::ProjectLanguages
+
+        def project_languages(project_id)
+          uri = ENDPOINT.list(project_id: project_id)
+
+          COLLECTION.from_response(get(uri))
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/projects.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides project API operations.
+      module Projects
+        ENDPOINT = Endpoints::Vantage::Projects
+        COLLECTION = Collections::Vantage::Projects
+        MODEL = COLLECTION::MODEL
+
+        def projects(team_id, params = {})
+          uri = ENDPOINT.list(team_id: team_id)
+
+          COLLECTION.from_response(get(uri, params: params))
+        end
+
+        def project(project_id)
+          uri = ENDPOINT.fetch(project_id: project_id)
+
+          MODEL.from_response(get(uri))
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/segments.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides project API operations.
+      module Segments
+        ENDPOINT = Endpoints::Vantage::Segments
+        COLLECTION = Collections::Vantage::Segments
+        MODEL = COLLECTION::MODEL
+
+        def segments(project_id, content_unit_id, params = {})
+          uri = ENDPOINT.list(project_id: project_id, content_unit_id: content_unit_id)
+
+          COLLECTION.from_response(get(uri, params: params))
+        end
+
+        def update_segment(project_id, segment_id, params)
+          uri = ENDPOINT.update(project_id: project_id, segment_id: segment_id)
+
+          MODEL.from_response(patch(uri, body: params))
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/tasks.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides task API operations.
+      module Tasks
+        ENDPOINT = Endpoints::Vantage::Tasks
+        COLLECTION = Collections::Vantage::Tasks
+
+        def tasks(team_id, project_id, params = {})
+          uri = ENDPOINT.list(team_id: team_id, project_id: project_id)
+
+          COLLECTION.from_response(get(uri, params: params))
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/rest/vantage/translation_statuses.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Rest
+    module Vantage
+      # Provides translation status API operations.
+      module TranslationStatuses
+        ENDPOINT = Endpoints::Vantage::TranslationStatuses
+        MODEL = Models::Vantage::TranslationStatus
+
+        def translation_status(project_id, import_id)
+          uri = ENDPOINT.fetch(project_id: project_id, import_id: import_id)
+
+          MODEL.from_response(get(uri))
+        end
+      end
+    end
+  end
+end