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

scout/forge:scout/5035-the-openapi-document-describes-what-the → main 6 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
2 files changed +44 −25
src/contract/openapi.ts +35 −25
@@ -918,31 +918,6 @@ export const ROUTES: readonly Route[] = [
918918 git: "git failed while committing",
919919 },
920920 },
921 {
922 method: "post",
923 path: "/api/v1/thoughts",
924 summary: "Keep a thought (rw scope); answers 201 with { id }",
925 auth: true,
926 status: 201,
927 body: { text: "string" },
928 refusals: { invalid: "text is not a string within the length limit" },
929 },
930 {
931 method: "get",
932 path: "/api/v1/asked",
933 summary: "What people asked, and the caller's thought stream; answers { asked, thoughts } (ro scope)",
934 auth: true,
935 query: { show: "string", order: "string", repo: "string" },
936 refusals: { invalid_show: "show is all, unshipped or flagged", invalid_order: "order is oldest or newest" },
937 },
938 {
939 method: "get",
940 path: "/api/v1/returns",
941 summary: "What the work returned over the last days, for the caller or one repository; never cached",
942 auth: true,
943 query: { repo: "string", days: "integer" },
944 refusals: { invalid_days: "days is not a whole number in range" },
945 },
946921 { method: "get", path: "/api/v1/here", summary: "The manifest of what you can do at `path` (default /), given who you are: { here, you, actions, mcp, docs }; never cached", auth: false, query: { path: "string" }, refusals: { not_found: "404: the path names no page you can read" } },
947922 {
948923 method: "get",
@@ -1171,6 +1146,30 @@ export const ROUTES: readonly Route[] = [
11711146 fork_failed: "the private repository could not be made",
11721147 },
11731148 },
1149 {
1150 method: "get",
1151 path: "/api/v1/asked",
1152 summary:
1153 "What people asked the crew in the repositories you can write, and what became of each; answers { asked, thoughts }: asked is oldest first by default and holds what has nothing merged yet (show: all, unshipped or flagged; order: oldest or newest), thoughts is your own kept thoughts, newest first",
1154 auth: true,
1155 query: { show: "string", order: "string", repo: "string" },
1156 refusals: {
1157 invalid_show: "show is not all, unshipped or flagged (422)",
1158 invalid_order: "order is not oldest or newest (422)",
1159 },
1160 },
1161 {
1162 method: "get",
1163 path: "/api/v1/returns",
1164 summary:
1165 "What the crew's tokens bought, over every repository you hold the owner's facts for, or one as repo=owner/name; days is a whole number from 1 to 90 (default 7); answers the window, spent, byState, landed, onLanded, landedNothing, okRun, byPillar and costliest, with repos (the names counted) and outside (spend reported by outside sessions, kept apart); never cached",
1166 auth: true,
1167 query: { repo: "string", days: "integer" },
1168 refusals: {
1169 invalid_days: "days is not a whole number from 1 to 90 (422)",
1170 not_found: "repo names no repository whose returns you may read (404)",
1171 },
1172 },
11741173 {
11751174 method: "get",
11761175 path: `${REPO}/flow`,
@@ -1209,6 +1208,17 @@ export const ROUTES: readonly Route[] = [
12091208 email_taken: "422, another account has the address",
12101209 },
12111210 },
1211 {
1212 method: "post",
1213 path: "/api/v1/thoughts",
1214 summary: "Leave a thought, kept exactly as typed and never edited; answers 201 with { id }",
1215 auth: true,
1216 status: 201,
1217 body: { text: "string" },
1218 refusals: {
1219 invalid: "text is not a string of at most the thought limit (422)",
1220 },
1221 },
12121222 {
12131223 method: "post",
12141224 path: "/api/v1/sessions",
test/openapi.test.ts +9
@@ -123,6 +123,14 @@ test("making and listing apps is described with every field the route reads", ()
123123 expect(post.responses.default.description).toContain(`\`${code}\``);
124124 });
125125
126 <<<<<<< HEAD
127 test("asked, returns and thoughts are described once, with the returns not_found refusal", () => {
128 for (const [method, path] of [["get", "/api/v1/asked"], ["get", "/api/v1/returns"], ["post", "/api/v1/thoughts"]])
129 expect(ROUTES.filter((r) => r.method === method && r.path === path).length, `${method} ${path}`).toBe(1);
130 const doc = openapi("https://f.test", "1") as any;
131 expect(doc.paths["/api/v1/returns"].get.responses.default.description).toContain("`not_found`");
132 expect(doc.paths["/api/v1/thoughts"].post.responses["201"]).toBeDefined();
133 =======
126134 test("an issue's teams and labels, a pull's labels and an issue's private repository are described", () => {
127135 const doc = openapi("https://f.test", "1") as any;
128136 const R = "/api/v1/repos/{owner}/{name}";
@@ -137,6 +145,7 @@ test("an issue's teams and labels, a pull's labels and an issue's private reposi
137145 expect(doc.paths[`${R}/issues/{number}/private`].post.responses["201"]).toBeDefined();
138146 expect(doc.paths[`${R}/issues/{number}/teams`].get.security).toBeUndefined();
139147 expect(doc.paths[`${R}/pulls/{number}/labels`].put.security).toBeDefined();
148 >>>>>>> origin/main
140149 });
141150
142151 test("no method and path is described twice, so no row is dead", () => {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs