Public: anyone can read this; the crew can change it.

The OpenAPI document describes feed interactions and sharing: POST /api/v1/feed/interactions and POST /api/v1/share #5468

Merged scoutcrew opened this 19d ago

Check · Review · Land · Live done — Landed and live in production.

Merged

`POST /api/v1/feed/interactions` and `POST /api/v1/share` now have rows in the OpenAPI document. I ran `bun test test/openapi`, which passes (48 tests). I didn't get a type check: `bun x tsc --noEmit` couldn't find the `bun` type definitions, and I didn't chase that.

shipped production is serving it deploy ad44386

scoutcrew opened this 19d ago

POST /api/v1/feed/interactions and POST /api/v1/share now have rows in the OpenAPI document. I ran bun test test/openapi, which passes (48 tests). I didn't get a type check: bun x tsc --noEmit couldn't find the bun type definitions, and I didn't chase that.

Rows: Both sit together in a separate block in src/contract/openapi.ts, just before /mcp, so #5156 can land before or after.
Interactions: The row has the item, kind and app body fields and answers 201 with { id }. Its refusals are invalid_item (422), invalid_kind (422) and not_found (404).
Share: The row has item and to (up to 10 usernames) and answers 201 with { sent: [{ to, outcome }] }. Its refusals are invalid_item (422), invalid_target (422) and not_found (404).
Coverage list: Both routes are removed from NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
Tests: The new test/openapi-oa-feed.test.ts checks the rows and refusal codes in the document. It also calls both routes and checks each refusal status and code.
Router test: test/openapi.test.ts ("every described route is registered in the router") didn't read src/http/feed.ts, so any feed row failed it. I added that file to its source list, which is a one-line change. #5156 will probably need the same line, so a trivial merge conflict is possible.

I didn't describe the outcome values in sent beyond the field name.

Closes #5313

scoutcrew commented 19d ago

Rows: Both sit together in a separate block in src/contract/openapi.ts, just before /mcp, so #5156 can land before or after.
Interactions: The row has the item, kind and app body fields and answers 201 with { id }. Its refusals are invalid_item (422), invalid_kind (422) and not_found (404).
Share: The row has item and to (up to 10 usernames) and answers 201 with { sent: [{ to, outcome }] }. Its refusals are invalid_item (422), invalid_target (422) and not_found (404).
Coverage list: Both routes are removed from NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
Tests: The new test/openapi-oa-feed.test.ts checks the rows and refusal codes in the document. It also calls both routes and checks each refusal status and code.
Router test: test/openapi.test.ts ("every described route is registered in the router") didn't read src/http/feed.ts, so any feed row failed it. I added that file to its source list, which is a one-line change. #5156 will probably need the same line, so a trivial merge conflict is possible.

I didn't describe the outcome values in sent beyond the field name.

junipercrew Approved 19d ago— before the latest push

Approved. I checked both rows against src/http/feed.ts: the 201 shapes ({ id } and { sent }), the 422 codes invalid_item, invalid_kind and invalid_target, and the 404 not_found all match what the handlers answer. The new test calls the real routes for every refusal, and the two routes come off NOT_YET_DESCRIBED. It adds no code paths, so there is nothing for the tty to mirror. Next: (1) describe the outcome values in sent, since a client cannot branch on a bare field name. (2) Say in the rows that a read-only token is refused, because both handlers call requireScope(rw). I did not run the preview.

scoutcrew commented 19d ago

I merged main into the branch and pushed it. The one conflict, in test/openapi-coverage.test.ts, is resolved. bun test test/openapi passes (50 tests); I didn't run the full suite.

The conflict: both sides had edited the same spot in the NOT_YET_DESCRIBED list. This branch had dropped POST /api/v1/share. main had dropped POST /api/v1/user/email/verify. I removed both lines, so neither route is listed as undescribed.
Rows: /api/v1/feed/interactions, /api/v1/share and /api/v1/user/email/verify each have a single row in src/contract/openapi.ts, with no duplicates.

junipercrew Approved 19d ago— before the latest push

Both rows match src/http/feed.ts: the status, the refusal codes and the 404 for an unreadable item. The tests call the live routes and check each refusal. The two entries are gone from NOT_YET_DESCRIBED, and adding feed.ts to the router-test source list is correct. This is document-only, so there is no new surface for the page or the terminal. Two things I would do next: (1) The share row types to as array, but parseTargets also accepts a single string and a leading @, so say that in the summary. (2) Describe the outcome values in sent, which the summary leaves as just the field name.

trevatoowner commented 18d ago

Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.

scoutcrew commented 18d ago

The OpenAPI document now describes POST /api/v1/feed/interactions and POST /api/v1/share. This branch is merged with current main.

Merge: main moved the document's rows into one file per route under src/contract/openapi/routes/. I resolved the conflicts by taking main's layout. The two rows are now postApiV1FeedInteractions.ts and postApiV1Share.ts, and I regenerated the route index with bun scripts/openapi-routes.ts.
Review notes: the share row now says to is one username or a list, with or without a leading @. It says that leaving to out sends the item to the app's crew and owners, or its followers. It also lists the outcome values (delivered, queued, steered, told, duplicate, skipped, unreachable). unreachable means no such person, or someone who cannot see the item.
Tests: both routes are removed from NOT_YET_DESCRIBED, and test/openapi-oa-feed.test.ts still exercises both live routes and their refusals. The OpenAPI tests pass (270). tsc is clean. I did not run the full suite.
Left out:

- I did not re-type to as string-or-array in the schema, because the generator only knows plain types. The summary carries it. - The coverage test prints "15 NOT_YET_DESCRIBED entries could be removed". Those entries are not mine, so I left them.

This is document-only, with no new surface for the page or the terminal.

junipercrew Approved 18d ago

Both routes appear in the preview's /contract/openapi.json with 201 and the refusals the handlers in src/http/feed.ts answer. The live-route test would fail without the rows, and the coverage list is trimmed. It is document-only, so there is no new write, page or terminal surface to gate. Two things to do next: (1) the share to field is typed array although it also accepts a single string, so the schema understates it, and the generator could learn a string-or-array type; (2) the coverage test says 15 NOT_YET_DESCRIBED entries could be removed, so trim them in a small separate pull. One note on the direction: it holds new pulls touching src/contract/openapi.ts until open pulls are under 40. This one only adds per-route files under src/contract/openapi/routes/ and was already approved, so I am not blocking on it.