seam 2.18.0 → 2.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c48c12355ea106daaa28e51b49c82112aa7ad7fd3b763c1c1af67120d307b2bc
-  data.tar.gz: 312994eaf8ca41fc60d61cf95e8d61cf17b2c24a7471be1eac25ef3fce58545f
+  metadata.gz: 6a8ea18ff74b9c148761bee6d9f263d4f724677e515724043dd7eccd4cfe3d3b
+  data.tar.gz: a59b64d0e2b47ca9c864a397e077588d2314f0ecec32a7a6fe4214148e72aa76
 SHA512:
-  metadata.gz: 36ec7f4184e8a99af08ed91d731c8f505ca682fc62ca46b0440d24b6c43ab3c7dc79f5952559759234bf0a18490c0d8e37c990f60302a5fd3394af8e5c22c678
-  data.tar.gz: 8ffa2babf798509b894ae45a84d3e83bcd51ec19533043430d0a8b57a4fb27c83d50f4697b9cb7de0ca95ad97abd3e13d95c59c1dbfbb2a3770cba787acd3a1f
+  metadata.gz: ee6c631bff63f2df1f4b9978066cb1c9552ce7693d76569f0769c76e4af2ff43fb9c3cbbf055467e4068fe7f5e3d9b0ee48a16d62631b5c709458008164533e7
+  data.tar.gz: 3154d05cbedde8d06e6f277a81b47ef325b0bdc996875b665a2fddafd1b94e3cab08b134f6b41f503acc0ef97aa7c078eea78765f416373b11063232046821dc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    seam (2.18.0)
+    seam (2.20.0)
       faraday (~> 2.7)
       faraday-retry (~> 2.2)
       svix (~> 1.30)

data/README.md

@@ -27,6 +27,11 @@ accurate and fully typed.
     - [API Key](#api-key)
     - [Personal Access Token](#personal-access-token)
   - [Action Attempts](#action-attempts)
+  - [Pagination](#pagination)
+    - [Manually fetch pages with the next_page_cursor](#manually-fetch-pages-with-the-next_page_cursor)
+    - [Resume pagination](#resume-pagination)
+    - [Iterate over all resources](#iterate-over-all-resources)
+    - [Return all resources across all pages as a list](#return-all-resources-across-all-pages-as-a-list)
   - [Interacting with Multiple Workspaces](#interacting-with-multiple-workspaces)
   - [Webhooks](#webhooks)
   - [Advanced Usage](#advanced-usage)
@@ -215,6 +220,99 @@ rescue Seam::ActionAttemptTimeoutError
 end
 ```
 
+### Pagination
+
+Some Seam API endpoints that return lists of resources support pagination.
+Use the `Seam::Paginator` class to fetch and process resources across multiple pages.
+
+#### Manually fetch pages with the next_page_cursor
+
+```ruby
+require "seam"
+
+seam = Seam.new
+
+paginator = seam.create_paginator(seam.connected_accounts.method(:list), {limit: 20})
+
+connected_accounts, pagination = paginator.first_page
+
+if pagination.has_next_page?
+  more_connected_accounts, _ = paginator.next_page(pagination.next_page_cursor)
+end
+```
+
+#### Resume pagination
+
+Get the first page on initial load and store the state (e.g., in memory or a file):
+
+```ruby
+require "seam"
+require "json"
+
+seam = Seam.new
+
+params = {limit: 20}
+paginator = seam.create_paginator(seam.connected_accounts.method(:list), params)
+
+connected_accounts, pagination = paginator.first_page
+
+# Example: Store state for later use (e.g., in a file or database)
+pagination_state = {
+  "params" => params,
+  "next_page_cursor" => pagination.next_page_cursor,
+  "has_next_page" => pagination.has_next_page?
+}
+File.write("/tmp/seam_connected_accounts_list.json", JSON.dump(pagination_state))
+```
+
+Get the next page at a later time using the stored state:
+
+```ruby
+require "seam"
+require "json"
+
+seam = Seam.new
+
+# Example: Load state from where it was stored
+pagination_state_json = File.read("/tmp/seam_connected_accounts_list.json")
+pagination_state = JSON.parse(pagination_state_json)
+
+if pagination_state["has_next_page"]
+  paginator = seam.create_paginator(
+    seam.connected_accounts.method(:list), pagination_state["params"]
+  )
+  more_connected_accounts, _ = paginator.next_page(
+    pagination_state["next_page_cursor"]
+  )
+end
+```
+
+#### Iterate over all resources
+
+```ruby
+require "seam"
+
+seam = Seam.new
+
+paginator = seam.create_paginator(seam.connected_accounts.method(:list), {limit: 20})
+
+paginator.flatten.each do |account|
+  puts account.account_type_display_name
+end
+```
+
+#### Return all resources across all pages as a list
+
+```ruby
+require "seam"
+
+seam = Seam.new
+
+paginator = seam.create_paginator(seam.connected_accounts.method(:list), {limit: 20})
+
+all_connected_accounts = paginator.flatten_to_list
+```
+
 ### Interacting with Multiple Workspaces
 
 Some Seam API endpoints interact with multiple workspaces. The `Seam::Http::SeamMultiWorkspace` client is not bound to a specific workspace and may use those endpoints with a personal access token authentication method.

data/lib/seam/http_single_workspace.rb

@@ -7,6 +7,7 @@ require_relative "routes/clients/index"
 require_relative "routes/routes"
 require_relative "version"
 require_relative "deep_hash_accessor"
+require_relative "paginator"
 
 module Seam
   module Http
@@ -32,6 +33,10 @@ module Seam
         Seam::LTS_VERSION
       end
 
+      def create_paginator(request, params = {})
+        Paginator.new(request, params)
+      end
+
       def self.from_api_key(api_key, endpoint: nil, wait_for_action_attempt: false, faraday_options: {}, faraday_retry_options: {})
         new(api_key: api_key, endpoint: endpoint, wait_for_action_attempt: wait_for_action_attempt,
           faraday_options: faraday_options, faraday_retry_options: faraday_retry_options)

data/lib/seam/paginator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "faraday"
+require_relative "http"
+
+module Seam
+  THREAD_CONTEXT_KEY = :seam_pagination_context
+  PaginationContext = Struct.new(:pagination)
+
+  class Paginator
+    def initialize(request, params = {})
+      raise ArgumentError, "request must be a Method" unless request.is_a?(Method)
+      raise ArgumentError, "params must be a Hash" unless params.is_a?(Hash)
+
+      @request = request
+      @params = params.transform_keys(&:to_sym)
+    end
+
+    def first_page
+      fetch_page(@params)
+    end
+
+    def next_page(next_page_cursor)
+      if next_page_cursor.nil? || next_page_cursor.empty?
+        raise ArgumentError,
+          "Cannot get the next page with a nil or empty next_page_cursor."
+      end
+
+      fetch_page(@params.merge(page_cursor: next_page_cursor))
+    end
+
+    def flatten_to_list
+      all_items = []
+      current_items, pagination = first_page
+
+      all_items.concat(current_items) if current_items
+
+      while pagination&.has_next_page? && (cursor = pagination.next_page_cursor)
+        current_items, pagination = next_page(cursor)
+        all_items.concat(current_items) if current_items
+      end
+
+      all_items
+    end
+
+    def flatten
+      Enumerator.new do |yielder|
+        current_items, pagination = first_page
+        current_items&.each { |item| yielder << item }
+
+        while pagination&.has_next_page? && (cursor = pagination.next_page_cursor)
+          current_items, pagination = next_page(cursor)
+          current_items&.each { |item| yielder << item }
+        end
+      end
+    end
+
+    private
+
+    def fetch_page(params)
+      context = PaginationContext.new(nil)
+      Thread.current[THREAD_CONTEXT_KEY] = context
+
+      begin
+        res_data = @request.call(**params)
+        pagination_result = Pagination.from_hash(context.pagination)
+        [res_data, pagination_result]
+      ensure
+        Thread.current[THREAD_CONTEXT_KEY] = nil
+      end
+    end
+  end
+
+  Pagination = Struct.new(:has_next_page, :next_page_cursor, :next_page_url, keyword_init: true) do
+    def self.from_hash(hash)
+      return nil unless hash.is_a?(Hash) && !hash.empty?
+
+      new(
+        has_next_page: hash.fetch("has_next_page", false),
+        next_page_cursor: hash.fetch("next_page_cursor", nil),
+        next_page_url: hash.fetch("next_page_url", nil)
+      )
+    end
+
+    def has_next_page?
+      has_next_page == true
+    end
+  end
+
+  class PaginationMiddleware < Faraday::Middleware
+    def on_complete(env)
+      context = Thread.current[THREAD_CONTEXT_KEY]
+      return unless context.is_a?(PaginationContext)
+
+      pagination_hash = extract_pagination(env)
+      context.pagination = pagination_hash if pagination_hash
+    end
+
+    private
+
+    def extract_pagination(env)
+      body = env[:body]
+      body["pagination"] if body.is_a?(Hash) && body.key?("pagination")
+    end
+  end
+end

data/lib/seam/request.rb

@@ -4,6 +4,7 @@ require "faraday"
 require "faraday/retry"
 require_relative "lts_version"
 require_relative "version"
+require_relative "paginator"
 
 module Seam
   module Http
@@ -25,6 +26,7 @@ module Seam
 
         Faraday.new(options) do |builder|
           builder.request :json
+          builder.use Seam::PaginationMiddleware
           builder.response :json
           builder.use ResponseMiddleware
           builder.request :retry, faraday_retry_options

data/lib/seam/routes/clients/user_identities.rb

@@ -30,6 +30,12 @@ module Seam
         nil
       end
 
+      def generate_instant_key(user_identity_id:)
+        res = @client.post("/user_identities/generate_instant_key", {user_identity_id: user_identity_id}.compact)
+
+        Seam::Resources::InstantKey.load_from_response(res.body["instant_key"])
+      end
+
       def get(user_identity_id: nil, user_identity_key: nil)
         res = @client.post("/user_identities/get", {user_identity_id: user_identity_id, user_identity_key: user_identity_key}.compact)
 

data/lib/seam/routes/resources/index.rb

@@ -22,6 +22,7 @@ require_relative "device"
 require_relative "device_provider"
 require_relative "enrollment_automation"
 require_relative "event"
+require_relative "instant_key"
 require_relative "network"
 require_relative "noise_threshold"
 require_relative "pagination"

data/lib/seam/routes/resources/instant_key.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Seam
+  module Resources
+    class InstantKey < BaseResource
+      attr_accessor :client_session_id, :instant_key_id, :instant_key_url, :user_identity_id, :workspace_id
+
+      date_accessor :created_at, :expires_at
+    end
+  end
+end

data/lib/seam/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Seam
-  VERSION = "2.18.0"
+  VERSION = "2.20.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: seam
 version: !ruby/object:Gem::Version
-  version: 2.18.0
+  version: 2.20.0
 platform: ruby
 authors:
 - Seam Labs, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-10 00:00:00.000000000 Z
+date: 2025-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -200,6 +200,7 @@ files:
 - lib/seam/http_single_workspace.rb
 - lib/seam/lts_version.rb
 - lib/seam/options.rb
+- lib/seam/paginator.rb
 - lib/seam/parse_options.rb
 - lib/seam/request.rb
 - lib/seam/routes/clients/access_codes.rb
@@ -255,6 +256,7 @@ files:
 - lib/seam/routes/resources/enrollment_automation.rb
 - lib/seam/routes/resources/event.rb
 - lib/seam/routes/resources/index.rb
+- lib/seam/routes/resources/instant_key.rb
 - lib/seam/routes/resources/network.rb
 - lib/seam/routes/resources/noise_threshold.rb
 - lib/seam/routes/resources/pagination.rb