lokalise-api-next 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88d19476ec7711330333098331e5bbd057920c239025dc9b45b923afb52c8cef
+  data.tar.gz: c84aecdefed351e4765c94fede0643d3d4544b00233d31a29e4546c5c26e2b1c
+SHA512:
+  metadata.gz: 271601532dc476a927aa53a50b57f7d41680910fb7d5c1fa999218ecc46413560357348f63d66193a024d574eb82d333477d592d1dff7cca35a18af58e9f211e
+  data.tar.gz: 3ca355127c47a4cb54e83781fc069b6996ce5febb5d05cf3896bc607140b79042b90fc63b81c16682a94f5065af5cb578c47ac7f6b329f11fa69828817fc6e37

data/LICENSE

@@ -0,0 +1,13 @@
+BSD 3 Clause
+
+Copyright 2026 Lokalise Group, Elijah S. Krukowski
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,92 @@
+# Ruby SDK for Lokalise API
+
+![Gem](https://img.shields.io/gem/v/lokalise-api-next)
+![CI](https://github.com/lokalise/ruby-lokalise-api-next/actions/workflows/ci.yml/badge.svg)
+[![Code Coverage](https://qlty.sh/gh/lokalise/projects/ruby-lokalise-api-next/coverage.svg)](https://qlty.sh/gh/lokalise/projects/ruby-lokalise-api-next)
+[![Maintainability](https://qlty.sh/gh/lokalise/projects/ruby-lokalise-api-next/maintainability.svg)](https://qlty.sh/gh/lokalise/projects/ruby-lokalise-api-next)
+
+Opinionated Ruby SDK for the [Lokalise Vantage API](https://developers.lokalise.com/reference/lokalise-vantage-api-introduction).
+
+The `lokalise-api-next` gem provides a Ruby interface for working with Lokalise Vantage resources. It handles authentication, HTTP requests, response parsing, and API errors, and returns Ruby models and collections.
+
+## Requirements
+
+- Ruby 3.4 or newer
+- A Lokalise API token with access to Vantage
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'lokalise-api-next'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+Create a client using your Lokalise API token:
+
+```ruby
+require 'lokalise_api_next'
+
+client_vantage = LokaliseApiNext.client_vantage(
+  ENV.fetch('LOKALISE_VANTAGE_TOKEN')
+)
+```
+
+For example, retrieve a project:
+
+```ruby
+project = client_vantage.project('project-id')
+
+puts project.name
+puts project.description
+```
+
+Or list projects belonging to a team:
+
+```ruby
+projects = client_vantage.projects('team-id', limit: 20)
+
+projects.each do |project|
+  puts "#{project.project_id}: #{project.name}"
+end
+```
+
+The SDK also supports configurable timeouts, automatic retries, proxies, and persistent HTTP connections.
+
+## Documentation
+
+See the **[GitHub Wiki](../../wiki)** for usage examples, client configuration, pagination, and available API operations.
+
+## Development and testing
+
+Clone the repository and install dependencies:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run RuboCop:
+
+```bash
+bundle exec rubocop
+```
+
+The tests use RSpec and WebMock to simulate API responses, so a real API token is not required.
+
+## License
+
+(c) 2026 Lokalise group, Elijah S. Krukowski, BSD 3 Clause license.

data/lib/lokalise_api_next/base_client.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  # Base client with shared HTTP configuration.
+  class BaseClient
+    attr_reader :token, :token_header, :api_host, :base_path,
+                :timeout, :open_timeout, :persistent, :proxy
+
+    def initialize(token, params = {})
+      @token = token.dup.freeze
+
+      configure_api(params)
+      configure_transport(params)
+      initialize_connection
+    end
+
+    private
+
+    def configure_api(params)
+      @token_header = params.fetch(:token_header, 'x-api-token').dup.freeze
+      @api_host = params.fetch(:api_host, 'https://api.lokalise.com').dup.freeze
+      @base_path = params.fetch(:base_path, self.class::BASE_PATH).dup.freeze
+    end
+
+    def configure_transport(params)
+      @timeout = params[:timeout]
+      @open_timeout = params[:open_timeout]
+      @persistent = params.fetch(:persistent, false)
+      @proxy = params[:proxy]&.dup&.freeze
+    end
+  end
+end

data/lib/lokalise_api_next/client_vantage.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  # Client for interacting with the Vantage API.
+  class ClientVantage < BaseClient
+    include LokaliseApiNext::RestVantage
+
+    BASE_PATH = '/vantage/v1'
+  end
+end

data/lib/lokalise_api_next/collections/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module LokaliseApiNext
+  module Collections
+    # Base class for API resource collections.
+    class Base
+      include Enumerable
+      extend Forwardable
+
+      attr_reader :items
+
+      def_delegators :items, :[], :last, :each, :size, :empty?
+
+      def self.from_response(response)
+        new(response.fetch('data'), response.fetch('meta', nil))
+      end
+
+      def initialize(json_items, _meta = nil)
+        model_klass = self.class::MODEL
+        @items = json_items.map { |json_item| model_klass.new(json_item) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Collections
+    module Vantage
+      # Paginated collection of Vantage content units.
+      class ContentUnits < Base
+        include Concerns::Paginated
+
+        MODEL = Models::Vantage::ContentUnit
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Collections
+    module Vantage
+      # Paginated collection of Vantage exports.
+      class Exports < Base
+        include Concerns::Paginated
+
+        MODEL = Models::Vantage::Export
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Collections
+    module Vantage
+      # Paginated collection of Vantage project items.
+      class ProjectItems < Base
+        include Concerns::Paginated
+
+        MODEL = Models::Vantage::ProjectItem
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Collections
+    module Vantage
+      # Collection of Vantage project languages.
+      class ProjectLanguages < Base
+        MODEL = Models::Vantage::ProjectLanguage
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Collections
+    module Vantage
+      # Represents a collection of Vantage projects.
+      class Projects < Base
+        include LokaliseApiNext::Concerns::Paginated
+
+        MODEL = Models::Vantage::Project
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Collections
+    module Vantage
+      # Paginated collection of Vantage segments.
+      class Segments < Base
+        include Concerns::Paginated
+
+        MODEL = Models::Vantage::Segment
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Collections
+    module Vantage
+      # Paginated collection of Vantage tasks.
+      class Tasks < Base
+        include Concerns::Paginated
+
+        MODEL = Models::Vantage::Task
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/collections/vantage/uploads.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Collections
+    module Vantage
+      # Paginated collection of Vantage uploads.
+      class Uploads < Base
+        include Concerns::Paginated
+
+        MODEL = Models::Vantage::Upload
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/concerns/paginated.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Concerns
+    # Adds pagination metadata to API collections.
+    module Paginated
+      attr_reader :page_count, :cursor
+
+      def initialize(json_items, meta = nil)
+        super
+
+        raise ArgumentError, 'Pagination metadata is missing' unless meta.is_a?(Hash)
+
+        @page_count = meta.fetch('count')
+        @cursor = meta['cursor']
+        @has_more = meta.fetch('hasMore')
+      end
+
+      def more?
+        @has_more
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/connection.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'httpx'
+
+module LokaliseApiNext
+  # Configures HTTP connections to the Vantage API.
+  module Connection
+    def close
+      connection.close
+    end
+
+    private
+
+    attr_reader :connection
+
+    def initialize_connection
+      options = {
+        origin: api_host,
+        base_path: base_path,
+        headers: connection_headers
+      }
+
+      timeouts = connection_timeouts
+      options[:timeout] = timeouts unless timeouts.empty?
+
+      session = connection_plugins.reduce(HTTPX) do |httpx, plugin|
+        httpx.plugin(plugin)
+      end
+
+      session = session.with(**options)
+      session = session.with_proxy(uri: proxy) if proxy
+
+      @connection = session
+    end
+
+    def connection_plugins
+      plugins = [:retries]
+      plugins << :persistent if persistent
+      plugins << :proxy if proxy
+
+      plugins
+    end
+
+    def connection_headers
+      {
+        'Accept' => 'application/json',
+        'User-Agent' => "ruby-lokalise-api-next/#{LokaliseApiNext::VERSION}",
+        token_header => token
+      }
+    end
+
+    def connection_timeouts
+      {
+        connect_timeout: open_timeout,
+        request_timeout: timeout
+      }.compact
+    end
+  end
+end

data/lib/lokalise_api_next/endpoints/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'addressable/template'
+
+module LokaliseApiNext
+  module Endpoints
+    # Base class for building API endpoint paths.
+    class Base
+      class << self
+        private
+
+        def build_path(pattern, **params)
+          template = Addressable::Template.new(pattern)
+          values = params.transform_keys(&:to_s)
+
+          missing = template.variables.select do |name|
+            values[name].to_s.strip.empty?
+          end
+
+          raise ArgumentError, "Missing required path parameters: #{missing.join(', ')}" unless missing.empty?
+
+          template.expand(values).to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for project languages operations.
+      class ContentUnits < Base
+        COLLECTION_PATH = '/projects/{project_id}/items/{item_id}/content-units'
+
+        class << self
+          def list(project_id:, item_id:)
+            build_path(COLLECTION_PATH, project_id: project_id, item_id: item_id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for export operations.
+      class Exports < Base
+        COLLECTION_PATH = '/projects/{project_id}/exports'
+        MEMBER_PATH = '/projects/{project_id}/exports/{export_id}'
+        DOWNLOAD_URL_PATH = '/projects/{project_id}/exports/{export_id}/download-url'
+
+        class << self
+          def list(project_id:)
+            build_path(COLLECTION_PATH, project_id: project_id)
+          end
+
+          def fetch(project_id:, export_id:)
+            build_path(
+              MEMBER_PATH,
+              project_id: project_id,
+              export_id: export_id
+            )
+          end
+
+          def create(project_id:)
+            build_path(COLLECTION_PATH, project_id: project_id)
+          end
+
+          def download_url(project_id:, export_id:)
+            build_path(
+              DOWNLOAD_URL_PATH,
+              project_id: project_id,
+              export_id: export_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for project import operations.
+      class Imports < Base
+        COLLECTION_PATH = '/projects/{project_id}/imports'
+
+        class << self
+          def create(project_id:)
+            build_path(COLLECTION_PATH, project_id: project_id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for project languages operations.
+      class ProjectItems < Base
+        COLLECTION_PATH = '/projects/{project_id}/items'
+
+        class << self
+          def list(project_id:)
+            build_path(COLLECTION_PATH, project_id: project_id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for project languages operations.
+      class ProjectLanguages < Base
+        COLLECTION_PATH = '/projects/{project_id}/languages'
+
+        class << self
+          def list(project_id:)
+            build_path(COLLECTION_PATH, project_id: project_id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for project operations.
+      class Projects < Base
+        COLLECTION_PATH = '/teams/{team_id}/projects'
+        MEMBER_PATH = '/projects/{project_id}'
+
+        class << self
+          def list(team_id:)
+            build_path(COLLECTION_PATH, team_id: team_id)
+          end
+
+          def fetch(project_id:)
+            build_path(MEMBER_PATH, project_id: project_id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for segment operations.
+      class Segments < Base
+        COLLECTION_PATH = '/projects/{project_id}/content-units/{content_unit_id}/segments'
+        MEMBER_PATH = '/projects/{project_id}/segments/{segment_id}'
+
+        class << self
+          def list(project_id:, content_unit_id:)
+            build_path(
+              COLLECTION_PATH,
+              project_id: project_id,
+              content_unit_id: content_unit_id
+            )
+          end
+
+          def update(project_id:, segment_id:)
+            build_path(
+              MEMBER_PATH,
+              project_id: project_id,
+              segment_id: segment_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for task operations.
+      class Tasks < Base
+        COLLECTION_PATH = '/teams/{team_id}/projects/{project_id}/tasks'
+
+        class << self
+          def list(team_id:, project_id:)
+            build_path(
+              COLLECTION_PATH,
+              team_id: team_id,
+              project_id: project_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for translation status operations.
+      class TranslationStatuses < Base
+        MEMBER_PATH = '/projects/{project_id}/translation-statuses/{import_id}'
+
+        class << self
+          def fetch(project_id:, import_id:)
+            build_path(
+              MEMBER_PATH,
+              project_id: project_id,
+              import_id: import_id
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lokalise_api_next/endpoints/vantage/uploads.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module LokaliseApiNext
+  module Endpoints
+    module Vantage
+      # Builds paths for project upload operations.
+      class Uploads < Base
+        COLLECTION_PATH = '/projects/{project_id}/uploads'
+        COMPLETE_PATH = '/projects/{project_id}/uploads/actions/complete'
+
+        class << self
+          def list(project_id:)
+            build_path(COLLECTION_PATH, project_id: project_id)
+          end
+
+          def stage(project_id:)
+            build_path(COLLECTION_PATH, project_id: project_id)
+          end
+
+          def complete(project_id:)
+            build_path(COMPLETE_PATH, project_id: project_id)
+          end
+        end
+      end
+    end
+  end
+end