@wildo-ai/framework-knowledge 1.1.9 → 1.1.10
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/claude-marketplace/.claude-plugin/marketplace.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +11 -0
- package/dist/claude-marketplace/plugins/wildo/references/expert-personas-and-deliberations.md +26 -7
- package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +4 -2
- package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +4 -2
- package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +9 -3
- package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +84 -4
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +39 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +132 -20
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +8 -4
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -6
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +85 -8
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +4 -3
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +4 -3
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +12 -3
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +8 -4
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +4 -1
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +2 -1
- package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +10 -4
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +5 -3
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +11 -9
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +17 -3
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +19 -2
- package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +27 -6
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +32 -12
- package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +13 -5
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +38 -3
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +23 -8
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +11 -0
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
- package/dist/knowledge/manifest.json +7 -7
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +149 -11
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +40 -2
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +55 -0
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +10 -2
- package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +107 -11
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +4 -2
- package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +28 -6
- package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +5 -4
- package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +50 -0
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +16 -4
- package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +19 -0
- package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +5 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +2 -1
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +8 -0
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +3 -2
- package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +5 -2
- package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +7 -3
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +3 -3
- package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +56 -16
- package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +6 -4
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +30 -9
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +5 -3
- package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +12 -1
- package/dist/knowledge/playbooks/top_down.capability-map/method.md +10 -9
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +16 -2
- package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +5 -2
- package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +26 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +4 -2
- package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +84 -9
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +6 -3
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +19 -0
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +19 -1
- package/dist/knowledge/references/brand.name-choice.config.md +20 -3
- package/dist/knowledge/references/brand.name-screening.config.md +58 -3
- package/dist/knowledge/references/build-plan.task-graph.config.md +55 -0
- package/dist/knowledge/references/companion.market.prompt-renderer.md +11 -6
- package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +44 -0
- package/dist/knowledge/references/example.backend.custom-operation.audit-event.md +81 -0
- package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +258 -0
- package/dist/knowledge/references/example.backend.custom-operation.computed-total.md +153 -0
- package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +107 -0
- package/dist/knowledge/references/example.data-seeding.minimal.md +10 -9
- package/dist/knowledge/references/example.data-seeding.row-reference.md +80 -0
- package/dist/knowledge/references/example.email.template.minimal.md +1 -1
- package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +74 -0
- package/dist/knowledge/references/example.resource.personal-data.free-text-field.md +19 -0
- package/dist/knowledge/references/example.resource.personal-data.person-without-account.md +27 -0
- package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +152 -0
- package/dist/knowledge/references/example.resource.ui-behavior.filter-presets.md +15 -0
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -0
- package/dist/knowledge/references/example.views.app-level.home-definition.md +13 -0
- package/dist/knowledge/references/example.views.chart-definition.shared.md +83 -0
- package/dist/knowledge/references/experience-plan.config.md +60 -7
- package/dist/knowledge/references/market.context-block.builder.md +1 -1
- package/dist/knowledge/references/placement-plan.config.md +43 -0
- package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -2
- package/dist/knowledge/references/requirements.non-functional-requirement.config.md +2 -0
- package/dist/knowledge/references/requirements.references.conventions.md +1 -1
- package/dist/knowledge/references/requirements.snapshot.config.md +57 -1
- package/dist/knowledge/references/requirements.snapshot.validation.md +35 -1
- package/dist/knowledge/references/saas.backend.audit-logs.log-event.md +63 -0
- package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +60 -0
- package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +156 -0
- package/dist/knowledge/references/saas.backend.email.send.md +77 -0
- package/dist/knowledge/references/saas.backend.notifications.operation-email-template-ref.md +60 -0
- package/dist/knowledge/references/saas.data-seeding.computed-entry.md +43 -0
- package/dist/knowledge/references/saas.data-seeding.definition-input.md +8 -2
- package/dist/knowledge/references/saas.data-seeding.row-reference.md +93 -0
- package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +124 -0
- package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +316 -0
- package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +106 -0
- package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +60 -0
- package/dist/knowledge/references/saas.frontend.resource-label-params.md +52 -0
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +47 -18
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -1
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destination-roles.md +25 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +2 -2
- package/dist/knowledge/references/saas.models.audit.trail-config.md +45 -0
- package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +5 -3
- package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +26 -0
- package/dist/knowledge/references/saas.models.roles.definition.md +61 -0
- package/dist/knowledge/references/saas.models.roles.organization-defaults.md +97 -0
- package/dist/knowledge/references/saas.public-runtime.contract.md +26 -0
- package/dist/knowledge/references/saas.website.astro.bridge.md +10 -0
- package/dist/knowledge/references/saas.website.astro.label-loader.md +3 -0
- package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +14 -1
- package/dist/knowledge/references/saas.website.astro.site-context.md +13 -0
- package/dist/knowledge/references/saas.website.blog.bridge.md +4 -0
- package/dist/knowledge/references/saas.website.config.site-context-loader.md +3 -0
- package/dist/knowledge/references/saas.website.legal.public-document-links.md +76 -0
- package/dist/knowledge/references/saas.website.root-config.seo.md +2 -1
- package/dist/knowledge/references/saas.website.runtime.context.md +7 -0
- package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +2 -0
- package/dist/knowledge/references/website-plan.config.md +26 -0
- package/dist/knowledge/references/zod.decorators.chainable-runtime.md +13 -0
- package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +7 -0
- package/dist/knowledge/references/zod.decorators.document-sequence.md +65 -0
- package/dist/knowledge/references/zod.decorators.schema-metadata.md +1 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +21 -0
- package/dist/knowledge/references/zod.factories.bigdecimal.md +1 -0
- package/dist/knowledge/references/zod.factories.code.md +1 -0
- package/dist/knowledge/references/zod.factories.duration.md +1 -0
- package/dist/knowledge/references/zod.factories.money.md +1 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +337 -1
- package/dist/knowledge/registries/playbooks.json +18 -18
- package/dist/knowledge/registries/source-tags.json +1435 -873
- package/dist/knowledge/rules/live-context-door.md +1 -1
- package/dist/knowledge/skills/INDEX.md +3 -1
- package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +16 -3
- package/dist/knowledge/skills/application-database-migrations/SKILL.md +14 -3
- package/dist/knowledge/skills/application-roles-authoring/SKILL.md +158 -0
- package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +169 -0
- package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +63 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +6 -1
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +256 -9
- package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +42 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +220 -0
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +5 -0
- package/dist/knowledge/skills/brand-name-screening/SKILL.md +33 -9
- package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +78 -6
- package/dist/knowledge/skills/brand-name-screening/references/screening-procedure.md +30 -8
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +2 -1
- package/dist/knowledge/skills/config-app-shell/SKILL.md +58 -5
- package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +461 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +80 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +28 -6
- package/dist/knowledge/skills/config-navigation/SKILL.md +14 -3
- package/dist/knowledge/skills/config-saas/SKILL.md +25 -11
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +51 -1
- package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +62 -2
- package/dist/knowledge/skills/config-saas-backend/SKILL.md +6 -1
- package/dist/knowledge/skills/configure-billing/SKILL.md +18 -4
- package/dist/knowledge/skills/email-add-template/SKILL.md +27 -5
- package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +1 -1
- package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +128 -0
- package/dist/knowledge/skills/email-add-template/references/framework-operation-email-template-ref-api.md +99 -0
- package/dist/knowledge/skills/engine-component-registration/SKILL.md +6 -1
- package/dist/knowledge/skills/engine-product-definitions/SKILL.md +21 -8
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +10 -2
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +18 -4
- package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +11 -3
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -1
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +8 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +18 -4
- package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +10 -2
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +6 -1
- package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +6 -1
- package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +10 -2
- package/dist/knowledge/skills/market-alternatives/SKILL.md +10 -2
- package/dist/knowledge/skills/market-authoring-overview/SKILL.md +10 -2
- package/dist/knowledge/skills/market-category/SKILL.md +21 -7
- package/dist/knowledge/skills/market-channels/SKILL.md +6 -1
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +11 -3
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +1 -1
- package/dist/knowledge/skills/market-generation-cli/SKILL.md +21 -11
- package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +11 -6
- package/dist/knowledge/skills/market-icp/SKILL.md +10 -2
- package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +6 -1
- package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +6 -1
- package/dist/knowledge/skills/market-persona/SKILL.md +14 -3
- package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +6 -1
- package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +10 -2
- package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +6 -1
- package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +14 -3
- package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +6 -1
- package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +26 -0
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +7 -1
- package/dist/knowledge/skills/module-relationships/SKILL.md +31 -4
- package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +4 -2
- package/dist/knowledge/skills/provider-address-lookup/SKILL.md +14 -3
- package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +6 -1
- package/dist/knowledge/skills/provider-operation-calls/SKILL.md +14 -3
- package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +10 -2
- package/dist/knowledge/skills/resource-add-field/SKILL.md +10 -2
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +46 -17
- package/dist/knowledge/skills/resource-add-resource/SKILL.md +14 -2
- package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +26 -0
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +29 -3
- package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +19 -4
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +5 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +103 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +135 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +26 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +26 -7
- package/dist/knowledge/skills/resource-custom-view/SKILL.md +10 -2
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +46 -17
- package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +2 -2
- package/dist/knowledge/skills/resource-retention-binding/SKILL.md +5 -1
- package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +15 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +569 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +358 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +8 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +21 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +7 -2
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +13 -0
- package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +153 -0
- package/dist/knowledge/skills/resource-status-lifecycle/references/commercial-documents.md +46 -0
- package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +198 -0
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +30 -4
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +157 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +101 -19
- package/dist/knowledge/skills/seeding-authoring/SKILL.md +155 -40
- package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +67 -0
- package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +148 -4
- package/dist/knowledge/skills/seeding-authoring/references/seed-row-overlay.md +22 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +43 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +2 -2
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +6 -1
- package/dist/knowledge/skills/spec-component-update/SKILL.md +10 -2
- package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +2 -2
- package/dist/knowledge/skills/spec-family-update/SKILL.md +71 -66
- package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +1 -1
- package/dist/knowledge/skills/spec-resource-update/SKILL.md +30 -10
- package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +28 -0
- package/dist/knowledge/skills/spec-update-after-change/SKILL.md +22 -5
- package/dist/knowledge/skills/views-add-composite-view/SKILL.md +6 -1
- package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -2
- package/dist/knowledge/skills/views-app-level/SKILL.md +13 -3
- package/dist/knowledge/skills/views-app-level/references/application-home.md +56 -0
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +221 -37
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +22 -5
- package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -1
- package/dist/knowledge/skills/website-anonymous-session/SKILL.md +32 -2
- package/dist/knowledge/skills/website-blog-authoring/SKILL.md +16 -3
- package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +4 -0
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +7 -1
- package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +13 -1
- package/dist/knowledge/skills/website-factory-advanced/SKILL.md +10 -2
- package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +13 -1
- package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -1
- package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +19 -1
- package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +55 -18
- package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +98 -0
- package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +8 -11
- package/dist/knowledge/skills/website-page-authoring/SKILL.md +16 -5
- package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +3 -0
- package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-faq/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +10 -2
- package/dist/knowledge/skills/website-section-hero/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-pricing/SKILL.md +6 -1
- package/dist/knowledge/skills/website-section-social-proof/SKILL.md +12 -2
- package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +15 -3
- package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +16 -1
- package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +2 -1
- package/dist/knowledge/topic-index.json +1441 -269
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
|
@@ -216,13 +216,13 @@ What is **not** in this block (and shouldn't be):
|
|
|
216
216
|
- `references/framework-connection-target-credentials.md` — which third-party identity a provider call acts as, how a tenant supplies its OWN credential, and why nothing is ever substituted for a missing one
|
|
217
217
|
- `references/framework-content-security-policy-api.md` — the `csp` block on any frontend: opt-in by absence, the generated artifact is the only one read, and why report-only without a collector does nothing
|
|
218
218
|
- `references/framework-value-moments-api.md` — `analytics.valueMoments`: why `role` changes three things at once, and why a declared moment with analytics off is evaluated by nothing
|
|
219
|
-
- `references/framework-audit-trail-config-api.md` — the `auditTrail` block: why `archiveAfterDays` is the opt-in and why setting it never shrinks the primary store
|
|
219
|
+
- `references/framework-audit-trail-config-api.md` — the `auditTrail` block: why `archiveAfterDays` is the opt-in and why setting it never shrinks the primary store, and how `applicationEventTypes` classifies and words the application's own audit event types
|
|
220
220
|
- `references/framework-systems-of-record-api.md` — `systemsOfRecord`: declaring a deployment your application reads its OWN rows out of, why it is not a provider, and the three files its name, address and credential live in; an instance's `facetAugmentations` opts it into packages that ADD a partition or a credential kind to its vendor's facet — see `resource-external-data`'s `references/facet-augmentations.md`
|
|
221
221
|
- `providers.packages` — the provider packages discovery does not walk by name (another scope's, or an own-scope one not named `provider-*`) that the application admits to discovery; listing activates nothing, and `wildo config sync` refuses a listing that admits nothing — see `provider-backend-package`'s `references/framework-provider-package-allow-list-api.md`
|
|
222
222
|
- `references/saas-config-scope.md` — what belongs in root SaaS config
|
|
223
223
|
- `references/framework-wildo-saas-config-api.md` — `WildoSaasConfigSchema` / inferred types
|
|
224
224
|
- `references/framework-provider-capabilities-api.md` — engine slots and provider capability vocabulary, including durable email selection
|
|
225
|
-
- `references/compliance-declarations.md` — the six compliance declarations,
|
|
225
|
+
- `references/compliance-declarations.md` — the six compliance declarations, why an ABSENT one is never a negative answer, and the legal notice (imprint) projected from the operator's identity
|
|
226
226
|
|
|
227
227
|
## Verification
|
|
228
228
|
|
|
@@ -247,19 +247,33 @@ Run from the app root:
|
|
|
247
247
|
|
|
248
248
|
| Invariant | Command |
|
|
249
249
|
|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
|
|
250
|
-
|
|
|
251
|
-
|
|
|
252
|
-
|
|
|
253
|
-
|
|
|
254
|
-
| Each engine capability declares `enabled:` | `rg -n "EngineCapability\.[A-Z_]+\]:\s*\{" wildo.saas.config.ts \| wc -l` then `rg -c "enabled:" wildo.saas.config.ts` |
|
|
255
|
-
| **No placeholder in a compliance declaration** (must return empty) | `rg -n "TODO\|TBD\|PLACEHOLDER\|example\.com\|Acme" wildo.saas.config.ts` |
|
|
250
|
+
| **Module entries ↔ module folders agree** (must return empty) | see the commands below the table |
|
|
251
|
+
| Minion / worker paths exist | see the commands below the table |
|
|
252
|
+
| Each engine capability declares `enabled:` | run the commands below the table, then `rg -c "enabled:" wildo.saas.config.ts` |
|
|
253
|
+
| **No placeholder in a compliance declaration** (must return empty) | see the commands below the table |
|
|
256
254
|
| Which provider is selected for telemetry | `rg -n "OBSERVABILITY_TELEMETRY\]:\s*\{" -A2 wildo.saas.config.ts` |
|
|
257
255
|
| **Which runtimes declare it** (compare against the runtimes that should be traceable) | `rg -n "^\s+<telemetryProviderRef>:\s*\{" wildo.saas.config.ts` |
|
|
258
256
|
| **Stored config matches the file** (no stale slice reported) | `wildo config validate --domain declaration` |
|
|
259
257
|
|
|
260
|
-
|
|
261
|
-
module
|
|
262
|
-
|
|
258
|
+
```bash
|
|
259
|
+
# Module entries ↔ module folders agree (must return empty) — reads only the modules block (inline, or the
|
|
260
|
+
# `applicationModules` constant in the same file); a module's folder lives under each service it declares, so a
|
|
261
|
+
# frontend-only module has no shared-lib folder
|
|
262
|
+
comm -3 <(awk '/^ *(modules: |export const applicationModules = )\{/{f=1;d=0} f{if(d==1&&match($0,/^ *\047?[a-z][a-z0-9-]*\047? *: *\{/)){k=$0;sub(/^ *\047?/,"",k);sub(/\047? *:.*/,"",k);print k} d+=gsub(/\{/,"{")-gsub(/\}/,"}"); if(d<=0)exit}' wildo.saas.config.ts | sort -u) <(ls -1 shared-lib/src/modules frontend/src/modules backend-api/src/modules 2>/dev/null | grep -E '^[a-z][a-z0-9-]*$' | sort -u)
|
|
263
|
+
|
|
264
|
+
# Minion / worker paths exist
|
|
265
|
+
rg -P -oN "path:\s+'\K[^']+" wildo.saas.config.ts | while read p; do test -d "$p" || echo "MISSING: $p"; done
|
|
266
|
+
|
|
267
|
+
# Each engine capability declares `enabled:`
|
|
268
|
+
rg -n "EngineCapability\.[A-Z_]+\]:\s*\{" wildo.saas.config.ts | wc -l
|
|
269
|
+
|
|
270
|
+
# No placeholder in a compliance declaration (must return empty)
|
|
271
|
+
rg -n "TODO|TBD|PLACEHOLDER|example\.com|Acme" wildo.saas.config.ts
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
The modules ↔ folders invariant is the high-signal one: it names a module
|
|
275
|
+
the config declares with no code under any service, and a module folder no
|
|
276
|
+
declaration names.
|
|
263
277
|
|
|
264
278
|
The last two are a READ, not a pass/fail: substitute the ref the first
|
|
265
279
|
returns into the second, then compare the runtimes it lists against the
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Six optional declarations sit in the root SaaS config alongside the composition keys. They answer a
|
|
4
4
|
different question from the rest of the file — not *"what am I made of"* but *"what is legally true of
|
|
5
|
-
this application"* — and a produced privacy notice or terms document quotes them.
|
|
5
|
+
this application"* — and a produced privacy notice or terms document quotes them. The application's legal
|
|
6
|
+
notice (imprint) is projected from `operatorComplianceIdentity` too; see the section on it below.
|
|
6
7
|
|
|
7
8
|
Read this before adding or editing any of them.
|
|
8
9
|
|
|
@@ -86,6 +87,55 @@ obligations for one of the two populations.
|
|
|
86
87
|
Art. 6(1) basis the processing rests on, are different questions. Declaring a gate does not make
|
|
87
88
|
consent the basis for anything.
|
|
88
89
|
|
|
90
|
+
## The legal notice (imprint) — owed where the operator is ESTABLISHED
|
|
91
|
+
|
|
92
|
+
A service provider established in the EU, the EEA, the UK or Switzerland must publish its identity where anyone can
|
|
93
|
+
reach it in one step (Directive 2000/31/EC Art. 5(1); in Germany § 5 DDG, the Impressum; in the UK the E-Commerce
|
|
94
|
+
Regulations 2002, reg. 6; in Switzerland UWG Art. 3 Abs. 1 Bst. s). Other countries' rules are not modelled, so for an
|
|
95
|
+
establishment elsewhere the framework publishes no notice: check your own law. The markets you sell into do not decide it:
|
|
96
|
+
an operator established in France owes one, an operator established only in the United States does not, whichever
|
|
97
|
+
countries either serves. So the application reads one field:
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
operatorComplianceIdentity: {
|
|
101
|
+
establishmentJurisdiction: 'fr', // a jurisdiction code, the place the operator is established
|
|
102
|
+
legalEntityName: 'Wonder Software SAS',
|
|
103
|
+
registeredAddress: '1 rue de la Paix, 75002 Paris, France',
|
|
104
|
+
generalContact: { email: 'contact@wonder.example' }, // phone optional; NOT the privacy contact
|
|
105
|
+
// Declare these only where they apply to the operator:
|
|
106
|
+
legalForm: 'SAS',
|
|
107
|
+
authorizedRepresentatives: ['Jeanne Martin, Présidente'],
|
|
108
|
+
tradeRegister: { register: 'RCS Paris', registrationNumber: '123 456 789' },
|
|
109
|
+
vatIdentificationNumber: 'FR12123456789',
|
|
110
|
+
// supervisoryAuthority, regulatedProfession: only for an activity that needs them
|
|
111
|
+
// Germany (§ 5 DDG) also: shareCapital { amount, outstandingContributions? } only if you state your capital,
|
|
112
|
+
// economicIdentificationNumber if you have one, and inLiquidation: true while the company is being wound up.
|
|
113
|
+
},
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Then project it into the running application and keep it current:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
wildo config legal-notice # writes backend-api/src/legal-notice.generated.ts
|
|
120
|
+
wildo config legal-notice --check # fails when the module is out of date
|
|
121
|
+
wildo config validate # the legal-notice domain: current, and composed as compliance.legalNotice
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`saas-config.backend.ts` composes the generated constant as `compliance.legalNotice`. The application then serves
|
|
125
|
+
the notice at `/legal-notice`, and a marketing website built from the same config links it from its footer.
|
|
126
|
+
The website decides from `wildo.saas.config.ts` at build time, while the page reads the generated module. Re-run
|
|
127
|
+
`wildo config legal-notice` after every change to the identity, or the footer can link to a page that is out of date.
|
|
128
|
+
`wildo config validate` fails until you do.
|
|
129
|
+
|
|
130
|
+
- Owed: the operator's name, its geographic address and a direct contact. Each one left undeclared appears on the
|
|
131
|
+
page as **not yet declared** and in `wildo context launch-blockers`. Never type a placeholder in its place: the page
|
|
132
|
+
publishes it as fact.
|
|
133
|
+
- Conditional: legal form, representatives, share capital, trade register, VAT number, economic identification number,
|
|
134
|
+
supervisory authority, regulated profession, liquidation.
|
|
135
|
+
Only you know whether each applies, so the page shows the ones you declare and nothing marks the others.
|
|
136
|
+
- `establishmentJurisdiction` undeclared means **unknown**, never "not owed". The page says no notice is published, and
|
|
137
|
+
the launch list names the field until you declare it.
|
|
138
|
+
|
|
89
139
|
## `operatingJurisdictions` — and the warning you must not silence
|
|
90
140
|
|
|
91
141
|
```ts
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# Framework Audit-Trail Config API
|
|
2
2
|
|
|
3
|
-
The `auditTrail` block on the
|
|
4
|
-
|
|
3
|
+
The `auditTrail` block on the application configuration (authored in the backend configuration). Its fields
|
|
4
|
+
are listed in the contract at the end. This page covers the two that are easiest to misread: the archival horizon
|
|
5
|
+
and the application's own audit event types.
|
|
5
6
|
|
|
6
7
|
## `archiveAfterDays` is the opt-in, and it deletes nothing
|
|
7
8
|
|
|
@@ -26,6 +27,20 @@ is a smaller primary store, this is not the mechanism.
|
|
|
26
27
|
- An application turning this on after it already has aged data seeds the archive with a one-off run
|
|
27
28
|
at a wider look-back.
|
|
28
29
|
|
|
30
|
+
## `applicationEventTypes` classifies YOUR event types, never the framework's
|
|
31
|
+
|
|
32
|
+
Every event type an operation records with `logEvent` that is not a framework type is the application's own. Declare
|
|
33
|
+
each one here, keyed by its exact `eventType` string, with a `category` and a `severity`. Rows of that type are then
|
|
34
|
+
recorded and routed to the SIEM with that classification, and the labelling pipeline plans its word
|
|
35
|
+
(`system_enums.CoreAuditableEventType.<eventType>`). An undeclared type is recorded as `data_access` / `info` and shown
|
|
36
|
+
by its raw value.
|
|
37
|
+
|
|
38
|
+
- Type the declaration as total over your event-type enum (`satisfies Record<Your_AuditEventType, …>`), so an event
|
|
39
|
+
type added without a classification fails to compile. The worked example in
|
|
40
|
+
`backend-custom-operation/references/framework-audit-log-event-api.md` does this.
|
|
41
|
+
- Naming a framework event type is refused at startup: the engine's classification of its own events is authoritative.
|
|
42
|
+
- The key must use only letters, digits, `_` and `-`, because it becomes the last segment of a label key.
|
|
43
|
+
|
|
29
44
|
## Audit-Trail Config
|
|
30
45
|
|
|
31
46
|
## Import Origins
|
|
@@ -117,6 +132,19 @@ export enum AuditApplicationReadAccess {
|
|
|
117
132
|
INDEPENDENT_APPROVAL = 'independent-approval',
|
|
118
133
|
}
|
|
119
134
|
|
|
135
|
+
/**
|
|
136
|
+
* How one of the application's OWN audit event types is classified: the activity it records and the attention it
|
|
137
|
+
* deserves. The same two vocabularies the engine uses for its event types.
|
|
138
|
+
*/
|
|
139
|
+
export const ApplicationAuditEventTypeDeclarationSchema = z.strictObject({
|
|
140
|
+
/** What kind of activity the event records. A business event (an invoice issued, a quote sent) is `data_access`. */
|
|
141
|
+
category: z.enum(AuditEventCategory),
|
|
142
|
+
/** How much attention it deserves: `info` is evidence, `warning` is worth review, `critical` is meant for whoever handles security incidents. A SIEM destination's event filter is what routes on it. */
|
|
143
|
+
severity: z.enum(AuditEventSeverity),
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
export type ApplicationAuditEventTypeDeclaration = z.infer<typeof ApplicationAuditEventTypeDeclarationSchema>;
|
|
147
|
+
|
|
120
148
|
export const AuditTrailConfigSchema = z.object({
|
|
121
149
|
/**
|
|
122
150
|
* Application audit viewer admission. Omitted means ROLE_BASED in every environment.
|
|
@@ -183,7 +211,39 @@ export const AuditTrailConfigSchema = z.object({
|
|
|
183
211
|
* addresses are admitted, never whether the admitted address is the one connected to.
|
|
184
212
|
*/
|
|
185
213
|
allowPrivateNetworkSiemCollectors: z.boolean().optional(),
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* The application's OWN audit event types — the `eventType` values it passes to `AuditLogsBackendService.logEvent`
|
|
217
|
+
* — each with its classification. Keyed by the exact `eventType` string.
|
|
218
|
+
*
|
|
219
|
+
* ── What declaring one changes ─────────────────────────────────────────────
|
|
220
|
+
* - Every row of that type is recorded with the declared `eventCategory` and `severity`, and the SIEM export
|
|
221
|
+
* routes and filters by them. An UNDECLARED application type is recorded as `data_access` / `info`, whatever
|
|
222
|
+
* the event is — a business-critical event is then indistinguishable from routine reads.
|
|
223
|
+
* - The labelling pipeline plans a word for it (`system_enums.CoreAuditableEventType.<eventType>`, the open
|
|
224
|
+
* vocabulary the audit row's `eventType` field names), so the audit views show "Quote issued" instead of
|
|
225
|
+
* `SALES_QUOTE_ISSUED`. Run label generation after adding one.
|
|
226
|
+
*
|
|
227
|
+
* ── What it cannot do ──────────────────────────────────────────────────────
|
|
228
|
+
* It cannot reclassify a FRAMEWORK event type: the engine's own classification is authoritative, and naming one of
|
|
229
|
+
* its event types here is refused at startup. The key must be usable as the last segment of a label key (letters,
|
|
230
|
+
* digits, `_`, `-`).
|
|
231
|
+
*
|
|
232
|
+
* Severity is a property of the event TYPE. A row's `riskLevel` (supplied per emission) is a separate signal and
|
|
233
|
+
* does not change it.
|
|
234
|
+
*
|
|
235
|
+
* @example
|
|
236
|
+
* auditTrail: {
|
|
237
|
+
* applicationEventTypes: {
|
|
238
|
+
* SALES_QUOTE_ISSUED: { category: AuditEventCategory.DATA_ACCESS, severity: AuditEventSeverity.WARNING },
|
|
239
|
+
* },
|
|
240
|
+
* }
|
|
241
|
+
*/
|
|
242
|
+
applicationEventTypes: z.record(z.string().regex(LABEL_KEY_SEGMENT_PATTERN), ApplicationAuditEventTypeDeclarationSchema).optional(),
|
|
186
243
|
});
|
|
187
244
|
|
|
245
|
+
/** The application's declared audit event types, keyed by `eventType` — see `AuditTrailConfig.applicationEventTypes`. */
|
|
246
|
+
export type ApplicationAuditEventTypes = NonNullable<AuditTrailConfig['applicationEventTypes']>;
|
|
247
|
+
|
|
188
248
|
export type AuditTrailConfig = z.infer<typeof AuditTrailConfigSchema>;
|
|
189
249
|
```
|
|
@@ -215,7 +215,12 @@ it names the failure you get without the block:
|
|
|
215
215
|
| The transactional From address is declared | `rg -n "from:" backend-api/src/saas-config.backend.ts` |
|
|
216
216
|
| The document-acceptance posture is declared | `rg -n "governedDocumentAcceptanceMode" backend-api/src/saas-config.backend.ts` |
|
|
217
217
|
| Declared identity-provider ranges are CIDR, never host names (inspect each entry) | `rg -n -A3 "federatedIdentityProviderPrivateNetworks" backend-api/src/saas-config.backend.ts` |
|
|
218
|
-
| No platform-managed branch leaked in (MUST return zero) |
|
|
218
|
+
| No platform-managed branch leaked in (MUST return zero) | see the commands below the table |
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
# No platform-managed branch leaked in (MUST return zero)
|
|
222
|
+
rg -n "jwt:|endPoints|mongodb|publicKey" backend-api/src/saas-config.backend.ts
|
|
223
|
+
```
|
|
219
224
|
|
|
220
225
|
## Common Rationalizations
|
|
221
226
|
|
|
@@ -247,13 +247,27 @@ Run from the app root (substitute `<ref>` / `<env>`):
|
|
|
247
247
|
|-----------|---------|
|
|
248
248
|
| **Provider SDK installed** (must return a hit) | `rg -n '"stripe"' backend-api/package.json` |
|
|
249
249
|
| Engine capability enabled | `rg -n "EngineCapability.BILLING.*enabled:\s*true" wildo.saas.config.ts` |
|
|
250
|
-
| Billing block declares provider ref |
|
|
251
|
-
| **Ref authored in BACKEND scope** (must return a hit) |
|
|
250
|
+
| Billing block declares provider ref | see the commands below the table |
|
|
251
|
+
| **Ref authored in BACKEND scope** (must return a hit) | see the commands below the table |
|
|
252
252
|
| **No second declaration** (must return NOTHING for an engine-shipped or package-shipped provider) | `rg -n "<ref>" backend-api/src/provider-contributions.ts` |
|
|
253
|
-
| Billing scope declares both protocols |
|
|
253
|
+
| Billing scope declares both protocols | see the commands below the table |
|
|
254
254
|
| Secrets populated (both listed under `SET`, none under `NEEDED`) | `wildo secrets list --env <env>` |
|
|
255
255
|
| **Ref materialized in the artifact** (must return a hit after sync) | `rg -n "<ref>" backend-api/src/generated/wildo-provider-runtime.generated.ts` |
|
|
256
|
-
| **No frontend-scope billing entry** (must return NOTHING — billing has no browser part) |
|
|
256
|
+
| **No frontend-scope billing entry** (must return NOTHING — billing has no browser part) | see the commands below the table |
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
# Billing block declares provider ref
|
|
260
|
+
rg -n "billing:\s*\{" -A3 backend-api/src/saas-config.backend.ts | rg "providerRef:"
|
|
261
|
+
|
|
262
|
+
# Ref authored in BACKEND scope (must return a hit)
|
|
263
|
+
rg -n "backend:\s*\{" -A80 wildo.saas.config.ts | rg "<ref>:"
|
|
264
|
+
|
|
265
|
+
# Billing scope declares both protocols
|
|
266
|
+
rg -n "'BILLING_PROVIDER'.*'WEBHOOK_ORIGINATOR'|'WEBHOOK_ORIGINATOR'.*'BILLING_PROVIDER'" wildo.saas.config.ts
|
|
267
|
+
|
|
268
|
+
# No frontend-scope billing entry (must return NOTHING — billing has no browser part)
|
|
269
|
+
rg -n "frontendServices:" -A60 wildo.saas.config.ts | rg "<ref>:"
|
|
270
|
+
```
|
|
257
271
|
|
|
258
272
|
The high-signal pair: **"ref authored in BACKEND scope"** returning empty while
|
|
259
273
|
**"no frontend-scope billing entry"** returns a hit is the exact billing crash-loop
|
|
@@ -184,7 +184,9 @@ co-location conventions.
|
|
|
184
184
|
Inspect the existing backend module's `emailTemplateDefinitions` slot before choosing a layout. The current skeleton scans compiled email directories; an older application may maintain an explicit map. Preserve the actual ownership and registration path rather than adding a parallel map with a prescribed filename.
|
|
185
185
|
|
|
186
186
|
- The scanner loads `template.js` default exports and co-located `labels.<locale>.js` named `labels` exports. Author their TypeScript sources and let the normal compiler publish them; a new `.tsx` file alone is not a loaded runtime template.
|
|
187
|
-
- The scanner's `keyFromPath` owns the template ref. The skeleton maps `system/<name>` to `system.<name_with_underscores
|
|
187
|
+
- The scanner's `keyFromPath` owns the template ref. The skeleton maps `system/<name>` to `system.<name_with_underscores>`, and under `resources/` turns the path into the ref by replacing `/` with `.`. Module-specific scanners may choose other mappings. Match the existing sender's typed ref to that mapping; creating an enum with a different value does not rename the scanned ref.
|
|
188
|
+
- **An operation's email (a `userNotifications` EMAIL entry) has a derived ref:** `email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`, so its directory is `resources/<resource>/<operation>[.<variantKey>].<target>[_<customNotificationRef>]/` — for example `resources/todos/change_status.admin.users-custom_notify-creator/`. The target segment is always there, and an operation with a keyed variant needs one template per variant. A missing one only WARNS at startup (it refuses only for a token-bearing operation), and the email is silently never sent. Read `references/framework-operation-email-template-ref-api.md` before naming the directory.
|
|
189
|
+
- **Declare before you code.** A non-user recipient at an address on the record is `recipientEmailField`; an email owed whatever the preferences is `alwaysDeliver: true`. Send from custom code with `EmailBackendService.send` only for an attachment, several or nested addresses, cc / bcc / threading, or a non-user's own language. Read `references/framework-email-send-api.md`.
|
|
188
190
|
- Contribute the resulting map through the existing owning backend module. For an explicit map, add the imported definition and locale labels there; for a scanner, put the correctly exported files under the scanned directory. Do not manually edit generated definitions or add duplicate registrations.
|
|
189
191
|
- Sender services resolve the typed ref through the framework email service; they do not import and render the template directly. Identity emails remain with their identity/engine owner; business-module emails remain with the owning business module.
|
|
190
192
|
|
|
@@ -249,7 +251,7 @@ import { EmailTemplateType } from '@wildo-ai/saas-models';
|
|
|
249
251
|
import type {
|
|
250
252
|
EmailTemplateDefinition,
|
|
251
253
|
EmailTemplateProps,
|
|
252
|
-
} from '
|
|
254
|
+
} from '@wildo-ai/saas-backend-lib';
|
|
253
255
|
|
|
254
256
|
export interface MinimalExampleLabels {
|
|
255
257
|
subject: string;
|
|
@@ -352,6 +354,8 @@ single self-contained reference shape for app developers.
|
|
|
352
354
|
- `references/framework-email-attachments-and-limits.md` — `attachmentFileIds`, the framework's own size cap, and why a declared vendor list is not failover
|
|
353
355
|
- `references/email-artifact-paths.md` — where files live (template, labels, registry, type enum)
|
|
354
356
|
- `references/framework-email-template-api.md` — `EmailTemplateDefinition<TLabels>` + `EmailTemplateDefinitionsMap` types
|
|
357
|
+
- `references/framework-operation-email-template-ref-api.md` — the ref an operation's `userNotifications` email renders, and the directory it lives in, with worked cases (source-backed)
|
|
358
|
+
- `references/framework-email-send-api.md` — when a declaration cannot express the email, and `EmailBackendService.send`'s request, outcomes and retry rule (source-backed)
|
|
355
359
|
- `i18n-rerun-pipeline/SKILL.md` — translation pipeline orchestrator (Step 6 trigger)
|
|
356
360
|
- `backend-addon-wiring/SKILL.md` — the module-level `emailTemplateDefinitions` slot consumer (the registry feeds into this)
|
|
357
361
|
|
|
@@ -361,6 +365,7 @@ single self-contained reference shape for app developers.
|
|
|
361
365
|
- [ ] Labels exist for **every** user-visible string (one key per string), satisfying the typed `TLabels` interface key-for-key
|
|
362
366
|
- [ ] Labels files exist for every supported locale (parallel key sets across locales)
|
|
363
367
|
- [ ] Compiled template and labels resolve under the owning module’s scanner/map, and its ref matches the sender’s typed id
|
|
368
|
+
- [ ] An operation email's directory carries the full derived ref (`<operation>[.<variantKey>].<target>[_<customNotificationRef>]`), one per keyed variant, and startup logs no unresolved operation email
|
|
364
369
|
- [ ] Definition explicitly selects `EmailTemplateType.*` and the corresponding provider capability is configured
|
|
365
370
|
- [ ] Definition is typed `EmailTemplateDefinition<TLabels>` (not `any`, not bare `EmailTemplateDefinition`)
|
|
366
371
|
- [ ] `subject` / `body` JSX contains **no inline strings** (every string flows through `labels`)
|
|
@@ -382,12 +387,26 @@ Run from the app root. Replace `<email-root>` with the actual owning scanner dir
|
|
|
382
387
|
| Subject / body read from `labels.` | `rg -n "labels\.[a-zA-Z]+" <email-root>/<template>/template.tsx` |
|
|
383
388
|
| Locale files exist for every supported locale | `ls <email-root>/<template>/labels.*.ts` |
|
|
384
389
|
| Other-locale files are the generated ones (must return empty) | `rg --files-without-match "DO NOT EDIT THIS FILE MANUALLY" <email-root>/<template>/labels.<locale>.ts` (run for each non-primary locale) |
|
|
385
|
-
| Owning registry/scanner and ref mapping are present |
|
|
386
|
-
| Per-locale label files share the same key set |
|
|
390
|
+
| Owning registry/scanner and ref mapping are present | see the commands below the table (inspect the mapping; scanned templates need no per-template map entry) |
|
|
391
|
+
| Per-locale label files share the same key set | see the commands below the table (output should be empty) |
|
|
387
392
|
| Sender resolves template by typed id | `rg -n "EmailTemplateType\.[A-Z_]+" backend-api/src/modules/<module>/` |
|
|
388
393
|
| **No inline JSX text in subject / body** (must return empty) | `rg -n ">[A-Za-z][^<{}]{2,}<" <email-root>/<template>/template.tsx` |
|
|
389
|
-
| **No app SPA imports** in the template (must return empty) |
|
|
394
|
+
| **No app SPA imports** in the template (must return empty) | see the commands below the table |
|
|
390
395
|
| **No direct template import** in sender services (must return empty) | `rg -n "from\s+['\"].*notifications/email/<template>/template['\"]" backend-api/src/modules/<module>/` |
|
|
396
|
+
| **Every operation email resolves** (must return empty after a backend start) | `rg -n "does not resolve through the configured primary/fallback locale chain" <backend startup log>` |
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
# No app SPA imports in the template (must return empty)
|
|
400
|
+
rg -n "from\s+['\"](app|frontend)/" <email-root>/<template>/template.tsx
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
# Owning registry/scanner and ref mapping are present
|
|
405
|
+
rg -n "scanEmailTemplateDirectory|keyFromPath|emailTemplateDefinitions" <registry-file>
|
|
406
|
+
|
|
407
|
+
# Per-locale label files share the same key set
|
|
408
|
+
comm -23 <(rg -o '\w+:' <email-root>/<template>/labels.<primary-locale>.ts | sort -u) <(rg -o '\w+:' <email-root>/<template>/labels.<locale>.ts | sort -u)
|
|
409
|
+
```
|
|
391
410
|
|
|
392
411
|
The high-signal invariants are **"No inline JSX text in subject /
|
|
393
412
|
body"** combined with **"No direct template import in sender
|
|
@@ -428,6 +447,9 @@ second guarantees the registry is the integration seam.
|
|
|
428
447
|
import in sender services** grep — must return empty)
|
|
429
448
|
- Template imports from `frontend/` (catch with the **No app SPA
|
|
430
449
|
imports** grep — must return empty)
|
|
450
|
+
- An operation email's template whose folder does not carry the full ref (no target segment, a missing variant) —
|
|
451
|
+
nothing renders it, startup only warns, and the email is silently never sent (catch with the **Every operation
|
|
452
|
+
email resolves** check)
|
|
431
453
|
- Brand color / domain hard-coded in the body (template no longer
|
|
432
454
|
renders correctly across environments)
|
|
433
455
|
- New label keys committed without a translation rerun (Step 6
|
|
@@ -12,6 +12,6 @@ Locate the owning backend module's `emailTemplateDefinitions` contribution first
|
|
|
12
12
|
|
|
13
13
|
The scanner starts beside its caller's `import.meta.url`, scans its configured `subdir` recursively and uses `keyFromPath` to derive refs. Its default extension is `.js`. It imports the template's default export and the labels module's named `labels` export (also accepts `default.labels`). It does not infer refs from a new enum or inspect an arbitrary TypeScript source folder.
|
|
14
14
|
|
|
15
|
-
In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; `resources/tasks/
|
|
15
|
+
In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; under `resources/`, `/` becomes `.`, so an operation email for `tasks` / `assign` / target `USER_SELF` lives in `resources/tasks/assign.user-self` and registers `email.tasks.assign.user-self` (the full rule: `references/framework-operation-email-template-ref-api.md`). The engine backend module contributes the map. Business-module email definitions should follow their existing module-owned contribution rather than being moved into the engine merely to match this example.
|
|
16
16
|
|
|
17
17
|
For an explicit map, follow its existing `EmailTemplateDefinitionsMap` shape and preserve its labels wiring. For a scanner, adding a correctly named/default-exported template and named locale exports under its root is the registration input; no per-template manual entry is required. In either case, normal compilation/publication and module loading must make the ref visible. Match the sender's typed identifier to the derived ref and verify through preview. Never hand-edit compiled artifacts to make a missing source registration appear fixed.
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Sending an email from custom code
|
|
2
|
+
|
|
3
|
+
Read this when an operation must send an email that a `userNotifications` declaration cannot express.
|
|
4
|
+
|
|
5
|
+
## Declare it first
|
|
6
|
+
|
|
7
|
+
Most business emails are declarations (`resource-config-wiring`, `references/framework-user-notifications-api.md`),
|
|
8
|
+
including two that look as if they need code:
|
|
9
|
+
|
|
10
|
+
| the email | declare |
|
|
11
|
+
|---|---|
|
|
12
|
+
| to a user, or to users chosen by role or relationship | `userNotifications` with a `target` |
|
|
13
|
+
| to somebody who is not a user, at an address held on the record (a customer contact, a lead) | `recipientEmailField` naming that top-level field |
|
|
14
|
+
| that must reach the recipient whatever their preferences | `alwaysDeliver: true` on the entry |
|
|
15
|
+
|
|
16
|
+
A declaration is dispatched by the framework after commit, honours preferences unless told otherwise, and needs no
|
|
17
|
+
code. Send from code only when it cannot express the email:
|
|
18
|
+
|
|
19
|
+
- it carries an **attachment** (a declaration has none);
|
|
20
|
+
- it goes to **several addresses**, or an address in a **nested** field or a list;
|
|
21
|
+
- it needs **cc, bcc, reply-to or threading** headers (a reply in an existing conversation);
|
|
22
|
+
- a recipient who is **not a user** must be written to in **their own language** (`recipientEmailField` sends in the
|
|
23
|
+
application's default locale).
|
|
24
|
+
|
|
25
|
+
A direct send consults no preference. Reaching for it to get around a person's choice to switch an email off is the
|
|
26
|
+
one wrong use.
|
|
27
|
+
|
|
28
|
+
## How
|
|
29
|
+
|
|
30
|
+
1. Create the template like any other, under a scanned directory; `send` renders a REGISTERED template by its ref.
|
|
31
|
+
2. In the custom operation, resolve the service from the factory's container on first use:
|
|
32
|
+
`container.get<EmailBackendService>(SAAS_SERVICE_TYPES.EmailService)`, both from `@wildo-ai/saas-backend-lib`.
|
|
33
|
+
3. Call it where the change is durable (a postfix without `transactionalCore`, `atTheEnd` with it), so a rolled-back
|
|
34
|
+
operation sends nothing.
|
|
35
|
+
4. **Wrap it.** `send` throws a typed configuration or validation error (an invalid recipient address, a template
|
|
36
|
+
ref that does not resolve, a configuration the email cannot be sent with). Thrown from `atTheEnd`, that error
|
|
37
|
+
reaches the caller AFTER the change committed, so catch it and decide: log it, or record that the email is owed.
|
|
38
|
+
5. **Read `outcome`, not only `success`:**
|
|
39
|
+
- `success: false` with `outcome` `ACCEPTANCE_UNKNOWN`: the request reached the provider and the answer was lost.
|
|
40
|
+
The email MAY have been sent; a retry can send it twice.
|
|
41
|
+
- `success: false` with `rejectedRecipients`: the provider accepted the message for some recipients and refused
|
|
42
|
+
others.
|
|
43
|
+
- otherwise `success: false` means it was not sent, and `retryable` says whether trying again may help.
|
|
44
|
+
6. **Retry with the same `submissionId`.** It names one logical email, so a provider that already accepted it can say
|
|
45
|
+
so instead of sending it twice. A retry that may happen in another process (a minion picking up the work later)
|
|
46
|
+
needs the `submissionId` stored on the row.
|
|
47
|
+
|
|
48
|
+
## The request and the result
|
|
49
|
+
|
|
50
|
+
`send(request: EmailSendRequest): Promise<EmailSendResult>`. `locale` is an `AvailableLanguage` (from
|
|
51
|
+
`@wildo-ai/presets-components-models`); `context` is the template's variables; `outcome` is an `EmailSubmissionOutcome`, from
|
|
52
|
+
`@wildo-ai/saas-models`.
|
|
53
|
+
|
|
54
|
+
## Import Origins
|
|
55
|
+
|
|
56
|
+
- `@wildo-ai/saas-backend-lib`
|
|
57
|
+
|
|
58
|
+
## Source Excerpts
|
|
59
|
+
|
|
60
|
+
### Origin Package: `@wildo-ai/saas-backend-lib`
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
/**
|
|
64
|
+
* What `EmailBackendService.send(request)` takes: one email, rendered from a REGISTERED template (`templateRef` is the
|
|
65
|
+
* scanned key, such as `email.quotes.issue.customer`) in one locale. Reach the service from a custom operation through
|
|
66
|
+
* the factory's container: `container.get<EmailBackendService>(SAAS_SERVICE_TYPES.EmailService)`.
|
|
67
|
+
*
|
|
68
|
+
* Unlike a `userNotifications` entry, a direct send consults no recipient preference: the caller decides that this
|
|
69
|
+
* person receives this email. Use it for an email the product owes regardless of preferences (a document the customer
|
|
70
|
+
* asked for); anything a person may switch off belongs in `userNotifications`.
|
|
71
|
+
*/
|
|
72
|
+
export interface EmailSendRequest {
|
|
73
|
+
/**
|
|
74
|
+
* Stable identity of one logical provider submission. A caller that can
|
|
75
|
+
* retry across process/job boundaries must persist and reuse this value.
|
|
76
|
+
* Ephemeral callers may omit it and let the service allocate one.
|
|
77
|
+
*/
|
|
78
|
+
submissionId?: string;
|
|
79
|
+
/** Template reference (e.g., "system.welcome_email") */
|
|
80
|
+
templateRef: string;
|
|
81
|
+
/** Locale for template selection */
|
|
82
|
+
locale: AvailableLanguage;
|
|
83
|
+
/** Email type for provider routing */
|
|
84
|
+
type: EmailTemplateType;
|
|
85
|
+
/** Primary recipient email(s) */
|
|
86
|
+
to: string | string[];
|
|
87
|
+
/** CC recipients (optional) */
|
|
88
|
+
cc?: string[];
|
|
89
|
+
/** BCC recipients (optional) */
|
|
90
|
+
bcc?: string[];
|
|
91
|
+
/** Reply-to address (optional) */
|
|
92
|
+
replyTo?: string;
|
|
93
|
+
/** From address (optional - uses provider default if not specified) */
|
|
94
|
+
from?: string;
|
|
95
|
+
/** Context for template rendering */
|
|
96
|
+
context: EmailTemplateContext;
|
|
97
|
+
/** File IDs for attachments (optional) */
|
|
98
|
+
attachmentFileIds?: string[];
|
|
99
|
+
/** Organization ID for org-scoped templates (optional) */
|
|
100
|
+
organizationId?: string;
|
|
101
|
+
/**
|
|
102
|
+
* Thread this email as a reply (#1630). Becomes exactly `Message-ID`, `In-Reply-To` and `References` —
|
|
103
|
+
* see {@link EmailThreadingHeaders} for why there is no general headers field.
|
|
104
|
+
*/
|
|
105
|
+
threading?: EmailThreadingHeaders;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export interface EmailSendResult {
|
|
109
|
+
success: boolean;
|
|
110
|
+
/**
|
|
111
|
+
* Whether an at-least-once caller should retry. An acceptance-unknown retry
|
|
112
|
+
* can duplicate an externally visible email; provider-native idempotency is
|
|
113
|
+
* only an optional risk reduction.
|
|
114
|
+
*/
|
|
115
|
+
retryable: boolean;
|
|
116
|
+
submissionId: string;
|
|
117
|
+
outcome: EmailSubmissionOutcome;
|
|
118
|
+
/** All honest provider receipts. Empty means no receipt was returned. */
|
|
119
|
+
providerMessageIds: string[];
|
|
120
|
+
/** Provider confirmed that this logical submission was already accepted. */
|
|
121
|
+
deduplicated?: boolean;
|
|
122
|
+
rejectedRecipients?: Array<{ email: string; reason?: string }>;
|
|
123
|
+
providerId?: string;
|
|
124
|
+
error?: string;
|
|
125
|
+
templateRef: string;
|
|
126
|
+
recipientCount: number;
|
|
127
|
+
}
|
|
128
|
+
```
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# The template an operation's email renders
|
|
2
|
+
|
|
3
|
+
Read this when a resource operation declares a `userNotifications` EMAIL entry and you are creating its template,
|
|
4
|
+
or when a startup warning says an operation email's template does not resolve.
|
|
5
|
+
|
|
6
|
+
## The ref, and the directory it lives in
|
|
7
|
+
|
|
8
|
+
The framework derives the template ref from the operation and the notification entry:
|
|
9
|
+
|
|
10
|
+
`email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`
|
|
11
|
+
|
|
12
|
+
- `<variantKey>` appears only for a variant that declares one. `userNotifications` is declared on the OPERATION and
|
|
13
|
+
the ref is derived per variant, so one EMAIL entry on an operation with a keyed variant needs one template per
|
|
14
|
+
variant: an operation with two EMAIL entries and two variants needs four folders (the last two rows below are two
|
|
15
|
+
of the four for `change_status`).
|
|
16
|
+
- `<target>` is the entry's `target`, lowercased with `_` turned into `-`: `USERS_CUSTOM` becomes `users-custom`.
|
|
17
|
+
- `_<customNotificationRef>` appears only when the entry names one, to tell two emails of the same target apart.
|
|
18
|
+
|
|
19
|
+
The scanner an application ships finds every directory holding a `template` file under the `resources/` directory beside it, at any
|
|
20
|
+
depth, and turns its path into a ref by replacing `/` with `.`. The applications keep one directory per template under
|
|
21
|
+
the resource, named with the rest of the ref, dots included:
|
|
22
|
+
|
|
23
|
+
| operation and entry | template directory |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `tasks` · `assign` · target `USER_SELF` | `resources/tasks/assign.user-self/` |
|
|
26
|
+
| `todos` · `assign` · target `USERS_CUSTOM` | `resources/todos/assign.users-custom/` |
|
|
27
|
+
| `todos` · `change_status` · target `USERS_CUSTOM` · custom ref `notify-creator` | `resources/todos/change_status.users-custom_notify-creator/` |
|
|
28
|
+
| `todos` · `change_status` · variant `admin` · target `USERS_CUSTOM` · custom ref `notify-creator` | `resources/todos/change_status.admin.users-custom_notify-creator/` |
|
|
29
|
+
|
|
30
|
+
A nested spelling (`resources/todos/assign/users-custom/`) scans to the same ref, because `/` and `.` both become
|
|
31
|
+
`.`. Keep to one spelling per application, so a template is found where the next reader looks for it. What never
|
|
32
|
+
works is a directory named after the operation alone (`resources/todos/assign/`) when the entry has a target: the
|
|
33
|
+
target segment is always part of the ref.
|
|
34
|
+
|
|
35
|
+
Startup resolves every declared operation email through the locale chain and names the folder to create when one is
|
|
36
|
+
missing. It REFUSES to start only for an operation with `tokenGeneration` (the email carries the token its flow
|
|
37
|
+
needs). For any other operation it only WARNS, and the email is silently never sent, so read the startup warnings
|
|
38
|
+
after adding an entry: `does not resolve through the configured primary/fallback locale chain` names each missing one.
|
|
39
|
+
|
|
40
|
+
## The derivation
|
|
41
|
+
|
|
42
|
+
## Import Origins
|
|
43
|
+
|
|
44
|
+
- `@wildo-ai/saas-backend-lib`
|
|
45
|
+
|
|
46
|
+
## Source Excerpts
|
|
47
|
+
|
|
48
|
+
### Origin Package: `@wildo-ai/saas-backend-lib`
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
/**
|
|
52
|
+
* Canonical template identity for operation-authored email notifications: the template a `userNotifications` EMAIL
|
|
53
|
+
* entry renders.
|
|
54
|
+
*
|
|
55
|
+
* `email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`, where `<target>` is the entry's
|
|
56
|
+
* `target` lowercased with `_` turned into `-` (an engine-internal entry without a target uses its `identifier`). The
|
|
57
|
+
* variant segment is present only for a variant that declares a `variantKey`, and `userNotifications` is declared on
|
|
58
|
+
* the OPERATION, so one entry on an operation with a keyed variant needs one template per variant.
|
|
59
|
+
*
|
|
60
|
+
* With the scanner an application ships (`keyFromPath` turns `/` into `.` under the `resources/` directory beside it), the template's
|
|
61
|
+
* directory is `resources/<resource>/<the rest of the ref, dotted>`: for `todos` / `change_status` / variant `admin` /
|
|
62
|
+
* target `USERS_CUSTOM` / custom ref `notify-assignee` it is
|
|
63
|
+
* `resources/todos/change_status.admin.users-custom_notify-assignee/`.
|
|
64
|
+
*
|
|
65
|
+
* Startup validation and runtime dispatch must use the same derivation;
|
|
66
|
+
* otherwise an application can boot against one template reference and fail
|
|
67
|
+
* only after a mutation commits because delivery derived another.
|
|
68
|
+
*/
|
|
69
|
+
export function buildUserNotificationEmailTemplateRef(
|
|
70
|
+
operation: {
|
|
71
|
+
resourceIdentifier: string;
|
|
72
|
+
operationIdentifier: string;
|
|
73
|
+
variantKey?: string;
|
|
74
|
+
},
|
|
75
|
+
notification: {
|
|
76
|
+
identifier: string;
|
|
77
|
+
target?: string;
|
|
78
|
+
customNotificationRef?: string;
|
|
79
|
+
},
|
|
80
|
+
): string {
|
|
81
|
+
const targetKebab =
|
|
82
|
+
(notification.target || notification.identifier)
|
|
83
|
+
.toLowerCase()
|
|
84
|
+
.replace(/_/g, '-');
|
|
85
|
+
const refParts = [
|
|
86
|
+
'email',
|
|
87
|
+
operation.resourceIdentifier,
|
|
88
|
+
operation.operationIdentifier,
|
|
89
|
+
];
|
|
90
|
+
if (operation.variantKey) {
|
|
91
|
+
refParts.push(operation.variantKey);
|
|
92
|
+
}
|
|
93
|
+
refParts.push(targetKebab);
|
|
94
|
+
const baseRef = refParts.join('.');
|
|
95
|
+
return notification.customNotificationRef
|
|
96
|
+
? `${baseRef}_${notification.customNotificationRef}`
|
|
97
|
+
: baseRef;
|
|
98
|
+
}
|
|
99
|
+
```
|
|
@@ -232,9 +232,14 @@ Run from the app root, substituting `<COMPONENT_REF_CONST>` and
|
|
|
232
232
|
| `componentRef` is a top-level constant | `rg -n "^const\s+\w+_COMPONENT_REF\s*=\s*'" frontend/src/engine/component-registrations.frontend.ts` |
|
|
233
233
|
| Constant is consumed (catch typos at consumer sites) | `rg -n "componentRef:\s+<COMPONENT_REF_CONST>" frontend/src/` |
|
|
234
234
|
| **No string-literal `componentRef`** in registrations (must be empty) | `rg -n "componentRef:\s+'" frontend/src/engine/component-registrations.frontend.ts` |
|
|
235
|
-
| Five framework-default registrars are invoked |
|
|
235
|
+
| Five framework-default registrars are invoked | see the commands below the table |
|
|
236
236
|
| Lazy `loadComponent` uses `.js` suffix | `rg -n "await import\('\./.*\.js'\)" frontend/src/engine/component-registrations.frontend.ts` |
|
|
237
237
|
|
|
238
|
+
```bash
|
|
239
|
+
# Five framework-default registrars are invoked
|
|
240
|
+
rg -n "registerDefault(Icons|Presets|Animations)|registerBuiltinCommonEnums|registerFrameworkLayouts" frontend/src/engine/component-registrations.frontend.ts
|
|
241
|
+
```
|
|
242
|
+
|
|
238
243
|
The high-signal invariant is **"`componentRef` is a top-level
|
|
239
244
|
constant"** combined with the consumer grep — it's the only
|
|
240
245
|
mechanism that catches typos at the consumer site at compile time.
|