docs(spec): document that marketplace seller filters by cryptoId (#231) - #272
docs(spec): document that marketplace seller filters by cryptoId (#231)#272M3gA-Mind wants to merge 2 commits into
seller filters by cryptoId (#231)#272Conversation
…inyhumansai#231) `GET /marketplace/identities?seller=` matches the seller's `cryptoId`, but the spec advertised it as a username filter. A client following the spec gets an empty list back — not an error — so the miss reads as "this account has nothing listed". That is the shape of tinyhumansai#231: the handle overview resolved for-sale badges out of a marketplace-wide feed instead of scoping to the viewer, and lost them once the feed outgrew its page size. Reproduced against production on two sellers: `?seller=<cryptoId>` returns 147 and 8 listings respectively, `?seller=bestbot` / `?seller=@bestbot` return 0, and `?sellerCryptoId=<cryptoId>` is ignored outright — the response comes back unfiltered, which is easy to misread as one seller owning the whole marketplace. Also documents `limit` / `offset`, which the endpoint honours today and which any owner-scoped listing lookup needs to page correctly. This records the API as it behaves; whether the backend should also accept a username is a separate call for the backend team.
|
@M3gA-Mind is attempting to deploy a commit to the Vezures Team on Vercel. A member of the Team first needs to authorize it. |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
M3gA-Mind has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.
|
Important Review skippedNo new commits to review since the last review. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis change updates marketplace search documentation in two mirrored docs. It changes the documented ChangesMarketplace search documentation
Estimated code review effort: 1 (Trivial) | ~4 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4a43e94ff1
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| | `q` | Free-text search across names and descriptions | | ||
| | `category` | Filter by category | | ||
| | `tags` | Filter by tags (comma-separated) | | ||
| | `seller` | Filter by seller **`cryptoId`** — not the username. See the note below. | |
There was a problem hiding this comment.
This changes only the served public copy, but gitbooks/commerce/marketplace.md still documents seller as filtering by seller username and lacks the new cryptoId/pagination warning. Since gitbooks/ is the authoritative product/protocol spec, clients reading the canonical docs will still implement username filtering and hit the same empty-result behavior this patch is meant to prevent; please update the GitBook source or sync the two copies together.
AGENTS.md reference: AGENTS.md:L122-L122
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 72bb2f24 — you're right, and the reason it mattered is worse than "two copies drifted".
On the generated-vs-authored question first, since it changes what the fix has to be. website/public/spec/ is not a build artifact of gitbooks/ — there is no generator. Nothing in package.json, the workflows, or scripts/ references public/spec, and the histories confirm it: the served tree was seeded once in ddabaaf1 ("add explore page with sidebar layout and spec docs") and has been touched since only by the repo-wide TinyVerse → TinyPlace rename in 4e9e69c3. gitbooks/commerce/marketplace.md has had six editorial passes in that window that the served copy never received. So the two are hand-maintained siblings, and hand-editing both is the correct fix rather than a workaround.
What changed. gitbooks/commerce/marketplace.md now carries the same seller correction, the same new limit / offset rows, and the same warning block. Those are byte-identical to the served copy — I diffed the region programmatically rather than by eye. The one remaining difference inside that table is sortBy, where gitbooks reads `price`, `rating`, `salesCount`, or `createdAt` and the served copy omits the "or". That is pre-existing stylistic drift, not something this change introduced, so I left it rather than silently tidying it inside a docs-correctness PR.
Wider drift, flagged rather than fixed. The two documents are not near-copies. They differ by ~300 lines out of ~210 each — different structure (10 headings vs 13), different prose throughout, and one genuinely substantive disagreement: the product-record example gives "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" in gitbooks and "network": "eip155:8453" in the served copy. Given 16f06b79 ("correct settlement to Solana-only"), the served copy looks like the stale one there too — but that is a settlement-contract question, not the seller filter this PR is about, and I am not going to resolve it from the outside inside a docs PR. Worth its own issue; happy to open one.
So: the seller contract now agrees across both copies, which is what your comment asked for. The rest of the divergence is real, larger than this PR, and now written down.
There was a problem hiding this comment.
Pushed as 72bb2f24, now the PR head. #272 touches both copies: gitbooks/commerce/marketplace.md and website/public/spec/marketplace.md.
Detail is in my reply above; the short version is that the seller row, the new limit / offset rows and the warning block are byte-identical across the two files, website/public/spec/ turned out not to be generated from gitbooks/ (no generator exists — the served tree was seeded once and has only been touched by a repo-wide rename since), and the wider ~300-line divergence between the two documents is flagged rather than silently fixed.
tinyhumansai#231) Applies the same correction to the authoritative spec. AGENTS.md:122 names `gitbooks/` as authoritative for intended behavior, so a client reading the canonical docs would still implement username filtering and hit the empty-result behaviour this change exists to prevent. The `seller` row, the new `limit` / `offset` rows and the warning block are byte-identical to the served copy in `website/public/spec/`.
There was a problem hiding this comment.
M3gA-Mind has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.
|
@coderabbitai review |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@gitbooks/commerce/marketplace.md`:
- Around line 163-165: Update the request code-fence opening at
gitbooks/commerce/marketplace.md lines 163-165 and
website/public/spec/marketplace.md lines 155-157 to use the http language
identifier, preserving the request examples unchanged.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f04d2583-11a3-4b8e-8940-a504a7b48360
📒 Files selected for processing (2)
gitbooks/commerce/marketplace.mdwebsite/public/spec/marketplace.md
| > ``` | ||
| > GET /marketplace/identities?seller=<cryptoId>&limit=100&offset=0 | ||
| > ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language identifier to both request examples.
markdownlint reports MD040 for both code fences. Use http so syntax renderers and the documentation lint configuration recognize the blocks.
gitbooks/commerce/marketplace.md#L163-L165: change the opening fence to```http.website/public/spec/marketplace.md#L155-L157: change the opening fence to```http.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 163-163: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
📍 Affects 2 files
gitbooks/commerce/marketplace.md#L163-L165(this comment)website/public/spec/marketplace.md#L155-L157
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@gitbooks/commerce/marketplace.md` around lines 163 - 165, Update the request
code-fence opening at gitbooks/commerce/marketplace.md lines 163-165 and
website/public/spec/marketplace.md lines 155-157 to use the http language
identifier, preserving the request examples unchanged.
Source: Linters/SAST tools
1 participant
Documentation-only. Records
GET /marketplace/identitiesas it actually behaves, so the identity-market re-implementation doesn't build on a contract the API doesn't honour.Problem
website/public/spec/marketplace.mddocuments the browsesellerparameter as "Filter by seller username". The live API matches the seller'scryptoIdinstead. A client that follows the spec getscount: 0back — not an error — so a valid account reads as "nothing listed".Reproduced against production on two different sellers:
count?seller=CQNcpyeuAhGjxyuiStmmU4j8fiameGTdmV53dEoztLiz(cryptoId)?seller=B721U8rP585FCMgmXr4hQPzUmD835Cju7evcfJXCY9b9(cryptoId)?seller=bestbot(username, per spec)?seller=@bestbot(username with@)?sellerCryptoId=<cryptoId>The
sellerCryptoIdspelling is the trap worth naming: it is silently dropped and the caller gets the entire marketplace back, which looks like one seller owning everything.This is the contract behind #231. The handle overview there resolved each handle's for-sale badge out of a marketplace-wide feed capped at 100 rows rather than scoping to the viewer, so badges disappeared once the feed outgrew that window — 166 active listings today, 147 of them from the reporter. Full diagnosis in #231.
Solution
selleris documented as taking acryptoId, with a note that a username matches nothing and thatsellerCryptoIdis not a parameter.Adds
limit/offsetrows — both are honoured today (?limit=5→ 5 rows;?offset=160→ the remaining 6 of 166) and were undocumented, yet any owner-scoped lookup needs them to page correctly.Shows the correct call shape for "what has this account listed?":
This documents the API as-built. Whether backend-tinyplace-v2 should also accept a username is a separate decision for the backend team — if it does, this note is the thing to update. Flagged on the issue.
Impact
Docs only — no code, no runtime, no build surface.
website/public/spec/marketplace.mdis served as reference content; nothing imports it.Out of scope, flagged on the issue rather than fixed here:
GET /marketplace/productscurrently returns404 Route Not Foundon backend-v2 while this spec documents it — the same spec/impl drift, but a backend call rather than a docs one.Related
mainin4b9c2eab(2026-06-22), so there is no client code left to patch; bug: For-sale listing status disappears from handle overview for accounts with 140+ handles #231 is best tracked against the identity-market re-implementation.Summary by CodeRabbit
sellerrequires a seller crypto ID.limitandoffsetpagination parameters.