Document interests and preferences, and tutorial completion

openapi/components/parameters.yaml

@@ -693,7 +693,7 @@
   schema:
     type: string
     format: date-time
 mostRecentFlag:
   name: mostRecent
   required: false
   in: query
@@ -889,7 +889,7 @@
   schema:
     type: string
     example: game night
 storeId:
   name: storeId
   required: true
   in: query
@@ -1029,3 +1029,19 @@
   in: path
   schema:
     $ref: ./schemas/WorldID.yaml
+xPlatform:
+  name: X-Platform
+  description: The platform the tutorial belongs to. `standalonewindows`, `android` and `ios` are kept; any other value is recorded as `null`.
+  required: false
+  in: header
+  schema:
+    type: string
+    example: standalonewindows
+xStore:
+  name: X-Store
+  description: The store the tutorial belongs to, recorded as sent.
+  required: false
+  in: header
+  schema:
+    type: string
+    example: steam

openapi/components/paths.yaml

@@ -52,6 +52,8 @@
   $ref: "./paths/friends.yaml#/paths/~1auth~1user~1friends"
 "/auth/user/friends/{userId}":
   $ref: "./paths/friends.yaml#/paths/~1auth~1user~1friends~1{userId}"
+/auth/user/interestsAndPreferences:
+  $ref: "./paths/authentication.yaml#/paths/~1auth~1user~1interestsAndPreferences"
 /auth/user/notifications:
   $ref: "./paths/notifications.yaml#/paths/~1auth~1user~1notifications"
 /auth/user/notifications/clear:
@@ -266,7 +268,7 @@
   $ref: "./paths/instances.yaml#/paths/~1instances~1s~1{shortName}"
 "/instances/{worldId}:{instanceId}":
   $ref: "./paths/instances.yaml#/paths/~1instances~1{worldId}:{instanceId}"
 "/instances/{worldId}:{instanceId}/shortName":
   $ref: "./paths/instances.yaml#/paths/~1instances~1{worldId}:{instanceId}~1shortName"
 /inventory:
   $ref: "./paths/inventory.yaml#/paths/~1inventory"
@@ -284,9 +286,9 @@
   $ref: "./paths/inventory.yaml#/paths/~1inventory~1template~1{inventoryTemplateId}"
 "/inventory/{inventoryItemId}":
   $ref: "./paths/inventory.yaml#/paths/~1inventory~1{inventoryItemId}"
 "/inventory/{inventoryItemId}/consume":
   $ref: "./paths/inventory.yaml#/paths/~1inventory~1{inventoryItemId}~1consume"
 "/inventory/{inventoryItemId}/equip":
   $ref: "./paths/inventory.yaml#/paths/~1inventory~1{inventoryItemId}~1equip"
 "/invite/myself/to/{worldId}:{instanceId}":
   $ref: "./paths/invite.yaml#/paths/~1invite~1myself~1to~1{worldId}:{instanceId}"
@@ -470,7 +472,7 @@
   $ref: "./paths/economy.yaml#/paths/~1users~1{userId}~1subscription~1eligible"
 "/users/{userId}/tutorial":
   $ref: "./paths/users.yaml#/paths/~1users~1{userId}~1tutorial"
 "/users/{userId}/{worldId}/persist":
   $ref: "./paths/users.yaml#/paths/~1users~1{userId}~1{worldId}~1persist"
 "/users/{userId}/{worldId}/persist/exists":
   $ref: "./paths/users.yaml#/paths/~1users~1{userId}~1{worldId}~1persist~1exists"

openapi/components/paths/authentication.yaml

@@ -30,7 +30,7 @@
         - $ref: ../parameters.yaml#/confirmEmailUserId
         - $ref: ../parameters.yaml#/confirmEmailToken
       security: []
       responses:
         "302":
           $ref: ../responses/authentication/ConfirmEmailResponse.yaml
   /auth/exists:
@@ -290,6 +290,41 @@
           $ref: ../responses/authentication/CreateAvatarModerationResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
+  /auth/user/interestsAndPreferences:
+    get:
+      operationId: getInterestsAndPreferences
+      summary: Get Interests and Preferences
+      description: Returns the interests and preferences the current user has turned on.
+      tags:
+        - authentication
+      security:
+        - authCookie: []
+      responses:
+        "200":
+          $ref: ../responses/authentication/GetInterestsAndPreferencesResponse.yaml
+        "401":
+          $ref: ../responses/MissingCredentialsError.yaml
+    put:
+      operationId: updateInterestsAndPreferences
+      summary: Update Interests and Preferences
+      description: Turns interests and preferences on with `true` and off with `false`. A key the body leaves out keeps its value, and an unknown key or a value that is not a boolean is ignored.
+      tags:
+        - authentication
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../schemas/InterestsAndPreferences.yaml
+      security:
+        - authCookie: []
+      responses:
+        "200":
+          $ref: ../responses/authentication/UpdateInterestsAndPreferencesResponse.yaml
+        "400":
+          $ref: ../responses/authentication/UpdateInterestsAndPreferencesParseError.yaml
+        "401":
+          $ref: ../responses/MissingCredentialsError.yaml
   /auth/user/resendEmail:
     post:
       operationId: resendEmailConfirmation
@@ -330,7 +365,7 @@
         - $ref: ../parameters.yaml#/userIdQuery
         - $ref: ../parameters.yaml#/verifyLoginPlaceToken
       security: []
       responses:
         "302":
           $ref: ../responses/authentication/VerifyLoginPlaceResponse.yaml
   /logout:

openapi/components/paths/users.yaml

@@ -602,11 +602,12 @@ paths:
   "/users/{userId}/tutorial":
     parameters:
       - $ref: ../parameters.yaml#/userId
+      - $ref: ../parameters.yaml#/xPlatform
+      - $ref: ../parameters.yaml#/xStore
     get:
       operationId: getUserTutorialStatus
       summary: Get User Tutorial Status
-      description: Gets the status of completed or outstanding tutorials for the
-        specified user.
+      description: Gets the status of completed or outstanding tutorials for the specified user. `tutorialKey` and `completed` describe the tutorial named by `X-Platform` and `X-Store`.
       tags:
         - users
       security:
@@ -616,6 +617,36 @@ paths:
           $ref: ../responses/users/TutorialStatusResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
+    post:
+      operationId: completeUserTutorial
+      summary: Complete User Tutorial
+      description: Marks the tutorial named by `X-Platform` and `X-Store` completed, and returns the current user.
+      tags:
+        - users
+      security:
+        - authCookie: []
+      responses:
+        "200":
+          $ref: ../responses/users/CurrentUserResponse.yaml
+        "401":
+          $ref: ../responses/MissingCredentialsError.yaml
+        "403":
+          $ref: ../responses/users/CompleteTutorialForbiddenError.yaml
+    delete:
+      operationId: clearUserTutorials
+      summary: Clear User Tutorials
+      description: Clears every tutorial the user completed on a platform, whatever `X-Platform` and `X-Store` name, and returns the current user. Tutorials of other kinds, such as `platform-agnostic:custom:onboarding-tutorial-world:v1`, stay completed.
+      tags:
+        - users
+      security:
+        - authCookie: []
+      responses:
+        "200":
+          $ref: ../responses/users/CurrentUserResponse.yaml
+        "401":
+          $ref: ../responses/MissingCredentialsError.yaml
+        "403":
+          $ref: ../responses/users/ClearTutorialsForbiddenError.yaml
   "/users/{userId}/{worldId}/persist":
     parameters:
       - $ref: ../parameters.yaml#/userId

openapi/components/responses/authentication/GetInterestsAndPreferencesResponse.yaml

@@ -0,0 +1,27 @@
+description: OK
+content:
+  application/json:
+    examples:
+      All Off:
+        value: {}
+      All On:
+        value:
+          Anime: true
+          Art: true
+          Avatars: true
+          BigGroup: true
+          Explore: true
+          Fantasy: true
+          Fashion: true
+          FindAvatars: true
+          Furries: true
+          Horror: true
+          LanguageLearning: true
+          MeetPeople: true
+          Music: true
+          Mystery: true
+          SciFi: true
+          SmallGroup: true
+          Surprise: true
+    schema:
+      $ref: ../../schemas/InterestsAndPreferences.yaml

openapi/components/responses/authentication/UpdateInterestsAndPreferencesParseError.yaml

@@ -0,0 +1,11 @@
+description: The body is not a JSON object.
+content:
+  application/json:
+    examples:
+      JSON Failed To Parse:
+        value:
+          error:
+            message: JSON failed to parse.
+            status_code: 400
+    schema:
+      $ref: ../../schemas/Error.yaml

openapi/components/responses/authentication/UpdateInterestsAndPreferencesResponse.yaml

@@ -0,0 +1,11 @@
+description: OK
+content:
+  application/json:
+    examples:
+      Update Interests And Preferences Success:
+        value:
+          success:
+            message: Interests and preferences updated!
+            status_code: 200
+    schema:
+      $ref: ../../schemas/Success.yaml

openapi/components/responses/users/ClearTutorialsForbiddenError.yaml

@@ -0,0 +1,11 @@
+description: A user can clear only their own tutorials.
+content:
+  application/json:
+    examples:
+      Other User:
+        value:
+          error:
+            message: '"You do not have permission to clear tutorials completions for others."'
+            status_code: 403
+    schema:
+      $ref: ../../schemas/Error.yaml

openapi/components/responses/users/CompleteTutorialForbiddenError.yaml

@@ -0,0 +1,11 @@
+description: A user can complete only their own tutorials.
+content:
+  application/json:
+    examples:
+      Other User:
+        value:
+          error:
+            message: '"You do not have permission to complete tutorials for others."'
+            status_code: 403
+    schema:
+      $ref: ../../schemas/Error.yaml

openapi/components/schemas/InterestsAndPreferences.yaml

@@ -0,0 +1,38 @@
+title: InterestsAndPreferences
+type: object
+description: Interests and preferences the current user has turned on. A key is present only while its value is `true`.
+properties:
+  Anime:
+    type: boolean
+  Art:
+    type: boolean
+  Avatars:
+    type: boolean
+  BigGroup:
+    type: boolean
+  Explore:
+    type: boolean
+  Fantasy:
+    type: boolean
+  Fashion:
+    type: boolean
+  FindAvatars:
+    type: boolean
+  Furries:
+    type: boolean
+  Horror:
+    type: boolean
+  LanguageLearning:
+    type: boolean
+  MeetPeople:
+    type: boolean
+  Music:
+    type: boolean
+  Mystery:
+    type: boolean
+  SciFi:
+    type: boolean
+  SmallGroup:
+    type: boolean
+  Surprise:
+    type: boolean

openapi/components/schemas/TutorialKey.yaml

@@ -1,5 +1,5 @@
 title: TutorialKey
 type: string
-description: "The ID of a tutorial, in the format `{platform}:{tutorial}:{version}`. `undefined:undefined:v1` is used as a null-ish or sentinel value."
+description: "The ID of a tutorial. A platform tutorial is `{platform}:{store}:v1`, taken from the `X-Platform` and `X-Store` headers, with `undefined` for a header the request left out. Other tutorials take a longer form, such as `platform-agnostic:custom:onboarding-tutorial-world:v1`."
 default: undefined:undefined:v1
 example: standalonewindows:steam:v1