seam 2.140.0 → 2.141.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 564fdfd341da5fc43c859ba3a1bb7d013b40845ffbab7e0e05f917493b974821
-  data.tar.gz: a9ce5bded784a3153d98b85d6fcaaa1625837f84e9078c94a6c372e9a4a2eb24
+  metadata.gz: 67761c76f072fe523b56a8ee78b3112bcccd5c2da40cdd6a38c623e251a66861
+  data.tar.gz: 17eb707e5799d5b97c05d18abb5ce0224411a9cb5f06d00166a791de0e342c66
 SHA512:
-  metadata.gz: 1cbe2df337d9004d747493a81330ccceda4caa1476e38d0907670b9f47d16bd4e5036a2745c958ca203ff0154e773ef91339769881da525a30ef2839f4d93761
-  data.tar.gz: 0d69f48f2499b5f2275e44ddce95be1ffa50a417e8430374197f6a976fef7691facf1fdf80f247a8dfe0f166f2a32a966b79e74c7c851252e3df5fb502e46332
+  metadata.gz: dda63b3fe99166377d432246a928f10da2f337cd8633da0df34055efb453afcffbdda6392b3ad94d4951ed12badf293dfb0bb94f5e2dd16dd8f36ef0ffe58f78
+  data.tar.gz: 03233cc7ee5e3136c92e3274410539c0642e69352538797198e2a2dfaebfd9d3187a6fa1e15cfbd744b36c3c8ab12e490631f6513020fd8298e295d5b3fbce34

data/Gemfile.lock

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

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/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/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

data/lib/seam/routes/access_codes.rb

@@ -129,7 +129,7 @@ module Seam
       # @param customer_key [String, nil] Customer key for which you want to list access codes.
       # @param device_id [String, nil] ID of the device for which you want to list access codes. Specify `device_id`, `access_code_ids`, `access_method_id`, `access_grant_id`, or `access_grant_key`.
       # @param limit [Float, nil] Numerical limit on the number of access codes to return.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned access codes to include all records that satisfy a partial match using `name`, `code` or `access_code_id`.
       # @param user_identifier_key [String, nil] Your user ID for the user by which to filter access codes.
       # @return [Seam::Resources::AccessCode] OK

data/lib/seam/routes/access_codes_unmanaged.rb

@@ -53,7 +53,7 @@ module Seam
       # Returns a list of all [unmanaged access codes](https://docs.seam.co/low-level-apis/smart-locks/access-codes/migrating-existing-access-codes).
       # @param device_id [String] ID of the device for which you want to list unmanaged access codes.
       # @param limit [Float, nil] Numerical limit on the number of unmanaged access codes to return.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned access codes to include all records that satisfy a partial match using `name`, `code` or `access_code_id`.
       # @param user_identifier_key [String, nil] Your user ID for the user by which to filter unmanaged access codes.
       # @return [Seam::Resources::UnmanagedAccessCode] OK

data/lib/seam/routes/access_grants.rb

@@ -20,12 +20,12 @@ module Seam
       # @param acs_entrance_ids [Array<String>, nil] Set of IDs of the [entrances](https://docs.seam.co/api/acs/systems/list) to which access is being granted.
       # @param customization_profile_id [String, nil] ID of the customization profile to apply to the Access Grant and its access methods.
       # @param device_ids [Array<String>, nil] Set of IDs of the [devices](https://docs.seam.co/api/devices/list) to which access is being granted.
-      # @param ends_at [String, nil] Date and time at which the validity of the new grant ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`.
+      # @param ends_at [String, Seam::Null, nil] Date and time at which the validity of the new grant ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`.
       # @param location [Hash, nil]
       # @deprecated location: Create a space first, then reference it using `space_ids`.
       # @param location_ids [Array<String>, nil]
       # @deprecated location_ids: Use `space_ids`.
-      # @param name [String, nil] Name for the access grant.
+      # @param name [String, Seam::Null, nil] Name for the access grant.
       # @param reservation_key [String, nil] Reservation key for the access grant.
       # @param space_ids [Array<String>, nil] Set of IDs of existing spaces to which access is being granted.
       # @param space_keys [Array<String>, nil] Set of keys of existing spaces to which access is being granted.
@@ -79,7 +79,7 @@ module Seam
       # Gets an Access Grant.
       # @param access_code_id [String, nil] ID of the access code by which you want to filter the list of Access Grants.
       # @param access_grant_ids [Array<String>, nil] IDs of the access grants to retrieve.
-      # @param access_grant_key [String, nil] Filter Access Grants by access_grant_key. Use null to filter for Access Grants without an access_grant_key.
+      # @param access_grant_key [String, Seam::Null, nil] Filter Access Grants by access_grant_key. Use null to filter for Access Grants without an access_grant_key.
       # @param acs_entrance_id [String, nil] ID of the entrance by which you want to filter the list of Access Grants.
       # @param acs_system_id [String, nil] ID of the access system by which you want to filter the list of Access Grants.
       # @param customer_key [String, nil] Customer key for which you want to list access grants.
@@ -87,7 +87,7 @@ module Seam
       # @param limit [Float, nil] Numerical limit on the number of access grants to return.
       # @param location_id [String, nil]
       # @deprecated location_id: Use `space_id`.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param reservation_key [String, nil] Filter Access Grants by reservation_key.
       # @param space_id [String, nil] ID of the space by which you want to filter the list of Access Grants.
       # @param user_identity_id [String, nil] ID of user identity by which you want to filter the list of Access Grants.
@@ -111,8 +111,8 @@ module Seam
       # Updates an existing Access Grant's time window.
       # @param access_grant_id [String, nil] ID of the Access Grant to update. Provide either `access_grant_id` or `access_grant_key`.
       # @param access_grant_key [String, nil] Key of the Access Grant to update. Provide either `access_grant_id` or `access_grant_key`.
-      # @param ends_at [Time, nil] Date and time at which the validity of the grant ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`.
-      # @param name [String, nil] Display name for the access grant.
+      # @param ends_at [Time, Seam::Null, nil] Date and time at which the validity of the grant ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`.
+      # @param name [String, Seam::Null, nil] Display name for the access grant.
       # @param starts_at [Time, nil] Date and time at which the validity of the grant starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
       # @return [nil] OK
       def update(access_grant_id: nil, access_grant_key: nil, ends_at: nil, name: nil, starts_at: nil)

data/lib/seam/routes/access_grants_unmanaged.rb

@@ -21,7 +21,7 @@ module Seam
       # @param acs_entrance_id [String, nil] ID of the entrance by which you want to filter the list of unmanaged Access Grants.
       # @param acs_system_id [String, nil] ID of the access system by which you want to filter the list of unmanaged Access Grants.
       # @param limit [Float, nil] Numerical limit on the number of unmanaged access grants to return.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param reservation_key [String, nil] Filter unmanaged Access Grants by reservation_key.
       # @param user_identity_id [String, nil] ID of user identity by which you want to filter the list of unmanaged Access Grants.
       # @return [Seam::Resources::UnmanagedAccessGrant] OK

data/lib/seam/routes/access_methods.rb

@@ -80,7 +80,7 @@ module Seam
       # @param acs_entrance_id [String, nil] ID of the entrance for which you want to retrieve all access methods that grant access to it.
       # @param device_id [String, nil] ID of the device by which to filter the returned access methods. Must be combined with `access_grant_id`, `access_grant_key`, or `acs_entrance_id`.
       # @param limit [Integer, nil] Maximum number of records to return per page.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param space_id [String, nil] ID of the space by which to filter the returned access methods. Must be combined with `access_grant_id`, `access_grant_key`, or `acs_entrance_id`.
       # @return [Seam::Resources::AccessMethod] OK
       def list(access_code_id: nil, access_grant_id: nil, access_grant_key: nil, acs_entrance_id: nil, device_id: nil, limit: nil, page_cursor: nil, space_id: nil)

data/lib/seam/routes/acs_credentials.rb

@@ -65,7 +65,7 @@ module Seam
       # @param created_before [Time, nil] Date and time, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format, before which events to return were created.
       # @param is_multi_phone_sync_credential [Boolean, nil] Indicates whether you want to retrieve only multi-phone sync credentials or non-multi-phone sync credentials.
       # @param limit [Float, nil] Number of credentials to return.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned credentials to include all records that satisfy a partial match using `display_name`, `code`, `card_number`, `acs_user_id` or `acs_credential_id`.
       # @return [Seam::Resources::AcsCredential] OK
       def list(acs_user_id: nil, acs_system_id: nil, user_identity_id: nil, created_before: nil, is_multi_phone_sync_credential: nil, limit: nil, page_cursor: nil, search: nil)

data/lib/seam/routes/acs_encoders.rb

@@ -41,7 +41,7 @@ module Seam
       # @param acs_system_ids [Array<String>, nil] IDs of the access systems for which you want to retrieve all encoders.
       # @param acs_encoder_ids [Array<String>, nil] IDs of the encoders that you want to retrieve.
       # @param limit [Float, nil] Number of encoders to return.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @return [Seam::Resources::AcsEncoder] OK
       def list(acs_system_id: nil, acs_system_ids: nil, acs_encoder_ids: nil, limit: nil, page_cursor: nil)
         res = @client.post("/acs/encoders/list", {acs_system_id: acs_system_id, acs_system_ids: acs_system_ids, acs_encoder_ids: acs_encoder_ids, limit: limit, page_cursor: page_cursor}.compact)

data/lib/seam/routes/acs_entrances.rb

@@ -38,9 +38,9 @@ module Seam
       # @param connected_account_id [String, nil] ID of the connected account for which you want to retrieve all entrances.
       # @param customer_key [String, nil] Customer key for which you want to list entrances.
       # @param limit [Integer, nil] Maximum number of records to return per page.
-      # @param location_id [String, nil]
+      # @param location_id [String, Seam::Null, nil]
       # @deprecated location_id: Use `space_id`.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned entrances to include all records that satisfy a partial match using `display_name`.
       # @param space_id [String, nil] ID of the space for which you want to list entrances.
       # @return [Seam::Resources::AcsEntrance] OK

data/lib/seam/routes/acs_users.rb

@@ -69,7 +69,7 @@ module Seam
       # @param acs_system_id [String, nil] ID of the `acs_system` for which you want to retrieve all access system users.
       # @param created_before [Time, nil] Timestamp by which to limit returned access system users. Returns users created before this timestamp.
       # @param limit [Integer, nil] Maximum number of records to return per page.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned access system users to include all records that satisfy a partial match using `full_name`, `phone_number`, `email_address`, `acs_user_id`, `user_identity_id`, `user_identity_full_name` or `user_identity_phone_number`.
       # @param user_identity_email_address [String, nil] Email address of the user identity for which you want to retrieve all access system users.
       # @param user_identity_id [String, nil] ID of the user identity for which you want to retrieve all access system users.
@@ -153,7 +153,7 @@ module Seam
       end
 
       # Updates the properties of a specified [access system user](https://docs.seam.co/low-level-apis/access-systems/user-management).
-      # @param access_schedule [Hash, nil] `starts_at` and `ends_at` timestamps for the access system user's access. If you specify an `access_schedule`, you may include both `starts_at` and `ends_at`. If you omit `starts_at`, it defaults to the current time. `ends_at` is optional and must be a time in the future and after `starts_at`.
+      # @param access_schedule [Hash, Seam::Null, nil] `starts_at` and `ends_at` timestamps for the access system user's access. If you specify an `access_schedule`, you may include both `starts_at` and `ends_at`. If you omit `starts_at`, it defaults to the current time. `ends_at` is optional and must be a time in the future and after `starts_at`.
       # @param acs_system_id [String, nil] ID of the access system that you want to update. You can only provide acs_system_id with user_identity_id.
       # @param acs_user_id [String, nil] ID of the access system user that you want to update. You can only provide acs_user_id or user_identity_id.
       # @param email [String, nil]

data/lib/seam/routes/action_attempts.rb

@@ -25,7 +25,7 @@ module Seam
       # @param action_attempt_ids [Array<String>, nil] IDs of the action attempts that you want to retrieve.
       # @param device_id [String, nil] ID of the device to filter action attempts by.
       # @param limit [Integer, nil] Maximum number of records to return per page.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @return [Seam::Resources::ActionAttempt] OK
       def list(action_attempt_ids: nil, device_id: nil, limit: nil, page_cursor: nil)
         res = @client.post("/action_attempts/list", {action_attempt_ids: action_attempt_ids, device_id: device_id, limit: limit, page_cursor: page_cursor}.compact)

data/lib/seam/routes/connect_webviews.rb

@@ -58,7 +58,7 @@ module Seam
       # @param custom_metadata_has [Hash, nil] Custom metadata pairs by which you want to [filter Connect Webviews](https://docs.seam.co/core-concepts/connect-webviews/filtering-connect-webviews-by-custom-metadata). Returns Connect Webviews with `custom_metadata` that contains all of the provided key:value pairs.
       # @param customer_key [String, nil] Customer key for which you want to list connect webviews.
       # @param limit [Float, nil] Maximum number of records to return per page.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned Connect Webviews to include all records that satisfy a partial match using `connect_webview_id`, `accepted_providers`, `custom_metadata`, or `customer_key`.
       # @param user_identifier_key [String, nil] Your user ID for the user by which you want to filter Connect Webviews.
       # @return [Seam::Resources::ConnectWebview] OK

data/lib/seam/routes/connected_accounts.rb

@@ -43,7 +43,7 @@ module Seam
       # @param custom_metadata_has [Hash, nil] Custom metadata pairs by which you want to filter connected accounts. Returns connected accounts with `custom_metadata` that contains all of the provided key:value pairs.
       # @param customer_key [String, nil] Customer key by which you want to filter connected accounts.
       # @param limit [Integer, nil] Maximum number of records to return per page.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned connected accounts to include all records that satisfy a partial match using `connected_account_id`, `account_type`, `customer_key`, `custom_metadata`, `user_identifier.username`, `user_identifier.email` or `user_identifier.phone`.
       # @param space_id [String, nil] ID of the space by which you want to filter connected accounts.
       # @param user_identifier_key [String, nil] Your user ID for the user by which you want to filter connected accounts.

data/lib/seam/routes/devices.rb

@@ -44,10 +44,10 @@ module Seam
       # @param device_types [Array<String>, nil] Array of device types for which you want to list devices.
       # @param limit [Float, nil] Numerical limit on the number of devices to return.
       # @param manufacturer [String, nil] Manufacturer for which you want to list devices.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned devices to include all records that satisfy a partial match using `device_id` (full or partial UUID prefix, minimum 4 characters), `connected_account_id`, `display_name`, `custom_metadata` or `location.location_name`.
       # @param space_id [String, nil] ID of the space for which you want to list devices.
-      # @param unstable_location_id [String, nil]
+      # @param unstable_location_id [String, Seam::Null, nil]
       # @deprecated unstable_location_id: Use `space_id`.
       # @param user_identifier_key [String, nil] Your own internal user ID for the user for which you want to list devices.
       # @return [Seam::Resources::Device] OK
@@ -86,7 +86,7 @@ module Seam
       # @param backup_access_code_pool_enabled [Boolean, nil] Indicates whether the device's [backup access code pool](https://docs.seam.co/low-level-apis/smart-locks/access-codes/backup-access-codes) is enabled. Set to `false` to disable the pool: Seam stops refilling it and removes any backup codes that have not yet been pulled into active use.
       # @param custom_metadata [Hash, nil] Custom metadata that you want to associate with the device. Supports up to 50 JSON key:value pairs. [Adding custom metadata to a device](https://docs.seam.co/core-concepts/devices/adding-custom-metadata-to-a-device) enables you to store custom information, like customer details or internal IDs from your application. Then, you can [filter devices by the desired metadata](https://docs.seam.co/core-concepts/devices/filtering-devices-by-custom-metadata).
       # @param is_managed [Boolean, nil] Indicates whether the device is managed. To unmanage a device, set `is_managed` to `false`.
-      # @param name [String, nil] Name for the device.
+      # @param name [String, Seam::Null, nil] Name for the device.
       # @param properties [Hash, nil]
       # @return [nil] OK
       def update(device_id:, backup_access_code_pool_enabled: nil, custom_metadata: nil, is_managed: nil, name: nil, properties: nil)

data/lib/seam/routes/devices_unmanaged.rb

@@ -39,7 +39,7 @@ module Seam
       # @param device_types [Array<String>, nil] Array of device types for which you want to list devices.
       # @param limit [Float, nil] Numerical limit on the number of devices to return.
       # @param manufacturer [String, nil] Manufacturer for which you want to list devices.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned devices to include all records that satisfy a partial match using `device_id` (full or partial UUID prefix, minimum 4 characters), `connected_account_id`, `display_name`, `custom_metadata` or `location.location_name`.
       # @return [Seam::Resources::UnmanagedDevice] OK
       def list(connect_webview_id: nil, connected_account_id: nil, connected_account_ids: nil, created_before: nil, customer_key: nil, device_ids: nil, device_type: nil, device_types: nil, limit: nil, manufacturer: nil, page_cursor: nil, search: nil)

data/lib/seam/routes/spaces.rb

@@ -95,7 +95,7 @@ module Seam
       # Returns a list of all spaces.
       # @param customer_key [String, nil] Customer key for which you want to list spaces.
       # @param limit [Float, nil] Maximum number of records to return per page.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned spaces to include all records that satisfy a partial match using `name`, `space_key`, or `customer_key`.
       # @param space_key [String, nil] Filter spaces by space_key.
       # @return [Seam::Resources::Space] OK

data/lib/seam/routes/thermostats.rb

@@ -60,7 +60,7 @@ module Seam
       # @param hvac_mode_setting [String, nil] Desired [HVAC mode](https://docs.seam.co/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
       # @param manual_override_allowed [Boolean, nil] Indicates whether a person at the thermostat or using the API can change the thermostat's settings.
       # @deprecated manual_override_allowed: Use 'thermostat_schedule.is_override_allowed'
-      # @param name [String, nil] User-friendly name to identify the [climate preset](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-climate-presets).
+      # @param name [String, Seam::Null, nil] User-friendly name to identify the [climate preset](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-climate-presets).
       # @return [nil] OK
       def create_climate_preset(climate_preset_key:, device_id:, climate_preset_mode: nil, cooling_set_point_celsius: nil, cooling_set_point_fahrenheit: nil, ecobee_metadata: nil, fan_mode_setting: nil, heating_set_point_celsius: nil, heating_set_point_fahrenheit: nil, hvac_mode_setting: nil, manual_override_allowed: nil, name: nil)
         @client.post("/thermostats/create_climate_preset", {climate_preset_key: climate_preset_key, device_id: device_id, climate_preset_mode: climate_preset_mode, cooling_set_point_celsius: cooling_set_point_celsius, cooling_set_point_fahrenheit: cooling_set_point_fahrenheit, ecobee_metadata: ecobee_metadata, fan_mode_setting: fan_mode_setting, heating_set_point_celsius: heating_set_point_celsius, heating_set_point_fahrenheit: heating_set_point_fahrenheit, hvac_mode_setting: hvac_mode_setting, manual_override_allowed: manual_override_allowed, name: name}.compact)
@@ -173,10 +173,10 @@ module Seam
 
       # Sets a [temperature threshold](https://docs.seam.co/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) for a specified thermostat. Seam emits a `thermostat.temperature_threshold_exceeded` event and adds a warning on a thermostat if it reports a temperature outside the threshold range.
       # @param device_id [String] ID of the thermostat device for which you want to set a temperature threshold.
-      # @param lower_limit_celsius [Float, nil] Lower temperature limit in in °C. Seam alerts you if the reported temperature is lower than this value. You can specify either `lower_limit` but not both.
-      # @param lower_limit_fahrenheit [Float, nil] Lower temperature limit in in °F. Seam alerts you if the reported temperature is lower than this value. You can specify either `lower_limit` but not both.
-      # @param upper_limit_celsius [Float, nil] Upper temperature limit in in °C. Seam alerts you if the reported temperature is higher than this value. You can specify either `upper_limit` but not both.
-      # @param upper_limit_fahrenheit [Float, nil] Upper temperature limit in in °C. Seam alerts you if the reported temperature is higher than this value. You can specify either `upper_limit` but not both.
+      # @param lower_limit_celsius [Float, Seam::Null, nil] Lower temperature limit in in °C. Seam alerts you if the reported temperature is lower than this value. You can specify either `lower_limit` but not both.
+      # @param lower_limit_fahrenheit [Float, Seam::Null, nil] Lower temperature limit in in °F. Seam alerts you if the reported temperature is lower than this value. You can specify either `lower_limit` but not both.
+      # @param upper_limit_celsius [Float, Seam::Null, nil] Upper temperature limit in in °C. Seam alerts you if the reported temperature is higher than this value. You can specify either `upper_limit` but not both.
+      # @param upper_limit_fahrenheit [Float, Seam::Null, nil] Upper temperature limit in in °C. Seam alerts you if the reported temperature is higher than this value. You can specify either `upper_limit` but not both.
       # @return [nil] OK
       def set_temperature_threshold(device_id:, lower_limit_celsius: nil, lower_limit_fahrenheit: nil, upper_limit_celsius: nil, upper_limit_fahrenheit: nil)
         @client.patch("/thermostats/set_temperature_threshold", {device_id: device_id, lower_limit_celsius: lower_limit_celsius, lower_limit_fahrenheit: lower_limit_fahrenheit, upper_limit_celsius: upper_limit_celsius, upper_limit_fahrenheit: upper_limit_fahrenheit}.compact)
@@ -197,7 +197,7 @@ module Seam
       # @param hvac_mode_setting [String, nil] Desired [HVAC mode](https://docs.seam.co/capability-guides/thermostats/understanding-thermostat-concepts/hvac-mode) setting, such as `heat`, `cool`, `heat_cool`, or `off`.
       # @param manual_override_allowed [Boolean, nil] Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
       # @deprecated manual_override_allowed: Use 'thermostat_schedule.is_override_allowed'
-      # @param name [String, nil] User-friendly name to identify the [climate preset](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-climate-presets).
+      # @param name [String, Seam::Null, nil] User-friendly name to identify the [climate preset](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-climate-presets).
       # @return [nil] OK
       def update_climate_preset(climate_preset_key:, device_id:, climate_preset_mode: nil, cooling_set_point_celsius: nil, cooling_set_point_fahrenheit: nil, ecobee_metadata: nil, fan_mode_setting: nil, heating_set_point_celsius: nil, heating_set_point_fahrenheit: nil, hvac_mode_setting: nil, manual_override_allowed: nil, name: nil)
         @client.patch("/thermostats/update_climate_preset", {climate_preset_key: climate_preset_key, device_id: device_id, climate_preset_mode: climate_preset_mode, cooling_set_point_celsius: cooling_set_point_celsius, cooling_set_point_fahrenheit: cooling_set_point_fahrenheit, ecobee_metadata: ecobee_metadata, fan_mode_setting: fan_mode_setting, heating_set_point_celsius: heating_set_point_celsius, heating_set_point_fahrenheit: heating_set_point_fahrenheit, hvac_mode_setting: hvac_mode_setting, manual_override_allowed: manual_override_allowed, name: name}.compact)
@@ -207,13 +207,13 @@ module Seam
 
       # Updates the thermostat weekly program for a thermostat device. To configure a weekly program, specify the ID of the daily program that you want to use for each day of the week. When you update a weekly program, the set of programs that you specify overwrites any previous weekly program for the thermostat.
       # @param device_id [String] ID of the thermostat device for which you want to update the weekly program.
-      # @param friday_program_id [String, nil] ID of the thermostat daily program to run on Fridays.
-      # @param monday_program_id [String, nil] ID of the thermostat daily program to run on Mondays.
-      # @param saturday_program_id [String, nil] ID of the thermostat daily program to run on Saturdays.
-      # @param sunday_program_id [String, nil] ID of the thermostat daily program to run on Sundays.
-      # @param thursday_program_id [String, nil] ID of the thermostat daily program to run on Thursdays.
-      # @param tuesday_program_id [String, nil] ID of the thermostat daily program to run on Tuesdays.
-      # @param wednesday_program_id [String, nil] ID of the thermostat daily program to run on Wednesdays.
+      # @param friday_program_id [String, Seam::Null, nil] ID of the thermostat daily program to run on Fridays.
+      # @param monday_program_id [String, Seam::Null, nil] ID of the thermostat daily program to run on Mondays.
+      # @param saturday_program_id [String, Seam::Null, nil] ID of the thermostat daily program to run on Saturdays.
+      # @param sunday_program_id [String, Seam::Null, nil] ID of the thermostat daily program to run on Sundays.
+      # @param thursday_program_id [String, Seam::Null, nil] ID of the thermostat daily program to run on Thursdays.
+      # @param tuesday_program_id [String, Seam::Null, nil] ID of the thermostat daily program to run on Tuesdays.
+      # @param wednesday_program_id [String, Seam::Null, nil] ID of the thermostat daily program to run on Wednesdays.
       # @return [Seam::Resources::ActionAttempt] OK
       def update_weekly_program(device_id:, friday_program_id: nil, monday_program_id: nil, saturday_program_id: nil, sunday_program_id: nil, thursday_program_id: nil, tuesday_program_id: nil, wednesday_program_id: nil, wait_for_action_attempt: nil)
         res = @client.post("/thermostats/update_weekly_program", {device_id: device_id, friday_program_id: friday_program_id, monday_program_id: monday_program_id, saturday_program_id: saturday_program_id, sunday_program_id: sunday_program_id, thursday_program_id: thursday_program_id, tuesday_program_id: tuesday_program_id, wednesday_program_id: wednesday_program_id}.compact)

data/lib/seam/routes/thermostats_schedules.rb

@@ -14,7 +14,7 @@ module Seam
       # @param ends_at [String] Date and time at which the new thermostat schedule ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
       # @param starts_at [String] Date and time at which the new thermostat schedule starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
       # @param is_override_allowed [Boolean, nil] Indicates whether a person at the thermostat or using the API can change the thermostat's settings while the new schedule is active. See also [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
-      # @param max_override_period_minutes [Integer, nil] Number of minutes for which a person at the thermostat or using the API can change the thermostat's settings after the activation of the scheduled climate preset. See also [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
+      # @param max_override_period_minutes [Integer, Seam::Null, nil] Number of minutes for which a person at the thermostat or using the API can change the thermostat's settings after the activation of the scheduled climate preset. See also [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
       # @param name [String, nil] Name of the thermostat schedule.
       # @return [Seam::Resources::ThermostatSchedule] OK
       def create(climate_preset_key:, device_id:, ends_at:, starts_at:, is_override_allowed: nil, max_override_period_minutes: nil, name: nil)
@@ -56,7 +56,7 @@ module Seam
       # @param climate_preset_key [String, nil] Key of the [climate preset](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-climate-presets) to use for the thermostat schedule.
       # @param ends_at [String, nil] Date and time at which the thermostat schedule ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
       # @param is_override_allowed [Boolean, nil] Indicates whether a person at the thermostat or using the API can change the thermostat's settings while the schedule is active. See also [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
-      # @param max_override_period_minutes [Integer, nil] Number of minutes for which a person at the thermostat or using the API can change the thermostat's settings after the activation of the scheduled climate preset. See also [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
+      # @param max_override_period_minutes [Integer, Seam::Null, nil] Number of minutes for which a person at the thermostat or using the API can change the thermostat's settings after the activation of the scheduled climate preset. See also [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions).
       # @param name [String, nil] Name of the thermostat schedule.
       # @param starts_at [String, nil] Date and time at which the thermostat schedule starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
       # @return [nil] OK

data/lib/seam/routes/user_identities.rb

@@ -29,10 +29,10 @@ module Seam
 
       # Creates a new [user identity](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).
       # @param acs_system_ids [Array<String>, nil] List of access system IDs to associate with the new user identity through access system users. If there's no user with the same email address or phone number in the specified access systems, a new access system user is created. If there is an existing user with the same email or phone number in the specified access systems, the user is linked to the user identity.
-      # @param email_address [String, nil] Unique email address for the new user identity.
-      # @param full_name [String, nil] Full name of the user associated with the new user identity.
-      # @param phone_number [String, nil] Unique phone number for the new user identity in E.164 format (for example, +15555550100).
-      # @param user_identity_key [String, nil] Unique key for the new user identity.
+      # @param email_address [String, Seam::Null, nil] Unique email address for the new user identity.
+      # @param full_name [String, Seam::Null, nil] Full name of the user associated with the new user identity.
+      # @param phone_number [String, Seam::Null, nil] Unique phone number for the new user identity in E.164 format (for example, +15555550100).
+      # @param user_identity_key [String, Seam::Null, nil] Unique key for the new user identity.
       # @return [Seam::Resources::UserIdentity] OK
       def create(acs_system_ids: nil, email_address: nil, full_name: nil, phone_number: nil, user_identity_key: nil)
         res = @client.post("/user_identities/create", {acs_system_ids: acs_system_ids, email_address: email_address, full_name: full_name, phone_number: phone_number, user_identity_key: user_identity_key}.compact)
@@ -88,7 +88,7 @@ module Seam
       # @param created_before [Time, nil] Timestamp by which to limit returned user identities. Returns user identities created before this timestamp.
       # @param credential_manager_acs_system_id [String, nil] `acs_system_id` of the credential manager by which you want to filter the list of user identities.
       # @param limit [Integer, nil] Maximum number of records to return per page.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned user identities to include all records that satisfy a partial match using `full_name`, `phone_number`, `email_address` or `user_identity_id`.
       # @param user_identity_ids [Array<String>, nil] Array of user identity IDs by which to filter the list of user identities.
       # @return [Seam::Resources::UserIdentity] OK
@@ -156,10 +156,10 @@ module Seam
 
       # Updates a specified [user identity](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity).
       # @param user_identity_id [String] ID of the user identity that you want to update.
-      # @param email_address [String, nil] Unique email address for the user identity.
-      # @param full_name [String, nil] Full name of the user associated with the user identity.
-      # @param phone_number [String, nil] Unique phone number for the user identity.
-      # @param user_identity_key [String, nil] Unique key for the user identity.
+      # @param email_address [String, Seam::Null, nil] Unique email address for the user identity.
+      # @param full_name [String, Seam::Null, nil] Full name of the user associated with the user identity.
+      # @param phone_number [String, Seam::Null, nil] Unique phone number for the user identity.
+      # @param user_identity_key [String, Seam::Null, nil] Unique key for the user identity.
       # @return [nil] OK
       def update(user_identity_id:, email_address: nil, full_name: nil, phone_number: nil, user_identity_key: nil)
         @client.patch("/user_identities/update", {user_identity_id: user_identity_id, email_address: email_address, full_name: full_name, phone_number: phone_number, user_identity_key: user_identity_key}.compact)

data/lib/seam/routes/user_identities_unmanaged.rb

@@ -20,7 +20,7 @@ module Seam
       # Returns a list of all unmanaged [user identities](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) (where is_managed = false).
       # @param created_before [Time, nil] Timestamp by which to limit returned unmanaged user identities. Returns user identities created before this timestamp.
       # @param limit [Integer, nil] Maximum number of records to return per page.
-      # @param page_cursor [String, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+      # @param page_cursor [String, Seam::Null, nil] Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
       # @param search [String, nil] String for which to search. Filters returned unmanaged user identities to include all records that satisfy a partial match using `full_name`, `phone_number`, `email_address`,  `user_identity_id` or `acs_system_id`.
       # @return [Seam::Resources::UnmanagedUserIdentity] OK
       def list(created_before: nil, limit: nil, page_cursor: nil, search: nil)

data/lib/seam/routes/workspaces.rb

@@ -13,7 +13,7 @@ module Seam
       # Creates a new [workspace](https://docs.seam.co/core-concepts/workspaces).
       # @param name [String] Name of the new workspace.
       # @param company_name [String, nil] Company name for the new workspace.
-      # @param connect_partner_name [String, nil] Connect partner name for the new workspace.
+      # @param connect_partner_name [String, Seam::Null, nil] Connect partner name for the new workspace.
       # @deprecated connect_partner_name: Use `company_name` instead.
       # @param connect_webview_customization [Hash, nil] [Connect Webview](https://docs.seam.co/core-concepts/connect-webviews) customizations for the new workspace. See also [Customize the Look and Feel of Your Connect Webviews](https://docs.seam.co/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-look-and-feel-of-your-connect-webviews).
       # @param is_sandbox [Boolean, nil] Indicates whether the new workspace is a [sandbox workspace](https://docs.seam.co/core-concepts/workspaces#sandbox-workspaces).

data/lib/seam/strict_url_search_params_serializer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "url_search_params_serializer"
+
+# Strict serialization, used by the SDK itself: _strict=true is added to any
+# non-empty query so the Seam API uses strict, schema-aware parsing.
+module Seam
+  # (see UrlSearchParamsSerializer.serialize_url_search_params)
+  def self.serialize_url_search_params(params)
+    UrlSearchParamsSerializer.serialize_url_search_params(params, strict: true)
+  end
+
+  # (see UrlSearchParamsSerializer.update_url_search_params)
+  def self.update_url_search_params(search_params, params)
+    UrlSearchParamsSerializer.update_url_search_params(search_params, params, strict: true)
+  end
+end

data/lib/seam/url_search_params.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Seam
+  # A mutable, ordered list of name/value string pairs modeling the parts of
+  # the WHATWG URLSearchParams interface that the Seam URL search params
+  # serializer needs.
+  class UrlSearchParams
+    include Enumerable
+
+    # @param init [String, Hash, Enumerable, nil]
+    def initialize(init = nil)
+      @pairs = []
+      return if init.nil?
+
+      case init
+      when String
+        query = init.delete_prefix("?")
+        URI.decode_www_form(query).each { |name, value| append(name, value) } unless query.empty?
+      when Hash
+        init.each { |name, value| append(name, value) }
+      else
+        init.each { |name, value| append(name, value) }
+      end
+    end
+
+    def append(name, value)
+      @pairs << [name.to_s, value.to_s]
+      nil
+    end
+
+    def set(name, value)
+      name = name.to_s
+      replaced = false
+      @pairs = @pairs.filter_map do |pair|
+        next pair unless pair.first == name
+        next nil if replaced
+
+        replaced = true
+        [name, value.to_s]
+      end
+      append(name, value) unless replaced
+      nil
+    end
+
+    def get(name)
+      name = name.to_s
+      @pairs.each { |pair_name, value| return value if pair_name == name }
+      nil
+    end
+
+    def get_all(name)
+      name = name.to_s
+      @pairs.filter_map { |pair_name, value| value if pair_name == name }
+    end
+
+    def has?(name)
+      name = name.to_s
+      @pairs.any? { |pair_name, _| pair_name == name }
+    end
+
+    def delete(name)
+      name = name.to_s
+      @pairs.reject! { |pair_name, _| pair_name == name }
+      nil
+    end
+
+    def sort!
+      @pairs = @pairs.each_with_index.sort_by do |(name, _), index|
+        [name.encode(Encoding::UTF_16BE).b, index]
+      end.map(&:first)
+      nil
+    end
+
+    def each(&block)
+      return @pairs.each unless block
+
+      @pairs.each(&block)
+      self
+    end
+
+    def size
+      @pairs.size
+    end
+    alias_method :length, :size
+
+    def empty?
+      @pairs.empty?
+    end
+
+    def to_s
+      @pairs.map do |name, value|
+        "#{self.class.encode_component(name)}=#{self.class.encode_component(value)}"
+      end.join("&")
+    end
+
+    def self.encode_component(string)
+      URI.encode_www_form_component(string.encode(Encoding::UTF_8))
+    end
+  end
+end

data/lib/seam/url_search_params_serializer.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "date"
+
+require_relative "null"
+require_relative "url_search_params"
+
+module Seam
+  class UnserializableParamError < StandardError
+    attr_reader :param_name
+
+    def initialize(param_name, reason)
+      @param_name = param_name
+      super("Could not serialize parameter: '#{param_name}' #{reason}")
+    end
+  end
+
+  def self.replace_null(value)
+    case value
+    when Seam::Null then nil
+    when Hash then value.transform_values { |v| replace_null(v) }
+    when Array then value.map { |v| replace_null(v) }
+    else value
+    end
+  end
+
+  # Serializes parameters to a URL query string following the
+  # @seamapi/url-search-params-serializer standard:
+  # https://github.com/seamapi/url-search-params-serializer
+  module UrlSearchParamsSerializer
+    # @param params [Hash]
+    # @param strict [Boolean] Whether to add +_strict=true+ to a non-empty
+    #   query string
+    # @return [String] The query string, without a leading +?+
+    # @raise [UnserializableParamError]
+    def self.serialize_url_search_params(params, strict: false)
+      search_params = UrlSearchParams.new
+      update_url_search_params(search_params, params, strict: strict)
+      search_params.to_s
+    end
+
+    # Serializes parameters into an existing {UrlSearchParams} collection,
+    # preserving pairs it does not overwrite.
+    #
+    # @param search_params [UrlSearchParams]
+    # @param params [Hash]
+    # @param strict [Boolean] Whether to add +_strict=true+ when the
+    #   resulting collection is non-empty
+    # @return [nil]
+    # @raise [UnserializableParamError]
+    def self.update_url_search_params(search_params, params, strict: false)
+      nested_update(search_params, params, [])
+      search_params.sort!
+
+      if strict && !search_params.empty?
+        search_params.delete("_strict")
+        search_params.append("_strict", "true")
+      end
+
+      nil
+    end
+
+    def self.nested_update(search_params, params, path)
+      params.each do |key, value|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise UnserializableParamError.new(
+            key.inspect,
+            "has a name that is not a string which is unsupported"
+          )
+        end
+        key = key.to_s
+
+        if key.include?(".")
+          raise UnserializableParamError.new(
+            key,
+            'contains one or more dots "." in its name which is unsupported'
+          )
+        end
+
+        current_path = [*path, key]
+
+        if value.is_a?(Hash)
+          nested_update(search_params, value, current_path)
+          next
+        end
+
+        name = current_path.join(".")
+
+        next if value.nil?
+
+        value = value.to_s if value.is_a?(Symbol)
+
+        next if value.is_a?(String) && value.empty?
+
+        if value.is_a?(Array)
+          serialize_array(search_params, name, value)
+          next
+        end
+
+        search_params.set(name, serialize_value(name, value))
+      end
+    end
+
+    def self.serialize_array(search_params, name, values)
+      # The parser reads a single pair with an empty value as an empty array.
+      if values.empty?
+        search_params.set(name, "")
+        return
+      end
+
+      values = values.map { |value| value.is_a?(Symbol) ? value.to_s : value }
+
+      if values.length == 1 && values.first == ""
+        raise UnserializableParamError.new(
+          name,
+          "is a single element array containing the empty string which is unsupported"
+        )
+      end
+
+      if values.any? { |value| value == "" }
+        raise UnserializableParamError.new(
+          name,
+          "is an array containing the empty string which is unsupported"
+        )
+      end
+
+      if values.any? { |value| value.nil? || value.is_a?(Seam::Null) }
+        raise UnserializableParamError.new(
+          name,
+          "is an array containing null or undefined values which is unsupported"
+        )
+      end
+
+      values.each { |value| search_params.append(name, serialize_value(name, value)) }
+    end
+
+    def self.serialize_value(name, value)
+      case value
+      when Seam::Null then ""
+      when String then value
+      when true, false then value.to_s
+      when Integer then value.to_s
+      when Float then serialize_float(name, value)
+      when Time then serialize_time(value)
+      when DateTime then serialize_time(value.to_time)
+      when Date then serialize_time(Time.utc(value.year, value.month, value.day))
+      else
+        raise UnserializableParamError.new(name, "is a #{value.class}")
+      end
+    end
+
+    # Formats a float exactly like ECMAScript Number::toString.
+    def self.serialize_float(name, value)
+      raise UnserializableParamError.new(name, "is NaN") if value.nan?
+      if value.infinite?
+        raise UnserializableParamError.new(name, "is #{value.positive? ? "Infinity" : "-Infinity"}")
+      end
+      return "0" if value.zero?
+
+      digits, point = shortest_decimal(value.abs)
+      count = digits.length
+
+      formatted = if point.between?(count, 21)
+        digits + "0" * (point - count)
+      elsif point.positive? && point <= 21
+        "#{digits[0, point]}.#{digits[point..]}"
+      elsif point > -6 && point <= 0
+        "0.#{"0" * -point}#{digits}"
+      else
+        mantissa = (count == 1) ? digits : "#{digits[0]}.#{digits[1..]}"
+        exponent = point - 1
+        "#{mantissa}e#{(exponent >= 0) ? "+" : "-"}#{exponent.abs}"
+      end
+
+      value.negative? ? "-#{formatted}" : formatted
+    end
+
+    # Returns the shortest round-tripping decimal digits of a positive float
+    # and the position of the decimal point relative to the first digit.
+    def self.shortest_decimal(value)
+      repr = value.to_s
+
+      if repr.include?("e")
+        mantissa, exponent = repr.split("e")
+        integer_part, fraction_part = mantissa.split(".")
+        digits = integer_part + (fraction_part || "")
+        point = integer_part.length + exponent.to_i
+      else
+        integer_part, fraction_part = repr.split(".")
+        digits = integer_part + (fraction_part || "")
+        point = integer_part.length
+      end
+
+      leading_zeros = digits[/\A0*/].length
+      digits = digits[leading_zeros..]
+      point -= leading_zeros
+
+      [digits.sub(/0+\z/, ""), point]
+    end
+
+    # Formats a time exactly like JavaScript's Date#toISOString.
+    def self.serialize_time(time)
+      utc = time.getutc
+      year = if utc.year.between?(0, 9999)
+        format("%04d", utc.year)
+      elsif utc.year > 9999
+        format("+%06d", utc.year)
+      else
+        format("-%06d", -utc.year)
+      end
+      format(
+        "%s-%02d-%02dT%02d:%02d:%02d.%03dZ",
+        year, utc.month, utc.day, utc.hour, utc.min, utc.sec, utc.nsec / 1_000_000
+      )
+    end
+  end
+end

data/lib/seam/version.rb

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

data/lib/seam.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "seam/null"
+require_relative "seam/url_search_params"
+require_relative "seam/strict_url_search_params_serializer"
 require_relative "seam/http"
 require_relative "seam/http_without_workspace"
 require_relative "seam/webhook"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: seam
 version: !ruby/object:Gem::Version
-  version: 2.140.0
+  version: 2.141.0
 platform: ruby
 authors:
 - Seam Labs, Inc.
@@ -197,6 +197,7 @@ files:
 - lib/seam/http.rb
 - lib/seam/http_single_workspace.rb
 - lib/seam/http_without_workspace.rb
+- lib/seam/null.rb
 - lib/seam/options.rb
 - lib/seam/paginator.rb
 - lib/seam/parse_options.rb
@@ -279,7 +280,10 @@ files:
 - lib/seam/routes/user_identities_unmanaged.rb
 - lib/seam/routes/webhooks.rb
 - lib/seam/routes/workspaces.rb
+- lib/seam/strict_url_search_params_serializer.rb
 - lib/seam/token.rb
+- lib/seam/url_search_params.rb
+- lib/seam/url_search_params_serializer.rb
 - lib/seam/version.rb
 - lib/seam/wait_for_action_attempt.rb
 - lib/seam/webhook.rb