@panneau/protocol 5.0.0-alpha.3 → 5.0.0-alpha.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/addresses.d.ts +23 -0
- package/dist/addresses.d.ts.map +1 -0
- package/dist/addresses.js +52 -0
- package/dist/addresses.js.map +1 -0
- package/dist/compound.d.ts +20 -0
- package/dist/compound.d.ts.map +1 -0
- package/dist/compound.js +27 -0
- package/dist/compound.js.map +1 -0
- package/dist/conditions.d.ts +1 -1
- package/dist/conformance/index.d.ts +6 -0
- package/dist/conformance/index.d.ts.map +1 -1
- package/dist/conformance/index.js +801 -11
- package/dist/conformance/index.js.map +1 -1
- package/dist/constants.d.ts +108 -2
- package/dist/constants.d.ts.map +1 -1
- package/dist/constants.js +181 -3
- package/dist/constants.js.map +1 -1
- package/dist/context.d.ts +15 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +34 -0
- package/dist/context.js.map +1 -0
- package/dist/currencies.d.ts +22 -0
- package/dist/currencies.d.ts.map +1 -0
- package/dist/currencies.js +231 -0
- package/dist/currencies.js.map +1 -0
- package/dist/index.d.ts +4 -4
- package/dist/index.js +19 -8
- package/dist/libraries.d.ts +33 -0
- package/dist/libraries.d.ts.map +1 -0
- package/dist/libraries.js +59 -0
- package/dist/libraries.js.map +1 -0
- package/dist/links.d.ts +38 -0
- package/dist/links.d.ts.map +1 -0
- package/dist/links.js +65 -0
- package/dist/links.js.map +1 -0
- package/dist/lint.d.ts +4 -3
- package/dist/lint.d.ts.map +1 -1
- package/dist/lint.js +168 -7
- package/dist/lint.js.map +1 -1
- package/dist/mock/auth.d.ts +71 -0
- package/dist/mock/auth.d.ts.map +1 -0
- package/dist/mock/auth.js +346 -0
- package/dist/mock/auth.js.map +1 -0
- package/dist/mock/example.d.ts +3 -2
- package/dist/mock/example.d.ts.map +1 -1
- package/dist/mock/example.js +241 -144
- package/dist/mock/example.js.map +1 -1
- package/dist/mock/index.d.ts +79 -7
- package/dist/mock/index.d.ts.map +1 -1
- package/dist/mock/index.js +603 -38
- package/dist/mock/index.js.map +1 -1
- package/dist/openapi.d.ts.map +1 -1
- package/dist/openapi.js +392 -144
- package/dist/openapi.js.map +1 -1
- package/dist/problem.d.ts +1 -1
- package/dist/query.d.ts +18 -0
- package/dist/query.d.ts.map +1 -1
- package/dist/query.js +34 -8
- package/dist/query.js.map +1 -1
- package/dist/resourceTypes.d.ts +39 -0
- package/dist/resourceTypes.d.ts.map +1 -0
- package/dist/resourceTypes.js +34 -0
- package/dist/resourceTypes.js.map +1 -0
- package/dist/rules.d.ts +18 -5
- package/dist/rules.d.ts.map +1 -1
- package/dist/rules.js +233 -15
- package/dist/rules.js.map +1 -1
- package/dist/runtime/index.d.ts +20 -10
- package/dist/runtime/index.d.ts.map +1 -1
- package/dist/runtime/index.js +13 -3
- package/dist/schemas/action.d.ts +118 -10
- package/dist/schemas/action.d.ts.map +1 -1
- package/dist/schemas/action.js +20 -3
- package/dist/schemas/action.js.map +1 -1
- package/dist/schemas/api.d.ts +334 -42
- package/dist/schemas/api.d.ts.map +1 -1
- package/dist/schemas/api.js +194 -34
- package/dist/schemas/api.js.map +1 -1
- package/dist/schemas/boot.d.ts +25 -1
- package/dist/schemas/boot.d.ts.map +1 -1
- package/dist/schemas/boot.js +2 -1
- package/dist/schemas/boot.js.map +1 -1
- package/dist/schemas/common.d.ts +1 -0
- package/dist/schemas/common.d.ts.map +1 -1
- package/dist/schemas/common.js +2 -1
- package/dist/schemas/common.js.map +1 -1
- package/dist/schemas/definition.d.ts +341 -28
- package/dist/schemas/definition.d.ts.map +1 -1
- package/dist/schemas/definition.js +65 -19
- package/dist/schemas/definition.js.map +1 -1
- package/dist/schemas/field.d.ts +357 -2
- package/dist/schemas/field.d.ts.map +1 -1
- package/dist/schemas/field.js +160 -20
- package/dist/schemas/field.js.map +1 -1
- package/dist/schemas/index.d.ts +1429 -80
- package/dist/schemas/index.d.ts.map +1 -1
- package/dist/schemas/index.js +60 -10
- package/dist/schemas/index.js.map +1 -1
- package/dist/schemas/jsonRules.d.ts +83 -0
- package/dist/schemas/jsonRules.d.ts.map +1 -0
- package/dist/schemas/jsonRules.js +46 -0
- package/dist/schemas/jsonRules.js.map +1 -0
- package/dist/schemas/layout.d.ts +2 -1
- package/dist/schemas/layout.d.ts.map +1 -1
- package/dist/schemas/layout.js +2 -1
- package/dist/schemas/layout.js.map +1 -1
- package/dist/schemas/list.d.ts +23 -2
- package/dist/schemas/list.d.ts.map +1 -1
- package/dist/schemas/list.js +15 -6
- package/dist/schemas/list.js.map +1 -1
- package/dist/schemas/resource.d.ts +263 -17
- package/dist/schemas/resource.d.ts.map +1 -1
- package/dist/schemas/resource.js +19 -4
- package/dist/schemas/resource.js.map +1 -1
- package/dist/schemas/theme.d.ts +4 -0
- package/dist/schemas/theme.d.ts.map +1 -1
- package/dist/schemas/theme.js +1 -0
- package/dist/schemas/theme.js.map +1 -1
- package/dist/schemas/widget.d.ts +109 -0
- package/dist/schemas/widget.d.ts.map +1 -0
- package/dist/schemas/widget.js +74 -0
- package/dist/schemas/widget.js.map +1 -0
- package/dist/search.d.ts +51 -0
- package/dist/search.d.ts.map +1 -0
- package/dist/search.js +53 -0
- package/dist/search.js.map +1 -0
- package/dist/themes.d.ts +1 -1
- package/dist/transforms.d.ts +17 -0
- package/dist/transforms.d.ts.map +1 -0
- package/dist/transforms.js +34 -0
- package/dist/transforms.js.map +1 -0
- package/dist/validate.d.ts +5 -3
- package/dist/validate.d.ts.map +1 -1
- package/dist/validate.js +36 -2
- package/dist/validate.js.map +1 -1
- package/dist/values.d.ts +5 -1
- package/dist/values.d.ts.map +1 -1
- package/dist/values.js +16 -2
- package/dist/values.js.map +1 -1
- package/dist/widgets.d.ts +42 -0
- package/dist/widgets.d.ts.map +1 -0
- package/dist/widgets.js +130 -0
- package/dist/widgets.js.map +1 -0
- package/package.json +6 -3
- package/schema/boot.schema.json +713 -20
- package/schema/definition.schema.json +710 -20
- package/schema/openapi.json +5656 -2229
package/dist/openapi.js
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
import { PROBLEM_CONTENT_TYPE } from "./version.js";
|
|
2
|
+
import { AUTH_PAGE_PATHS, CONTEXT_HEADER, CONTEXT_PROBLEM_TYPE, EMAIL_UNVERIFIED_PROBLEM_TYPE, PASSWORD_CONFIRMATION_PROBLEM_TYPE, TWO_FACTOR_REQUIRED_PROBLEM_TYPE } from "./constants.js";
|
|
3
|
+
import "./search.js";
|
|
2
4
|
import { Theme } from "./schemas/theme.js";
|
|
3
5
|
import { Definition } from "./schemas/definition.js";
|
|
4
6
|
import { BootConfig } from "./schemas/boot.js";
|
|
@@ -15,11 +17,14 @@ var ok = (description, schema, headers) => ({
|
|
|
15
17
|
var PROBLEMS = {
|
|
16
18
|
400: "Bad request, such as a dry run of an action that does not declare `dryRun`.",
|
|
17
19
|
401: "Not authenticated.",
|
|
18
|
-
403:
|
|
20
|
+
403: `Not allowed. A value of \`${CONTEXT_HEADER}\` that the user can't use is a problem of type \`${CONTEXT_PROBLEM_TYPE}\`, with its \`param\`. With \`auth.emailVerification\`, a user whose email address isn't verified gets a problem of type \`${EMAIL_UNVERIFIED_PROBLEM_TYPE}\` on every operation but those of the auth. A user who must have two-factor authentication and hasn't set it up gets a problem of type \`${TWO_FACTOR_REQUIRED_PROBLEM_TYPE}\` on every operation but those of the auth and of \`/account/two-factor\`.`,
|
|
19
21
|
404: "Not found.",
|
|
20
22
|
409: "Conflict with a business rule.",
|
|
21
23
|
412: "Version conflict: `If-Match` does not match the current version, which is in `current`.",
|
|
22
|
-
422: "Invalid values: messages are in `errors`, keyed by dot path."
|
|
24
|
+
422: "Invalid values: messages are in `errors`, keyed by dot path.",
|
|
25
|
+
423: `The password must be confirmed first (\`POST /auth/password/confirm\`): a problem of type \`${PASSWORD_CONFIRMATION_PROBLEM_TYPE}\`.`,
|
|
26
|
+
429: "Too many requests: `Retry-After` gives the seconds to wait.",
|
|
27
|
+
500: "Server error, such as a widget whose data does not have the shape of its type."
|
|
23
28
|
};
|
|
24
29
|
function problems(...statuses) {
|
|
25
30
|
return Object.fromEntries(statuses.map((status) => [String(status), {
|
|
@@ -54,6 +59,7 @@ var listParameters = [
|
|
|
54
59
|
type: "integer",
|
|
55
60
|
minimum: 1
|
|
56
61
|
}),
|
|
62
|
+
queryParameter("cursor", "Lists whose `pagination` is `cursor`: the `nextCursor` (or `previousCursor`) of a page, instead of `page`.", { type: "string" }),
|
|
57
63
|
queryParameter("sort", "Comma-separated fields; a `-` prefix sorts descending.", { type: "string" }),
|
|
58
64
|
{
|
|
59
65
|
name: "filter",
|
|
@@ -117,6 +123,42 @@ function createBootConfigJsonSchema() {
|
|
|
117
123
|
})
|
|
118
124
|
};
|
|
119
125
|
}
|
|
126
|
+
/** The `Panneau-Context` header, which every operation takes (decision 0045). */
|
|
127
|
+
var contextHeader = {
|
|
128
|
+
name: CONTEXT_HEADER,
|
|
129
|
+
in: "header",
|
|
130
|
+
required: false,
|
|
131
|
+
description: "The values of the current context, when the definition has `context`: the format of a query string, in the order of its params (`client=4&contest=12`). Responses vary with it.",
|
|
132
|
+
schema: { type: "string" }
|
|
133
|
+
};
|
|
134
|
+
var METHODS = [
|
|
135
|
+
"get",
|
|
136
|
+
"post",
|
|
137
|
+
"put",
|
|
138
|
+
"patch",
|
|
139
|
+
"delete"
|
|
140
|
+
];
|
|
141
|
+
/**
|
|
142
|
+
* Adds the `Panneau-Context` header to the parameters of every path, and its `403` problem to
|
|
143
|
+
* every operation that doesn't have one: a value the user can't use is refused everywhere.
|
|
144
|
+
*/
|
|
145
|
+
function withContextHeader(paths) {
|
|
146
|
+
const parameter = { $ref: "#/components/parameters/Context" };
|
|
147
|
+
return Object.fromEntries(Object.entries(paths).map(([path, item]) => [path, {
|
|
148
|
+
...Object.fromEntries(Object.entries(item).map(([key, operation]) => {
|
|
149
|
+
if (!METHODS.includes(key)) return [key, operation];
|
|
150
|
+
const { responses = {}, ...rest } = operation;
|
|
151
|
+
return [key, {
|
|
152
|
+
...rest,
|
|
153
|
+
responses: {
|
|
154
|
+
...problems(403),
|
|
155
|
+
...responses
|
|
156
|
+
}
|
|
157
|
+
}];
|
|
158
|
+
})),
|
|
159
|
+
parameters: [...item.parameters ?? [], parameter]
|
|
160
|
+
}]));
|
|
161
|
+
}
|
|
120
162
|
/** The OpenAPI 3.1 document of the Panneau HTTP API. */
|
|
121
163
|
function createOpenApiDocument() {
|
|
122
164
|
return {
|
|
@@ -126,15 +168,27 @@ function createOpenApiDocument() {
|
|
|
126
168
|
version: String(1),
|
|
127
169
|
description: "The HTTP API between a Panneau frontend and its backend. Paths are relative to `api.baseUrl` of the definition. Authentication is up to the backend (session cookie or bearer token). Errors use `application/problem+json`."
|
|
128
170
|
},
|
|
129
|
-
paths: {
|
|
171
|
+
paths: withContextHeader({
|
|
130
172
|
"/definition": { get: {
|
|
131
173
|
operationId: "getDefinition",
|
|
132
|
-
summary: "The definition for the current user, in the current locale
|
|
174
|
+
summary: "The definition for the current user, in the current locale, and for the values of `Panneau-Context`.",
|
|
133
175
|
responses: {
|
|
134
176
|
200: ok("The definition.", ref("Definition")),
|
|
135
177
|
...problems(401, 403)
|
|
136
178
|
}
|
|
137
179
|
} },
|
|
180
|
+
"/context/{param}/options": {
|
|
181
|
+
parameters: [pathParameter("param", "The name of a param of the context.")],
|
|
182
|
+
get: {
|
|
183
|
+
operationId: "getContextOptions",
|
|
184
|
+
summary: "The choices of a param of the context without inline `options`, for the values of the params before it in `Panneau-Context`.",
|
|
185
|
+
parameters: [queryParameter("q", "Search terms.", { type: "string" })],
|
|
186
|
+
responses: {
|
|
187
|
+
200: ok("The first choices that match `q`, in the order to show them.", ref("ContextOptionsResponse")),
|
|
188
|
+
...problems(401, 403, 404)
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
},
|
|
138
192
|
"/resources/{resource}": {
|
|
139
193
|
parameters: [resource],
|
|
140
194
|
get: {
|
|
@@ -142,7 +196,7 @@ function createOpenApiDocument() {
|
|
|
142
196
|
parameters: listParameters,
|
|
143
197
|
responses: {
|
|
144
198
|
200: ok("A page of items.", ref("ListResponse")),
|
|
145
|
-
...problems(401, 403, 404)
|
|
199
|
+
...problems(401, 403, 404, 422)
|
|
146
200
|
}
|
|
147
201
|
},
|
|
148
202
|
post: {
|
|
@@ -193,6 +247,21 @@ function createOpenApiDocument() {
|
|
|
193
247
|
}
|
|
194
248
|
}
|
|
195
249
|
},
|
|
250
|
+
"/resources/{resource}/{id}/duplicate": {
|
|
251
|
+
parameters: [resource, id],
|
|
252
|
+
post: {
|
|
253
|
+
operationId: "duplicateItem",
|
|
254
|
+
description: "Copies an item, for the built-in `duplicate` (decision 0040). Allowed on the items whose `abilities.duplicate` is `true`.",
|
|
255
|
+
responses: {
|
|
256
|
+
201: ok("The copy, a new item.", ref("ItemResponse"), etag),
|
|
257
|
+
...problems(401, 403, 404),
|
|
258
|
+
409: {
|
|
259
|
+
description: "The copy conflicts with another item, such as a unique value.",
|
|
260
|
+
content: { [PROBLEM_CONTENT_TYPE]: { schema: ref("Problem") } }
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
},
|
|
196
265
|
"/resources/{resource}/{id}/preview": {
|
|
197
266
|
parameters: [resource, id],
|
|
198
267
|
post: {
|
|
@@ -225,6 +294,21 @@ function createOpenApiDocument() {
|
|
|
225
294
|
}
|
|
226
295
|
}
|
|
227
296
|
},
|
|
297
|
+
"/resources/{resource}/fields/{field}/check": {
|
|
298
|
+
parameters: [resource, pathParameter("field", "Name of a field with `check`.")],
|
|
299
|
+
post: {
|
|
300
|
+
operationId: "checkField",
|
|
301
|
+
summary: "Checks a value as it is typed: whether a slug is available, and its URL. With the permission to create, or to update the item `id`.",
|
|
302
|
+
requestBody: {
|
|
303
|
+
required: true,
|
|
304
|
+
content: json(ref("FieldCheckRequest"))
|
|
305
|
+
},
|
|
306
|
+
responses: {
|
|
307
|
+
200: ok("What the backend says about the value.", ref("FieldCheckResponse")),
|
|
308
|
+
...problems(401, 403, 404, 422)
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
},
|
|
228
312
|
"/actions/runs": { get: {
|
|
229
313
|
operationId: "listActionRuns",
|
|
230
314
|
summary: "The current user's recent runs.",
|
|
@@ -257,115 +341,39 @@ function createOpenApiDocument() {
|
|
|
257
341
|
}
|
|
258
342
|
}
|
|
259
343
|
},
|
|
260
|
-
"/
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
...problems(401, 403)
|
|
267
|
-
}
|
|
344
|
+
"/uploads/sign": { post: {
|
|
345
|
+
operationId: "signUpload",
|
|
346
|
+
summary: "Signs a request of the browser's S3 client. The first request of a file creates its upload.",
|
|
347
|
+
requestBody: {
|
|
348
|
+
required: true,
|
|
349
|
+
content: json(ref("UploadSignRequest"))
|
|
268
350
|
},
|
|
269
|
-
post: {
|
|
270
|
-
operationId: "uploadMedia",
|
|
271
|
-
requestBody: {
|
|
272
|
-
required: true,
|
|
273
|
-
content: { "multipart/form-data": { schema: {
|
|
274
|
-
type: "object",
|
|
275
|
-
required: ["file"],
|
|
276
|
-
properties: {
|
|
277
|
-
file: {
|
|
278
|
-
type: "string",
|
|
279
|
-
contentMediaType: "application/octet-stream"
|
|
280
|
-
},
|
|
281
|
-
name: { type: "string" },
|
|
282
|
-
tags: {
|
|
283
|
-
type: "array",
|
|
284
|
-
items: { type: "string" }
|
|
285
|
-
}
|
|
286
|
-
}
|
|
287
|
-
} } }
|
|
288
|
-
},
|
|
289
|
-
responses: {
|
|
290
|
-
201: ok("The created media.", ref("MediaResponse")),
|
|
291
|
-
...problems(401, 403, 422)
|
|
292
|
-
}
|
|
293
|
-
}
|
|
294
|
-
},
|
|
295
|
-
"/media/tags": { get: {
|
|
296
|
-
operationId: "listMediaTags",
|
|
297
351
|
responses: {
|
|
298
|
-
200: ok("
|
|
299
|
-
|
|
300
|
-
required: ["data"],
|
|
301
|
-
properties: { data: {
|
|
302
|
-
type: "array",
|
|
303
|
-
items: { type: "string" }
|
|
304
|
-
} }
|
|
305
|
-
}),
|
|
306
|
-
...problems(401, 403)
|
|
352
|
+
200: ok("The presigned request.", ref("UploadSignResponse")),
|
|
353
|
+
...problems(401, 403, 404, 422)
|
|
307
354
|
}
|
|
308
355
|
} },
|
|
309
|
-
"/
|
|
310
|
-
parameters: [pathParameter("
|
|
311
|
-
get: {
|
|
312
|
-
operationId: "getMedia",
|
|
313
|
-
responses: {
|
|
314
|
-
200: ok("The media.", ref("MediaResponse")),
|
|
315
|
-
...problems(401, 403, 404)
|
|
316
|
-
}
|
|
317
|
-
},
|
|
318
|
-
patch: {
|
|
319
|
-
operationId: "updateMedia",
|
|
320
|
-
description: "Updates metadata, tags or the image `transform`.",
|
|
321
|
-
requestBody: {
|
|
322
|
-
required: true,
|
|
323
|
-
content: json(values)
|
|
324
|
-
},
|
|
325
|
-
responses: {
|
|
326
|
-
200: ok("The updated media.", ref("MediaResponse")),
|
|
327
|
-
...problems(401, 403, 404, 422)
|
|
328
|
-
}
|
|
329
|
-
},
|
|
330
|
-
delete: {
|
|
331
|
-
operationId: "deleteMedia",
|
|
332
|
-
responses: {
|
|
333
|
-
204: ok("Moved to the trash."),
|
|
334
|
-
...problems(401, 403, 404, 409)
|
|
335
|
-
}
|
|
336
|
-
}
|
|
337
|
-
},
|
|
338
|
-
"/media/{id}/file": {
|
|
339
|
-
parameters: [pathParameter("id", "Media id.")],
|
|
356
|
+
"/uploads/{upload}/complete": {
|
|
357
|
+
parameters: [pathParameter("upload", "Upload id: `upl_…`.")],
|
|
340
358
|
post: {
|
|
341
|
-
operationId: "
|
|
359
|
+
operationId: "completeUpload",
|
|
360
|
+
summary: "Once the browser completed the upload in storage, checks the object and gives the upload, which values reference.",
|
|
342
361
|
requestBody: {
|
|
343
|
-
required:
|
|
344
|
-
content: {
|
|
362
|
+
required: false,
|
|
363
|
+
content: json({
|
|
345
364
|
type: "object",
|
|
346
|
-
|
|
347
|
-
properties: { file: {
|
|
365
|
+
properties: { name: {
|
|
348
366
|
type: "string",
|
|
349
|
-
|
|
367
|
+
description: "The file's name, which the key doesn't keep, since the backend chose it."
|
|
350
368
|
} }
|
|
351
|
-
}
|
|
369
|
+
})
|
|
352
370
|
},
|
|
353
371
|
responses: {
|
|
354
|
-
200: ok("The
|
|
372
|
+
200: ok("The upload.", ref("UploadResponse")),
|
|
355
373
|
...problems(401, 403, 404, 422)
|
|
356
374
|
}
|
|
357
375
|
}
|
|
358
376
|
},
|
|
359
|
-
"/media/{id}/restore": {
|
|
360
|
-
parameters: [pathParameter("id", "Media id.")],
|
|
361
|
-
post: {
|
|
362
|
-
operationId: "restoreMedia",
|
|
363
|
-
responses: {
|
|
364
|
-
200: ok("The restored media.", ref("MediaResponse")),
|
|
365
|
-
...problems(401, 403, 404)
|
|
366
|
-
}
|
|
367
|
-
}
|
|
368
|
-
},
|
|
369
377
|
"/auth/session": { get: {
|
|
370
378
|
operationId: "getSession",
|
|
371
379
|
responses: {
|
|
@@ -378,44 +386,62 @@ function createOpenApiDocument() {
|
|
|
378
386
|
requestBody: {
|
|
379
387
|
required: true,
|
|
380
388
|
content: json({
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
389
|
+
description: "An email and a password, or the single secret of `auth.token`.",
|
|
390
|
+
oneOf: [{
|
|
391
|
+
type: "object",
|
|
392
|
+
required: ["email", "password"],
|
|
393
|
+
properties: {
|
|
394
|
+
email: { type: "string" },
|
|
395
|
+
password: { type: "string" },
|
|
396
|
+
remember: { type: "boolean" }
|
|
397
|
+
}
|
|
398
|
+
}, {
|
|
399
|
+
type: "object",
|
|
400
|
+
required: ["token"],
|
|
401
|
+
properties: {
|
|
402
|
+
token: { type: "string" },
|
|
403
|
+
remember: { type: "boolean" }
|
|
404
|
+
}
|
|
405
|
+
}]
|
|
388
406
|
})
|
|
389
407
|
},
|
|
390
408
|
responses: {
|
|
391
409
|
200: ok("Logged in.", ref("Session")),
|
|
392
|
-
202: ok("A second factor is required: answer `/auth/two-factor/challenge`.",
|
|
393
|
-
|
|
394
|
-
properties: { twoFactor: {
|
|
395
|
-
type: "boolean",
|
|
396
|
-
const: true
|
|
397
|
-
} }
|
|
398
|
-
}),
|
|
399
|
-
...problems(422)
|
|
410
|
+
202: ok("A second factor is required: answer `/auth/two-factor/challenge`.", ref("TwoFactorChallenge")),
|
|
411
|
+
...problems(422, 429)
|
|
400
412
|
}
|
|
401
413
|
} },
|
|
402
414
|
"/auth/logout": { post: {
|
|
403
415
|
operationId: "logout",
|
|
416
|
+
description: "`panneau` auth mode. In `external` mode, the browser goes to `auth.logoutUrl` instead.",
|
|
404
417
|
responses: { 204: ok("Logged out.") }
|
|
405
418
|
} },
|
|
406
419
|
"/auth/providers/{provider}/redirect": {
|
|
407
420
|
parameters: [pathParameter("provider", "Provider id.")],
|
|
408
421
|
get: {
|
|
409
422
|
operationId: "redirectToProvider",
|
|
410
|
-
|
|
423
|
+
summary: "Starts the login with an OAuth provider of `auth.providers`. The callback is the backend's: it goes to `next`, or to the base path of the app with `authError` when it fails.",
|
|
424
|
+
parameters: [queryParameter("next", "Where to go after the login: a local path under the base path of the app. Another one is ignored.", { type: "string" })],
|
|
411
425
|
responses: {
|
|
412
426
|
302: { description: "Redirect to the provider." },
|
|
413
427
|
...problems(404)
|
|
414
428
|
}
|
|
415
429
|
}
|
|
416
430
|
},
|
|
431
|
+
"/auth/providers/{provider}/callback": {
|
|
432
|
+
parameters: [pathParameter("provider", "Provider id.")],
|
|
433
|
+
get: {
|
|
434
|
+
operationId: "providerCallback",
|
|
435
|
+
summary: "Optional: the callback of the provider, when the backend has it here. Its URL is the backend's, registered with the provider; the app never calls it.",
|
|
436
|
+
responses: {
|
|
437
|
+
302: { description: "To `next`, or to the base path of the app with `authError` when the login failed." },
|
|
438
|
+
...problems(404)
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
},
|
|
417
442
|
"/auth/password/forgot": { post: {
|
|
418
443
|
operationId: "forgotPassword",
|
|
444
|
+
summary: `With \`auth.passwordReset\`: emails a link to the page of the app at \`{basePath}/${AUTH_PAGE_PATHS.resetPassword}?token=…&email=…\`.`,
|
|
419
445
|
requestBody: {
|
|
420
446
|
required: true,
|
|
421
447
|
content: json({
|
|
@@ -425,12 +451,13 @@ function createOpenApiDocument() {
|
|
|
425
451
|
})
|
|
426
452
|
},
|
|
427
453
|
responses: {
|
|
428
|
-
204: ok("A reset link was sent, if the account
|
|
429
|
-
...problems(422)
|
|
454
|
+
204: ok("A reset link was sent, if the address has an account. The answer is the same when it hasn't, or when a link was sent recently."),
|
|
455
|
+
...problems(422, 429)
|
|
430
456
|
}
|
|
431
457
|
} },
|
|
432
458
|
"/auth/password/reset": { post: {
|
|
433
459
|
operationId: "resetPassword",
|
|
460
|
+
summary: "With `auth.passwordReset`: sets a new password, with the token and the email of the link. It does not log in.",
|
|
434
461
|
requestBody: {
|
|
435
462
|
required: true,
|
|
436
463
|
content: json({
|
|
@@ -449,64 +476,233 @@ function createOpenApiDocument() {
|
|
|
449
476
|
},
|
|
450
477
|
responses: {
|
|
451
478
|
204: ok("The password was reset."),
|
|
452
|
-
...problems(422)
|
|
479
|
+
...problems(422, 429)
|
|
480
|
+
}
|
|
481
|
+
} },
|
|
482
|
+
"/auth/email/verification": { post: {
|
|
483
|
+
operationId: "sendEmailVerification",
|
|
484
|
+
summary: `With \`auth.emailVerification\`: emails the current user a link to the page of the app at \`{basePath}/${AUTH_PAGE_PATHS.verifyEmail}?token=…\`.`,
|
|
485
|
+
responses: {
|
|
486
|
+
204: ok("A link was sent, or the address is already verified."),
|
|
487
|
+
...problems(401, 429)
|
|
488
|
+
}
|
|
489
|
+
} },
|
|
490
|
+
"/auth/email/verify": { post: {
|
|
491
|
+
operationId: "verifyEmail",
|
|
492
|
+
summary: "With `auth.emailVerification`: verifies the address of the token of a link. The user does not need to be logged in.",
|
|
493
|
+
requestBody: {
|
|
494
|
+
required: true,
|
|
495
|
+
content: json({
|
|
496
|
+
type: "object",
|
|
497
|
+
required: ["token"],
|
|
498
|
+
properties: { token: { type: "string" } }
|
|
499
|
+
})
|
|
500
|
+
},
|
|
501
|
+
responses: {
|
|
502
|
+
204: ok("The address is verified."),
|
|
503
|
+
...problems(422, 429)
|
|
453
504
|
}
|
|
454
505
|
} },
|
|
455
506
|
"/auth/two-factor/challenge": { post: {
|
|
456
507
|
operationId: "twoFactorChallenge",
|
|
508
|
+
summary: "Ends a login that answered `202`, with a code of the authenticator app or a recovery code. A login that is no longer pending is a `422`.",
|
|
509
|
+
requestBody: {
|
|
510
|
+
required: true,
|
|
511
|
+
content: json({ oneOf: [{
|
|
512
|
+
type: "object",
|
|
513
|
+
required: ["code"],
|
|
514
|
+
properties: { code: { type: "string" } }
|
|
515
|
+
}, {
|
|
516
|
+
type: "object",
|
|
517
|
+
required: ["recoveryCode"],
|
|
518
|
+
properties: { recoveryCode: { type: "string" } }
|
|
519
|
+
}] })
|
|
520
|
+
},
|
|
521
|
+
responses: {
|
|
522
|
+
200: ok("Logged in.", ref("Session")),
|
|
523
|
+
...problems(422, 429)
|
|
524
|
+
}
|
|
525
|
+
} },
|
|
526
|
+
"/auth/password/confirm": { post: {
|
|
527
|
+
operationId: "confirmPassword",
|
|
528
|
+
summary: "Confirms the password of the current user, for the operations that answer `423`.",
|
|
457
529
|
requestBody: {
|
|
458
530
|
required: true,
|
|
459
531
|
content: json({
|
|
460
532
|
type: "object",
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
recoveryCode: { type: "string" }
|
|
464
|
-
}
|
|
533
|
+
required: ["password"],
|
|
534
|
+
properties: { password: { type: "string" } }
|
|
465
535
|
})
|
|
466
536
|
},
|
|
467
537
|
responses: {
|
|
468
|
-
|
|
469
|
-
...problems(422)
|
|
538
|
+
204: ok("The password is confirmed."),
|
|
539
|
+
...problems(401, 422, 429)
|
|
540
|
+
}
|
|
541
|
+
} },
|
|
542
|
+
"/account/two-factor": {
|
|
543
|
+
get: {
|
|
544
|
+
operationId: "getTwoFactor",
|
|
545
|
+
summary: "With `auth.twoFactor`: the two-factor authentication of the user.",
|
|
546
|
+
responses: {
|
|
547
|
+
200: ok("Its status.", ref("TwoFactorStatus")),
|
|
548
|
+
...problems(401, 403)
|
|
549
|
+
}
|
|
550
|
+
},
|
|
551
|
+
post: {
|
|
552
|
+
operationId: "enableTwoFactor",
|
|
553
|
+
summary: "Starts setting it up: a new secret, `pending` until `POST /account/two-factor/confirm`.",
|
|
554
|
+
responses: {
|
|
555
|
+
200: ok("The secret to add to an authenticator app.", ref("TwoFactorSetup")),
|
|
556
|
+
...problems(401, 403, 409, 423)
|
|
557
|
+
}
|
|
558
|
+
},
|
|
559
|
+
delete: {
|
|
560
|
+
operationId: "disableTwoFactor",
|
|
561
|
+
summary: "Turns it off. A `409` when the backend requires it for the user.",
|
|
562
|
+
responses: {
|
|
563
|
+
204: ok("Turned off."),
|
|
564
|
+
...problems(401, 403, 409, 423)
|
|
565
|
+
}
|
|
566
|
+
}
|
|
567
|
+
},
|
|
568
|
+
"/account/two-factor/confirm": { post: {
|
|
569
|
+
operationId: "confirmTwoFactor",
|
|
570
|
+
requestBody: {
|
|
571
|
+
required: true,
|
|
572
|
+
content: json({
|
|
573
|
+
type: "object",
|
|
574
|
+
required: ["code"],
|
|
575
|
+
properties: { code: { type: "string" } }
|
|
576
|
+
})
|
|
577
|
+
},
|
|
578
|
+
responses: {
|
|
579
|
+
200: ok("Turned on, with its recovery codes.", ref("RecoveryCodes")),
|
|
580
|
+
...problems(401, 403, 409, 422, 423)
|
|
581
|
+
}
|
|
582
|
+
} },
|
|
583
|
+
"/account/two-factor/recovery-codes": { post: {
|
|
584
|
+
operationId: "regenerateRecoveryCodes",
|
|
585
|
+
summary: "New recovery codes, in place of the old ones.",
|
|
586
|
+
responses: {
|
|
587
|
+
200: ok("The new codes.", ref("RecoveryCodes")),
|
|
588
|
+
...problems(401, 403, 409, 423)
|
|
470
589
|
}
|
|
471
590
|
} },
|
|
472
591
|
"/auth/passkeys/options": { post: {
|
|
473
|
-
operationId: "
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
592
|
+
operationId: "passkeyLoginOptions",
|
|
593
|
+
summary: "With `auth.passkeys`: the options of `navigator.credentials.get()`, for any passkey of the site.",
|
|
594
|
+
responses: {
|
|
595
|
+
200: ok("The options.", ref("WebAuthnOptions")),
|
|
596
|
+
...problems(429)
|
|
597
|
+
}
|
|
478
598
|
} },
|
|
479
599
|
"/auth/passkeys/login": { post: {
|
|
480
600
|
operationId: "passkeyLogin",
|
|
601
|
+
summary: "Logs in with the credential of a passkey, in the JSON form of the WebAuthn spec. It does not ask for a second factor.",
|
|
481
602
|
requestBody: {
|
|
482
603
|
required: true,
|
|
483
604
|
content: json({
|
|
484
605
|
type: "object",
|
|
485
|
-
|
|
606
|
+
required: ["credential"],
|
|
607
|
+
properties: {
|
|
608
|
+
credential: {
|
|
609
|
+
type: "object",
|
|
610
|
+
additionalProperties: true
|
|
611
|
+
},
|
|
612
|
+
remember: { type: "boolean" }
|
|
613
|
+
}
|
|
486
614
|
})
|
|
487
615
|
},
|
|
488
616
|
responses: {
|
|
489
617
|
200: ok("Logged in.", ref("Session")),
|
|
490
|
-
...problems(422)
|
|
618
|
+
...problems(422, 429)
|
|
619
|
+
}
|
|
620
|
+
} },
|
|
621
|
+
"/account/passkeys": {
|
|
622
|
+
get: {
|
|
623
|
+
operationId: "listPasskeys",
|
|
624
|
+
responses: {
|
|
625
|
+
200: ok("The passkeys of the current user.", {
|
|
626
|
+
type: "object",
|
|
627
|
+
required: ["data"],
|
|
628
|
+
properties: { data: {
|
|
629
|
+
type: "array",
|
|
630
|
+
items: ref("Passkey")
|
|
631
|
+
} }
|
|
632
|
+
}),
|
|
633
|
+
...problems(401, 403)
|
|
634
|
+
}
|
|
635
|
+
},
|
|
636
|
+
post: {
|
|
637
|
+
operationId: "addPasskey",
|
|
638
|
+
summary: "Adds a passkey, with the credential of `navigator.credentials.create()` for the options of `POST /account/passkeys/options`.",
|
|
639
|
+
requestBody: {
|
|
640
|
+
required: true,
|
|
641
|
+
content: json({
|
|
642
|
+
type: "object",
|
|
643
|
+
required: ["name", "credential"],
|
|
644
|
+
properties: {
|
|
645
|
+
name: { type: "string" },
|
|
646
|
+
credential: {
|
|
647
|
+
type: "object",
|
|
648
|
+
additionalProperties: true
|
|
649
|
+
}
|
|
650
|
+
}
|
|
651
|
+
})
|
|
652
|
+
},
|
|
653
|
+
responses: {
|
|
654
|
+
201: ok("The passkey.", {
|
|
655
|
+
type: "object",
|
|
656
|
+
required: ["data"],
|
|
657
|
+
properties: { data: ref("Passkey") }
|
|
658
|
+
}),
|
|
659
|
+
...problems(401, 403, 409, 422, 423)
|
|
660
|
+
}
|
|
661
|
+
}
|
|
662
|
+
},
|
|
663
|
+
"/account/passkeys/options": { post: {
|
|
664
|
+
operationId: "passkeyRegistrationOptions",
|
|
665
|
+
summary: "The options of `navigator.credentials.create()`, for the current user. A `409` for a user who can't have passkeys.",
|
|
666
|
+
responses: {
|
|
667
|
+
200: ok("The options.", ref("WebAuthnOptions")),
|
|
668
|
+
...problems(401, 403, 409, 423)
|
|
491
669
|
}
|
|
492
670
|
} },
|
|
671
|
+
"/account/passkeys/{passkey}": {
|
|
672
|
+
parameters: [pathParameter("passkey", "The id of the passkey.")],
|
|
673
|
+
delete: {
|
|
674
|
+
operationId: "deletePasskey",
|
|
675
|
+
responses: {
|
|
676
|
+
204: ok("Removed."),
|
|
677
|
+
...problems(401, 403, 404, 423)
|
|
678
|
+
}
|
|
679
|
+
}
|
|
680
|
+
},
|
|
493
681
|
"/account": {
|
|
494
682
|
get: {
|
|
495
683
|
operationId: "getAccount",
|
|
684
|
+
summary: "With `auth.account`: the current user.",
|
|
496
685
|
responses: {
|
|
497
686
|
200: ok("The current user.", {
|
|
498
687
|
type: "object",
|
|
499
688
|
required: ["data"],
|
|
500
689
|
properties: { data: ref("User") }
|
|
501
690
|
}),
|
|
502
|
-
...problems(401)
|
|
691
|
+
...problems(401, 403)
|
|
503
692
|
}
|
|
504
693
|
},
|
|
505
694
|
patch: {
|
|
506
695
|
operationId: "updateAccount",
|
|
696
|
+
summary: "Saves the name and the email of the current user. With `auth.emailVerification`, a new email is unverified, and gets a link.",
|
|
507
697
|
requestBody: {
|
|
508
698
|
required: true,
|
|
509
|
-
content: json(
|
|
699
|
+
content: json({
|
|
700
|
+
type: "object",
|
|
701
|
+
properties: {
|
|
702
|
+
name: { type: "string" },
|
|
703
|
+
email: { type: "string" }
|
|
704
|
+
}
|
|
705
|
+
})
|
|
510
706
|
},
|
|
511
707
|
responses: {
|
|
512
708
|
200: ok("The updated user.", {
|
|
@@ -514,36 +710,88 @@ function createOpenApiDocument() {
|
|
|
514
710
|
required: ["data"],
|
|
515
711
|
properties: { data: ref("User") }
|
|
516
712
|
}),
|
|
517
|
-
...problems(401, 422)
|
|
713
|
+
...problems(401, 403, 422)
|
|
518
714
|
}
|
|
519
715
|
}
|
|
520
716
|
},
|
|
717
|
+
"/account/password": { put: {
|
|
718
|
+
operationId: "updatePassword",
|
|
719
|
+
summary: "Changes the password of the current user, with the current one.",
|
|
720
|
+
requestBody: {
|
|
721
|
+
required: true,
|
|
722
|
+
content: json({
|
|
723
|
+
type: "object",
|
|
724
|
+
required: ["currentPassword", "password"],
|
|
725
|
+
properties: {
|
|
726
|
+
currentPassword: { type: "string" },
|
|
727
|
+
password: { type: "string" }
|
|
728
|
+
}
|
|
729
|
+
})
|
|
730
|
+
},
|
|
731
|
+
responses: {
|
|
732
|
+
204: ok("The password was changed."),
|
|
733
|
+
...problems(401, 403, 422, 429)
|
|
734
|
+
}
|
|
735
|
+
} },
|
|
521
736
|
"/search": { get: {
|
|
522
737
|
operationId: "search",
|
|
738
|
+
parameters: [
|
|
739
|
+
{
|
|
740
|
+
...queryParameter("q", "Search terms, trimmed.", {
|
|
741
|
+
type: "string",
|
|
742
|
+
minLength: 2,
|
|
743
|
+
maxLength: 255
|
|
744
|
+
}),
|
|
745
|
+
required: true
|
|
746
|
+
},
|
|
747
|
+
queryParameter("limit", "Items per resource.", {
|
|
748
|
+
type: "integer",
|
|
749
|
+
minimum: 1,
|
|
750
|
+
maximum: 20,
|
|
751
|
+
default: 5
|
|
752
|
+
}),
|
|
753
|
+
queryParameter("resources", "Comma-separated ids of the searchable resources to search. Defaults to every one.", { type: "string" })
|
|
754
|
+
],
|
|
755
|
+
responses: {
|
|
756
|
+
200: ok(`Results grouped by resource, in the order of the definition: at most \`limit\` items per resource, and 20 in all.`, ref("SearchResponse")),
|
|
757
|
+
...problems(401, 422, 429)
|
|
758
|
+
}
|
|
759
|
+
} },
|
|
760
|
+
"/embeds": { get: {
|
|
761
|
+
operationId: "resolveEmbed",
|
|
523
762
|
parameters: [{
|
|
524
|
-
...queryParameter("
|
|
763
|
+
...queryParameter("url", "The URL to embed.", { type: "string" }),
|
|
525
764
|
required: true
|
|
526
765
|
}],
|
|
527
766
|
responses: {
|
|
528
|
-
200: ok("
|
|
529
|
-
...problems(401)
|
|
767
|
+
200: ok("The value of an `embed` field for the URL, from its provider's oEmbed.", ref("EmbedResponse")),
|
|
768
|
+
...problems(401, 422, 429)
|
|
530
769
|
}
|
|
531
770
|
} },
|
|
532
771
|
"/dashboard/widgets/{widget}": {
|
|
533
772
|
parameters: [pathParameter("widget", "Widget id.")],
|
|
534
773
|
get: {
|
|
535
774
|
operationId: "getWidgetData",
|
|
775
|
+
description: "The data of a widget of the dashboard of the user, read as the user (decision 0064). The built-in `stat` and `list` on a resource (`settings.resource`) have none: clients read the list of the resource. A widget that is not in the dashboard of the user is a `404`; a `403` hides the widget.",
|
|
536
776
|
responses: {
|
|
537
|
-
200: ok("The widget's data
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
777
|
+
200: ok("The widget's data, in the shape of its type: `StatWidgetData`, `SeriesWidgetData` and `ListWidgetData` for the built-in types, the plugin's own object for others.", { anyOf: [
|
|
778
|
+
ref("StatWidgetData"),
|
|
779
|
+
ref("SeriesWidgetData"),
|
|
780
|
+
ref("ListWidgetData"),
|
|
781
|
+
{
|
|
782
|
+
type: "object",
|
|
783
|
+
additionalProperties: true
|
|
784
|
+
}
|
|
785
|
+
] }),
|
|
786
|
+
...problems(401, 403, 404, 500)
|
|
542
787
|
}
|
|
543
788
|
}
|
|
544
789
|
}
|
|
545
|
-
},
|
|
546
|
-
components: {
|
|
790
|
+
}),
|
|
791
|
+
components: {
|
|
792
|
+
schemas: createComponentSchemas(),
|
|
793
|
+
parameters: { Context: contextHeader }
|
|
794
|
+
}
|
|
547
795
|
};
|
|
548
796
|
}
|
|
549
797
|
//#endregion
|