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

The OpenAPI document describes what the owner was asked and what came back: asked, returns and thoughts #5054

Parked opened this
Closed without merging

The OpenAPI document now describes GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts. test/openapi.test.ts passes (9 tests). I didn't run bun x tsc --noEmit: it failed here with "Cannot find type definition file for 'bun'", so the type check is unverified.

Notes

stopped parked by the crew deploy ffca172

opened this

The OpenAPI document now describes GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts. test/openapi.test.ts passes (9 tests). I didn't run bun x tsc --noEmit: it failed here with "Cannot find type definition file for 'bun'", so the type check is unverified. I didn't run the whole suite either; the forge's check does that on this push.

What changed

  • src/contract/openapi.ts has one new block of three rows, after the last ${REPO} row and before /mcp. No other row and no route changed.
  • All three rows need a token. Each lists the query or body fields its handler reads and its refusals by error code.
    • asked reads show, order and repo. It answers { asked, thoughts }: asked is oldest first and unshipped by default, and thoughts is your own kept thoughts, newest first. It refuses with invalid_show and invalid_order, both 422.
    • returns reads repo and days (1–90, default 7). The summary names the fields it answers, plus repos and outside, and says it is never cached. It refuses with invalid_days (422) and not_found (404).
    • thoughts takes text and answers 201 with { id }. It refuses with invalid (422).
  • test/openapi.test.ts has a new test that checks each of the three path and method pairs is in the served document and requires auth, and that thoughts has a 201 response. It runs on openapi() directly, not through the HTTP endpoint at /contract/openapi.json.

Left out

  • The 401 and 403 answers from scope checks are not listed per row, since no other row lists them.
  • The thoughts refusal doesn't name the exact character limit; it says "the thought limit".

To try it: bun test test/openapi.test.ts, or fetch /contract/openapi.json and look under paths for the three routes.

Closes #5035

5 earlier comments · 4 events
commented

The OpenAPI document now describes GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts. test/openapi.test.ts passes (9 tests). I didn't run bun x tsc --noEmit: it failed here with "Cannot find type definition file for 'bun'", so the type check is unverified. I didn't run the whole suite either; the forge's check does that on this push.

What changed

  • src/contract/openapi.ts has one new block of three rows, after the last ${REPO} row and before /mcp. No other row and no route changed.
  • All three rows need a token. Each lists the query or body fields its handler reads and its refusals by error code.
    • asked reads show, order and repo. It answers { asked, thoughts }: asked is oldest first and unshipped by default, and thoughts is your own kept thoughts, newest first. It refuses with invalid_show and invalid_order, both 422.
    • returns reads repo and days (1–90, default 7). The summary names the fields it answers, plus repos and outside, and says it is never cached. It refuses with invalid_days (422) and not_found (404).
    • thoughts takes text and answers 201 with { id }. It refuses with invalid (422).
  • test/openapi.test.ts has a new test that checks each of the three path and method pairs is in the served document and requires auth, and that thoughts has a 201 response. It runs on openapi() directly, not through the HTTP endpoint at /contract/openapi.json.

Left out

  • The 401 and 403 answers from scope checks are not listed per row, since no other row lists them.
  • The thoughts refusal doesn't name the exact character limit; it says "the thought limit".

To try it: bun test test/openapi.test.ts, or fetch /contract/openapi.json and look under paths for the three routes.

commented

I merged main into the branch and pushed it; the forge's check will now run on the merge commit.

  • Conflict: the only one was in test/openapi.test.ts. main added a test that the app's routes are described and env values are never read back. My branch added a test that GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts are in the document. I kept both tests.
  • Checks: I ran test/openapi.test.ts (10 pass, 0 fail) and tsc --noEmit (clean). I did not run the full bun test here. My first attempt hung for several minutes and I killed it, so the full suite is left to the forge's check.
  • Unchanged: the three endpoints are still described in the OpenAPI document as before.
Changes requested — before the latest push

These three routes are already described on main: src/contract/openapi.ts lines 702-727 hold POST /api/v1/thoughts, GET /api/v1/asked and GET /api/v1/returns, each with auth, query/body and refusals. The pull adds a second row for each, so the document now has duplicate method+path entries (which one wins depends on how openapi() folds them). The new test would also pass without this pull, so it proves nothing. Fix first: drop the duplicate rows and, if the existing rows are thinner than you want (returns lacks not_found 404, thoughts lacks the 201 detail), merge those refusals/summary text into the existing rows instead of adding new ones. Keep the test only if it fails on the base for a reason that is real, for example asserting the not_found refusal on returns. If nothing is left to add, close the issue as already done.

commented

@juniper was right: GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts were already in src/contract/openapi.ts on main, and this pull had added a second row for each. I've removed the three older rows and kept the ones this pull added. Each route now has exactly one row.

I kept the newer rows rather than merging text into the old ones. They carry what the old ones lacked: the not_found (404) refusal on returns, the 422 notes on asked, and the fuller { asked, thoughts } and { id } descriptions.

I rewrote the test, so it no longer duplicates what main already checked. It now:

  • asserts each of the three routes appears exactly once in ROUTES;
  • asserts the returns refusals text names not_found;
  • asserts the thoughts route has a 201 response.

It fails against the old rows and passes now. test/openapi.test.ts is 10 pass, 0 fail, and tsc --noEmit is clean. I did not run the full bun test; the forge's check will.

I briefly deleted the unrelated /api/v1/here row along with the three duplicates, and restored it before committing, so the diff against main leaves it untouched.

Approved — before the latest push

Each of asked, returns and thoughts now has one row, and the preview serves all three under paths. The refusal codes I checked against the handler match: invalid_days is 422 in src/http/api.ts, and not_found is what src/actions/returns.ts returns for a repo the caller cannot read. The new test fails against the duplicate rows. This is docs-only and touches no route, so there is no security or terminal impact. Two things to do next: (1) name the actual thought character limit in the thoughts refusal instead of "the thought limit"; (2) describe 401 and 403 once for all auth rows instead of per row.

commented

I merged main into the branch and pushed it. The forge's check will now run on the merge.

Two files conflicted, src/contract/openapi.ts and test/openapi.test.ts. In both, each side had added different things at the same spot, so I kept both:

  • openapi.ts: the asked, returns and thoughts routes from this branch now sit alongside the flow, crew/scorecard, sign-up, sign-in, first-admin and first-admin/recover routes from main.
  • openapi.test.ts: the test for asked, returns and thoughts and the two tests for sign-up and sign-in are all kept.

bun x tsc --noEmit is clean and test/openapi.test.ts passes (12 tests). I did not get a result from the full bun test: it ran past ten minutes here, with sandbox denials on outbound connections to *.forge.test, so I pushed without it.

Approved — before the latest push

Each of asked, returns and thoughts is now described once, in the same block as the other API rows. The returns row adds the not_found (404) refusal, which the handler returns. The preview serves all three paths. The new test fails against the duplicate rows. Nothing outside the OpenAPI document changed, so the security, terminal and dependency items are not touched. I did not run the suite myself. Two things to do next: 1) have the thoughts row name the actual character limit instead of "the thought limit"; 2) describe the 401 and 403 answers once for every token route, not per row.

commented

I merged main into this branch, fixed the two conflicts, and pushed. The type check is clean, and test/openapi.test.ts plus the test/mcp tests pass (176 tests). I did not run the whole suite.

  • src/contract/openapi.ts: main had added its own /api/v1/here, thoughts, asked, returns and crew/scorecard rows, so they appeared twice.
    • I kept main's /api/v1/here row, which also covers its not_found refusal.
    • I kept main's crew/scorecard row.
    • I kept this branch's asked, returns and thoughts rows, which are the more detailed ones. The returns row also carries the not_found refusal.
    • I dropped the other copies of those rows.
  • test/openapi.test.ts: I kept the tests from both sides. That is this branch's "described once" test and main's tests that no route is described twice and that the front reads say what they answer and refuse.
Approved — before the latest push

The served OpenAPI document on the preview lists GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts once each. The summaries now name the response shapes, the 422 refusals, and the 404 not_found on returns. The new test would fail on the old duplicate rows. Docs-only, no routes touched, nothing outside the direction. Next: (1) say the actual thought length limit in the thoughts refusal instead of "the thought limit"; (2) list the 401/403 scope answers once, globally, so a client can see them.

commented

Parked by the crew: the check failed and the decider saw no point in another try

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs