Specify third party room invitations

SYN-458

api/client-server/v1/membership.yaml

@@ -66,11 +66,16 @@ paths:
         aliases:
           - /join/{roomId}
 
-  "/rooms/{roomId}/invite":
+  # With an extra " " to disambiguate from the 3pid invite endpoint
+  # The extra space makes it sort first for what I'm sure is a good reason.
+  "/rooms/{roomId}/invite ":
     post:
       summary: Invite a user to participate in a particular room.
-      # It's a crying shame that I don't know how to force line breaks.
       description: |-
+        *Note that there are two forms of this API, which are documented separately.
+        This version of the API requires that the inviter knows the Matrix
+        identifier of the invitee.*
+
         This API invites a user to participate in a particular room.
         They do not start participating in the room until they actually join the
         room.
@@ -82,6 +87,9 @@ paths:
 
         Only users currently in a particular room can invite other users to
         join that room.
+
+        If the user was invited to the room, the home server will append a
+        ``m.room.member`` event to the room.
       security:
         - accessToken: []
       parameters:
@@ -92,7 +100,7 @@ paths:
           required: true
           x-example: "!d41d8cd:matrix.org"
         - in: body
-          name: user_id
+          name: body
           required: true
           schema:
             type: object
@@ -112,7 +120,107 @@ paths:
             application/json: |-
               {}
           schema:
-            type: object  # empty json object
+            type: object
+        403:
+          description: |-
+            You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+              - The invitee has been banned from the room.
+              - The invitee is already a member of the room.
+              - The inviter is not currently in the room.
+              - The inviter's power level is insufficient to invite users to the room.
+          examples:
+            application/json: |-
+              {"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+
+  "/rooms/{roomId}/invite":
+    post:
+      summary: Invite a user to participate in a particular room.
+      description: |-
+        *Note that there are two forms of this API, which are documented separately.
+        This version of the API does not require that the inviter know the Matrix
+        identifier of the invitee, and instead relies on third party identifiers.*
+
+        This API invites a user to participate in a particular room.
+        They do not start participating in the room until they actually join the
+        room.
+
+        This serves two purposes; firstly, to notify the user that the room
+        exists (and that their presence is requested). Secondly, some rooms can
+        only be joined if a user is invited to join it; sending the invite gives
+        that user permission to join the room.
+
+        Only users currently in a particular room can invite other users to
+        join that room.
+
+        If the identity server does not know a Matrix user identifier for the
+        passed third party identifier, the homeserver will issue an invitation
+        which can be accepted upon providing proof of ownership of the third
+        party identifier. This is achieved by requesting a nonce and digest from
+        the identity server. When a user binds the invited third party
+        identifier to a Matrix user ID, the identity server will give the user a
+        list of pending invitations, each containing:
+
+          - The room ID to which they were invited
+
+          - The digest given to the homeserver
+
+          - A secret which, when appended to the nonce, digests to the above digest
+
+        The digest algorithm to be used is SHA256.
+
+        If the identity server did know the Matrix user identifier for the
+        third party identifier, the home server will append a ``m.room.member``
+        event to the room.
+
+        If a digest and nonce are requested from the identity server, the home
+        server will append a ``m.room.token_based_invite`` event to the room.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) to which to invite the user.
+          required: true
+          x-example: "!d41d8cd:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "identity_server": "matrix.org",
+                "medium": "email",
+                "address": "cheeky@monkey.com",
+                "display_name": "A very cheeky monkey"
+              }
+            properties:
+              identity_server:
+                type: string
+                description: The hostname+port of the identity server which should be used for third party identifier lookups.
+              medium:
+                type: string
+                description: The kind of address being passed in the address field.
+              address:
+                type: string
+                description: The invitee's third party identifier.
+              display_name:
+                type: string
+                description: A user-friendly string describing who has been invited. It should not contain the address of the invitee, to avoid leaking mappings between third party identities and matrix user IDs.
+            required: ["identity_server", "medium", "address", "display_name"]
+      responses:
+        200:
+          description: The user has been invited to join the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
         403:
           description: |-
             You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:

templating/matrix_templates/units.py

@@ -110,7 +110,7 @@ class MatrixUnits(Units):
                     "title": single_api.get("summary", ""),
                     "desc": single_api.get("description", single_api.get("summary", "")),
                     "method": method.upper(),
-                    "path": full_path,
+                    "path": full_path.strip(),
                     "requires_auth": "security" in single_api,
                     "rate_limited": 429 in single_api.get("responses", {}),
                     "req_params": [],