knockapi 1.8.0 → 1.9.0

data/lib/knockapi/resources/tenants.rb

@@ -16,7 +16,7 @@ module Knockapi
       #
       # @param name [String] Filter tenants by name.
       #
-      # @param page_size [Integer] The number of items per page.
+      # @param page_size [Integer] The number of items per page (defaults to 50).
       #
       # @param tenant_id [String] Filter tenants by ID.
       #

data/lib/knockapi/resources/users/feeds.rb

@@ -8,7 +8,7 @@ module Knockapi
         #
         # @overload get_settings(user_id, id, request_options: {})
         #
-        # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+        # @param user_id [String] The unique identifier of the user.
         #
         # @param id [String] The unique identifier for the channel.
         #
@@ -26,12 +26,24 @@ module Knockapi
           )
         end
 
-        # Returns a paginated list of feed items for a user, including metadata about the
-        # feed.
+        # Returns a paginated list of feed items for a user in reverse chronological
+        # order, including metadata about the feed. If the user has not yet been
+        # identified within Knock, an empty feed will be returned.
+        #
+        # You can customize the response using
+        # [response filters](/integrations/in-app/knock#customizing-api-response-content)
+        # to exclude or only include specific properties on your resources.
+        #
+        # **Notes:**
+        #
+        # - When making this call from a client-side environment, use your publishable key
+        #   along with a user token.
+        # - This endpoint’s rate limit is always scoped per-user and per-environment. This
+        #   is true even for requests made without a signed user token.
         #
         # @overload list_items(user_id, id, after: nil, archived: nil, before: nil, has_tenant: nil, page_size: nil, source: nil, status: nil, tenant: nil, trigger_data: nil, workflow_categories: nil, request_options: {})
         #
-        # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+        # @param user_id [String] The unique identifier of the user.
         #
         # @param id [String] The unique identifier for the channel.
         #
@@ -43,9 +55,9 @@ module Knockapi
         #
         # @param has_tenant [Boolean] Whether the feed items have a tenant.
         #
-        # @param page_size [Integer] The number of items per page.
+        # @param page_size [Integer] The number of items per page (defaults to 50).
         #
-        # @param source [String] The source of the feed items.
+        # @param source [String] The workflow key associated with the message in the feed.
         #
         # @param status [Symbol, Knockapi::Models::Users::FeedListItemsParams::Status] The status of the feed items.
         #

data/lib/knockapi/resources/users/guides.rb

@@ -8,7 +8,7 @@ module Knockapi
         #
         # @overload get_channel(user_id, channel_id, data: nil, tenant: nil, type: nil, request_options: {})
         #
-        # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+        # @param user_id [String] The unique identifier of the user.
         #
         # @param channel_id [String] The unique identifier for the channel.
         #
@@ -39,7 +39,7 @@ module Knockapi
         #
         # @overload mark_message_as_archived(user_id, message_id, channel_id:, guide_id:, guide_key:, guide_step_ref:, content: nil, data: nil, is_final: nil, metadata: nil, tenant: nil, request_options: {})
         #
-        # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+        # @param user_id [String] The unique identifier of the user.
         #
         # @param message_id [String] The unique identifier for the message.
         #
@@ -82,7 +82,7 @@ module Knockapi
         #
         # @overload mark_message_as_interacted(user_id, message_id, channel_id:, guide_id:, guide_key:, guide_step_ref:, content: nil, data: nil, is_final: nil, metadata: nil, tenant: nil, request_options: {})
         #
-        # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+        # @param user_id [String] The unique identifier of the user.
         #
         # @param message_id [String] The unique identifier for the message.
         #
@@ -125,7 +125,7 @@ module Knockapi
         #
         # @overload mark_message_as_seen(user_id, message_id, channel_id:, guide_id:, guide_key:, guide_step_ref:, content: nil, data: nil, is_final: nil, metadata: nil, tenant: nil, request_options: {})
         #
-        # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+        # @param user_id [String] The unique identifier of the user.
         #
         # @param message_id [String] The unique identifier for the message.
         #

data/lib/knockapi/resources/users.rb

@@ -21,9 +21,9 @@ module Knockapi
       #
       # @overload update(user_id, avatar: nil, channel_data: nil, created_at: nil, email: nil, locale: nil, name: nil, phone_number: nil, preferences: nil, timezone: nil, request_options: {})
       #
-      # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+      # @param user_id [String] The unique identifier of the user.
       #
-      # @param avatar [String, nil] URL to the user's avatar image.
+      # @param avatar [String, nil] A URL for the avatar of the user.
       #
       # @param channel_data [Hash{Symbol=>Knockapi::Models::Recipients::PushChannelData, Knockapi::Models::Recipients::OneSignalChannelData, Knockapi::Models::Recipients::SlackChannelData, Knockapi::Models::Recipients::MsTeamsChannelData, Knockapi::Models::Recipients::DiscordChannelData}, nil] A request to set channel data for a type of channel inline.
       #
@@ -68,7 +68,7 @@ module Knockapi
       #
       # @param include [Array<Symbol, Knockapi::Models::UserListParams::Include>] Associated resources to include in the response.
       #
-      # @param page_size [Integer] The number of items per page.
+      # @param page_size [Integer] The number of items per page (defaults to 50).
       #
       # @param request_options [Knockapi::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -131,7 +131,7 @@ module Knockapi
       #
       # @overload get_channel_data(user_id, channel_id, request_options: {})
       #
-      # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+      # @param user_id [String] The unique identifier of the user.
       #
       # @param channel_id [String] The unique identifier for the channel.
       #
@@ -154,7 +154,7 @@ module Knockapi
       #
       # @overload get_preferences(user_id, id, tenant: nil, request_options: {})
       #
-      # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+      # @param user_id [String] The unique identifier of the user.
       #
       # @param id [String] Unique identifier for the preference set.
       #
@@ -179,9 +179,9 @@ module Knockapi
       # Some parameter documentations has been truncated, see
       # {Knockapi::Models::UserListMessagesParams} for more details.
       #
-      # Returns a paginated list of messages for a specific user. Allows filtering by
-      # message status and provides various sorting options. Messages outside the
-      # account's retention window will not be included in the results.
+      # Returns a paginated list of messages for a specific user. Messages are sorted
+      # with the most recent ones appearing first. Messages outside the account's
+      # retention window will not be included in the results.
       #
       # @overload list_messages(user_id, after: nil, before: nil, channel_id: nil, engagement_status: nil, inserted_at: nil, message_ids: nil, page_size: nil, source: nil, status: nil, tenant: nil, trigger_data: nil, workflow_categories: nil, workflow_recipient_run_id: nil, workflow_run_id: nil, request_options: {})
       #
@@ -199,7 +199,7 @@ module Knockapi
       #
       # @param message_ids [Array<String>] Limits the results to only the message IDs given (max 50). Note: when using this
       #
-      # @param page_size [Integer] The number of items per page.
+      # @param page_size [Integer] The number of items per page (defaults to 50).
       #
       # @param source [String] Limits the results to messages triggered by the given workflow key.
       #
@@ -236,7 +236,7 @@ module Knockapi
       #
       # @overload list_preferences(user_id, request_options: {})
       #
-      # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+      # @param user_id [String] The unique identifier of the user.
       #
       # @param request_options [Knockapi::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -262,7 +262,7 @@ module Knockapi
       #
       # @param before [String] The cursor to fetch entries before.
       #
-      # @param page_size [Integer] The number of items per page.
+      # @param page_size [Integer] The number of items per page (defaults to 50).
       #
       # @param tenant [String] The tenant ID to filter schedules for.
       #
@@ -300,7 +300,7 @@ module Knockapi
       #
       # @param objects [Array<String, Knockapi::Models::RecipientReference::ObjectReference>] Only returns subscriptions for the specified object references.
       #
-      # @param page_size [Integer] The number of items per page.
+      # @param page_size [Integer] The number of items per page (defaults to 50).
       #
       # @param request_options [Knockapi::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -350,7 +350,7 @@ module Knockapi
       #
       # @overload set_channel_data(user_id, channel_id, data:, request_options: {})
       #
-      # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+      # @param user_id [String] The unique identifier of the user.
       #
       # @param channel_id [String] The unique identifier for the channel.
       #
@@ -380,7 +380,7 @@ module Knockapi
       #
       # @overload set_preferences(user_id, id, categories: nil, channel_types: nil, workflows: nil, request_options: {})
       #
-      # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+      # @param user_id [String] The unique identifier of the user.
       #
       # @param id [String] Unique identifier for the preference set.
       #
@@ -410,7 +410,7 @@ module Knockapi
       #
       # @overload unset_channel_data(user_id, channel_id, request_options: {})
       #
-      # @param user_id [String] The ID for the user that you set when identifying them in Knock.
+      # @param user_id [String] The unique identifier of the user.
       #
       # @param channel_id [String] The unique identifier for the channel.
       #

data/lib/knockapi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Knockapi
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end

data/rbi/knockapi/errors.rbi

@@ -8,6 +8,22 @@ module Knockapi
     end
 
     class ConversionError < Knockapi::Errors::Error
+      sig { returns(T.nilable(StandardError)) }
+      def cause
+      end
+
+      # @api private
+      sig do
+        params(
+          on: T::Class[StandardError],
+          method: Symbol,
+          target: T.anything,
+          value: T.anything,
+          cause: T.nilable(StandardError)
+        ).returns(T.attached_class)
+      end
+      def self.new(on:, method:, target:, value:, cause: nil)
+      end
     end
 
     class APIError < Knockapi::Errors::Error

data/rbi/knockapi/internal/type/boolean.rbi

@@ -22,6 +22,8 @@ module Knockapi
 
         class << self
           # @api private
+          #
+          # Coerce value to Boolean if possible, otherwise return the original value.
           sig do
             override
               .params(

data/rbi/knockapi/internal/type/converter.rbi

@@ -15,12 +15,14 @@ module Knockapi
         CoerceState =
           T.type_alias do
             {
-              strictness: T.any(T::Boolean, Symbol),
+              translate_names: T::Boolean,
+              strictness: T::Boolean,
               exactness: {
                 yes: Integer,
                 no: Integer,
                 maybe: Integer
               },
+              error: T::Class[StandardError],
               branched: Integer
             }
           end
@@ -88,6 +90,15 @@ module Knockapi
           def self.type_info(spec)
           end
 
+          # @api private
+          sig do
+            params(translate_names: T::Boolean).returns(
+              Knockapi::Internal::Type::Converter::CoerceState
+            )
+          end
+          def self.new_coerce_state(translate_names: true)
+          end
+
           # @api private
           #
           # Based on `target`, transform `value` into `target`, to the extent possible:
@@ -109,14 +120,11 @@ module Knockapi
           def self.coerce(
             target,
             value,
-            # The `strictness` is one of `true`, `false`, or `:strong`. This informs the
-            # coercion strategy when we have to decide between multiple possible conversion
-            # targets:
+            # The `strictness` is one of `true`, `false`. This informs the coercion strategy
+            # when we have to decide between multiple possible conversion targets:
             #
             # - `true`: the conversion must be exact, with minimum coercion.
             # - `false`: the conversion can be approximate, with some coercion.
-            # - `:strong`: the conversion must be exact, with no coercion, and raise an error
-            #   if not possible.
             #
             # The `exactness` is `Hash` with keys being one of `yes`, `no`, or `maybe`. For
             # any given conversion attempt, the exactness will be updated based on how closely
@@ -128,15 +136,7 @@ module Knockapi
             # - `no`: the value cannot be converted to the target type.
             #
             # See implementation below for more details.
-            state: {
-              strictness: true,
-              exactness: {
-                yes: 0,
-                no: 0,
-                maybe: 0
-              },
-              branched: 0
-            }
+            state: Knockapi::Internal::Type::Converter.new_coerce_state
           )
           end
 

data/rbi/knockapi/internal/type/union.rbi

@@ -78,6 +78,11 @@ module Knockapi
         end
 
         # @api private
+        #
+        # Tries to efficiently coerce the given value to one of the known variants.
+        #
+        # If the value cannot match any of the known variants, the coercion is considered
+        # non-viable and returns the original value.
         sig do
           override
             .params(

data/rbi/knockapi/internal/type/unknown.rbi

@@ -22,6 +22,8 @@ module Knockapi
 
         class << self
           # @api private
+          #
+          # No coercion needed for Unknown type.
           sig do
             override
               .params(

data/rbi/knockapi/models/audience_add_members_params.rbi

@@ -98,7 +98,7 @@ module Knockapi
               )
             end
 
-          # The ID for the user that you set when identifying them in Knock.
+          # The unique identifier of the user.
           sig { returns(T.nilable(String)) }
           attr_reader :id
 
@@ -108,7 +108,7 @@ module Knockapi
           # An object containing the user's ID.
           sig { params(id: String).returns(T.attached_class) }
           def self.new(
-            # The ID for the user that you set when identifying them in Knock.
+            # The unique identifier of the user.
             id: nil
           )
           end

data/rbi/knockapi/models/audience_member.rbi

@@ -25,7 +25,7 @@ module Knockapi
       sig { params(user: Knockapi::User::OrHash).void }
       attr_writer :user
 
-      # The ID for the user that you set when identifying them in Knock.
+      # The unique identifier of the user.
       sig { returns(String) }
       attr_accessor :user_id
 
@@ -52,7 +52,7 @@ module Knockapi
         # receive notifications through Knock. Users are the most common recipients of
         # notifications and are always referenced by your internal identifier.
         user:,
-        # The ID for the user that you set when identifying them in Knock.
+        # The unique identifier of the user.
         user_id:,
         # The unique identifier for the tenant.
         tenant: nil

data/rbi/knockapi/models/audience_remove_members_params.rbi

@@ -102,7 +102,7 @@ module Knockapi
               )
             end
 
-          # The ID for the user that you set when identifying them in Knock.
+          # The unique identifier of the user.
           sig { returns(T.nilable(String)) }
           attr_reader :id
 
@@ -112,7 +112,7 @@ module Knockapi
           # An object containing the user's ID.
           sig { params(id: String).returns(T.attached_class) }
           def self.new(
-            # The ID for the user that you set when identifying them in Knock.
+            # The unique identifier of the user.
             id: nil
           )
           end

data/rbi/knockapi/models/identify_user_request.rbi

@@ -8,7 +8,7 @@ module Knockapi
           T.any(Knockapi::IdentifyUserRequest, Knockapi::Internal::AnyHash)
         end
 
-      # URL to the user's avatar image.
+      # A URL for the avatar of the user.
       sig { returns(T.nilable(String)) }
       attr_accessor :avatar
 
@@ -104,7 +104,7 @@ module Knockapi
         ).returns(T.attached_class)
       end
       def self.new(
-        # URL to the user's avatar image.
+        # A URL for the avatar of the user.
         avatar: nil,
         # A request to set channel data for a type of channel inline.
         channel_data: nil,

data/rbi/knockapi/models/inline_identify_user_request.rbi

@@ -11,11 +11,11 @@ module Knockapi
           )
         end
 
-      # The ID for the user that you set when identifying them in Knock.
+      # The unique identifier of the user.
       sig { returns(String) }
       attr_accessor :id
 
-      # URL to the user's avatar image.
+      # A URL for the avatar of the user.
       sig { returns(T.nilable(String)) }
       attr_accessor :avatar
 
@@ -113,9 +113,9 @@ module Knockapi
         ).returns(T.attached_class)
       end
       def self.new(
-        # The ID for the user that you set when identifying them in Knock.
+        # The unique identifier of the user.
         id:,
-        # URL to the user's avatar image.
+        # A URL for the avatar of the user.
         avatar: nil,
         # A request to set channel data for a type of channel inline.
         channel_data: nil,

data/rbi/knockapi/models/message.rbi

@@ -328,13 +328,18 @@ module Knockapi
         sig { returns(String) }
         attr_accessor :version_id
 
+        # The step reference for the step in the workflow that generated the message
+        sig { returns(T.nilable(String)) }
+        attr_accessor :step_ref
+
         # The workflow that triggered the message.
         sig do
           params(
             _typename: String,
             categories: T::Array[String],
             key: String,
-            version_id: String
+            version_id: String,
+            step_ref: T.nilable(String)
           ).returns(T.attached_class)
         end
         def self.new(
@@ -344,7 +349,9 @@ module Knockapi
           # The key of the workflow that triggered the message.
           key:,
           # The ID of the version of the workflow that triggered the message.
-          version_id:
+          version_id:,
+          # The step reference for the step in the workflow that generated the message
+          step_ref: nil
         )
         end
 
@@ -354,7 +361,8 @@ module Knockapi
               _typename: String,
               categories: T::Array[String],
               key: String,
-              version_id: String
+              version_id: String,
+              step_ref: T.nilable(String)
             }
           )
         end

data/rbi/knockapi/models/message_get_content_response.rbi

@@ -258,7 +258,7 @@ module Knockapi
           sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
           attr_accessor :data
 
-          # The content of a push notification.
+          # Push channel data.
           sig do
             params(
               token: String,

data/rbi/knockapi/models/message_list_activities_params.rbi

@@ -28,7 +28,7 @@ module Knockapi
       sig { params(before: String).void }
       attr_writer :before
 
-      # The number of items per page.
+      # The number of items per page (defaults to 50).
       sig { returns(T.nilable(Integer)) }
       attr_reader :page_size
 
@@ -56,7 +56,7 @@ module Knockapi
         after: nil,
         # The cursor to fetch entries before.
         before: nil,
-        # The number of items per page.
+        # The number of items per page (defaults to 50).
         page_size: nil,
         # The trigger data to filter activities by.
         trigger_data: nil,

data/rbi/knockapi/models/message_list_delivery_logs_params.rbi

@@ -28,7 +28,7 @@ module Knockapi
       sig { params(before: String).void }
       attr_writer :before
 
-      # The number of items per page.
+      # The number of items per page (defaults to 50).
       sig { returns(T.nilable(Integer)) }
       attr_reader :page_size
 
@@ -48,7 +48,7 @@ module Knockapi
         after: nil,
         # The cursor to fetch entries before.
         before: nil,
-        # The number of items per page.
+        # The number of items per page (defaults to 50).
         page_size: nil,
         request_options: {}
       )

data/rbi/knockapi/models/message_list_events_params.rbi

@@ -25,7 +25,7 @@ module Knockapi
       sig { params(before: String).void }
       attr_writer :before
 
-      # The number of items per page.
+      # The number of items per page (defaults to 50).
       sig { returns(T.nilable(Integer)) }
       attr_reader :page_size
 
@@ -45,7 +45,7 @@ module Knockapi
         after: nil,
         # The cursor to fetch entries before.
         before: nil,
-        # The number of items per page.
+        # The number of items per page (defaults to 50).
         page_size: nil,
         request_options: {}
       )

data/rbi/knockapi/models/message_list_params.rbi

@@ -68,7 +68,7 @@ module Knockapi
       sig { params(message_ids: T::Array[String]).void }
       attr_writer :message_ids
 
-      # The number of items per page.
+      # The number of items per page (defaults to 50).
       sig { returns(T.nilable(Integer)) }
       attr_reader :page_size
 
@@ -168,7 +168,7 @@ module Knockapi
         # Limits the results to only the message IDs given (max 50). Note: when using this
         # option, the results will be subject to any other filters applied to the query.
         message_ids: nil,
-        # The number of items per page.
+        # The number of items per page (defaults to 50).
         page_size: nil,
         # Limits the results to messages triggered by the given workflow key.
         source: nil,

data/rbi/knockapi/models/messages/batch_get_content_response.rbi

@@ -262,7 +262,7 @@ module Knockapi
             sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
             attr_accessor :data
 
-            # The content of a push notification.
+            # Push channel data.
             sig do
               params(
                 token: String,

data/rbi/knockapi/models/object_list_messages_params.rbi

@@ -72,7 +72,7 @@ module Knockapi
       sig { params(message_ids: T::Array[String]).void }
       attr_writer :message_ids
 
-      # The number of items per page.
+      # The number of items per page (defaults to 50).
       sig { returns(T.nilable(Integer)) }
       attr_reader :page_size
 
@@ -177,7 +177,7 @@ module Knockapi
         # Limits the results to only the message IDs given (max 50). Note: when using this
         # option, the results will be subject to any other filters applied to the query.
         message_ids: nil,
-        # The number of items per page.
+        # The number of items per page (defaults to 50).
         page_size: nil,
         # Limits the results to messages triggered by the given workflow key.
         source: nil,

data/rbi/knockapi/models/object_list_params.rbi

@@ -40,7 +40,7 @@ module Knockapi
       end
       attr_writer :include
 
-      # The number of items per page.
+      # The number of items per page (defaults to 50).
       sig { returns(T.nilable(Integer)) }
       attr_reader :page_size
 
@@ -63,7 +63,7 @@ module Knockapi
         before: nil,
         # Includes preferences of the objects in the response.
         include: nil,
-        # The number of items per page.
+        # The number of items per page (defaults to 50).
         page_size: nil,
         request_options: {}
       )

data/rbi/knockapi/models/object_list_schedules_params.rbi

@@ -28,7 +28,7 @@ module Knockapi
       sig { params(before: String).void }
       attr_writer :before
 
-      # The number of items per page.
+      # The number of items per page (defaults to 50).
       sig { returns(T.nilable(Integer)) }
       attr_reader :page_size
 
@@ -64,7 +64,7 @@ module Knockapi
         after: nil,
         # The cursor to fetch entries before.
         before: nil,
-        # The number of items per page.
+        # The number of items per page (defaults to 50).
         page_size: nil,
         # Filter schedules by tenant id.
         tenant: nil,

data/rbi/knockapi/models/object_list_subscriptions_params.rbi

@@ -79,7 +79,7 @@ module Knockapi
       end
       attr_writer :objects
 
-      # The number of items per page.
+      # The number of items per page (defaults to 50).
       sig { returns(T.nilable(Integer)) }
       attr_reader :page_size
 
@@ -146,7 +146,7 @@ module Knockapi
         mode: nil,
         # Objects to filter by (only used if mode is `recipient`).
         objects: nil,
-        # The number of items per page.
+        # The number of items per page (defaults to 50).
         page_size: nil,
         # Recipients to filter by (only used if mode is `object`).
         recipients: nil,