@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.
Files changed (147) hide show
  1. package/dist/addresses.d.ts +23 -0
  2. package/dist/addresses.d.ts.map +1 -0
  3. package/dist/addresses.js +52 -0
  4. package/dist/addresses.js.map +1 -0
  5. package/dist/compound.d.ts +20 -0
  6. package/dist/compound.d.ts.map +1 -0
  7. package/dist/compound.js +27 -0
  8. package/dist/compound.js.map +1 -0
  9. package/dist/conditions.d.ts +1 -1
  10. package/dist/conformance/index.d.ts +6 -0
  11. package/dist/conformance/index.d.ts.map +1 -1
  12. package/dist/conformance/index.js +801 -11
  13. package/dist/conformance/index.js.map +1 -1
  14. package/dist/constants.d.ts +108 -2
  15. package/dist/constants.d.ts.map +1 -1
  16. package/dist/constants.js +181 -3
  17. package/dist/constants.js.map +1 -1
  18. package/dist/context.d.ts +15 -0
  19. package/dist/context.d.ts.map +1 -0
  20. package/dist/context.js +34 -0
  21. package/dist/context.js.map +1 -0
  22. package/dist/currencies.d.ts +22 -0
  23. package/dist/currencies.d.ts.map +1 -0
  24. package/dist/currencies.js +231 -0
  25. package/dist/currencies.js.map +1 -0
  26. package/dist/index.d.ts +4 -4
  27. package/dist/index.js +19 -8
  28. package/dist/libraries.d.ts +33 -0
  29. package/dist/libraries.d.ts.map +1 -0
  30. package/dist/libraries.js +59 -0
  31. package/dist/libraries.js.map +1 -0
  32. package/dist/links.d.ts +38 -0
  33. package/dist/links.d.ts.map +1 -0
  34. package/dist/links.js +65 -0
  35. package/dist/links.js.map +1 -0
  36. package/dist/lint.d.ts +4 -3
  37. package/dist/lint.d.ts.map +1 -1
  38. package/dist/lint.js +168 -7
  39. package/dist/lint.js.map +1 -1
  40. package/dist/mock/auth.d.ts +71 -0
  41. package/dist/mock/auth.d.ts.map +1 -0
  42. package/dist/mock/auth.js +346 -0
  43. package/dist/mock/auth.js.map +1 -0
  44. package/dist/mock/example.d.ts +3 -2
  45. package/dist/mock/example.d.ts.map +1 -1
  46. package/dist/mock/example.js +241 -144
  47. package/dist/mock/example.js.map +1 -1
  48. package/dist/mock/index.d.ts +79 -7
  49. package/dist/mock/index.d.ts.map +1 -1
  50. package/dist/mock/index.js +603 -38
  51. package/dist/mock/index.js.map +1 -1
  52. package/dist/openapi.d.ts.map +1 -1
  53. package/dist/openapi.js +392 -144
  54. package/dist/openapi.js.map +1 -1
  55. package/dist/problem.d.ts +1 -1
  56. package/dist/query.d.ts +18 -0
  57. package/dist/query.d.ts.map +1 -1
  58. package/dist/query.js +34 -8
  59. package/dist/query.js.map +1 -1
  60. package/dist/resourceTypes.d.ts +39 -0
  61. package/dist/resourceTypes.d.ts.map +1 -0
  62. package/dist/resourceTypes.js +34 -0
  63. package/dist/resourceTypes.js.map +1 -0
  64. package/dist/rules.d.ts +18 -5
  65. package/dist/rules.d.ts.map +1 -1
  66. package/dist/rules.js +233 -15
  67. package/dist/rules.js.map +1 -1
  68. package/dist/runtime/index.d.ts +20 -10
  69. package/dist/runtime/index.d.ts.map +1 -1
  70. package/dist/runtime/index.js +13 -3
  71. package/dist/schemas/action.d.ts +118 -10
  72. package/dist/schemas/action.d.ts.map +1 -1
  73. package/dist/schemas/action.js +20 -3
  74. package/dist/schemas/action.js.map +1 -1
  75. package/dist/schemas/api.d.ts +334 -42
  76. package/dist/schemas/api.d.ts.map +1 -1
  77. package/dist/schemas/api.js +194 -34
  78. package/dist/schemas/api.js.map +1 -1
  79. package/dist/schemas/boot.d.ts +25 -1
  80. package/dist/schemas/boot.d.ts.map +1 -1
  81. package/dist/schemas/boot.js +2 -1
  82. package/dist/schemas/boot.js.map +1 -1
  83. package/dist/schemas/common.d.ts +1 -0
  84. package/dist/schemas/common.d.ts.map +1 -1
  85. package/dist/schemas/common.js +2 -1
  86. package/dist/schemas/common.js.map +1 -1
  87. package/dist/schemas/definition.d.ts +341 -28
  88. package/dist/schemas/definition.d.ts.map +1 -1
  89. package/dist/schemas/definition.js +65 -19
  90. package/dist/schemas/definition.js.map +1 -1
  91. package/dist/schemas/field.d.ts +357 -2
  92. package/dist/schemas/field.d.ts.map +1 -1
  93. package/dist/schemas/field.js +160 -20
  94. package/dist/schemas/field.js.map +1 -1
  95. package/dist/schemas/index.d.ts +1429 -80
  96. package/dist/schemas/index.d.ts.map +1 -1
  97. package/dist/schemas/index.js +60 -10
  98. package/dist/schemas/index.js.map +1 -1
  99. package/dist/schemas/jsonRules.d.ts +83 -0
  100. package/dist/schemas/jsonRules.d.ts.map +1 -0
  101. package/dist/schemas/jsonRules.js +46 -0
  102. package/dist/schemas/jsonRules.js.map +1 -0
  103. package/dist/schemas/layout.d.ts +2 -1
  104. package/dist/schemas/layout.d.ts.map +1 -1
  105. package/dist/schemas/layout.js +2 -1
  106. package/dist/schemas/layout.js.map +1 -1
  107. package/dist/schemas/list.d.ts +23 -2
  108. package/dist/schemas/list.d.ts.map +1 -1
  109. package/dist/schemas/list.js +15 -6
  110. package/dist/schemas/list.js.map +1 -1
  111. package/dist/schemas/resource.d.ts +263 -17
  112. package/dist/schemas/resource.d.ts.map +1 -1
  113. package/dist/schemas/resource.js +19 -4
  114. package/dist/schemas/resource.js.map +1 -1
  115. package/dist/schemas/theme.d.ts +4 -0
  116. package/dist/schemas/theme.d.ts.map +1 -1
  117. package/dist/schemas/theme.js +1 -0
  118. package/dist/schemas/theme.js.map +1 -1
  119. package/dist/schemas/widget.d.ts +109 -0
  120. package/dist/schemas/widget.d.ts.map +1 -0
  121. package/dist/schemas/widget.js +74 -0
  122. package/dist/schemas/widget.js.map +1 -0
  123. package/dist/search.d.ts +51 -0
  124. package/dist/search.d.ts.map +1 -0
  125. package/dist/search.js +53 -0
  126. package/dist/search.js.map +1 -0
  127. package/dist/themes.d.ts +1 -1
  128. package/dist/transforms.d.ts +17 -0
  129. package/dist/transforms.d.ts.map +1 -0
  130. package/dist/transforms.js +34 -0
  131. package/dist/transforms.js.map +1 -0
  132. package/dist/validate.d.ts +5 -3
  133. package/dist/validate.d.ts.map +1 -1
  134. package/dist/validate.js +36 -2
  135. package/dist/validate.js.map +1 -1
  136. package/dist/values.d.ts +5 -1
  137. package/dist/values.d.ts.map +1 -1
  138. package/dist/values.js +16 -2
  139. package/dist/values.js.map +1 -1
  140. package/dist/widgets.d.ts +42 -0
  141. package/dist/widgets.d.ts.map +1 -0
  142. package/dist/widgets.js +130 -0
  143. package/dist/widgets.js.map +1 -0
  144. package/package.json +6 -3
  145. package/schema/boot.schema.json +713 -20
  146. package/schema/definition.schema.json +710 -20
  147. 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: "Not allowed.",
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
- "/media": {
261
- get: {
262
- operationId: "listMedia",
263
- parameters: listParameters,
264
- responses: {
265
- 200: ok("A page of media.", ref("MediaListResponse")),
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("Tags in use.", {
299
- type: "object",
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
- "/media/{id}": {
310
- parameters: [pathParameter("id", "Media id.")],
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: "replaceMediaFile",
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: true,
344
- content: { "multipart/form-data": { schema: {
362
+ required: false,
363
+ content: json({
345
364
  type: "object",
346
- required: ["file"],
347
- properties: { file: {
365
+ properties: { name: {
348
366
  type: "string",
349
- contentMediaType: "application/octet-stream"
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 media.", ref("MediaResponse")),
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
- type: "object",
382
- required: ["email", "password"],
383
- properties: {
384
- email: { type: "string" },
385
- password: { type: "string" },
386
- remember: { type: "boolean" }
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
- type: "object",
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
- parameters: [queryParameter("next", "Local path to go to after login.", { type: "string" })],
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 exists."),
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
- properties: {
462
- code: { type: "string" },
463
- recoveryCode: { type: "string" }
464
- }
533
+ required: ["password"],
534
+ properties: { password: { type: "string" } }
465
535
  })
466
536
  },
467
537
  responses: {
468
- 200: ok("Logged in.", ref("Session")),
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: "passkeyOptions",
474
- responses: { 200: ok("WebAuthn request options.", {
475
- type: "object",
476
- additionalProperties: true
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
- additionalProperties: true
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(values)
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("q", "Search terms.", { type: "string" }),
763
+ ...queryParameter("url", "The URL to embed.", { type: "string" }),
525
764
  required: true
526
765
  }],
527
766
  responses: {
528
- 200: ok("Results grouped by resource.", ref("SearchResponse")),
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. Its shape depends on the widget type.", {
538
- type: "object",
539
- additionalProperties: true
540
- }),
541
- ...problems(401, 403, 404)
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: { schemas: createComponentSchemas() }
790
+ }),
791
+ components: {
792
+ schemas: createComponentSchemas(),
793
+ parameters: { Context: contextHeader }
794
+ }
547
795
  };
548
796
  }
549
797
  //#endregion