teams_rb 2.0.1

data/lib/teams/api/conversation_account.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class ConversationAccount < Model
+      def id
+        read("id")
+      end
+
+      def tenant_id
+        read("tenantId", "tenant_id")
+      end
+
+      def conversation_type
+        read("conversationType", "conversation_type")
+      end
+
+      def name
+        read("name")
+      end
+
+      def is_group
+        read("isGroup", "is_group")
+      end
+
+      def to_h
+        body = raw.dup
+        body["id"] = id if id
+        body["tenantId"] = tenant_id if tenant_id
+        body["conversationType"] = conversation_type if conversation_type
+        body["name"] = name if name
+        body["isGroup"] = is_group unless is_group.nil?
+        body.delete("tenant_id")
+        body.delete("conversation_type")
+        body.delete("is_group")
+        body
+      end
+    end
+  end
+end

data/lib/teams/api/conversation_client.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Teams
+  module Api
+    class ConversationClient
+      TARGETED_PARAMS = { "isTargetedActivity" => "true" }.freeze
+
+      attr_reader :service_url, :http
+
+      def initialize(service_url:, http:, logger: nil)
+        @service_url = service_url.sub(%r{/+\z}, "")
+        @http = http
+        @logger = logger
+        @reactions = ReactionClient.new(service_url: @service_url, http:)
+      end
+
+      # Creates a conversation (or returns the pre-existing one for the same
+      # members). isGroup/bot/topicName are omitted: the SDKs deprecate them
+      # for removal, and Python never had them.
+      def create(members: nil, tenant_id: nil, activity: nil, channel_data: nil, service_url: nil)
+        body = {}
+        body["members"] = members.map { |member| account_to_h(member) } if members
+        body["tenantId"] = tenant_id if tenant_id
+        body["activity"] = activity_to_h(activity) if activity
+        body["channelData"] = Common::Hashes.deep_stringify_keys(channel_data) if channel_data
+
+        url = absolute("/v3/conversations", service_url:)
+        @logger&.debug("Teams API POST #{url}")
+        ConversationResource.new(http.post(url, json: body))
+      end
+
+      def create_activity(conversation_id, activity, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/activities"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API POST #{url}")
+        http.post(url, json: activity_to_h(activity))
+      end
+
+      def reply_to_activity(conversation_id, activity_id, activity, service_url: nil)
+        body = activity_to_h(activity)
+        body = body.merge("replyToId" => activity_id) if body.is_a?(Hash)
+        path = "/v3/conversations/#{escape(conversation_id)}/activities/#{escape(activity_id)}"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API POST #{url}")
+        http.post(url, json: body)
+      end
+
+      def update_activity(conversation_id, activity_id, activity, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/activities/#{escape(activity_id)}"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API PUT #{url}")
+        http.put(url, json: activity_to_h(activity))
+      end
+
+      def delete_activity(conversation_id, activity_id, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/activities/#{escape(activity_id)}"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API DELETE #{url}")
+        http.delete(url)
+      end
+
+      def create_targeted_activity(conversation_id, activity, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/activities"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API POST #{url} (targeted)")
+        http.post(url, json: activity_to_h(activity), params: TARGETED_PARAMS)
+      end
+
+      def update_targeted_activity(conversation_id, activity_id, activity, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/activities/#{escape(activity_id)}"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API PUT #{url} (targeted)")
+        http.put(url, json: activity_to_h(activity), params: TARGETED_PARAMS)
+      end
+
+      def delete_targeted_activity(conversation_id, activity_id, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/activities/#{escape(activity_id)}"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API DELETE #{url} (targeted)")
+        http.delete(url, params: TARGETED_PARAMS)
+      end
+
+      # The backend returns objectId instead of aadObjectId on some member
+      # endpoints; Api::Account reads both, so the accounts here are already
+      # normalized like the other SDKs' TeamsChannelAccount.
+      def get_members(conversation_id, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/members"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API GET #{url}")
+        Array(http.get(url)).map { |member| Account.new(member) }
+      end
+
+      def get_member_by_id(conversation_id, member_id, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/members/#{escape(member_id)}"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API GET #{url}")
+        Account.new(http.get(url))
+      end
+
+      def get_paged_members(conversation_id, page_size: nil, continuation_token: nil, service_url: nil)
+        params = {}
+        params["pageSize"] = page_size if page_size
+        params["continuationToken"] = continuation_token if continuation_token
+
+        path = "/v3/conversations/#{escape(conversation_id)}/pagedMembers"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API GET #{url}")
+        PagedMembersResult.new(http.get(url, params: params.empty? ? nil : params))
+      end
+
+      def get_activity_members(conversation_id, activity_id, service_url: nil)
+        path = "/v3/conversations/#{escape(conversation_id)}/activities/#{escape(activity_id)}/members"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API GET #{url}")
+        Array(http.get(url)).map { |member| Account.new(member) }
+      end
+
+      def add_reaction(conversation_id, activity_id, reaction_type)
+        reactions.add(conversation_id, activity_id, reaction_type)
+      end
+
+      def delete_reaction(conversation_id, activity_id, reaction_type)
+        reactions.delete(conversation_id, activity_id, reaction_type)
+      end
+
+      private
+
+      attr_reader :reactions
+
+      def account_to_h(account)
+        account.is_a?(Hash) ? Common::Hashes.deep_stringify_keys(account) : account.to_h
+      end
+
+      def activity_to_h(activity)
+        case activity
+        when String
+          MessageActivity.new(activity).to_h
+        when Hash
+          Common::Hashes.deep_stringify_keys(activity)
+        else
+          activity.respond_to?(:to_h) ? activity.to_h : activity
+        end
+      end
+
+      def absolute(path, service_url: nil)
+        "#{(service_url || self.service_url).sub(%r{/+\z}, "")}#{path}"
+      end
+
+      def escape(value)
+        URI.encode_www_form_component(value.to_s)
+      end
+    end
+  end
+end

data/lib/teams/api/conversation_reference.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Teams
+  module Api
+    class ConversationReference
+      attr_reader :activity_id, :user, :locale, :bot, :conversation, :channel_id, :service_url
+
+      def self.from_activity(activity)
+        new(
+          activity_id: activity.id,
+          user: activity.from,
+          locale: activity.locale,
+          bot: activity.recipient,
+          conversation: activity.conversation,
+          channel_id: activity.channel_id,
+          service_url: activity.service_url
+        )
+      end
+
+      def self.from_h(raw)
+        raw = raw.to_h if raw.respond_to?(:to_h)
+
+        new(
+          activity_id: raw["activityId"] || raw["activity_id"] || raw[:activityId] || raw[:activity_id],
+          user: raw["user"] || raw[:user],
+          locale: raw["locale"] || raw[:locale],
+          bot: raw.fetch("bot") { raw.fetch(:bot) },
+          conversation: raw.fetch("conversation") { raw.fetch(:conversation) },
+          channel_id: raw["channelId"] || raw["channel_id"] || raw[:channelId] || raw[:channel_id],
+          service_url: raw["serviceUrl"] || raw["service_url"] || raw[:serviceUrl] || raw[:service_url]
+        )
+      end
+
+      def initialize(activity_id: nil, user: nil, locale: nil, bot:, conversation:, channel_id:, service_url:)
+        @activity_id = activity_id
+        @user = wrap_account(user)
+        @locale = locale
+        @bot = wrap_account(bot)
+        @conversation = wrap_conversation(conversation)
+        @channel_id = channel_id
+        @service_url = service_url
+      end
+
+      def conversation_id
+        conversation.id
+      end
+
+      def to_h
+        body = {
+          "bot" => bot.to_h,
+          "conversation" => conversation.to_h,
+          "channelId" => channel_id,
+          "serviceUrl" => service_url
+        }
+        body["activityId"] = activity_id if activity_id
+        body["user"] = user.to_h if user
+        body["locale"] = locale if locale
+        body
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      private
+
+      def wrap_account(value)
+        return value if value.is_a?(Account)
+        return nil if value.nil?
+
+        Account.new(value)
+      end
+
+      def wrap_conversation(value)
+        return value if value.is_a?(ConversationAccount)
+
+        ConversationAccount.new(value)
+      end
+    end
+  end
+end

data/lib/teams/api/conversation_resource.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class ConversationResource < Model
+      def id
+        read("id")
+      end
+
+      def activity_id
+        read("activityId", "activity_id")
+      end
+
+      def service_url
+        read("serviceUrl", "service_url")
+      end
+    end
+  end
+end

data/lib/teams/api/meeting_client.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Teams
+  module Api
+    class MeetingClient
+      attr_reader :service_url, :http
+
+      def initialize(service_url:, http:, logger: nil)
+        @service_url = service_url.sub(%r{/+\z}, "")
+        @http = http
+        @logger = logger
+      end
+
+      def get_by_id(meeting_id, service_url: nil)
+        path = "/v1/meetings/#{escape(meeting_id)}"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API GET #{url}")
+        MeetingInfo.new(http.get(url))
+      end
+
+      # participant_id is the user's AAD object id; tenant_id is required by
+      # the service.
+      def get_participant(meeting_id, participant_id, tenant_id, service_url: nil)
+        path = "/v1/meetings/#{escape(meeting_id)}/participants/#{escape(participant_id)}"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API GET #{url}")
+        MeetingParticipant.new(http.get(url, params: { "tenantId" => tenant_id }))
+      end
+
+      # Sends a targeted in-meeting notification. Returns nil when every
+      # recipient succeeded (202); returns a MeetingNotificationResponse with
+      # per-recipient failures on partial success (207).
+      def send_notification(meeting_id, params, service_url: nil)
+        body = Common::Hashes.deep_stringify_keys(params.respond_to?(:to_h) ? params.to_h : params)
+        body["type"] ||= "targetedMeetingNotification"
+
+        path = "/v1/meetings/#{escape(meeting_id)}/notification"
+        url = absolute(path, service_url:)
+        @logger&.debug("Teams API POST #{url}")
+        response = http.post(url, json: body)
+        response ? MeetingNotificationResponse.new(response) : nil
+      end
+
+      private
+
+      def absolute(path, service_url: nil)
+        "#{(service_url || self.service_url).sub(%r{/+\z}, "")}#{path}"
+      end
+
+      def escape(value)
+        URI.encode_www_form_component(value.to_s)
+      end
+    end
+  end
+end

data/lib/teams/api/meeting_info.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class MeetingInfo < Model
+      def id
+        read("id")
+      end
+
+      def details
+        value = read("details")
+        value.is_a?(Hash) ? ActivityValue.new(value) : value
+      end
+
+      def conversation
+        value = read("conversation")
+        value ? ConversationAccount.new(value) : nil
+      end
+
+      def organizer
+        value = read("organizer")
+        value ? Account.new(value) : nil
+      end
+    end
+  end
+end

data/lib/teams/api/meeting_notification_response.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class MeetingNotificationRecipientFailure < Model
+      def recipient_mri
+        read("recipientMri", "recipient_mri")
+      end
+
+      def error_code
+        read("errorCode", "error_code")
+      end
+
+      def failure_reason
+        read("failureReason", "failure_reason")
+      end
+    end
+
+    # Returned on partial success (HTTP 207) of a meeting notification; the
+    # client returns nil instead when every recipient succeeded (HTTP 202).
+    class MeetingNotificationResponse < Model
+      def recipients_failure_info
+        Array(read("recipientsFailureInfo", "recipients_failure_info")).map do |failure|
+          MeetingNotificationRecipientFailure.new(failure)
+        end
+      end
+    end
+  end
+end

data/lib/teams/api/meeting_participant.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    # A participant's meeting-specific details: role and presence status.
+    class Meeting < Model
+      def role
+        read("role")
+      end
+
+      def in_meeting
+        read("inMeeting", "in_meeting")
+      end
+    end
+
+    class MeetingParticipant < Model
+      def user
+        value = read("user")
+        value ? Account.new(value) : nil
+      end
+
+      def meeting
+        value = read("meeting")
+        value ? Meeting.new(value) : nil
+      end
+
+      def conversation
+        value = read("conversation")
+        value ? ConversationAccount.new(value) : nil
+      end
+    end
+  end
+end

data/lib/teams/api/message_activity.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class MessageActivity
+      TEXT_FORMATS = %w[plain markdown xml extendedmarkdown].freeze
+      FEEDBACK_MODES = %w[default custom].freeze
+      AI_MESSAGE_ENTITY_TYPE = "https://schema.org/Message"
+
+      attr_reader :id, :text, :attachments, :text_format, :summary, :input_hint, :entities, :channel_data, :recipient
+
+      def initialize(text = nil, id: nil, attachments: [], text_format: nil, summary: nil, input_hint: nil)
+        @id = id
+        @text = text
+        @attachments = attachments
+        @text_format = normalize_text_format(text_format)
+        @summary = summary
+        @input_hint = input_hint
+        @entities = []
+        @channel_data = {}
+        @recipient = nil
+      end
+
+      def add_text(value)
+        @text = "#{text}#{value}"
+        self
+      end
+
+      def add_quote(message_id, text = nil)
+        @entities << QuotedReplyEntity.new("quotedReply" => { "messageId" => message_id })
+        add_text(%(<quoted messageId="#{message_id}"/>))
+        add_text(" #{text}") if text
+        self
+      end
+
+      def prepend_quote(message_id)
+        @entities << QuotedReplyEntity.new("quotedReply" => { "messageId" => message_id })
+        placeholder = %(<quoted messageId="#{message_id}"/>)
+        @text = text.to_s.strip.empty? ? placeholder : "#{placeholder} #{text}"
+        self
+      end
+
+      def get_quoted_messages
+        entities.select { |entity| quoted_reply_entity?(entity) }
+      end
+
+      def add_card(card)
+        @attachments << {
+          "contentType" => "application/vnd.microsoft.card.adaptive",
+          "content" => card.respond_to?(:to_h) ? card.to_h : card
+        }
+        self
+      end
+
+      def with_text_format(text_format)
+        @text_format = normalize_text_format(text_format)
+        self
+      end
+
+      def with_id(id)
+        @id = id
+        self
+      end
+
+      def with_recipient(account, is_targeted: nil)
+        body = account.respond_to?(:to_h) ? account.to_h : account
+        body = body.dup
+        body["isTargeted"] = is_targeted unless is_targeted.nil?
+        @recipient = body
+        self
+      end
+
+      # Adds a targetedMessageInfo entity for prompt preview, once per message.
+      # Any quotedReply entities and the matching quote placeholder are removed
+      # to avoid collision with the prompt preview.
+      def add_targeted_message_info(message_id)
+        @entities.reject! { |entity| quoted_reply_entity?(entity) }
+        @text = text.gsub(%(<quoted messageId="#{message_id}"/>), "").strip if text
+
+        unless @entities.any? { |entity| entity_type(entity) == "targetedMessageInfo" }
+          @entities << { "type" => "targetedMessageInfo", "messageId" => message_id }
+        end
+
+        self
+      end
+
+      def add_ai_generated
+        entity = ensure_single_root_level_message_entity
+        additional_types = Array(entity["additionalType"])
+        return self if additional_types.include?("AIGeneratedContent")
+
+        entity["additionalType"] = additional_types + ["AIGeneratedContent"]
+        self
+      end
+
+      def add_mention(account, text: nil, add_text: true)
+        account_hash = account.respond_to?(:to_h) ? account.to_h : account
+        mention_text = text || account_hash["name"]
+
+        self.add_text("<at>#{mention_text}</at>") if add_text
+
+        @entities << {
+          "type" => "mention",
+          "mentioned" => account_hash,
+          "text" => "<at>#{mention_text}</at>"
+        }
+        self
+      end
+
+      # Adds a content sensitivity label. The label is carried as usageInfo on
+      # the root schema.org/Message entity, the wire shape TypeScript, Python,
+      # and the Teams documentation use.
+      def add_sensitivity_label(name, description: nil, pattern: nil)
+        usage_info = {
+          "type" => AI_MESSAGE_ENTITY_TYPE,
+          "@type" => "CreativeWork",
+          "name" => name
+        }
+        usage_info["description"] = description if description
+        usage_info["pattern"] = pattern if pattern
+
+        ensure_single_root_level_message_entity["usageInfo"] = usage_info
+        self
+      end
+
+      def add_citation(position, appearance)
+        entity = ensure_single_root_level_message_entity
+        entity["citation"] ||= []
+        entity["citation"] << {
+          "@type" => "Claim",
+          "position" => position,
+          "appearance" => citation_appearance(appearance).to_h
+        }
+        self
+      end
+
+      def add_feedback(mode = "default")
+        @channel_data["feedbackLoop"] = { "type" => normalize_feedback_mode(mode) }
+        @channel_data.delete("feedbackLoopEnabled")
+        self
+      end
+
+      def to_h
+        body = { "type" => "message" }
+        body["id"] = id if id
+        body["text"] = text if text
+        body["textFormat"] = text_format if text_format
+        body["summary"] = summary if summary
+        body["inputHint"] = input_hint if input_hint
+        body["attachments"] = attachments unless attachments.empty?
+        body["entities"] = @entities.map { |entity| entity.respond_to?(:to_h) ? entity.to_h : entity } unless @entities.empty?
+        body["channelData"] = channel_data unless channel_data.empty?
+        body["recipient"] = recipient if recipient
+        body
+      end
+
+      private
+
+      def quoted_reply_entity?(entity)
+        entity_type(entity) == "quotedReply"
+      end
+
+      def ensure_single_root_level_message_entity
+        entity = @entities.find { |item| entity_type(item) == AI_MESSAGE_ENTITY_TYPE }
+        return entity if entity
+
+        entity = {
+          "type" => AI_MESSAGE_ENTITY_TYPE,
+          "@type" => "Message",
+          "@context" => "https://schema.org"
+        }
+        @entities << entity
+        entity
+      end
+
+      def citation_appearance(appearance)
+        appearance.is_a?(CitationAppearance) ? appearance : CitationAppearance.new(appearance || {})
+      end
+
+      def entity_type(entity)
+        entity.respond_to?(:type) ? entity.type : entity["type"]
+      end
+
+      def normalize_text_format(value)
+        return nil if value.nil?
+
+        normalized = value.to_s
+        return normalized if TEXT_FORMATS.include?(normalized)
+
+        raise ArgumentError, "text_format must be one of: #{TEXT_FORMATS.join(", ")}"
+      end
+
+      def normalize_feedback_mode(value)
+        normalized = value.to_s
+        return normalized if FEEDBACK_MODES.include?(normalized)
+
+        raise ArgumentError, "feedback mode must be one of: #{FEEDBACK_MODES.join(", ")}"
+      end
+    end
+  end
+end