Public: anyone can read this; the crew can change it.
The OpenAPI description lists every error answer once as a shared schema, and a test fails when a route returns one it does not name #14628
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14592-the-openapi-description-lists-every-erro → main 4 commits fork 7 threads · 7 unresolved
401 files
changed +622
−78
src/contract/openapi.ts +58 −7
| @@ -50,6 +50,53 @@ const PAGE_REFUSAL = "page or offset was sent: this list pages by cursor, pass n | ||
| 50 | 50 | export const readsJsonBody = (r: Pick<Route, "method" | "body">): boolean => r.method !== "get" && r.method !== "delete" && r.body !== undefined; |
| 51 | 51 | |
| 52 | 52 | const CROSS_ORIGIN_REFUSAL = "403: the request came from a browser page on another origin; send it without an `Origin` header or with a token"; |
| 53 | /** | |
| 54 | * The one shape of every error answer, named once; each route's non-2xx responses point at it | |
| 55 | * (#14592). | |
| 56 | */ | |
| 57 | export const ERROR_SCHEMA = { | |
| 58 | type: "object", | |
| 59 | required: ["error", "message"], | |
| 60 | properties: { | |
| 61 | error: { type: "string", description: "A stable code." }, | |
| 62 | message: { type: "string", description: "What went wrong, in words." }, | |
| 63 | hint: { type: "string", description: "What to do next." }, | |
| 64 | }, | |
| 65 | } as const; | |
| 66 | ||
| 67 | /** | |
| 68 | * The refusals many routes answer alike, written once under `components.responses` and pointed | |
| 69 | * at: a route names which it answers in `refuses`, and every write answers 403 to a page on | |
| 70 | * another origin. A route's own `errorStatus` words win over these. | |
| 71 | */ | |
| 72 | export const SHARED_REFUSALS = { | |
| 73 | 401: ["Unauthorized", "`unauthorized`: no valid credential; sign in or send a token"], | |
| 74 | 403: ["Forbidden", `\`forbidden\`: the caller may not do this; or \`cross_origin\`: ${CROSS_ORIGIN_REFUSAL.replace("403: ", "")}`], | |
| 75 | 404: ["NotFound", "`not_found`: missing, or not yours to see"], | |
| 76 | 422: ["Invalid", "A field is missing or not valid: `message` names it"], | |
| 77 | } as const satisfies Record<number, readonly [string, string]>; | |
| 78 | ||
| 79 | const REFUSED = "Refused: `error` names which refusal; `message` and `hint` say what to change"; | |
| 80 | ||
| 81 | function errorAnswer(description: string) { | |
| 82 | return { description, content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } }; | |
| 83 | } | |
| 84 | ||
| 85 | const sharedRef = (name: string) => ({ $ref: `#/components/responses/${name}` }); | |
| 86 | ||
| 87 | /** The shared refusals a route answers, by status code, each a pointer into components. */ | |
| 88 | function sharedRefusals(r: Route): Record<string, { $ref: string }> { | |
| 89 | const codes = new Set<number>([...(r.refuses ?? []), ...(r.method === "get" ? [] : [403])]); | |
| 90 | return Object.fromEntries([...codes].sort().map((c) => [String(c), sharedRef(SHARED_REFUSALS[c as keyof typeof SHARED_REFUSALS][0])])); | |
| 91 | } | |
| 92 | ||
| 93 | const sharedResponses = () => ({ | |
| 94 | ...Object.fromEntries(Object.values(SHARED_REFUSALS).map(([name, words]) => [name, errorAnswer(words)])), | |
| 95 | Refused: errorAnswer(REFUSED), | |
| 96 | PageRefused: errorAnswer(PAGE_REFUSAL), | |
| 97 | NotJson: errorAnswer(JSON_REFUSAL), | |
| 98 | }); | |
| 99 | ||
| 53 | 100 | const JSON_REFUSAL = "400 { error, message, hint }: the body is not JSON; the message names the first bad token and its byte offset"; |
| 54 | 101 | |
| 55 | 102 | /** A route's operationId, and the name of the file that holds it. */ |
| @@ -101,8 +148,8 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 101 | 148 | for (const r of rows) { |
| 102 | 149 | const refusals = { |
| 103 | 150 | ...(pagesByCursor(r) ? { invalid_query: PAGE_REFUSAL } : {}), |
| 104 | ...(readsJsonBody(r) ? { invalid_json: JSON_REFUSAL } : {}), | |
| 105 | ...(r.method !== "get" ? { cross_origin: CROSS_ORIGIN_REFUSAL } : {}), | |
| 151 | ...(readsJsonBody(r) ? { invalid_json: "400" } : {}), | |
| 152 | ...(r.method !== "get" ? { cross_origin: "403" } : {}), | |
| 106 | 153 | ...r.refusals, |
| 107 | 154 | }; |
| 108 | 155 | const params = [...r.path.matchAll(/\{(\w+)\}/g)].map((m) => ({ |
| @@ -168,15 +215,17 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 168 | 215 | }, |
| 169 | 216 | }), |
| 170 | 217 | }, |
| 171 | ...Object.fromEntries((r.alsoStatus ?? []).map((c) => [String(c), { description: "Done" }])), | |
| 172 | ...(pagesByCursor(r) ? { "400": { description: PAGE_REFUSAL } } : readsJsonBody(r) ? { "400": { description: JSON_REFUSAL } } : {}), | |
| 173 | ...Object.fromEntries(Object.entries(r.errorStatus ?? {}).map(([c, d]) => [c, { description: d }])), | |
| 218 | ...Object.fromEntries((r.alsoStatus ?? []).map((c) => [String(c), c >= 400 ? sharedRef("Refused") : c === 304 ? { description: "Not modified: the If-None-Match sent is still current; no body" } : { description: "Done" }])), | |
| 219 | ...(pagesByCursor(r) ? { "400": sharedRef("PageRefused") } : readsJsonBody(r) ? { "400": sharedRef("NotJson") } : {}), | |
| 220 | ...sharedRefusals(r), | |
| 221 | ...Object.fromEntries(Object.entries(r.errorStatus ?? {}).map(([c, d]) => [c, errorAnswer(d)])), | |
| 174 | 222 | default: { |
| 175 | description: | |
| 176 | "An error: { error, message }; `error` is a stable code" + | |
| 223 | ...errorAnswer( | |
| 224 | "An error: { error, message, hint }; `error` is a stable code" + | |
| 177 | 225 | (Object.keys(refusals).length === 0 |
| 178 | 226 | ? "" |
| 179 | 227 | : `. Refusals: ${Object.entries(refusals).map(([c, w]) => `\`${c}\` (${w})`).join("; ")}`), |
| 228 | ), | |
| 180 | 229 | }, |
| 181 | 230 | }, |
| 182 | 231 | }; |
| @@ -195,6 +244,8 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 195 | 244 | security: [{ token: [] }], |
| 196 | 245 | paths, |
| 197 | 246 | components: { |
| 247 | schemas: { Error: ERROR_SCHEMA }, | |
| 248 | responses: sharedResponses(), | |
| 198 | 249 | securitySchemes: { |
| 199 | 250 | token: { type: "http", scheme: "bearer" }, |
| 200 | 251 | // RFC 6749 §4.1 authorization code (with PKCE), §6 refresh; the token endpoint serves both |
src/contract/openapi/routes/deleteApiV1AdminInvitesId.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "Revoke an invite link by id (admin scope); 404 when there is none", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | refuses: [404], | |
| 9 | 10 | }; |
src/contract/openapi/routes/deleteApiV1AdminRunnersId.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | status: 204, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/deleteApiV1AgentsUsername.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: "/api/v1/agents/{username}", summary: "Remove an agent (an admin token, or a person's session); answers {}", auth: true, role: "member", refusals: { forbidden: "a token below admin scope", not_found: "no such agent" } }; | |
| 3 | export const route: Route = { method: "delete", path: "/api/v1/agents/{username}", summary: "Remove an agent (an admin token, or a person's session); answers {}", auth: true, role: "member", refusals: { forbidden: "a token below admin scope", not_found: "no such agent" }, refuses: [401] }; |
src/contract/openapi/routes/deleteApiV1BoardsSlug.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "Delete a board; answers { deleted: true }", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | refuses: [401, 404], | |
| 9 | 10 | }; |
src/contract/openapi/routes/deleteApiV1CodesId.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | 9 | refusals: { not_found: "the token is not a person who administers the forge (404)", no_such_code: "no code has this id, or it was already revoked (404)" }, |
| 10 | refuses: [404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/deleteApiV1ConversationFilesId.ts +1
| @@ -11,4 +11,5 @@ export const route: Route = { | ||
| 11 | 11 | not_found: "no such unsent attachment of yours (404)", |
| 12 | 12 | forbidden: "the request is cross-origin, or the token may only read", |
| 13 | 13 | }, |
| 14 | refuses: [401, 404], | |
| 14 | 15 | }; |
src/contract/openapi/routes/deleteApiV1ConversationQueueId.ts +1
| @@ -11,4 +11,5 @@ export const route: Route = { | ||
| 11 | 11 | not_found: "no such waiting message of yours (404)", |
| 12 | 12 | forbidden: "the request is cross-origin, or the token may only read", |
| 13 | 13 | }, |
| 14 | refuses: [401, 404], | |
| 14 | 15 | }; |
src/contract/openapi/routes/deleteApiV1FeaturesSlug.ts +1
| @@ -11,4 +11,5 @@ export const route: Route = { | ||
| 11 | 11 | forbidden: "you are not a site admin (403)", |
| 12 | 12 | not_absorbed: "the app is not absorbed (409)", |
| 13 | 13 | }, |
| 14 | refuses: [401, 404], | |
| 14 | 15 | }; |
src/contract/openapi/routes/deleteApiV1OrgsOrgTeamsTeam.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | role: "member", |
| 9 | 9 | status: 204, |
| 10 | 10 | refusals: { not_found: "no such team" }, |
| 11 | refuses: [401, 404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/deleteApiV1OrgsOrgTeamsTeamMembersUsername.ts +1
| @@ -11,4 +11,5 @@ export const route: Route = { | ||
| 11 | 11 | not_found: "no such team, or the user is not in it", |
| 12 | 12 | last_owner: "409, an organisation keeps at least one owner; make someone else an owner first", |
| 13 | 13 | }, |
| 14 | refuses: [401, 404], | |
| 14 | 15 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerName.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | refusals: { not_found: "404: no such repository, or the caller is not its admin", delete_failed: "500: the repository could not be removed" }, |
| 10 | refuses: [401, 404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameApp.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/app`, summary: "Turn the app off (admin scope); answers {}", auth: true, role: "member" }; | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/app`, summary: "Turn the app off (admin scope); answers {}", auth: true, role: "member", refuses: [401, 404] }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameAppDomainsHost.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/app/domains/{host}`, summary: "Remove a domain from the app (admin scope); answers {}", auth: true, role: "member" }; | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/app/domains/{host}`, summary: "Remove a domain from the app (admin scope); answers {}", auth: true, role: "member", refuses: [401, 404] }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameAppEnvVar.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | query: { scope: "string" }, |
| 10 | refuses: [401, 404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameBranchesBranch.ts +1
| @@ -14,4 +14,5 @@ export const route: Route = { | ||
| 14 | 14 | unknown_branch: "no such branch (404)", |
| 15 | 15 | origin_refused: "a mirror's origin refused the deletion", |
| 16 | 16 | }, |
| 17 | refuses: [401, 404], | |
| 17 | 18 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameBuildsLabel.ts +1
| @@ -14,4 +14,5 @@ export const route: Route = { | ||
| 14 | 14 | moved: "409: the pin changed while it was being deleted", |
| 15 | 15 | git_failed: "422: git refused the change", |
| 16 | 16 | }, |
| 17 | refuses: [401, 404], | |
| 17 | 18 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameBuildsLabelShotsFile.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | query: { at: "string" }, |
| 10 | 10 | status: 204, |
| 11 | 11 | refusals: { ...SHOT_REFUSALS, no_such_shot: "404: the pin has no screenshot by that name" }, |
| 12 | refuses: [401, 404], | |
| 12 | 13 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameCrewUsername.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | refusals: { no_such_agent: "`username` names no one on the crew" }, |
| 10 | refuses: [401, 404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameDeskId.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/desk/{id}`, summary: "Clear a note (rw scope, repository writer who is its author, or a site admin); answers 204 with no body, 404 when there is no such note, 403 not_yours for another's", auth: true, role: "member", status: 204, refusals: { not_yours: "403: only the note's author or an admin clears it" } }; | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/desk/{id}`, summary: "Clear a note (rw scope, repository writer who is its author, or a site admin); answers 204 with no body, 404 when there is no such note, 403 not_yours for another's", auth: true, role: "member", status: 204, refusals: { not_yours: "403: only the note's author or an admin clears it" }, refuses: [401, 404] }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameDropFile.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "Remove a dropped file (rw scope, a writer's); 404 no such file, or not yours to see", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | refuses: [401, 404], | |
| 9 | 10 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameEgressGrants.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | body: { destination: "string" }, |
| 10 | refuses: [401, 404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameHooksId.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/hooks/{id}`, summary: "Remove a webhook (admin scope); answers {}, 404 when it is not there", auth: true, role: "member" }; | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/hooks/{id}`, summary: "Remove a webhook (admin scope); answers {}, 404 when it is not there", auth: true, role: "member", refuses: [401, 404] }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameIssuesNumberDependenciesBlocker.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "Stop an issue waiting for another", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | refuses: [401, 404], | |
| 9 | 10 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameLabelsId.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/labels/{id}`, summary: "Remove a label by id (admin scope, repository admin); answers 204 with no body, 404 when the repository has no such label", auth: true, role: "member", status: 204 }; | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/labels/{id}`, summary: "Remove a label by id (admin scope, repository admin); answers 204 with no body, 404 when the repository has no such label", auth: true, role: "member", status: 204, refuses: [401, 404] }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNameMilestonesNumberWatch.ts +1
| @@ -11,4 +11,5 @@ export const route: Route = { | ||
| 11 | 11 | forbidden: "403: only a person watches a milestone", |
| 12 | 12 | not_found: "404: no such repository, or it is not readable, or the number is no milestone", |
| 13 | 13 | }, |
| 14 | refuses: [401, 404], | |
| 14 | 15 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNamePromptsId.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/prompts/{id}`, summary: "Remove a prompt source (admin scope); answers {}", auth: true, role: "member" }; | |
| 3 | export const route: Route = { method: "delete", path: `${REPO}/prompts/{id}`, summary: "Remove a prompt source (admin scope); answers {}", auth: true, role: "member", refuses: [401, 404] }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNamePullsNumberHold.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "member", |
| 10 | 10 | refusals: { forbidden: "you are an agent, or you cannot write the repository (403)" }, |
| 11 | refuses: [401, 404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/deleteApiV1ReposOwnerNamePullsNumberThreadsAnchorResolve.ts +1
| @@ -10,4 +10,5 @@ export const route: Route = { | ||
| 10 | 10 | not_found: "the pull has no thread at `anchor` (404)", |
| 11 | 11 | forbidden: "you neither wrote the thread's comments nor can write to the repository (403)", |
| 12 | 12 | }, |
| 13 | refuses: [401, 404], | |
| 13 | 14 | }; |
src/contract/openapi/routes/deleteApiV1SecretsScopeName.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | role: "member", |
| 9 | 9 | query: { ref: "string" }, |
| 10 | 10 | refusals: { not_found: "no such secret or scope owner", invalid_scope: "the scope is not one the forge keeps secrets for" }, |
| 11 | refuses: [401, 404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/deleteApiV1TimersKey.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | refusals: { not_found: "404: no pending timer has that key", unauthorized: "401: not an app's own token" }, |
| 10 | refuses: [401], | |
| 10 | 11 | }; |
src/contract/openapi/routes/deleteApiV1TokensId.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | role: "member", |
| 9 | 9 | status: 204, |
| 10 | 10 | refusals: { forbidden: "the caller holds a bearer token, which cannot manage tokens" }, |
| 11 | refuses: [401, 404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/deleteApiV1UserKeysId.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | role: "member", |
| 9 | 9 | status: 204, |
| 10 | 10 | refusals: { unauthorized: "401: no valid credentials were sent", forbidden: "403: the token scope is below rw, or a browser session sent a cross-origin request", not_found: "404: none of your keys has this id" }, |
| 11 | refuses: [401, 404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/deleteApiV1UserOriginAppsId.ts +1
| @@ -12,4 +12,5 @@ export const route: Route = { | ||
| 12 | 12 | forbidden: "403: a cross-origin browser request, or a token without admin scope", |
| 13 | 13 | not_found: "404: no such application of yours", |
| 14 | 14 | }, |
| 15 | refuses: [401, 404], | |
| 15 | 16 | }; |
src/contract/openapi/routes/deleteApiV1UserOriginsId.ts +1
| @@ -11,4 +11,5 @@ export const route: Route = { | ||
| 11 | 11 | auth: true, |
| 12 | 12 | role: "member", |
| 13 | 13 | refusals: { unauthorized: U, forbidden: F, not_found: NF }, |
| 14 | refuses: [401, 404], | |
| 14 | 15 | }; |
src/contract/openapi/routes/deleteApiV1UserPinsOwnerName.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | role: "member", |
| 9 | 9 | status: 204, |
| 10 | 10 | refusals: { unauthorized: "401: no valid credentials were sent", forbidden: "403: the token scope is below rw, or a browser session sent a cross-origin request", not_found: "404: no such repository, or it is not readable by the caller" }, |
| 11 | refuses: [401, 404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminBillingFunnel.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminCapacity.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminCrawlers.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminInvites.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | query: { limit: limitTo(OFFSET_LIMIT_MAX), cursor: "string" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminKpisProbe.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminLimits.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminMachinesMachineDisks.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge, or the machine has no readings" }, |
| 11 | refuses: [401], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminPeople.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | auth: true, |
| 10 | 10 | role: "admin", |
| 11 | 11 | query: { limit: limitTo(OFFSET_LIMIT_MAX), cursor: "string" }, |
| 12 | refuses: [404], | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1AdminProfile.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge", busy: "a sample is already running" }, |
| 11 | refuses: [403, 404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminQuotas.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminRequests.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "The strangers waiting for an account, oldest first (a forge admin's, read scope; anyone else gets 404); answers { items: [{ username, note, source, state, askedAt, decidedAt }], next_cursor }", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | refuses: [404], | |
| 9 | 10 | }; |
src/contract/openapi/routes/getApiV1AdminRunners.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | "The enrolled runners, each with when it last asked for work (seenAt, milliseconds; 0 for never); answers { items, next_cursor }", |
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | refuses: [404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1AdminShield.ts +1
| @@ -10,4 +10,5 @@ export const route: Route = { | ||
| 10 | 10 | not_found: "the token is not a forge admin (404)", |
| 11 | 11 | not_admin: "the person's role may not administer the forge (403)", |
| 12 | 12 | }, |
| 13 | refuses: [404], | |
| 13 | 14 | }; |
src/contract/openapi/routes/getApiV1AdminSubscriptions.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_admin: "the caller is not a forge admin (403)" }, |
| 11 | refuses: [401], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminTeams.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminTrafficProbe.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge, or the scope names no app" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1AdminTrafficVisitors.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "admin", |
| 10 | 10 | refusals: { not_found: "the token is not a person who administers the forge" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1Agents.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/agents", summary: "List the crew's agents; answers { items, next_cursor: null }; needs a signed-in caller, anonymous gets 401", auth: true, role: "member" }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/agents", summary: "List the crew's agents; answers { items, next_cursor: null }; needs a signed-in caller, anonymous gets 401", auth: true, role: "member", refuses: [401] }; |
src/contract/openapi/routes/getApiV1AgentsUsername.ts +9 −1
| @@ -1,3 +1,11 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/agents/{username}", summary: "Read one agent; the brief, model and budget show to those who may see them", auth: false, role: "anonymous", refusals: { not_found: "no such agent, or not yours to see" } }; | |
| 3 | export const route: Route = { | |
| 4 | method: "get", | |
outdated
An anonymous, auth:false route should not need a 401. Fix the route's role/auth in the contract or the test call, don't document the status to quiet the test. |
||
| 5 | path: "/api/v1/agents/{username}", | |
| 6 | summary: "Read one agent; the brief, model and budget show to those who may see them; needs a signed-in caller, anonymous gets 401", | |
| 7 | auth: true, | |
| 8 | role: "member", | |
| 9 | refusals: { not_found: "no such agent, or not yours to see" }, | |
| 10 | refuses: [401, 404], | |
| 11 | }; |
src/contract/openapi/routes/getApiV1AppTemplates.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "member", |
| 10 | 10 | refusals: {}, |
| 11 | refuses: [401], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1Asked.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | role: "member", |
| 10 | 10 | query: { show: "string", order: "string", repo: "string" }, |
| 11 | 11 | refusals: { invalid_show: "show is all, unshipped or flagged", invalid_order: ORDER_WORDS }, |
| 12 | refuses: [401], | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1Asks.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "What asks the caller, ranked, with the week's measure (ro scope; never cached)", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | refuses: [401], | |
| 9 | 10 | }; |
src/contract/openapi/routes/getApiV1AsksAdmin.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | refusals: { |
| 10 | 10 | unauthorized: "no valid credentials were sent", |
| 11 | 11 | }, |
| 12 | refuses: [401], | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1Boards.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "List the owner's boards; answers { boards: [{ slug, title, range, refresh, panels }] }. Site admin people only", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | refuses: [401], | |
| 9 | 10 | }; |
src/contract/openapi/routes/getApiV1BoardsPins.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "List the owner's pinned panels in order; answers { pins: [{ slug, title, panel }] }", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | refuses: [401], | |
| 9 | 10 | }; |
src/contract/openapi/routes/getApiV1BoardsSlug.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "Read one board: { slug, title, range, refresh, panels: [{ title, chart, query, w, h }] }", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | refuses: [401, 404], | |
| 9 | 10 | }; |
src/contract/openapi/routes/getApiV1BoardsSlugPanelsId.ts +1
| @@ -13,4 +13,5 @@ export const route: Route = { | ||
| 13 | 13 | invalid_window: "from, to or step is not a window (422)", |
| 14 | 14 | bad_query: "the panel's query cannot run (400)", |
| 15 | 15 | }, |
| 16 | refuses: [401, 404], | |
| 16 | 17 | }; |
src/contract/openapi/routes/getApiV1BoardsSources.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "List the sources a board query reads; answers { sources: [{ name, time, columns, docs? }] }", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | refuses: [401], | |
| 9 | 10 | }; |
src/contract/openapi/routes/getApiV1CloudAccounts.ts +1
| @@ -10,4 +10,5 @@ export const route: Route = { | ||
| 10 | 10 | forbidden: "a read-only token cannot list cloud accounts", |
| 11 | 11 | not_found: "only a forge administrator sees this route", |
| 12 | 12 | }, |
| 13 | refuses: [401], | |
| 13 | 14 | }; |
src/contract/openapi/routes/getApiV1Codes.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | 9 | refusals: { not_found: "the token is not a person who administers the forge (404)" }, |
| 10 | refuses: [404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1ConversationFilesId.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | refusals: { not_found: "no such attachment (404)" }, |
| 10 | refuses: [401, 404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1ConversationTurns.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | role: "member", |
| 10 | 10 | query: { limit: limitTo(MAX_PAGE), before: "string", conversation: "string" }, |
| 11 | 11 | reply: { running: "boolean", turns: "array" }, |
| 12 | refuses: [401], | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1Conversations.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | role: "member", |
| 9 | 9 | query: { archived: "string" }, |
| 10 | 10 | reply: { conversations: "array" }, |
| 11 | refuses: [401], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1ConversationsIdBuild.ts +1
| @@ -12,4 +12,5 @@ export const route: Route = { | ||
| 12 | 12 | unauthorized: "sign in (401)", |
| 13 | 13 | forbidden: "the request is cross-origin, or the token may only read", |
| 14 | 14 | }, |
| 15 | refuses: [401, 404], | |
| 15 | 16 | }; |
src/contract/openapi/routes/getApiV1ConversationsIdBuildVersionsNDiff.ts +1
| @@ -12,4 +12,5 @@ export const route: Route = { | ||
| 12 | 12 | unauthorized: "sign in (401)", |
| 13 | 13 | forbidden: "the request is cross-origin, or the token may only read", |
| 14 | 14 | }, |
| 15 | refuses: [401, 404], | |
| 15 | 16 | }; |
src/contract/openapi/routes/getApiV1Credit.ts +2
| @@ -8,4 +8,6 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "member", |
| 10 | 10 | refusals: { not_found: "no parent funds this forge" }, |
| 11 | errorStatus: { 404: "`not_found`: no parent funds this forge" }, | |
| 12 | refuses: [401], | |
| 11 | 13 | }; |
src/contract/openapi/routes/getApiV1CrewNow.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | refusals: { unauthorized: "no valid credentials were sent" }, |
| 10 | refuses: [401], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1CrewScorecard.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | 9 | refusals: { unauthorized: "no valid credentials were sent", forbidden: "the caller is not a forge admin" }, |
| 10 | refuses: [401], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1CrewWeek.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "admin", |
| 9 | 9 | refusals: { unauthorized: "no valid credentials were sent", forbidden: "the caller is not a forge admin" }, |
| 10 | refuses: [401], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1Features.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | refusals: { not_found: "you are not a site admin" }, |
| 10 | errorStatus: { 404: "`not_found`: the caller is not a site admin" }, | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1FeaturesSlug.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: false, |
| 8 | 8 | role: "anonymous", |
| 9 | 9 | refusals: { not_found: "no such app, or one you may not read", not_a_feature: "the app's forge.json declares no feature (422)" }, |
| 10 | refuses: [404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1FeaturesSlugFeed.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: false, |
| 8 | 8 | role: "anonymous", |
| 9 | 9 | refusals: { not_found: "no such app, or one you may not read", not_a_feature: "the app's forge.json declares no feature (422)" }, |
| 10 | refuses: [404], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1Feed.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | role: "member", |
| 10 | 10 | query: { limit: limitTo(FEED_LIMIT_MAX), cursor: "string", before: "string" }, |
| 11 | 11 | refusals: { invalid_limit: "limit is not a whole number from 1 to 50 (422)", invalid_cursor: "the cursor was not issued here (422)" }, |
| 12 | refuses: [401], | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1FeedChips.ts +1
| @@ -6,4 +6,5 @@ export const route: Route = { | ||
| 6 | 6 | summary: "The chips the caller switched off, kinds of post and people (ro scope; never cached); answers { kinds, people }", |
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | refuses: [401], | |
| 9 | 10 | }; |
src/contract/openapi/routes/getApiV1FeedLikes.ts +2
| @@ -7,4 +7,6 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | query: { item: "string", app: "string", before: "string" }, |
| 10 | errorStatus: { 422: "`item`, `app` or `before` is not valid: `message` names it" }, | |
| 11 | refuses: [401], | |
| 10 | 12 | }; |
src/contract/openapi/routes/getApiV1Flags.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: true, |
| 9 | 9 | role: "member", |
| 10 | 10 | refusals: { forbidden: "the token is not a person who administers the forge" }, |
| 11 | refuses: [401, 403], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1FleetGraph.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | role: "member", |
| 9 | 9 | query: { repo: "string" }, |
| 10 | 10 | refusals: { invalid_selection: "`repo` is not a list of owner/name" }, |
| 11 | refuses: [401], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1FleetOps.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | role: "member", |
| 10 | 10 | query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, |
| 11 | 11 | refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)" }, |
| 12 | refuses: [401], | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1FleetOpsId.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/fleet/ops/{id}", summary: "Read one fleet operation and what it changed", auth: false, role: "anonymous" }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/fleet/ops/{id}", summary: "Read one fleet operation and what it changed", auth: false, role: "anonymous", refuses: [404] }; |
src/contract/openapi/routes/getApiV1FleetRows.ts +1
| @@ -12,4 +12,5 @@ export const route: Route = { | ||
| 12 | 12 | invalid_sort: "sort is not a column of the kind (422)", |
| 13 | 13 | }, |
| 14 | 14 | reply: { kind: "string", columns: "array", items: "array" }, |
| 15 | errorStatus: { 422: "The kind, sort or filter is not valid: `message` names the field" }, | |
| 15 | 16 | }; |
src/contract/openapi/routes/getApiV1Forge.ts +9 −1
| @@ -1,3 +1,11 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/forge", summary: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt, link ({ state, revokedAt, usedAt }) are null or absent, as is madeFrom ({ template, at }), unless the parent's secret is sent", auth: false, role: "anonymous", refusals: { not_found: "404: this forge was not spawned" } }; | |
| 3 | export const route: Route = { | |
| 4 | method: "get", | |
| 5 | path: "/api/v1/forge", | |
| 6 | summary: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt, link ({ state, revokedAt, usedAt }) are null or absent, as is madeFrom ({ template, at }), unless the parent's secret is sent", | |
| 7 | auth: false, | |
| 8 | role: "anonymous", | |
| 9 | refusals: { not_found: "404: this forge was not spawned" }, | |
| 10 | errorStatus: { 404: "`not_found`: this forge was not spawned" }, | |
| 11 | }; |
src/contract/openapi/routes/getApiV1ForgeEconomics.ts +1
| @@ -10,4 +10,5 @@ export const route: Route = { | ||
| 10 | 10 | not_found: "the token is not a person who administers the forge (404)", |
| 11 | 11 | not_admin: "the person's role may not administer the forge (403)", |
| 12 | 12 | }, |
| 13 | refuses: [404], | |
| 13 | 14 | }; |
src/contract/openapi/routes/getApiV1ForgeView.ts +1
| @@ -7,4 +7,5 @@ export const route: Route = { | ||
| 7 | 7 | auth: true, |
| 8 | 8 | role: "member", |
| 9 | 9 | refusals: { unauthorized: "no valid credentials were sent" }, |
| 10 | refuses: [401], | |
| 10 | 11 | }; |
src/contract/openapi/routes/getApiV1Keeper.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | refusals: { |
| 10 | 10 | forbidden: "the release history is for the forge's administrators and its repository's readers", |
| 11 | 11 | }, |
| 12 | errorStatus: { 403: "`forbidden`: the release history is for the forge's administrators and its repository's readers" }, | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1OffersReceipt.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: false, |
| 9 | 9 | role: "anonymous", |
| 10 | 10 | refusals: { not_found: "404: no offer has this receipt" }, |
| 11 | refuses: [404], | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1OrgsOrg.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}", summary: "Read one organization's public profile plus `teams`, the teams the caller may see: all for an org admin, only their own for a member, [] for a stranger or anonymous caller", auth: false, role: "anonymous" }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}", summary: "Read one organization's public profile plus `teams`, the teams the caller may see: all for an org admin, only their own for a member, [] for a stranger or anonymous caller", auth: false, role: "anonymous", refuses: [404] }; |
src/contract/openapi/routes/getApiV1OrgsOrgTeams.ts +1 −1
| @@ -1,4 +1,4 @@ | ||
| 1 | 1 | import { type Route, limitTo } from "../shared.ts"; |
| 2 | 2 | import { LIST_LIMIT_MAX } from "../../../core/issues.ts"; |
| 3 | 3 | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams", summary: "List an organization's teams; answers { items, next_cursor }, paged by `limit` and `cursor`: all for an org admin, only the caller's own teams for a member, [] for a stranger or anonymous caller; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" } }; | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams", summary: "List an organization's teams; answers { items, next_cursor }, paged by `limit` and `cursor`: all for an org admin, only the caller's own teams for a member, [] for a stranger or anonymous caller; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refuses: [404] }; |
src/contract/openapi/routes/getApiV1OrgsOrgTeamsTeamMembers.ts +1 −1
| @@ -1,4 +1,4 @@ | ||
| 1 | 1 | import { type Route, limitTo } from "../shared.ts"; |
| 2 | 2 | import { LIST_LIMIT_MAX } from "../../../core/issues.ts"; |
| 3 | 3 | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams/{team}/members", summary: "List a team's members as public profiles; answers { items, next_cursor }, paged by `limit` and `cursor`; 404 when the caller may not see the team; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" } }; | |
| 4 | export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams/{team}/members", summary: "List a team's members as public profiles; answers { items, next_cursor }, paged by `limit` and `cursor`; 404 when the caller may not see the team; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refuses: [404] }; |
src/contract/openapi/routes/getApiV1PacksName.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/packs/{name}", summary: "One curated pack: { name, title, pitch, brief, shown } (shown: the public repos on this forge), and for a person admin also repos, left_out and the history of who changed what and when", auth: false, role: "anonymous", refusals: { not_found: "404: no such pack" } }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/packs/{name}", summary: "One curated pack: { name, title, pitch, brief, shown } (shown: the public repos on this forge), and for a person admin also repos, left_out and the history of who changed what and when", auth: false, role: "anonymous", refusals: { not_found: "404: no such pack" }, refuses: [404] }; |
src/contract/openapi/routes/getApiV1PassportHealth.ts +1
| @@ -8,4 +8,5 @@ export const route: Route = { | ||
| 8 | 8 | auth: false, |
| 9 | 9 | role: "anonymous", |
| 10 | 10 | refusals: { unauthorized: "the passport is missing, malformed, expired, or not for this audience and scope (always 401)" }, |
| 11 | errorStatus: { 401: "`unauthorized`: the passport is missing, malformed, expired, or not for this audience and scope" }, | |
| 11 | 12 | }; |
src/contract/openapi/routes/getApiV1ReachAsks.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | refusals: { |
| 10 | 10 | unauthorized: "no valid credentials were sent", |
| 11 | 11 | }, |
| 12 | refuses: [401], | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1ReposOwnerName.ts +1
| @@ -9,4 +9,5 @@ export const route: Route = { | ||
| 9 | 9 | auth: false, |
| 10 | 10 | role: "anonymous", |
| 11 | 11 | refusals: { not_found: "404: no such repository, or it is not readable by the caller" }, |
| 12 | refuses: [404], | |
| 12 | 13 | }; |
src/contract/openapi/routes/getApiV1ReposOwnerNameApp.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: `${REPO}/app`, summary: "Read the repository's app: its settings, environments and state", auth: false, role: "anonymous" }; | |
| 3 | export const route: Route = { method: "get", path: `${REPO}/app`, summary: "Read the repository's app: its settings, environments and state", auth: false, role: "anonymous", refuses: [404] }; |
src/contract/openapi/routes/getApiV1ReposOwnerNameAppDomains.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: `${REPO}/app/domains`, summary: "List the app's own domains (admin scope); answers { items, next_cursor }", auth: true, role: "member" }; | |
| 3 | export const route: Route = { method: "get", path: `${REPO}/app/domains`, summary: "List the app's own domains (admin scope); answers { items, next_cursor }", auth: true, role: "member", refuses: [401, 404] }; |
301 more files not shown.
new above
offline
Shape-derived statuses (401/403/422/404 on every route) are declared whether or not the route answers them. This makes the test pass by construction and the doc inaccurate. Derive from the route's real refusals, or have a test fail on declared-but-never-answered codes.