teams_rb 2.0.1

data/docs/in-depth-guides/adaptive-cards.md

@@ -0,0 +1,62 @@
+# Adaptive Cards
+
+`Teams::Cards` provides typed builders for all 112 Adaptive Card element classes. They're generated from the Microsoft SDK's own card model, so they serialize to exactly the same JSON — including the host-specific defaults the Teams client expects.
+
+## Building a card
+
+```ruby
+C = Teams::Cards
+
+card = C::AdaptiveCard.new(
+  C::TextBlock.new("Weekly report", size: "Large", weight: "Bolder"),
+  C::TextBlock.new("Everything is on track.", wrap: true),
+  C::FactSet.new(facts: [
+    C::Fact.new(title: "Status", value: "Green"),
+    C::Fact.new(title: "Owner", value: "Devran")
+  ]),
+  actions: [
+    C::OpenUrlAction.new("https://example.com", title: "Details"),
+    C::SubmitAction.new(title: "Acknowledge", data: { "action" => "ack" })
+  ]
+)
+
+ctx.post Teams::Api::MessageActivity.new.add_card(card)
+```
+
+Constructors take positional children where it reads naturally (a `TextBlock`'s text, a card's body elements) and keyword arguments for properties. Ruby conveniences like `add_item` / `add_action` / `add_choice` are available alongside the constructor forms.
+
+## Sending cards
+
+```ruby
+ctx.post card          # card as the sole attachment
+ctx.reply card
+ctx.post Teams::Api::MessageActivity.new("See attached").add_card(card)
+```
+
+A raw Hash works too, as an escape hatch — `add_card({ "type" => "AdaptiveCard", ... })`.
+
+## Actions and submissions
+
+`SubmitAction` data comes back as a message activity with no text and the data in `ctx.activity.value` — **answer it with `post`, never `reply`** (quoting the invisible submit activity is rejected by Teams):
+
+```ruby
+teams.on_message do |ctx, nxt|
+  next nxt.call unless ctx.activity.text.nil? && ctx.activity.raw["value"]
+  ctx.post "Got: #{ctx.activity.raw["value"].inspect}"
+end
+```
+
+For richer action flows — opening a modal form from a card button — see [Dialogs](dialogs.md).
+
+## Regenerating
+
+The card classes are generated; don't hand-edit `lib/teams/cards/generated.rb`. To regenerate after an upstream card-model change:
+
+```sh
+bundle exec rake cards:generate   # reads a sibling teams.py checkout; TEAMS_PY_PATH overrides
+bundle exec rake test             # golden tests assert byte-identical serialization
+```
+
+## A note on validation
+
+Cards serialize faithfully but the SDK does not validate field values — invalid values pass straight through, exactly as raw hashes would. One live gotcha worth knowing: `CodeBlock`'s `language` is a server-side enum; unlisted values (including "Ruby") are rejected — use `"PlainText"`.

data/docs/in-depth-guides/dialogs.md

@@ -0,0 +1,77 @@
+# Dialogs (task modules)
+
+Dialogs are modal forms opened from a card action. A card button carrying `msteams: { type: "task/fetch" }` triggers a `task/fetch` invoke; the bot answers with the dialog content; the user's submission arrives as `task/submit`.
+
+## Opening a dialog
+
+The launcher card's action carries a reserved `dialog_id`:
+
+```ruby
+teams.on_message(/^form$/i) do |ctx|
+  ctx.post Teams::Api::MessageActivity.new.add_card(
+    Teams::Cards::AdaptiveCard.new(
+      Teams::Cards::TextBlock.new("Open the form"),
+      actions: [Teams::Cards::SubmitAction.new(
+        title: "Open",
+        data: { "msteams" => { "type" => "task/fetch" }, "dialog_id" => "simple_form" }
+      )]
+    )
+  )
+end
+```
+
+Handle the open by returning the dialog:
+
+```ruby
+teams.on_dialog_open("simple_form") do |ctx|
+  Teams::Api::TaskModuleResponse.new(
+    Teams::Api::TaskModuleContinueResponse.new(
+      Teams::Api::TaskModuleTaskInfo.new(
+        title: "Simple form",
+        card: {
+          "type" => "AdaptiveCard", "version" => "1.4",
+          "body" => [{ "type" => "Input.Text", "id" => "name", "label" => "Name", "isRequired" => true }],
+          "actions" => [{ "type" => "Action.Submit", "title" => "Submit", "data" => { "action" => "submit_simple_form" } }]
+        }
+      )
+    )
+  )
+end
+```
+
+`on_dialog_open(dialog_id)` matches only that dialog; `on_dialog_open` with no argument matches all. `TaskModuleTaskInfo` accepts `card:` (an `AdaptiveCard`, card hash, or attachment) **or** `url:` for a webpage dialog, plus `title:`, `height:`/`width:` (`"small"`/`"medium"`/`"large"` or pixels).
+
+## Handling submissions
+
+```ruby
+teams.on_dialog_submit("submit_simple_form") do |ctx|
+  name = ctx.activity.value.data["name"]
+  ctx.post "Hi #{name}, thanks!"
+  Teams::Api::TaskModuleResponse.new(Teams::Api::TaskModuleMessageResponse.new("Submitted"))
+end
+```
+
+Return a `TaskModuleMessageResponse` to close the dialog with a message. `on_dialog_submit(action)` filters on the reserved `action` value in the submit data.
+
+## Multi-step forms
+
+Return another `TaskModuleContinueResponse` from a submit handler to advance to the next step — pass state forward in the next card's action data:
+
+```ruby
+teams.on_dialog_submit("step_1") do |ctx|
+  name = ctx.activity.value.data["name"]
+  Teams::Api::TaskModuleResponse.new(
+    Teams::Api::TaskModuleContinueResponse.new(
+      Teams::Api::TaskModuleTaskInfo.new(
+        title: "Step 2",
+        card: {
+          "type" => "AdaptiveCard", "version" => "1.4",
+          "body" => [{ "type" => "Input.Text", "id" => "email", "label" => "Email" }],
+          "actions" => [{ "type" => "Action.Submit", "title" => "Finish",
+                          "data" => { "action" => "step_2", "name" => name } }]
+        }
+      )
+    )
+  )
+end
+```

data/docs/in-depth-guides/feedback.md

@@ -0,0 +1,29 @@
+# Feedback
+
+Add thumbs up/down feedback buttons to a bot message — the standard way to collect quality signals on AI answers.
+
+## Requesting feedback
+
+```ruby
+ctx.post Teams::Api::MessageActivity.new("Here's my answer.")
+  .add_ai_generated
+  .add_feedback
+```
+
+`add_feedback` enables the default feedback UI on the message. Teams renders the thumbs on hover; when a user submits feedback, your bot receives a `message/submitAction` invoke.
+
+## Handling submissions
+
+```ruby
+teams.on_message_submit_feedback do |ctx|
+  value = ctx.activity.value.raw
+  FeedbackRecord.create!(
+    reply_to: ctx.activity.raw["replyToId"],        # the message being rated
+    reaction: value.dig("actionValue", "reaction"),  # "like" / "dislike"
+    text: value.dig("actionValue", "feedback")       # free-text, JSON-encoded by some clients
+  )
+  nil
+end
+```
+
+The rated message's id arrives as the invoke's `replyToId` — store your messages' `SentActivity#id`s if you need to join feedback back to content. `on_message_submit` (without the filter) catches every `message/submitAction` invoke, matching the TypeScript/Python route pair.

data/docs/in-depth-guides/meeting-events.md

@@ -0,0 +1,27 @@
+# Meeting events
+
+When a bot is installed in a meeting chat, Teams posts event activities as the meeting starts and ends.
+
+```ruby
+teams.on_meeting_start do |ctx|
+  v = ctx.activity.value
+  ctx.post "#{v.title} started at #{v.start_time}"
+end
+
+teams.on_meeting_end do |ctx|
+  ctx.post "Meeting ended at #{ctx.activity.value.end_time}"
+end
+```
+
+The event value is available on `ctx.activity.value`, with readers matching the wire fields (which Teams sends PascalCase):
+
+| Reader | Field | Notes |
+|---|---|---|
+| `id` | `Id` | Base64-encoded meeting id |
+| `title` | `Title` | Meeting title |
+| `meeting_type` | `MeetingType` | e.g. `"Scheduled"` |
+| `join_url` | `JoinUrl` | Join link (start event) |
+| `start_time` | `StartTime` | UTC timestamp (start event) |
+| `end_time` | `EndTime` | UTC timestamp (end event) |
+
+For meeting details and participant lookup outside events, use the [meetings API client](../essentials/api-client.md#teams-and-meetings).

data/docs/in-depth-guides/message-extensions.md

@@ -0,0 +1,77 @@
+# Message extensions
+
+Message extensions (compose extensions) add search boxes, action commands, and link unfurling to the Teams compose area. The commands are declared in the app manifest; the SDK routes the `composeExtension/*` invokes to named handlers whose return values become the invoke response.
+
+> The manifest commands must be added in the classic Developer Portal view or the app package editor — the new Developer Portal UI currently lacks the message-extension commands editor.
+
+## Search commands
+
+A search box in the compose area. Return a `MessagingExtensionResponse` wrapping a result list; each attachment can carry a preview card:
+
+```ruby
+teams.on_message_ext_query do |ctx|
+  query = ctx.activity.value.parameters.find { |p| p["name"] == "searchQuery" }&.dig("value")
+  attachments = Item.search(query).map do |item|
+    Teams::Api::MessagingExtensionAttachment.new(
+      content_type: "application/vnd.microsoft.card.adaptive",
+      content: item.to_card,
+      preview: { "contentType" => "application/vnd.microsoft.card.thumbnail",
+                 "content" => { "title" => item.title } }
+    )
+  end
+
+  Teams::Api::MessagingExtensionResponse.new(
+    Teams::Api::MessagingExtensionResult.new(type: "result", attachment_layout: "list", attachments: attachments)
+  )
+end
+```
+
+`on_message_ext_select_item` handles clicking a result when you return lightweight items and expand on selection.
+
+## Action commands
+
+An action command opens a dialog (via `fetchTask`) and then handles the submission — returning a `MessagingExtensionActionResponse`, which reuses the [dialog](dialogs.md) task-module responses:
+
+```ruby
+teams.on_message_ext_open do |ctx|
+  Teams::Api::MessagingExtensionActionResponse.new(
+    task: Teams::Api::TaskModuleContinueResponse.new(
+      Teams::Api::TaskModuleTaskInfo.new(title: "Create", card: create_form_card)
+    )
+  )
+end
+
+teams.on_message_ext_submit do |ctx|
+  item = Item.create!(title: ctx.activity.value.data["title"])
+  Teams::Api::MessagingExtensionActionResponse.new(
+    compose_extension: Teams::Api::MessagingExtensionResult.new(
+      type: "result", attachment_layout: "list",
+      attachments: [Teams::Api::MessagingExtensionAttachment.new(
+        content_type: "application/vnd.microsoft.card.adaptive", content: item.to_card
+      )]
+    )
+  )
+end
+```
+
+## Link unfurling
+
+When a user pastes a URL from a domain your manifest registers, Teams sends a `composeExtension/queryLink` invoke — return a card preview for it:
+
+```ruby
+teams.on_message_ext_query_link do |ctx|
+  url = ctx.activity.value.raw["url"]
+  Teams::Api::MessagingExtensionResponse.new(
+    Teams::Api::MessagingExtensionResult.new(
+      type: "result", attachment_layout: "list",
+      attachments: [Teams::Api::MessagingExtensionAttachment.new(
+        content_type: "application/vnd.microsoft.card.adaptive", content: unfurl_card(url)
+      )]
+    )
+  )
+end
+```
+
+## All routes
+
+`on_message_ext_query`, `on_message_ext_select_item`, `on_message_ext_submit`, `on_message_ext_open`, `on_message_ext_query_link`, `on_message_ext_anon_query_link`, `on_message_ext_query_settings_url`, `on_message_ext_setting`, `on_message_ext_card_button_clicked` — the same nine the TypeScript and Python SDKs expose. The inbound command and parameters read from `ctx.activity.value` (`command_id`, `parameters`, `data`).

data/docs/in-depth-guides/message-reactions.md

@@ -0,0 +1,29 @@
+# Message reactions
+
+## Reacting to messages
+
+The bot can add and remove reactions on any message via the API client:
+
+```ruby
+teams.on_message do |ctx|
+  ctx.api.conversations.add_reaction(ctx.ref.conversation_id, ctx.activity.id, "like")
+end
+
+api.conversations.delete_reaction(conversation_id, activity_id, "like")
+```
+
+Reaction types: `like`, `heart`, `laugh`, `surprised`, `sad`, `angry`.
+
+## Receiving reactions
+
+When a user reacts to one of the bot's messages, Teams sends a `messageReaction` activity. Route it with the activity-type escape hatch:
+
+```ruby
+teams.on("messageReaction") do |ctx|
+  added = Array(ctx.activity.raw["reactionsAdded"]).map { |r| r["type"] }
+  removed = Array(ctx.activity.raw["reactionsRemoved"]).map { |r| r["type"] }
+  ctx.log.info("reactions +#{added.inspect} -#{removed.inspect} on #{ctx.activity.raw["replyToId"]}")
+end
+```
+
+The reacted-to message's id arrives as `replyToId`. Reaction activities carry no `text` and need no response — return nothing.

data/docs/in-depth-guides/observability.md

@@ -0,0 +1,28 @@
+# Observability
+
+## Logging
+
+The app logs to the `logger:` you pass (stdout by default). At debug level it logs every inbound activity (type, invoke name, id, matched route count) and every API request; at warn level it logs rejected requests (invalid JSON, auth failures) and OAuth/streaming issues; handler errors log at error level before the 500 response.
+
+```ruby
+teams = Teams::App.new(logger: Rails.logger)
+```
+
+Inside handlers, `ctx.log` is that same logger.
+
+## Middleware
+
+`use` wraps every activity — the place for timing, request ids, structured context, or short-circuiting. The second block parameter continues the chain:
+
+```ruby
+teams.use do |ctx, nxt|
+  ctx.log.info("→ #{ctx.activity.type} from #{ctx.activity.from&.id}")
+  nxt.call
+end
+```
+
+Middleware runs before route handlers; omit `nxt.call` to stop processing (e.g. to drop an activity). See [Listening to activities](../essentials/on-activity.md#middleware) for the ordering rules.
+
+## Health
+
+The messaging endpoint returns `401` to unauthenticated requests once credentials are configured — a simple external signal that the app is up and validating. A `POST /api/messages` with an empty body is the cheapest probe.

data/docs/in-depth-guides/streaming.md

@@ -0,0 +1,52 @@
+# Streaming
+
+Stream a response in chunks — the "typing then progressively filling in" experience used for AI answers. `ctx.stream` handles the Teams streaming protocol; you just emit.
+
+## Emitting
+
+```ruby
+teams.on_message do |ctx|
+  ctx.stream.update "Thinking..."     # informative status line (visible above the response)
+  answer_tokens.each { |t| ctx.stream.emit(t) }
+  # the stream finalizes automatically when the handler returns
+end
+```
+
+- `emit(text)` appends to the streamed message.
+- `update(text)` sends an informative status update (shown before content starts).
+- `clear_text` discards accumulated text — e.g. to replace streamed text with a final card.
+- `close` finalizes explicitly; it's called for you when the handler returns.
+
+Emits are queued and flushed by a background thread, matching the TypeScript and Python streamers: rapid emits coalesce into fewer chunks (spaced to respect Teams rate limits), and `close` waits for the queue to drain before sending the final message.
+
+## Final message metadata
+
+The final streamed message can carry the same enrichment as a normal message:
+
+```ruby
+ctx.stream.emit "Here's the summary. "
+ctx.stream.emit Teams::Api::MessageActivity.new.add_ai_generated
+```
+
+## Events
+
+```ruby
+ctx.stream.on_chunk { |sent| ctx.log.debug("chunk #{sent.id}") }
+ctx.stream.on_close { |sent| Analytics.record_stream(sent.id) }
+```
+
+`on_chunk` fires with the `SentActivity` of each shipped chunk; `on_close` fires once with the final `SentActivity`. Handlers persist across stream reuse.
+
+## Reuse and typed errors
+
+Emitting again after `close` starts a **new** streamed message on the same stream. If Teams stops a stream, the SDK raises typed errors:
+
+- `Teams::StreamCancelledError` — the user cancelled (sticky: the next `emit` also raises)
+- `Teams::StreamNotAllowedError`, `Teams::TerminalStreamError` — terminal failures
+
+Chunk-send errors are recorded on the stream and surface when `close` sends the final message. A stream that exceeds the Teams two-minute limit finalizes automatically by updating the streamed message in place.
+
+## Gotchas
+
+- The Teams client renders **only one** streamed message per inbound turn well; use reuse deliberately.
+- A **card-only** stream (no text ever emitted) sends nothing, matching the other SDKs — emit text chunks first, then `clear_text` and emit the card as the final message.

data/docs/in-depth-guides/tabs.md

@@ -0,0 +1,59 @@
+# Tabs and remote functions
+
+A tab is a web page hosted inside Teams. Serve the page from your own app (Rails route, `public/`, any host) — the SDK doesn't host pages, since your framework already does that better. What the SDK provides is **remote functions**: authenticated endpoints your tab's JavaScript calls to reach the bot backend as the signed-in user.
+
+## Registering a function
+
+```ruby
+teams.on_function("create-ticket") do |ctx|
+  ticket = Ticket.create!(title: ctx.data["title"], creator_oid: ctx.user_id)
+  ctx.post "#{ctx.user_name} created ticket ##{ticket.id} from the tab"
+  { "id" => ticket.id }
+end
+```
+
+This serves `POST /api/functions/create-ticket`. The handler receives a `FunctionContext`:
+
+- `ctx.data` — the parsed JSON request body
+- `ctx.user_id`, `ctx.tenant_id`, `ctx.user_name` — from the validated Entra token
+- `ctx.chat_id`, `ctx.channel_id`, `ctx.meeting_id`, `ctx.team_id`, `ctx.page_id`, `ctx.app_session_id` — from the `X-Teams-*` client-context headers
+- `ctx.conversation_id` — resolves the conversation (validating membership; creating the 1:1 in personal scope)
+- `ctx.post` — sends into the resolved conversation proactively
+
+The handler's return value becomes the JSON response body.
+
+## Validation
+
+Every call is validated like the TypeScript/Python SDKs: required `X-Teams-App-Session-Id` / `X-Teams-Page-Id` / bearer headers, the Entra token verified against your app registration (client id audience forms, tenant issuer), and the `oid`/`tid`/`name` claims. Invalid requests get a `401` with a `detail` message; unregistered names get a `404`.
+
+## Calling from the tab
+
+The tab page acquires a token through the Teams JS SDK and posts it with the client-context headers:
+
+```js
+const token = await microsoftTeams.authentication.getAuthToken();
+const context = await microsoftTeams.app.getContext();
+
+await fetch("/api/functions/create-ticket", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "Authorization": "Bearer " + token,
+    "X-Teams-App-Session-Id": context.app.sessionId,
+    "X-Teams-Page-Id": context.page.id,
+    ...(context.chat?.id ? { "X-Teams-Chat-Id": context.chat.id } : {})
+  },
+  body: JSON.stringify({ title: "New ticket" })
+});
+```
+
+## SSO setup
+
+Tab SSO needs an **Application ID URI whose domain matches the tab's origin**, with `requestedAccessTokenVersion: 2` on the app registration:
+
+- Application ID URI: `api://<your-tab-domain>/<app-id>` (a distinct path suffix like `/<app-id>/tab` avoids collisions if the base URI is taken)
+- Pre-authorize the two Teams client app ids (`1fec8e78-bce4-4aaf-ab1b-5451cc387264`, `5e3ce6c0-2b1f-4285-8d4b-75ee78787346`) on the exposed `access_as_user` scope
+- Manifest `webApplicationInfo.resource` must match the Application ID URI exactly
+- Manifest `staticTabs` entry points `contentUrl` at your page
+
+> Watch for **duplicate app registrations** — the Developer Portal can create a second one; make sure the SSO configuration lands on the registration whose client id your bot uses.

data/docs/in-depth-guides/user-authentication.md

@@ -0,0 +1,60 @@
+# User authentication
+
+Sign a user in and act as them — call Microsoft Graph, your own API, anything needing their delegated token. Built on an OAuth connection configured on the bot's Azure registration.
+
+## Azure setup
+
+User auth needs an **OAuth connection setting**, which lives only on an **Azure Bot resource** — a Developer Portal bot registration has no place for it. If your bot was created in the Developer Portal, migrate it: delete the Developer Portal bot registration, create an Azure Bot resource with **"Use existing app registration"** and the same app id, then re-set the messaging endpoint and re-enable the Teams channel. The app id never changes, so Teams sees no difference.
+
+Then on the Azure Bot's Configuration blade → **Add OAuth Connection Settings**:
+
+- **Name** — match `default_connection_name` (default `"graph"`)
+- **Service Provider** — Azure Active Directory v2
+- **Client id / secret** — reuse the bot's own credentials
+- **Tenant ID** — your tenant
+- **Scopes** — e.g. `openid profile User.Read`
+
+And in the Entra app registration: add the Web redirect URI `https://token.botframework.com/.auth/web/redirect`, plus the delegated permissions your scopes name. Use **Test Connection** on the saved setting to confirm before touching code.
+
+## The flow
+
+```ruby
+teams = Teams::App.new(default_connection_name: "graph")
+
+teams.on_message(/^login$/i) do |ctx|
+  token = ctx.sign_in
+  ctx.reply "Already signed in!" if token   # nil means a card was sent
+end
+
+teams.on_sign_in do |ctx, token_response|
+  ctx.post "Welcome! You're signed in."
+end
+```
+
+`ctx.sign_in` returns the token when the user is already signed in; otherwise it sends an OAuth card (to a 1:1 conversation when invoked from a group chat) and returns `nil`. The SDK's **default handlers** then complete the sign-in invokes automatically — both the interactive card path (`signin/verifyState`) and silent SSO (`signin/tokenExchange`) — and fire `on_sign_in`. You don't handle the invokes yourself.
+
+`ctx.sign_out` clears the stored token.
+
+## Using the token
+
+Most often through the [user Graph client](../essentials/graph.md):
+
+```ruby
+teams.on_sign_in do |ctx, _token|
+  me = ctx.user_graph.get("/me")
+  ctx.post "Hello #{me["displayName"]}"
+end
+```
+
+Or the raw token from the token service:
+
+```ruby
+response = ctx.api.users.get_token(
+  user_id: ctx.activity.from.id, connection_name: "graph", channel_id: ctx.activity.channel_id
+)
+response.token   # the delegated access token
+```
+
+## Custom invoke handling
+
+The defaults run first; handlers you register on `on_signin_verify_state` / `on_signin_token_exchange` / `on_signin_failure` run **after** them, for custom behavior. Don't fetch the token yourself in a verify-state handler — the magic code is single-use and the default already consumed it.

data/lib/teams/activity.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Teams
+  class Activity
+    attr_reader :raw
+
+    def initialize(raw = {})
+      @raw = normalize_hash(raw)
+    end
+
+    def type
+      raw["type"]
+    end
+
+    def name
+      raw["name"]
+    end
+
+    def text
+      raw["text"]
+    end
+
+    def id
+      raw["id"]
+    end
+
+    def reply_to_id
+      raw["replyToId"] || raw["reply_to_id"]
+    end
+
+    def service_url
+      raw["serviceUrl"] || raw["service_url"]
+    end
+
+    def channel_id
+      raw["channelId"] || raw["channel_id"]
+    end
+
+    def locale
+      raw["locale"]
+    end
+
+    def local_timestamp
+      raw["localTimestamp"] || raw["local_timestamp"]
+    end
+
+    def channel_data
+      Api::ChannelData.new(raw["channelData"] || raw["channel_data"] || {})
+    end
+
+    def from
+      Api::Account.new(raw["from"] || {})
+    end
+
+    def recipient
+      Api::Account.new(raw["recipient"] || {})
+    end
+
+    def conversation
+      Api::ConversationAccount.new(raw["conversation"] || {})
+    end
+
+    def value
+      value = raw["value"]
+      value.is_a?(Hash) ? Api::ActivityValue.new(value) : value
+    end
+
+    def entities
+      Array(raw["entities"])
+    end
+
+    def get_quoted_messages
+      entities
+        .select { |entity| entity.is_a?(Hash) && entity["type"] == "quotedReply" }
+        .map { |entity| Api::QuotedReplyEntity.new(entity) }
+    end
+
+    def get_mentions
+      entities.select { |entity| entity.is_a?(Hash) && entity["type"] == "mention" }
+    end
+
+    def get_account_mention(account_id)
+      get_mentions.find { |mention| mention.dig("mentioned", "id") == account_id }
+    end
+
+    def recipient_mentioned?
+      !get_account_mention(recipient.id).nil?
+    end
+
+    # Returns the text with "<at>...</at>" mention tokens removed, without
+    # mutating the raw activity. With tag_only, only the tags are removed and
+    # the mention names are kept.
+    def strip_mentions_text(account_id: nil, tag_only: false)
+      return nil unless text
+
+      get_mentions.reduce(text) do |result, mention|
+        next result if account_id && mention.dig("mentioned", "id") != account_id
+
+        mention_text = mention["text"].to_s
+        if !mention_text.empty?
+          without_tags = mention_text.gsub("<at>", "").gsub("</at>", "")
+          result.sub(mention_text, tag_only ? without_tags : "")
+        elsif (name = mention.dig("mentioned", "name"))
+          result.sub("<at>#{name}</at>", tag_only ? name : "")
+        else
+          result
+        end
+      end.strip
+    end
+
+    def to_h
+      raw.dup
+    end
+
+    def message?
+      type == "message"
+    end
+
+    def message_update?
+      type == "messageUpdate"
+    end
+
+    def typing?
+      type == "typing"
+    end
+
+    def invoke?
+      type == "invoke"
+    end
+
+    def install_update?
+      type == "installationUpdate"
+    end
+
+    def suggested_action_submit?
+      type == "invoke" && name == "suggestedActions/submit"
+    end
+
+    private
+
+    def normalize_hash(value)
+      return {} if value.nil?
+
+      value.each_with_object({}) do |(key, item), result|
+        result[key.to_s] = normalize_value(item)
+      end
+    end
+
+    def normalize_value(value)
+      case value
+      when Hash
+        normalize_hash(value)
+      when Array
+        value.map { |item| normalize_value(item) }
+      else
+        value
+      end
+    end
+  end
+end