From c472c1fed74b3026b38f46855fbaeaa0bfceddf3 Mon Sep 17 00:00:00 2001 From: elsy Date: Wed, 4 Nov 2026 23:44:38 +0900 Subject: [PATCH 1/6] feat(users): document createUserModeration --- openapi/components/paths.yaml | 2 ++ openapi/components/paths/users.yaml | 30 +++++++++++++++++++ .../requests/CreateUserModerationRequest.yaml | 19 ++++++++++++ .../CreateUserModerationForbiddenError.yaml | 11 +++++++ .../CreateUserModerationRateLimitError.yaml | 11 +++++++ .../users/CreateUserModerationResponse.yaml | 5 ++++ .../CreateUserModerationRequestType.yaml | 25 ++++++++++++++++ .../schemas/CreateUserModerationResponse.yaml | 7 +++++ openapi/components/schemas/ModerationID.yaml | 4 +++ 9 files changed, 114 insertions(+) create mode 100644 openapi/components/requests/CreateUserModerationRequest.yaml create mode 100644 openapi/components/responses/users/CreateUserModerationForbiddenError.yaml create mode 100644 openapi/components/responses/users/CreateUserModerationRateLimitError.yaml create mode 100644 openapi/components/responses/users/CreateUserModerationResponse.yaml create mode 100644 openapi/components/schemas/CreateUserModerationRequestType.yaml create mode 100644 openapi/components/schemas/CreateUserModerationResponse.yaml create mode 100644 openapi/components/schemas/ModerationID.yaml diff --git a/openapi/components/paths.yaml b/openapi/components/paths.yaml index bb4a1e10..756c8d07 100644 --- a/openapi/components/paths.yaml +++ b/openapi/components/paths.yaml @@ -434,6 +434,8 @@ $ref: "./paths/inventory.yaml#/paths/~1user~1{userId}~1inventory~1{inventoryItemId}" "/user/{userId}/listings": $ref: "./paths/economy.yaml#/paths/~1user~1{userId}~1listings" +"/user/{userId}/moderations": + $ref: "./paths/users.yaml#/paths/~1user~1{userId}~1moderations" "/user/{userId}/products": $ref: "./paths/economy.yaml#/paths/~1user~1{userId}~1products" "/user/{userId}/tilia/kyc": diff --git a/openapi/components/paths/users.yaml b/openapi/components/paths/users.yaml index 0853534f..017b71cb 100644 --- a/openapi/components/paths/users.yaml +++ b/openapi/components/paths/users.yaml @@ -81,6 +81,36 @@ paths: $ref: ../responses/users/PrivateProfileResponse.yaml "401": $ref: ../responses/MissingCredentialsError.yaml + "/user/{userId}/moderations": + parameters: + - $ref: ../parameters.yaml#/userId + post: + operationId: createUserModeration + summary: Create User Moderation + description: A `kick` bans the user from the instance in `worldId` and `instanceId`. They are not removed from it, but cannot join it again, even by invite. + tags: + - users + requestBody: + required: true + content: + application/json: + schema: + $ref: ../requests/CreateUserModerationRequest.yaml + security: + - authCookie: [] + responses: + "200": + $ref: ../responses/users/CreateUserModerationResponse.yaml + "400": + $ref: ../responses/RequestValidationError.yaml + "401": + $ref: ../responses/MissingCredentialsError.yaml + "403": + $ref: ../responses/users/CreateUserModerationForbiddenError.yaml + "404": + $ref: ../responses/ResourceNotFoundError.yaml + "429": + $ref: ../responses/users/CreateUserModerationRateLimitError.yaml /userNotes: get: operationId: getUserNotes diff --git a/openapi/components/requests/CreateUserModerationRequest.yaml b/openapi/components/requests/CreateUserModerationRequest.yaml new file mode 100644 index 00000000..e967c96e --- /dev/null +++ b/openapi/components/requests/CreateUserModerationRequest.yaml @@ -0,0 +1,19 @@ +title: CreateUserModerationRequest +type: object +properties: + expires: + type: string + format: date-time + instanceId: + $ref: ../schemas/InstanceID.yaml + isPermanent: + type: boolean + reason: + type: string + type: + $ref: ../schemas/CreateUserModerationRequestType.yaml + worldId: + $ref: ../schemas/WorldID.yaml +required: + - reason + - type diff --git a/openapi/components/responses/users/CreateUserModerationForbiddenError.yaml b/openapi/components/responses/users/CreateUserModerationForbiddenError.yaml new file mode 100644 index 00000000..0fdfb0a1 --- /dev/null +++ b/openapi/components/responses/users/CreateUserModerationForbiddenError.yaml @@ -0,0 +1,11 @@ +description: Error response when you are not allowed to moderate the user. +content: + application/json: + examples: + Cannot Moderate User: + value: + error: + message: You cannot moderate this user․ + status_code: 403 + schema: + $ref: ../../schemas/Error.yaml diff --git a/openapi/components/responses/users/CreateUserModerationRateLimitError.yaml b/openapi/components/responses/users/CreateUserModerationRateLimitError.yaml new file mode 100644 index 00000000..f8a695d7 --- /dev/null +++ b/openapi/components/responses/users/CreateUserModerationRateLimitError.yaml @@ -0,0 +1,11 @@ +description: Error response when moderating the same user too often. +content: + application/json: + examples: + Too Many Moderations: + value: + error: + message: Too many moderations being created at one player․ + status_code: 429 + schema: + $ref: ../../schemas/Error.yaml diff --git a/openapi/components/responses/users/CreateUserModerationResponse.yaml b/openapi/components/responses/users/CreateUserModerationResponse.yaml new file mode 100644 index 00000000..73c18521 --- /dev/null +++ b/openapi/components/responses/users/CreateUserModerationResponse.yaml @@ -0,0 +1,5 @@ +description: Returns the ID of the created moderation. +content: + application/json: + schema: + $ref: ../../schemas/CreateUserModerationResponse.yaml diff --git a/openapi/components/schemas/CreateUserModerationRequestType.yaml b/openapi/components/schemas/CreateUserModerationRequestType.yaml new file mode 100644 index 00000000..a1c6f300 --- /dev/null +++ b/openapi/components/schemas/CreateUserModerationRequestType.yaml @@ -0,0 +1,25 @@ +title: CreateUserModerationRequestType +enum: + - avatar + - ban + - banpubliconly + - chat + - emoji + - event + - gallery + - group + - hardban + - icon + - kick + - note + - nuisance + - print + - profile + - publicinstance + - sticker + - voice + - warn + - warning + - world +examples: + - kick diff --git a/openapi/components/schemas/CreateUserModerationResponse.yaml b/openapi/components/schemas/CreateUserModerationResponse.yaml new file mode 100644 index 00000000..a21d45cd --- /dev/null +++ b/openapi/components/schemas/CreateUserModerationResponse.yaml @@ -0,0 +1,7 @@ +title: CreateUserModerationResponse +type: object +properties: + id: + $ref: ./ModerationID.yaml +required: + - id diff --git a/openapi/components/schemas/ModerationID.yaml b/openapi/components/schemas/ModerationID.yaml new file mode 100644 index 00000000..7be84360 --- /dev/null +++ b/openapi/components/schemas/ModerationID.yaml @@ -0,0 +1,4 @@ +title: ModerationID +type: string +examples: + - mod_f862716d-23bf-49e0-a931-a08759450834 From 04d1c2e7f8068c1f02021f78c37ad4768f023e3f Mon Sep 17 00:00:00 2001 From: elsy Date: Wed, 4 Nov 2026 23:44:38 +0900 Subject: [PATCH 2/6] test(users): cover createUserModeration --- test/arazzo.yaml | 100 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/test/arazzo.yaml b/test/arazzo.yaml index 6858da25..c03f1d40 100644 --- a/test/arazzo.yaml +++ b/test/arazzo.yaml @@ -14025,6 +14025,106 @@ workflows: successCriteria: - condition: $statusCode == 401 + - workflowId: create-user-moderation-invalid-type + summary: createUserModeration refuses a type it does not know + parameters: + - reference: $components.parameters.userAgent + x-security: + - schemeName: authCookie + values: + apiKey: $workflows.session.outputs.sessionToken + steps: + - stepId: create-user-moderation + operationId: $sourceDescriptions.default.createUserModeration + parameters: + - name: userId + in: path + value: usr_00000000-0000-0000-0000-000000000000 + requestBody: + contentType: application/json + payload: + reason: x + type: x + successCriteria: + - condition: $statusCode == 400 + - condition: $response.body#/error/message == 'type must be one of ["ban"‚"note"‚"warning"‚"nuisance"‚"hardban"‚"kick"‚"warn"‚"banpubliconly"‚"publicinstance"‚"avatar"‚"world"‚"event"‚"group"‚"voice"‚"chat"‚"profile"‚"sticker"‚"emoji"‚"gallery"‚"print"‚"icon"]‚ not "x"' + + - workflowId: create-user-moderation-not-found + summary: createUserModeration refuses a user that does not exist + parameters: + - reference: $components.parameters.userAgent + x-security: + - schemeName: authCookie + values: + apiKey: $workflows.session.outputs.sessionToken + steps: + - stepId: create-user-moderation + operationId: $sourceDescriptions.default.createUserModeration + parameters: + - name: userId + in: path + value: usr_00000000-0000-0000-0000-000000000000 + requestBody: + contentType: application/json + payload: + reason: x + type: kick + successCriteria: + - condition: $statusCode == 404 + + - workflowId: create-user-moderation-self + summary: createUserModeration refuses the caller as its target, and rate limits a second attempt + parameters: + - reference: $components.parameters.userAgent + x-security: + - schemeName: authCookie + values: + apiKey: $workflows.session.outputs.sessionToken + steps: + - stepId: create-user-moderation + operationId: $sourceDescriptions.default.createUserModeration + parameters: + - name: userId + in: path + value: $workflows.session.outputs.userId + requestBody: + contentType: application/json + payload: + reason: x + type: kick + successCriteria: + - condition: $statusCode == 403 + - condition: $response.body#/error/message == 'You cannot moderate this user․' + + - stepId: create-user-moderation-rate-limited + operationId: $sourceDescriptions.default.createUserModeration + parameters: + - name: userId + in: path + value: $workflows.session.outputs.userId + requestBody: + contentType: application/json + payload: + reason: x + type: kick + successCriteria: + - condition: $statusCode == 429 + - condition: $response.body#/error/message == 'Too many moderations being created at one player․' + + - workflowId: create-user-moderation-unauthenticated + summary: createUserModeration refuses an anonymous caller + parameters: + - reference: $components.parameters.userAgent + steps: + - stepId: create-user-moderation + operationId: $sourceDescriptions.default.createUserModeration + parameters: + - name: userId + in: path + value: usr_00000000-0000-0000-0000-000000000000 + successCriteria: + - condition: $statusCode == 401 + - workflowId: delete-all-user-persistence-data-unauthenticated summary: deleteAllUserPersistenceData refuses an anonymous caller parameters: From bc9b93438fa8bd0f1196957fad905a1b968b09b4 Mon Sep 17 00:00:00 2001 From: elsy Date: Thu, 5 Nov 2026 00:15:44 +0900 Subject: [PATCH 3/6] fix(users): describe kick failures --- openapi/components/paths/users.yaml | 2 +- .../responses/users/CreateUserModerationForbiddenError.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi/components/paths/users.yaml b/openapi/components/paths/users.yaml index 017b71cb..e3967e44 100644 --- a/openapi/components/paths/users.yaml +++ b/openapi/components/paths/users.yaml @@ -87,7 +87,7 @@ paths: post: operationId: createUserModeration summary: Create User Moderation - description: A `kick` bans the user from the instance in `worldId` and `instanceId`. They are not removed from it, but cannot join it again, even by invite. + description: With `type` `kick`, bans the user in the path from the instance given by `worldId` and `instanceId`. The user is not removed from the instance, but cannot join it again, even by invite. tags: - users requestBody: diff --git a/openapi/components/responses/users/CreateUserModerationForbiddenError.yaml b/openapi/components/responses/users/CreateUserModerationForbiddenError.yaml index 0fdfb0a1..f43fbec1 100644 --- a/openapi/components/responses/users/CreateUserModerationForbiddenError.yaml +++ b/openapi/components/responses/users/CreateUserModerationForbiddenError.yaml @@ -1,4 +1,4 @@ -description: Error response when you are not allowed to moderate the user. +description: Error response when the user in the path can't be moderated, such as when they aren't in the instance given by `worldId` and `instanceId`, either of those is missing, or the user is you. content: application/json: examples: From 975c428730a8bdeca2975d5cee86140e7a325f04 Mon Sep 17 00:00:00 2001 From: Aries Clark Date: Wed, 4 Nov 2026 17:54:26 -0500 Subject: [PATCH 4/6] test(users): stop provoking the createUserModeration rate limit --- openapi/components/paths/users.yaml | 2 -- .../CreateUserModerationRateLimitError.yaml | 11 ----------- test/arazzo.yaml | 17 +---------------- 3 files changed, 1 insertion(+), 29 deletions(-) delete mode 100644 openapi/components/responses/users/CreateUserModerationRateLimitError.yaml diff --git a/openapi/components/paths/users.yaml b/openapi/components/paths/users.yaml index e3967e44..d102c5f1 100644 --- a/openapi/components/paths/users.yaml +++ b/openapi/components/paths/users.yaml @@ -109,8 +109,6 @@ paths: $ref: ../responses/users/CreateUserModerationForbiddenError.yaml "404": $ref: ../responses/ResourceNotFoundError.yaml - "429": - $ref: ../responses/users/CreateUserModerationRateLimitError.yaml /userNotes: get: operationId: getUserNotes diff --git a/openapi/components/responses/users/CreateUserModerationRateLimitError.yaml b/openapi/components/responses/users/CreateUserModerationRateLimitError.yaml deleted file mode 100644 index f8a695d7..00000000 --- a/openapi/components/responses/users/CreateUserModerationRateLimitError.yaml +++ /dev/null @@ -1,11 +0,0 @@ -description: Error response when moderating the same user too often. -content: - application/json: - examples: - Too Many Moderations: - value: - error: - message: Too many moderations being created at one player․ - status_code: 429 - schema: - $ref: ../../schemas/Error.yaml diff --git a/test/arazzo.yaml b/test/arazzo.yaml index c03f1d40..bc2fa708 100644 --- a/test/arazzo.yaml +++ b/test/arazzo.yaml @@ -14073,7 +14073,7 @@ workflows: - condition: $statusCode == 404 - workflowId: create-user-moderation-self - summary: createUserModeration refuses the caller as its target, and rate limits a second attempt + summary: createUserModeration refuses the caller as its target parameters: - reference: $components.parameters.userAgent x-security: @@ -14096,21 +14096,6 @@ workflows: - condition: $statusCode == 403 - condition: $response.body#/error/message == 'You cannot moderate this user․' - - stepId: create-user-moderation-rate-limited - operationId: $sourceDescriptions.default.createUserModeration - parameters: - - name: userId - in: path - value: $workflows.session.outputs.userId - requestBody: - contentType: application/json - payload: - reason: x - type: kick - successCriteria: - - condition: $statusCode == 429 - - condition: $response.body#/error/message == 'Too many moderations being created at one player․' - - workflowId: create-user-moderation-unauthenticated summary: createUserModeration refuses an anonymous caller parameters: From 5f2e8666315cd55da02bd19fd5d880c84e3ee6ba Mon Sep 17 00:00:00 2001 From: Aries Clark Date: Wed, 4 Nov 2026 18:10:04 -0500 Subject: [PATCH 5/6] refactor(playermoderation): move createUserModeration under the playermoderation tag --- openapi/components/paths.yaml | 2 +- .../components/paths/playermoderation.yaml | 30 ++++++++++++++++++- openapi/components/paths/users.yaml | 28 ----------------- .../CreateUserModerationForbiddenError.yaml | 0 .../CreateUserModerationResponse.yaml | 0 5 files changed, 30 insertions(+), 30 deletions(-) rename openapi/components/responses/{users => playermoderation}/CreateUserModerationForbiddenError.yaml (100%) rename openapi/components/responses/{users => playermoderation}/CreateUserModerationResponse.yaml (100%) diff --git a/openapi/components/paths.yaml b/openapi/components/paths.yaml index 756c8d07..264c3ce2 100644 --- a/openapi/components/paths.yaml +++ b/openapi/components/paths.yaml @@ -435,7 +435,7 @@ "/user/{userId}/listings": $ref: "./paths/economy.yaml#/paths/~1user~1{userId}~1listings" "/user/{userId}/moderations": - $ref: "./paths/users.yaml#/paths/~1user~1{userId}~1moderations" + $ref: "./paths/playermoderation.yaml#/paths/~1user~1{userId}~1moderations" "/user/{userId}/products": $ref: "./paths/economy.yaml#/paths/~1user~1{userId}~1products" "/user/{userId}/tilia/kyc": diff --git a/openapi/components/paths/playermoderation.yaml b/openapi/components/paths/playermoderation.yaml index 838f09d5..28d938ee 100644 --- a/openapi/components/paths/playermoderation.yaml +++ b/openapi/components/paths/playermoderation.yaml @@ -2,7 +2,7 @@ openapi: 3.2.1 info: title: playermoderation description: |- - There are two different moderation API's, "moderation" for Staff actions, and "playermoderation" for players. + There are two kinds of moderation here: player moderations, and moderations created through `createUserModeration`, such as an instance kick. PlayerModerations are user-generated actions towards others, such as muting them, blocking, or toggling interaction. Your global permission settings are stored locally on your computer. @@ -130,6 +130,34 @@ paths: $ref: ../responses/RequestValidationError.yaml "401": $ref: ../responses/MissingCredentialsError.yaml + "/user/{userId}/moderations": + parameters: + - $ref: ../parameters.yaml#/userId + post: + operationId: createUserModeration + summary: Create User Moderation + description: With `type` `kick`, bans the user in the path from the instance given by `worldId` and `instanceId`. The user is not removed from the instance, but cannot join it again, even by invite. + tags: + - playermoderation + requestBody: + required: true + content: + application/json: + schema: + $ref: ../requests/CreateUserModerationRequest.yaml + security: + - authCookie: [] + responses: + "200": + $ref: ../responses/playermoderation/CreateUserModerationResponse.yaml + "400": + $ref: ../responses/RequestValidationError.yaml + "401": + $ref: ../responses/MissingCredentialsError.yaml + "403": + $ref: ../responses/playermoderation/CreateUserModerationForbiddenError.yaml + "404": + $ref: ../responses/ResourceNotFoundError.yaml components: securitySchemes: $ref: ../securitySchemes.yaml diff --git a/openapi/components/paths/users.yaml b/openapi/components/paths/users.yaml index d102c5f1..0853534f 100644 --- a/openapi/components/paths/users.yaml +++ b/openapi/components/paths/users.yaml @@ -81,34 +81,6 @@ paths: $ref: ../responses/users/PrivateProfileResponse.yaml "401": $ref: ../responses/MissingCredentialsError.yaml - "/user/{userId}/moderations": - parameters: - - $ref: ../parameters.yaml#/userId - post: - operationId: createUserModeration - summary: Create User Moderation - description: With `type` `kick`, bans the user in the path from the instance given by `worldId` and `instanceId`. The user is not removed from the instance, but cannot join it again, even by invite. - tags: - - users - requestBody: - required: true - content: - application/json: - schema: - $ref: ../requests/CreateUserModerationRequest.yaml - security: - - authCookie: [] - responses: - "200": - $ref: ../responses/users/CreateUserModerationResponse.yaml - "400": - $ref: ../responses/RequestValidationError.yaml - "401": - $ref: ../responses/MissingCredentialsError.yaml - "403": - $ref: ../responses/users/CreateUserModerationForbiddenError.yaml - "404": - $ref: ../responses/ResourceNotFoundError.yaml /userNotes: get: operationId: getUserNotes diff --git a/openapi/components/responses/users/CreateUserModerationForbiddenError.yaml b/openapi/components/responses/playermoderation/CreateUserModerationForbiddenError.yaml similarity index 100% rename from openapi/components/responses/users/CreateUserModerationForbiddenError.yaml rename to openapi/components/responses/playermoderation/CreateUserModerationForbiddenError.yaml diff --git a/openapi/components/responses/users/CreateUserModerationResponse.yaml b/openapi/components/responses/playermoderation/CreateUserModerationResponse.yaml similarity index 100% rename from openapi/components/responses/users/CreateUserModerationResponse.yaml rename to openapi/components/responses/playermoderation/CreateUserModerationResponse.yaml From 2308397e6a3946b567d5b71632b0cda8b210c048 Mon Sep 17 00:00:00 2001 From: Aries Clark Date: Wed, 4 Nov 2026 18:15:21 -0500 Subject: [PATCH 6/6] test(playermoderation): cover createUserModeration on a user outside the instance --- test/arazzo.yaml | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/test/arazzo.yaml b/test/arazzo.yaml index bc2fa708..d74a749c 100644 --- a/test/arazzo.yaml +++ b/test/arazzo.yaml @@ -14072,6 +14072,53 @@ workflows: successCriteria: - condition: $statusCode == 404 + - workflowId: create-user-moderation-not-in-instance + summary: createUserModeration refuses a user who is not in the instance it names + inputs: + type: object + required: + - friendId + properties: + friendId: + type: string + parameters: + - reference: $components.parameters.userAgent + x-security: + - schemeName: authCookie + values: + apiKey: $workflows.session.outputs.sessionToken + steps: + - stepId: create-instance + operationId: $sourceDescriptions.default.createInstance + requestBody: + contentType: application/json + payload: + worldId: wrld_4cf554b4-430c-4f8f-b53e-1f294eed230b + type: private + region: use + ownerId: $workflows.session.outputs.userId + successCriteria: + - condition: $statusCode == 200 + outputs: + instanceId: $response.body#/instanceId + + - stepId: create-user-moderation + operationId: $sourceDescriptions.default.createUserModeration + parameters: + - name: userId + in: path + value: $inputs.friendId + requestBody: + contentType: application/json + payload: + instanceId: $steps.create-instance.outputs.instanceId + reason: x + type: kick + worldId: wrld_4cf554b4-430c-4f8f-b53e-1f294eed230b + successCriteria: + - condition: $statusCode == 403 + - condition: $response.body#/error/message == 'You cannot moderate this user․' + - workflowId: create-user-moderation-self summary: createUserModeration refuses the caller as its target parameters: