# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
  title: "Matrix Identity Service Store Invitations API"
  version: "1.0.0"
host: localhost:8090
schemes:
  - https
  - http
basePath: /_matrix/identity/api/v1
produces:
  - application/json
paths:
  "/store-invite":
    post:
      summary: Store pending invitations to a user\'s 3pid.
      description: |-
        Store pending invitations to a user\'s 3pid.

        In addition to the request parameters specified below, an arbitrary
        number of other parameters may also be specified. These may be used in
        the invite message generation described below.

        The service will generate a random token and an ephemeral key used for
        accepting the invite.

        The service also generates a ``display_name`` for the inviter, which is
        a redacted version of ``address`` which does not leak the full contents
        of the ``address``.

        The service records persistently all of the above information.

        It also generates an email containing all of this data, sent to the
        ``address`` parameter, notifying them of the invitation.

        Also, the generated ephemeral public key will be listed as valid on
        requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
      operationId: storeInvite
      parameters:
        - in: body
          name: body
          schema:
            type: object
            example: {
              "medium": "email",
              "address": "foo@bar.baz",
              "room_id": "!something:example.tld",
              "sender": "@bob:example.com"
            }
            properties:
              medium:
                type: string
                description: The literal string ``email``.
              address:
                type: string
                description: The email address of the invited user.
              room_id:
                type: string
                description: The Matrix room ID to which the user is invited
              sender:
                type: string
                description: The Matrix user ID of the inviting user
            required: ["medium", "address", "room_id", "sender"]
      responses:
        200:
          description: The invitation was stored.
          schema:
            type: object
            properties:
              token:
                type: string
                description: The generated token.
              public_keys:
                type: array
                description: A list of [server\'s long-term public key, generated ephemeral public key].
                items:
                  type: string
              display_name:
                type: string
                description: The generated (redacted) display_name.
            required: ['token', 'public_keys', 'display_name']
            example:
              application/json: {
                "token": "sometoken",
                "public_keys": [
                  "serverpublickey",
                  "ephemeralpublickey"
                ],
                "display_name": "f...@b..."
              }
        400:
          description: |
            An error has occured.

            If the 3pid is already bound to a Matrix user ID, the error code
            will be ``M_THREEPID_IN_USE``.  If the medium is unsupported, the
            error code will be ``M_UNRECOGNIZED``.
          examples:
            application/json: {
              "errcode": "M_THREEPID_IN_USE",
              "error": "Binding already known",
              "mxid": mxid
            }
          schema:
            $ref: "../client-server/definitions/errors/error.yaml"