feat(P6/T02-T03): EnvelopeEmissionContract and InteractionReportingContract

T02: EnvelopeEmissionContractsController (index+show, read-only); widgetEnvelope
helper validates against contract v1.0 required attributes with inline warning
on missing view-context; adapterStatusBadge helper added to Application.Helper.View.

T03: InteractionReportingContractsController (index+show, read-only); API endpoint
POST /api/v1/interaction-events with bearer token auth against hub.api_key,
contract v1.0 field validation, and 201/422/401 responses.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Web/Controller/ApiInteractionEvents.hs

@@ -0,0 +1,104 @@
+module Web.Controller.ApiInteractionEvents where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import qualified Data.Text as T
+import Network.Wai (requestMethod, requestHeaders)
+
+-- | Accepted event types per InteractionReportingContract v1.0
+apiAcceptedEventTypes :: [Text]
+apiAcceptedEventTypes = ["clicked", "viewed", "submitted", "dismissed", "errored"]
+
+instance Controller ApiInteractionEventsController where
+
+    action CreateApiInteractionEventAction = do
+        -- Method guard — only POST accepted.
+        when (requestMethod ?request /= "POST") do
+            setStatus 405
+            respondJson (object ["error" .= ("Method not allowed" :: Text)])
+
+        -- Bearer token auth — validate against hub.api_key.
+        let authHeader = lookup "Authorization" (requestHeaders ?request)
+        let mApiKey = authHeader >>= \h ->
+                let t = cs h :: Text
+                in if "Bearer " `T.isPrefixOf` t
+                   then Just (T.drop 7 t)
+                   else Nothing
+
+        case mApiKey of
+            Nothing -> do
+                setStatus 401
+                respondJson (object ["error" .= ("Authorization: Bearer <hub-api-key> required" :: Text)])
+            Just apiKey -> do
+                mHub <- query @Hub
+                    |> filterWhere (#apiKey, Just apiKey)
+                    |> fetchOneOrNothing
+                case mHub of
+                    Nothing -> do
+                        setStatus 401
+                        respondJson (object ["error" .= ("Invalid or unknown API key" :: Text)])
+                    Just hub -> createEventForHub hub
+
+createEventForHub :: (?context :: ControllerContext, ?modelContext :: ModelContext, ?respond :: Respond, ?request :: Request) => Hub -> IO ResponseReceived
+createEventForHub hub = do
+    -- Validate required fields per contract v1.0
+    widgetIdText <- paramOrNothing @Text "widget_id"
+    eventType    <- paramOrNothing @Text "event_type"
+    _occurredAt  <- paramOrNothing @Text "occurred_at"
+
+    let missing = catMaybes
+            [ if isNothing widgetIdText then Just ("widget_id"  :: Text) else Nothing
+            , if isNothing eventType    then Just "event_type"            else Nothing
+            , if isNothing _occurredAt  then Just "occurred_at"           else Nothing
+            ]
+
+    unless (null missing) do
+        setStatus 422
+        respondJson (object
+            [ "error"   .= ("Missing required fields" :: Text)
+            , "missing" .= missing
+            ])
+
+    let Just wIdText = widgetIdText
+        Just evType  = eventType
+
+    unless (evType `elem` apiAcceptedEventTypes) do
+        setStatus 422
+        respondJson (object
+            [ "error"    .= ("Unacceptable event_type" :: Text)
+            , "accepted" .= apiAcceptedEventTypes
+            ])
+
+    -- Resolve widget — must belong to this hub.
+    case readMay wIdText of
+        Nothing -> do
+            setStatus 422
+            respondJson (object ["error" .= ("widget_id must be a valid UUID" :: Text)])
+        Just rawId -> do
+            let wId = Id rawId :: Id Widget
+            mWidget <- fetchOneOrNothing wId
+            case mWidget of
+                Nothing -> do
+                    setStatus 422
+                    respondJson (object ["error" .= ("Widget not found" :: Text)])
+                Just widget -> do
+                    when (widget.hubId /= hub.id) do
+                        setStatus 403
+                        respondJson (object ["error" .= ("Widget does not belong to this hub" :: Text)])
+
+                    event <- newRecord @InteractionEvent
+                        |> set #widgetId  widget.id
+                        |> set #eventType evType
+                        |> set #actorType "external_adapter"
+                        |> createRecord
+
+                    setStatus 201
+                    respondJson (object
+                        [ "id"          .= event.id
+                        , "widget_id"   .= event.widgetId
+                        , "event_type"  .= event.eventType
+                        , "occurred_at" .= event.occurredAt
+                        ])

Web/Controller/EnvelopeEmissionContracts.hs

@@ -0,0 +1,21 @@
+module Web.Controller.EnvelopeEmissionContracts where
+
+import Web.Types
+import Web.View.EnvelopeEmissionContracts.Index
+import Web.View.EnvelopeEmissionContracts.Show
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+
+instance Controller EnvelopeEmissionContractsController where
+    beforeAction = ensureIsUser
+
+    action EnvelopeEmissionContractsAction = do
+        contracts <- query @EnvelopeEmissionContract
+            |> orderByDesc #createdAt
+            |> fetch
+        render IndexView { contracts }
+
+    action ShowEnvelopeEmissionContractAction { envelopeEmissionContractId } = do
+        contract <- fetch envelopeEmissionContractId
+        render ShowView { contract }

Web/Controller/InteractionReportingContracts.hs

@@ -0,0 +1,21 @@
+module Web.Controller.InteractionReportingContracts where
+
+import Web.Types
+import Web.View.InteractionReportingContracts.Index
+import Web.View.InteractionReportingContracts.Show
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+
+instance Controller InteractionReportingContractsController where
+    beforeAction = ensureIsUser
+
+    action InteractionReportingContractsAction = do
+        contracts <- query @InteractionReportingContract
+            |> orderByDesc #createdAt
+            |> fetch
+        render IndexView { contracts }
+
+    action ShowInteractionReportingContractAction { interactionReportingContractId } = do
+        contract <- fetch interactionReportingContractId
+        render ShowView { contract }

Web/FrontController.hs

@@ -17,6 +17,7 @@ import Web.Controller.Requirements ()
 import Web.Controller.DecisionRecords ()
 import Web.Controller.DeploymentRecords ()
 import Web.Controller.AgentProposals ()
+import Web.Controller.ApiInteractionEvents ()
 import Web.Controller.EnvelopeEmissionContracts ()
 import Web.Controller.InteractionReportingContracts ()
 import Web.Controller.WidgetAdapterSpecs ()
@@ -35,6 +36,7 @@ instance FrontController WebApplication where
         , parseRoute @DecisionRecordsController
         , parseRoute @DeploymentRecordsController
         , parseRoute @AgentProposalsController
+        , parseRoute @ApiInteractionEventsController
         , parseRoute @EnvelopeEmissionContractsController
         , parseRoute @InteractionReportingContractsController
         , parseRoute @WidgetAdapterSpecsController

Web/Routes.hs

@@ -35,6 +35,19 @@ instance AutoRoute DeploymentRecordsController
 instance AutoRoute AgentProposalsController
 
 -- Phase 6 — Cross-Framework UI Adaptation
+
+-- API endpoint: POST /api/v1/interaction-events
+instance CanRoute ApiInteractionEventsController where
+    parseRoute' = do
+        _ <- string "/api"
+        _ <- string "/v1"
+        _ <- string "/interaction-events"
+        endOfInput
+        pure CreateApiInteractionEventAction
+
+instance HasPath ApiInteractionEventsController where
+    pathTo CreateApiInteractionEventAction = "/api/v1/interaction-events"
+
 instance AutoRoute EnvelopeEmissionContractsController
 instance AutoRoute InteractionReportingContractsController
 instance AutoRoute WidgetAdapterSpecsController

Web/Types.hs

@@ -112,6 +112,10 @@ data AgentProposalsController
     | RejectProposalAction    { agentProposalId :: !(Id AgentProposal) }
     deriving (Eq, Show, Data)
 
+data ApiInteractionEventsController
+    = CreateApiInteractionEventAction
+    deriving (Eq, Show, Data)
+
 data EnvelopeEmissionContractsController
     = EnvelopeEmissionContractsAction
     | ShowEnvelopeEmissionContractAction { envelopeEmissionContractId :: !(Id EnvelopeEmissionContract) }

Web/View/EnvelopeEmissionContracts/Index.hs

@@ -0,0 +1,67 @@
+module Web.View.EnvelopeEmissionContracts.Index where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+import Application.Helper.View (adapterStatusBadge)
+
+data IndexView = IndexView
+    { contracts :: ![EnvelopeEmissionContract]
+    }
+
+instance View IndexView where
+    html IndexView { .. } = [hsx|
+        <div class="flex items-center justify-between mb-6">
+            <div>
+                <h1 class="text-2xl font-semibold">Envelope Emission Contracts</h1>
+                <p class="text-sm text-gray-500 mt-1">
+                    Formalises which <code>data-*</code> attributes every widget envelope must emit.
+                </p>
+            </div>
+            <a href={InteractionReportingContractsAction}
+               class="text-sm text-gray-500 hover:text-gray-800">
+                → Reporting Contracts
+            </a>
+        </div>
+
+        {if null contracts
+            then [hsx|<p class="text-sm text-gray-400">No contracts found.</p>|]
+            else renderTable contracts}
+    |]
+
+renderTable :: [EnvelopeEmissionContract] -> Html
+renderTable contracts = [hsx|
+    <div class="bg-white rounded-lg border border-gray-200 overflow-hidden">
+        <table class="w-full text-sm">
+            <thead class="bg-gray-50 border-b border-gray-200">
+                <tr>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Version</th>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Required Attributes</th>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Status</th>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Created</th>
+                </tr>
+            </thead>
+            <tbody class="divide-y divide-gray-100">
+                {forEach contracts renderRow}
+            </tbody>
+        </table>
+    </div>
+|]
+
+renderRow :: EnvelopeEmissionContract -> Html
+renderRow c = [hsx|
+    <tr class="hover:bg-gray-50">
+        <td class="px-4 py-3">
+            <a href={ShowEnvelopeEmissionContractAction { envelopeEmissionContractId = c.id }}
+               class="font-mono text-indigo-600 hover:underline">v{c.contractVersion}</a>
+        </td>
+        <td class="px-4 py-3 text-gray-600 font-mono text-xs">{tshow c.requiredAttributes}</td>
+        <td class="px-4 py-3">
+            <span class={adapterStatusBadge c.status <> " text-xs px-2 py-0.5 rounded font-medium"}>
+                {c.status}
+            </span>
+        </td>
+        <td class="px-4 py-3 text-gray-400 text-xs">{show c.createdAt}</td>
+    </tr>
+|]

Web/View/EnvelopeEmissionContracts/Show.hs

@@ -0,0 +1,59 @@
+module Web.View.EnvelopeEmissionContracts.Show where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+import Application.Helper.View (adapterStatusBadge)
+
+data ShowView = ShowView
+    { contract :: !EnvelopeEmissionContract
+    }
+
+instance View ShowView where
+    html ShowView { .. } = [hsx|
+        <div class="mb-6">
+            <a href={EnvelopeEmissionContractsAction} class="text-sm text-gray-500 hover:text-gray-800">
+                ← Envelope Contracts
+            </a>
+        </div>
+
+        <div class="flex items-center gap-3 mb-6">
+            <h1 class="text-2xl font-semibold">
+                Envelope Contract <span class="font-mono">v{contract.contractVersion}</span>
+            </h1>
+            <span class={adapterStatusBadge contract.status <> " text-xs px-2 py-0.5 rounded font-medium"}>
+                {contract.status}
+            </span>
+        </div>
+
+        {forEach (contractDescription contract) (\d -> [hsx|
+            <p class="text-sm text-gray-600 mb-6">{d}</p>
+        |])}
+
+        <div class="grid grid-cols-1 gap-4">
+            <div class="bg-white rounded-lg border border-gray-200 p-5">
+                <h2 class="text-sm font-semibold text-gray-700 mb-3">Required Attributes</h2>
+                <pre class="text-xs bg-gray-50 rounded p-3 overflow-auto">{tshow contract.requiredAttributes}</pre>
+            </div>
+
+            <div class="bg-white rounded-lg border border-gray-200 p-5">
+                <h2 class="text-sm font-semibold text-gray-700 mb-3">Optional Attributes</h2>
+                <pre class="text-xs bg-gray-50 rounded p-3 overflow-auto">{tshow contract.optionalAttributes}</pre>
+            </div>
+
+            <div class="bg-white rounded-lg border border-gray-200 p-5">
+                <h2 class="text-sm font-semibold text-gray-700 mb-3">Validation Rules</h2>
+                <pre class="text-xs bg-gray-50 rounded p-3 overflow-auto">{tshow contract.validationRules}</pre>
+            </div>
+        </div>
+
+        <div class="mt-6 text-xs text-gray-400">
+            Created: {show contract.createdAt}
+        </div>
+    |]
+
+contractDescription :: EnvelopeEmissionContract -> [Text]
+contractDescription c = case c.description of
+    Just d  -> [d]
+    Nothing -> []

Web/View/InteractionReportingContracts/Index.hs

@@ -0,0 +1,69 @@
+module Web.View.InteractionReportingContracts.Index where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+import Application.Helper.View (adapterStatusBadge)
+
+data IndexView = IndexView
+    { contracts :: ![InteractionReportingContract]
+    }
+
+instance View IndexView where
+    html IndexView { .. } = [hsx|
+        <div class="flex items-center justify-between mb-6">
+            <div>
+                <h1 class="text-2xl font-semibold">Interaction Reporting Contracts</h1>
+                <p class="text-sm text-gray-500 mt-1">
+                    Defines the REST endpoint and payload schema for external adapter event submission.
+                </p>
+            </div>
+            <a href={EnvelopeEmissionContractsAction}
+               class="text-sm text-gray-500 hover:text-gray-800">
+                ← Envelope Contracts
+            </a>
+        </div>
+
+        {if null contracts
+            then [hsx|<p class="text-sm text-gray-400">No contracts found.</p>|]
+            else renderTable contracts}
+    |]
+
+renderTable :: [InteractionReportingContract] -> Html
+renderTable contracts = [hsx|
+    <div class="bg-white rounded-lg border border-gray-200 overflow-hidden">
+        <table class="w-full text-sm">
+            <thead class="bg-gray-50 border-b border-gray-200">
+                <tr>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Version</th>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Endpoint</th>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Auth</th>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Status</th>
+                    <th class="text-left px-4 py-3 font-medium text-gray-600">Created</th>
+                </tr>
+            </thead>
+            <tbody class="divide-y divide-gray-100">
+                {forEach contracts renderRow}
+            </tbody>
+        </table>
+    </div>
+|]
+
+renderRow :: InteractionReportingContract -> Html
+renderRow c = [hsx|
+    <tr class="hover:bg-gray-50">
+        <td class="px-4 py-3">
+            <a href={ShowInteractionReportingContractAction { interactionReportingContractId = c.id }}
+               class="font-mono text-indigo-600 hover:underline">v{c.contractVersion}</a>
+        </td>
+        <td class="px-4 py-3 font-mono text-xs text-gray-700">{c.endpointPath}</td>
+        <td class="px-4 py-3 text-xs text-gray-500">{c.authScheme}</td>
+        <td class="px-4 py-3">
+            <span class={adapterStatusBadge c.status <> " text-xs px-2 py-0.5 rounded font-medium"}>
+                {c.status}
+            </span>
+        </td>
+        <td class="px-4 py-3 text-gray-400 text-xs">{show c.createdAt}</td>
+    </tr>
+|]

Web/View/InteractionReportingContracts/Show.hs

@@ -0,0 +1,76 @@
+module Web.View.InteractionReportingContracts.Show where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+import Application.Helper.View (adapterStatusBadge)
+
+data ShowView = ShowView
+    { contract :: !InteractionReportingContract
+    }
+
+instance View ShowView where
+    html ShowView { .. } = [hsx|
+        <div class="mb-6">
+            <a href={InteractionReportingContractsAction} class="text-sm text-gray-500 hover:text-gray-800">
+                ← Reporting Contracts
+            </a>
+        </div>
+
+        <div class="flex items-center gap-3 mb-6">
+            <h1 class="text-2xl font-semibold">
+                Reporting Contract <span class="font-mono">v{contract.contractVersion}</span>
+            </h1>
+            <span class={adapterStatusBadge contract.status <> " text-xs px-2 py-0.5 rounded font-medium"}>
+                {contract.status}
+            </span>
+        </div>
+
+        {forEach (contractDescription contract) (\d -> [hsx|
+            <p class="text-sm text-gray-600 mb-6">{d}</p>
+        |])}
+
+        <div class="grid grid-cols-1 gap-4">
+            <div class="bg-white rounded-lg border border-gray-200 p-5">
+                <h2 class="text-sm font-semibold text-gray-700 mb-3">Endpoint</h2>
+                <div class="flex items-center gap-2">
+                    <span class="bg-green-100 text-green-800 text-xs font-bold px-2 py-0.5 rounded">POST</span>
+                    <code class="text-sm text-gray-800">{contract.endpointPath}</code>
+                </div>
+                <div class="mt-2 text-xs text-gray-500">Auth: <code>{contract.authScheme}</code></div>
+            </div>
+
+            <div class="bg-white rounded-lg border border-gray-200 p-5">
+                <h2 class="text-sm font-semibold text-gray-700 mb-3">Required Fields</h2>
+                <pre class="text-xs bg-gray-50 rounded p-3 overflow-auto">{tshow contract.requiredFields}</pre>
+            </div>
+
+            <div class="bg-white rounded-lg border border-gray-200 p-5">
+                <h2 class="text-sm font-semibold text-gray-700 mb-3">Accepted Event Types</h2>
+                <pre class="text-xs bg-gray-50 rounded p-3 overflow-auto">{tshow contract.acceptedEventTypes}</pre>
+            </div>
+        </div>
+
+        <div class="mt-6 bg-blue-50 border border-blue-200 rounded p-4 text-sm">
+            <h3 class="font-semibold text-blue-800 mb-2">Example Request</h3>
+            <pre class="text-xs text-blue-900 overflow-auto">curl -X POST {contract.endpointPath} \
+  -H "Authorization: Bearer &lt;hub-api-key&gt;" \
+  -H "Content-Type: application/json" \
+  -d '{"{"}
+    "widget_id": "&lt;uuid&gt;",
+    "hub_id": "&lt;uuid&gt;",
+    "event_type": "clicked",
+    "occurred_at": "2026-03-29T12:00:00Z"
+{"}"}'</pre>
+        </div>
+
+        <div class="mt-4 text-xs text-gray-400">
+            Created: {show contract.createdAt}
+        </div>
+    |]
+
+contractDescription :: InteractionReportingContract -> [Text]
+contractDescription c = case c.description of
+    Just d  -> [d]
+    Nothing -> []