feat(teams): webhook primitive subpath (chat@4.31 8c71411)

Port the NET-NEW Teams webhook primitives subpackage from
packages/adapter-teams/src/webhook (chat@4.31.0, commit 8c71411),
mirroring the slack/webhook layout.

Parse-only Bot Framework activity classification — no JWT verification,
no outbound HTTP. Classifies an inbound activity into typed,
discriminated payloads (message / card_action / dialog_open /
dialog_submit / message_reaction / conversation_update /
installation_update / unsupported), plus continuation / user /
attachment extraction and is_teams_mention bot-mention detection.

SDK-free: plain dicts + stdlib only, no microsoft_teams imports. Typed
results use snake_case dataclasses while the camelCase Bot Framework
wire keys survive verbatim on each payload's raw passthrough. Truthiness
fallbacks use `is not None` / membership checks; invalid JSON and
non-object bodies raise TeamsWebhookParseError.

Strict lane scoping: only the new webhook/ subpackage and its test file
are added — the Teams package __init__ is left untouched (PEP-562 lazy
subpath registration is deferred to the packaging PR).

Tests: 45 cases porting the 12 index.test.ts `it` cases plus the source
boundary case (13 upstream), with adversarial/divergence coverage for
the camelCase raw passthrough, `replyToId ?? id` fallback, mention
`:`-suffix matching, and explicit-null content handling.

Author: patrick-chinchill

src/chat_sdk/adapters/teams/webhook/__init__.py

@@ -0,0 +1,117 @@
+"""Teams webhook primitives — a lightweight, runtime-free subpath.
+
+Port of ``packages/adapter-teams/src/webhook`` (chat@4.31, commit 8c71411),
+exposed upstream as ``@chat-adapter/teams/webhook``. Provides primitives for
+classifying an inbound Bot Framework activity into typed, discriminated
+payloads, plus continuation / user / attachment extraction and bot-mention
+detection — without the full Teams adapter, the ``microsoft_teams`` SDK,
+chat state, dedupe, locks, or subscriptions.
+
+Parse-ONLY: these primitives never verify JWTs and never make outbound HTTP
+requests. Importing this module never imports ``microsoft_teams``, HTTP
+clients, or the high-level :mod:`chat_sdk.adapters.teams.adapter`.
+
+Wire boundary: typed results are ``snake_case`` dataclasses; the original
+camelCase Bot Framework activity is preserved verbatim on each payload's
+``raw`` field (``channelData.teamsChannelId``, ``replyToId``, ``aadObjectId``,
+``tenantId``, ...).
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from chat_sdk.adapters.teams.webhook.continuation import (
+    extract_teams_attachments,
+    extract_teams_continuation,
+    extract_teams_user,
+    is_teams_mention,
+)
+from chat_sdk.adapters.teams.webhook.parse import parse_teams_webhook_body
+from chat_sdk.adapters.teams.webhook.types import (
+    TeamsActivity,
+    TeamsCardActionPayload,
+    TeamsContinuation,
+    TeamsConversationUpdatePayload,
+    TeamsDialogOpenPayload,
+    TeamsDialogSubmitPayload,
+    TeamsInstallationUpdatePayload,
+    TeamsMessagePayload,
+    TeamsMessageReactionPayload,
+    TeamsParseOptions,
+    TeamsUnsupportedPayload,
+    TeamsWebhookAttachment,
+    TeamsWebhookError,
+    TeamsWebhookParseError,
+    TeamsWebhookPayload,
+    TeamsWebhookUser,
+)
+
+
+async def read_teams_request_body(request: Any) -> str:
+    """Read the raw body from a duck-typed request object.
+
+    Python stand-in for the Fetch API's ``await request.text()`` used by the
+    upstream ``readTeamsWebhook`` helper. Supports:
+
+    - ``request.text`` as an (async or sync) method or plain attribute
+    - ``request.body`` as an (async or sync) method, awaitable, bytes, or str
+    - falling back to ``str(request)``
+
+    Bytes are decoded as UTF-8.
+    """
+    text_attr = getattr(request, "text", None)
+    if text_attr is not None:
+        if callable(text_attr):
+            result = text_attr()
+            text_attr = await result if inspect.isawaitable(result) else result
+        return text_attr.decode("utf-8") if isinstance(text_attr, (bytes, bytearray)) else str(text_attr)
+    raw = getattr(request, "body", None)
+    if raw is not None:
+        if callable(raw):
+            raw = raw()
+        if inspect.isawaitable(raw):
+            raw = await raw
+        return raw.decode("utf-8") if isinstance(raw, (bytes, bytearray)) else str(raw)
+    return str(request)
+
+
+async def read_teams_webhook(
+    request: Any,
+    options: TeamsParseOptions | None = None,
+) -> TeamsWebhookPayload:
+    """Read a request body and classify it — no JWT verification.
+
+    Port of upstream ``readTeamsWebhook``: reads ``await request.text()`` then
+    delegates to :func:`parse_teams_webhook_body`.
+    """
+    body = await read_teams_request_body(request)
+    return parse_teams_webhook_body(body, options)
+
+
+__all__ = [
+    "TeamsActivity",
+    "TeamsCardActionPayload",
+    "TeamsContinuation",
+    "TeamsConversationUpdatePayload",
+    "TeamsDialogOpenPayload",
+    "TeamsDialogSubmitPayload",
+    "TeamsInstallationUpdatePayload",
+    "TeamsMessagePayload",
+    "TeamsMessageReactionPayload",
+    "TeamsParseOptions",
+    "TeamsUnsupportedPayload",
+    "TeamsWebhookAttachment",
+    "TeamsWebhookError",
+    "TeamsWebhookParseError",
+    "TeamsWebhookPayload",
+    "TeamsWebhookUser",
+    "extract_teams_attachments",
+    "extract_teams_continuation",
+    "extract_teams_user",
+    "is_teams_mention",
+    "parse_teams_webhook_body",
+    "read_teams_request_body",
+    "read_teams_webhook",
+]

src/chat_sdk/adapters/teams/webhook/continuation.py

@@ -0,0 +1,163 @@
+"""Continuation / extraction helpers for the Teams webhook primitives.
+
+Port of ``packages/adapter-teams/src/webhook/continuation.ts`` (chat@4.31,
+commit 8c71411). Pulls provider-native reply data, the acting user, message
+attachments, and bot-mention state out of a raw Bot Framework activity.
+
+These helpers are SDK-free: they operate on plain dicts (the camelCase wire
+shape) using membership / ``is not None`` checks — never truthiness ``or``
+fallbacks that would coerce ``""``/``0``/``False`` into the wrong branch.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from chat_sdk.adapters.teams.webhook.types import (
+    TeamsActivity,
+    TeamsContinuation,
+    TeamsWebhookAttachment,
+    TeamsWebhookUser,
+)
+
+
+def _record(value: Any) -> dict[str, Any] | None:
+    """Return ``value`` when it is a dict, else ``None`` (optional chaining)."""
+    return value if isinstance(value, dict) else None
+
+
+def _opt_str(value: Any) -> str | None:
+    """Return ``value`` only when it is a non-empty string, else ``None``.
+
+    Mirrors the upstream ``activity.foo ? { foo } : {}`` spread guards, which
+    drop empty strings as well as ``undefined`` (an empty string is falsy in
+    JS). Keeping the same shape avoids emitting blank continuation fields.
+    """
+    return value if isinstance(value, str) and value else None
+
+
+def extract_teams_continuation(activity: TeamsActivity) -> TeamsContinuation:
+    """Build a :class:`TeamsContinuation` from a raw activity.
+
+    ``conversation_id`` / ``service_url`` default to ``""`` (upstream ``?? ""``)
+    so the continuation always carries the two fields a reply needs; the rest
+    are populated only when present, applying the same channelData fallbacks
+    as upstream (``channel.id`` then ``teamsChannelId``; ``team.id`` then
+    ``teamsTeamId``; ``conversation.tenantId`` then ``tenant.id``).
+    """
+    channel_data = _record(activity.get("channelData")) or {}
+    conversation = _record(activity.get("conversation")) or {}
+    channel = _record(channel_data.get("channel")) or {}
+    team = _record(channel_data.get("team")) or {}
+    tenant = _record(channel_data.get("tenant")) or {}
+
+    channel_id = _opt_str(channel.get("id"))
+    if channel_id is None:
+        channel_id = _opt_str(channel_data.get("teamsChannelId"))
+
+    team_id = _opt_str(team.get("id"))
+    if team_id is None:
+        team_id = _opt_str(channel_data.get("teamsTeamId"))
+
+    tenant_id = _opt_str(conversation.get("tenantId"))
+    if tenant_id is None:
+        tenant_id = _opt_str(tenant.get("id"))
+
+    conversation_id = conversation.get("id")
+    service_url = activity.get("serviceUrl")
+
+    return TeamsContinuation(
+        activity_id=_opt_str(activity.get("id")),
+        channel_id=channel_id,
+        conversation_id=conversation_id if isinstance(conversation_id, str) else "",
+        reply_to_id=_opt_str(activity.get("replyToId")),
+        service_url=service_url if isinstance(service_url, str) else "",
+        team_id=team_id,
+        tenant_id=tenant_id,
+    )
+
+
+def extract_teams_user(activity: TeamsActivity) -> TeamsWebhookUser | None:
+    """Return the acting user, or ``None`` when ``from.id`` is missing.
+
+    Upstream short-circuits on ``!activity.from?.id`` — a present user object
+    with no ``id`` yields ``None``. ``aadObjectId`` / ``name`` are included
+    only when truthy on the wire.
+    """
+    sender = _record(activity.get("from"))
+    if sender is None:
+        return None
+    user_id = sender.get("id")
+    if not (isinstance(user_id, str) and user_id):
+        return None
+    return TeamsWebhookUser(
+        aad_object_id=_opt_str(sender.get("aadObjectId")),
+        id=user_id,
+        name=_opt_str(sender.get("name")),
+    )
+
+
+def extract_teams_attachments(activity: TeamsActivity) -> list[TeamsWebhookAttachment]:
+    """Normalize ``activity.attachments``, skipping non-object entries.
+
+    Non-list ``attachments`` yields ``[]``; ``None`` / non-dict entries are
+    dropped. The typed ``content`` is the entry's ``content`` value (``None``
+    when absent); the key-present-vs-absent distinction (upstream's
+    ``typeof attachment.content === "undefined" ? {} : { content }``) is
+    preserved on ``raw``. ``content_type`` / ``content_url`` / ``name`` are
+    copied only when they are strings.
+    """
+    raw_attachments = activity.get("attachments")
+    if not isinstance(raw_attachments, list):
+        return []
+    result: list[TeamsWebhookAttachment] = []
+    for attachment in raw_attachments:
+        record = _record(attachment)
+        if record is None:
+            continue
+        content_type = record.get("contentType")
+        content_url = record.get("contentUrl")
+        name = record.get("name")
+        result.append(
+            TeamsWebhookAttachment(
+                # The typed ``content`` is ``None`` for both a missing key and an
+                # explicit ``null`` (upstream copies the value only when present,
+                # but the absent-value is itself ``undefined``/``None``). The
+                # key-present-vs-absent distinction is preserved in ``raw``.
+                content=record.get("content"),
+                content_type=content_type if isinstance(content_type, str) else None,
+                content_url=content_url if isinstance(content_url, str) else None,
+                name=name if isinstance(name, str) else None,
+                raw=record,
+            )
+        )
+    return result
+
+
+def is_teams_mention(activity: TeamsActivity, bot_app_id: str | None = None) -> bool:
+    """Return ``True`` when the activity @-mentions the bot.
+
+    Without a ``bot_app_id`` this is always ``False``. A match requires a
+    ``mention`` entity whose ``mentioned.id`` either equals ``bot_app_id`` or
+    ends with the exact ``":" + bot_app_id`` suffix (Bot Framework prefixes
+    user ids like ``28:<app-id>``).
+    """
+    if not bot_app_id:
+        return False
+    entities = activity.get("entities")
+    if not isinstance(entities, list):
+        return False
+    suffix = f":{bot_app_id}"
+    for entity in entities:
+        record = _record(entity)
+        if record is None or record.get("type") != "mention":
+            continue
+        mentioned = _record(record.get("mentioned"))
+        if mentioned is None:
+            continue
+        mentioned_id = mentioned.get("id")
+        if not isinstance(mentioned_id, str):
+            continue
+        if mentioned_id == bot_app_id or mentioned_id.endswith(suffix):
+            return True
+    return False