notiflows 0.0.1

data/rbi/notiflows/resources/topics.rbi

@@ -0,0 +1,69 @@
+# typed: strong
+
+module Notiflows
+  module Resources
+    class Topics
+      sig { returns(Notiflows::Resources::Topics::Subscriptions) }
+      attr_reader :subscriptions
+
+      # Retrieve a topic by name.
+      sig do
+        params(
+          id: String,
+          request_options: Notiflows::RequestOptions::OrHash
+        ).returns(Notiflows::Topic)
+      end
+      def retrieve(
+        # Topic name
+        id,
+        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.
+      sig do
+        params(
+          after: String,
+          before: String,
+          limit: Integer,
+          request_options: Notiflows::RequestOptions::OrHash
+        ).returns(Notiflows::Internal::CursorPage[Notiflows::Topic])
+      end
+      def list(
+        # Cursor for fetching the next page
+        after: nil,
+        # Cursor for fetching the previous page
+        before: nil,
+        # Number of items per page (default: 25, max: 1000)
+        limit: nil,
+        request_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.
+      sig do
+        params(
+          id: String,
+          request_options: Notiflows::RequestOptions::OrHash
+        ).void
+      end
+      def delete(
+        # Topic name
+        id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Notiflows::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/notiflows/resources/users/channel_settings.rbi

@@ -0,0 +1,104 @@
+# typed: strong
+
+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).
+        sig do
+          params(
+            channel_id: String,
+            user_external_id: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(Notiflows::Users::UsersChannelSettings)
+        end
+        def retrieve(
+          # Channel ID (UUID)
+          channel_id,
+          # User external ID
+          user_external_id:,
+          request_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.
+        sig do
+          params(
+            channel_id: String,
+            user_external_id: String,
+            settings:
+              T.any(
+                Notiflows::Users::MobilePushSettings::OrHash,
+                Notiflows::Users::SlackSettings::OrHash
+              ),
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(Notiflows::Users::UsersChannelSettings)
+        end
+        def update(
+          # Path param: Channel ID (UUID)
+          channel_id,
+          # Path param: User external ID
+          user_external_id:,
+          # Body param: Provider-specific settings. Structure depends on channel provider.
+          settings:,
+          request_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.
+        sig do
+          params(
+            channel_id: String,
+            user_external_id: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).void
+        end
+        def delete(
+          # Channel ID (UUID)
+          channel_id,
+          # User external ID
+          user_external_id:,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Notiflows::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/notiflows/resources/users/deliveries.rbi

@@ -0,0 +1,69 @@
+# typed: strong
+
+module Notiflows
+  module Resources
+    class Users
+      class Deliveries
+        # Retrieve details of a specific delivery attempt for a user.
+        sig do
+          params(
+            delivery_id: String,
+            user_external_id: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(Notiflows::Delivery)
+        end
+        def retrieve(
+          # Delivery ID (UUID)
+          delivery_id,
+          # User external ID
+          user_external_id:,
+          request_options: {}
+        )
+        end
+
+        # Retrieve all delivery attempts for a user across all channels.
+        sig do
+          params(
+            user_external_id: String,
+            after: String,
+            before: String,
+            channel_id: String,
+            created_after: String,
+            created_before: String,
+            limit: Integer,
+            status: String,
+            topic: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(Notiflows::Internal::CursorPage[Notiflows::Delivery])
+        end
+        def list(
+          # User external ID
+          user_external_id,
+          # Cursor for fetching the next page
+          after: nil,
+          # Cursor for fetching the previous page
+          before: nil,
+          # Filter by channel ID (UUID)
+          channel_id: nil,
+          # Filter by created after (ISO 8601 datetime)
+          created_after: nil,
+          # Filter by created before (ISO 8601 datetime)
+          created_before: nil,
+          # Number of items per page (default: 25, max: 1000)
+          limit: nil,
+          # Filter by status (pending, sent, failed)
+          status: nil,
+          # Filter by topic name
+          topic: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Notiflows::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/notiflows/resources/users/notifications.rbi

@@ -0,0 +1,66 @@
+# typed: strong
+
+module Notiflows
+  module Resources
+    class Users
+      class Notifications
+        # Retrieve a specific notification for a user, including all delivery attempts.
+        sig do
+          params(
+            notification_id: String,
+            user_external_id: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(Notiflows::Notification)
+        end
+        def retrieve(
+          # Notification ID (UUID)
+          notification_id,
+          # User external ID
+          user_external_id:,
+          request_options: {}
+        )
+        end
+
+        # Retrieve all notifications sent to a specific user.
+        sig do
+          params(
+            user_external_id: String,
+            after: String,
+            before: String,
+            created_after: String,
+            created_before: String,
+            limit: Integer,
+            status: String,
+            topic: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(Notiflows::Internal::CursorPage[Notiflows::Notification])
+        end
+        def list(
+          # User external ID
+          user_external_id,
+          # Cursor for fetching the next page
+          after: nil,
+          # Cursor for fetching the previous page
+          before: nil,
+          # Filter by created after (ISO 8601 datetime)
+          created_after: nil,
+          # Filter by created before (ISO 8601 datetime)
+          created_before: nil,
+          # Number of items per page (default: 25, max: 1000)
+          limit: nil,
+          # Filter by status
+          status: nil,
+          # Filter by topic
+          topic: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Notiflows::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/notiflows/resources/users/preferences.rbi

@@ -0,0 +1,76 @@
+# typed: strong
+
+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
+        sig do
+          params(
+            user_external_id: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(::Notiflows::Users::UsersPreferences)
+        end
+        def retrieve(
+          # User external ID
+          user_external_id,
+          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
+        #       }
+        #     }
+        #   }
+        # }
+        # ```
+        sig do
+          params(
+            user_external_id: String,
+            channel_types: T::Hash[Symbol, T::Boolean],
+            notiflows:
+              T::Hash[
+                Symbol,
+                ::Notiflows::Users::UpdatePreferencesRequest::Notiflow::OrHash
+              ],
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(::Notiflows::Users::UsersPreferences)
+        end
+        def update(
+          # User external ID
+          user_external_id,
+          # Global channel type preferences
+          channel_types: nil,
+          # Per-notiflow preferences (keyed by notiflow ID)
+          notiflows: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Notiflows::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/notiflows/resources/users/subscriptions.rbi

@@ -0,0 +1,102 @@
+# typed: strong
+
+module Notiflows
+  module Resources
+    class Users
+      class Subscriptions
+        # Check if a user is subscribed to a specific topic.
+        sig do
+          params(
+            topic_name: String,
+            user_external_id: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(Notiflows::Users::Subscription)
+        end
+        def retrieve(
+          # Topic name
+          topic_name,
+          # User external ID
+          user_external_id:,
+          request_options: {}
+        )
+        end
+
+        # Retrieve all topic subscriptions for a user.
+        sig do
+          params(
+            user_external_id: String,
+            after: String,
+            before: String,
+            created_after: String,
+            created_before: String,
+            limit: Integer,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(
+            Notiflows::Internal::CursorPage[Notiflows::Users::Subscription]
+          )
+        end
+        def list(
+          # User external ID
+          user_external_id,
+          # Cursor for fetching the next page
+          after: nil,
+          # Cursor for fetching the previous page
+          before: nil,
+          # Filter by created after (ISO 8601 datetime)
+          created_after: nil,
+          # Filter by created before (ISO 8601 datetime)
+          created_before: nil,
+          # Number of items per page (default: 25, max: 1000)
+          limit: nil,
+          request_options: {}
+        )
+        end
+
+        # Subscribe a user to a topic. Topics are created automatically if they don't
+        # exist.
+        #
+        # **Idempotent:** If the user is already subscribed, returns the existing
+        # subscription with `200 OK`.
+        sig do
+          params(
+            user_external_id: String,
+            topic_name: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).returns(Notiflows::Users::Subscription)
+        end
+        def subscribe(
+          # User external ID
+          user_external_id,
+          # Name of the topic to subscribe to. Topics are created automatically if they
+          # don't exist.
+          topic_name:,
+          request_options: {}
+        )
+        end
+
+        # Remove a user's subscription from a topic. The user will no longer receive
+        # notifications triggered for this topic.
+        sig do
+          params(
+            topic_name: String,
+            user_external_id: String,
+            request_options: Notiflows::RequestOptions::OrHash
+          ).void
+        end
+        def unsubscribe(
+          # Topic name
+          topic_name,
+          # User external ID
+          user_external_id:,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Notiflows::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/notiflows/resources/users.rbi

@@ -0,0 +1,147 @@
+# typed: strong
+
+module Notiflows
+  module Resources
+    class Users
+      sig { returns(Notiflows::Resources::Users::ChannelSettings) }
+      attr_reader :channel_settings
+
+      sig { returns(Notiflows::Resources::Users::Deliveries) }
+      attr_reader :deliveries
+
+      sig { returns(Notiflows::Resources::Users::Notifications) }
+      attr_reader :notifications
+
+      sig { returns(Notiflows::Resources::Users::Preferences) }
+      attr_reader :preferences
+
+      sig { returns(Notiflows::Resources::Users::Subscriptions) }
+      attr_reader :subscriptions
+
+      # Retrieve a single user by their external ID. The external ID is the identifier
+      # you assigned when creating the user.
+      sig do
+        params(
+          user_external_id: String,
+          request_options: Notiflows::RequestOptions::OrHash
+        ).returns(Notiflows::User)
+      end
+      def retrieve(
+        # User external ID (your system's user identifier)
+        user_external_id,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a paginated list of users in your project. Users are sorted by creation
+      # date (newest first).
+      sig do
+        params(
+          after: String,
+          before: String,
+          created_after: String,
+          created_before: String,
+          limit: Integer,
+          request_options: Notiflows::RequestOptions::OrHash
+        ).returns(Notiflows::Internal::CursorPage[Notiflows::User])
+      end
+      def list(
+        # Cursor for fetching the next page
+        after: nil,
+        # Cursor for fetching the previous page
+        before: nil,
+        # Filter users created after this datetime (ISO 8601)
+        created_after: nil,
+        # Filter users created before this datetime (ISO 8601)
+        created_before: nil,
+        # Number of items per page (default: 25, max: 1000)
+        limit: nil,
+        request_options: {}
+      )
+      end
+
+      # Permanently delete a user and all their associated data including:
+      #
+      # - Subscriptions
+      # - Preferences
+      # - Channel settings
+      # - Notifications and deliveries
+      #
+      # **This action cannot be undone.**
+      sig do
+        params(
+          user_external_id: String,
+          request_options: Notiflows::RequestOptions::OrHash
+        ).void
+      end
+      def delete(
+        # User external ID
+        user_external_id,
+        request_options: {}
+      )
+      end
+
+      # Create a new user or update an existing user by external ID (upsert operation).
+      #
+      # - If the user doesn't exist, they will be created with the provided attributes.
+      # - If the user exists, their attributes will be updated (merge behavior).
+      # - `custom_fields` are deep-merged with existing values.
+      #
+      # **Returns:**
+      #
+      # - `201 Created` when a new user is created
+      # - `200 OK` when an existing user is updated
+      sig do
+        params(
+          user_external_id: String,
+          external_id: String,
+          avatar: String,
+          channel_settings:
+            T::Array[Notiflows::UserUpsertParams::ChannelSetting::OrHash],
+          custom_fields: T.anything,
+          email: String,
+          first_name: String,
+          last_name: String,
+          locale: String,
+          phone: String,
+          preferences: ::Notiflows::Users::UpdatePreferencesRequest::OrHash,
+          timezone: String,
+          request_options: Notiflows::RequestOptions::OrHash
+        ).returns(Notiflows::User)
+      end
+      def upsert(
+        # User external ID
+        user_external_id,
+        # Your system's unique identifier for this user. Required for creating new users.
+        external_id:,
+        # URL to user's avatar image (must start with http:// or https://)
+        avatar: nil,
+        # Initial channel settings (e.g., device tokens for push)
+        channel_settings: nil,
+        # Custom attributes. Deep-merged with existing values on update.
+        custom_fields: nil,
+        # User's email address
+        email: nil,
+        # User's first name
+        first_name: nil,
+        # User's last name
+        last_name: nil,
+        # BCP 47 locale code (e.g., en-US, es-ES, fr-FR)
+        locale: nil,
+        # User's phone number in E.164 format
+        phone: nil,
+        # Request body for updating user preferences. Only provided fields are updated.
+        preferences: nil,
+        # IANA timezone (e.g., America/New_York, Europe/London)
+        timezone: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Notiflows::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/notiflows/version.rbi

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

data/sig/notiflows/client.rbs

@@ -0,0 +1,41 @@
+module Notiflows
+  class Client < Notiflows::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 secret: String
+
+    attr_reader deliveries: Notiflows::Resources::Deliveries
+
+    attr_reader notifications: Notiflows::Resources::Notifications
+
+    attr_reader notiflows: Notiflows::Resources::Notiflows
+
+    attr_reader topics: Notiflows::Resources::Topics
+
+    attr_reader users: Notiflows::Resources::Users
+
+    private def auth_headers: -> ::Hash[String, String]
+
+    private def api_key_auth: -> ::Hash[String, String]
+
+    private def secret_key_auth: -> ::Hash[String, String]
+
+    def initialize: (
+      ?api_key: String?,
+      ?secret: String?,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end