@panneau/protocol 5.0.0-alpha.2 → 5.0.0-alpha.20
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 +787 -11
- package/dist/conformance/index.js.map +1 -1
- package/dist/constants.d.ts +101 -2
- package/dist/constants.d.ts.map +1 -1
- package/dist/constants.js +174 -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 +17 -7
- package/dist/libraries.d.ts +26 -0
- package/dist/libraries.d.ts.map +1 -0
- package/dist/libraries.js +22 -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 +114 -2
- 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 +223 -142
- package/dist/mock/example.js.map +1 -1
- package/dist/mock/index.d.ts +77 -7
- package/dist/mock/index.d.ts.map +1 -1
- package/dist/mock/index.js +577 -34
- package/dist/mock/index.js.map +1 -1
- package/dist/openapi.d.ts.map +1 -1
- package/dist/openapi.js +394 -145
- 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/rules.d.ts +16 -4
- package/dist/rules.d.ts.map +1 -1
- package/dist/rules.js +230 -13
- package/dist/rules.js.map +1 -1
- package/dist/runtime/index.d.ts +19 -10
- package/dist/runtime/index.d.ts.map +1 -1
- package/dist/runtime/index.js +12 -3
- package/dist/schemas/action.d.ts +117 -10
- package/dist/schemas/action.d.ts.map +1 -1
- package/dist/schemas/action.js +21 -3
- package/dist/schemas/action.js.map +1 -1
- package/dist/schemas/api.d.ts +326 -42
- package/dist/schemas/api.d.ts.map +1 -1
- package/dist/schemas/api.js +192 -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 +332 -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 +356 -2
- package/dist/schemas/field.d.ts.map +1 -1
- package/dist/schemas/field.js +159 -20
- package/dist/schemas/field.js.map +1 -1
- package/dist/schemas/index.d.ts +1384 -72
- package/dist/schemas/index.d.ts.map +1 -1
- package/dist/schemas/index.js +58 -9
- 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 +1 -1
- package/dist/schemas/list.d.ts +23 -2
- package/dist/schemas/list.d.ts.map +1 -1
- package/dist/schemas/list.js +14 -5
- package/dist/schemas/list.js.map +1 -1
- package/dist/schemas/resource.d.ts +247 -15
- package/dist/schemas/resource.d.ts.map +1 -1
- package/dist/schemas/resource.js +6 -1
- package/dist/schemas/resource.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 +666 -18
- package/schema/definition.schema.json +663 -18
- package/schema/openapi.json +5694 -2328
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";
|
|
@@ -13,12 +15,16 @@ var ok = (description, schema, headers) => ({
|
|
|
13
15
|
...headers !== void 0 ? { headers } : {}
|
|
14
16
|
});
|
|
15
17
|
var PROBLEMS = {
|
|
18
|
+
400: "Bad request, such as a dry run of an action that does not declare `dryRun`.",
|
|
16
19
|
401: "Not authenticated.",
|
|
17
|
-
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\`.`,
|
|
18
21
|
404: "Not found.",
|
|
19
22
|
409: "Conflict with a business rule.",
|
|
20
23
|
412: "Version conflict: `If-Match` does not match the current version, which is in `current`.",
|
|
21
|
-
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."
|
|
22
28
|
};
|
|
23
29
|
function problems(...statuses) {
|
|
24
30
|
return Object.fromEntries(statuses.map((status) => [String(status), {
|
|
@@ -53,6 +59,7 @@ var listParameters = [
|
|
|
53
59
|
type: "integer",
|
|
54
60
|
minimum: 1
|
|
55
61
|
}),
|
|
62
|
+
queryParameter("cursor", "Lists whose `pagination` is `cursor`: the `nextCursor` (or `previousCursor`) of a page, instead of `page`.", { type: "string" }),
|
|
56
63
|
queryParameter("sort", "Comma-separated fields; a `-` prefix sorts descending.", { type: "string" }),
|
|
57
64
|
{
|
|
58
65
|
name: "filter",
|
|
@@ -116,6 +123,42 @@ function createBootConfigJsonSchema() {
|
|
|
116
123
|
})
|
|
117
124
|
};
|
|
118
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
|
+
}
|
|
119
162
|
/** The OpenAPI 3.1 document of the Panneau HTTP API. */
|
|
120
163
|
function createOpenApiDocument() {
|
|
121
164
|
return {
|
|
@@ -125,15 +168,27 @@ function createOpenApiDocument() {
|
|
|
125
168
|
version: String(1),
|
|
126
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`."
|
|
127
170
|
},
|
|
128
|
-
paths: {
|
|
171
|
+
paths: withContextHeader({
|
|
129
172
|
"/definition": { get: {
|
|
130
173
|
operationId: "getDefinition",
|
|
131
|
-
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`.",
|
|
132
175
|
responses: {
|
|
133
176
|
200: ok("The definition.", ref("Definition")),
|
|
134
177
|
...problems(401, 403)
|
|
135
178
|
}
|
|
136
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
|
+
},
|
|
137
192
|
"/resources/{resource}": {
|
|
138
193
|
parameters: [resource],
|
|
139
194
|
get: {
|
|
@@ -141,7 +196,7 @@ function createOpenApiDocument() {
|
|
|
141
196
|
parameters: listParameters,
|
|
142
197
|
responses: {
|
|
143
198
|
200: ok("A page of items.", ref("ListResponse")),
|
|
144
|
-
...problems(401, 403, 404)
|
|
199
|
+
...problems(401, 403, 404, 422)
|
|
145
200
|
}
|
|
146
201
|
},
|
|
147
202
|
post: {
|
|
@@ -192,6 +247,21 @@ function createOpenApiDocument() {
|
|
|
192
247
|
}
|
|
193
248
|
}
|
|
194
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
|
+
},
|
|
195
265
|
"/resources/{resource}/{id}/preview": {
|
|
196
266
|
parameters: [resource, id],
|
|
197
267
|
post: {
|
|
@@ -220,7 +290,22 @@ function createOpenApiDocument() {
|
|
|
220
290
|
responses: {
|
|
221
291
|
200: ok("The result.", ref("ActionResult")),
|
|
222
292
|
202: ok("The action runs in the background.", ref("ActionRunResponse")),
|
|
223
|
-
...problems(401, 403, 404, 409, 422)
|
|
293
|
+
...problems(400, 401, 403, 404, 409, 422)
|
|
294
|
+
}
|
|
295
|
+
}
|
|
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)
|
|
224
309
|
}
|
|
225
310
|
}
|
|
226
311
|
},
|
|
@@ -256,115 +341,39 @@ function createOpenApiDocument() {
|
|
|
256
341
|
}
|
|
257
342
|
}
|
|
258
343
|
},
|
|
259
|
-
"/
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
...problems(401, 403)
|
|
266
|
-
}
|
|
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"))
|
|
267
350
|
},
|
|
268
|
-
post: {
|
|
269
|
-
operationId: "uploadMedia",
|
|
270
|
-
requestBody: {
|
|
271
|
-
required: true,
|
|
272
|
-
content: { "multipart/form-data": { schema: {
|
|
273
|
-
type: "object",
|
|
274
|
-
required: ["file"],
|
|
275
|
-
properties: {
|
|
276
|
-
file: {
|
|
277
|
-
type: "string",
|
|
278
|
-
contentMediaType: "application/octet-stream"
|
|
279
|
-
},
|
|
280
|
-
name: { type: "string" },
|
|
281
|
-
tags: {
|
|
282
|
-
type: "array",
|
|
283
|
-
items: { type: "string" }
|
|
284
|
-
}
|
|
285
|
-
}
|
|
286
|
-
} } }
|
|
287
|
-
},
|
|
288
|
-
responses: {
|
|
289
|
-
201: ok("The created media.", ref("MediaResponse")),
|
|
290
|
-
...problems(401, 403, 422)
|
|
291
|
-
}
|
|
292
|
-
}
|
|
293
|
-
},
|
|
294
|
-
"/media/tags": { get: {
|
|
295
|
-
operationId: "listMediaTags",
|
|
296
351
|
responses: {
|
|
297
|
-
200: ok("
|
|
298
|
-
|
|
299
|
-
required: ["data"],
|
|
300
|
-
properties: { data: {
|
|
301
|
-
type: "array",
|
|
302
|
-
items: { type: "string" }
|
|
303
|
-
} }
|
|
304
|
-
}),
|
|
305
|
-
...problems(401, 403)
|
|
352
|
+
200: ok("The presigned request.", ref("UploadSignResponse")),
|
|
353
|
+
...problems(401, 403, 404, 422)
|
|
306
354
|
}
|
|
307
355
|
} },
|
|
308
|
-
"/
|
|
309
|
-
parameters: [pathParameter("
|
|
310
|
-
get: {
|
|
311
|
-
operationId: "getMedia",
|
|
312
|
-
responses: {
|
|
313
|
-
200: ok("The media.", ref("MediaResponse")),
|
|
314
|
-
...problems(401, 403, 404)
|
|
315
|
-
}
|
|
316
|
-
},
|
|
317
|
-
patch: {
|
|
318
|
-
operationId: "updateMedia",
|
|
319
|
-
description: "Updates metadata, tags or the image `transform`.",
|
|
320
|
-
requestBody: {
|
|
321
|
-
required: true,
|
|
322
|
-
content: json(values)
|
|
323
|
-
},
|
|
324
|
-
responses: {
|
|
325
|
-
200: ok("The updated media.", ref("MediaResponse")),
|
|
326
|
-
...problems(401, 403, 404, 422)
|
|
327
|
-
}
|
|
328
|
-
},
|
|
329
|
-
delete: {
|
|
330
|
-
operationId: "deleteMedia",
|
|
331
|
-
responses: {
|
|
332
|
-
204: ok("Moved to the trash."),
|
|
333
|
-
...problems(401, 403, 404, 409)
|
|
334
|
-
}
|
|
335
|
-
}
|
|
336
|
-
},
|
|
337
|
-
"/media/{id}/file": {
|
|
338
|
-
parameters: [pathParameter("id", "Media id.")],
|
|
356
|
+
"/uploads/{upload}/complete": {
|
|
357
|
+
parameters: [pathParameter("upload", "Upload id: `upl_…`.")],
|
|
339
358
|
post: {
|
|
340
|
-
operationId: "
|
|
359
|
+
operationId: "completeUpload",
|
|
360
|
+
summary: "Once the browser completed the upload in storage, checks the object and gives the upload, which values reference.",
|
|
341
361
|
requestBody: {
|
|
342
|
-
required:
|
|
343
|
-
content: {
|
|
362
|
+
required: false,
|
|
363
|
+
content: json({
|
|
344
364
|
type: "object",
|
|
345
|
-
|
|
346
|
-
properties: { file: {
|
|
365
|
+
properties: { name: {
|
|
347
366
|
type: "string",
|
|
348
|
-
|
|
367
|
+
description: "The file's name, which the key doesn't keep, since the backend chose it."
|
|
349
368
|
} }
|
|
350
|
-
}
|
|
369
|
+
})
|
|
351
370
|
},
|
|
352
371
|
responses: {
|
|
353
|
-
200: ok("The
|
|
372
|
+
200: ok("The upload.", ref("UploadResponse")),
|
|
354
373
|
...problems(401, 403, 404, 422)
|
|
355
374
|
}
|
|
356
375
|
}
|
|
357
376
|
},
|
|
358
|
-
"/media/{id}/restore": {
|
|
359
|
-
parameters: [pathParameter("id", "Media id.")],
|
|
360
|
-
post: {
|
|
361
|
-
operationId: "restoreMedia",
|
|
362
|
-
responses: {
|
|
363
|
-
200: ok("The restored media.", ref("MediaResponse")),
|
|
364
|
-
...problems(401, 403, 404)
|
|
365
|
-
}
|
|
366
|
-
}
|
|
367
|
-
},
|
|
368
377
|
"/auth/session": { get: {
|
|
369
378
|
operationId: "getSession",
|
|
370
379
|
responses: {
|
|
@@ -377,44 +386,62 @@ function createOpenApiDocument() {
|
|
|
377
386
|
requestBody: {
|
|
378
387
|
required: true,
|
|
379
388
|
content: json({
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
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
|
+
}]
|
|
387
406
|
})
|
|
388
407
|
},
|
|
389
408
|
responses: {
|
|
390
409
|
200: ok("Logged in.", ref("Session")),
|
|
391
|
-
202: ok("A second factor is required: answer `/auth/two-factor/challenge`.",
|
|
392
|
-
|
|
393
|
-
properties: { twoFactor: {
|
|
394
|
-
type: "boolean",
|
|
395
|
-
const: true
|
|
396
|
-
} }
|
|
397
|
-
}),
|
|
398
|
-
...problems(422)
|
|
410
|
+
202: ok("A second factor is required: answer `/auth/two-factor/challenge`.", ref("TwoFactorChallenge")),
|
|
411
|
+
...problems(422, 429)
|
|
399
412
|
}
|
|
400
413
|
} },
|
|
401
414
|
"/auth/logout": { post: {
|
|
402
415
|
operationId: "logout",
|
|
416
|
+
description: "`panneau` auth mode. In `external` mode, the browser goes to `auth.logoutUrl` instead.",
|
|
403
417
|
responses: { 204: ok("Logged out.") }
|
|
404
418
|
} },
|
|
405
419
|
"/auth/providers/{provider}/redirect": {
|
|
406
420
|
parameters: [pathParameter("provider", "Provider id.")],
|
|
407
421
|
get: {
|
|
408
422
|
operationId: "redirectToProvider",
|
|
409
|
-
|
|
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" })],
|
|
410
425
|
responses: {
|
|
411
426
|
302: { description: "Redirect to the provider." },
|
|
412
427
|
...problems(404)
|
|
413
428
|
}
|
|
414
429
|
}
|
|
415
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
|
+
},
|
|
416
442
|
"/auth/password/forgot": { post: {
|
|
417
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=…\`.`,
|
|
418
445
|
requestBody: {
|
|
419
446
|
required: true,
|
|
420
447
|
content: json({
|
|
@@ -424,12 +451,13 @@ function createOpenApiDocument() {
|
|
|
424
451
|
})
|
|
425
452
|
},
|
|
426
453
|
responses: {
|
|
427
|
-
204: ok("A reset link was sent, if the account
|
|
428
|
-
...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)
|
|
429
456
|
}
|
|
430
457
|
} },
|
|
431
458
|
"/auth/password/reset": { post: {
|
|
432
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.",
|
|
433
461
|
requestBody: {
|
|
434
462
|
required: true,
|
|
435
463
|
content: json({
|
|
@@ -448,64 +476,233 @@ function createOpenApiDocument() {
|
|
|
448
476
|
},
|
|
449
477
|
responses: {
|
|
450
478
|
204: ok("The password was reset."),
|
|
451
|
-
...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)
|
|
452
504
|
}
|
|
453
505
|
} },
|
|
454
506
|
"/auth/two-factor/challenge": { post: {
|
|
455
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`.",
|
|
456
529
|
requestBody: {
|
|
457
530
|
required: true,
|
|
458
531
|
content: json({
|
|
459
532
|
type: "object",
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
recoveryCode: { type: "string" }
|
|
463
|
-
}
|
|
533
|
+
required: ["password"],
|
|
534
|
+
properties: { password: { type: "string" } }
|
|
464
535
|
})
|
|
465
536
|
},
|
|
466
537
|
responses: {
|
|
467
|
-
|
|
468
|
-
...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)
|
|
469
589
|
}
|
|
470
590
|
} },
|
|
471
591
|
"/auth/passkeys/options": { post: {
|
|
472
|
-
operationId: "
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
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
|
+
}
|
|
477
598
|
} },
|
|
478
599
|
"/auth/passkeys/login": { post: {
|
|
479
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.",
|
|
480
602
|
requestBody: {
|
|
481
603
|
required: true,
|
|
482
604
|
content: json({
|
|
483
605
|
type: "object",
|
|
484
|
-
|
|
606
|
+
required: ["credential"],
|
|
607
|
+
properties: {
|
|
608
|
+
credential: {
|
|
609
|
+
type: "object",
|
|
610
|
+
additionalProperties: true
|
|
611
|
+
},
|
|
612
|
+
remember: { type: "boolean" }
|
|
613
|
+
}
|
|
485
614
|
})
|
|
486
615
|
},
|
|
487
616
|
responses: {
|
|
488
617
|
200: ok("Logged in.", ref("Session")),
|
|
489
|
-
...problems(422)
|
|
618
|
+
...problems(422, 429)
|
|
490
619
|
}
|
|
491
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)
|
|
669
|
+
}
|
|
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
|
+
},
|
|
492
681
|
"/account": {
|
|
493
682
|
get: {
|
|
494
683
|
operationId: "getAccount",
|
|
684
|
+
summary: "With `auth.account`: the current user.",
|
|
495
685
|
responses: {
|
|
496
686
|
200: ok("The current user.", {
|
|
497
687
|
type: "object",
|
|
498
688
|
required: ["data"],
|
|
499
689
|
properties: { data: ref("User") }
|
|
500
690
|
}),
|
|
501
|
-
...problems(401)
|
|
691
|
+
...problems(401, 403)
|
|
502
692
|
}
|
|
503
693
|
},
|
|
504
694
|
patch: {
|
|
505
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.",
|
|
506
697
|
requestBody: {
|
|
507
698
|
required: true,
|
|
508
|
-
content: json(
|
|
699
|
+
content: json({
|
|
700
|
+
type: "object",
|
|
701
|
+
properties: {
|
|
702
|
+
name: { type: "string" },
|
|
703
|
+
email: { type: "string" }
|
|
704
|
+
}
|
|
705
|
+
})
|
|
509
706
|
},
|
|
510
707
|
responses: {
|
|
511
708
|
200: ok("The updated user.", {
|
|
@@ -513,36 +710,88 @@ function createOpenApiDocument() {
|
|
|
513
710
|
required: ["data"],
|
|
514
711
|
properties: { data: ref("User") }
|
|
515
712
|
}),
|
|
516
|
-
...problems(401, 422)
|
|
713
|
+
...problems(401, 403, 422)
|
|
517
714
|
}
|
|
518
715
|
}
|
|
519
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
|
+
} },
|
|
520
736
|
"/search": { get: {
|
|
521
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",
|
|
522
762
|
parameters: [{
|
|
523
|
-
...queryParameter("
|
|
763
|
+
...queryParameter("url", "The URL to embed.", { type: "string" }),
|
|
524
764
|
required: true
|
|
525
765
|
}],
|
|
526
766
|
responses: {
|
|
527
|
-
200: ok("
|
|
528
|
-
...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)
|
|
529
769
|
}
|
|
530
770
|
} },
|
|
531
771
|
"/dashboard/widgets/{widget}": {
|
|
532
772
|
parameters: [pathParameter("widget", "Widget id.")],
|
|
533
773
|
get: {
|
|
534
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.",
|
|
535
776
|
responses: {
|
|
536
|
-
200: ok("The widget's data
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
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)
|
|
541
787
|
}
|
|
542
788
|
}
|
|
543
789
|
}
|
|
544
|
-
},
|
|
545
|
-
components: {
|
|
790
|
+
}),
|
|
791
|
+
components: {
|
|
792
|
+
schemas: createComponentSchemas(),
|
|
793
|
+
parameters: { Context: contextHeader }
|
|
794
|
+
}
|
|
546
795
|
};
|
|
547
796
|
}
|
|
548
797
|
//#endregion
|