teams_rb 2.0.1

data/lib/teams/activity_context.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module Teams
+  class ActivityContext
+    attr_reader :app, :activity, :conversation_reference, :extra, :stream
+
+    def initialize(app:, activity:, conversation_reference:, extra: {}, stream: nil)
+      @app = app
+      @activity = activity
+      @conversation_reference = conversation_reference
+      @extra = extra
+      @stream = stream
+    end
+
+    def ref
+      conversation_reference
+    end
+
+    def reference
+      conversation_reference
+    end
+
+    def log
+      app.logger
+    end
+
+    def storage
+      app.storage
+    end
+
+    def api
+      app.api
+    end
+
+    # The TypeScript, Python, and .NET SDKs call this operation `send`.
+    # Ruby already defines Object#send for dynamic dispatch, so the public
+    # Ruby API uses `post` to avoid shadowing a core language method.
+    def post(activity_or_text)
+      app.send_activity(conversation_reference, apply_targeted_defaults(activity_or_text))
+    end
+
+    def reply(activity_or_text)
+      return post(activity_or_text) unless activity.id
+      # Replies to targeted inbound messages are targeted sends: no quoted
+      # reply and no replyToId, matching the TypeScript and Python SDKs.
+      return post(activity_or_text) if targeted_reply?(activity_or_text)
+
+      quote(activity.id, activity_or_text)
+    end
+
+    # Quoted replies are plain sends carrying the quote placeholder and
+    # entity, matching the TypeScript and Python SDKs; no replyToId is set.
+    def quote(message_id, activity_or_text)
+      post(quoted_activity(message_id, activity_or_text))
+    end
+
+    # Sugar over post: the SDKs update by sending an activity that already
+    # carries an id, and post does exactly that. See AGENTS.md.
+    def update(activity_id, activity_or_text)
+      post(activity_with_id(activity_id, activity_or_text))
+    end
+
+    def typing(text = nil)
+      post(Api::TypingActivity.new(text))
+    end
+
+    # Microsoft Graph client with the app's own identity (app-only tokens).
+    def app_graph
+      app.graph
+    end
+
+    # Microsoft Graph client with the signed-in user's token. Raises when
+    # the user is not signed in, like the Python SDK's user_graph.
+    def user_graph(connection_name: nil)
+      connection = connection_name || app.default_connection_name
+      @user_graph ||= {}
+      @user_graph[connection] ||= begin
+        response = api.users.get_token(
+          user_id: activity.from.id,
+          connection_name: connection,
+          channel_id: activity.channel_id
+        )
+        raise Error, "User must be signed in to access the Graph client" if response.token.to_s.empty?
+
+        Graph::Client.new(token: response.token, base_url_root: app.graph.base_url_root)
+      rescue HttpError
+        raise Error, "User must be signed in to access the Graph client"
+      end
+    end
+
+    # Starts the user sign-in flow: returns the token if the user is already
+    # signed in, otherwise sends an OAuth card and returns nil. In group
+    # conversations the card goes to a 1:1 conversation with the user (group
+    # OAuth is not supported by Teams), like the TypeScript/Python SDKs.
+    def sign_in(connection_name: nil, oauth_card_text: "Please Sign In...", sign_in_button_text: "Sign In")
+      connection_name ||= app.default_connection_name
+
+      begin
+        response = api.users.get_token(
+          user_id: activity.from.id,
+          connection_name:,
+          channel_id: activity.channel_id
+        )
+        return response.token if response.token && !response.token.to_s.empty?
+      rescue HttpError
+        # No token yet; continue with the OAuth card flow.
+      end
+
+      conversation_id = conversation_reference.conversation_id
+      if activity.conversation.is_group
+        one_on_one = api.conversations.create(
+          members: [activity.from.to_h],
+          tenant_id: activity.conversation.tenant_id
+        )
+        conversation_id = one_on_one.id
+        # Deliberately posts the plain text notice into the group (matching
+        # TypeScript and Python): group chats don't support SSO, so the card
+        # itself goes to the 1:1 below while the group sees only the notice.
+        post(oauth_card_text)
+      end
+
+      state = Base64.strict_encode64(JSON.generate(
+        "connectionName" => connection_name,
+        "conversation" => conversation_reference.to_h,
+        "msAppId" => app.client_id
+      ))
+      resource = api.bots.sign_in.get_resource(state:)
+
+      card = {
+        "text" => oauth_card_text,
+        "connectionName" => connection_name,
+        "tokenExchangeResource" => resource.token_exchange_resource&.to_h,
+        "tokenPostResource" => resource.token_post_resource&.to_h,
+        "buttons" => [
+          { "type" => "signin", "title" => sign_in_button_text, "value" => resource.sign_in_link }
+        ]
+      }.compact
+
+      payload = {
+        "type" => "message",
+        "recipient" => activity.from.to_h,
+        "attachments" => [
+          { "contentType" => "application/vnd.microsoft.card.oauth", "content" => card }
+        ]
+      }
+
+      app.send_activity(sign_in_reference(conversation_id), payload)
+      nil
+    end
+
+    # Clears the user's token for the connection. Failures are logged, not
+    # raised, matching the TypeScript/Python SDKs.
+    def sign_out(connection_name: nil)
+      api.users.sign_out(
+        user_id: activity.from.id,
+        connection_name: connection_name || app.default_connection_name,
+        channel_id: activity.channel_id
+      )
+      nil
+    rescue HttpError => error
+      log&.error("Failed to sign out user: #{error.message}")
+      nil
+    end
+
+    private
+
+    def sign_in_reference(conversation_id)
+      return conversation_reference if conversation_id == conversation_reference.conversation_id
+
+      Api::ConversationReference.from_h(
+        conversation_reference.to_h.merge(
+          "conversation" => conversation_reference.conversation.to_h.merge("id" => conversation_id)
+        )
+      )
+    end
+
+    def incoming_targeted_sender
+      return nil unless activity.message?
+      return nil unless activity.recipient.is_targeted == true
+
+      activity.from
+    end
+
+    def apply_targeted_defaults(activity_or_text)
+      sender = incoming_targeted_sender
+      return activity_or_text unless sender
+
+      body = activity_body(activity_or_text)
+      return activity_or_text unless body
+
+      if body["type"] == "message" && !body["id"] && !body.key?("recipient")
+        body["recipient"] = sender.to_h.merge("isTargeted" => true)
+      end
+
+      return body unless targeted_outbound?(body)
+
+      add_targeted_message_info(body, activity.id)
+      body
+    end
+
+    def targeted_reply?(activity_or_text)
+      return false unless incoming_targeted_sender
+
+      body = activity_body(activity_or_text)
+      return false unless body
+      return false unless body["type"] == "message"
+
+      (!body["id"] && !body.key?("recipient")) || targeted_outbound?(body)
+    end
+
+    def targeted_outbound?(body)
+      body["type"] == "message" && body.dig("recipient", "isTargeted") == true
+    end
+
+    def activity_body(activity_or_text)
+      outbound = normalize_activity(activity_or_text)
+      body = outbound.respond_to?(:to_h) ? outbound.to_h : outbound
+      body.is_a?(Hash) ? body.dup : nil
+    end
+
+    # Hash counterpart of MessageActivity#add_targeted_message_info: strips
+    # quotedReply artifacts and adds the prompt preview entity once.
+    def add_targeted_message_info(body, message_id)
+      entities = Array(body["entities"]).reject do |entity|
+        entity.is_a?(Hash) && entity["type"] == "quotedReply"
+      end
+      body["text"] = body["text"].gsub(%(<quoted messageId="#{message_id}"/>), "").strip if body["text"]
+
+      unless entities.any? { |entity| entity.is_a?(Hash) && entity["type"] == "targetedMessageInfo" }
+        entities << { "type" => "targetedMessageInfo", "messageId" => message_id }
+      end
+
+      body["entities"] = entities
+    end
+
+    def activity_with_id(activity_id, activity_or_text)
+      outbound = normalize_activity(activity_or_text)
+      body = outbound.respond_to?(:to_h) ? outbound.to_h : outbound
+      body.merge("id" => activity_id)
+    end
+
+    def quoted_activity(message_id, activity_or_text)
+      outbound = normalize_activity(activity_or_text)
+      return outbound.prepend_quote(message_id) if outbound.is_a?(Api::MessageActivity)
+
+      body = outbound.respond_to?(:to_h) ? outbound.to_h : outbound
+      return body unless body.is_a?(Hash)
+
+      body = body.dup
+      prepend_quote_to_hash(body, message_id) if body["type"] == "message"
+      body
+    end
+
+    def prepend_quote_to_hash(body, message_id)
+      body["entities"] = Array(body["entities"]) + [
+        Api::QuotedReplyEntity.new("quotedReply" => { "messageId" => message_id }).to_h
+      ]
+      placeholder = %(<quoted messageId="#{message_id}"/>)
+      body["text"] = body["text"].to_s.strip.empty? ? placeholder : "#{placeholder} #{body["text"]}"
+    end
+
+    def normalize_activity(activity_or_text)
+      case activity_or_text
+      when String
+        Api::MessageActivity.new(activity_or_text)
+      when Cards::AdaptiveCard
+        Api::MessageActivity.new.add_card(activity_or_text)
+      when Hash
+        Common::Hashes.deep_stringify_keys(activity_or_text)
+      else
+        activity_or_text
+      end
+    end
+  end
+end

data/lib/teams/api/account.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class Account < Model
+      def id
+        read("id")
+      end
+
+      def name
+        read("name")
+      end
+
+      def aad_object_id
+        read("aadObjectId", "objectId", "aad_object_id")
+      end
+
+      def type
+        read("type")
+      end
+
+      def properties
+        read("properties")
+      end
+
+      def is_targeted
+        read("isTargeted", "is_targeted")
+      end
+
+      def role
+        read("role")
+      end
+
+      def user_role
+        read("userRole", "user_role")
+      end
+
+      def given_name
+        read("givenName", "given_name")
+      end
+
+      def surname
+        read("surname")
+      end
+
+      def email
+        read("email")
+      end
+
+      def user_principal_name
+        read("userPrincipalName", "user_principal_name")
+      end
+
+      def tenant_id
+        read("tenantId", "tenant_id")
+      end
+
+      def to_h
+        body = raw.dup
+        body["id"] = id if id
+        body["name"] = name if name
+        body["aadObjectId"] = aad_object_id if aad_object_id
+        body["type"] = type if type
+        body["properties"] = properties if properties
+        body["isTargeted"] = is_targeted unless is_targeted.nil?
+        body["role"] = role if role
+        body["userRole"] = user_role if user_role
+        body["givenName"] = given_name if given_name
+        body["surname"] = surname if surname
+        body["email"] = email if email
+        body["userPrincipalName"] = user_principal_name if user_principal_name
+        body["tenantId"] = tenant_id if tenant_id
+        remove_aliases(body)
+      end
+
+      private
+
+      def remove_aliases(body)
+        body.delete("objectId")
+        body.delete("aad_object_id")
+        body.delete("is_targeted")
+        body.delete("user_role")
+        body.delete("given_name")
+        body.delete("user_principal_name")
+        body.delete("tenant_id")
+        body
+      end
+    end
+  end
+end

data/lib/teams/api/activity_value.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class ActivityValue < Model
+      # The invoke payload's data, e.g. dialog submit form values plus the
+      # card action's data (dialog_id / action routing keys).
+      def data
+        read("data")
+      end
+
+      # The message extension command that fired (query/submit/fetchTask).
+      def command_id
+        read("commandId", "command_id")
+      end
+
+      # Message extension query parameters: [{"name" => ..., "value" => ...}].
+      def parameters
+        Array(read("parameters"))
+      end
+
+      # Meeting start/end event fields. Teams sends these PascalCase on the
+      # wire (Id, JoinUrl, Title, MeetingType, StartTime, EndTime).
+      def id
+        read("Id", "id")
+      end
+
+      def title
+        read("Title", "title")
+      end
+
+      def meeting_type
+        read("MeetingType", "meetingType", "meeting_type")
+      end
+
+      def join_url
+        read("JoinUrl", "joinUrl", "join_url")
+      end
+
+      def start_time
+        read("StartTime", "startTime", "start_time")
+      end
+
+      def end_time
+        read("EndTime", "endTime", "end_time")
+      end
+    end
+  end
+end

data/lib/teams/api/bot_sign_in_client.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Teams
+  module Api
+    # Bot sign-in resources from the Bot Framework token service, used to
+    # build OAuth cards. Exposed as api.bots.sign_in, following .NET's
+    # non-deprecated Bots client (TypeScript/Python deprecate their bot
+    # client but still call sign-in through it internally).
+    class BotSignInClient
+      attr_reader :oauth_url, :http
+
+      def initialize(oauth_url:, http:, logger: nil)
+        @oauth_url = oauth_url.sub(%r{/+\z}, "")
+        @http = http
+        @logger = logger
+      end
+
+      # Returns the sign-in URL as a plain string.
+      def get_url(state:, code_challenge: nil, emulator_url: nil, final_redirect: nil)
+        url = endpoint("api/botsignin/GetSignInUrl", state:, code_challenge:, emulator_url:, final_redirect:)
+        @logger&.debug("Teams API GET #{url}")
+        http.get(url)
+      end
+
+      def get_resource(state:, code_challenge: nil, emulator_url: nil, final_redirect: nil)
+        url = endpoint("api/botsignin/GetSignInResource", state:, code_challenge:, emulator_url:, final_redirect:)
+        @logger&.debug("Teams API GET #{url}")
+        SignInUrlResponse.new(http.get(url))
+      end
+
+      private
+
+      def endpoint(path, state:, code_challenge:, emulator_url:, final_redirect:)
+        params = {
+          "state" => state,
+          "codeChallenge" => code_challenge,
+          "emulatorUrl" => emulator_url,
+          "finalRedirect" => final_redirect
+        }.compact
+        "#{oauth_url}/#{path}?#{URI.encode_www_form(params)}"
+      end
+    end
+
+    class BotClient
+      attr_reader :sign_in
+
+      def initialize(oauth_url:, http:, logger: nil)
+        @sign_in = BotSignInClient.new(oauth_url:, http:, logger:)
+      end
+    end
+  end
+end

data/lib/teams/api/channel_data.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class ChannelData < Model
+      def tenant
+        wrap(read("tenant"), TenantInfo)
+      end
+
+      def team
+        wrap(read("team"), TeamInfo)
+      end
+
+      def channel
+        wrap(read("channel"), ChannelInfo)
+      end
+
+      def meeting
+        wrap(read("meeting"), MeetingInfo)
+      end
+
+      def notification
+        wrap(read("notification"), NotificationInfo)
+      end
+
+      def event_type
+        read("eventType", "event_type")
+      end
+
+      def settings
+        value = read("settings")
+        value.is_a?(Hash) ? ActivityValue.new(value) : value
+      end
+
+      def feedback_loop_enabled
+        read("feedbackLoopEnabled", "feedback_loop_enabled")
+      end
+
+      def feedback_loop
+        value = read("feedbackLoop", "feedback_loop")
+        value.is_a?(Hash) ? ActivityValue.new(value) : value
+      end
+
+      def stream_id
+        read("streamId", "stream_id")
+      end
+
+      def stream_type
+        read("streamType", "stream_type")
+      end
+
+      def stream_sequence
+        read("streamSequence", "stream_sequence")
+      end
+
+      def to_h
+        body = raw.dup
+        body["tenant"] = tenant.to_h if tenant
+        body["team"] = team.to_h if team
+        body["channel"] = channel.to_h if channel
+        body["meeting"] = meeting.to_h if meeting
+        body["notification"] = notification.to_h if notification
+        body["eventType"] = event_type if event_type
+        body["settings"] = settings.to_h if settings.respond_to?(:to_h)
+        body["feedbackLoopEnabled"] = feedback_loop_enabled unless feedback_loop_enabled.nil?
+        body["feedbackLoop"] = feedback_loop.to_h if feedback_loop.respond_to?(:to_h)
+        body["streamId"] = stream_id if stream_id
+        body["streamType"] = stream_type if stream_type
+        body["streamSequence"] = stream_sequence if stream_sequence
+        body.delete("event_type")
+        body.delete("feedback_loop_enabled")
+        body.delete("feedback_loop")
+        body.delete("stream_id")
+        body.delete("stream_type")
+        body.delete("stream_sequence")
+        body
+      end
+
+      private
+
+      def wrap(value, klass)
+        value ? klass.new(value) : nil
+      end
+    end
+  end
+end

data/lib/teams/api/channel_info.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class ChannelInfo < Model
+      def id
+        read("id")
+      end
+
+      def name
+        read("name")
+      end
+
+      def type
+        read("type")
+      end
+    end
+  end
+end

data/lib/teams/api/citation_appearance.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class CitationAppearance < Model
+      ADAPTIVE_CARD_CONTENT_TYPE = "application/vnd.microsoft.card.adaptive"
+
+      def initialize(raw = nil, name: nil, text: nil, url: nil, abstract: nil, icon: nil, keywords: nil, usage_info: nil)
+        body = raw || {}
+        body = body.to_h if body.respond_to?(:to_h)
+        body = body.merge({
+          "name" => name,
+          "text" => text,
+          "url" => url,
+          "abstract" => abstract,
+          "icon" => icon,
+          "keywords" => keywords,
+          "usageInfo" => usage_info
+        }.compact)
+        super(body)
+      end
+
+      def name
+        read("name")
+      end
+
+      def text
+        read("text")
+      end
+
+      def url
+        read("url")
+      end
+
+      def abstract
+        read("abstract")
+      end
+
+      def icon
+        read("icon")
+      end
+
+      def keywords
+        read("keywords")
+      end
+
+      def usage_info
+        read("usageInfo", "usage_info")
+      end
+
+      def to_h
+        validate!
+
+        body = {
+          "@type" => "DigitalDocument",
+          "name" => name,
+          "abstract" => abstract
+        }
+        body["text"] = text if text
+        body["url"] = url if url
+        body["encodingFormat"] = ADAPTIVE_CARD_CONTENT_TYPE if text && !text.empty?
+        body["image"] = { "@type" => "ImageObject", "name" => icon } if icon
+        body["keywords"] = keywords if keywords
+        body["usageInfo"] = usage_info.to_h if usage_info && usage_info.respond_to?(:to_h)
+        body["usageInfo"] = usage_info if usage_info && !usage_info.respond_to?(:to_h)
+        body
+      end
+
+      private
+
+      def validate!
+        validate_required!("name", name)
+        validate_required!("abstract", abstract)
+      end
+
+      def validate_required!(field, value)
+        return unless value.nil?
+
+        raise ArgumentError, "citation #{field} is required"
+      end
+    end
+  end
+end

data/lib/teams/api/client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Teams
+  module Api
+    class Client
+      attr_reader :service_url, :http
+
+      DEFAULT_OAUTH_URL = "https://token.botframework.com"
+
+      attr_reader :conversations, :teams, :meetings, :users, :bots
+
+      # Sub-clients are constructed eagerly like the other SDKs' ApiClient
+      # constructors, which also keeps the shared client thread-safe.
+      # oauth_url is the Bot Framework token service (cloud-dependent), used
+      # by the user token and bot sign-in clients.
+      def initialize(service_url:, http:, logger: nil, oauth_url: DEFAULT_OAUTH_URL)
+        @service_url = service_url.sub(%r{/+\z}, "")
+        @http = http
+        @logger = logger
+        @conversations = ConversationClient.new(service_url: @service_url, http:, logger:)
+        @teams = TeamClient.new(service_url: @service_url, http:, logger:)
+        @meetings = MeetingClient.new(service_url: @service_url, http:, logger:)
+        @users = UserClient.new(oauth_url:, http:, logger:)
+        @bots = BotClient.new(oauth_url:, http:, logger:)
+      end
+    end
+  end
+end