@panneau/protocol 5.0.0-alpha.4 → 5.0.0-alpha.41
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/aggregates.d.ts +135 -0
- package/dist/aggregates.d.ts.map +1 -0
- package/dist/aggregates.js +236 -0
- package/dist/aggregates.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 +970 -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/dashboards.d.ts +95 -0
- package/dist/dashboards.d.ts.map +1 -0
- package/dist/dashboards.js +140 -0
- package/dist/dashboards.js.map +1 -0
- package/dist/index.d.ts +4 -4
- package/dist/index.js +22 -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 -4
- package/dist/lint.d.ts.map +1 -1
- package/dist/lint.js +540 -15
- 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 +1 -1
- package/dist/mock/example.d.ts.map +1 -1
- package/dist/mock/example.js +49 -28
- package/dist/mock/example.js.map +1 -1
- package/dist/mock/index.d.ts +96 -5
- package/dist/mock/index.d.ts.map +1 -1
- package/dist/mock/index.js +505 -44
- package/dist/mock/index.js.map +1 -1
- package/dist/openapi.d.ts.map +1 -1
- package/dist/openapi.js +462 -50
- package/dist/openapi.js.map +1 -1
- package/dist/periods.d.ts +61 -0
- package/dist/periods.d.ts.map +1 -0
- package/dist/periods.js +130 -0
- package/dist/periods.js.map +1 -0
- 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 +23 -10
- package/dist/runtime/index.d.ts.map +1 -1
- package/dist/runtime/index.js +16 -3
- package/dist/schemas/action.d.ts +119 -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 +266 -5
- package/dist/schemas/api.d.ts.map +1 -1
- package/dist/schemas/api.js +134 -16
- 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 +1414 -30
- package/dist/schemas/definition.d.ts.map +1 -1
- package/dist/schemas/definition.js +77 -17
- package/dist/schemas/definition.js.map +1 -1
- package/dist/schemas/field.d.ts +358 -2
- package/dist/schemas/field.d.ts.map +1 -1
- package/dist/schemas/field.js +161 -20
- package/dist/schemas/field.js.map +1 -1
- package/dist/schemas/index.d.ts +5820 -46
- package/dist/schemas/index.d.ts.map +1 -1
- package/dist/schemas/index.js +69 -7
- 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 +34 -2
- package/dist/schemas/list.d.ts.map +1 -1
- package/dist/schemas/list.js +21 -6
- package/dist/schemas/list.js.map +1 -1
- package/dist/schemas/resource.d.ts +826 -17
- package/dist/schemas/resource.d.ts.map +1 -1
- package/dist/schemas/resource.js +26 -4
- package/dist/schemas/resource.js.map +1 -1
- package/dist/schemas/theme.d.ts +6 -2
- 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 +4379 -0
- package/dist/schemas/widget.d.ts.map +1 -0
- package/dist/schemas/widget.js +269 -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 +232 -0
- package/dist/widgets.d.ts.map +1 -0
- package/dist/widgets.js +630 -0
- package/dist/widgets.js.map +1 -0
- package/package.json +6 -3
- package/schema/boot.schema.json +1461 -104
- package/schema/definition.schema.json +1459 -105
- package/schema/openapi.json +7176 -2000
package/dist/openapi.js
CHANGED
|
@@ -1,4 +1,9 @@
|
|
|
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 "./widgets.js";
|
|
4
|
+
import "./aggregates.js";
|
|
5
|
+
import { OVERVIEW_PERIODS } from "./periods.js";
|
|
6
|
+
import "./search.js";
|
|
2
7
|
import { Theme } from "./schemas/theme.js";
|
|
3
8
|
import { Definition } from "./schemas/definition.js";
|
|
4
9
|
import { BootConfig } from "./schemas/boot.js";
|
|
@@ -15,11 +20,14 @@ var ok = (description, schema, headers) => ({
|
|
|
15
20
|
var PROBLEMS = {
|
|
16
21
|
400: "Bad request, such as a dry run of an action that does not declare `dryRun`.",
|
|
17
22
|
401: "Not authenticated.",
|
|
18
|
-
403:
|
|
23
|
+
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
24
|
404: "Not found.",
|
|
20
25
|
409: "Conflict with a business rule.",
|
|
21
26
|
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."
|
|
27
|
+
422: "Invalid values: messages are in `errors`, keyed by dot path.",
|
|
28
|
+
423: `The password must be confirmed first (\`POST /auth/password/confirm\`): a problem of type \`${PASSWORD_CONFIRMATION_PROBLEM_TYPE}\`.`,
|
|
29
|
+
429: "Too many requests: `Retry-After` gives the seconds to wait.",
|
|
30
|
+
500: "Server error, such as a widget whose data does not have the shape of its type."
|
|
23
31
|
};
|
|
24
32
|
function problems(...statuses) {
|
|
25
33
|
return Object.fromEntries(statuses.map((status) => [String(status), {
|
|
@@ -54,6 +62,7 @@ var listParameters = [
|
|
|
54
62
|
type: "integer",
|
|
55
63
|
minimum: 1
|
|
56
64
|
}),
|
|
65
|
+
queryParameter("cursor", "Lists whose `pagination` is `cursor`: the `nextCursor` (or `previousCursor`) of a page, instead of `page`.", { type: "string" }),
|
|
57
66
|
queryParameter("sort", "Comma-separated fields; a `-` prefix sorts descending.", { type: "string" }),
|
|
58
67
|
{
|
|
59
68
|
name: "filter",
|
|
@@ -70,6 +79,19 @@ var listParameters = [
|
|
|
70
79
|
queryParameter("q", "Search.", { type: "string" }),
|
|
71
80
|
queryParameter("fields", "Comma-separated fields to include in each item.", { type: "string" })
|
|
72
81
|
];
|
|
82
|
+
/** The parameters of `GET /resources/{resource}/aggregate`: the filters and search of the list. */
|
|
83
|
+
var aggregateParameters = [
|
|
84
|
+
...listParameters.filter((parameter) => ["filter", "q"].includes(String(parameter.name))),
|
|
85
|
+
queryParameter("measure", "What is measured of the items: `count` (the default), or `sum:{field}` of a field of the `sum` of the aggregates of the list. A sum of `money` adds the amounts, in minor units.", {
|
|
86
|
+
type: "string",
|
|
87
|
+
pattern: "^(count|sum:.+)$",
|
|
88
|
+
default: "count"
|
|
89
|
+
}),
|
|
90
|
+
queryParameter("group", "How the items are grouped: `{period}:{date field}`, where the period is `day`, `week` (from Monday) or `month` and the field is in the `dates` of the aggregates, or a field of their `groupBy`. Without it, the answer is a stat.", {
|
|
91
|
+
type: "string",
|
|
92
|
+
pattern: "^((day|week|month):.+|[^:]+)$"
|
|
93
|
+
})
|
|
94
|
+
];
|
|
73
95
|
var resource = pathParameter("resource", "Resource id.");
|
|
74
96
|
var id = pathParameter("id", "Item id.");
|
|
75
97
|
var values = {
|
|
@@ -117,6 +139,42 @@ function createBootConfigJsonSchema() {
|
|
|
117
139
|
})
|
|
118
140
|
};
|
|
119
141
|
}
|
|
142
|
+
/** The `Panneau-Context` header, which every operation takes (decision 0045). */
|
|
143
|
+
var contextHeader = {
|
|
144
|
+
name: CONTEXT_HEADER,
|
|
145
|
+
in: "header",
|
|
146
|
+
required: false,
|
|
147
|
+
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.",
|
|
148
|
+
schema: { type: "string" }
|
|
149
|
+
};
|
|
150
|
+
var METHODS = [
|
|
151
|
+
"get",
|
|
152
|
+
"post",
|
|
153
|
+
"put",
|
|
154
|
+
"patch",
|
|
155
|
+
"delete"
|
|
156
|
+
];
|
|
157
|
+
/**
|
|
158
|
+
* Adds the `Panneau-Context` header to the parameters of every path, and its `403` problem to
|
|
159
|
+
* every operation that doesn't have one: a value the user can't use is refused everywhere.
|
|
160
|
+
*/
|
|
161
|
+
function withContextHeader(paths) {
|
|
162
|
+
const parameter = { $ref: "#/components/parameters/Context" };
|
|
163
|
+
return Object.fromEntries(Object.entries(paths).map(([path, item]) => [path, {
|
|
164
|
+
...Object.fromEntries(Object.entries(item).map(([key, operation]) => {
|
|
165
|
+
if (!METHODS.includes(key)) return [key, operation];
|
|
166
|
+
const { responses = {}, ...rest } = operation;
|
|
167
|
+
return [key, {
|
|
168
|
+
...rest,
|
|
169
|
+
responses: {
|
|
170
|
+
...problems(403),
|
|
171
|
+
...responses
|
|
172
|
+
}
|
|
173
|
+
}];
|
|
174
|
+
})),
|
|
175
|
+
parameters: [...item.parameters ?? [], parameter]
|
|
176
|
+
}]));
|
|
177
|
+
}
|
|
120
178
|
/** The OpenAPI 3.1 document of the Panneau HTTP API. */
|
|
121
179
|
function createOpenApiDocument() {
|
|
122
180
|
return {
|
|
@@ -126,15 +184,39 @@ function createOpenApiDocument() {
|
|
|
126
184
|
version: String(1),
|
|
127
185
|
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
186
|
},
|
|
129
|
-
paths: {
|
|
187
|
+
paths: withContextHeader({
|
|
130
188
|
"/definition": { get: {
|
|
131
189
|
operationId: "getDefinition",
|
|
132
|
-
summary: "The definition for the current user, in the current locale
|
|
190
|
+
summary: "The definition for the current user, in the current locale, and for the values of `Panneau-Context`.",
|
|
133
191
|
responses: {
|
|
134
192
|
200: ok("The definition.", ref("Definition")),
|
|
135
193
|
...problems(401, 403)
|
|
136
194
|
}
|
|
137
195
|
} },
|
|
196
|
+
"/locale/{locale}": {
|
|
197
|
+
parameters: [pathParameter("locale", "A `locale` of `interfaceLocales`.")],
|
|
198
|
+
get: {
|
|
199
|
+
operationId: "switchLocale",
|
|
200
|
+
summary: "Optional: switches the interface to a locale of `interfaceLocales`, when their `url` is here (decision 0083). The app comes with a full navigation, and the next page load gets the definition in that locale.",
|
|
201
|
+
parameters: [queryParameter("next", "Where to go next: a local path under the base path of the app. Another one is ignored.", { type: "string" })],
|
|
202
|
+
responses: {
|
|
203
|
+
302: { description: "To `next`, or to the base path of the app." },
|
|
204
|
+
...problems(401, 404)
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
},
|
|
208
|
+
"/context/{param}/options": {
|
|
209
|
+
parameters: [pathParameter("param", "The name of a param of the context.")],
|
|
210
|
+
get: {
|
|
211
|
+
operationId: "getContextOptions",
|
|
212
|
+
summary: "The choices of a param of the context without inline `options`, for the values of the params before it in `Panneau-Context`.",
|
|
213
|
+
parameters: [queryParameter("q", "Search terms.", { type: "string" })],
|
|
214
|
+
responses: {
|
|
215
|
+
200: ok("The first choices that match `q`, in the order to show them.", ref("ContextOptionsResponse")),
|
|
216
|
+
...problems(401, 403, 404)
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
},
|
|
138
220
|
"/resources/{resource}": {
|
|
139
221
|
parameters: [resource],
|
|
140
222
|
get: {
|
|
@@ -142,7 +224,7 @@ function createOpenApiDocument() {
|
|
|
142
224
|
parameters: listParameters,
|
|
143
225
|
responses: {
|
|
144
226
|
200: ok("A page of items.", ref("ListResponse")),
|
|
145
|
-
...problems(401, 403, 404)
|
|
227
|
+
...problems(401, 403, 404, 422)
|
|
146
228
|
}
|
|
147
229
|
},
|
|
148
230
|
post: {
|
|
@@ -157,6 +239,22 @@ function createOpenApiDocument() {
|
|
|
157
239
|
}
|
|
158
240
|
}
|
|
159
241
|
},
|
|
242
|
+
"/resources/{resource}/aggregate": {
|
|
243
|
+
parameters: [resource],
|
|
244
|
+
get: {
|
|
245
|
+
operationId: "getResourceAggregate",
|
|
246
|
+
description: `The count or the sum of the items of the list that the user can list, with the filters and the search of the list, in the shape of a widget (decision 0084). Only what \`list.aggregates\` declares is aggregated: a resource without it is a \`404\`, and an undeclared field, or a measure or a group in the wrong format, a \`422\` with \`errors\` keyed by \`measure\` or \`group\`. Without a group, a \`StatWidgetData\`. By a period, a \`SeriesWidgetData\`: a point per period, at 0 without items, from the period of the \`from\` bound of the \`date-range\` filter whose id is the date field to the period of its \`to\` bound, or without a bound, of the first or the last item; at most 366 points, the latest, and their sum in \`total\`. By a field, a \`BreakdownWidgetData\`: a part per value, the largest first, at most 10, the rest in \`other\`, each with its \`key\` (\`null\` for the items without a value), the label and the tone of its option for a \`select\`, and the measure of every item in \`total\`.`,
|
|
247
|
+
parameters: aggregateParameters,
|
|
248
|
+
responses: {
|
|
249
|
+
200: ok("The aggregate, in the shape of a widget.", { anyOf: [
|
|
250
|
+
ref("StatWidgetData"),
|
|
251
|
+
ref("SeriesWidgetData"),
|
|
252
|
+
ref("BreakdownWidgetData")
|
|
253
|
+
] }),
|
|
254
|
+
...problems(401, 403, 404, 422)
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
},
|
|
160
258
|
"/resources/{resource}/{id}": {
|
|
161
259
|
parameters: [resource, id],
|
|
162
260
|
get: {
|
|
@@ -193,6 +291,21 @@ function createOpenApiDocument() {
|
|
|
193
291
|
}
|
|
194
292
|
}
|
|
195
293
|
},
|
|
294
|
+
"/resources/{resource}/{id}/duplicate": {
|
|
295
|
+
parameters: [resource, id],
|
|
296
|
+
post: {
|
|
297
|
+
operationId: "duplicateItem",
|
|
298
|
+
description: "Copies an item, for the built-in `duplicate` (decision 0040). Allowed on the items whose `abilities.duplicate` is `true`.",
|
|
299
|
+
responses: {
|
|
300
|
+
201: ok("The copy, a new item.", ref("ItemResponse"), etag),
|
|
301
|
+
...problems(401, 403, 404),
|
|
302
|
+
409: {
|
|
303
|
+
description: "The copy conflicts with another item, such as a unique value.",
|
|
304
|
+
content: { [PROBLEM_CONTENT_TYPE]: { schema: ref("Problem") } }
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
},
|
|
196
309
|
"/resources/{resource}/{id}/preview": {
|
|
197
310
|
parameters: [resource, id],
|
|
198
311
|
post: {
|
|
@@ -225,6 +338,21 @@ function createOpenApiDocument() {
|
|
|
225
338
|
}
|
|
226
339
|
}
|
|
227
340
|
},
|
|
341
|
+
"/resources/{resource}/fields/{field}/check": {
|
|
342
|
+
parameters: [resource, pathParameter("field", "Name of a field with `check`.")],
|
|
343
|
+
post: {
|
|
344
|
+
operationId: "checkField",
|
|
345
|
+
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`.",
|
|
346
|
+
requestBody: {
|
|
347
|
+
required: true,
|
|
348
|
+
content: json(ref("FieldCheckRequest"))
|
|
349
|
+
},
|
|
350
|
+
responses: {
|
|
351
|
+
200: ok("What the backend says about the value.", ref("FieldCheckResponse")),
|
|
352
|
+
...problems(401, 403, 404, 422)
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
},
|
|
228
356
|
"/actions/runs": { get: {
|
|
229
357
|
operationId: "listActionRuns",
|
|
230
358
|
summary: "The current user's recent runs.",
|
|
@@ -302,44 +430,62 @@ function createOpenApiDocument() {
|
|
|
302
430
|
requestBody: {
|
|
303
431
|
required: true,
|
|
304
432
|
content: json({
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
433
|
+
description: "An email and a password, or the single secret of `auth.token`.",
|
|
434
|
+
oneOf: [{
|
|
435
|
+
type: "object",
|
|
436
|
+
required: ["email", "password"],
|
|
437
|
+
properties: {
|
|
438
|
+
email: { type: "string" },
|
|
439
|
+
password: { type: "string" },
|
|
440
|
+
remember: { type: "boolean" }
|
|
441
|
+
}
|
|
442
|
+
}, {
|
|
443
|
+
type: "object",
|
|
444
|
+
required: ["token"],
|
|
445
|
+
properties: {
|
|
446
|
+
token: { type: "string" },
|
|
447
|
+
remember: { type: "boolean" }
|
|
448
|
+
}
|
|
449
|
+
}]
|
|
312
450
|
})
|
|
313
451
|
},
|
|
314
452
|
responses: {
|
|
315
453
|
200: ok("Logged in.", ref("Session")),
|
|
316
|
-
202: ok("A second factor is required: answer `/auth/two-factor/challenge`.",
|
|
317
|
-
|
|
318
|
-
properties: { twoFactor: {
|
|
319
|
-
type: "boolean",
|
|
320
|
-
const: true
|
|
321
|
-
} }
|
|
322
|
-
}),
|
|
323
|
-
...problems(422)
|
|
454
|
+
202: ok("A second factor is required: answer `/auth/two-factor/challenge`.", ref("TwoFactorChallenge")),
|
|
455
|
+
...problems(422, 429)
|
|
324
456
|
}
|
|
325
457
|
} },
|
|
326
458
|
"/auth/logout": { post: {
|
|
327
459
|
operationId: "logout",
|
|
460
|
+
description: "`panneau` auth mode. In `external` mode, the browser goes to `auth.logoutUrl` instead.",
|
|
328
461
|
responses: { 204: ok("Logged out.") }
|
|
329
462
|
} },
|
|
330
463
|
"/auth/providers/{provider}/redirect": {
|
|
331
464
|
parameters: [pathParameter("provider", "Provider id.")],
|
|
332
465
|
get: {
|
|
333
466
|
operationId: "redirectToProvider",
|
|
334
|
-
|
|
467
|
+
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.",
|
|
468
|
+
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" })],
|
|
335
469
|
responses: {
|
|
336
470
|
302: { description: "Redirect to the provider." },
|
|
337
471
|
...problems(404)
|
|
338
472
|
}
|
|
339
473
|
}
|
|
340
474
|
},
|
|
475
|
+
"/auth/providers/{provider}/callback": {
|
|
476
|
+
parameters: [pathParameter("provider", "Provider id.")],
|
|
477
|
+
get: {
|
|
478
|
+
operationId: "providerCallback",
|
|
479
|
+
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.",
|
|
480
|
+
responses: {
|
|
481
|
+
302: { description: "To `next`, or to the base path of the app with `authError` when the login failed." },
|
|
482
|
+
...problems(404)
|
|
483
|
+
}
|
|
484
|
+
}
|
|
485
|
+
},
|
|
341
486
|
"/auth/password/forgot": { post: {
|
|
342
487
|
operationId: "forgotPassword",
|
|
488
|
+
summary: `With \`auth.passwordReset\`: emails a link to the page of the app at \`{basePath}/${AUTH_PAGE_PATHS.resetPassword}?token=…&email=…\`.`,
|
|
343
489
|
requestBody: {
|
|
344
490
|
required: true,
|
|
345
491
|
content: json({
|
|
@@ -349,12 +495,13 @@ function createOpenApiDocument() {
|
|
|
349
495
|
})
|
|
350
496
|
},
|
|
351
497
|
responses: {
|
|
352
|
-
204: ok("A reset link was sent, if the account
|
|
353
|
-
...problems(422)
|
|
498
|
+
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."),
|
|
499
|
+
...problems(422, 429)
|
|
354
500
|
}
|
|
355
501
|
} },
|
|
356
502
|
"/auth/password/reset": { post: {
|
|
357
503
|
operationId: "resetPassword",
|
|
504
|
+
summary: "With `auth.passwordReset`: sets a new password, with the token and the email of the link. It does not log in.",
|
|
358
505
|
requestBody: {
|
|
359
506
|
required: true,
|
|
360
507
|
content: json({
|
|
@@ -373,64 +520,233 @@ function createOpenApiDocument() {
|
|
|
373
520
|
},
|
|
374
521
|
responses: {
|
|
375
522
|
204: ok("The password was reset."),
|
|
376
|
-
...problems(422)
|
|
523
|
+
...problems(422, 429)
|
|
524
|
+
}
|
|
525
|
+
} },
|
|
526
|
+
"/auth/email/verification": { post: {
|
|
527
|
+
operationId: "sendEmailVerification",
|
|
528
|
+
summary: `With \`auth.emailVerification\`: emails the current user a link to the page of the app at \`{basePath}/${AUTH_PAGE_PATHS.verifyEmail}?token=…\`.`,
|
|
529
|
+
responses: {
|
|
530
|
+
204: ok("A link was sent, or the address is already verified."),
|
|
531
|
+
...problems(401, 429)
|
|
532
|
+
}
|
|
533
|
+
} },
|
|
534
|
+
"/auth/email/verify": { post: {
|
|
535
|
+
operationId: "verifyEmail",
|
|
536
|
+
summary: "With `auth.emailVerification`: verifies the address of the token of a link. The user does not need to be logged in.",
|
|
537
|
+
requestBody: {
|
|
538
|
+
required: true,
|
|
539
|
+
content: json({
|
|
540
|
+
type: "object",
|
|
541
|
+
required: ["token"],
|
|
542
|
+
properties: { token: { type: "string" } }
|
|
543
|
+
})
|
|
544
|
+
},
|
|
545
|
+
responses: {
|
|
546
|
+
204: ok("The address is verified."),
|
|
547
|
+
...problems(422, 429)
|
|
377
548
|
}
|
|
378
549
|
} },
|
|
379
550
|
"/auth/two-factor/challenge": { post: {
|
|
380
551
|
operationId: "twoFactorChallenge",
|
|
552
|
+
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`.",
|
|
553
|
+
requestBody: {
|
|
554
|
+
required: true,
|
|
555
|
+
content: json({ oneOf: [{
|
|
556
|
+
type: "object",
|
|
557
|
+
required: ["code"],
|
|
558
|
+
properties: { code: { type: "string" } }
|
|
559
|
+
}, {
|
|
560
|
+
type: "object",
|
|
561
|
+
required: ["recoveryCode"],
|
|
562
|
+
properties: { recoveryCode: { type: "string" } }
|
|
563
|
+
}] })
|
|
564
|
+
},
|
|
565
|
+
responses: {
|
|
566
|
+
200: ok("Logged in.", ref("Session")),
|
|
567
|
+
...problems(422, 429)
|
|
568
|
+
}
|
|
569
|
+
} },
|
|
570
|
+
"/auth/password/confirm": { post: {
|
|
571
|
+
operationId: "confirmPassword",
|
|
572
|
+
summary: "Confirms the password of the current user, for the operations that answer `423`.",
|
|
381
573
|
requestBody: {
|
|
382
574
|
required: true,
|
|
383
575
|
content: json({
|
|
384
576
|
type: "object",
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
recoveryCode: { type: "string" }
|
|
388
|
-
}
|
|
577
|
+
required: ["password"],
|
|
578
|
+
properties: { password: { type: "string" } }
|
|
389
579
|
})
|
|
390
580
|
},
|
|
391
581
|
responses: {
|
|
392
|
-
|
|
393
|
-
...problems(422)
|
|
582
|
+
204: ok("The password is confirmed."),
|
|
583
|
+
...problems(401, 422, 429)
|
|
584
|
+
}
|
|
585
|
+
} },
|
|
586
|
+
"/account/two-factor": {
|
|
587
|
+
get: {
|
|
588
|
+
operationId: "getTwoFactor",
|
|
589
|
+
summary: "With `auth.twoFactor`: the two-factor authentication of the user.",
|
|
590
|
+
responses: {
|
|
591
|
+
200: ok("Its status.", ref("TwoFactorStatus")),
|
|
592
|
+
...problems(401, 403)
|
|
593
|
+
}
|
|
594
|
+
},
|
|
595
|
+
post: {
|
|
596
|
+
operationId: "enableTwoFactor",
|
|
597
|
+
summary: "Starts setting it up: a new secret, `pending` until `POST /account/two-factor/confirm`.",
|
|
598
|
+
responses: {
|
|
599
|
+
200: ok("The secret to add to an authenticator app.", ref("TwoFactorSetup")),
|
|
600
|
+
...problems(401, 403, 409, 423)
|
|
601
|
+
}
|
|
602
|
+
},
|
|
603
|
+
delete: {
|
|
604
|
+
operationId: "disableTwoFactor",
|
|
605
|
+
summary: "Turns it off. A `409` when the backend requires it for the user.",
|
|
606
|
+
responses: {
|
|
607
|
+
204: ok("Turned off."),
|
|
608
|
+
...problems(401, 403, 409, 423)
|
|
609
|
+
}
|
|
610
|
+
}
|
|
611
|
+
},
|
|
612
|
+
"/account/two-factor/confirm": { post: {
|
|
613
|
+
operationId: "confirmTwoFactor",
|
|
614
|
+
requestBody: {
|
|
615
|
+
required: true,
|
|
616
|
+
content: json({
|
|
617
|
+
type: "object",
|
|
618
|
+
required: ["code"],
|
|
619
|
+
properties: { code: { type: "string" } }
|
|
620
|
+
})
|
|
621
|
+
},
|
|
622
|
+
responses: {
|
|
623
|
+
200: ok("Turned on, with its recovery codes.", ref("RecoveryCodes")),
|
|
624
|
+
...problems(401, 403, 409, 422, 423)
|
|
625
|
+
}
|
|
626
|
+
} },
|
|
627
|
+
"/account/two-factor/recovery-codes": { post: {
|
|
628
|
+
operationId: "regenerateRecoveryCodes",
|
|
629
|
+
summary: "New recovery codes, in place of the old ones.",
|
|
630
|
+
responses: {
|
|
631
|
+
200: ok("The new codes.", ref("RecoveryCodes")),
|
|
632
|
+
...problems(401, 403, 409, 423)
|
|
394
633
|
}
|
|
395
634
|
} },
|
|
396
635
|
"/auth/passkeys/options": { post: {
|
|
397
|
-
operationId: "
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
636
|
+
operationId: "passkeyLoginOptions",
|
|
637
|
+
summary: "With `auth.passkeys`: the options of `navigator.credentials.get()`, for any passkey of the site.",
|
|
638
|
+
responses: {
|
|
639
|
+
200: ok("The options.", ref("WebAuthnOptions")),
|
|
640
|
+
...problems(429)
|
|
641
|
+
}
|
|
402
642
|
} },
|
|
403
643
|
"/auth/passkeys/login": { post: {
|
|
404
644
|
operationId: "passkeyLogin",
|
|
645
|
+
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.",
|
|
405
646
|
requestBody: {
|
|
406
647
|
required: true,
|
|
407
648
|
content: json({
|
|
408
649
|
type: "object",
|
|
409
|
-
|
|
650
|
+
required: ["credential"],
|
|
651
|
+
properties: {
|
|
652
|
+
credential: {
|
|
653
|
+
type: "object",
|
|
654
|
+
additionalProperties: true
|
|
655
|
+
},
|
|
656
|
+
remember: { type: "boolean" }
|
|
657
|
+
}
|
|
410
658
|
})
|
|
411
659
|
},
|
|
412
660
|
responses: {
|
|
413
661
|
200: ok("Logged in.", ref("Session")),
|
|
414
|
-
...problems(422)
|
|
662
|
+
...problems(422, 429)
|
|
415
663
|
}
|
|
416
664
|
} },
|
|
665
|
+
"/account/passkeys": {
|
|
666
|
+
get: {
|
|
667
|
+
operationId: "listPasskeys",
|
|
668
|
+
responses: {
|
|
669
|
+
200: ok("The passkeys of the current user.", {
|
|
670
|
+
type: "object",
|
|
671
|
+
required: ["data"],
|
|
672
|
+
properties: { data: {
|
|
673
|
+
type: "array",
|
|
674
|
+
items: ref("Passkey")
|
|
675
|
+
} }
|
|
676
|
+
}),
|
|
677
|
+
...problems(401, 403)
|
|
678
|
+
}
|
|
679
|
+
},
|
|
680
|
+
post: {
|
|
681
|
+
operationId: "addPasskey",
|
|
682
|
+
summary: "Adds a passkey, with the credential of `navigator.credentials.create()` for the options of `POST /account/passkeys/options`.",
|
|
683
|
+
requestBody: {
|
|
684
|
+
required: true,
|
|
685
|
+
content: json({
|
|
686
|
+
type: "object",
|
|
687
|
+
required: ["name", "credential"],
|
|
688
|
+
properties: {
|
|
689
|
+
name: { type: "string" },
|
|
690
|
+
credential: {
|
|
691
|
+
type: "object",
|
|
692
|
+
additionalProperties: true
|
|
693
|
+
}
|
|
694
|
+
}
|
|
695
|
+
})
|
|
696
|
+
},
|
|
697
|
+
responses: {
|
|
698
|
+
201: ok("The passkey.", {
|
|
699
|
+
type: "object",
|
|
700
|
+
required: ["data"],
|
|
701
|
+
properties: { data: ref("Passkey") }
|
|
702
|
+
}),
|
|
703
|
+
...problems(401, 403, 409, 422, 423)
|
|
704
|
+
}
|
|
705
|
+
}
|
|
706
|
+
},
|
|
707
|
+
"/account/passkeys/options": { post: {
|
|
708
|
+
operationId: "passkeyRegistrationOptions",
|
|
709
|
+
summary: "The options of `navigator.credentials.create()`, for the current user. A `409` for a user who can't have passkeys.",
|
|
710
|
+
responses: {
|
|
711
|
+
200: ok("The options.", ref("WebAuthnOptions")),
|
|
712
|
+
...problems(401, 403, 409, 423)
|
|
713
|
+
}
|
|
714
|
+
} },
|
|
715
|
+
"/account/passkeys/{passkey}": {
|
|
716
|
+
parameters: [pathParameter("passkey", "The id of the passkey.")],
|
|
717
|
+
delete: {
|
|
718
|
+
operationId: "deletePasskey",
|
|
719
|
+
responses: {
|
|
720
|
+
204: ok("Removed."),
|
|
721
|
+
...problems(401, 403, 404, 423)
|
|
722
|
+
}
|
|
723
|
+
}
|
|
724
|
+
},
|
|
417
725
|
"/account": {
|
|
418
726
|
get: {
|
|
419
727
|
operationId: "getAccount",
|
|
728
|
+
summary: "With `auth.account`: the current user.",
|
|
420
729
|
responses: {
|
|
421
730
|
200: ok("The current user.", {
|
|
422
731
|
type: "object",
|
|
423
732
|
required: ["data"],
|
|
424
733
|
properties: { data: ref("User") }
|
|
425
734
|
}),
|
|
426
|
-
...problems(401)
|
|
735
|
+
...problems(401, 403)
|
|
427
736
|
}
|
|
428
737
|
},
|
|
429
738
|
patch: {
|
|
430
739
|
operationId: "updateAccount",
|
|
740
|
+
summary: "Saves the name and the email of the current user. With `auth.emailVerification`, a new email is unverified, and gets a link.",
|
|
431
741
|
requestBody: {
|
|
432
742
|
required: true,
|
|
433
|
-
content: json(
|
|
743
|
+
content: json({
|
|
744
|
+
type: "object",
|
|
745
|
+
properties: {
|
|
746
|
+
name: { type: "string" },
|
|
747
|
+
email: { type: "string" }
|
|
748
|
+
}
|
|
749
|
+
})
|
|
434
750
|
},
|
|
435
751
|
responses: {
|
|
436
752
|
200: ok("The updated user.", {
|
|
@@ -438,36 +754,132 @@ function createOpenApiDocument() {
|
|
|
438
754
|
required: ["data"],
|
|
439
755
|
properties: { data: ref("User") }
|
|
440
756
|
}),
|
|
441
|
-
...problems(401, 422)
|
|
757
|
+
...problems(401, 403, 422)
|
|
442
758
|
}
|
|
443
759
|
}
|
|
444
760
|
},
|
|
761
|
+
"/account/password": { put: {
|
|
762
|
+
operationId: "updatePassword",
|
|
763
|
+
summary: "Changes the password of the current user, with the current one.",
|
|
764
|
+
requestBody: {
|
|
765
|
+
required: true,
|
|
766
|
+
content: json({
|
|
767
|
+
type: "object",
|
|
768
|
+
required: ["currentPassword", "password"],
|
|
769
|
+
properties: {
|
|
770
|
+
currentPassword: { type: "string" },
|
|
771
|
+
password: { type: "string" }
|
|
772
|
+
}
|
|
773
|
+
})
|
|
774
|
+
},
|
|
775
|
+
responses: {
|
|
776
|
+
204: ok("The password was changed."),
|
|
777
|
+
...problems(401, 403, 422, 429)
|
|
778
|
+
}
|
|
779
|
+
} },
|
|
445
780
|
"/search": { get: {
|
|
446
781
|
operationId: "search",
|
|
782
|
+
parameters: [
|
|
783
|
+
{
|
|
784
|
+
...queryParameter("q", "Search terms, trimmed.", {
|
|
785
|
+
type: "string",
|
|
786
|
+
minLength: 2,
|
|
787
|
+
maxLength: 255
|
|
788
|
+
}),
|
|
789
|
+
required: true
|
|
790
|
+
},
|
|
791
|
+
queryParameter("limit", "Items per resource.", {
|
|
792
|
+
type: "integer",
|
|
793
|
+
minimum: 1,
|
|
794
|
+
maximum: 20,
|
|
795
|
+
default: 5
|
|
796
|
+
}),
|
|
797
|
+
queryParameter("resources", "Comma-separated ids of the searchable resources to search. Defaults to every one.", { type: "string" })
|
|
798
|
+
],
|
|
799
|
+
responses: {
|
|
800
|
+
200: ok(`Results grouped by resource, in the order of the definition: at most \`limit\` items per resource, and 20 in all.`, ref("SearchResponse")),
|
|
801
|
+
...problems(401, 422, 429)
|
|
802
|
+
}
|
|
803
|
+
} },
|
|
804
|
+
"/embeds": { get: {
|
|
805
|
+
operationId: "resolveEmbed",
|
|
447
806
|
parameters: [{
|
|
448
|
-
...queryParameter("
|
|
807
|
+
...queryParameter("url", "The URL to embed.", { type: "string" }),
|
|
449
808
|
required: true
|
|
450
809
|
}],
|
|
451
810
|
responses: {
|
|
452
|
-
200: ok("
|
|
453
|
-
...problems(401)
|
|
811
|
+
200: ok("The value of an `embed` field for the URL, from its provider's oEmbed.", ref("EmbedResponse")),
|
|
812
|
+
...problems(401, 422, 429)
|
|
454
813
|
}
|
|
455
814
|
} },
|
|
456
815
|
"/dashboard/widgets/{widget}": {
|
|
457
816
|
parameters: [pathParameter("widget", "Widget id.")],
|
|
458
817
|
get: {
|
|
459
818
|
operationId: "getWidgetData",
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
819
|
+
description: "The data of a widget of a dashboard of the user, read as the user (decision 0064): the home page, the dashboard page of `page`, or the summary above the list of `resource`, with the filters and the search of the list (decision 0084). The built-in widgets on a resource (`settings.resource`) have none: clients read the list or the aggregates of the resource. A widget that is not on that page or in that summary of the user is a `404`; a `403` hides the widget. `page` and `resource` together are a `422`.",
|
|
820
|
+
parameters: [
|
|
821
|
+
queryParameter("page", "The id of the dashboard page of the widget, in `pages`. Defaults to `home`, the home page, whose widgets are `pages.home.widgets` or `dashboard.widgets`. Not with `resource`.", {
|
|
822
|
+
type: "string",
|
|
823
|
+
minLength: 1
|
|
464
824
|
}),
|
|
465
|
-
|
|
825
|
+
queryParameter("resource", "The id of the resource whose summary (`summary.widgets`) holds the widget, instead of a page. The request then has the list's current filters and search (`filter`, `q`), unless the widget has `settings.followsList: false`; never its sort or paging.", {
|
|
826
|
+
type: "string",
|
|
827
|
+
minLength: 1
|
|
828
|
+
}),
|
|
829
|
+
...listParameters.filter((parameter) => ["filter", "q"].includes(String(parameter.name))),
|
|
830
|
+
{
|
|
831
|
+
name: "period",
|
|
832
|
+
in: "query",
|
|
833
|
+
required: false,
|
|
834
|
+
style: "deepObject",
|
|
835
|
+
explode: true,
|
|
836
|
+
description: "The period chosen in the overview of the widget (decision 0084), unless the widget has `settings.period: false`: `period[option]=30d&period[from]=2026-10-19&period[to]=2026-11-17`. `from` and `to` are its first and last days, both inclusive, in the time zone of the browser. A wrong period is a `422` keyed by `period`.",
|
|
837
|
+
schema: {
|
|
838
|
+
type: "object",
|
|
839
|
+
properties: {
|
|
840
|
+
option: {
|
|
841
|
+
type: "string",
|
|
842
|
+
enum: [...OVERVIEW_PERIODS]
|
|
843
|
+
},
|
|
844
|
+
from: {
|
|
845
|
+
type: "string",
|
|
846
|
+
format: "date"
|
|
847
|
+
},
|
|
848
|
+
to: {
|
|
849
|
+
type: "string",
|
|
850
|
+
format: "date"
|
|
851
|
+
}
|
|
852
|
+
},
|
|
853
|
+
required: [
|
|
854
|
+
"option",
|
|
855
|
+
"from",
|
|
856
|
+
"to"
|
|
857
|
+
]
|
|
858
|
+
}
|
|
859
|
+
}
|
|
860
|
+
],
|
|
861
|
+
responses: {
|
|
862
|
+
200: ok("The widget's data, in the shape of its type: `StatWidgetData`, `SeriesWidgetData`, `ListWidgetData`, `BreakdownWidgetData`, `MetricWidgetData` and `TableWidgetData` for the built-in types, the plugin's own object for others. A `metric` that follows the period has `previous`, its value over the days of `getPreviousRange()`: the same number of days just before (`7d`, `30d`, `90d`), the same days of the month before (`month`), or of the year before (`year`).", { anyOf: [
|
|
863
|
+
ref("StatWidgetData"),
|
|
864
|
+
ref("SeriesWidgetData"),
|
|
865
|
+
ref("ListWidgetData"),
|
|
866
|
+
ref("BreakdownWidgetData"),
|
|
867
|
+
ref("MetricWidgetData"),
|
|
868
|
+
ref("TableWidgetData"),
|
|
869
|
+
{
|
|
870
|
+
type: "object",
|
|
871
|
+
additionalProperties: true
|
|
872
|
+
}
|
|
873
|
+
] }),
|
|
874
|
+
...problems(401, 403, 404, 422, 500)
|
|
466
875
|
}
|
|
467
876
|
}
|
|
468
877
|
}
|
|
469
|
-
},
|
|
470
|
-
components: {
|
|
878
|
+
}),
|
|
879
|
+
components: {
|
|
880
|
+
schemas: createComponentSchemas(),
|
|
881
|
+
parameters: { Context: contextHeader }
|
|
882
|
+
}
|
|
471
883
|
};
|
|
472
884
|
}
|
|
473
885
|
//#endregion
|