Version 9.1.0

lokalise · May 15, 2024 · b7dd055 · b7dd055
1 parent 2d78458
commit b7dd055
Show file tree

Hide file tree

Showing 18 changed files with 536 additions and 40 deletions.
diff --git a/.gitignore b/.gitignore
@@ -10,4 +10,5 @@ measurement/*
 pkg/*
 .DS_Store
 .env
-demo.rb
+demo.rb
+.ruby-lsp
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -20,6 +20,10 @@ Layout/LineLength:
   Exclude:
     - ./*.gemspec
 
+Metrics/ClassLength:
+  CountComments: false
+  Max: 120
+
 Metrics/MethodLength:
   CountComments: false
   Max: 10

diff --git a/docs/Gemfile b/docs/Gemfile
@@ -27,7 +27,7 @@ end
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
 # and associated library.
 install_if -> { RUBY_PLATFORM =~ /mingw|mswin|java/ } do
-  gem 'tzinfo', '~> 1.2'
+  gem 'tzinfo', '~> 2.0'
   gem 'tzinfo-data'
 end
 

diff --git a/docs/additional_info/changelog.md b/docs/additional_info/changelog.md
@@ -1,5 +1,25 @@
 # Changelog
 
+## 9.1.0 (15-May-2024)
+
+* Add support for [cursor pagination](https://lokalise.github.io/ruby-lokalise-api/api/getting-started#cursor-pagination) for List keys and List translation endpoints:
+
+```ruby
+cursor_pagination_params = {
+  pagination: 'cursor',
+  cursor: 'eyIxIjozMTk3ODIzNzJ9', # The starting cursor. Optional, string
+  limit: 2 # The number of items to fetch. Optional, default is 100
+}
+
+keys = @client.keys '123abcdef.01', cursor_pagination_params
+
+keys.next_cursor? # => true
+keys.next_cursor # => 'eyIxIjozMTk3ODIzNzV9'
+
+# Request keys from the next cursor (returns `nil` if the next cursor is not available):
+keys_next_cursor = keys.load_next_cursor
+```
+
 ## 9.0.1 (13-Mar-2024)
 
 * Handle cases when server responds with non-JSON

diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md
@@ -138,6 +138,26 @@ first_translation = prev_page_translations.first # get first translation from th
 first_translation.translation # => 'Translation text'
 ```
 
+### Cursor pagination
+
+The [List Keys](https://developers.lokalise.com/reference/list-all-keys) and [List Translations](https://developers.lokalise.com/reference/list-all-translations) endpoints support cursor pagination, which is recommended for its faster performance compared to traditional "offset" pagination. By default, "offset" pagination is used, so you must explicitly set `pagination` to `"cursor"` to use cursor pagination.
+
+```ruby
+cursor_pagination_params = {
+  pagination: 'cursor',
+  cursor: 'eyIxIjozMTk3ODIzNzJ9', # The starting cursor. Optional, string
+  limit: 2 # The number of items to fetch. Optional, default is 100
+}
+
+keys = @client.keys '123abcdef.01', cursor_pagination_params
+
+keys.next_cursor? # => true
+keys.next_cursor # => 'eyIxIjozMTk3ODIzNzV9'
+
+# Request keys from the next cursor (returns `nil` if the next cursor is not available):
+keys_next_cursor = keys.load_next_cursor
+```
+
 ## Branching
 
 If you are using [project branching feature](https://docs.lokalise.com/en/articles/3391861-project-branching), simply add branch name separated by semicolon to your project ID in any endpoint to access the branch. For example, in order to access `new-feature` branch for the project with an id `123abcdef.01`:

diff --git a/docs/api/keys.md b/docs/api/keys.md
@@ -8,11 +8,13 @@
 @client.keys(project_id, params = {})   # Input:
                                         ## project_id (string, required)
                                         ## params (hash)
-                                        ### :page and :limit
+                                        ### pagination and cursor-related params
                                         # Output:
                                         ## Collection of keys available in the given project
 ```
 
+**This endpoint also supports cursor pagination which is now a recommended approach, especially for fetching large amounts of data. Please [learn more in the Pagination docs](https://lokalise.github.io/ruby-lokalise-api/api/getting-started#cursor-pagination).**
+
 For example:
 
 ```ruby

diff --git a/docs/api/translations.md b/docs/api/translations.md
@@ -9,11 +9,12 @@
                                                 ## project_id (string, required)
                                                 ## params (hash)
                                                 ### Find full list in the docs
-                                                ### :page and :limit
                                                 # Output:
                                                 ## Collection of translations for the project
 ```
 
+**This endpoint also supports cursor pagination which is now a recommended approach, especially for fetching large amounts of data. Please [learn more in the Pagination docs](https://lokalise.github.io/ruby-lokalise-api/api/getting-started#cursor-pagination).**
+
 For example:
 
 ```ruby

diff --git a/lib/ruby_lokalise_api/collections/base.rb b/lib/ruby_lokalise_api/collections/base.rb
@@ -18,7 +18,7 @@ class Base
       def_delegators :collection, :[], :last, :each
 
       attr_reader :total_pages, :total_results, :results_per_page, :current_page,
-                  :collection
+                  :collection, :next_cursor
 
       def initialize(response)
         @self_endpoint = response.endpoint
@@ -32,9 +32,25 @@ def initialize(response)
       def next_page
         return nil if last_page?
 
+        override_params = { page: current_page + 1 }
+
         self.class.new(
           reinit_endpoint(
-            override_req_params: { page: current_page + 1 }
+            override_req_params: override_params
+          ).do_get
+        )
+      end
+
+      # Tries to fetch the next cursor for paginated collection
+      # Returns a new collection or nil if the next cursor is not available
+      def load_next_cursor
+        return nil unless next_cursor?
+
+        override_params = { cursor: next_cursor }
+
+        self.class.new(
+          reinit_endpoint(
+            override_req_params: override_params
           ).do_get
         )
       end
@@ -75,6 +91,12 @@ def first_page?
         !prev_page?
       end
 
+      # Checks whether the next cursor is available
+      # @return [Boolean]
+      def next_cursor?
+        !next_cursor.nil? && next_cursor != ''
+      end
+
       private
 
       # This method is utilized to recreate an endpoint for the current collection
@@ -89,14 +111,17 @@ def populate_common_attrs_from(response)
           instance_variable_set :"@#{attrib}", response.content[attrib]
         end
 
-        headers = response.headers
+        extract_common_from_headers(response.headers)
+      end
 
+      def extract_common_from_headers(headers)
         return unless headers.any?
 
-        @total_results = headers[:'x-pagination-total-count']
-        @total_pages = headers[:'x-pagination-page-count']
-        @results_per_page = headers[:'x-pagination-limit']
-        @current_page = headers[:'x-pagination-page']
+        @total_results = headers[:'x-pagination-total-count'].to_i
+        @total_pages = headers[:'x-pagination-page-count'].to_i
+        @results_per_page = headers[:'x-pagination-limit'].to_i
+        @current_page = headers[:'x-pagination-page'].to_i
+        @next_cursor = headers[:'x-pagination-next-cursor']
       end
 
       def produce_collection_from(response)

diff --git a/lib/ruby_lokalise_api/response.rb b/lib/ruby_lokalise_api/response.rb
@@ -5,7 +5,7 @@ module RubyLokaliseApi
   class Response
     # Lokalise returns pagination info in special headers
     PAGINATION_HEADERS = %w[x-pagination-total-count x-pagination-page-count x-pagination-limit
-                            x-pagination-page].freeze
+                            x-pagination-page x-pagination-next-cursor].freeze
 
     attr_reader :content, :endpoint, :headers
 
@@ -43,8 +43,7 @@ def extract_headers_from(raw_headers)
       raw_headers.
         to_h.
         keep_if { |header, _value| pagination_headers.include?(header) }.
-        transform_keys(&:to_sym).
-        transform_values(&:to_i)
+        transform_keys(&:to_sym)
     end
   end
 end
diff --git a/lib/ruby_lokalise_api/version.rb b/lib/ruby_lokalise_api/version.rb
@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyLokaliseApi
-  VERSION = '9.0.1'
+  VERSION = '9.1.0'
 end
diff --git a/spec/fixtures/keys/keys_cursor_1.json b/spec/fixtures/keys/keys_cursor_1.json
@@ -0,0 +1,75 @@
+{
+  "project_id": "88628569645b945648b474.25982965",
+  "branch": "master",
+  "keys": [
+    {
+      "key_id": 319782369,
+      "created_at": "2023-04-06 17:49:36 (Etc/UTC)",
+      "created_at_timestamp": 1680803376,
+      "key_name": {
+        "ios": "hi",
+        "android": "hi",
+        "web": "hi",
+        "other": "hi"
+      },
+      "filenames": {
+        "ios": "",
+        "android": "",
+        "web": "",
+        "other": ""
+      },
+      "description": "Welcoming message",
+      "platforms": [
+        "ios",
+        "web"
+      ],
+      "tags": [],
+      "is_plural": false,
+      "plural_name": "",
+      "is_hidden": false,
+      "is_archived": false,
+      "context": "",
+      "base_words": 3,
+      "char_limit": 0,
+      "custom_attributes": "",
+      "modified_at": "2023-05-09 11:59:42 (Etc/UTC)",
+      "modified_at_timestamp": 1683633582,
+      "translations_modified_at": "2023-05-18 12:55:25 (Etc/UTC)",
+      "translations_modified_at_timestamp": 1684414525
+    },
+    {
+      "key_id": 319782372,
+      "created_at": "2023-04-18 16:40:16 (Etc/UTC)",
+      "created_at_timestamp": 1681836016,
+      "key_name": {
+        "ios": "editor",
+        "android": "editor",
+        "web": "editor",
+        "other": "editor"
+      },
+      "filenames": {
+        "ios": "",
+        "android": "",
+        "web": "",
+        "other": ""
+      },
+      "description": "",
+      "platforms": [
+        "android"
+      ],
+      "tags": [],
+      "is_plural": false,
+      "plural_name": "",
+      "is_hidden": false,
+      "is_archived": false,
+      "context": "",
+      "base_words": 1,
+      "char_limit": 0,
+      "custom_attributes": "",
+      "modified_at": "2023-04-24 11:28:17 (Etc/UTC)",
+      "modified_at_timestamp": 1682335697,
+      "translations_modified_at": "2023-05-18 12:55:19 (Etc/UTC)",
+      "translations_modified_at_timestamp": 1684414519
+    }
+  ]
+}
diff --git a/spec/fixtures/keys/keys_cursor_2.json b/spec/fixtures/keys/keys_cursor_2.json
@@ -0,0 +1,75 @@
+{
+  "project_id": "88628569645b945648b474.25982965",
+  "branch": "master",
+  "keys": [
+    {
+      "key_id": 319782375,
+      "created_at": "2023-04-24 11:24:38 (Etc/UTC)",
+      "created_at_timestamp": 1682335478,
+      "key_name": {
+        "ios": "how_are_you",
+        "android": "how_are_you",
+        "web": "how_are_you",
+        "other": "how_are_you"
+      },
+      "filenames": {
+        "ios": "",
+        "android": "",
+        "web": "main-%LANG_ISO%.json",
+        "other": ""
+      },
+      "description": "",
+      "platforms": [
+        "web"
+      ],
+      "tags": [],
+      "is_plural": false,
+      "plural_name": "",
+      "is_hidden": false,
+      "is_archived": false,
+      "context": "",
+      "base_words": 4,
+      "char_limit": 0,
+      "custom_attributes": "",
+      "modified_at": "2023-04-24 11:24:38 (Etc/UTC)",
+      "modified_at_timestamp": 1682335478,
+      "translations_modified_at": "2023-05-18 12:55:17 (Etc/UTC)",
+      "translations_modified_at_timestamp": 1684414517
+    },
+    {
+      "key_id": 319782376,
+      "created_at": "2023-04-24 11:24:38 (Etc/UTC)",
+      "created_at_timestamp": 1682335478,
+      "key_name": {
+        "ios": "login",
+        "android": "login",
+        "web": "login",
+        "other": "login"
+      },
+      "filenames": {
+        "ios": "",
+        "android": "",
+        "web": "main-%LANG_ISO%.json",
+        "other": ""
+      },
+      "description": "",
+      "platforms": [
+        "ios",
+        "web"
+      ],
+      "tags": [],
+      "is_plural": false,
+      "plural_name": "",
+      "is_hidden": false,
+      "is_archived": false,
+      "context": "",
+      "base_words": 2,
+      "char_limit": 0,
+      "custom_attributes": "",
+      "modified_at": "2023-05-10 13:10:57 (Etc/UTC)",
+      "modified_at_timestamp": 1683724257,
+      "translations_modified_at": "2023-05-18 12:55:16 (Etc/UTC)",
+      "translations_modified_at_timestamp": 1684414516
+    }
+  ]
+}