@panneau/protocol 5.0.0-alpha.36 → 5.0.0-alpha.37

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 (57) hide show
  1. package/dist/aggregates.d.ts +135 -0
  2. package/dist/aggregates.d.ts.map +1 -0
  3. package/dist/aggregates.js +236 -0
  4. package/dist/aggregates.js.map +1 -0
  5. package/dist/conformance/index.d.ts.map +1 -1
  6. package/dist/conformance/index.js +201 -24
  7. package/dist/conformance/index.js.map +1 -1
  8. package/dist/dashboards.d.ts +95 -0
  9. package/dist/dashboards.d.ts.map +1 -0
  10. package/dist/dashboards.js +140 -0
  11. package/dist/dashboards.js.map +1 -0
  12. package/dist/index.js +8 -5
  13. package/dist/lint.d.ts.map +1 -1
  14. package/dist/lint.js +237 -15
  15. package/dist/lint.js.map +1 -1
  16. package/dist/mock/index.d.ts +27 -8
  17. package/dist/mock/index.d.ts.map +1 -1
  18. package/dist/mock/index.js +42 -6
  19. package/dist/mock/index.js.map +1 -1
  20. package/dist/openapi.d.ts.map +1 -1
  21. package/dist/openapi.js +77 -3
  22. package/dist/openapi.js.map +1 -1
  23. package/dist/periods.d.ts +49 -0
  24. package/dist/periods.d.ts.map +1 -0
  25. package/dist/periods.js +93 -0
  26. package/dist/periods.js.map +1 -0
  27. package/dist/runtime/index.d.ts +4 -1
  28. package/dist/runtime/index.d.ts.map +1 -1
  29. package/dist/runtime/index.js +5 -2
  30. package/dist/schemas/definition.d.ts +125 -0
  31. package/dist/schemas/definition.d.ts.map +1 -1
  32. package/dist/schemas/definition.js +8 -3
  33. package/dist/schemas/definition.js.map +1 -1
  34. package/dist/schemas/index.d.ts +277 -1
  35. package/dist/schemas/index.d.ts.map +1 -1
  36. package/dist/schemas/index.js +11 -5
  37. package/dist/schemas/index.js.map +1 -1
  38. package/dist/schemas/list.d.ts +11 -0
  39. package/dist/schemas/list.d.ts.map +1 -1
  40. package/dist/schemas/list.js +8 -2
  41. package/dist/schemas/list.js.map +1 -1
  42. package/dist/schemas/resource.d.ts +98 -0
  43. package/dist/schemas/resource.d.ts.map +1 -1
  44. package/dist/schemas/resource.js +9 -1
  45. package/dist/schemas/resource.js.map +1 -1
  46. package/dist/schemas/widget.d.ts +62 -2
  47. package/dist/schemas/widget.d.ts.map +1 -1
  48. package/dist/schemas/widget.js +36 -8
  49. package/dist/schemas/widget.js.map +1 -1
  50. package/dist/widgets.d.ts +48 -9
  51. package/dist/widgets.d.ts.map +1 -1
  52. package/dist/widgets.js +81 -10
  53. package/dist/widgets.js.map +1 -1
  54. package/package.json +1 -1
  55. package/schema/boot.schema.json +232 -66
  56. package/schema/definition.schema.json +232 -66
  57. package/schema/openapi.json +504 -7
@@ -3,10 +3,13 @@ import { CONTEXT_HEADER, CONTEXT_PROBLEM_TYPE } from "../constants.js";
3
3
  import { isEqual, isFilled } from "../values.js";
4
4
  import { getLinkTypes } from "../links.js";
5
5
  import { isCursorPage, toSearchParams } from "../query.js";
6
- import { getWidgetResource, isBuiltInWidgetType } from "../widgets.js";
6
+ import { followsPeriod, getWidgetResource, isBuiltInWidgetType } from "../widgets.js";
7
+ import { getAggregateWidgetType, nextPeriod, parseAggregateGroup, toAggregateParams } from "../aggregates.js";
8
+ import { getDefaultPeriod, getPeriodRange } from "../periods.js";
9
+ import { HOME_PAGE, getDashboardPages, getDashboardPeriod, getDashboardWidgets, getSummaryResources, getSummaryWidgets, toWidgetDataParams } from "../dashboards.js";
7
10
  import { isSearchableResource, toSearchQueryParams } from "../search.js";
8
11
  import { formatContextHeader } from "../context.js";
9
- import { widgetDataSchemas } from "../schemas/widget.js";
12
+ import { BreakdownWidgetData, SeriesWidgetData, StatWidgetData, widgetDataSchemas } from "../schemas/widget.js";
10
13
  import { Definition, User } from "../schemas/definition.js";
11
14
  import { ActionResult, ContextOptionsResponse, FieldCheckResponse, ItemResponse, ListResponse, Passkey, Problem, SearchResponse, TwoFactorStatus, UploadSignResponse, WebAuthnOptions } from "../schemas/api.js";
12
15
  import { z } from "zod";
@@ -56,6 +59,16 @@ var Check = class {
56
59
  this.skippedBecause = reason;
57
60
  }
58
61
  };
62
+ /** The points of a series: one per period, each on the first day of its period, going up. */
63
+ function expectPeriods(check, points, period, label) {
64
+ points.forEach((point, index) => {
65
+ const previous = points[index - 1];
66
+ if (previous !== void 0) {
67
+ const expected = nextPeriod(previous.date, period);
68
+ check.expect(point.date === expected, `${label}: after ${previous.date}, expected a point on ${expected}, got ${point.date}.`);
69
+ }
70
+ });
71
+ }
59
72
  /**
60
73
  * Runs the protocol's conformance checks against a live backend. Read-only checks always run;
61
74
  * checks that write data run only with `writes`.
@@ -669,55 +682,219 @@ async function runConformance(options) {
669
682
  if (failure !== null) check.expect(failure.errors?.[parameter] !== void 0, `${toSearchQueryParams(query)}: the 422 problem must have errors.${parameter}.`);
670
683
  }
671
684
  });
672
- const widgets = () => definition?.dashboard?.widgets ?? [];
685
+ const aggregated = () => (definition?.resources ?? []).filter((candidate) => candidate.list?.aggregates !== void 0 && candidate.abilities?.viewAny !== false);
686
+ const aggregate = (id, params) => request(`/resources/${encodeURIComponent(id)}/aggregate?${params.toString()}`);
687
+ await run("list.aggregate", "GET /resources/{resource}/aggregate answers the declared aggregates in the shape of a widget", async (check) => {
688
+ const resources = aggregated();
689
+ if (resources.length === 0) {
690
+ check.skip("No resource declares aggregates.");
691
+ return;
692
+ }
693
+ for (const current of resources) {
694
+ const aggregates = current.list?.aggregates ?? {};
695
+ const label = (params) => `The aggregate of "${current.id}" (${decodeURIComponent(params.toString())})`;
696
+ const fetchShape = async (params, schema) => {
697
+ const reply = await aggregate(current.id, params);
698
+ if (!check.expect(reply.status === 200, `${label(params)}: expected status 200, got ${reply.status}.`)) return null;
699
+ return check.expectSchema(schema, reply.body, label(params));
700
+ };
701
+ const count = await fetchShape(toAggregateParams({}), StatWidgetData);
702
+ const list = await request(`/resources/${encodeURIComponent(current.id)}?perPage=1`);
703
+ const total = list.status === 200 && ListResponse.safeParse(list.body).success ? list.body.meta.total : void 0;
704
+ if (count !== null && typeof total === "number") check.expect(count.value === total, `The count of "${current.id}" is ${count.value}; its list has ${total} items.`);
705
+ for (const field of aggregates.sum ?? []) await fetchShape(toAggregateParams({ measure: `sum:${field}` }), StatWidgetData);
706
+ for (const field of aggregates.groupBy ?? []) await fetchShape(toAggregateParams({ group: field }), BreakdownWidgetData);
707
+ for (const field of aggregates.dates ?? []) {
708
+ for (const period of [
709
+ "day",
710
+ "week",
711
+ "month"
712
+ ]) {
713
+ const params = toAggregateParams({ group: `${period}:${field}` });
714
+ const series = await fetchShape(params, SeriesWidgetData);
715
+ if (series === null) continue;
716
+ check.expect(series.period === period, `${label(params)}: expected the period ${period}, got ${series.period}.`);
717
+ expectPeriods(check, series.points, period, label(params));
718
+ }
719
+ if (current.list?.filters?.find((candidate) => candidate.id === field && candidate.type === "date-range") === void 0) continue;
720
+ const params = toAggregateParams({
721
+ filter: { [field]: {
722
+ from: "2026-01-01",
723
+ to: "2026-01-07"
724
+ } },
725
+ group: `day:${field}`
726
+ });
727
+ const series = await fetchShape(params, SeriesWidgetData);
728
+ if (series !== null) {
729
+ const dates = series.points.map((point) => point.date);
730
+ check.expect(dates.length === 7 && dates[0] === "2026-01-01" && dates[6] === "2026-01-07", `${label(params)}: expected a point per day from 2026-01-01 to 2026-01-07, got ${dates.length > 0 ? `${dates[0]} to ${dates.at(-1)}` : "none"}.`);
731
+ }
732
+ }
733
+ }
734
+ });
735
+ await run("list.aggregate.invalid", "GET /resources/{resource}/aggregate refuses undeclared fields and bad measures or groups with a 422", async (check) => {
736
+ const resources = aggregated();
737
+ if (resources.length === 0) {
738
+ check.skip("No resource declares aggregates.");
739
+ return;
740
+ }
741
+ for (const current of resources) {
742
+ const date = current.list?.aggregates?.dates?.[0] ?? "created_at";
743
+ const invalid = [
744
+ [{ measure: "average" }, "measure"],
745
+ [{ measure: `sum:${UNKNOWN}` }, "measure"],
746
+ [{ group: UNKNOWN }, "group"],
747
+ [{ group: `day:${UNKNOWN}` }, "group"],
748
+ [{ group: `year:${date}` }, "group"]
749
+ ];
750
+ for (const [params, key] of invalid) {
751
+ const reply = await aggregate(current.id, new URLSearchParams(params));
752
+ const refused = check.expectProblem(reply, 422);
753
+ if (refused !== null) check.expect(refused.errors?.[key] !== void 0, `The aggregate of "${current.id}" with ${new URLSearchParams(params).toString()}: expected errors on "${key}".`);
754
+ }
755
+ }
756
+ const without = (definition?.resources ?? []).find((candidate) => candidate.list?.aggregates === void 0 && candidate.abilities?.viewAny !== false);
757
+ if (without !== void 0) check.expectProblem(await aggregate(without.id, toAggregateParams({})), 404);
758
+ });
759
+ const dashboardPages = () => {
760
+ const current = definition;
761
+ return current !== null ? getDashboardPages(current) : [];
762
+ };
763
+ const summaryResources = () => {
764
+ const current = definition;
765
+ return current !== null ? getSummaryResources(current) : [];
766
+ };
767
+ const widgets = () => [...dashboardPages().flatMap((page) => getDashboardWidgets(definition, page).map((widget) => ({
768
+ place: { page },
769
+ widget
770
+ }))), ...summaryResources().flatMap((resource) => getSummaryWidgets(definition, resource).map((widget) => ({
771
+ place: { resource },
772
+ widget
773
+ })))];
774
+ const widgetPath = (id, place) => {
775
+ const search = toWidgetDataParams(place).toString();
776
+ return `/dashboard/widgets/${encodeURIComponent(id)}${search !== "" ? `?${search}` : ""}`;
777
+ };
778
+ const placeName = (place) => place.resource !== void 0 ? `the summary of "${place.resource}"` : place.page !== "home" ? `the page "${place.page}"` : "the home page";
779
+ const widgetName = (id, place) => place.resource !== void 0 || place.page !== "home" ? `"${id}" of ${placeName(place)}` : `"${id}"`;
673
780
  await run("dashboard.widgets", "GET /dashboard/widgets/{widget} answers each widget in the shape of its type", async (check) => {
674
- const own = widgets().filter((widget) => getWidgetResource(widget) === null);
781
+ const own = widgets().filter(({ widget }) => getWidgetResource(widget) === null);
675
782
  if (own.length === 0) {
676
- check.skip("The dashboard has no widget with data of its own.");
783
+ check.skip("No dashboard or summary has a widget with data of its own.");
677
784
  return;
678
785
  }
679
- for (const widget of own) {
680
- const reply = await request(`/dashboard/widgets/${encodeURIComponent(widget.id)}`);
786
+ for (const { place, widget } of own) {
787
+ const name = widgetName(widget.id, place);
788
+ const reply = await request(widgetPath(widget.id, place));
681
789
  if (reply.status === 403) {
682
790
  check.expectProblem(reply, 403);
683
791
  continue;
684
792
  }
685
- if (!check.expect(reply.status === 200, `Widget "${widget.id}": expected status 200, got ${reply.status}.`)) continue;
686
- if (isBuiltInWidgetType(widget.type)) check.expectSchema(widgetDataSchemas[widget.type], reply.body, `The data of the ${widget.type} "${widget.id}"`);
687
- else check.expect(reply.body !== null && typeof reply.body === "object" && !Array.isArray(reply.body), `The data of the widget "${widget.id}" must be an object.`);
793
+ if (!check.expect(reply.status === 200, `Widget ${name}: expected status 200, got ${reply.status}.`)) continue;
794
+ if (isBuiltInWidgetType(widget.type)) check.expectSchema(widgetDataSchemas[widget.type], reply.body, `The data of the ${widget.type} ${name}`);
795
+ else check.expect(reply.body !== null && typeof reply.body === "object" && !Array.isArray(reply.body), `The data of the widget ${name} must be an object.`);
688
796
  }
689
797
  });
690
- await run("dashboard.widgets.resource", "The lists of the widgets on a resource answer their query, with a total for a stat", async (check) => {
691
- const onResource = widgets().flatMap((widget) => {
798
+ await run("dashboard.widgets.resource", "The lists and the aggregates of the widgets on a resource answer their query, with a total for a stat", async (check) => {
799
+ const onResource = widgets().flatMap(({ place, widget }) => {
692
800
  const read = getWidgetResource(widget);
693
801
  return read !== null ? [{
802
+ place,
694
803
  widget,
695
804
  read
696
805
  }] : [];
697
806
  });
698
807
  if (onResource.length === 0) {
699
- check.skip("The dashboard has no widget on a resource.");
808
+ check.skip("No dashboard or summary has a widget on a resource.");
809
+ return;
810
+ }
811
+ for (const { place, widget, read } of onResource) {
812
+ const name = widgetName(widget.id, place);
813
+ const reads = read.aggregate !== null ? "aggregate" : "list";
814
+ const params = read.aggregate !== null ? toAggregateParams({
815
+ ...read.query,
816
+ ...read.aggregate
817
+ }) : new URLSearchParams(read.params);
818
+ if (read.aggregate === null) params.set("perPage", widget.type === "stat" ? "1" : String(5));
819
+ const reply = await request(`/resources/${encodeURIComponent(read.resource)}${read.aggregate !== null ? "/aggregate" : ""}?${params.toString()}`);
820
+ if (reply.status === 403) {
821
+ check.expectProblem(reply, 403);
822
+ continue;
823
+ }
824
+ if (!check.expect(reply.status === 200, `Widget ${name}: expected status 200 from its ${reads}, got ${reply.status}.`)) continue;
825
+ if (read.aggregate !== null) {
826
+ const type = getAggregateWidgetType(read.aggregate.group !== null ? parseAggregateGroup(read.aggregate.group) : null);
827
+ check.expect(type === widget.type, `The ${widget.type} ${name} reads aggregates in the shape of a ${type}.`);
828
+ check.expectSchema(widgetDataSchemas[type], reply.body, `The aggregate of the widget ${name}`);
829
+ continue;
830
+ }
831
+ const list = check.expectSchema(ListResponse, reply.body, `The list of the widget ${name}`);
832
+ if (list !== null && widget.type === "stat") check.expect(typeof list.meta.total === "number", `The list of the stat ${name} has no meta.total to count.`);
833
+ }
834
+ });
835
+ const placePeriod = (place) => {
836
+ const current = definition;
837
+ return place.resource !== void 0 ? current.resources.find(({ id }) => id === place.resource)?.summary?.period : getDashboardPeriod(current, place.page);
838
+ };
839
+ await run("dashboard.widgets.period", "GET /dashboard/widgets/{widget} answers the widgets that follow the period of their overview with its parameters", async (check) => {
840
+ const following = widgets().flatMap(({ place, widget }) => {
841
+ const period = placePeriod(place);
842
+ const option = period !== void 0 ? getDefaultPeriod(period) : null;
843
+ return getWidgetResource(widget) === null && option !== null && followsPeriod(widget, place.resource) ? [{
844
+ place,
845
+ widget,
846
+ period: {
847
+ option,
848
+ ...getPeriodRange(option)
849
+ }
850
+ }] : [];
851
+ });
852
+ const first = following[0];
853
+ if (first === void 0) {
854
+ check.skip("No dashboard or summary with a period has a widget with data of its own that follows it.");
700
855
  return;
701
856
  }
702
- for (const { widget, read } of onResource) {
703
- const params = new URLSearchParams(read.params);
704
- params.set("perPage", widget.type === "stat" ? "1" : String(5));
705
- const reply = await request(`/resources/${encodeURIComponent(read.resource)}?${params.toString()}`);
857
+ for (const { place, widget, period } of following) {
858
+ const name = widgetName(widget.id, place);
859
+ const reply = await request(widgetPath(widget.id, {
860
+ ...place,
861
+ period
862
+ }));
706
863
  if (reply.status === 403) {
707
864
  check.expectProblem(reply, 403);
708
865
  continue;
709
866
  }
710
- if (!check.expect(reply.status === 200, `Widget "${widget.id}": expected status 200, got ${reply.status}.`)) continue;
711
- const list = check.expectSchema(ListResponse, reply.body, `The list of the widget "${widget.id}"`);
712
- if (list !== null && widget.type === "stat") check.expect(typeof list.meta.total === "number", `The list of the stat "${widget.id}" has no meta.total to count.`);
867
+ if (check.expect(reply.status === 200, `Widget ${name} for the period ${period.option}: expected status 200, got ${reply.status}.`) && isBuiltInWidgetType(widget.type)) check.expectSchema(widgetDataSchemas[widget.type], reply.body, `The data of the ${widget.type} ${name} for the period ${period.option}`);
713
868
  }
869
+ const wrong = await request(`${widgetPath(first.widget.id, first.place)}${first.place.resource !== void 0 || first.place.page !== "home" ? "&" : "?"}period%5Boption%5D=decade&period%5Bfrom%5D=2026-01-01&period%5Bto%5D=2026-12-31`);
870
+ if (check.expect(wrong.status === 422, `Widget ${widgetName(first.widget.id, first.place)} for the period "decade": expected status 422, got ${wrong.status}.`)) check.expectProblem(wrong, 422);
714
871
  });
715
- await run("dashboard.widgets.unknown", "A widget that is not in the dashboard of the user is a 404 problem", async (check) => {
716
- if (definition?.dashboard === void 0) {
717
- check.skip("The definition has no dashboard.");
872
+ await run("dashboard.widgets.unknown", "A widget that is not on a dashboard page or in a summary of the user is a 404 problem", async (check) => {
873
+ const pages = dashboardPages();
874
+ const summaries = summaryResources();
875
+ if (pages.length === 0 && summaries.length === 0) {
876
+ check.skip("The definition has no dashboard and no summary.");
718
877
  return;
719
878
  }
720
- check.expectProblem(await request(`/dashboard/widgets/${UNKNOWN}`), 404);
879
+ const expectStatus = async (path, what, status) => {
880
+ const reply = await request(path);
881
+ if (check.expect(reply.status === status, `${what}: expected status ${status}, got ${reply.status}.`)) check.expectProblem(reply, status);
882
+ };
883
+ const expectMissing = (path, what) => expectStatus(path, what, 404);
884
+ const places = [...pages.map((page) => ({ page })), ...summaries.map((resource) => ({ resource }))];
885
+ for (const place of places) await expectMissing(widgetPath(UNKNOWN, place), `An unknown widget of ${placeName(place)}`);
886
+ const all = widgets().sort((a, b) => Number(getWidgetResource(a.widget) !== null) - Number(getWidgetResource(b.widget) !== null));
887
+ const first = all[0];
888
+ if (first === void 0) return;
889
+ const summarized = all.find(({ place, widget }) => place.resource !== void 0 && getWidgetResource(widget) === null);
890
+ if (summarized?.place.resource !== void 0) await expectStatus(`${widgetPath(summarized.widget.id, summarized.place)}&page=${HOME_PAGE}`, `Widget ${widgetName(summarized.widget.id, summarized.place)} with both a page and a resource`, 422);
891
+ if (places.length === 1 && first.place.page === "home") return;
892
+ await expectMissing(`/dashboard/widgets/${encodeURIComponent(first.widget.id)}?page=${UNKNOWN}`, `Widget ${widgetName(first.widget.id, first.place)} on an unknown page`);
893
+ for (const place of places) {
894
+ const ids = new Set((place.resource !== void 0 ? getSummaryWidgets(definition, place.resource) : getDashboardWidgets(definition, place.page)).map(({ id }) => id));
895
+ const elsewhere = all.find(({ widget }) => !ids.has(widget.id));
896
+ if (elsewhere !== void 0) await expectMissing(widgetPath(elsewhere.widget.id, place), `Widget ${widgetName(elsewhere.widget.id, elsewhere.place)} on ${placeName(place)}`);
897
+ }
721
898
  });
722
899
  const writes = options.writes;
723
900
  let createdId = null;