async-matrix 0.1.3 → 1.1.0

data/data/matrix-spec/api/client-server/profile.yaml

@@ -0,0 +1,366 @@
+# Copyright 2016 OpenMarket 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Profile API
+  version: 1.0.0
+paths:
+  "/profile/{userId}/{keyName}":
+    put:
+      x-changedInMatrixVersion:
+        "1.16": This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted.
+      summary: Set a profile field for a user.
+      description: |-
+        Set or update a profile field for a user. Must be authenticated with an
+        access token authorised to make changes. Servers MAY impose size limits
+        on individual fields, and the total profile MUST be under 64 KiB.
+
+        Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
+        them rather than treating `null` as a deletion request. Clients that want to delete a
+        field, including its key and value, SHOULD use the `DELETE` endpoint instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation)
+        depending on the `keyName`. Clients SHOULD check the value of the
+        [`m.profile_fields` capability](/client-server-api/#mprofile_fields-capability) to detect
+        which `keyName`s they are allowed to modify.
+      operationId: setProfileField
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user whose profile field should be set.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: keyName
+          description: The name of the profile field to set. This MUST be either
+            `avatar_url`, `displayname`, `m.tz`, or a custom field following the
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
+      requestBody:
+        description: A JSON object containing the property whose name matches
+          the `keyName` specified in the URL. See `additionalProperties` for
+          further details.
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              minProperties: 1
+              description: |
+                An object which contains exactly one property. The key
+                of that property MUST match the `keyName` specified in the URL.
+                
+                For `avatar_url`, the value MUST be an MXC URI string. 
+                
+                For `displayname`, the value MUST be a string.
+                
+                For `m.tz`, the value MUST be a valid identifier from the  [IANA Time Zone Database](https://www.iana.org/time-zones).
+                Servers MAY choose to validate the value. Clients MUST expect unknown or invalid
+                values.
+
+                For custom keys, any JSON type is allowed. Servers MAY not validate
+                these values, but clients SHOULD follow the format defined for that key.
+              additionalProperties: true
+              example: { "displayname": "Alice Wonderland" }
+      responses:
+        "200":
+          description: The profile field was set.
+          content:
+            application/json:
+              schema:
+                type: object # empty JSON object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: |
+            The input was invalid in some way. This can include one
+            of the following error codes:
+            
+            - `M_BAD_JSON`: The provided value is not valid JSON.
+            - `M_MISSING_PARAM`: The required `keyName` property is
+              missing from the request body.
+            - `M_PROFILE_TOO_LARGE`: Storing the supplied value would
+              make the profile exceed its maximum allowed size of 64 KiB.
+            - `M_KEY_TOO_LARGE`: The supplied profile key exceeds the
+              maximum allowed key length of 255 bytes.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                bad_json:
+                  value:
+                    {
+                      "errcode": "M_BAD_JSON",
+                      "error": "Malformed JSON payload.",
+                    }
+                invalid_key:
+                  value:
+                    {
+                      "errcode": "M_INVALID_PARAM",
+                      "error": "Invalid profile key.",
+                    }
+        "403":
+          description: The server is unwilling to perform the operation, either
+            due to insufficient permissions or because profile modifications
+            are disabled.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile modification is not permitted.",
+                    }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - User data
+    get:
+      x-changedInMatrixVersion:
+        "1.16": This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted.
+      summary: Get a profile field for a user.
+      description: Get the value of a profile field for a user.
+      operationId: getProfileField
+      parameters:
+        - in: path
+          name: userId
+          description: The user whose profile field should be returned.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: keyName
+          description: The name of the profile field to retrieve.
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
+      responses:
+        "200":
+          description: The profile field value was retrieved.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: |
+                  An object with one property, whose key matches the `keyName` specified
+                  in the URL, and whose value is the current setting of that profile field.
+                additionalProperties: true
+              examples:
+                response:
+                  value: { "displayname": "Alice" }
+        "403":
+          x-addedInMatrixVersion: "1.12"
+          description: The server is unwilling to disclose whether the user
+            exists and/or has the specified profile field.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile lookup is disabled on this homeserver",
+                    }
+        "404":
+          description: There is no profile field with this key for this user, or
+            the user does not exist.
+      tags:
+        - User data
+    delete:
+      x-addedInMatrixVersion: "1.16"
+      summary: Remove a profile field from a user.
+      description: Remove a specific field from a user's profile.
+      operationId: deleteProfileField
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user whose profile field should be deleted.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: keyName
+          description: The name of the profile field to delete.
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
+      responses:
+        "200":
+          description: The profile field was deleted or it doesn't exist.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: The request is malformed, contains invalid JSON, or
+            specifies an invalid key.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                bad_json:
+                  value:
+                    { "errcode": "M_BAD_JSON", "error": "Malformed request." }
+                invalid_key:
+                  value:
+                    {
+                      "errcode": "M_INVALID_PARAM",
+                      "error": "Invalid profile key.",
+                    }
+        "403":
+          description: The user is not authorised to delete this profile field.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile deletion is not permitted.",
+                    }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - User data
+  "/profile/{userId}":
+    get:
+      summary: Get all profile information for a user.
+      description: |-
+        Get the complete profile for a user.
+      operationId: getUserProfile
+      parameters:
+        - in: path
+          name: userId
+          description: The user whose profile information to get.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The profile information for this user.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  avatar_url:
+                    type: string
+                    format: mx-mxc-uri
+                    description: The user's avatar URL if they have set one, otherwise not present.
+                  displayname:
+                    type: string
+                    description: The user's display name if they have set one, otherwise not
+                      present.
+                  m.tz:
+                    x-addedInMatrixVersion: "1.16"
+                    type: string
+                    description: The user's time zone.
+                additionalProperties:
+                  x-addedInMatrixVersion: "1.16"
+                  description: Additional profile fields.
+              examples:
+                response:
+                  value:
+                    {
+                      "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+                      "displayname": "Alice Margatroid",
+                      "m.tz": "Europe/London",
+                      "m.example_field": "custom_value",
+                    }
+        "403":
+          x-addedInMatrixVersion: "1.2"
+          description: The server is unwilling to disclose whether the user
+            exists and/or has profile information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile lookup is disabled on this homeserver",
+                    }
+        "404":
+          description: There is no profile information for this user or this
+            user does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value:
+                    { "errcode": "M_NOT_FOUND", "error": "Profile not found" }
+      tags:
+        - User data
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/data/matrix-spec/api/client-server/pusher.yaml

@@ -0,0 +1,303 @@
+# Copyright 2016 OpenMarket Ltd
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Push API
+  version: 1.0.0
+paths:
+  /pushers:
+    get:
+      summary: Gets the current pushers for the authenticated user
+      description: Gets all currently active pushers for the authenticated user.
+      operationId: getPushers
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The pushers for this user.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  pushers:
+                    type: array
+                    title: Pushers
+                    description: An array containing the current pushers for the user
+                    items:
+                      type: object
+                      title: Pusher
+                      properties:
+                        pushkey:
+                          type: string
+                          description: |-
+                            This is a unique identifier for this pusher. See `/set` for
+                            more detail.
+                            Max length, 512 bytes.
+                        kind:
+                          type: string
+                          description: |-
+                            The kind of pusher. `"http"` is a pusher that
+                            sends HTTP pokes.
+                        app_id:
+                          type: string
+                          description: |-
+                            This is a reverse-DNS style identifier for the application.
+                            Max length, 64 chars.
+                        app_display_name:
+                          type: string
+                          description: |-
+                            A string that will allow the user to identify what application
+                            owns this pusher.
+                        device_display_name:
+                          type: string
+                          description: |-
+                            A string that will allow the user to identify what device owns
+                            this pusher.
+                        profile_tag:
+                          type: string
+                          description: |-
+                            This string determines which set of device specific rules this
+                            pusher executes.
+                        lang:
+                          type: string
+                          description: |-
+                            The preferred language for receiving notifications (e.g. 'en'
+                            or 'en-US')
+                        data:
+                          type: object
+                          description: |-
+                            A dictionary of information for the pusher implementation
+                            itself.
+                          title: PusherData
+                          properties:
+                            url:
+                              type: string
+                              format: uri
+                              description: |-
+                                Required if `kind` is `http`. The URL to use to send
+                                notifications to.
+                            format:
+                              type: string
+                              description: |-
+                                The format to use when sending notifications to the Push
+                                Gateway.
+                      required:
+                        - pushkey
+                        - app_id
+                        - kind
+                        - app_display_name
+                        - device_display_name
+                        - lang
+                        - data
+              examples:
+                response:
+                  value: {
+                    "pushers": [
+                      {
+                        "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
+                        "kind": "http",
+                        "app_id": "face.mcapp.appy.prod",
+                        "app_display_name": "Appy McAppface",
+                        "device_display_name": "Alice's Phone",
+                        "profile_tag": "xyz",
+                        "lang": "en-US",
+                        "data": {
+                          "url": "https://example.com/_matrix/push/v1/notify"
+                        }
+                      }
+                    ]
+                  }
+      tags:
+        - Push notifications
+  /pushers/set:
+    post:
+      summary: Modify a pusher for this user on the homeserver.
+      description: |-
+        This endpoint allows the creation, modification and deletion of [pushers](/client-server-api/#push-notifications)
+        for this user ID. The behaviour of this endpoint varies depending on the
+        values in the JSON body.
+
+        If `kind` is not `null`, the pusher with this `app_id` and `pushkey`
+        for this user is updated, or it is created if it doesn't exist. If
+        `kind` is `null`, the pusher with this `app_id` and `pushkey` for this
+        user is deleted.
+      operationId: postPusher
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "lang": "en",
+                "kind": "http",
+                "app_display_name": "Mat Rix",
+                "device_display_name": "iPhone 9",
+                "profile_tag": "xxyyzz",
+                "app_id": "com.example.app.ios",
+                "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
+                "data": {
+                  "url": "https://push-gateway.location.here/_matrix/push/v1/notify",
+                  "format": "event_id_only"
+                },
+                "append": false
+              }
+              properties:
+                pushkey:
+                  type: string
+                  description: |-
+                    This is a unique identifier for this pusher. The value you
+                    should use for this is the routing or destination address
+                    information for the notification, for example, the APNS token
+                    for APNS or the Registration ID for GCM. If your notification
+                    client has no such concept, use any unique identifier.
+                    Max length, 512 bytes.
+
+                    If the `kind` is `"email"`, this is the email address to
+                    send notifications to.
+                kind:
+                  description: |-
+                    The kind of pusher to configure. `"http"` makes a pusher that
+                    sends HTTP pokes. `"email"` makes a pusher that emails the
+                    user with unread notifications. `null` deletes the pusher.
+                  type: ["string", "null"]
+                app_id:
+                  type: string
+                  description: |-
+                    This is a reverse-DNS style identifier for the application.
+                    It is recommended that this end with the platform, such that
+                    different platform versions get different app identifiers.
+                    Max length, 64 chars.
+
+                    If the `kind` is `"email"`, this is `"m.email"`.
+                app_display_name:
+                  type: string
+                  description: |-
+                    Required if `kind` is not `null`. A string that will allow the
+                    user to identify what application owns this pusher.
+                device_display_name:
+                  type: string
+                  description: |-
+                    Required if `kind` is not `null`. A string that will allow the
+                    user to identify what device owns this pusher.
+                profile_tag:
+                  type: string
+                  description: |-
+                    This string determines which set of device specific rules this
+                    pusher executes.
+                lang:
+                  type: string
+                  description: |-
+                    Required if `kind` is not `null`. The preferred language for
+                    receiving notifications (e.g. 'en' or 'en-US').
+                data:
+                  type: object
+                  description: |-
+                    Required if `kind` is not `null`. A dictionary of information
+                    for the pusher implementation itself.
+
+                    If `kind` is `http`, this MUST contain `url` which is the URL
+                    to use for sending notifications. Clients MAY use this object
+                    to pass custom data to their push gateway. Servers MUST forward
+                    the entire content including `format` and any custom keys but excluding `url`
+                    when calling [`/_matrix/push/v1/notify`](/push-gateway-api/#post_matrixpushv1notify).
+                  title: PusherData
+                  properties:
+                    url:
+                      type: string
+                      format: uri
+                      description: |-
+                        Required if `kind` is `http`. The URL to use for sending
+                        notifications. MUST be an HTTPS URL with a path of
+                        `/_matrix/push/v1/notify`.
+                      example: https://push-gateway.location.here/_matrix/push/v1/notify
+                    format:
+                      type: string
+                      description: |-
+                        The format in which to send notifications to the push gateway
+                        if the `kind` is `http`. The details about what fields the
+                        homeserver should include are defined in the
+                        [Push Gateway Specification](/push-gateway-api/). If omitted,
+                        the server is expected to populate all of the event-related fields
+                        specified in [`/_matrix/push/v1/notify`](/push-gateway-api/#post_matrixpushv1notify).
+                      enum:
+                        - "event_id_only"
+                append:
+                  type: boolean
+                  description: |-
+                    If true, the homeserver should add another pusher with the
+                    given pushkey and App ID in addition to any others with
+                    different user IDs. Otherwise, the homeserver must remove any
+                    other pushers with the same App ID and pushkey for different
+                    users. The default is `false`.
+              required:
+                - kind
+                - app_id
+                - pushkey
+        description: The pusher information.
+        required: true
+      responses:
+        "200":
+          description: The pusher was set.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: An empty object.
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: One or more of the pusher values were invalid.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "error": "Missing parameters: lang, data",
+                    "errcode": "M_MISSING_PARAM"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Push notifications
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer