teams_rb 2.0.1

data/lib/teams/cards/generated_base.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Teams
+  module Cards
+    # Base class for the generated Adaptive Card models. Serialization matches
+    # the other Teams SDKs' generated card classes: non-nil fields (including
+    # defaults) are emitted under their camelCase aliases, unknown extra
+    # fields pass through verbatim.
+    class GeneratedCard
+      OMIT = Object.new.freeze
+
+      class << self
+        def card_fields
+          @card_fields ||= superclass.respond_to?(:card_fields) ? superclass.card_fields.dup : {}
+        end
+
+        def field(name, alias_name, default = nil, mutable: false)
+          card_fields[name] = { alias: alias_name, default:, mutable: }
+
+          define_method(name) { @values[name] }
+          define_method("#{name}=") { |value| @values[name] = value }
+          define_method("with_#{name}") do |value|
+            @values[name] = value
+            self
+          end
+        end
+
+        # Ruby convenience preserved from the original hand-written classes:
+        # allows the first constructor argument to set the given field.
+        def positional_field(name)
+          define_method(:initialize) do |positional = OMIT, **values|
+            values[name] = positional unless positional.equal?(OMIT)
+            super(**values)
+          end
+        end
+
+        # Same, for classes whose hand-written predecessors took a splat.
+        def splat_field(name)
+          define_method(:initialize) do |*positional, **values|
+            values[name] = positional.flatten unless positional.empty?
+            super(**values)
+          end
+        end
+
+        def array_adder(method_name, field_name)
+          define_method(method_name) do |item|
+            (@values[field_name] ||= []) << item
+            self
+          end
+        end
+      end
+
+      def initialize(**values)
+        @values = {}
+        self.class.card_fields.each do |name, spec|
+          @values[name] = if values.key?(name)
+            values.delete(name)
+          elsif spec[:mutable]
+            deep_dup(spec[:default])
+          else
+            spec[:default]
+          end
+        end
+        values.each { |key, value| @values[key] = value }
+      end
+
+      def to_h
+        @values.each_with_object({}) do |(name, value), body|
+          next if value.nil?
+
+          spec = self.class.card_fields[name]
+          body[spec ? spec[:alias] : camelize(name.to_s)] = serialize(value)
+        end
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      private
+
+      def serialize(value)
+        case value
+        when Array
+          value.map { |item| serialize(item) }
+        when Hash
+          value.each_with_object({}) { |(key, item), hash| hash[key.to_s] = serialize(item) }
+        else
+          value.respond_to?(:to_h) && !value.is_a?(Numeric) ? value.to_h : value
+        end
+      end
+
+      def deep_dup(value)
+        Marshal.load(Marshal.dump(value))
+      end
+
+      def camelize(key)
+        parts = key.split("_")
+        parts.first + parts.drop(1).map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/teams/cards.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cards/generated_base"
+
+module Teams
+  module Cards
+    class CardObject
+      attr_reader :options
+
+      def initialize(**options)
+        @options = options
+      end
+
+      def to_h
+        compact_hash(serialize_options(options))
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      def with_options(options = nil, **kwargs)
+        options = (options || {}).merge(kwargs)
+        options.each { |key, value| with_option(key, value) }
+        self
+      end
+
+      private
+
+      def with_option(key, value)
+        options[key] = value
+        self
+      end
+
+      def serialize(value)
+        case value
+        when nil
+          nil
+        when Array
+          value.map { |item| serialize(item) }
+        when Hash
+          serialize_options(value)
+        else
+          value.respond_to?(:to_h) ? value.to_h : value
+        end
+      end
+
+      def serialize_options(values)
+        values.each_with_object({}) do |(key, value), hash|
+          hash[json_key(key)] = serialize(value)
+        end
+      end
+
+      def compact_hash(hash)
+        hash.reject { |_key, value| value.nil? }
+      end
+
+      def json_key(key)
+        return key if key.is_a?(String)
+
+        case key
+        when :schema
+          "$schema"
+        when :choices_data
+          "choices.data"
+        when :grid_area
+          "grid.area"
+        else
+          camelize(key)
+        end
+      end
+
+      def camelize(key)
+        parts = key.to_s.split("_")
+        parts.first + parts.drop(1).map(&:capitalize).join
+      end
+    end
+
+  end
+end

data/lib/teams/cloud_environment.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Teams
+  CloudEnvironment = Struct.new(
+    :login_endpoint,
+    :login_tenant,
+    :bot_scope,
+    :token_service_url,
+    :open_id_metadata_url,
+    :token_issuer,
+    :graph_scope,
+    keyword_init: true
+  )
+
+  PUBLIC_CLOUD = CloudEnvironment.new(
+    login_endpoint: "https://login.microsoftonline.com",
+    login_tenant: "botframework.com",
+    bot_scope: "https://api.botframework.com/.default",
+    token_service_url: "https://token.botframework.com",
+    open_id_metadata_url: "https://login.botframework.com/v1/.well-known/openidconfiguration",
+    token_issuer: "https://api.botframework.com",
+    graph_scope: "https://graph.microsoft.com/.default"
+  )
+
+  module CloudEnvironments
+    module_function
+
+    def public
+      PUBLIC_CLOUD
+    end
+
+    def from_name(name)
+      case name.to_s.downcase
+      when "", "public"
+        public
+      else
+        raise ConfigurationError, "unsupported cloud environment: #{name.inspect}"
+      end
+    end
+  end
+end

data/lib/teams/common/hashes.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Teams
+  module Common
+    module Hashes
+      module_function
+
+      def deep_stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, item), hash| hash[key.to_s] = deep_stringify_keys(item) }
+        when Array
+          value.map { |item| deep_stringify_keys(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/teams/common/http_client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Teams
+  module Common
+    class HttpClient
+      attr_reader :base_url, :headers, :token
+
+      def initialize(base_url: nil, headers: {}, token: nil, connection: nil)
+        @base_url = base_url
+        @headers = headers
+        @token = token
+        @connection = connection
+      end
+
+      def get(path, headers: {}, params: nil)
+        request(:get, path, headers:, params:)
+      end
+
+      def post(path, json: nil, body: nil, headers: {}, params: nil)
+        request(:post, path, json:, body:, headers:, params:)
+      end
+
+      def patch(path, json: nil, body: nil, headers: {}, params: nil)
+        request(:patch, path, json:, body:, headers:, params:)
+      end
+
+      def put(path, json: nil, body: nil, headers: {}, params: nil)
+        request(:put, path, json:, body:, headers:, params:)
+      end
+
+      def delete(path, headers: {}, params: nil)
+        request(:delete, path, headers:, params:)
+      end
+
+      def request(method, path, json: nil, body: nil, headers: {}, params: nil)
+        resolved_token = resolve_token
+        response = connection.public_send(method) do |request|
+          request.url(path)
+          request.params.update(params) if params
+          request.headers.update(default_headers)
+          request.headers.update(headers)
+          request.headers["Authorization"] = "Bearer #{resolved_token}" if resolved_token
+
+          if json
+            request.headers["Content-Type"] ||= "application/json"
+            request.body = JSON.generate(json)
+          elsif body
+            request.body = body
+          end
+        end
+
+        parse_response(response)
+      end
+
+      def clone(base_url: nil, headers: nil, token: nil)
+        self.class.new(
+          base_url: base_url || self.base_url,
+          headers: self.headers.merge(headers || {}),
+          token: token || self.token,
+          connection: @connection
+        )
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: base_url) do |faraday|
+          # Flat params: arrays encode as repeated plain keys (a=1&a=2),
+          # the shape the Bot Framework token service expects.
+          faraday.options.params_encoder = Faraday::FlatParamsEncoder
+          faraday.adapter Faraday.default_adapter
+        end
+      end
+
+      def default_headers
+        { "User-Agent" => "teams_rb/#{Teams::VERSION}" }.merge(headers)
+      end
+
+      def resolve_token
+        @resolved_token = token.respond_to?(:call) ? token.call : token
+      end
+
+      def parse_response(response)
+        body = response.body.to_s
+        parsed = begin
+          body.empty? ? nil : JSON.parse(body)
+        rescue JSON::ParserError
+          body
+        end
+
+        if response.status < 200 || response.status >= 300
+          message = "HTTP request failed with status #{response.status}"
+          message = "#{message}: #{parsed}" if parsed && parsed != ""
+
+          raise HttpError.new(
+            message,
+            status: response.status,
+            headers: response.headers,
+            body: parsed || body,
+            request: response.env&.request
+          )
+        end
+
+        parsed
+      end
+    end
+  end
+end

data/lib/teams/common/retry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Teams
+  module Common
+    module Retry
+      module_function
+
+      # Retries the block with exponential backoff, mirroring the retry
+      # helpers the TypeScript and Python SDKs use for stream sends.
+      # jitter :full randomizes each wait between 0 and the capped delay;
+      # :none waits the capped delay exactly.
+      def call(max_attempts: 5, delay: 0.5, max_delay: 30.0, jitter: :full, non_retryable: [], logger: nil)
+        attempt = 1
+        begin
+          yield
+        rescue *non_retryable
+          raise
+        rescue StandardError => error
+          raise if attempt >= max_attempts
+
+          capped = [delay * (2**(attempt - 1)), max_delay].min
+          wait = jitter == :full ? rand * capped : capped
+          logger&.debug("retrying in #{format('%.2f', wait)}s (attempt #{attempt}/#{max_attempts}): #{error.message}")
+          sleep(wait)
+          attempt += 1
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/teams/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Teams
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class AuthenticationError < Error; end
+
+  class BadRequestError < Error; end
+
+  # Raised when Teams cancels a stream (for example, the user pressed Stop)
+  # or when a stream operation is attempted after cancellation.
+  class StreamCancelledError < Error; end
+
+  # Base class for terminal streaming errors (HTTP 403) that should not be retried.
+  # https://learn.microsoft.com/en-us/microsoftteams/platform/bots/streaming-ux?tabs=csharp#error-codes
+  class TerminalStreamError < Error; end
+
+  # Raised when the bot failed to complete streaming within the two-minute limit.
+  class StreamTimedOutError < TerminalStreamError; end
+
+  # Raised when streaming is not allowed for this user or bot.
+  class StreamNotAllowedError < TerminalStreamError; end
+
+  # A failed Microsoft Graph request; code carries the Graph error code
+  # (e.g. "Authorization_RequestDenied") and body the full error payload.
+  class GraphError < Error
+    attr_reader :status, :code, :body
+
+    def initialize(message, status:, code: nil, body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @body = body
+    end
+  end
+
+  class HttpError < Error
+    attr_reader :status, :headers, :body, :request
+
+    def initialize(message, status:, headers:, body:, request: nil)
+      super(message)
+      @status = status
+      @headers = headers
+      @body = body
+      @request = request
+    end
+  end
+end

data/lib/teams/function_context.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Teams
+  # Context for a remote function call from a tab (POST /api/functions/{name}):
+  # the validated Entra identity, the Teams client context headers, and the
+  # request payload.
+  class FunctionContext
+    attr_reader :app, :function_name, :data, :app_session_id, :page_id, :auth_token,
+      :tenant_id, :user_id, :user_name, :app_id, :channel_id, :chat_id,
+      :meeting_id, :message_id, :sub_page_id, :team_id
+
+    def initialize(app:, function_name:, data:, app_session_id:, page_id:, auth_token:,
+                   tenant_id:, user_id:, user_name:, app_id: nil, channel_id: nil,
+                   chat_id: nil, meeting_id: nil, message_id: nil, sub_page_id: nil, team_id: nil)
+      @app = app
+      @function_name = function_name
+      @data = data
+      @app_session_id = app_session_id
+      @page_id = page_id
+      @auth_token = auth_token
+      @tenant_id = tenant_id
+      @user_id = user_id
+      @user_name = user_name
+      @app_id = app_id
+      @channel_id = channel_id
+      @chat_id = chat_id
+      @meeting_id = meeting_id
+      @message_id = message_id
+      @sub_page_id = sub_page_id
+      @team_id = team_id
+      @resolved = false
+    end
+
+    def api
+      app.api
+    end
+
+    def log
+      app.logger
+    end
+
+    # Resolves the conversation this call relates to, like the TypeScript and
+    # Python function contexts: chat/channel id when the user is a member of
+    # it; in personal scope, creates (or re-fetches) the 1:1 conversation.
+    # Returns nil when no conversation can be resolved.
+    def conversation_id
+      return @conversation_id if @resolved
+
+      @resolved = true
+      @conversation_id = resolve_conversation_id
+    end
+
+    # Posts into the resolved conversation (proactive send with the bot's
+    # identity).
+    def post(activity_or_text)
+      id = conversation_id
+      raise Error, "Unable to resolve a conversation for this function call" unless id
+
+      app.post(id, activity_or_text)
+    end
+
+    private
+
+    def resolve_conversation_id
+      existing = chat_id || channel_id
+
+      if existing.nil?
+        conversation = api.conversations.create(
+          members: [{ "id" => user_id, "role" => "user", "name" => user_name }],
+          tenant_id: tenant_id
+        )
+        return conversation.id
+      end
+
+      member = api.conversations.get_member_by_id(existing, user_id)
+      member ? existing : nil
+    rescue HttpError => error
+      log&.warn("Could not resolve conversation for function call: #{error.message}")
+      nil
+    end
+  end
+end

data/lib/teams/graph/client.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Teams
+  module Graph
+    # Thin Microsoft Graph HTTP client, following the TypeScript SDK's core
+    # Graph client (Python/.NET delegate to the official Graph SDKs, which
+    # Ruby lacks a maintained equivalent of; TypeScript's generated endpoint
+    # packages are out of scope, so the raw request surface is the API here,
+    # like TypeScript's client.http escape hatch).
+    class Client
+      DEFAULT_BASE_URL_ROOT = "https://graph.microsoft.com"
+
+      attr_reader :base_url_root, :version, :http
+
+      # token: a string or a callable returning one (an app-only Graph token
+      # or a user token from sign-in). base_url_root overrides the Graph host
+      # for sovereign clouds (e.g. "https://graph.microsoft.us").
+      def initialize(token:, base_url_root: nil, version: "v1.0", http: nil)
+        @base_url_root = (base_url_root || DEFAULT_BASE_URL_ROOT).sub(%r{/+\z}, "")
+        @version = version
+        @http = http || Common::HttpClient.new(token:)
+      end
+
+      def get(path, params: nil)
+        request { http.get(url(path), params:) }
+      end
+
+      def post(path, json: nil, params: nil)
+        request { http.post(url(path), json: stringify(json), params:) }
+      end
+
+      def patch(path, json: nil, params: nil)
+        request { http.patch(url(path), json: stringify(json), params:) }
+      end
+
+      def put(path, json: nil, params: nil)
+        request { http.put(url(path), json: stringify(json), params:) }
+      end
+
+      def delete(path, params: nil)
+        request { http.delete(url(path), params:) }
+      end
+
+      private
+
+      def request
+        yield
+      rescue HttpError => error
+        graph_error = error.body.is_a?(Hash) ? error.body["error"] : nil
+        message = if graph_error.is_a?(Hash) && graph_error["message"]
+          "Graph request failed (#{error.status}): #{graph_error["message"]}"
+        else
+          "Graph request failed with status #{error.status}"
+        end
+
+        raise GraphError.new(
+          message,
+          status: error.status,
+          code: graph_error.is_a?(Hash) ? graph_error["code"] : nil,
+          body: error.body
+        )
+      end
+
+      def url(path)
+        "#{base_url_root}/#{version}/#{path.to_s.sub(%r{\A/+}, "")}"
+      end
+
+      def stringify(json)
+        json.is_a?(Hash) ? Common::Hashes.deep_stringify_keys(json) : json
+      end
+    end
+  end
+end