Allow sending ephemeral data to application services (#2018)

As per MSC2409.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/application_service/newsfragments/2018.feature

@@ -0,0 +1 @@
+Allow sending ephemeral data to application services, as per [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409).

content/application-service-api.md

@@ -207,6 +207,39 @@ processed the events.
 
 {{% http-api spec="application-service" api="transactions" %}}
 
+##### Pushing ephemeral data
+
+{{% added-in v="1.13" %}}
+
+If the `receive_ephemeral` settings is enabled in the [registration](#registration)
+file, homeservers MUST send ephemeral data that is relevant to the application
+service via the transaction API, using the `ephemeral` property of the request's
+body. This property is an array that is effectively a combination of the
+`presence` and `ephemeral` sections of the client-server [`/sync`](/client-server-api/#get_matrixclientv3sync)
+API.
+
+There are currently three event types that can be delivered to an application
+service:
+
+- **[`m.presence`](/client-server-api/#mpresence)**: MUST be sent to the
+application service if the data would apply contextually. For example, a
+presence update for a user an application service shares a room with, or
+matching one of the application service's namespaces.
+- **[`m.typing`](/client-server-api/#mtyping)**: MUST be sent to the application
+service under the same rules as regular events, meaning that the application
+service must have registered interest in the room itself, or in a user that is
+in the room. The data MUST use the same format as the client-server API, with
+the addition of a `room_id` property at the top level to identify the room that
+they were sent in.
+- **[`m.receipt`](/client-server-api/#mreceipt)**: MUST be sent to the
+application service under the same rules as regular events, meaning that the
+application service must have registered interest in the room itself, or in a
+user that is in the room. The data MUST use the same format as the client-server
+API, with the addition of a `room_id` property at the top level to identify the
+room that they were sent in. [Private read receipts](/client-server-api/#private-read-receipts)
+MUST only be sent for users matching one of the application service's
+namespaces. Normal read receipts and threaded read receipts are always sent.
+
 #### Pinging
 
 {{% added-in v="1.7" %}}

data/api/application-service/definitions/registration.yaml

@@ -32,6 +32,13 @@ properties:
     description: |-
       The localpart of the user associated with the application service. Events will be sent to the AS if this user is the target of the event, or
       is a joined member of the room where the event occurred.
+  receive_ephemeral:
+    type: boolean
+    x-addedInMatrixVersion: "1.13"
+    description: |-
+      Whether the application service wants to [receive ephemeral data](/application-service-api/#pushing-ephemeral-data).
+      
+      Defaults to `false` if not present.
   namespaces:
     type: object
     title: Namespaces

data/api/application-service/transactions.yaml

@@ -46,6 +46,15 @@ paths:
             schema:
               type: object
               example: {
+                "ephemeral": [
+                  {
+                    "$ref": "../../event-schemas/examples/m.receipt.yaml",
+                    "room_id": "!jEsUZKDJdhlrceRyVU:example.org"
+                  },
+                  {
+                    "$ref": "../../event-schemas/examples/m.presence.yaml"
+                  },
+                ],
                 "events": [
                   {
                     "$ref": "../../event-schemas/examples/m.room.member.yaml"
@@ -61,6 +70,21 @@ paths:
                   description: A list of events, formatted as per the Client-Server API.
                   items:
                     $ref: ../client-server/definitions/client_event.yaml
+                ephemeral:
+                  type: array
+                  x-addedInMatrixVersion: "1.13"
+                  description: |-
+                    A list of ephemeral data, if the `receive_ephemeral` setting was enabled in the
+                    [registration](/application-service-api/#registration) file.
+
+                    There are only three event types that can currently occur in this list: `m.presence`,
+                    `m.typing`, and `m.receipt`. Room-scoped ephemeral data (`m.typing` and
+                    `m.receipt`) MUST include a `room_id` property to identify the room that they
+                    were sent in.
+
+                    This property can be omitted if it would be empty.
+                  items:
+                    $ref: ../../event-schemas/schema/core-event-schema/event.yaml
               required:
                 - events
         description: Transaction information