seam 2.139.0 → 2.141.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b94008b86b31b1f480fc2c3276075bc61d83a74dd09ea0af2b7831f39e603c3
-  data.tar.gz: 1f4a039c2309d9b31c82cb9c295c09fb925161150f64eede25fcad60e35c89c0
+  metadata.gz: 67761c76f072fe523b56a8ee78b3112bcccd5c2da40cdd6a38c623e251a66861
+  data.tar.gz: 17eb707e5799d5b97c05d18abb5ce0224411a9cb5f06d00166a791de0e342c66
 SHA512:
-  metadata.gz: c23cbe8e1da6b13568c3cdb1676d7e19c68068aaa99b651ae1915ce4ec04eb776def06af72e3b592381e200e9dd85dbc20e7d568ebe60ea5092e17b27151b67c
-  data.tar.gz: 23f38b1e3c55349694570c17aa70a1d3e6696336d04ec0506ba4758360fdc2a651f9229263efb2c5168f95903f3525c85163ebb1b92de1856f18775e30d830df
+  metadata.gz: dda63b3fe99166377d432246a928f10da2f337cd8633da0df34055efb453afcffbdda6392b3ad94d4951ed12badf293dfb0bb94f5e2dd16dd8f36ef0ffe58f78
+  data.tar.gz: 03233cc7ee5e3136c92e3274410539c0642e69352538797198e2a2dfaebfd9d3187a6fa1e15cfbd744b36c3c8ab12e490631f6513020fd8298e295d5b3fbce34

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    seam (2.139.0)
+    seam (2.141.0)
       faraday (~> 2.7)
       faraday-retry (~> 2.2)
       svix (~> 1.30)
@@ -9,106 +9,109 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
-    ansi (1.5.0)
-    ast (2.4.2)
-    bigdecimal (3.1.8)
-    crack (1.0.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ansi (1.6.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    crack (1.0.1)
       bigdecimal
       rexml
-    diff-lcs (1.5.1)
-    docile (1.4.1)
-    faraday (2.12.0)
-      faraday-net_http (>= 2.0, < 3.4)
+    diff-lcs (1.6.2)
+    faraday (2.14.3)
+      faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.3.0)
-      net-http
-    faraday-retry (2.2.1)
+    faraday-net_http (3.4.4)
+      net-http (~> 0.5)
+    faraday-retry (2.4.0)
       faraday (~> 2.0)
-    gem-release (2.2.2)
-    hashdiff (1.1.2)
-    json (2.8.1)
-    language_server-protocol (3.17.0.3)
+    gem-release (2.2.4)
+    hashdiff (1.2.1)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
-    logger (1.6.1)
-    multi_json (1.15.0)
-    net-http (0.5.0)
-      uri
-    parallel (1.26.3)
+    logger (1.7.0)
+    multi_json (1.21.1)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    parallel (2.1.0)
     parse_gemspec (1.0.0)
     parse_gemspec-cli (1.0.0)
       multi_json
       parse_gemspec
       thor
-    parser (3.3.6.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    public_suffix (6.0.1)
+    prism (1.9.0)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.9.2)
-    rexml (3.3.9)
-    rspec (3.13.0)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rexml (3.4.4)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.2)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.3)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.2)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.1)
-    rubocop (1.66.1)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
-      parallel (~> 1.10)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.4, < 3.0)
-      rubocop-ast (>= 1.32.2, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.35.0)
-      parser (>= 3.3.1.0)
-    rubocop-performance (1.22.1)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-console (0.9.2)
+    simplecov (1.1.1)
+    simplecov-console (0.9.5)
       ansi
       simplecov
       terminal-table
-    simplecov-html (0.13.1)
-    simplecov_json_formatter (0.1.4)
-    standard (1.41.1)
+    standard (1.56.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.66.0)
+      rubocop (~> 1.88.0)
       standard-custom (~> 1.0.0)
-      standard-performance (~> 1.5)
+      standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.5.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.22.0)
-    svix (1.40.0)
-    terminal-table (3.0.2)
-      unicode-display_width (>= 1.1.1, < 3)
-    thor (1.3.2)
-    unicode-display_width (2.6.0)
-    uri (1.0.1)
-    webmock (3.24.0)
+      rubocop-performance (~> 1.26.0)
+    svix (1.99.1)
+      base64 (~> 0.3.0)
+      logger (~> 1.0)
+    terminal-table (4.0.0)
+      unicode-display_width (>= 1.1.1, < 4)
+    thor (1.5.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    webmock (3.26.2)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
@@ -124,10 +127,10 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.0)
   seam!
-  simplecov (~> 0.21)
+  simplecov (~> 1.1)
   simplecov-console (~> 0.9)
   standard (~> 1.3)
-  webmock (~> 3.24.0)
+  webmock (~> 3.26.2)
 
 BUNDLED WITH
-   2.5.16
+   2.5.22

data/README.md

@@ -27,6 +27,7 @@ accurate and fully typed.
     - [API Key](#api-key)
     - [Personal Access Token](#personal-access-token)
   - [Action Attempts](#action-attempts)
+  - [Setting a value to null](#setting-a-value-to-null)
   - [Pagination](#pagination)
     - [Manually fetch pages with the next_page_cursor](#manually-fetch-pages-with-the-next_page_cursor)
     - [Resume pagination](#resume-pagination)
@@ -43,6 +44,7 @@ accurate and fully typed.
     - [Configuring the Faraday Client](#configuring-the-faraday-client)
     - [Using the Faraday Client](#using-the-faraday-client)
     - [Overriding the Client](#overriding-the-client)
+    - [Serializing URL search params](#serializing-url-search-params)
 - [Development and Testing](#development-and-testing)
   - [Quickstart](#quickstart)
   - [Source code](#source-code)
@@ -226,6 +228,35 @@ rescue Seam::ActionAttemptTimeoutError
 end
 ```
 
+### Setting a value to null
+
+The Seam API distinguishes three states for an updatable parameter:
+omitted (leave the stored value unchanged), null (unset the stored value),
+and a value (set it).
+
+Ruby's `nil` means omitted.
+The SDK removes `nil` parameters from the request entirely,
+so passing `nil` never unsets a value.
+To unset a value, pass the `Seam::NULL` sentinel,
+which the SDK sends as JSON `null` in request bodies
+and as an empty value in query strings:
+
+```ruby
+require "seam"
+
+seam = Seam.new
+
+# Leaves ends_at unchanged.
+seam.access_grants.update(access_grant_id: access_grant_id, ends_at: nil)
+
+# Unsets ends_at so the grant no longer expires.
+seam.access_grants.update(access_grant_id: access_grant_id, ends_at: Seam::NULL)
+```
+
+Only pass `Seam::NULL` for parameters the API documents as nullable.
+Generated methods document nullable parameters
+with `Seam::Null` in their `@param` types, e.g. `[String, Seam::Null, nil]`.
+
 ### Pagination
 
 Some Seam API endpoints that return lists of resources support pagination.
@@ -489,6 +520,61 @@ devices = seam.client.get("/devices/list").body["devices"]
 A Faraday compatible client may be provided to create a `Seam` instance.
 This API is used internally and is not directly supported.
 
+#### Serializing URL search params
+
+The Seam API parses URL search params as complex types.
+If you call it with your own HTTP client,
+`Seam.serialize_url_search_params` is exported for that purpose.
+The `_strict=true` parameter is added to any non-empty query
+so the Seam API uses strict, schema-aware parsing.
+A query with no serializable params remains empty.
+
+```ruby
+require "net/http"
+require "seam"
+
+uri = URI("https://connect.getseam.com/devices/list")
+uri.query = Seam.serialize_url_search_params({device_ids: ["device1", "device2"]})
+
+Net::HTTP.get(uri, {"Authorization" => "Bearer your-api-key"})
+```
+
+The serialization defines the name and value of each search param,
+where every value is a string.
+`Seam::UrlSearchParams` holds those pairs and renders the query string,
+as [URLSearchParams] does for the [reference implementation]:
+
+```ruby
+require "seam"
+
+search_params = Seam::UrlSearchParams.new
+
+Seam.update_url_search_params(search_params, {device_ids: ["device1", "device2"]})
+
+search_params.to_a
+# => [["device_ids", "device1"], ["device_ids", "device2"], ["_strict", "true"]]
+
+search_params.to_s
+# => "device_ids=device1&device_ids=device2&_strict=true"
+```
+
+Pass either the query string or the pairs to your HTTP client.
+A client may percent-encode a few characters differently
+than `URLSearchParams` does,
+which the Seam API reads as the same params either way.
+
+A param set to `nil` is omitted,
+while a param set to `Seam::NULL` is serialized to an empty value,
+which the Seam API reads as null,
+as described in [Setting a value to null](#setting-a-value-to-null).
+A param that cannot be represented raises a `Seam::UnserializableParamError`.
+
+The Seam API parses these params with the corresponding [parser].
+
+[URLSearchParams]: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
+[reference implementation]: https://github.com/seamapi/url-search-params-serializer
+[parser]: https://github.com/seamapi/url-search-params-parser
+
 ## Development and Testing
 
 ### Quickstart

data/lib/seam/http_without_workspace.rb

@@ -78,12 +78,12 @@ module Seam
         @workspaces = workspaces
       end
 
-      def list(**kwargs)
-        @workspaces.list(**kwargs)
+      def list(**)
+        @workspaces.list(**)
       end
 
-      def create(**kwargs)
-        @workspaces.create(**kwargs)
+      def create(**)
+        @workspaces.create(**)
       end
     end
 

data/lib/seam/null.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module Seam
+  # The type of the {Seam::NULL} sentinel.
+  class Null
+    include Singleton
+
+    def to_s
+      "NULL"
+    end
+
+    def inspect
+      "NULL"
+    end
+  end
+
+  # Sentinel for an explicit JSON null: +nil+ omits a parameter, +Seam::NULL+
+  # unsets its stored value. Only for parameters the API documents as
+  # nullable.
+  NULL = Null.instance
+end

data/lib/seam/paginator.rb

@@ -11,6 +11,9 @@ module Seam
     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)
+      unless request.parameters.any? { |_, name| name == :page_cursor }
+        raise ArgumentError, "request does not support pagination"
+      end
 
       @request = request
       @params = params.transform_keys(&:to_sym)
@@ -71,7 +74,7 @@ module Seam
     end
   end
 
-  Pagination = Struct.new(:has_next_page, :next_page_cursor, :next_page_url, keyword_init: true) do
+  Pagination = Struct.new(:has_next_page, :next_page_cursor, :next_page_url) do
     def self.from_hash(hash)
       return nil unless hash.is_a?(Hash) && !hash.empty?
 

data/lib/seam/request.rb

@@ -5,6 +5,7 @@ require "faraday/retry"
 require_relative "defaults"
 require_relative "version"
 require_relative "paginator"
+require_relative "strict_url_search_params_serializer"
 
 module Seam
   module Http
@@ -16,7 +17,11 @@ module Seam
         default_options = {
           url: endpoint,
           headers: auth_headers.merge(default_headers),
-          request: {timeout: timeout, open_timeout: timeout}
+          request: {
+            timeout: timeout,
+            open_timeout: timeout,
+            params_encoder: UrlSearchParamsEncoder
+          }
         }
 
         options = deep_merge(default_options, faraday_options)
@@ -33,6 +38,7 @@ module Seam
         faraday_retry_options = default_faraday_retry_options.merge(faraday_retry_options)
 
         Faraday.new(options) do |builder|
+          builder.use ReplaceNullMiddleware
           builder.request :json
           builder.use Seam::PaginationMiddleware
           builder.response :json
@@ -97,6 +103,14 @@ module Seam
         end
       end
 
+      class ReplaceNullMiddleware < Faraday::Middleware
+        def on_request(env)
+          return unless env.body.is_a?(Hash) || env.body.is_a?(Array)
+
+          env.body = Seam.replace_null(env.body)
+        end
+      end
+
       def self.deep_merge(hash1, hash2)
         result = hash1.dup
         hash2.each do |key, value|
@@ -111,5 +125,39 @@ module Seam
 
       private_class_method :deep_merge
     end
+
+    module UrlSearchParamsEncoder
+      # Pairs decoded from a query string already present in the request
+      # path, passed through {encode} verbatim rather than re-serialized.
+      Decoded = Struct.new(:values)
+
+      def self.encode(params)
+        search_params = Seam::UrlSearchParams.new
+        map_params = {}
+
+        params.each do |name, value|
+          if value.is_a?(Decoded)
+            value.values.each { |element| search_params.append(name, element) }
+          else
+            map_params[name] = value
+          end
+        end
+
+        return search_params.to_s if map_params.empty?
+
+        Seam.update_url_search_params(search_params, map_params)
+        search_params.to_s
+      end
+
+      # Called by Faraday when a request path carries its own query string.
+      def self.decode(query)
+        return {} if query.nil? || query.empty?
+
+        pairs = URI.decode_www_form(query.encode(Encoding::UTF_8))
+        pairs.each_with_object({}) do |(name, value), decoded|
+          (decoded[name] ||= Decoded.new([])).values << value
+        end
+      end
+    end
   end
 end