Merge pull request #791 from decentraland/feat/re-discovery-add-ranking-endpoint

feat: add ranking update endpoint for places

Author: AndresMorelos

docs/ai-agent-context.md

@@ -68,7 +68,7 @@ The Decentraland Places service is a comprehensive API solution for discovering,
 
 The service exposes a REST API under `/api` with comprehensive documentation in [OpenAPI 3.0 format](openapi.yaml). Key endpoint categories:
 
-- **Places**: `/api/places`, `/api/places/:id`, `/api/places/status`, `/api/places/:id/categories`, `/api/places/:id/rating`, `/api/places/:id/highlight` (admin only) (POST `/api/places` accepts array of place IDs in body)
+- **Places**: `/api/places`, `/api/places/:id`, `/api/places/status`, `/api/places/:id/categories`, `/api/places/:id/rating`, `/api/places/:id/ranking` (service token auth via `DATA_TEAM_AUTH_TOKEN` env var), `/api/places/:id/highlight` (admin only) (POST `/api/places` accepts array of place IDs in body)
 - **Worlds**: `/api/worlds`, `/api/world_names`
 - **Destinations**: `/api/destinations` (GET: combined places + worlds with enhanced filtering including SDK version and LIKE name matching; highlighted items are always returned first, followed by ranking value, then by specified sort order. POST: accepts array of destination IDs in body, maximum 100 IDs per request, supports all GET query parameters for additional filtering)
 - **Map**: `/api/map`, `/api/map/places` (coordinate-based queries with higher limits)

docs/openapi.yaml

@@ -530,6 +530,93 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
+  /places/{place_id}/ranking:
+    put:
+      tags:
+        - Places
+      summary: Update place ranking 🔒 (Service token)
+      security:
+        - ServiceToken: []
+      description: |
+        Update the ranking score for a place. **Requires service token authentication.**
+
+        This endpoint uses a pre-configured service token for authentication, intended for
+        service-to-service calls from the data team's systems. The token must be provided
+        in the Authorization header as `Bearer <token>` or just `<token>`.
+
+        The ranking value is used to order places in listings. Higher ranking values appear first
+        (after highlighted places). This endpoint is intended for the data team to curate
+        place ordering based on quality metrics or promotional needs.
+
+        **Use Cases:**
+        - Promote high-quality places in listings
+        - Adjust place ordering based on data analysis
+        - Set custom ordering for promotional periods
+
+        **Authentication:**
+        Set the `DATA_TEAM_AUTH_TOKEN` environment variable on the server, then use that
+        token value in the Authorization header when calling this endpoint.
+      operationId: updatePlaceRanking
+      parameters:
+        - name: place_id
+          in: path
+          required: true
+          description: UUID of the place to update ranking
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateRankingBody'
+            examples:
+              setRanking:
+                summary: Set ranking value
+                value:
+                  ranking: 0.85
+              removeRanking:
+                summary: Remove ranking (set to null)
+                value:
+                  ranking: null
+      responses:
+        '200':
+          description: Ranking updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceResponse'
+        '401':
+          description: Unauthorized - missing or invalid token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                ok: false
+                error: "Authorization required"
+        '403':
+          description: Forbidden - invalid authorization token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                ok: false
+                error: "Invalid authorization token"
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          description: Internal server error - service authentication not configured
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                ok: false
+                error: "Service authentication not configured"
+
   /places/{place_id}/highlight:
     put:
       tags:
@@ -1651,6 +1738,19 @@ components:
         2. Get the auth token from the SDK
         3. Include in requests: `Authorization: Bearer <token>`
 
+    ServiceToken:
+      type: http
+      scheme: bearer
+      description: |
+        Pre-configured service token for service-to-service authentication.
+
+        This authentication method is used for internal service calls, such as
+        the data team's ranking updates. The token value must match the
+        `DATA_TEAM_AUTH_TOKEN` environment variable configured on the server.
+
+        To authenticate:
+        Include in requests: `Authorization: Bearer <service-token>` or `Authorization: <service-token>`
+
   schemas:
     Place:
       type: object
@@ -2089,6 +2189,19 @@ components:
           description: Optional explanation for the rating change (for moderation log)
           example: "Updated due to new interactive content"
 
+    UpdateRankingBody:
+      type: object
+      required:
+        - ranking
+      properties:
+        ranking:
+          type: number
+          nullable: true
+          description: |
+            Ranking score for ordering places. Higher values appear first in listings
+            (after highlighted places). Set to null to remove ranking.
+          example: 0.85
+
     UpdateHighlightBody:
       type: object
       required:

src/api/CommsGatekeeper.ts

@@ -56,11 +56,11 @@ export default class CommsGatekeeper extends API {
       return cached.addresses
     }
 
-    const { signal, abort } = new AbortController()
-    const fetchOptions = new Options({ signal })
+    const controller = new AbortController()
+    const fetchOptions = new Options({ signal: controller.signal })
 
     const timeoutId = setTimeout(() => {
-      abort()
+      controller.abort()
     }, Time.Second * 10)
 
     try {
@@ -107,11 +107,11 @@ export default class CommsGatekeeper extends API {
       return cached.addresses
     }
 
-    const { signal, abort } = new AbortController()
-    const fetchOptions = new Options({ signal })
+    const controller = new AbortController()
+    const fetchOptions = new Options({ signal: controller.signal })
 
     const timeoutId = setTimeout(() => {
-      abort()
+      controller.abort()
     }, Time.Second * 10)
 
     try {

src/entities/Place/routes/index.ts

@@ -8,6 +8,7 @@ import { getPlaceList } from "./getPlaceList"
 import { getPlaceListById } from "./getPlaceListById"
 import { getPlaceStatusListById } from "./getPlaceStatusListById"
 import { updateHighlight } from "./updateHighlight"
+import { updateRanking } from "./updateRanking"
 import { updateRating } from "./updateRating"
 
 export const DECENTRALAND_URL = env("DECENTRALAND_URL", "")
@@ -34,8 +35,8 @@ export default routes((router) => {
   router.get("/places", getPlaceList)
   router.post("/places", getPlaceListById)
   router.put("/places/:place_id/rating", updateRating)
+  router.put("/places/:place_id/ranking", updateRanking)
   router.put("/places/:place_id/highlight", updateHighlight)
   router.get("/places/:place_id/categories", getPlaceCategories)
-  router.put("/places/:place_id/rating", updateRating)
   router.post("/places/status", getPlaceStatusListById)
 }, {})