knockapi 0.6.1 → 1.0.0

data/rbi/knockapi/resources/users.rbi

@@ -0,0 +1,357 @@
+# typed: strong
+
+module Knockapi
+  module Resources
+    class Users
+      sig { returns(Knockapi::Resources::Users::Feeds) }
+      attr_reader :feeds
+
+      sig { returns(Knockapi::Resources::Users::Guides) }
+      attr_reader :guides
+
+      sig { returns(Knockapi::Resources::Users::Bulk) }
+      attr_reader :bulk
+
+      # Create or update a user with the provided identification data. When you identify
+      # an existing user, the system merges the properties you specific with what is
+      # currently set on the user, updating only the fields included in your requests.
+      sig do
+        params(
+          user_id: String,
+          avatar: T.nilable(String),
+          channel_data: T.nilable(
+            T::Hash[Symbol, T.any(Knockapi::Models::Recipients::ChannelDataRequest, Knockapi::Internal::AnyHash)]
+          ),
+          created_at: T.nilable(Time),
+          email: T.nilable(String),
+          locale: T.nilable(String),
+          name: T.nilable(String),
+          phone_number: T.nilable(String),
+          preferences: T.nilable(
+            T::Hash[Symbol, T.any(Knockapi::Models::Recipients::PreferenceSetRequest, Knockapi::Internal::AnyHash)]
+          ),
+          timezone: T.nilable(String),
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(Knockapi::Models::User)
+      end
+      def update(
+        # The ID for the user that you set when identifying them in Knock.
+        user_id,
+        # URL to the user's avatar image.
+        avatar: nil,
+        # A request to set channel data for a type of channel inline.
+        channel_data: nil,
+        # The creation date of the user from your system.
+        created_at: nil,
+        # The primary email address for the user.
+        email: nil,
+        # The locale of the user. Used for [message localization](/concepts/translations).
+        locale: nil,
+        # Display name of the user.
+        name: nil,
+        # The [E.164](https://www.twilio.com/docs/glossary/what-e164) phone number of the
+        # user (required for SMS channels).
+        phone_number: nil,
+        # Inline set preferences for a recipient, where the key is the preference set id.
+        preferences: nil,
+        # The timezone of the user. Must be a valid
+        # [tz database time zone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+        # Used for
+        # [recurring schedules](/concepts/schedules#scheduling-workflows-with-recurring-schedules-for-recipients).
+        timezone: nil,
+        request_options: {}
+      ); end
+      # Retrieve a paginated list of users in the environment. Defaults to 50 users per
+      # page.
+      sig do
+        params(
+          after: String,
+          before: String,
+          include: T::Array[Knockapi::Models::UserListParams::Include::OrSymbol],
+          page_size: Integer,
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(Knockapi::Internal::EntriesCursor[Knockapi::Models::User])
+      end
+      def list(
+        # The cursor to fetch entries after.
+        after: nil,
+        # The cursor to fetch entries before.
+        before: nil,
+        # Associated resources to include in the response.
+        include: nil,
+        # The number of items per page.
+        page_size: nil,
+        request_options: {}
+      ); end
+      # Permanently delete a user and all associated data.
+      sig { params(user_id: String, request_options: Knockapi::RequestOpts).returns(String) }
+      def delete(
+        # The ID of the user to delete.
+        user_id,
+        request_options: {}
+      ); end
+      # Retrieve a specific user by their ID.
+      sig { params(user_id: String, request_options: Knockapi::RequestOpts).returns(Knockapi::Models::User) }
+      def get(
+        # The ID of the user to retrieve.
+        user_id,
+        request_options: {}
+      ); end
+      # Retrieves the channel data for a specific user and channel ID.
+      sig do
+        params(user_id: String, channel_id: String, request_options: Knockapi::RequestOpts)
+          .returns(Knockapi::Models::Recipients::RecipientsChannelData)
+      end
+      def get_channel_data(
+        # The ID for the user that you set when identifying them in Knock.
+        user_id,
+        # The unique identifier for the channel.
+        channel_id,
+        request_options: {}
+      ); end
+      # Retrieves a specific preference set for a user identified by the preference set
+      # ID.
+      sig do
+        params(user_id: String, id: String, tenant: String, request_options: Knockapi::RequestOpts)
+          .returns(Knockapi::Models::Recipients::PreferenceSet)
+      end
+      def get_preferences(
+        # The ID for the user that you set when identifying them in Knock.
+        user_id,
+        # Unique identifier for the preference set.
+        id,
+        # The unique identifier for the tenant.
+        tenant: nil,
+        request_options: {}
+      ); end
+      # 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.
+      sig do
+        params(
+          user_id: String,
+          after: String,
+          before: String,
+          channel_id: String,
+          engagement_status: T::Array[Knockapi::Models::UserListMessagesParams::EngagementStatus::OrSymbol],
+          inserted_at: T.any(Knockapi::Models::UserListMessagesParams::InsertedAt, Knockapi::Internal::AnyHash),
+          message_ids: T::Array[String],
+          page_size: Integer,
+          source: String,
+          status: T::Array[Knockapi::Models::UserListMessagesParams::Status::OrSymbol],
+          tenant: String,
+          trigger_data: String,
+          workflow_categories: T::Array[String],
+          workflow_recipient_run_id: String,
+          workflow_run_id: String,
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(Knockapi::Internal::EntriesCursor[Knockapi::Models::Message])
+      end
+      def list_messages(
+        # The user ID to list messages for.
+        user_id,
+        # The cursor to fetch entries after.
+        after: nil,
+        # The cursor to fetch entries before.
+        before: nil,
+        # Limits the results to items with the corresponding channel ID.
+        channel_id: nil,
+        # Limits the results to messages with the given engagement status.
+        engagement_status: nil,
+        inserted_at: nil,
+        # 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.
+        page_size: nil,
+        # Limits the results to messages triggered by the given workflow key.
+        source: nil,
+        # Limits the results to messages with the given delivery status.
+        status: nil,
+        # Limits the results to items with the corresponding tenant.
+        tenant: nil,
+        # Limits the results to only messages that were generated with the given data. See
+        # [trigger data filtering](/api-reference/overview/trigger-data-filtering) for
+        # more information.
+        trigger_data: nil,
+        # Limits the results to messages related to any of the provided categories.
+        workflow_categories: nil,
+        # Limits the results to messages for a specific recipient's workflow run.
+        workflow_recipient_run_id: nil,
+        # Limits the results to messages associated with the top-level workflow run ID
+        # returned by the workflow trigger request.
+        workflow_run_id: nil,
+        request_options: {}
+      ); end
+      # Retrieves a list of all preference sets for a specific user.
+      sig do
+        params(user_id: String, request_options: Knockapi::RequestOpts)
+          .returns(T::Array[Knockapi::Models::Recipients::PreferenceSet])
+      end
+      def list_preferences(
+        # The ID for the user that you set when identifying them in Knock.
+        user_id,
+        request_options: {}
+      ); end
+      # Returns a paginated list of schedules for a specific user, in descending order.
+      sig do
+        params(
+          user_id: String,
+          after: String,
+          before: String,
+          page_size: Integer,
+          tenant: String,
+          workflow: String,
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(Knockapi::Internal::EntriesCursor[Knockapi::Models::Schedule])
+      end
+      def list_schedules(
+        # The user ID to list schedules for.
+        user_id,
+        # The cursor to fetch entries after.
+        after: nil,
+        # The cursor to fetch entries before.
+        before: nil,
+        # The number of items per page.
+        page_size: nil,
+        # The tenant ID to filter schedules for.
+        tenant: nil,
+        # The workflow key to filter schedules for.
+        workflow: nil,
+        request_options: {}
+      ); end
+      # Retrieves a paginated list of subscriptions for a specific user, in descending
+      # order.
+      sig do
+        params(
+          user_id: String,
+          after: String,
+          before: String,
+          include: T::Array[Knockapi::Models::UserListSubscriptionsParams::Include::OrSymbol],
+          objects: T::Array[String],
+          page_size: Integer,
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(Knockapi::Internal::EntriesCursor[Knockapi::Models::Recipients::Subscription])
+      end
+      def list_subscriptions(
+        # The user ID to list subscriptions for.
+        user_id,
+        # The cursor to fetch entries after.
+        after: nil,
+        # The cursor to fetch entries before.
+        before: nil,
+        # Associated resources to include in the response.
+        include: nil,
+        # Only returns subscriptions for the specified object GIDs.
+        objects: nil,
+        # The number of items per page.
+        page_size: nil,
+        request_options: {}
+      ); end
+      # Merge two users together, where the user specified with the `from_user_id` param
+      # will be merged into the user specified by `user_id`.
+      sig do
+        params(user_id: String, from_user_id: String, request_options: Knockapi::RequestOpts)
+          .returns(Knockapi::Models::User)
+      end
+      def merge(
+        # The id of the user to merge into.
+        user_id,
+        # The user ID to merge from.
+        from_user_id:,
+        request_options: {}
+      ); end
+      # Updates or creates channel data for a specific user and channel ID.
+      sig do
+        params(
+          user_id: String,
+          channel_id: String,
+          data: T.any(
+            Knockapi::Models::Recipients::PushChannelData,
+            Knockapi::Internal::AnyHash,
+            Knockapi::Models::Recipients::OneSignalChannelData,
+            Knockapi::Models::Recipients::SlackChannelData,
+            Knockapi::Models::Recipients::MsTeamsChannelData,
+            Knockapi::Models::Recipients::DiscordChannelData
+          ),
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(Knockapi::Models::Recipients::RecipientsChannelData)
+      end
+      def set_channel_data(
+        # The ID for the user that you set when identifying them in Knock.
+        user_id,
+        # The unique identifier for the channel.
+        channel_id,
+        # Channel data for a given channel type.
+        data:,
+        request_options: {}
+      ); end
+      # Updates a complete preference set for a user. This is a destructive operation
+      # that will replace the existing preference set for the user.
+      sig do
+        params(
+          user_id: String,
+          id: String,
+          categories: T.nilable(
+            T::Hash[
+              Symbol,
+              T.any(
+                T::Boolean,
+                Knockapi::Models::Recipients::PreferenceSetRequest::Category::PreferenceSetWorkflowCategorySettingObject,
+                Knockapi::Internal::AnyHash
+              )
+            ]
+          ),
+          channel_types: T.nilable(T.any(Knockapi::Models::Recipients::PreferenceSetChannelTypes, Knockapi::Internal::AnyHash)),
+          workflows: T.nilable(
+            T::Hash[
+              Symbol,
+              T.any(
+                T::Boolean,
+                Knockapi::Models::Recipients::PreferenceSetRequest::Workflow::PreferenceSetWorkflowCategorySettingObject,
+                Knockapi::Internal::AnyHash
+              )
+            ]
+          ),
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(Knockapi::Models::Recipients::PreferenceSet)
+      end
+      def set_preferences(
+        # The ID for the user that you set when identifying them in Knock.
+        user_id,
+        # Unique identifier for the preference set.
+        id,
+        # An object where the key is the category and the values are the preference
+        # settings for that category.
+        categories: nil,
+        # Channel type preferences.
+        channel_types: nil,
+        # An object where the key is the workflow key and the values are the preference
+        # settings for that workflow.
+        workflows: nil,
+        request_options: {}
+      ); end
+      # Deletes channel data for a specific user and channel ID.
+      sig do
+        params(user_id: String, channel_id: String, request_options: Knockapi::RequestOpts).returns(String)
+      end
+      def unset_channel_data(
+        # The ID for the user that you set when identifying them in Knock.
+        user_id,
+        # The unique identifier for the channel.
+        channel_id,
+        request_options: {}
+      ); end
+      # @api private
+      sig { params(client: Knockapi::Client).returns(T.attached_class) }
+      def self.new(client:); end
+    end
+  end
+end

data/rbi/knockapi/resources/workflows.rbi

@@ -0,0 +1,92 @@
+# typed: strong
+
+module Knockapi
+  module Resources
+    class Workflows
+      # When invoked for a workflow using a specific workflow key and cancellation key,
+      # will cancel any queued workflow runs associated with that key/cancellation key
+      # pair. Can optionally be provided one or more recipients to scope the request to.
+      sig do
+        params(
+          key: String,
+          cancellation_key: String,
+          recipients: T.nilable(
+            T::Array[T.any(String, Knockapi::Models::RecipientReference::ObjectReference, Knockapi::Internal::AnyHash)]
+          ),
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(String)
+      end
+      def cancel(
+        # The key of the workflow to cancel.
+        key,
+        # An optional key that is used to reference a specific workflow trigger request
+        # when issuing a [workflow cancellation](/send-notifications/canceling-workflows)
+        # request. Must be provided while triggering a workflow in order to enable
+        # subsequent cancellation. Should be unique across trigger requests to avoid
+        # unintentional cancellations.
+        cancellation_key:,
+        # A list of recipients to cancel the notification for. If omitted, cancels for all
+        # recipients associated with the cancellation key.
+        recipients: nil,
+        request_options: {}
+      ); end
+      # Trigger a workflow (specified by the key) to run for the given recipients, using
+      # the parameters provided. Returns an identifier for the workflow run request. All
+      # workflow runs are executed asynchronously. This endpoint also handles
+      # [inline identifications](/managing-recipients/identifying-recipients#inline-identifying-recipients)
+      # for the `actor`, `recipient`, and `tenant` fields.
+      sig do
+        params(
+          key: String,
+          recipients: T::Array[
+            T.any(
+              String,
+              Knockapi::Models::InlineIdentifyUserRequest,
+              Knockapi::Internal::AnyHash,
+              Knockapi::Models::InlineObjectRequest
+            )
+          ],
+          actor: T.nilable(
+            T.any(
+              String,
+              Knockapi::Models::InlineIdentifyUserRequest,
+              Knockapi::Internal::AnyHash,
+              Knockapi::Models::InlineObjectRequest
+            )
+          ),
+          cancellation_key: T.nilable(String),
+          data: T.nilable(T::Hash[Symbol, T.anything]),
+          tenant: T.nilable(T.any(String, Knockapi::Models::TenantRequest, Knockapi::Internal::AnyHash)),
+          request_options: Knockapi::RequestOpts
+        )
+          .returns(Knockapi::Models::WorkflowTriggerResponse)
+      end
+      def trigger(
+        # Key of the workflow to trigger.
+        key,
+        # The recipients to trigger the workflow for. Can inline identify users, objects,
+        # or use a list of user IDs. Limited to 1,000 recipients.
+        recipients:,
+        # Specifies a recipient in a request. This can either be a user identifier
+        # (string), an inline user request (object), or an inline object request, which is
+        # determined by the presence of a `collection` property.
+        actor: nil,
+        # An optional key that is used to reference a specific workflow trigger request
+        # when issuing a [workflow cancellation](/send-notifications/canceling-workflows)
+        # request. Must be provided while triggering a workflow in order to enable
+        # subsequent cancellation. Should be unique across trigger requests to avoid
+        # unintentional cancellations.
+        cancellation_key: nil,
+        # An optional map of data to pass into the workflow execution.
+        data: nil,
+        # An request to set a tenant inline.
+        tenant: nil,
+        request_options: {}
+      ); end
+      # @api private
+      sig { params(client: Knockapi::Client).returns(T.attached_class) }
+      def self.new(client:); end
+    end
+  end
+end

data/rbi/knockapi/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module Knockapi
+  VERSION = T.let(T.unsafe(nil), String)
+end

data/sig/knockapi/client.rbs

@@ -0,0 +1,50 @@
+module Knockapi
+  class Client < Knockapi::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    attr_reader api_key: String
+
+    attr_reader shared: Knockapi::Resources::Shared
+
+    attr_reader recipients: Knockapi::Resources::Recipients
+
+    attr_reader users: Knockapi::Resources::Users
+
+    attr_reader objects: Knockapi::Resources::Objects
+
+    attr_reader tenants: Knockapi::Resources::Tenants
+
+    attr_reader bulk_operations: Knockapi::Resources::BulkOperations
+
+    attr_reader messages: Knockapi::Resources::Messages
+
+    attr_reader providers: Knockapi::Resources::Providers
+
+    attr_reader integrations: Knockapi::Resources::Integrations
+
+    attr_reader workflows: Knockapi::Resources::Workflows
+
+    attr_reader schedules: Knockapi::Resources::Schedules
+
+    attr_reader channels: Knockapi::Resources::Channels
+
+    attr_reader audiences: Knockapi::Resources::Audiences
+
+    private def auth_headers: -> ::Hash[String, String]
+
+    def initialize: (
+      ?api_key: String?,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end

data/sig/knockapi/errors.rbs

@@ -0,0 +1,101 @@
+module Knockapi
+  module Errors
+    class Error < StandardError
+      attr_accessor cause: StandardError?
+    end
+
+    class ConversionError < Knockapi::Errors::Error
+    end
+
+    class APIError < Knockapi::Errors::Error
+      attr_accessor url: URI::Generic
+
+      attr_accessor status: Integer?
+
+      attr_accessor body: top?
+
+      def initialize: (
+        url: URI::Generic,
+        ?status: Integer?,
+        ?body: Object?,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIConnectionError < Knockapi::Errors::APIError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APITimeoutError < Knockapi::Errors::APIConnectionError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIStatusError < Knockapi::Errors::APIError
+      def self.for: (
+        url: URI::Generic,
+        status: Integer,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> instance
+
+      def initialize: (
+        url: URI::Generic,
+        status: Integer,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class BadRequestError < Knockapi::Errors::APIStatusError
+      HTTP_STATUS: 400
+    end
+
+    class AuthenticationError < Knockapi::Errors::APIStatusError
+      HTTP_STATUS: 401
+    end
+
+    class PermissionDeniedError < Knockapi::Errors::APIStatusError
+      HTTP_STATUS: 403
+    end
+
+    class NotFoundError < Knockapi::Errors::APIStatusError
+      HTTP_STATUS: 404
+    end
+
+    class ConflictError < Knockapi::Errors::APIStatusError
+      HTTP_STATUS: 409
+    end
+
+    class UnprocessableEntityError < Knockapi::Errors::APIStatusError
+      HTTP_STATUS: 422
+    end
+
+    class RateLimitError < Knockapi::Errors::APIStatusError
+      HTTP_STATUS: 429
+    end
+
+    class InternalServerError < Knockapi::Errors::APIStatusError
+      HTTP_STATUS: Range[Integer]
+    end
+  end
+end

data/sig/knockapi/file_part.rbs

@@ -0,0 +1,21 @@
+module Knockapi
+  class FilePart
+    attr_reader content: Pathname | StringIO | IO | String
+
+    attr_reader content_type: String?
+
+    attr_reader filename: String?
+
+    private def read: -> String
+
+    def to_json: (*top a) -> String
+
+    def to_yaml: (*top a) -> String
+
+    def initialize: (
+      Pathname | StringIO | IO | String content,
+      ?filename: String?,
+      ?content_type: String?
+    ) -> void
+  end
+end

data/sig/knockapi/internal/entries_cursor.rbs

@@ -0,0 +1,24 @@
+module Knockapi
+  module Internal
+    class EntriesCursor[Elem]
+      include Knockapi::Internal::Type::BasePage[Elem]
+
+      attr_accessor entries: ::Array[Elem]?
+
+      attr_accessor page_info: PageInfo
+
+      def inspect: -> String
+
+      type page_info = { after: String }
+      class PageInfo < Knockapi::Internal::Type::BaseModel
+        attr_reader after: String?
+
+        def after=: (String) -> String
+
+        def initialize: (?after: String) -> void
+
+        def to_hash: -> page_info
+      end
+    end
+  end
+end

data/sig/knockapi/internal/items_cursor.rbs

@@ -0,0 +1,24 @@
+module Knockapi
+  module Internal
+    class ItemsCursor[Elem]
+      include Knockapi::Internal::Type::BasePage[Elem]
+
+      attr_accessor items: ::Array[Elem]?
+
+      attr_accessor page_info: PageInfo
+
+      def inspect: -> String
+
+      type page_info = { after: String }
+      class PageInfo < Knockapi::Internal::Type::BaseModel
+        attr_reader after: String?
+
+        def after=: (String) -> String
+
+        def initialize: (?after: String) -> void
+
+        def to_hash: -> page_info
+      end
+    end
+  end
+end

data/sig/knockapi/internal/ms_teams_pagination.rbs

@@ -0,0 +1,13 @@
+module Knockapi
+  module Internal
+    class MsTeamsPagination[Elem]
+      include Knockapi::Internal::Type::BasePage[Elem]
+
+      attr_accessor skip_token: String
+
+      attr_accessor ms_teams_teams: ::Array[Elem]?
+
+      def inspect: -> String
+    end
+  end
+end