lara-sdk 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33000e4a2972ae2f98c8e9b2e307122e4d729d1e50e5d78325fde5d5b7d470b4
-  data.tar.gz: 11a9586abaf2b895fe0d7f50f04470c462b80f83c44ffb33a9a4c869c30bb4bb
+  metadata.gz: d794b96f2ef4b205bf0b46706b9346af3659ee923870116341e87a3688220ee7
+  data.tar.gz: e460f4a73a7a25c94c2d57a99a8d6998c06625b9e27723594b9789b86d601061
 SHA512:
-  metadata.gz: bab5b019aaab9736023be72456df455558afcc17dce5060792c6b4d8fe73a34c81065a86320614437a234792b6ca204ddddd3884049e0927e51d16d894eb3441
-  data.tar.gz: 0a5bd84f86a55cce9ab60930178411857cc84df2534d6b91deb5300ab0e9ff12bdc126a7e374458d83a64c7cd105dda4ba6852b4eac313b40852e528941d7158
+  metadata.gz: 722e1746da8b4735ee5b072b8168cef5996a1aeb7cc059b3ca651da46a0144808c93c7cde7583d300ea0adf02a1b812f24803072e399e35642560b82b10b272f
+  data.tar.gz: c3dec84e4e56eec0bbfa2f46ec05a688bbecf2ee76f17bd80c6f78273f33458595b33c42baa39d2cb2d76057c04c9ac16f8c03937847ab1e994aacd976bfdf94

data/lib/lara/client.rb

@@ -56,6 +56,22 @@ module Lara
       request(:get, path, body: nil, headers: headers, params: params)
     end
 
+    # Retrieves a collection using pagination metadata from the response headers.
+    # @yield [Hash] Converts each resource to its SDK model
+    # @return [Lara::Models::CollectionResult]
+    def get_collection(path, params: nil)
+      items, headers = request(:get, path, params: params, with_metadata: true)
+      total = integer_header(headers, "x-total-count", minimum: 0)
+      raise LaraError, "Missing or invalid X-Total-Count response header" if total.nil?
+
+      Lara::Models::CollectionResult.new(
+        items: block_given? ? items.map { |item| yield item } : items,
+        total: total,
+        page: integer_header(headers, "x-page", minimum: 1),
+        size: integer_header(headers, "x-page-size", minimum: 1)
+      )
+    end
+
     # Sends a POST request to the Lara API.
     # @param path [String] The path to send the request to.
     # @param body [Hash,nil] The parameters to send with the request.
@@ -90,8 +106,19 @@ module Lara
 
     private
 
+    def integer_header(headers, name, minimum:)
+      value = headers.find { |key, _| key.downcase == name }&.last
+      return nil unless value.is_a?(String)
+
+      value = value.gsub(/\A[ \t]+|[ \t]+\z/, "")
+      return nil unless value.match?(/\A[0-9]+\z/)
+
+      number = value.to_i
+      number if number >= minimum
+    end
+
     def request(method, path, body: nil, files: nil, headers: nil, params: nil,
-                raw_response: false, &callback)
+                raw_response: false, with_metadata: false, &callback)
       file_positions = (files || {}).each_with_object({}) do |(name, file), positions|
         next unless file.respond_to?(:pos) && file.respond_to?(:seek)
 
@@ -104,7 +131,8 @@ module Lara
       ensure_valid_token
 
       make_request(method, path, body: body, files: files, headers: headers, params: params,
-                                 raw_response: raw_response, &callback)
+                                 raw_response: raw_response, with_metadata: with_metadata,
+                                 &callback)
     rescue LaraApiError => e
       raise unless e.status_code == 401
 
@@ -112,7 +140,8 @@ module Lara
       # Multipart encoding consumed the files; replay their original bytes.
       file_positions.each { |name, position| files[name].seek(position) }
       make_request(method, path, body: body, files: files, headers: headers, params: params,
-                                 raw_response: raw_response, &callback)
+                                 raw_response: raw_response, with_metadata: with_metadata,
+                                 &callback)
     end
 
     def ensure_valid_token
@@ -204,7 +233,7 @@ module Lara
     end
 
     def make_request(method, path, body: nil, files: nil, headers: nil, params: nil,
-                     raw_response: false, &callback)
+                     raw_response: false, with_metadata: false, &callback)
       path = "/#{path}" unless path.start_with?("/")
       request_headers = build_request_headers(body, files, headers)
 
@@ -226,6 +255,8 @@ module Lara
 
       raise LaraApiError.from_response(response) unless response.success?
 
+      return [parse_json(response.body), response.headers] if with_metadata
+
       return response.body if raw_response
 
       content_type = response.headers["content-type"] || response.headers["Content-Type"]

data/lib/lara/glossaries.rb

@@ -25,13 +25,27 @@ module Lara
       @polling_interval = 2
     end
 
+    # @deprecated Use #list_paginated instead.
     # @return [Array<Lara::Models::Glossary>]
     def list
+      warn "[DEPRECATION] list is deprecated; use list_paginated instead.", uplevel: 1
       (@client.get("/v2/glossaries") || []).map do |_h|
         Lara::Models::Glossary.new(**_h.transform_keys(&:to_sym))
       end
     end
 
+    # Lists resources with optional name filtering and pagination.
+    # Without options, returns the complete collection without pagination.
+    # Any supplied option enables pagination; page and size default to 1 and 20.
+    # @param options [Lara::Models::ResourceQueryOptions,nil] Name filter and pagination
+    # @return [Lara::Models::CollectionResult] Collection containing Glossary objects
+    def list_paginated(options = nil)
+      params = options&.to_params || {}
+      @client.get_collection("/v2/glossaries", params: params) do |item|
+        Lara::Models::Glossary.new(**item.transform_keys(&:to_sym))
+      end
+    end
+
     # @return [Lara::Models::Glossary]
     def create(name:)
       Lara::Models::Glossary.new(**@client.post("/v2/glossaries",

data/lib/lara/memories.rb

@@ -24,13 +24,27 @@ module Lara
       @polling_interval = 2
     end
 
+    # @deprecated Use #list_paginated instead.
     # @return [Array<Lara::Models::Memory>]
     def list
+      warn "[DEPRECATION] list is deprecated; use list_paginated instead.", uplevel: 1
       (@client.get("/v2/memories") || []).map do |_h|
         Lara::Models::Memory.new(**_h.transform_keys(&:to_sym))
       end
     end
 
+    # Lists resources with optional name filtering and pagination.
+    # Without options, returns the complete collection without pagination.
+    # Any supplied option enables pagination; page and size default to 1 and 20.
+    # @param options [Lara::Models::ResourceQueryOptions,nil] Name filter and pagination
+    # @return [Lara::Models::CollectionResult] Collection containing Memory objects
+    def list_paginated(options = nil)
+      params = options&.to_params || {}
+      @client.get_collection("/v2/memories", params: params) do |item|
+        Lara::Models::Memory.new(**item.transform_keys(&:to_sym))
+      end
+    end
+
     # @return [Lara::Models::Memory]
     def create(name:, external_id: nil)
       payload = { name: name, external_id: external_id }.compact

data/lib/lara/models/collection_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Lara
+  module Models
+    # A resource collection and its server-provided pagination metadata.
+    class CollectionResult < Base
+      # @return [Array<Lara::Models::Memory,Lara::Models::Glossary,Lara::Models::Styleguide>]
+      attr_reader :items
+      # @return [Integer] Total number of matching resources
+      attr_reader :total
+      # @return [Integer,nil] Current page (1-based), or nil for an unbounded collection
+      attr_reader :page
+      # @return [Integer,nil] Page size, or nil for an unbounded collection
+      attr_reader :size
+
+      def initialize(items:, total:, page: nil, size: nil)
+        super()
+        @items = items
+        @total = total
+        @page = page
+        @size = size
+      end
+    end
+  end
+end

data/lib/lara/models/resource_query_options.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Lara
+  module Models
+    # Optional name filtering and pagination for resource collections.
+    class ResourceQueryOptions < Base
+      # @return [String,nil] Filter by visible name (1-255 characters)
+      attr_reader :search
+      # @return [Integer,nil] Page number (1-based); enables pagination when supplied
+      attr_reader :page
+      # @return [Integer,nil] Page size (1-200); enables pagination when supplied
+      attr_reader :size
+
+      def initialize(search: nil, page: nil, size: nil)
+        super()
+        @search = search
+        @page = page
+        @size = size
+      end
+
+      # @return [Hash] Supplied options; validation and defaults are handled by the API
+      def to_params
+        { search: search, page: page, size: size }.compact
+      end
+    end
+  end
+end

data/lib/lara/styleguides.rb

@@ -6,13 +6,27 @@ module Lara
       @client = client
     end
 
+    # @deprecated Use #list_paginated instead.
     # @return [Array<Lara::Models::Styleguide>]
     def list
+      warn "[DEPRECATION] list is deprecated; use list_paginated instead.", uplevel: 1
       (@client.get("/v2/styleguides") || []).map do |h|
         Lara::Models::Styleguide.new(**h.transform_keys(&:to_sym))
       end
     end
 
+    # Lists resources with optional name filtering and pagination.
+    # Without options, returns the complete collection without pagination.
+    # Any supplied option enables pagination; page and size default to 1 and 20.
+    # @param options [Lara::Models::ResourceQueryOptions,nil] Name filter and pagination
+    # @return [Lara::Models::CollectionResult] Collection containing Styleguide objects
+    def list_paginated(options = nil)
+      params = options&.to_params || {}
+      @client.get_collection("/v2/styleguides", params: params) do |item|
+        Lara::Models::Styleguide.new(**item.transform_keys(&:to_sym))
+      end
+    end
+
     # @return [Lara::Models::Styleguide]
     def create(name:, content:)
       Lara::Models::Styleguide.new(**@client.post("/v2/styleguides",

data/lib/lara/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lara
-  VERSION = "1.10.0"
+  VERSION = "1.11.0"
 end

data/lib/lara.rb

@@ -16,6 +16,8 @@ require_relative "lara/audio"
 
 # Models
 require_relative "lara/models/base"
+require_relative "lara/models/collection_result"
+require_relative "lara/models/resource_query_options"
 require_relative "lara/models/text"
 require_relative "lara/models/memories"
 require_relative "lara/models/glossaries"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lara-sdk
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Translated
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -161,10 +161,12 @@ files:
 - lib/lara/memories.rb
 - lib/lara/models/audio.rb
 - lib/lara/models/base.rb
+- lib/lara/models/collection_result.rb
 - lib/lara/models/documents.rb
 - lib/lara/models/glossaries.rb
 - lib/lara/models/images.rb
 - lib/lara/models/memories.rb
+- lib/lara/models/resource_query_options.rb
 - lib/lara/models/shares.rb
 - lib/lara/models/text.rb
 - lib/lara/s3_client.rb