@cosmicdrift/kumiko-framework 0.410.0 → 0.412.0

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 (68) hide show
  1. package/agents/api/framework-db.md +1 -1
  2. package/agents/api/framework-engine.md +50 -1
  3. package/agents/api/framework-errors.md +2 -0
  4. package/agents/api/framework-ui-types.md +10 -0
  5. package/agents/api/renderer-web.md +113 -10
  6. package/agents/api/types.md +30 -0
  7. package/agents/api.md +3 -3
  8. package/agents/boot-rules.md +4 -0
  9. package/agents/examples/api-docs.md +702 -0
  10. package/agents/examples/realtime-sse.md +37 -2
  11. package/agents/examples/record-detail-layout.md +35 -2
  12. package/agents/examples/wizard-form.md +96 -5
  13. package/agents/examples.md +1 -0
  14. package/agents/features.md +6 -0
  15. package/agents/widgets.md +6 -0
  16. package/dist/api/auth-middleware.d.ts +1 -0
  17. package/dist/api/index.d.ts +3 -0
  18. package/dist/api/index.js +3 -0
  19. package/dist/api/pat-auth-reject.d.ts +7 -0
  20. package/dist/api/pat-auth-reject.js +7 -0
  21. package/dist/api/server-middleware.js +2 -1
  22. package/dist/compliance/sub-processors.js +2 -2
  23. package/dist/config/index.d.ts +25 -0
  24. package/dist/config/index.js +28 -1
  25. package/dist/db/event-store-executor-read-paging.d.ts +1 -0
  26. package/dist/db/event-store-executor-read-paging.js +2 -1
  27. package/dist/db/queries/session-advisory-lock.js +3 -0
  28. package/dist/db/read-gate-clause.js +26 -7
  29. package/dist/db/table-builder.d.ts +1 -2
  30. package/dist/engine/boot-validator/boot-rules.d.ts +20 -0
  31. package/dist/engine/boot-validator/list-table-options.js +1 -0
  32. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +15 -0
  33. package/dist/engine/boot-validator/screens-forms-layout-rules.js +15 -0
  34. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  35. package/dist/engine/boot-validator/screens-forms.js +60 -3
  36. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  37. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  38. package/dist/engine/boot-validator/screens-kind-projection-detail.js +19 -0
  39. package/dist/engine/boot-validator/screens-lists.js +2 -2
  40. package/dist/engine/define-feature.js +3 -0
  41. package/dist/engine/entity-list-runtime-options.js +12 -0
  42. package/dist/engine/factories.d.ts +2 -0
  43. package/dist/engine/feature-builder-state.d.ts +2 -1
  44. package/dist/engine/feature-builder-state.js +1 -0
  45. package/dist/engine/index.d.ts +5 -2
  46. package/dist/engine/index.js +4 -1
  47. package/dist/engine/project-app-schema-for-roles.js +11 -10
  48. package/dist/engine/registry-facade.js +13 -0
  49. package/dist/engine/screen-helpers.d.ts +1 -0
  50. package/dist/engine/screen-helpers.js +1 -1
  51. package/dist/engine/webhook-contracts.d.ts +12 -0
  52. package/dist/engine/webhook-contracts.js +172 -0
  53. package/dist/engine/webhook-events.d.ts +34 -0
  54. package/dist/engine/webhook-events.js +71 -0
  55. package/dist/errors/docs-url.js +2 -19
  56. package/dist/errors/error-codes.d.ts +20 -0
  57. package/dist/errors/error-codes.js +19 -0
  58. package/dist/errors/index.d.ts +2 -0
  59. package/dist/errors/index.js +1 -0
  60. package/dist/i18n/required-surface-keys.d.ts +4 -0
  61. package/dist/i18n/required-surface-keys.js +15 -0
  62. package/dist/pipeline/context-services.d.ts +1 -0
  63. package/dist/pipeline/context-services.js +1 -0
  64. package/dist/pipeline/handler-context-scope.js +5 -1
  65. package/dist/pipeline/user-live-signals.d.ts +5 -0
  66. package/dist/pipeline/user-live-signals.js +20 -0
  67. package/package.json +3 -3
  68. package/src/changes.json +78 -0
@@ -957,6 +957,21 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
957
957
  readonly summary: "Every wizard section has a non-empty title.";
958
958
  readonly fix: "Give each wizard section a title.";
959
959
  };
960
+ readonly wizardOptionWithoutWizard: {
961
+ readonly id: "form/wizard-option-without-wizard";
962
+ readonly summary: "layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout.";
963
+ readonly fix: 'Remove the option or set mode: "wizard".';
964
+ };
965
+ readonly wizardSummaryFieldUnknown: {
966
+ readonly id: "form/wizard-summary-field-unknown";
967
+ readonly summary: "A wizard section summaryField names a field of that section.";
968
+ readonly fix: "Use a field name declared in the section.";
969
+ };
970
+ readonly wizardSubmitConditionFieldUnknown: {
971
+ readonly id: "form/wizard-submit-condition-field-unknown";
972
+ readonly summary: "layout.wizard.submitDisabledWhen names a field of the layout.";
973
+ readonly fix: "Use a field name declared in one of the sections.";
974
+ };
960
975
  readonly sectionFieldsAndGroups: {
961
976
  readonly id: "form/section-fields-and-groups";
962
977
  readonly summary: "A section declares fields or groups, not both.";
@@ -1270,6 +1285,11 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1270
1285
  readonly summary: "A metric navigate.tab names a section id of the screen.";
1271
1286
  readonly fix: "Navigate to an existing section id or remove navigate.tab.";
1272
1287
  };
1288
+ readonly actionShowOnTabsInvalid: {
1289
+ readonly id: "projection-detail/action-show-on-tabs-invalid";
1290
+ readonly summary: 'A header action showOnTabs is non-empty, names section ids of the screen and needs layout.mode "tabs".';
1291
+ readonly fix: "List existing section ids or remove showOnTabs.";
1292
+ };
1273
1293
  readonly metricLabelMissing: {
1274
1294
  readonly id: "projection-detail/metric-label-missing";
1275
1295
  readonly summary: "Every metric has an i18n label key.";
@@ -14,6 +14,7 @@ const BOOLEAN_OPTION_KEYS = [
14
14
  "pinning",
15
15
  "resizing",
16
16
  "keyboardNavigation",
17
+ "compactHeader",
17
18
  ];
18
19
  function validateDensity(where, density) {
19
20
  if (!isPlainObject(density)) {
@@ -49,6 +49,21 @@ export declare const FORM_LAYOUT_RULES: {
49
49
  readonly summary: "Every wizard section has a non-empty title.";
50
50
  readonly fix: "Give each wizard section a title.";
51
51
  };
52
+ readonly wizardOptionWithoutWizard: {
53
+ readonly id: "form/wizard-option-without-wizard";
54
+ readonly summary: "layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout.";
55
+ readonly fix: 'Remove the option or set mode: "wizard".';
56
+ };
57
+ readonly wizardSummaryFieldUnknown: {
58
+ readonly id: "form/wizard-summary-field-unknown";
59
+ readonly summary: "A wizard section summaryField names a field of that section.";
60
+ readonly fix: "Use a field name declared in the section.";
61
+ };
62
+ readonly wizardSubmitConditionFieldUnknown: {
63
+ readonly id: "form/wizard-submit-condition-field-unknown";
64
+ readonly summary: "layout.wizard.submitDisabledWhen names a field of the layout.";
65
+ readonly fix: "Use a field name declared in one of the sections.";
66
+ };
52
67
  readonly sectionFieldsAndGroups: {
53
68
  readonly id: "form/section-fields-and-groups";
54
69
  readonly summary: "A section declares fields or groups, not both.";
@@ -49,6 +49,21 @@ export const FORM_LAYOUT_RULES = {
49
49
  summary: "Every wizard section has a non-empty title.",
50
50
  fix: "Give each wizard section a title.",
51
51
  },
52
+ wizardOptionWithoutWizard: {
53
+ id: "form/wizard-option-without-wizard",
54
+ summary: "layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout.",
55
+ fix: 'Remove the option or set mode: "wizard".',
56
+ },
57
+ wizardSummaryFieldUnknown: {
58
+ id: "form/wizard-summary-field-unknown",
59
+ summary: "A wizard section summaryField names a field of that section.",
60
+ fix: "Use a field name declared in the section.",
61
+ },
62
+ wizardSubmitConditionFieldUnknown: {
63
+ id: "form/wizard-submit-condition-field-unknown",
64
+ summary: "layout.wizard.submitDisabledWhen names a field of the layout.",
65
+ fix: "Use a field name declared in one of the sections.",
66
+ },
52
67
  sectionFieldsAndGroups: {
53
68
  id: "form/section-fields-and-groups",
54
69
  summary: "A section declares fields or groups, not both.",
@@ -13,7 +13,7 @@ export declare function validateTabSections(featureName: string, screenId: strin
13
13
  readonly id?: string;
14
14
  readonly title?: string;
15
15
  }[]): void;
16
- export declare function validateWizardLayout(featureName: string, screenId: string, screenType: "entityEdit" | "actionForm" | "configEdit" | "secretMint", layout: EditLayout, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
16
+ export declare function validateWizardLayout(featureName: string, screenId: string, screenType: "entityEdit" | "actionForm" | "configEdit" | "secretMint", layout: EditLayout, featureMap: ReadonlyMap<string, FeatureDefinition>, inlineFieldNames?: ReadonlySet<string>): void;
17
17
  export declare function isWriteOnlyField(fdef: FieldDefinition | undefined): boolean;
18
18
  export declare function validateConfigEditSecretField(featureName: string, screen: ConfigEditScreenDefinition, fieldName: string, secretQn: string, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
19
19
  export declare function rejectWriteOnlyFormField(featureName: string, screenId: string, context: string, fieldName: string, fdef: FieldDefinition): void;
@@ -1,6 +1,6 @@
1
1
  import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
2
2
  import { isKebabSegment } from "../qualified-name.js";
3
- import { isExtensionEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
3
+ import { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
4
4
  import { bootRuleError } from "./boot-rule.js";
5
5
  import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
6
6
  import { assertWriteHandlerRegistered, isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
@@ -189,10 +189,66 @@ export function validateTabSections(featureName, screenId, screenType, sections)
189
189
  tabIds.add(section.id);
190
190
  });
191
191
  }
192
+ // An actionForm's own `fields` count too: extension steps (a wizard with no fields section) keep their values there.
193
+ function wizardFieldNames(layout, inlineFieldNames) {
194
+ const names = new Set(inlineFieldNames);
195
+ for (const section of layout.sections) {
196
+ if (!isFieldsEditSection(section))
197
+ continue;
198
+ for (const spec of sectionFieldSpecs(section))
199
+ names.add(normalizeEditField(spec).field);
200
+ }
201
+ return names;
202
+ }
203
+ function usesWizardOption(layout) {
204
+ const wizard = layout.wizard;
205
+ return (wizard?.saveAndCloseOnCreate !== undefined ||
206
+ wizard?.submitDisabledWhen !== undefined ||
207
+ wizard?.aside?.finishDescription !== undefined ||
208
+ layout.sections.some((section) => (isFieldsEditSection(section) || section.kind === "extension") &&
209
+ section.summaryField !== undefined));
210
+ }
211
+ function validateWizardOptions(featureName, screenId, screenType, layout, inlineFieldNames) {
212
+ const where = `[Feature ${featureName}] Screen "${screenId}" (${screenType})`;
213
+ const wizard = layout.wizard;
214
+ if (layout.mode !== "wizard") {
215
+ if (usesWizardOption(layout)) {
216
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardOptionWithoutWizard, {
217
+ message: `${where} sets a wizard-only layout option but mode is not "wizard". Remove it or set mode: "wizard".`,
218
+ });
219
+ }
220
+ // skip: the remaining checks only apply to wizards
221
+ return;
222
+ }
223
+ const allFieldNames = wizardFieldNames(layout, inlineFieldNames);
224
+ for (const section of layout.sections) {
225
+ if (section.kind === "extension" &&
226
+ section.summaryField !== undefined &&
227
+ !allFieldNames.has(section.summaryField)) {
228
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardSummaryFieldUnknown, {
229
+ message: `${where} extension section "${section.title}" sets summaryField "${section.summaryField}", which is not a field of the screen. Use a field name declared in the screen's fields or a fields section.`,
230
+ });
231
+ }
232
+ if (!isFieldsEditSection(section))
233
+ continue;
234
+ const sectionFieldNames = sectionFieldSpecs(section).map((spec) => normalizeEditField(spec).field);
235
+ if (section.summaryField !== undefined && !sectionFieldNames.includes(section.summaryField)) {
236
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardSummaryFieldUnknown, {
237
+ message: `${where} section "${section.title ?? ""}" sets summaryField "${section.summaryField}", which is not a field of that section. Use a field name declared in the section.`,
238
+ });
239
+ }
240
+ }
241
+ const condition = wizard?.submitDisabledWhen;
242
+ if (typeof condition === "object" && !allFieldNames.has(condition.field)) {
243
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardSubmitConditionFieldUnknown, {
244
+ message: `${where} layout.wizard.submitDisabledWhen names field "${condition.field}", which no section declares. Use a field name declared in one of the sections.`,
245
+ });
246
+ }
247
+ }
192
248
  // Wizard layouts (mode: "wizard") need >= 2 titled sections — a single or
193
249
  // untitled step would leave the progress indicator blank, so both fail at
194
250
  // boot rather than as a broken step UI.
195
- export function validateWizardLayout(featureName, screenId, screenType, layout, featureMap) {
251
+ export function validateWizardLayout(featureName, screenId, screenType, layout, featureMap, inlineFieldNames) {
196
252
  // entityEdit renders tabs like wizard steps: every section stays mounted,
197
253
  // submit validates across all of them, and a field error jumps to the tab
198
254
  // holding it. The other three have no such jump — actionForm and
@@ -227,6 +283,7 @@ export function validateWizardLayout(featureName, screenId, screenType, layout,
227
283
  });
228
284
  }
229
285
  }
286
+ validateWizardOptions(featureName, screenId, screenType, layout, inlineFieldNames);
230
287
  // skip: mode omitted/"single" — no wizard constraints apply.
231
288
  if (layout.mode !== "wizard")
232
289
  return;
@@ -584,7 +641,7 @@ export function validateInlineFormScreen(feature, screenId, screen, kind, allWri
584
641
  const allowEmptyMintForm = kind === "secretMint";
585
642
  const fieldNames = validateFormFieldsMap(feature.name, screenId, kind, screen.fields, allowEmptyMintForm);
586
643
  validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, screen.fields, allowEmptyMintForm && fieldNames.size === 0);
587
- validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap);
644
+ validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap, fieldNames);
588
645
  if (screen.type === "actionForm") {
589
646
  validateFormDerivations(feature.name, screenId, screen);
590
647
  validateFormDerivationsEnforced(feature.name, screenId, screen, featureMap);
@@ -24,6 +24,11 @@ export declare const PROJECTION_DETAIL_RULES: {
24
24
  readonly summary: "A metric navigate.tab names a section id of the screen.";
25
25
  readonly fix: "Navigate to an existing section id or remove navigate.tab.";
26
26
  };
27
+ readonly actionShowOnTabsInvalid: {
28
+ readonly id: "projection-detail/action-show-on-tabs-invalid";
29
+ readonly summary: 'A header action showOnTabs is non-empty, names section ids of the screen and needs layout.mode "tabs".';
30
+ readonly fix: "List existing section ids or remove showOnTabs.";
31
+ };
27
32
  readonly metricLabelMissing: {
28
33
  readonly id: "projection-detail/metric-label-missing";
29
34
  readonly summary: "Every metric has an i18n label key.";
@@ -24,6 +24,11 @@ export const PROJECTION_DETAIL_RULES = {
24
24
  summary: "A metric navigate.tab names a section id of the screen.",
25
25
  fix: "Navigate to an existing section id or remove navigate.tab.",
26
26
  },
27
+ actionShowOnTabsInvalid: {
28
+ id: "projection-detail/action-show-on-tabs-invalid",
29
+ summary: 'A header action showOnTabs is non-empty, names section ids of the screen and needs layout.mode "tabs".',
30
+ fix: "List existing section ids or remove showOnTabs.",
31
+ },
27
32
  metricLabelMissing: {
28
33
  id: "projection-detail/metric-label-missing",
29
34
  summary: "Every metric has an i18n label key.",
@@ -255,6 +255,24 @@ function validateProjectionDetailSection(ctx, screenId, screen, section) {
255
255
  validateProjectionDetailFieldsSection(ctx, screenId, section);
256
256
  }
257
257
  }
258
+ function validateHeaderActionShowOnTabs(featureName, screenId, screen, action) {
259
+ // skip: no showOnTabs declared, the action is shown on every tab
260
+ if (action.showOnTabs === undefined)
261
+ return;
262
+ const sectionIds = screen.layout.sections.map((section) => section.id);
263
+ const unknownTab = action.showOnTabs.find((tab) => !sectionIds.includes(tab));
264
+ if (screen.layout.mode !== "tabs" || action.showOnTabs.length === 0 || unknownTab !== undefined) {
265
+ throw bootRuleError(PROJECTION_DETAIL_RULES.actionShowOnTabsInvalid, {
266
+ message: `[Feature ${featureName}] Screen "${screenId}" (projectionDetail) action "${action.id}" ` +
267
+ `sets showOnTabs ${JSON.stringify(action.showOnTabs)}` +
268
+ (unknownTab !== undefined
269
+ ? `, but "${unknownTab}" is not a section id on this screen`
270
+ : "") +
271
+ (screen.layout.mode !== "tabs" ? ` — showOnTabs needs layout.mode "tabs"` : "") +
272
+ `. List existing section ids (at least one) or remove showOnTabs.`,
273
+ });
274
+ }
275
+ }
258
276
  // Query-driven like projectionList, but a single row plus layout instead of
259
277
  // columns. No entity check is possible: fields resolve against the query
260
278
  // response at render time, not against an entity.
@@ -277,5 +295,6 @@ export function validateProjectionDetailScreen(ctx, screenId, screen) {
277
295
  for (const action of screen.actions ?? []) {
278
296
  validateActionHasIcon(featureName, screenId, "projectionDetail", "action", action);
279
297
  validateRecordHeaderAction(ctx, screenId, "projectionDetail", screen.detailFor, action);
298
+ validateHeaderActionShowOnTabs(featureName, screenId, screen, action);
280
299
  }
281
300
  }
@@ -3,7 +3,7 @@ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
3
3
  import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
4
4
  import { parseRefTarget } from "../parse-ref-target.js";
5
5
  import { qualifyEntityName } from "../qualified-name.js";
6
- import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, } from "../screen-helpers.js";
6
+ import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, screenShortId, } from "../screen-helpers.js";
7
7
  import { bootRuleError } from "./boot-rule.js";
8
8
  import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
9
9
  import { validateListBulkActions } from "./list-bulk-actions.js";
@@ -46,7 +46,7 @@ export function validateExplicitListScreenExists(featureName, screenId, screen,
46
46
  // skip: no explicit listScreenId, the nav heuristic applies and there is nothing to validate
47
47
  if (listScreenId === undefined)
48
48
  return;
49
- const shortId = listScreenId.slice(listScreenId.lastIndexOf(":") + 1);
49
+ const shortId = screenShortId(listScreenId);
50
50
  // skip: the explicit listScreenId resolves to a mounted screen
51
51
  if (screensByShortId.has(shortId))
52
52
  return;
@@ -4,6 +4,7 @@ import { buildEntityHandlerMethods } from "./feature-entity-handlers.js";
4
4
  import { buildProbeMethods } from "./feature-probes.js";
5
5
  import { buildUiExtensionsMethods } from "./feature-ui-extensions.js";
6
6
  import { isObjectArgument, throwObjectArgumentRequired, unwrapArrayForm } from "./object-form.js";
7
+ import { buildWebhookEventMethods } from "./webhook-events.js";
7
8
  // `TExports` lets the setup callback hand back a typed object that
8
9
  // downstream features can import (e.g. `tenantFeature.exports.config`). The
9
10
  // runtime always packs whatever setup returns into `featureDef.exports` —
@@ -89,6 +90,7 @@ export function defineFeature(name, setup, settings) {
89
90
  },
90
91
  ...buildEntityHandlerMethods(state, name),
91
92
  ...buildConfigEventsJobsMethods(state, name),
93
+ ...buildWebhookEventMethods(state, name),
92
94
  ...buildUiExtensionsMethods(state, name),
93
95
  ...buildProbeMethods(state, name),
94
96
  };
@@ -143,6 +145,7 @@ export function defineFeature(name, setup, settings) {
143
145
  bootChecks: state.bootChecks,
144
146
  referenceData: state.referenceData,
145
147
  events: state.events,
148
+ ...(Object.keys(state.webhookEvents).length > 0 && { webhookEvents: state.webhookEvents }),
146
149
  eventMigrations: state.eventMigrations,
147
150
  configReads: state.configReads,
148
151
  handlerEntityMappings: state.handlerEntityMappings,
@@ -26,6 +26,17 @@ function readTableOf(ctx, entityName, entity) {
26
26
  .find((projection) => projection.name.endsWith(`:projection:${entityName}${IMPLICIT_PROJECTION_SUFFIX}`));
27
27
  return implicit?.table ?? buildEntityTable(entityName, entity);
28
28
  }
29
+ const readModelOwnersOf = memoizePerRegistry((registry) => {
30
+ const owners = new Map();
31
+ for (const { source, table } of registry.getAllProjections().values()) {
32
+ if (typeof source !== "string")
33
+ continue;
34
+ const entity = registry.getReadModelEntity(source);
35
+ if (entity !== undefined)
36
+ owners.set(source, { entity, table });
37
+ }
38
+ return owners;
39
+ });
29
40
  function readTableResolver(ctx, label) {
30
41
  return (name) => {
31
42
  const entity = ctx.registry.getEntity(name);
@@ -40,6 +51,7 @@ export function parentVisibilityFor(ctx, user) {
40
51
  const detailRules = detailAccessOf(ctx.registry);
41
52
  return {
42
53
  entities: ctx.registry.getAllEntities(),
54
+ readModelEntities: readModelOwnersOf(ctx.registry),
43
55
  canReadEntity: (name) => {
44
56
  const rule = detailRules.get(name);
45
57
  return rule !== undefined && hasAccess(user, rule);
@@ -192,6 +192,8 @@ export declare function createEntity<const F, const T extends EntityTenancy = "t
192
192
  /** Event stream lives on SYSTEM_TENANT_ID (tenant-independent aggregate, e.g.
193
193
  * user) instead of the creator's tenant. See EntityDefinition.systemStream. */
194
194
  readonly systemStream?: boolean;
195
+ /** See EntityDefinition.webhookEvents. */
196
+ readonly webhookEvents?: boolean;
195
197
  readonly eventVersion?: number;
196
198
  readonly eventMigrations?: EntityDefinition["eventMigrations"];
197
199
  readonly searchWeight?: number;
@@ -1,5 +1,5 @@
1
1
  import type { ConfigKeyDefinition, ConfigSeedDef, ExtensionSelectorDef, JobDefinition, NotificationDefinition, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TranslationKeys } from "@cosmicdrift/kumiko-types/config";
2
- import type { BootCheckFn, FeatureMetricDef, SecretKeyDefinition, SecretNamespaceDefinition, StoreTableEntry, UiHints } from "@cosmicdrift/kumiko-types/feature";
2
+ import type { BootCheckFn, FeatureMetricDef, SecretKeyDefinition, SecretNamespaceDefinition, StoreTableEntry, UiHints, WebhookEventDef } from "@cosmicdrift/kumiko-types/feature";
3
3
  import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
4
4
  import type { AuthClaimsFn, ClaimKeyDefinition, EventDef, EventMigrationDef, QueryHandlerDef, StreamHandlerDef, WriteHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
5
5
  import type { LifecycleHookFn, OwnedFn, PhasedHook, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, SearchPayloadContributorFn, ValidationHookFn } from "@cosmicdrift/kumiko-types/hooks";
@@ -31,6 +31,7 @@ export type FeatureBuilderState = {
31
31
  configSeeds: ConfigSeedDef[];
32
32
  jobs: Record<string, JobDefinition>;
33
33
  events: Record<string, EventDef>;
34
+ webhookEvents: Record<string, WebhookEventDef>;
34
35
  eventMigrations: Record<string, EventMigrationDef[]>;
35
36
  configReads: string[];
36
37
  entityPostSave: Record<string, PhasedHook<PostSaveHookFn>[]>;
@@ -24,6 +24,7 @@ export function createInitialFeatureBuilderState() {
24
24
  jobs: {},
25
25
  events: {},
26
26
  eventMigrations: {},
27
+ webhookEvents: {},
27
28
  configReads: [],
28
29
  entityPostSave: {},
29
30
  entityPreDelete: {},
@@ -3,7 +3,7 @@ export type { ConfigAccessor, ConfigAccessorFactory, ConfigCascade, ConfigCascad
3
3
  export type { ConfigScope } from "@cosmicdrift/kumiko-types/config-scope";
4
4
  export type { KumikoEventTypeMap } from "@cosmicdrift/kumiko-types/event-type-map";
5
5
  export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
6
- export type { BootOptionName, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, } from "@cosmicdrift/kumiko-types/feature";
6
+ export type { BootOptionName, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, WebhookEntityVerb, WebhookEventContract, WebhookEventHandle, } from "@cosmicdrift/kumiko-types/feature";
7
7
  export type { FeatureRegistrar } from "@cosmicdrift/kumiko-types/feature-registrar";
8
8
  export type { DeriveContext, EntityDefinition, FieldDefinition, JsonbFieldDef, ResolvedPiiFlags, RetentionDef, } from "@cosmicdrift/kumiko-types/fields";
9
9
  export type { AccessRule, AgentEffect, AgentHandlerHints, AgentRisk, AuthClaimsContext, BeforeTransactionResult, ChatSendFailureCode, ClaimKeyType, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchUseEvent, EventDef, JobContext, JobDeferral, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, QueryHandlerDef, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, StreamHandlerDef, TenantWriteTarget, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
@@ -18,7 +18,8 @@ export type { ActionFormScreenDefinition, BundledListsOptions, ConfigEditScreenD
18
18
  export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
19
19
  export type { TreeAction, TreeActionDef, TreeChildrenSubscribe, TreeNode, } from "@cosmicdrift/kumiko-types/tree-node";
20
20
  export type { WorkspaceDefinition } from "@cosmicdrift/kumiko-types/workspace";
21
- export { handlerFieldLabelKey, handlerTitleKey } from "../i18n/required-surface-keys.ts";
21
+ export { DEFAULT_LIST_LIMIT } from "../db/event-store-executor-read-paging.ts";
22
+ export { handlerDescriptionKey, handlerFieldLabelKey, handlerTitleKey, webhookEventDescriptionKey, webhookEventFieldKey, } from "../i18n/required-surface-keys.ts";
22
23
  export { attachOutsideTransaction } from "../pipeline/attach-outside-transaction.ts";
23
24
  export { hasAccess } from "./access.ts";
24
25
  export type { PrincipalProfile, PrincipalStatus, PrincipalStatusPlugin, TenantLifecycleStatusPlugin, } from "./active-membership.ts";
@@ -103,4 +104,6 @@ export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types
103
104
  export type { AppContext, BeforeTransactionContext, FeatureDefinition, HandlerAuth, HandlerContext, HandlerDb, HandlerDispatch, HandlerEvents, HandlerObservability, JobDispatch, JobEvents, JobObservability, QueryEvent, Registry, ReservationContext, SessionUser, TenantId, } from "./types/index.ts";
104
105
  export type { AwaitedEventType, PipelineCtx, StepInstance, StepResolver, } from "./types/step.ts";
105
106
  export { walkStepInstances } from "./walk-step-instances.ts";
107
+ export { createWebhookContractResolver, type WebhookContractResolver, } from "./webhook-contracts.ts";
108
+ export { formatWebhookPayloadIssues, parseWebhookPayload, toEntityWebhookPayload, type WebhookPayloadIssue, type WebhookPayloadResult, } from "./webhook-events.ts";
106
109
  export { withFormDerivations } from "./with-form-derivations.ts";
@@ -1,7 +1,8 @@
1
1
  // Public API
2
2
  export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
3
3
  export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, } from "@cosmicdrift/kumiko-types/handlers";
4
- export { handlerFieldLabelKey, handlerTitleKey } from "../i18n/required-surface-keys.js";
4
+ export { DEFAULT_LIST_LIMIT } from "../db/event-store-executor-read-paging.js";
5
+ export { handlerDescriptionKey, handlerFieldLabelKey, handlerTitleKey, webhookEventDescriptionKey, webhookEventFieldKey, } from "../i18n/required-surface-keys.js";
5
6
  export { attachOutsideTransaction } from "../pipeline/attach-outside-transaction.js";
6
7
  export { hasAccess } from "./access.js";
7
8
  export { collectBootRuleViolations } from "./boot-validator/boot-report.js";
@@ -83,4 +84,6 @@ export { findTierResolverUsage, isTierResolverPlugin, requireTierResolverPlugin,
83
84
  export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, } from "./transfer-adjacency.js";
84
85
  export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
85
86
  export { walkStepInstances } from "./walk-step-instances.js";
87
+ export { createWebhookContractResolver, } from "./webhook-contracts.js";
88
+ export { formatWebhookPayloadIssues, parseWebhookPayload, toEntityWebhookPayload, } from "./webhook-events.js";
86
89
  export { withFormDerivations } from "./with-form-derivations.js";
@@ -231,15 +231,18 @@ function isTargetKept(target, keptScreenQns) {
231
231
  return false;
232
232
  return keptScreenQns.has(qualifyEntityName(target.featureName, "screen", target.screen.id));
233
233
  }
234
- function resolveNavigateTarget(action, indices) {
235
- if (action.entity !== undefined)
236
- return indices.detailForScreens.get(action.entity);
237
- if (action.screen !== undefined)
238
- return indices.screensByShortId.get(action.screen);
239
- return undefined;
234
+ // A QN names exactly one screen; resolving it through the short-id index could land on another
235
+ // feature's same-named screen and keep a reference to a hidden one.
236
+ function isScreenRefKept(ref, indices, keptScreenQns) {
237
+ if (isValidQn(ref))
238
+ return keptScreenQns.has(ref);
239
+ return isTargetKept(indices.screensByShortId.get(ref), keptScreenQns);
240
240
  }
241
241
  function isNavigateTargetKept(action, indices, keptScreenQns) {
242
- const target = resolveNavigateTarget(action, indices);
242
+ if (action.entity === undefined && action.screen !== undefined) {
243
+ return isScreenRefKept(action.screen, indices, keptScreenQns);
244
+ }
245
+ const target = action.entity === undefined ? undefined : indices.detailForScreens.get(action.entity);
243
246
  if (target === undefined)
244
247
  return false;
245
248
  return keptScreenQns.has(qualifyEntityName(target.featureName, "screen", target.screen.id));
@@ -404,9 +407,7 @@ function projectDashboardPanels(panels, feature, keptScreenQns) {
404
407
  function projectListScreenId(listScreenId, indices, keptScreenQns) {
405
408
  if (listScreenId === undefined)
406
409
  return undefined;
407
- return isTargetKept(indices.screensByShortId.get(listScreenId), keptScreenQns)
408
- ? listScreenId
409
- : undefined;
410
+ return isScreenRefKept(listScreenId, indices, keptScreenQns) ? listScreenId : undefined;
410
411
  }
411
412
  // guard:dup-ok sibling of projectListScreenId for a different reference kind with its own keep check
412
413
  function projectRedirect(featureName, redirect, keptScreenQns) {
@@ -1,4 +1,5 @@
1
1
  import { filterByPhase, filterOwned } from "./registry-state.js";
2
+ import { assertUniqueWebhookWireNames, createWebhookContractResolver, } from "./webhook-contracts.js";
2
3
  function isFeatureSystemScoped(state, featureName) {
3
4
  if (!featureName)
4
5
  return false;
@@ -9,6 +10,12 @@ function isFeatureSystemScoped(state, featureName) {
9
10
  // return-object literal, only the closure-captured variable changed
10
11
  // (state.X instead of bare X, done in the RegistryState-threading step).
11
12
  export function buildRegistryFacade(state) {
13
+ assertUniqueWebhookWireNames([...state.featureMap.values()]);
14
+ let resolver;
15
+ const webhookContracts = () => {
16
+ resolver ??= createWebhookContractResolver([...state.featureMap.values()]);
17
+ return resolver;
18
+ };
12
19
  return {
13
20
  features: state.featureMap,
14
21
  getFeature(name) {
@@ -149,6 +156,12 @@ export function buildRegistryFacade(state) {
149
156
  getEvent(qualifiedName) {
150
157
  return state.eventMap.get(qualifiedName);
151
158
  },
159
+ getWebhookEventContract(qualifiedName) {
160
+ return webhookContracts().get(qualifiedName);
161
+ },
162
+ getWebhookEventContracts() {
163
+ return webhookContracts().declared();
164
+ },
152
165
  getEventUpcasters() {
153
166
  return state.eventUpcasterMap;
154
167
  },
@@ -2,6 +2,7 @@ import type { FieldDefinition, SelectFieldDef } from "./types/fields.ts";
2
2
  import type { ActionFormScreenDefinition, ConfigEditScreenDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, FieldCondition, FormatSpec, ListColumnSpec, ProjectionDetailScreenDefinition, ScreenDefinition, SecretMintScreenDefinition } from "./types/screen.ts";
3
3
  export declare const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
4
4
  export declare function explicitListScreenId(screen: ScreenDefinition): string | undefined;
5
+ export declare function screenShortId(ref: string): string;
5
6
  export declare function resolveNavParentScreen(screens: readonly ScreenDefinition[], detail: ScreenDefinition, getId: (screen: ScreenDefinition) => string): ScreenDefinition | undefined;
6
7
  export type EditLayoutScreen = ProjectionDetailScreenDefinition | EntityEditScreenDefinition | ActionFormScreenDefinition | ConfigEditScreenDefinition | SecretMintScreenDefinition;
7
8
  export declare function isEditLayoutScreen(screen: ScreenDefinition): screen is EditLayoutScreen;
@@ -19,7 +19,7 @@ export function explicitListScreenId(screen) {
19
19
  }
20
20
  // Screen refs may be short ids or `<feature>:screen:<id>` QNs (boot-validator
21
21
  // accepts both for navigate targets and listScreenId); compare on the short id.
22
- function screenShortId(ref) {
22
+ export function screenShortId(ref) {
23
23
  return ref.slice(ref.lastIndexOf(":") + 1);
24
24
  }
25
25
  // Shared by the renderer breadcrumb and the boot-validator so both resolve
@@ -0,0 +1,12 @@
1
+ import type { WebhookEventContract } from "@cosmicdrift/kumiko-types/feature";
2
+ import type { FeatureDefinition } from "./types/index.ts";
3
+ export type WebhookContractResolver = {
4
+ /** Declared contract, or one derived from an entity lifecycle event (`entity.verb`). */
5
+ get(qualifiedName: string): WebhookEventContract | undefined;
6
+ /** Declared contracts only, sorted by QN. */
7
+ declared(): readonly WebhookEventContract[];
8
+ };
9
+ /** Works on the feature list so a boot check, which has no registry, resolves the same contracts. */
10
+ export declare function createWebhookContractResolver(features: readonly FeatureDefinition[]): WebhookContractResolver;
11
+ /** Receivers tell events apart by wire name, so two contracts must never share one. */
12
+ export declare function assertUniqueWebhookWireNames(features: readonly FeatureDefinition[]): void;