Add mapbox feedback list/get

CHANGELOG.md

@@ -29,7 +29,15 @@ that may never merge. They are not releases and are not listed here.
   what is unchanged from what was published, reporting local edits rather
   than discarding them. `MAPBOX_CLI_NO_AGENT_SETUP=1` skips the question
   entirely, same spelling convention as `MAPBOX_CLI_NO_TELEMETRY`.
-
+- `mapbox feedback list`/`get`, reading the feedback end users submit from
+  apps built with Mapbox — filterable, sortable, paginated. Each filter
+  takes one value for now. Hand-authored into
+  `custom-openapi/`, like `search`, because no upstream spec exists yet.
+  `feedback create`, the write side, is not a command — confirmed directly
+  against production that `user-feedback:write` is silently dropped from a
+  `POST /oauth/register` grant, the same unregistrable shape
+  `accounts create-token` already documents, so no `mapbox auth login`
+  token can ever carry it.
 - `mapbox generate-skills`/`agent-skills install`/`agent-skills update`,
   when no coding agent is detected and none was named with `--agent`,
   `--global` or `--dir`: the failure now carries a stable

README.md

@@ -215,6 +215,7 @@ Each Mapbox API is a command group, with one subcommand per operation:
 
 ```sh
 mapbox accounts <operation>
+mapbox feedback <operation>
 mapbox fonts <operation>
 mapbox geocoder <operation>
 mapbox search <operation>

custom-openapi/feedback/openapi/feedback.yaml

@@ -0,0 +1,229 @@
+openapi: "3.0.0"
+# `parse_spec` turns `info.description` below into this service's clap
+# `long_about`, so it also reaches `mapbox feedback --help`, `--schema` and
+# `generate-skills` output. Keep it to API prose only — the provenance below
+# is for whoever edits this file, not for a CLI user:
+#
+# Hand-authored down to the parameters documented at
+# docs.mapbox.com/api/feedback. See `custom-openapi/README.md` for how a
+# file like this is wired in. `createFeedbackItem` is declared here but
+# never reaches the command surface: it needs `user-feedback:write`, which
+# `POST /oauth/register` silently drops from the granted scope — confirmed
+# directly against production (`curl -X POST
+# https://api.mapbox.com/oauth/register?scope=user-feedback:write ...`
+# returns a registration with that scope missing from the response, the
+# same shape `tokens:write` already documents in `src/spec.rs`'s
+# `UNSUPPORTED_OPERATIONS`). No `mapbox auth login` token
+# can ever carry it, so `feedback create` is not a command today.
+info:
+  title: "Mapbox Feedback API"
+  description: >-
+    Feedback that end users submit from apps built with Mapbox, through
+    the Feedback Agent — filterable, sortable, and paginated.
+  version: "0.0.0"
+servers:
+  - url: https://api.mapbox.com
+    description: Feedback API
+paths:
+  /user-feedback/v1/feedback:
+    get:
+      operationId: list
+      summary: List feedback items.
+      description: >-
+        Every feedback item on the account, oldest received first by
+        default — filterable by id, status, category, a free-text search
+        phrase, trace id, or a time window on when it was created,
+        received, or last updated. Paginated with `--after`/`start_cursor`/
+        `end_cursor` the way every other listing on this CLI is.
+      parameters:
+        - name: "access_token"
+          in: query
+          required: true
+          description: "Mapbox API Access Token"
+          schema:
+            type: string
+            minLength: 1
+        # The API takes several values for `feedback_id`, `status`,
+        # `category` and `trace_id` only as a repeated parameter
+        # (`status=a&status=b`). A comma-separated value is not split:
+        # `status` answers it with a 400, and the others silently match
+        # nothing — both verified against production on 2026-10-02. The
+        # command builder can't repeat a query parameter yet, so each of
+        # these takes one value for now. `status` stays prose rather than an
+        # `enum` so it can become a list later without a breaking change to
+        # its value parser.
+        - name: "feedback_id"
+          in: query
+          required: false
+          description: "Limit to one feedback id."
+          schema:
+            type: string
+        - name: "after"
+          in: query
+          required: false
+          description: "A cursor from a previous response's `end_cursor`, to page forward."
+          schema:
+            type: string
+        - name: "limit"
+          in: query
+          required: false
+          description: "Maximum items to return, up to 1000."
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+        - name: "sort_by"
+          in: query
+          required: false
+          description: >-
+            Which timestamp to sort by. Defaults to `received_at`.
+          schema:
+            type: string
+            enum: ["received_at", "created_at", "updated_at"]
+        - name: "order"
+          in: query
+          required: false
+          description: "Sort direction. Defaults to `asc`."
+          schema:
+            type: string
+            enum: ["asc", "desc"]
+        - name: "status"
+          in: query
+          required: false
+          description: >-
+            Limit to one status: `received`, `fixed`, `reviewed`, or
+            `out_of_scope`.
+          schema:
+            type: string
+          example: "received"
+        - name: "category"
+          in: query
+          required: false
+          description: >-
+            Limit to one feedback category. Categories are
+            account-specific, so there is no fixed list here.
+          schema:
+            type: string
+        - name: "search"
+          in: query
+          required: false
+          description: "A phrase to match against feedback text."
+          schema:
+            type: string
+        - name: "trace_id"
+          in: query
+          required: false
+          description: >-
+            Limit to one trace id, as provided by the app that submitted
+            the feedback.
+          schema:
+            type: string
+        # "ISO 8601" trails each of these six rather than leads them:
+        # `first_sentence` in `src/main.rs` cuts a `--help` line at the
+        # first `.`, and "ISO 8601." on its own left `--help` showing just
+        # that. `--schema` and `docs/commands.md` still show each in full.
+        - name: "created_before"
+          in: query
+          required: false
+          description: "Only items the end user created before this time, ISO 8601."
+          schema:
+            type: string
+        - name: "created_after"
+          in: query
+          required: false
+          description: "Only items the end user created after this time, ISO 8601."
+          schema:
+            type: string
+        - name: "received_before"
+          in: query
+          required: false
+          description: "Only items Mapbox received before this time, ISO 8601."
+          schema:
+            type: string
+        - name: "received_after"
+          in: query
+          required: false
+          description: "Only items Mapbox received after this time, ISO 8601."
+          schema:
+            type: string
+        - name: "updated_before"
+          in: query
+          required: false
+          description: "Only items last updated before this time, ISO 8601."
+          schema:
+            type: string
+        - name: "updated_after"
+          in: query
+          required: false
+          description: "Only items last updated after this time, ISO 8601."
+          schema:
+            type: string
+      responses:
+        "200":
+          description: >-
+            A JSON object with an `items` array (each a feedback item: `id`,
+            `status`, `category`, `feedback`, `location`, timestamps), plus
+            `has_after`/`end_cursor` and `has_before`/`start_cursor` for
+            paging either direction.
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+
+    post:
+      # Not `create`: this operation is never reachable (see below), so the
+      # user-facing name doesn't matter — but the withheld-operation guard
+      # in `generate_skills.rs` checks the bare command word against every
+      # generated file's text, and a bare `create` collides with the
+      # exposed, unrelated `styles create`. A multi-word operationId, the
+      # same shape every other disabled operation already has
+      # (`createToken`, `getFontCoverage`, …), sidesteps that.
+      operationId: createFeedbackItem
+      summary: Submit a new feedback item.
+      description: >-
+        Not a command — see this file's own header comment for why.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        "201":
+          description: The created feedback item.
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+
+  /user-feedback/v1/feedback/{feedback_id}:
+    get:
+      operationId: get
+      summary: Retrieve one feedback item by id.
+      parameters:
+        - name: "feedback_id"
+          in: path
+          required: true
+          description: "The feedback item's id."
+          schema:
+            type: string
+            minLength: 1
+        - name: "access_token"
+          in: query
+          required: true
+          description: "Mapbox API Access Token"
+          schema:
+            type: string
+            minLength: 1
+      responses:
+        "200":
+          description: >-
+            The feedback item: `id`, `status`, `category`, `feedback`,
+            `location` (`place_name`, `lon`, `lat`), and its
+            created/received/updated timestamps.
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not Found — no feedback item with that id.