notiflows 0.0.1

data/lib/notiflows/resources/topics/subscriptions.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Notiflows
+  module Resources
+    class Topics
+      class Subscriptions
+        # Retrieve all users subscribed to a specific topic.
+        #
+        # @overload list(topic_id, after: nil, before: nil, created_after: nil, created_before: nil, limit: nil, request_options: {})
+        #
+        # @param topic_id [String] Topic name
+        #
+        # @param after [String] Cursor for fetching the next page
+        #
+        # @param before [String] Cursor for fetching the previous page
+        #
+        # @param created_after [String] Filter by created after (ISO 8601 datetime)
+        #
+        # @param created_before [String] Filter by created before (ISO 8601 datetime)
+        #
+        # @param limit [Integer] Number of items per page (default: 25, max: 1000)
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Internal::CursorPage<Notiflows::Models::Users::Subscription>]
+        #
+        # @see Notiflows::Models::Topics::SubscriptionListParams
+        def list(topic_id, params = {})
+          parsed, options = ::Notiflows::Topics::SubscriptionListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["topics/%1$s/subscriptions", topic_id],
+            query: parsed,
+            page: ::Notiflows::Internal::CursorPage,
+            model: ::Notiflows::Users::Subscription,
+            options: options
+          )
+        end
+
+        # Subscribe multiple users to a topic in a single request.
+        #
+        # - Topics are created automatically if they don't exist.
+        # - If a user is already subscribed, they are included in the `successful`
+        #   response.
+        # - Returns `207 Multi-Status` if some subscriptions failed.
+        #
+        # @overload subscribe_bulk(topic_id, user_external_ids:, request_options: {})
+        #
+        # @param topic_id [String] Topic name
+        #
+        # @param user_external_ids [Array<String>] List of user external IDs to subscribe/unsubscribe
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Models::Topics::BulkOperationResponse]
+        #
+        # @see Notiflows::Models::Topics::SubscriptionSubscribeBulkParams
+        def subscribe_bulk(topic_id, params)
+          parsed, options = ::Notiflows::Topics::SubscriptionSubscribeBulkParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["topics/%1$s/subscriptions", topic_id],
+            body: parsed,
+            model: ::Notiflows::Topics::BulkOperationResponse,
+            options: options
+          )
+        end
+
+        # Unsubscribe multiple users from a topic in a single request.
+        #
+        # - Returns `207 Multi-Status` if some unsubscriptions failed (e.g., user not
+        #   found).
+        # - Users not subscribed to the topic are included in the `failed` response.
+        #
+        # @overload unsubscribe_bulk(topic_id, user_external_ids:, request_options: {})
+        #
+        # @param topic_id [String] Topic name
+        #
+        # @param user_external_ids [Array<String>] List of user external IDs to subscribe/unsubscribe
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Models::Topics::BulkOperationResponse]
+        #
+        # @see Notiflows::Models::Topics::SubscriptionUnsubscribeBulkParams
+        def unsubscribe_bulk(topic_id, params)
+          parsed, options = ::Notiflows::Topics::SubscriptionUnsubscribeBulkParams.dump_request(params)
+          @client.request(
+            method: :delete,
+            path: ["topics/%1$s/subscriptions", topic_id],
+            body: parsed,
+            model: ::Notiflows::Topics::BulkOperationResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Notiflows::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/notiflows/resources/topics.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Notiflows
+  module Resources
+    class Topics
+      # @return [Notiflows::Resources::Topics::Subscriptions]
+      attr_reader :subscriptions
+
+      # Retrieve a topic by name.
+      #
+      # @overload retrieve(id, request_options: {})
+      #
+      # @param id [String] Topic name
+      #
+      # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Notiflows::Models::Topic]
+      #
+      # @see Notiflows::Models::TopicRetrieveParams
+      def retrieve(id, params = {})
+        @client.request(
+          method: :get,
+          path: ["topics/%1$s", id],
+          model: ::Notiflows::Topic,
+          options: params[:request_options]
+        )
+      end
+
+      # Retrieve a paginated list of all topics in your project.
+      #
+      # Topics are used for pub/sub notification patterns. Users subscribe to topics,
+      # and you can run notiflows for all subscribers of a topic.
+      #
+      # @overload list(after: nil, before: nil, limit: nil, request_options: {})
+      #
+      # @param after [String] Cursor for fetching the next page
+      #
+      # @param before [String] Cursor for fetching the previous page
+      #
+      # @param limit [Integer] Number of items per page (default: 25, max: 1000)
+      #
+      # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Notiflows::Internal::CursorPage<Notiflows::Models::Topic>]
+      #
+      # @see Notiflows::Models::TopicListParams
+      def list(params = {})
+        parsed, options = ::Notiflows::TopicListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "topics",
+          query: parsed,
+          page: ::Notiflows::Internal::CursorPage,
+          model: ::Notiflows::Topic,
+          options: options
+        )
+      end
+
+      # Delete a topic and all its subscriptions.
+      #
+      # **Warning:** This removes all user subscriptions to this topic. Users will need
+      # to re-subscribe if the topic is recreated.
+      #
+      # @overload delete(id, request_options: {})
+      #
+      # @param id [String] Topic name
+      #
+      # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [nil]
+      #
+      # @see Notiflows::Models::TopicDeleteParams
+      def delete(id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["topics/%1$s", id],
+          model: NilClass,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Notiflows::Client]
+      def initialize(client:)
+        @client = client
+        @subscriptions = Subscriptions.new(client: client)
+      end
+    end
+  end
+end

data/lib/notiflows/resources/users/channel_settings.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Notiflows
+  module Resources
+    class Users
+      class ChannelSettings
+        # Retrieve a user's settings for a specific channel.
+        #
+        # Channel settings store provider-specific data like device tokens (for push) or
+        # Slack user IDs (for chat).
+        #
+        # @overload retrieve(channel_id, user_external_id:, request_options: {})
+        #
+        # @param channel_id [String] Channel ID (UUID)
+        #
+        # @param user_external_id [String] User external ID
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Models::Users::UsersChannelSettings]
+        #
+        # @see Notiflows::Models::Users::ChannelSettingRetrieveParams
+        def retrieve(channel_id, params)
+          parsed, options = ::Notiflows::Users::ChannelSettingRetrieveParams.dump_request(params)
+          user_external_id =
+            parsed.delete(:user_external_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["users/%1$s/channel-settings/%2$s", user_external_id, channel_id],
+            model: ::Notiflows::Users::UsersChannelSettings,
+            options: options
+          )
+        end
+
+        # Update a user's settings for a specific channel. Creates the settings if they
+        # don't exist.
+        #
+        # **Provider-specific settings:**
+        #
+        # **Mobile Push (APNS/FCM):**
+        #
+        # ```json
+        # {
+        #   "settings": {
+        #     "device_tokens": ["token1", "token2"]
+        #   }
+        # }
+        # ```
+        #
+        # **Slack:**
+        #
+        # ```json
+        # {
+        #   "settings": {
+        #     "slack_channel_id": "C0123456789",
+        #     "slack_user_id": "U0123456789"
+        #   }
+        # }
+        # ```
+        #
+        # At least one of `slack_channel_id` or `slack_user_id` must be provided.
+        #
+        # @overload update(channel_id, user_external_id:, settings:, request_options: {})
+        #
+        # @param channel_id [String] Path param: Channel ID (UUID)
+        #
+        # @param user_external_id [String] Path param: User external ID
+        #
+        # @param settings [Notiflows::Models::Users::MobilePushSettings, Notiflows::Models::Users::SlackSettings] Body param: Provider-specific settings. Structure depends on channel provider.
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Models::Users::UsersChannelSettings]
+        #
+        # @see Notiflows::Models::Users::ChannelSettingUpdateParams
+        def update(channel_id, params)
+          parsed, options = ::Notiflows::Users::ChannelSettingUpdateParams.dump_request(params)
+          user_external_id =
+            parsed.delete(:user_external_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :put,
+            path: ["users/%1$s/channel-settings/%2$s", user_external_id, channel_id],
+            body: parsed,
+            model: ::Notiflows::Users::UsersChannelSettings,
+            options: options
+          )
+        end
+
+        # Remove a user's settings for a specific channel.
+        #
+        # After deletion, the user will no longer receive notifications through this
+        # channel until new settings are configured.
+        #
+        # @overload delete(channel_id, user_external_id:, request_options: {})
+        #
+        # @param channel_id [String] Channel ID (UUID)
+        #
+        # @param user_external_id [String] User external ID
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see Notiflows::Models::Users::ChannelSettingDeleteParams
+        def delete(channel_id, params)
+          parsed, options = ::Notiflows::Users::ChannelSettingDeleteParams.dump_request(params)
+          user_external_id =
+            parsed.delete(:user_external_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :delete,
+            path: ["users/%1$s/channel-settings/%2$s", user_external_id, channel_id],
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Notiflows::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/notiflows/resources/users/deliveries.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Notiflows
+  module Resources
+    class Users
+      class Deliveries
+        # Retrieve details of a specific delivery attempt for a user.
+        #
+        # @overload retrieve(delivery_id, user_external_id:, request_options: {})
+        #
+        # @param delivery_id [String] Delivery ID (UUID)
+        #
+        # @param user_external_id [String] User external ID
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Models::Delivery]
+        #
+        # @see Notiflows::Models::Users::DeliveryRetrieveParams
+        def retrieve(delivery_id, params)
+          parsed, options = ::Notiflows::Users::DeliveryRetrieveParams.dump_request(params)
+          user_external_id =
+            parsed.delete(:user_external_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["users/%1$s/deliveries/%2$s", user_external_id, delivery_id],
+            model: ::Notiflows::Delivery,
+            options: options
+          )
+        end
+
+        # Retrieve all delivery attempts for a user across all channels.
+        #
+        # @overload list(user_external_id, after: nil, before: nil, channel_id: nil, created_after: nil, created_before: nil, limit: nil, status: nil, topic: nil, request_options: {})
+        #
+        # @param user_external_id [String] User external ID
+        #
+        # @param after [String] Cursor for fetching the next page
+        #
+        # @param before [String] Cursor for fetching the previous page
+        #
+        # @param channel_id [String] Filter by channel ID (UUID)
+        #
+        # @param created_after [String] Filter by created after (ISO 8601 datetime)
+        #
+        # @param created_before [String] Filter by created before (ISO 8601 datetime)
+        #
+        # @param limit [Integer] Number of items per page (default: 25, max: 1000)
+        #
+        # @param status [String] Filter by status (pending, sent, failed)
+        #
+        # @param topic [String] Filter by topic name
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Internal::CursorPage<Notiflows::Models::Delivery>]
+        #
+        # @see Notiflows::Models::Users::DeliveryListParams
+        def list(user_external_id, params = {})
+          parsed, options = ::Notiflows::Users::DeliveryListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["users/%1$s/deliveries", user_external_id],
+            query: parsed,
+            page: ::Notiflows::Internal::CursorPage,
+            model: ::Notiflows::Delivery,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Notiflows::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/notiflows/resources/users/notifications.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Notiflows
+  module Resources
+    class Users
+      class Notifications
+        # Retrieve a specific notification for a user, including all delivery attempts.
+        #
+        # @overload retrieve(notification_id, user_external_id:, request_options: {})
+        #
+        # @param notification_id [String] Notification ID (UUID)
+        #
+        # @param user_external_id [String] User external ID
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Models::Notification]
+        #
+        # @see Notiflows::Models::Users::NotificationRetrieveParams
+        def retrieve(notification_id, params)
+          parsed, options = ::Notiflows::Users::NotificationRetrieveParams.dump_request(params)
+          user_external_id =
+            parsed.delete(:user_external_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["users/%1$s/notifications/%2$s", user_external_id, notification_id],
+            model: ::Notiflows::Notification,
+            options: options
+          )
+        end
+
+        # Retrieve all notifications sent to a specific user.
+        #
+        # @overload list(user_external_id, after: nil, before: nil, created_after: nil, created_before: nil, limit: nil, status: nil, topic: nil, request_options: {})
+        #
+        # @param user_external_id [String] User external ID
+        #
+        # @param after [String] Cursor for fetching the next page
+        #
+        # @param before [String] Cursor for fetching the previous page
+        #
+        # @param created_after [String] Filter by created after (ISO 8601 datetime)
+        #
+        # @param created_before [String] Filter by created before (ISO 8601 datetime)
+        #
+        # @param limit [Integer] Number of items per page (default: 25, max: 1000)
+        #
+        # @param status [String] Filter by status
+        #
+        # @param topic [String] Filter by topic
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Notiflows::Internal::CursorPage<Notiflows::Models::Notification>]
+        #
+        # @see Notiflows::Models::Users::NotificationListParams
+        def list(user_external_id, params = {})
+          parsed, options = ::Notiflows::Users::NotificationListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["users/%1$s/notifications", user_external_id],
+            query: parsed,
+            page: ::Notiflows::Internal::CursorPage,
+            model: ::Notiflows::Notification,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Notiflows::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/notiflows/resources/users/preferences.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Notiflows
+  module Resources
+    class Users
+      class Preferences
+        # Retrieve a user's notification preferences.
+        #
+        # Preferences control which notifications the user receives:
+        #
+        # - `channel_types`: Global opt-in/opt-out per channel type (email, sms, push,
+        #   etc.)
+        # - `notiflows`: Per-notiflow preferences with optional channel overrides
+        #
+        # @overload retrieve(user_external_id, request_options: {})
+        #
+        # @param user_external_id [String] User external ID
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [::Notiflows::Models::Users::UsersPreferences]
+        #
+        # @see Notiflows::Models::Users::PreferenceRetrieveParams
+        def retrieve(user_external_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["users/%1$s/preferences", user_external_id],
+            model: ::Notiflows::Users::UsersPreferences,
+            options: params[:request_options]
+          )
+        end
+
+        # Update a user's notification preferences. Only provided fields are updated
+        # (partial update).
+        #
+        # **Channel types:** Set to `false` to opt the user out of a channel globally.
+        #
+        # **Notiflow preferences:** Override settings for specific notiflows:
+        #
+        # ```json
+        # {
+        #   "notiflows": {
+        #     "notiflow_uuid": {
+        #       "enabled": true,
+        #       "channel_types": {
+        #         "email": false
+        #       }
+        #     }
+        #   }
+        # }
+        # ```
+        #
+        # @overload update(user_external_id, channel_types: nil, notiflows: nil, request_options: {})
+        #
+        # @param user_external_id [String] User external ID
+        #
+        # @param channel_types [Hash{Symbol=>Boolean}] Global channel type preferences
+        #
+        # @param notiflows [Hash{Symbol=>::Notiflows::Models::Users::UpdatePreferencesRequest::Notiflow}] Per-notiflow preferences (keyed by notiflow ID)
+        #
+        # @param request_options [Notiflows::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [::Notiflows::Models::Users::UsersPreferences]
+        #
+        # @see Notiflows::Models::Users::PreferenceUpdateParams
+        def update(user_external_id, params = {})
+          parsed, options = ::Notiflows::Users::PreferenceUpdateParams.dump_request(params)
+          @client.request(
+            method: :put,
+            path: ["users/%1$s/preferences", user_external_id],
+            body: parsed,
+            model: ::Notiflows::Users::UsersPreferences,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Notiflows::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end