@wildo-ai/framework-knowledge 1.1.11 → 1.1.12
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 +4 -0
- package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +25 -3
- package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +40 -12
- package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +3 -3
- package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +12 -0
- package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +19 -2
- package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +33 -9
- package/dist/esm/framework-knowledge.definitions.d.ts +2 -3
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +170 -32
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.loader.js.map +1 -1
- package/dist/esm/framework-knowledge.research-provenance.d.ts +6 -4
- package/dist/esm/framework-knowledge.research-provenance.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.research-provenance.js.map +1 -1
- package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.schemas.js.map +1 -1
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -3
- 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 +4 -12
- 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/playbook.definition.js +12 -1
- package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +7 -4
- 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 +76 -14
- 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 +0 -4
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +3 -15
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js.map +1 -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 +35 -14
- 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 +16 -8
- 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 +19 -8
- package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +29 -3
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +80 -16
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js +2 -2
- package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +5 -1
- 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 +3 -2
- 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.map +1 -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 +45 -10
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js +61 -21
- package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts +4 -3
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js +8 -5
- package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts +2 -2
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js +3 -5
- package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +3 -3
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +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 +8 -6
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts +5 -0
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js +8 -1
- package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +4 -1
- 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 +11 -3
- 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.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +1 -1
- 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.map +1 -1
- package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +6 -4
- 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 +3 -1
- 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 +4 -1
- 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 +10 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +36 -13
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +8 -2
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +7 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +4 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +34 -6
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +5 -2
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +4 -3
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.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-evidence-adequacy/playbook.definition.js +2 -2
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +22 -10
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +39 -29
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +8 -3
- package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.definition/playbook.definition.js +16 -7
- package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
- 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.map +1 -1
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js.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-analysis/playbook.definition.js.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-evidence-adequacy/playbook.definition.js +2 -2
- package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.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-research/playbook.definition.js.map +1 -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 +1 -1
- 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 +13 -5
- 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 +3 -7
- 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 +12 -14
- 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 +3 -0
- package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +2 -1
- package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +3 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +2 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts +4 -1
- package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.service-method/playbook.definition.js +14 -1
- package/dist/esm/playbooks/top_down.service-method/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +3 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +4 -2
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +34 -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 +35 -17
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
- package/dist/esm/source-anchor-grammar.d.ts.map +1 -1
- package/dist/esm/source-anchor-grammar.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +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/method.md +6 -0
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +4 -4
- package/dist/knowledge/playbooks/bottom_up.build/method.md +12 -2
- package/dist/knowledge/playbooks/bottom_up.build/playbook.json +5 -3
- 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 +439 -27
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +15 -4
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +203 -7
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -5
- package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +1 -0
- package/dist/knowledge/playbooks/bottom_up.documentation-plan/method.md +2 -2
- package/dist/knowledge/playbooks/bottom_up.documentation-plan/playbook.json +2 -1
- 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 +104 -2
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +8 -4
- package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +59 -4
- package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +18 -6
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +121 -24
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +51 -7
- package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +15 -8
- package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -1
- package/dist/knowledge/playbooks/bottom_up.maturity-reading/method.md +10 -2
- package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +4 -3
- package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +34 -0
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +9 -2
- package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +1 -0
- package/dist/knowledge/playbooks/cross_cutting.application-creation/method.md +27 -12
- package/dist/knowledge/playbooks/cross_cutting.application-creation/playbook.json +11 -5
- package/dist/knowledge/playbooks/cross_cutting.compliance/method.md +4 -4
- package/dist/knowledge/playbooks/cross_cutting.compliance/playbook.json +7 -2
- package/dist/knowledge/playbooks/cross_cutting.feature-development/playbook.json +1 -0
- package/dist/knowledge/playbooks/cross_cutting.refinement/method.md +6 -6
- package/dist/knowledge/playbooks/cross_cutting.refinement/playbook.json +3 -4
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +56 -5
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +3 -2
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +6 -4
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +5 -1
- package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +8 -1
- package/dist/knowledge/playbooks/refinement.governance-document-candidate/playbook.json +1 -0
- 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/playbook.json +15 -3
- package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +11 -4
- package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +3 -2
- 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 +16 -6
- package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +3 -2
- package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +5 -1
- package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.business-model/method.md +43 -11
- package/dist/knowledge/playbooks/top_down.business-model/playbook.json +24 -8
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +6 -2
- package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +1 -1
- package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +49 -14
- package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +3 -3
- package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +6 -2
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +20 -0
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +4 -3
- package/dist/knowledge/playbooks/top_down.compliance-posture/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.compliance-posture/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +69 -65
- package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +11 -7
- package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +1 -0
- package/dist/knowledge/playbooks/top_down.definition/method.md +3 -1
- package/dist/knowledge/playbooks/top_down.definition/playbook.json +11 -3
- package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +1 -0
- package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -0
- package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +1 -0
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +4 -2
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +4 -3
- package/dist/knowledge/playbooks/top_down.market-research/playbook.json +1 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +3 -0
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +3 -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 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +10 -6
- package/dist/knowledge/playbooks/top_down.risk-register/method.md +7 -0
- package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +5 -1
- package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +6 -1
- package/dist/knowledge/playbooks/top_down.service-method/method.md +19 -1
- package/dist/knowledge/playbooks/top_down.service-method/playbook.json +16 -4
- package/dist/knowledge/playbooks/top_down.value-proposition/method.md +5 -2
- package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +9 -3
- package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-protocol.json +1 -1
- package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-treatment.json +1 -1
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +17 -2
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +59 -15
- package/dist/knowledge/references/application-documentation-chapters.config.md +45 -10
- package/dist/knowledge/references/application-documentation-plan.config.md +2 -2
- package/dist/knowledge/references/application-maturity.config.md +27 -1
- package/dist/knowledge/references/backend.inbound-channels.attachment-adoption.md +4 -2
- package/dist/knowledge/references/backend.inbound-channels.handler-definition.md +52 -11
- package/dist/knowledge/references/backend.inbound-handlers.definition.md +38 -1
- package/dist/knowledge/references/brand.name-screening.config.md +30 -3
- package/dist/knowledge/references/build-plan.task-graph.config.md +200 -4
- package/dist/knowledge/references/business-model.pricing-plan.config.md +12 -9
- package/dist/knowledge/references/business-model.snapshot.config.md +29 -2
- package/dist/knowledge/references/business-model.snapshot.validation.md +11 -8
- package/dist/knowledge/references/companion.introspection.behaviors.market.md +3 -0
- package/dist/knowledge/references/companion.market.generation-service.md +46 -5
- package/dist/knowledge/references/companion.market.prompt-renderer.md +1 -1
- package/dist/knowledge/references/companion.technical-doc.service.md +195 -63
- package/dist/knowledge/references/domain-plan.record-partition.md +105 -0
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +3 -1
- package/dist/knowledge/references/engine.saas-technical-doc.config.md +69 -15
- package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +10 -0
- package/dist/knowledge/references/example.backend.addon-wiring.module.md +6 -0
- package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +41 -0
- package/dist/knowledge/references/example.backend.custom-operation.external-effect-reservation.md +107 -0
- package/dist/knowledge/references/example.blueprint.definition.internal-tool.md +4 -2
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +8 -5
- package/dist/knowledge/references/example.infra.environment-config.local.md +13 -66
- package/dist/knowledge/references/example.module.companion-exports.full.md +1 -0
- package/dist/knowledge/references/example.module.relationships.actor-edge-back-to-scope-owner.md +35 -35
- package/dist/knowledge/references/example.navigation.one-entry-per-concept.md +47 -0
- package/dist/knowledge/references/example.organization-identity.system-of-record-partitions.md +18 -0
- package/dist/knowledge/references/example.provider.backend-module-shape.md +28 -4
- package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +0 -4
- package/dist/knowledge/references/example.resource.custom-view.backend-refusal.md +75 -0
- package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +8 -7
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +37 -2
- package/dist/knowledge/references/example.resource.ui-behavior.record-template.md +0 -1
- package/dist/knowledge/references/example.resource.ui-behavior.surface-decision.md +1 -1
- package/dist/knowledge/references/example.resource.ui-behavior.workflow-record-page.md +212 -0
- package/dist/knowledge/references/example.subject-export.portability-archive.md +42 -0
- package/dist/knowledge/references/example.views.app-level.workflow-home.md +238 -0
- package/dist/knowledge/references/example.website.demo.complete-items.md +3 -3
- package/dist/knowledge/references/example.website.pricing.audit-payloads.md +38 -0
- package/dist/knowledge/references/example.website.pricing.catalog-load.md +77 -0
- package/dist/knowledge/references/example.website.pricing.offers.md +43 -0
- package/dist/knowledge/references/example.website.pricing.plans-section.md +20 -0
- package/dist/knowledge/references/example.website.pricing.plans.md +88 -0
- package/dist/knowledge/references/example.website.section.stats.md +1 -1
- package/dist/knowledge/references/experience-plan.config.md +111 -1
- package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
- package/dist/knowledge/references/external-connectors.models.file-storage-adapter.md +8 -1
- package/dist/knowledge/references/external-connectors.models.hook-signature-algorithms.md +104 -0
- package/dist/knowledge/references/external-connectors.models.oauth2-audiences.md +11 -6
- package/dist/knowledge/references/external-connectors.models.oauth2-incremental-consent.md +165 -0
- package/dist/knowledge/references/external-connectors.models.rest-operation-contract.md +1035 -19
- package/dist/knowledge/references/external-connectors.private.provider-compliance-state-collector.md +36 -0
- package/dist/knowledge/references/external-connectors.private.provider-configuration-check.md +69 -0
- package/dist/knowledge/references/integration-plan.config.md +7 -7
- package/dist/knowledge/references/placement-plan.config.md +19 -0
- package/dist/knowledge/references/platform.config.backing-services.md +9 -11
- package/dist/knowledge/references/platform.config.environment.deployment.md +133 -8
- package/dist/knowledge/references/platform.config.infra-provider-resolution.md +3 -3
- package/dist/knowledge/references/platform.config.infrastructure-host.md +0 -1
- package/dist/knowledge/references/platform.config.platform-key-management.md +84 -8
- package/dist/knowledge/references/platform.config.saas.md +20 -18
- package/dist/knowledge/references/presets.3d.frame-style-resolution.md +65 -0
- package/dist/knowledge/references/presets.layouts-2d.authoring.md +1 -1
- package/dist/knowledge/references/presets.models.field-form-control-variant.md +32 -0
- package/dist/knowledge/references/presets.models.labelling.sections.md +39 -0
- package/dist/knowledge/references/presets.models.surface-policy.defaults.md +3 -3
- package/dist/knowledge/references/presets.models.surface-variant.md +5 -4
- package/dist/knowledge/references/presets.themes.compose-theme.md +2 -1
- package/dist/knowledge/references/requirements.non-functional-requirement.config.md +4 -4
- package/dist/knowledge/references/requirements.snapshot.config.md +2 -3
- package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +29 -2
- package/dist/knowledge/references/saas.backend.a2a.token-budget.md +11 -4
- package/dist/knowledge/references/saas.backend.actor-execution-continuation.md +21 -0
- package/dist/knowledge/references/saas.backend.app-config.backend-authored.md +5 -1
- package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +1 -1
- package/dist/knowledge/references/saas.backend.authorization.role-ceiling.md +13 -1
- package/dist/knowledge/references/saas.backend.custom-operation.authoritative-fields.md +4 -1
- package/dist/knowledge/references/saas.backend.custom-operation.core-write-precondition.md +38 -0
- package/dist/knowledge/references/saas.backend.custom-operation.external-effect-reservation.md +109 -0
- package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +43 -0
- package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +1 -1
- package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +62 -13
- package/dist/knowledge/references/saas.backend.domain-module.md +30 -1
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +26 -3
- package/dist/knowledge/references/saas.backend.flows-actors.chat-reply-handler.md +13 -1
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +363 -2
- package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +5 -3
- package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +1 -1
- package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +9 -4
- package/dist/knowledge/references/saas.backend.flows.start-flow-method.md +2 -1
- package/dist/knowledge/references/saas.backend.privacy.subject-export-archive.md +26 -0
- package/dist/knowledge/references/saas.backend.providers.connection-target-credential-resolution.md +21 -19
- package/dist/knowledge/references/saas.backend.system-access-service.md +159 -4
- package/dist/knowledge/references/saas.config.content-security-policy.md +26 -9
- package/dist/knowledge/references/saas.data-seeding.definition-input.md +1 -1
- package/dist/knowledge/references/saas.data-seeding.modes.md +4 -1
- package/dist/knowledge/references/saas.data-seeding.row-reference.md +2 -4
- package/dist/knowledge/references/saas.external-providers.backend-provider-loader.md +6 -0
- package/dist/knowledge/references/saas.external-providers.backend-provider-registry.runtime-filter.md +2 -0
- package/dist/knowledge/references/saas.frontend.chart-dashboard-view.md +43 -0
- package/dist/knowledge/references/saas.frontend.chart-dashboard.md +130 -0
- package/dist/knowledge/references/saas.frontend.chart-view.resource-chart-data.md +8 -4
- package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +76 -9
- package/dist/knowledge/references/saas.frontend.command-menu.search-resource.md +3 -3
- package/dist/knowledge/references/saas.frontend.errors.backend-refusal.md +96 -0
- package/dist/knowledge/references/saas.frontend.execution-view.definition.md +40 -0
- package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +4 -0
- package/dist/knowledge/references/saas.frontend.linked-conversations-embed.md +3 -5
- package/dist/knowledge/references/saas.frontend.record-page-parts.md +117 -0
- package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +46 -16
- package/dist/knowledge/references/saas.frontend.related-resource-sections.md +6 -0
- package/dist/knowledge/references/saas.frontend.resource-header-title.md +1 -1
- package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +43 -9
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +259 -15
- package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -2
- package/dist/knowledge/references/saas.frontend.section-stages.md +63 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +42 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +6 -9
- package/dist/knowledge/references/saas.frontend.viewer-may-perform-operation.md +52 -0
- package/dist/knowledge/references/saas.models.agent-suspension.md +8 -8
- package/dist/knowledge/references/saas.models.audit-trails.actor-attribution.md +21 -0
- package/dist/knowledge/references/saas.models.auth.relationship-grantor-authentication.md +2 -2
- package/dist/knowledge/references/saas.models.config.declared-type-renames.md +246 -0
- package/dist/knowledge/references/saas.models.config.organization-types.md +20 -0
- package/dist/knowledge/references/saas.models.conversation-threads.md +39 -3
- package/dist/knowledge/references/saas.models.crypto-keys.floors.md +10 -0
- package/dist/knowledge/references/saas.models.crypto-keys.local-provider.md +2 -0
- package/dist/knowledge/references/saas.models.crypto-keys.purpose-descriptor.md +39 -0
- package/dist/knowledge/references/saas.models.crypto-keys.purposes.md +7 -0
- package/dist/knowledge/references/saas.models.data-mode-read-list.md +0 -78
- package/dist/knowledge/references/saas.models.engine-capabilities.md +11 -2
- package/dist/knowledge/references/saas.models.engine-capabilities.required-provider-floor.md +3 -0
- package/dist/knowledge/references/saas.models.external-data-pipeline.md +15 -8
- package/dist/knowledge/references/saas.models.flows-actors.agent-behavior-report.md +13 -9
- package/dist/knowledge/references/saas.models.flows-actors.agent-configuration.md +29 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-operation-record.md +7 -0
- package/dist/knowledge/references/saas.models.flows-actors.human-decision-decider.md +8 -0
- package/dist/knowledge/references/saas.models.flows-actors.human-input-form.md +47 -12
- package/dist/knowledge/references/saas.models.flows-actors.operation-approval-requirement.md +31 -0
- package/dist/knowledge/references/saas.models.flows-actors.review-deadlines-declaration.md +3 -3
- package/dist/knowledge/references/saas.models.flows.runnable-model.md +21 -2
- package/dist/knowledge/references/saas.models.guidance-flow.md +1 -1
- package/dist/knowledge/references/saas.models.http-api-binding.md +19 -8
- package/dist/knowledge/references/saas.models.human-decision-review-marker.md +1 -1
- package/dist/knowledge/references/saas.models.inbound-channels.md +71 -2
- package/dist/knowledge/references/saas.models.model-cost-accounting-config.md +1 -1
- package/dist/knowledge/references/saas.models.notifications.targets.md +3 -1
- package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +201 -15
- package/dist/knowledge/references/saas.models.organization-assigned-rows-declaration.md +2 -1
- package/dist/knowledge/references/saas.models.organization-own-rows-declaration.md +5 -2
- package/dist/knowledge/references/saas.models.organizations.identity-declaration.md +201 -0
- package/dist/knowledge/references/saas.models.organizations.organization-relationships.md +25 -3
- package/dist/knowledge/references/saas.models.organizations.relationship-invitations.md +6 -2
- package/dist/knowledge/references/saas.models.organizations.relationship-kinds.md +14 -0
- package/dist/knowledge/references/saas.models.organizations.relationship-record-separation.md +1 -0
- package/dist/knowledge/references/saas.models.privacy.data-residency.md +676 -0
- package/dist/knowledge/references/saas.models.privacy.legal-holds.md +46 -2
- package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +6 -0
- package/dist/knowledge/references/saas.models.privacy.retention-binding.md +84 -1
- package/dist/knowledge/references/saas.models.privacy.retention-enforcement-record.md +10 -0
- package/dist/knowledge/references/saas.models.privacy.retention-schedule.md +5 -3
- package/dist/knowledge/references/saas.models.privacy.subject-data-recipients.md +2 -0
- package/dist/knowledge/references/saas.models.privacy.subject-export.md +134 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +5 -0
- package/dist/knowledge/references/saas.models.providers.capability-resolution-mode.md +12 -6
- package/dist/knowledge/references/saas.models.providers.compliance-choice.md +15 -0
- package/dist/knowledge/references/saas.models.providers.processing-region-reach.md +132 -0
- package/dist/knowledge/references/saas.models.providers.processing-region-selection.md +139 -0
- package/dist/knowledge/references/saas.models.representative-activity.md +4 -0
- package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +107 -42
- package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +35 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-auditable-event.md +4 -2
- package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +56 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-idempotency-key.md +16 -6
- package/dist/knowledge/references/saas.models.resource-config.operation-scope-admissions.md +38 -0
- package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +14 -16
- package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +2 -2
- package/dist/knowledge/references/saas.models.resource-config.retention-policy.md +21 -0
- package/dist/knowledge/references/saas.models.resource-config.system-access-policy.md +32 -15
- package/dist/knowledge/references/saas.models.resource-operation-display-risk.md +5 -4
- package/dist/knowledge/references/saas.models.roles.definition.md +12 -1
- package/dist/knowledge/references/saas.models.roles.organization-defaults.md +6 -0
- package/dist/knowledge/references/saas.models.schema-family-builder.md +17 -2
- package/dist/knowledge/references/saas.models.system-of-record-actions.md +65 -1
- package/dist/knowledge/references/saas.models.system-of-record-capabilities.md +3 -1
- package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +16 -0
- package/dist/knowledge/references/saas.models.systems-of-record.md +75 -14
- package/dist/knowledge/references/saas.public-runtime.contract.md +41 -23
- package/dist/knowledge/references/saas.rag.retrieval-refusals.md +3 -2
- package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +12 -4
- package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +21 -2
- package/dist/knowledge/references/saas.specifications.engine-resource-sub-domain.md +105 -0
- package/dist/knowledge/references/saas.specifications.governed-document-release.contract.md +6 -2
- package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +20 -3
- package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +100 -71
- package/dist/knowledge/references/saas.specifications.translation-glossary.md +80 -0
- package/dist/knowledge/references/saas.website.astro.label-loader.md +44 -10
- package/dist/knowledge/references/saas.website.astro.runtime-helper.md +3 -2
- package/dist/knowledge/references/saas.website.blog.collection-config.md +36 -32
- package/dist/knowledge/references/saas.website.blog.cover-resolver.md +1 -1
- package/dist/knowledge/references/saas.website.blog.frontmatter.md +2 -2
- package/dist/knowledge/references/saas.website.blog.post-renderer.md +2 -2
- package/dist/knowledge/references/saas.website.blog.react-mdx-integration.md +26 -19
- package/dist/knowledge/references/saas.website.blog.react-mdx-query.md +1 -1
- package/dist/knowledge/references/saas.website.config.pricing-catalog-loader.md +3 -1
- package/dist/knowledge/references/saas.website.config.site-context-loader.md +6 -3
- package/dist/knowledge/references/saas.website.label-keys.format.md +3 -2
- package/dist/knowledge/references/saas.website.label-pack.validator.md +3 -1
- package/dist/knowledge/references/service-method.config.md +35 -2
- package/dist/knowledge/references/vision.constraint.config.md +4 -2
- package/dist/knowledge/references/zod.decorators.chainable-runtime.md +60 -0
- package/dist/knowledge/references/zod.decorators.data-categories.md +46 -46
- package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +24 -0
- package/dist/knowledge/references/zod.decorators.display-edit-modes.md +11 -0
- package/dist/knowledge/references/zod.decorators.file-schema.md +4 -3
- package/dist/knowledge/references/zod.decorators.rag-source.md +20 -20
- package/dist/knowledge/references/zod.decorators.schema-metadata.md +2 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +30 -24
- package/dist/knowledge/references/zod.decorators.shared-structural-params.md +63 -0
- package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +63 -0
- package/dist/knowledge/references/zod.factories.bigdecimal.md +4 -4
- package/dist/knowledge/references/zod.factories.code.md +4 -4
- package/dist/knowledge/references/zod.factories.duration.md +4 -4
- package/dist/knowledge/references/zod.factories.money.md +4 -4
- package/dist/knowledge/references/zod.factories.phone.md +4 -4
- package/dist/knowledge/references/zod.factories.year-month.md +79 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +415 -2
- package/dist/knowledge/registries/playbooks.json +51 -39
- package/dist/knowledge/registries/source-tags.json +2412 -1604
- package/dist/knowledge/rules/database-migration-obligation.md +6 -7
- package/dist/knowledge/rules/live-context-door.md +1 -1
- package/dist/knowledge/skills/INDEX.md +3 -1
- package/dist/knowledge/skills/agent-work-review/references/framework-actor-execution-continuation-api.md +24 -0
- package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-marker-api.md +1 -1
- package/dist/knowledge/skills/agent-work-review/references/framework-human-input-form-api.md +47 -12
- package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +30 -19
- package/dist/knowledge/skills/application-consumer-documentation-authoring/references/framework-documentation-chapters-api.md +48 -13
- package/dist/knowledge/skills/application-consumer-documentation-authoring/references/source-and-ownership-routing.md +2 -2
- package/dist/knowledge/skills/application-database-migrations/SKILL.md +10 -11
- package/dist/knowledge/skills/application-database-migrations/references/postgresql-supported-surfaces.md +64 -0
- package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +13 -11
- package/dist/knowledge/skills/application-roles-authoring/SKILL.md +28 -3
- package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +18 -1
- package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +22 -1
- package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +46 -2
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-assigned-rows-declaration-api.md +5 -3
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-organization-identity-declaration-api.md +247 -0
- package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-own-rows-declaration-api.md +12 -5
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +6 -0
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +31 -2
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +51 -14
- package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +4 -1
- package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +95 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +2 -2
- package/dist/knowledge/skills/backend-custom-operation/references/framework-core-write-precondition-api.md +73 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-error-handling-api.md +5 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-external-effect-reservation-api.md +276 -0
- package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +79 -0
- package/dist/knowledge/skills/blueprint-authoring/SKILL.md +4 -2
- package/dist/knowledge/skills/brand-name-screening/SKILL.md +13 -2
- package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +30 -3
- package/dist/knowledge/skills/chat-agent-conversations/SKILL.md +3 -0
- package/dist/knowledge/skills/chat-agent-conversations/references/framework-chat-conversations-api.md +13 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +45 -4
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +17 -7
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +859 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +6 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-subject-data-recipients.md +2 -0
- package/dist/knowledge/skills/config-app-shell/SKILL.md +5 -1
- package/dist/knowledge/skills/config-app-shell/references/framework-command-menu-omnibox-api.md +3 -3
- package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +4 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +1 -1
- package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +8 -7
- package/dist/knowledge/skills/config-design-system/references/framework-theme-composition-api.md +44 -1
- package/dist/knowledge/skills/config-navigation/SKILL.md +2 -0
- package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +5 -0
- package/dist/knowledge/skills/config-navigation/references/one-entry-per-concept.md +101 -0
- package/dist/knowledge/skills/config-saas/SKILL.md +2 -2
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +40 -3
- package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +20 -1
- package/dist/knowledge/skills/config-saas/references/framework-capability-resolution-api.md +75 -11
- package/dist/knowledge/skills/config-saas/references/framework-connection-target-credentials.md +21 -19
- package/dist/knowledge/skills/config-saas/references/framework-content-security-policy-api.md +26 -9
- package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +197 -9
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +16 -2
- package/dist/knowledge/skills/config-saas/references/framework-systems-of-record-api.md +116 -16
- package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +20 -18
- package/dist/knowledge/skills/config-saas/references/saas-config-scope.md +1 -1
- package/dist/knowledge/skills/config-saas-backend/SKILL.md +11 -1
- package/dist/knowledge/skills/config-saas-backend/references/framework-backend-authored-config-api.md +5 -1
- package/dist/knowledge/skills/config-saas-backend/references/framework-declared-type-renames-api.md +261 -0
- package/dist/knowledge/skills/config-saas-backend/references/framework-organization-types-api.md +20 -0
- package/dist/knowledge/skills/config-saas-backend/references/renaming-organization-and-user-types.md +69 -0
- package/dist/knowledge/skills/configure-billing/SKILL.md +6 -0
- package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +28 -4
- package/dist/knowledge/skills/configure-billing/references/framework-backend-provider-reachability-api.md +2 -0
- package/dist/knowledge/skills/configure-billing/references/framework-subscription-behavior-policy.md +4 -1
- package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +131 -0
- package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +61 -0
- package/dist/knowledge/skills/email-add-template/SKILL.md +1 -1
- package/dist/knowledge/skills/email-add-template/references/framework-email-attachments-and-limits.md +11 -8
- package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +3 -2
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +31 -9
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-a2a-token-budget-api.md +11 -4
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +26 -3
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +1 -1
- package/dist/knowledge/skills/flows-actors-autonomous-agents/references/binding-and-review.md +27 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +18 -7
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +8 -5
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-behavior-reports-api.md +13 -9
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +44 -4
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-operation-record-api.md +7 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-suspension-api.md +11 -9
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-audit-agent-attribution-api.md +21 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-decision-deadlines-api.md +3 -3
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-realtime-catalog.md +7 -1
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +375 -8
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +30 -1
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-model-spend-limits-api.md +36 -15
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-tool-dispatch-obligations-api.md +8 -0
- package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +1 -1
- package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-flow-model-api.md +21 -2
- package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +2 -1
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +1 -1
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +33 -1
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +5 -3
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +3 -3
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +37 -14
- package/dist/knowledge/skills/guidance-onboarding-authoring/references/framework-guidance-flow-api.md +1 -1
- package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +39 -0
- package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +39 -0
- package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +31 -2
- package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +39 -0
- package/dist/knowledge/skills/i18n-translation-rerun/references/framework-translation-glossary-api.md +87 -0
- package/dist/knowledge/skills/inbound-channels/SKILL.md +31 -9
- package/dist/knowledge/skills/inbound-channels/references/email-channel.md +16 -4
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-channel-api.md +169 -23
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +38 -1
- package/dist/knowledge/skills/inbound-channels/references/inbound-delivery-lifecycle.md +43 -4
- package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +15 -3
- package/dist/knowledge/skills/inbound-channels/references/sms-channel.md +93 -0
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +125 -77
- package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +12 -14
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +133 -8
- package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +0 -1
- package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +84 -8
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-authoring-api.md +1 -1
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-focal-plane-settings-api.md +16 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-frame-style-overrides-api.md +72 -0
- package/dist/knowledge/skills/layout-3d-adoption/references/manual-adoption-and-removal.md +2 -2
- package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +12 -9
- package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +3 -3
- package/dist/knowledge/skills/local-environment-bootstrap/references/framework-upgrade-and-dependency-alignment.md +2 -2
- package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +18 -10
- package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +7 -7
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +24 -2
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +33 -2
- package/dist/knowledge/skills/market-generation-cli/SKILL.md +47 -6
- package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +61 -8
- package/dist/knowledge/skills/model-cost-attribution/SKILL.md +3 -1
- package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-pricing-api.md +1 -1
- package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +107 -42
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +1 -0
- package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +21 -2
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +30 -1
- package/dist/knowledge/skills/module-relationships/SKILL.md +92 -91
- package/dist/knowledge/skills/organization-relationships/references/framework-organization-relationships-api.md +31 -5
- package/dist/knowledge/skills/organization-relationships/references/framework-relationship-grantor-authentication-api.md +2 -2
- package/dist/knowledge/skills/organization-relationships/references/framework-relationship-kinds-api.md +34 -0
- package/dist/knowledge/skills/organization-relationships/references/framework-relationship-record-separation-api.md +1 -0
- package/dist/knowledge/skills/organization-relationships/references/framework-representative-activity-api.md +4 -0
- package/dist/knowledge/skills/professional-qualifications/references/framework-operation-approval-requirement-api.md +31 -0
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +255 -12
- package/dist/knowledge/skills/provider-backend-package/references/framework-optional-runtime-peers.md +4 -5
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-compliance-state-collector-api.md +96 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-configuration-check-api.md +130 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-file-storage-adapter-api.md +8 -1
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-inbound-endpoint-api.md +124 -3
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-incremental-consent-api.md +165 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-loader-api.md +6 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-processing-region-api.md +340 -0
- package/dist/knowledge/skills/provider-backend-package/references/framework-provider-shared-connection-api.md +11 -6
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
- package/dist/knowledge/skills/provider-frontend-module/SKILL.md +5 -2
- package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +1 -1
- package/dist/knowledge/skills/provider-operation-calls/SKILL.md +17 -3
- package/dist/knowledge/skills/provider-operation-calls/references/framework-rest-operation-contract-api.md +1035 -19
- package/dist/knowledge/skills/resource-add-field/SKILL.md +7 -0
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +322 -15
- package/dist/knowledge/skills/resource-add-resource/SKILL.md +9 -5
- package/dist/knowledge/skills/resource-add-resource/references/framework-engine-api-reference-categories-api.md +119 -0
- package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +107 -42
- package/dist/knowledge/skills/resource-chat-commands/SKILL.md +2 -1
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +71 -5
- package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +2 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-approval-api.md +48 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +33 -7
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-bulk-api.md +15 -11
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-idempotency-key-api.md +66 -27
- package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +140 -58
- package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +7 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-role-ceiling-api.md +34 -10
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +5 -4
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +158 -138
- package/dist/knowledge/skills/resource-config-wiring/references/framework-scope-admissions-api.md +52 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +205 -19
- package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +253 -25
- package/dist/knowledge/skills/resource-custom-view/SKILL.md +126 -1
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +259 -15
- package/dist/knowledge/skills/resource-custom-view/references/framework-backend-refusal-api.md +110 -0
- package/dist/knowledge/skills/resource-external-data/SKILL.md +46 -12
- package/dist/knowledge/skills/resource-external-data/references/bidirectional-pipelines.md +1 -1
- package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +15 -8
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +19 -8
- package/dist/knowledge/skills/resource-external-data/references/framework-system-of-record-capabilities-api.md +3 -1
- package/dist/knowledge/skills/resource-external-data/references/local-test-doubles.md +121 -0
- package/dist/knowledge/skills/resource-external-data/references/outbound-pipelines.md +1 -1
- package/dist/knowledge/skills/resource-external-data/references/partition-from-the-domain-plan.md +230 -0
- package/dist/knowledge/skills/resource-external-data/references/presenting-a-copy-and-a-read-through.md +73 -0
- package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +26 -5
- package/dist/knowledge/skills/resource-external-data/references/system-of-record-actions.md +76 -6
- package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +8 -0
- package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +12 -9
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +11 -2
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +29 -2
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-source-decorator-api.md +20 -20
- package/dist/knowledge/skills/resource-retention-binding/SKILL.md +18 -2
- package/dist/knowledge/skills/resource-retention-binding/references/framework-legal-holds-api.md +46 -2
- package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-binding-api.md +84 -1
- package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-enforcement-records-api.md +10 -0
- package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-schedule-api.md +5 -3
- package/dist/knowledge/skills/resource-retention-binding/references/framework-statutory-retention-api.md +21 -0
- package/dist/knowledge/skills/resource-retention-binding/references/start-point-decisions.md +14 -2
- package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +1 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +4 -1
- package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +78 -17
- package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +2 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +26 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +46 -46
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +17 -2
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +36 -24
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +63 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +104 -23
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +123 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +1 -0
- package/dist/knowledge/skills/resource-schema-authoring/references/special-factories.md +72 -0
- package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +42 -2
- package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +67 -0
- package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +16 -12
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +66 -3
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +89 -10
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +11 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +263 -17
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-record-page-parts-api.md +155 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +83 -16
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +44 -10
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-section-stages-api.md +102 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/record-page-anatomy.md +9 -2
- package/dist/knowledge/skills/resource-ui-behavior/references/surface-decisions.md +33 -2
- package/dist/knowledge/skills/resource-ui-behavior/references/visual-quality-rubric.md +19 -2
- package/dist/knowledge/skills/resource-ui-behavior/references/workflow-record-page.md +264 -0
- package/dist/knowledge/skills/seeding-authoring/SKILL.md +24 -4
- package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +12 -0
- package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +7 -6
- package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +6 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +42 -0
- package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +6 -9
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +1 -0
- package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +21 -2
- package/dist/knowledge/skills/spec-resource-update/SKILL.md +26 -0
- package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +121 -75
- package/dist/knowledge/skills/spec-resource-update/references/workflow-record-page-specification.md +237 -0
- package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +100 -71
- package/dist/knowledge/skills/subject-data-export/SKILL.md +176 -0
- package/dist/knowledge/skills/subject-data-export/references/file-content-exclusions.md +15 -0
- package/dist/knowledge/skills/subject-data-export/references/framework-subject-export-api.md +142 -0
- package/dist/knowledge/skills/subject-data-export/references/framework-subject-export-archive-api.md +33 -0
- package/dist/knowledge/skills/views-app-level/SKILL.md +3 -1
- package/dist/knowledge/skills/views-app-level/references/workflow-home.md +373 -0
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +36 -5
- package/dist/knowledge/skills/views-chart-authoring/references/framework-resource-chart-data-api.md +9 -5
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +4 -0
- package/dist/knowledge/skills/views-composite-authoring/references/framework-chart-dashboard-api.md +244 -0
- package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +40 -0
- package/dist/knowledge/skills/website-blog-authoring/SKILL.md +8 -6
- package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +70 -59
- package/dist/knowledge/skills/website-building-blocks/SKILL.md +1 -1
- package/dist/knowledge/skills/website-building-blocks/references/framework-website-demo-examples.md +3 -3
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +4 -2
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +3 -1
- package/dist/knowledge/skills/website-label-pack/SKILL.md +20 -5
- package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +6 -3
- package/dist/knowledge/skills/website-section-comparison/SKILL.md +2 -2
- package/dist/knowledge/skills/website-section-contact/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-cta/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-faq/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-hero/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-how-it-works/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-integrations/SKILL.md +3 -3
- package/dist/knowledge/skills/website-section-latest-posts/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-pricing/SKILL.md +142 -98
- package/dist/knowledge/skills/website-section-pricing/examples/pricing-offers.example.md +178 -66
- package/dist/knowledge/skills/website-section-pricing/references/framework-pricing-catalog-api.md +3 -1
- package/dist/knowledge/skills/website-section-problem/SKILL.md +3 -3
- package/dist/knowledge/skills/website-section-product-showcase/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-roadmap/SKILL.md +4 -4
- package/dist/knowledge/skills/website-section-social-proof/SKILL.md +1 -1
- package/dist/knowledge/skills/website-section-solution-paths/SKILL.md +2 -2
- package/dist/knowledge/skills/website-section-stats/SKILL.md +3 -3
- package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +3 -2
- package/dist/knowledge/skills/worker-authoring/SKILL.md +4 -2
- package/dist/knowledge/topic-index.json +2275 -715
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +6 -6
- package/dist/tsconfig.tsbuildinfo +0 -1
|
@@ -8,6 +8,539 @@
|
|
|
8
8
|
|
|
9
9
|
### Origin Package: `@wildo-ai/external-connectors-models`
|
|
10
10
|
|
|
11
|
+
```typescript
|
|
12
|
+
/**
|
|
13
|
+
* The GraphQL document a provider operation sends (#3392), set as `ProviderRestOperation.graphql`.
|
|
14
|
+
*
|
|
15
|
+
* With it the operation is a GraphQL call: `method` must be `POST`, `pathTemplate` is the vendor's GraphQL endpoint
|
|
16
|
+
* (`/graphql`), and the operation's input IS the variables. So it may declare no `requestBody`, and no parameter fed by
|
|
17
|
+
* the input (a `constantValue` header or path parameter, such as a pinned API version, is allowed). `inputSchema`
|
|
18
|
+
* describes the variables, one top-level field per variable the document declares, and `inputOptions` work on them as on
|
|
19
|
+
* any input. `resultPath` and `outputSchema` read the answer's `data`, never the `{ data, errors }` envelope around it.
|
|
20
|
+
* `responseDecoding` stays JSON.
|
|
21
|
+
*
|
|
22
|
+
* Checked when the catalogue loads, at publish and on every call ({@link describeProviderRestOperationGraphqlDefects}).
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* // GitHub: a repository's discussions, which GitHub serves through GraphQL only.
|
|
26
|
+
* {
|
|
27
|
+
* operationId: 'github_issues_list_discussions', domain: 'default', method: API_HttpMethod.POST, pathTemplate: '/graphql',
|
|
28
|
+
* classification: ExternalOperation_Classification.READ,
|
|
29
|
+
* graphql: {
|
|
30
|
+
* operationName: 'ListDiscussions',
|
|
31
|
+
* document: 'query ListDiscussions($owner: String!, $repo: String!, $first: Int!) { repository(owner: $owner, name: $repo) { discussions(first: $first) { nodes { number title } } } }',
|
|
32
|
+
* },
|
|
33
|
+
* inputSchema: z.strictObject({ owner: z.string(), repo: z.string(), first: z.number().int() }),
|
|
34
|
+
* resultPath: 'repository.discussions',
|
|
35
|
+
* }
|
|
36
|
+
*/
|
|
37
|
+
export interface ProviderRestOperationGraphql {
|
|
38
|
+
/**
|
|
39
|
+
* The executable document, owned by the provider: exactly ONE operation (a `query` or a `mutation`, named
|
|
40
|
+
* {@link operationName}) and any fragments it uses. A `query` is a READ operation and a `mutation` a WRITE; a
|
|
41
|
+
* `subscription` is refused, since it is not answered over a single POST.
|
|
42
|
+
*/
|
|
43
|
+
readonly document: string;
|
|
44
|
+
/** The operation's name in {@link document}, sent as `operationName`. */
|
|
45
|
+
readonly operationName: string;
|
|
46
|
+
/**
|
|
47
|
+
* Dot path, inside EACH error of the answer's `errors` list, to the vendor's machine-readable code (`extensions.code`
|
|
48
|
+
* by convention, where a vendor uses it). The specification standardizes no code, so absent, no code is read and the
|
|
49
|
+
* failure carries the vendor's messages only. A code is kept only when it is code-shaped, as every vendor code is.
|
|
50
|
+
*/
|
|
51
|
+
readonly errorCodePath?: string;
|
|
52
|
+
/**
|
|
53
|
+
* The codes, read at {@link errorCodePath}, that mean the vendor refused the CREDENTIAL itself rather than the request
|
|
54
|
+
* (#3392): the stored credential is then recorded as rejected, as a REST vendor's
|
|
55
|
+
* `applicationOutcome.credentialRefusedErrorCodes` records it. A GraphQL vendor may name a dead or expired token inside
|
|
56
|
+
* a 200 (an error list beside or instead of `data`) or inside a 4xx carrying the same error list, and both are read.
|
|
57
|
+
* The failure itself is unchanged: the call fails with the vendor's code and is never retried.
|
|
58
|
+
*
|
|
59
|
+
* List only a code the vendor DOCUMENTS as a refused credential. A code for a resource the credential may not reach
|
|
60
|
+
* (`FORBIDDEN` on one repository), for a missing scope, or for a request sent with no credential at all, does not
|
|
61
|
+
* belong here: the credential still works, and recording it rejected would show a working connection as broken.
|
|
62
|
+
* Requires {@link errorCodePath}, without which no code is read and none could match.
|
|
63
|
+
*
|
|
64
|
+
* @example
|
|
65
|
+
* // monday.com answers a key it refuses with the error code `Unauthorized`, whose documented resolution is a valid key.
|
|
66
|
+
* // spec-cite: https://developer.monday.com/api-reference/docs/errors — the `Unauthorized` row (HTTP 401, resolution
|
|
67
|
+
* // "Input a valid API key."), fetched 2026-11-09.
|
|
68
|
+
* graphql: { operationName: 'CreateItem', document: CREATE_ITEM, errorCodePath: 'extensions.code', credentialRefusedErrorCodes: ['Unauthorized'] }
|
|
69
|
+
*/
|
|
70
|
+
readonly credentialRefusedErrorCodes?: readonly string[];
|
|
71
|
+
/**
|
|
72
|
+
* Where a MUTATION's answer says the vendor refused it in the DATA rather than in `errors` (follow-up to #3392). Several
|
|
73
|
+
* GraphQL vendors answer a write they refused with a successful response whose payload carries the refusal: Shopify's
|
|
74
|
+
* `userErrors` list ("validation failures, such as invalid field values or business logic violations, that prevent the
|
|
75
|
+
* operation from completing"), Linear's `success: Boolean!`. Without it such an answer is returned as the result and a
|
|
76
|
+
* caller that does not read the payload takes a refused write for a done one; with it the call FAILS, carrying the
|
|
77
|
+
* vendor's messages, exactly as an `errors` entry does. See {@link ProviderGraphqlPayloadRefusal}.
|
|
78
|
+
* spec-cite: https://shopify.dev/docs/api/admin-graphql — the `UserError` description quoted above, fetched 2026-11-10.
|
|
79
|
+
*
|
|
80
|
+
* @example
|
|
81
|
+
* // Shopify: productCreate's userErrors, each `{ field, message }`.
|
|
82
|
+
* payloadRefusal: { kind: ProviderGraphqlPayloadRefusalKind.USER_ERRORS, path: 'productCreate.userErrors', messagePath: 'message', fieldPath: 'field' }
|
|
83
|
+
*/
|
|
84
|
+
readonly payloadRefusal?: ProviderGraphqlPayloadRefusal;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** How a mutation's payload states a refusal. See {@link ProviderRestOperationGraphql.payloadRefusal}. */
|
|
88
|
+
export enum ProviderGraphqlPayloadRefusalKind {
|
|
89
|
+
/** A list of the vendor's refusals (Shopify's `userErrors`): the write was refused when the list is not empty. */
|
|
90
|
+
USER_ERRORS = 'user_errors',
|
|
91
|
+
/** A boolean the vendor sets to `false` when it did not do the write (Linear's `success`). */
|
|
92
|
+
SUCCESS_FLAG = 'success_flag',
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Where a mutation's payload states a refusal (follow-up to #3392). Every path is a dot path, `path` from the answer's
|
|
97
|
+
* `data` (as `resultPath` is), `messagePath`, `fieldPath` and `codePath` from inside each listed refusal.
|
|
98
|
+
*
|
|
99
|
+
* - {@link ProviderGraphqlPayloadRefusalKind.USER_ERRORS}: a non-empty list at `path` fails the call. Each entry's text at
|
|
100
|
+
* `messagePath` (`message` when absent) is kept, prefixed with the input field it names at `fieldPath` (a string or a
|
|
101
|
+
* list of path segments), and the first code-shaped value at `codePath` is the failure's code.
|
|
102
|
+
* - {@link ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG}: `false` at `path` fails the call.
|
|
103
|
+
*
|
|
104
|
+
* Anything else at `path` (an absent payload, `true`, an empty list) refuses nothing: the answer is read as it is.
|
|
105
|
+
*/
|
|
106
|
+
export type ProviderGraphqlPayloadRefusal =
|
|
107
|
+
| {
|
|
108
|
+
readonly kind: ProviderGraphqlPayloadRefusalKind.USER_ERRORS;
|
|
109
|
+
readonly path: string;
|
|
110
|
+
readonly messagePath?: string;
|
|
111
|
+
readonly fieldPath?: string;
|
|
112
|
+
readonly codePath?: string;
|
|
113
|
+
}
|
|
114
|
+
| { readonly kind: ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG; readonly path: string };
|
|
115
|
+
|
|
116
|
+
/** What a GraphQL document's operation does. A `subscription` is not served over a single POST, so it is no member. */
|
|
117
|
+
export enum ProviderGraphqlOperationType {
|
|
118
|
+
/** Reads. The operation must be classified READ. */
|
|
119
|
+
QUERY = 'query',
|
|
120
|
+
/** Changes the vendor. The operation must be classified WRITE. */
|
|
121
|
+
MUTATION = 'mutation',
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* The `Accept` a GraphQL call sends: the GraphQL response media type first, `application/json` for a server that predates
|
|
126
|
+
* it (GraphQL over HTTP §4.2, quoted in this module's header).
|
|
127
|
+
* semantic-literal-boundary: the media types GraphQL over HTTP names, sent on the wire.
|
|
128
|
+
*/
|
|
129
|
+
export const PROVIDER_GRAPHQL_ACCEPT_HEADER = 'application/graphql-response+json, application/json;q=0.9';
|
|
130
|
+
|
|
131
|
+
/** At most this many of the vendor's error messages are kept on a failure. */
|
|
132
|
+
export const PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES = 10;
|
|
133
|
+
/** A kept error message is cut at this many characters. */
|
|
134
|
+
export const PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH = 500;
|
|
135
|
+
|
|
136
|
+
/** One operation a document defines, as {@link readProviderGraphqlDocument} reads it. */
|
|
137
|
+
export interface ProviderGraphqlDocumentOperation {
|
|
138
|
+
/** `query`, `mutation` or `subscription`, as written (an anonymous `{ … }` is a query). */
|
|
139
|
+
readonly type: string;
|
|
140
|
+
/** Absent for an anonymous operation. */
|
|
141
|
+
readonly name?: string;
|
|
142
|
+
/** The variables it declares, without their `$`, in order. */
|
|
143
|
+
readonly variables: readonly string[];
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** What a document holds, or why it cannot be read. */
|
|
147
|
+
export interface ProviderGraphqlDocumentShape {
|
|
148
|
+
readonly operations: readonly ProviderGraphqlDocumentOperation[];
|
|
149
|
+
/** Set when the text is not a document of executable definitions. `operations` is then what was read before it. */
|
|
150
|
+
readonly defect?: string;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
|
|
154
|
+
const GRAPHQL_PUNCTUATORS = new Set(['!', '$', '&', '(', ')', ':', '=', '@', '[', ']', '{', '|', '}']);
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* The tokens of a GraphQL document, with strings and comments dropped: enough to find its definitions and their
|
|
158
|
+
* variables. Not a validating parser: the vendor's server is the parser that decides, and this only has to see the
|
|
159
|
+
* document's outline. A block string (`"""…"""`) and a string (`"…"`, with `\` escapes) are skipped whole, so a brace or
|
|
160
|
+
* a `$` inside one is never read as structure. `undefined` for a string that never closes.
|
|
161
|
+
*/
|
|
162
|
+
function tokenizeGraphqlDocument(document: string): string[] | undefined {
|
|
163
|
+
const tokens: string[] = [];
|
|
164
|
+
let index = 0;
|
|
165
|
+
while (index < document.length) {
|
|
166
|
+
const character = document[index]!;
|
|
167
|
+
if (character === '#') {
|
|
168
|
+
while (index < document.length && document[index] !== '\n' && document[index] !== '\r') index += 1;
|
|
169
|
+
continue;
|
|
170
|
+
}
|
|
171
|
+
if (character === '"') {
|
|
172
|
+
if (document.startsWith('"""', index)) {
|
|
173
|
+
const close = document.indexOf('"""', index + 3);
|
|
174
|
+
// A `\"""` inside a block string is an escaped delimiter, not its end.
|
|
175
|
+
let end = close;
|
|
176
|
+
while (end !== -1 && document[end - 1] === '\\') end = document.indexOf('"""', end + 3);
|
|
177
|
+
if (end === -1) return undefined;
|
|
178
|
+
index = end + 3;
|
|
179
|
+
} else {
|
|
180
|
+
index += 1;
|
|
181
|
+
while (index < document.length && document[index] !== '"') {
|
|
182
|
+
if (document[index] === '\n') return undefined;
|
|
183
|
+
index += document[index] === '\\' ? 2 : 1;
|
|
184
|
+
}
|
|
185
|
+
if (index >= document.length) return undefined;
|
|
186
|
+
index += 1;
|
|
187
|
+
}
|
|
188
|
+
tokens.push('"');
|
|
189
|
+
continue;
|
|
190
|
+
}
|
|
191
|
+
if (character === '.' && document.startsWith('...', index)) {
|
|
192
|
+
tokens.push('...');
|
|
193
|
+
index += 3;
|
|
194
|
+
continue;
|
|
195
|
+
}
|
|
196
|
+
if (GRAPHQL_PUNCTUATORS.has(character)) {
|
|
197
|
+
tokens.push(character);
|
|
198
|
+
index += 1;
|
|
199
|
+
continue;
|
|
200
|
+
}
|
|
201
|
+
if (/[_A-Za-z0-9.+-]/.test(character)) {
|
|
202
|
+
let end = index + 1;
|
|
203
|
+
while (end < document.length && /[_A-Za-z0-9.+-]/.test(document[end]!)) end += 1;
|
|
204
|
+
tokens.push(document.slice(index, end));
|
|
205
|
+
index = end;
|
|
206
|
+
continue;
|
|
207
|
+
}
|
|
208
|
+
// White space, commas (insignificant in GraphQL) and the byte order mark.
|
|
209
|
+
index += 1;
|
|
210
|
+
}
|
|
211
|
+
return tokens;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* The executable definitions of a GraphQL document (#3392): each operation's type, name and declared variables. A
|
|
216
|
+
* fragment is skipped; a type-system definition (`type`, `schema`, …) is a defect, since a document sent to a server is
|
|
217
|
+
* executable only.
|
|
218
|
+
*/
|
|
219
|
+
export function readProviderGraphqlDocument(document: string): ProviderGraphqlDocumentShape {
|
|
220
|
+
const tokens = tokenizeGraphqlDocument(document);
|
|
221
|
+
if (tokens === undefined) return { operations: [], defect: 'a string in it never closes' };
|
|
222
|
+
const operations: ProviderGraphqlDocumentOperation[] = [];
|
|
223
|
+
let index = 0;
|
|
224
|
+
/** Skips the balanced block opening at `index` (a `{` or a `(`), and answers the index after it, or -1. */
|
|
225
|
+
const skipBalanced = (open: string, close: string): number => {
|
|
226
|
+
let depth = 0;
|
|
227
|
+
for (let position = index; position < tokens.length; position += 1) {
|
|
228
|
+
if (tokens[position] === open) depth += 1;
|
|
229
|
+
else if (tokens[position] === close) {
|
|
230
|
+
depth -= 1;
|
|
231
|
+
if (depth === 0) return position + 1;
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
return -1;
|
|
235
|
+
};
|
|
236
|
+
while (index < tokens.length) {
|
|
237
|
+
const token = tokens[index]!;
|
|
238
|
+
if (token === '{') {
|
|
239
|
+
const after = skipBalanced('{', '}');
|
|
240
|
+
if (after === -1) return { operations, defect: 'a selection set never closes' };
|
|
241
|
+
operations.push({ type: 'query', variables: [] });
|
|
242
|
+
index = after;
|
|
243
|
+
continue;
|
|
244
|
+
}
|
|
245
|
+
if (token === 'query' || token === 'mutation' || token === 'subscription') {
|
|
246
|
+
index += 1;
|
|
247
|
+
const name = tokens[index] !== undefined && GRAPHQL_NAME.test(tokens[index]!) ? tokens[index] : undefined;
|
|
248
|
+
if (name !== undefined) index += 1;
|
|
249
|
+
const variables: string[] = [];
|
|
250
|
+
if (tokens[index] === '(') {
|
|
251
|
+
const after = skipBalanced('(', ')');
|
|
252
|
+
if (after === -1) return { operations, defect: `the variable definitions of ${name ?? 'an operation'} never close` };
|
|
253
|
+
// A definition is `$name :`; a default value is constant and holds no variable.
|
|
254
|
+
for (let position = index; position < after - 2; position += 1) {
|
|
255
|
+
if (tokens[position] === '$' && tokens[position + 2] === ':' && GRAPHQL_NAME.test(tokens[position + 1]!)) variables.push(tokens[position + 1]!);
|
|
256
|
+
}
|
|
257
|
+
index = after;
|
|
258
|
+
}
|
|
259
|
+
while (index < tokens.length && tokens[index] !== '{') index += 1;
|
|
260
|
+
if (index >= tokens.length) return { operations, defect: `${name ?? 'an operation'} has no selection set` };
|
|
261
|
+
const after = skipBalanced('{', '}');
|
|
262
|
+
if (after === -1) return { operations, defect: `the selection set of ${name ?? 'an operation'} never closes` };
|
|
263
|
+
operations.push({ type: token, ...(name === undefined ? {} : { name }), variables });
|
|
264
|
+
index = after;
|
|
265
|
+
continue;
|
|
266
|
+
}
|
|
267
|
+
if (token === 'fragment') {
|
|
268
|
+
while (index < tokens.length && tokens[index] !== '{') index += 1;
|
|
269
|
+
if (index >= tokens.length) return { operations, defect: 'a fragment has no selection set' };
|
|
270
|
+
const after = skipBalanced('{', '}');
|
|
271
|
+
if (after === -1) return { operations, defect: 'a fragment\'s selection set never closes' };
|
|
272
|
+
index = after;
|
|
273
|
+
continue;
|
|
274
|
+
}
|
|
275
|
+
return { operations, defect: `'${token}' begins no executable definition (an operation or a fragment)` };
|
|
276
|
+
}
|
|
277
|
+
return { operations };
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* The top-level fields an input schema declares, read through Zod's own definition (`_zod.def`) as the input-options
|
|
282
|
+
* check reads it, so a module built against another copy of Zod is read the same. Wrappers that keep the value's shape
|
|
283
|
+
* are seen through; a union declares what any of its options declares. `undefined` when the schema is not an object
|
|
284
|
+
* (or a union of objects), so its fields cannot be listed.
|
|
285
|
+
*/
|
|
286
|
+
function inputSchemaTopLevelFields(schema: unknown): Set<string> | undefined {
|
|
287
|
+
let current: unknown = schema;
|
|
288
|
+
for (let depth = 0; depth < 64; depth += 1) {
|
|
289
|
+
const def = (current as { _zod?: { def?: Record<string, unknown> } } | undefined)?._zod?.def;
|
|
290
|
+
if (def === undefined) return undefined;
|
|
291
|
+
switch (def.type) {
|
|
292
|
+
case 'optional': case 'nullable': case 'default': case 'prefault': case 'readonly': case 'catch': case 'nonoptional':
|
|
293
|
+
current = def.innerType;
|
|
294
|
+
continue;
|
|
295
|
+
case 'pipe':
|
|
296
|
+
current = def.in;
|
|
297
|
+
continue;
|
|
298
|
+
case 'lazy':
|
|
299
|
+
current = typeof def.getter === 'function' ? (def.getter as () => unknown)() : undefined;
|
|
300
|
+
continue;
|
|
301
|
+
case 'object':
|
|
302
|
+
return new Set(Object.keys((def.shape as Record<string, unknown> | undefined) ?? {}));
|
|
303
|
+
case 'union': {
|
|
304
|
+
const fields = new Set<string>();
|
|
305
|
+
for (const option of Array.isArray(def.options) ? def.options : []) {
|
|
306
|
+
const optionFields = inputSchemaTopLevelFields(option);
|
|
307
|
+
if (optionFields === undefined) return undefined;
|
|
308
|
+
for (const field of optionFields) fields.add(field);
|
|
309
|
+
}
|
|
310
|
+
return fields;
|
|
311
|
+
}
|
|
312
|
+
default:
|
|
313
|
+
return undefined;
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
return undefined;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/**
|
|
320
|
+
* Why a GraphQL operation cannot be sent as declared, or an empty list (#3392). Empty for an operation without
|
|
321
|
+
* `graphql`. Checked where a catalogue loads (the operation executor, an augmentation merge), at `wildo registry publish`,
|
|
322
|
+
* and by the request compiler on every call, so the one rule refuses in every place:
|
|
323
|
+
*
|
|
324
|
+
* - the call is a POST with no `requestBody`, every parameter carries a `constantValue` (the input is the variables
|
|
325
|
+
* and nothing else), and the answer is read as JSON;
|
|
326
|
+
* - the document reads as exactly ONE operation, named `operationName`, beside any fragments;
|
|
327
|
+
* - a `query` is classified READ and a `mutation` WRITE; a `subscription` is refused;
|
|
328
|
+
* - each declared variable is a top-level field of `inputSchema`, and each top-level field is a declared variable, so no
|
|
329
|
+
* value a caller supplies is silently dropped (when `inputSchema` lists its fields; without one, the call refuses a
|
|
330
|
+
* value for a variable the document does not declare);
|
|
331
|
+
* - `errorCodePath` is a dot path;
|
|
332
|
+
* - each of `credentialRefusedErrorCodes` is code-shaped (a value of any other shape is never kept, so it could never
|
|
333
|
+
* match), and the list comes with an `errorCodePath` to read the code at;
|
|
334
|
+
* - a `payloadRefusal` belongs to a mutation, names a kind of its vocabulary, and reads every path as a dot path.
|
|
335
|
+
*/
|
|
336
|
+
export function describeProviderRestOperationGraphqlDefects(
|
|
337
|
+
operation: Pick<
|
|
338
|
+
ProviderRestOperation,
|
|
339
|
+
'operationId' | 'method' | 'classification' | 'parameters' | 'requestBody' | 'responseDecoding' | 'binaryResponse' | 'inputSchema' | 'graphql'
|
|
340
|
+
>,
|
|
341
|
+
): string[] {
|
|
342
|
+
const graphql = operation.graphql;
|
|
343
|
+
if (graphql === undefined) return [];
|
|
344
|
+
const at = `GraphQL operation '${operation.operationId}'`;
|
|
345
|
+
const defects: string[] = [];
|
|
346
|
+
if (operation.method !== API_HttpMethod.POST) defects.push(`${at} is sent with ${operation.method}; a GraphQL call is a POST`);
|
|
347
|
+
if (operation.requestBody !== undefined) defects.push(`${at} declares a requestBody; its body is the document and its variables`);
|
|
348
|
+
for (const parameter of operation.parameters ?? []) {
|
|
349
|
+
if (parameter.constantValue === undefined) {
|
|
350
|
+
defects.push(`${at} declares the ${parameter.in} parameter '${parameter.name}' fed by the input; its input is the document's variables only, so a parameter must carry a constantValue`);
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
if (operation.responseDecoding !== undefined && operation.responseDecoding !== ProviderRestResponseDecoding.JSON) defects.push(`${at} reads its answer as ${operation.responseDecoding}; a GraphQL answer is JSON`);
|
|
354
|
+
if (operation.binaryResponse !== undefined) defects.push(`${at} declares binaryResponse; a GraphQL answer is JSON`);
|
|
355
|
+
if (!GRAPHQL_NAME.test(graphql.operationName)) defects.push(`${at} names the operation '${graphql.operationName}', which is not a GraphQL name`);
|
|
356
|
+
if (graphql.errorCodePath !== undefined && graphql.errorCodePath.split('.').some((segment) => segment.length === 0)) {
|
|
357
|
+
defects.push(`${at} reads its error code at '${graphql.errorCodePath}', which is not a dot path`);
|
|
358
|
+
}
|
|
359
|
+
const payloadRefusal = graphql.payloadRefusal;
|
|
360
|
+
if (payloadRefusal !== undefined) {
|
|
361
|
+
const kinds: readonly string[] = Object.values(ProviderGraphqlPayloadRefusalKind);
|
|
362
|
+
if (!kinds.includes(payloadRefusal.kind)) defects.push(`${at} declares the payload refusal kind ${JSON.stringify(payloadRefusal.kind)}, which is none of ${kinds.join(', ')}`);
|
|
363
|
+
const paths: [string, string | undefined][] = [['path', payloadRefusal.path]];
|
|
364
|
+
if (payloadRefusal.kind === ProviderGraphqlPayloadRefusalKind.USER_ERRORS) {
|
|
365
|
+
paths.push(['messagePath', payloadRefusal.messagePath], ['fieldPath', payloadRefusal.fieldPath], ['codePath', payloadRefusal.codePath]);
|
|
366
|
+
}
|
|
367
|
+
for (const [field, value] of paths) {
|
|
368
|
+
if (value === undefined && field !== 'path') continue;
|
|
369
|
+
if (typeof value !== 'string' || value.length === 0 || value.split('.').some((segment) => segment.length === 0)) {
|
|
370
|
+
defects.push(`${at} reads its payload refusal's ${field} at ${JSON.stringify(value)}, which is not a dot path`);
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
if (graphql.credentialRefusedErrorCodes !== undefined && graphql.errorCodePath === undefined) {
|
|
375
|
+
defects.push(`${at} lists credentialRefusedErrorCodes but no errorCodePath, so no code is read and none of them could ever match`);
|
|
376
|
+
}
|
|
377
|
+
for (const code of graphql.credentialRefusedErrorCodes ?? []) {
|
|
378
|
+
if (!PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(code)) {
|
|
379
|
+
defects.push(`${at} lists the credential-refusal code '${code}', which is not code-shaped and would never match a code the transport keeps`);
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
const shape = readProviderGraphqlDocument(graphql.document);
|
|
384
|
+
if (shape.defect !== undefined) {
|
|
385
|
+
defects.push(`${at}: its document does not read as a GraphQL document (${shape.defect})`);
|
|
386
|
+
return defects;
|
|
387
|
+
}
|
|
388
|
+
const named = shape.operations.filter((candidate) => candidate.name === graphql.operationName);
|
|
389
|
+
if (named.length !== 1 || shape.operations.length !== 1) {
|
|
390
|
+
defects.push(
|
|
391
|
+
`${at}: its document must define exactly one operation, named '${graphql.operationName}', and it defines `
|
|
392
|
+
+ `${shape.operations.length === 0 ? 'none' : shape.operations.map((candidate) => `${candidate.type} ${candidate.name ?? '(anonymous)'}`).join(', ')}`,
|
|
393
|
+
);
|
|
394
|
+
return defects;
|
|
395
|
+
}
|
|
396
|
+
const [definition] = named as [ProviderGraphqlDocumentOperation];
|
|
397
|
+
const expected = definition.type === ProviderGraphqlOperationType.QUERY ? ExternalOperation_Classification.READ
|
|
398
|
+
: definition.type === ProviderGraphqlOperationType.MUTATION ? ExternalOperation_Classification.WRITE
|
|
399
|
+
: undefined;
|
|
400
|
+
if (expected === undefined) defects.push(`${at} is a ${definition.type}, which is not answered over a single POST`);
|
|
401
|
+
// A refusal stated in a payload is a WRITE's: a query that answers data refused nothing.
|
|
402
|
+
if (graphql.payloadRefusal !== undefined && definition.type !== ProviderGraphqlOperationType.MUTATION) {
|
|
403
|
+
defects.push(`${at} is a ${definition.type} and declares a payload refusal, which only a mutation's payload states`);
|
|
404
|
+
}
|
|
405
|
+
else if (operation.classification !== expected) defects.push(`${at} is a ${definition.type} classified ${operation.classification}; a query is a READ and a mutation a WRITE`);
|
|
406
|
+
|
|
407
|
+
const fields = operation.inputSchema === undefined ? undefined : inputSchemaTopLevelFields(operation.inputSchema);
|
|
408
|
+
if (operation.inputSchema !== undefined && fields === undefined) {
|
|
409
|
+
defects.push(`${at} has an inputSchema that is not an object, and its input is the document's variables`);
|
|
410
|
+
}
|
|
411
|
+
if (fields !== undefined) {
|
|
412
|
+
for (const variable of definition.variables) {
|
|
413
|
+
if (!fields.has(variable)) defects.push(`${at} declares the variable '$${variable}', which its inputSchema does not declare`);
|
|
414
|
+
}
|
|
415
|
+
for (const field of fields) {
|
|
416
|
+
if (!definition.variables.includes(field)) defects.push(`${at}: its inputSchema declares '${field}', which is no variable of the document, so a value for it would never be sent`);
|
|
417
|
+
}
|
|
418
|
+
}
|
|
419
|
+
return defects;
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
/** The variables a GraphQL operation's document declares, or `undefined` when the document cannot be read. */
|
|
423
|
+
export function providerGraphqlOperationVariables(graphql: ProviderRestOperationGraphql): readonly string[] | undefined {
|
|
424
|
+
const shape = readProviderGraphqlDocument(graphql.document);
|
|
425
|
+
if (shape.defect !== undefined) return undefined;
|
|
426
|
+
return shape.operations.find((candidate) => candidate.name === graphql.operationName)?.variables;
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/** What a GraphQL answer says about the call. See the table in this module's header. */
|
|
430
|
+
export enum ProviderGraphqlResponseOutcomeKind {
|
|
431
|
+
/** `data` is an object and no error was reported. */
|
|
432
|
+
SUCCEEDED = 'succeeded',
|
|
433
|
+
/** Errors, and no `data` entry: the request was refused before anything executed. Nothing was applied. */
|
|
434
|
+
REQUEST_ERROR = 'request_error',
|
|
435
|
+
/** Errors beside a `data` entry (null or partial): execution began and something failed. */
|
|
436
|
+
EXECUTION_ERROR = 'execution_error',
|
|
437
|
+
/** Neither a `data` object nor an error list: the answer does not state what happened. */
|
|
438
|
+
UNSTATED = 'unstated',
|
|
439
|
+
/**
|
|
440
|
+
* `data` and no `errors`, and the mutation's payload states the vendor refused it (its declared `payloadRefusal`): the
|
|
441
|
+
* write was not done, as the vendor says (follow-up to #3392).
|
|
442
|
+
*/
|
|
443
|
+
PAYLOAD_REFUSED = 'payload_refused',
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
/** What {@link readProviderGraphqlResponse} read. */
|
|
447
|
+
export interface ProviderGraphqlResponseVerdict {
|
|
448
|
+
readonly kind: ProviderGraphqlResponseOutcomeKind;
|
|
449
|
+
/** On SUCCEEDED, the answer's `data` object: what the operation's `resultPath` and `outputSchema` read. */
|
|
450
|
+
readonly data?: Readonly<Record<string, unknown>>;
|
|
451
|
+
/**
|
|
452
|
+
* The vendor's error messages, in its order, at most {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES}, each cut at
|
|
453
|
+
* {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH} characters. Vendor prose: it may quote what the call sent, so it
|
|
454
|
+
* travels to the caller and is never written to a log or an audit row by the engine.
|
|
455
|
+
*/
|
|
456
|
+
readonly errorMessages?: readonly string[];
|
|
457
|
+
/** The first code-shaped value at the operation's `errorCodePath` among the errors, when one is declared and found. */
|
|
458
|
+
readonly errorCode?: string;
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
/** The value at a dot path, read through own properties only (an array's index is an own property), or `undefined`. */
|
|
462
|
+
function readGraphqlDotPath(value: unknown, path: string): unknown {
|
|
463
|
+
let current: unknown = value;
|
|
464
|
+
for (const segment of path.split('.')) {
|
|
465
|
+
if (current === null || typeof current !== 'object' || !Object.hasOwn(current, segment)) return undefined;
|
|
466
|
+
current = (current as Record<string, unknown>)[segment];
|
|
467
|
+
}
|
|
468
|
+
return current;
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
function readGraphqlErrorCode(error: unknown, errorCodePath: string): string | undefined {
|
|
472
|
+
const current = readGraphqlDotPath(error, errorCodePath);
|
|
473
|
+
return typeof current === 'string' && PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(current) ? current : undefined;
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
/** A vendor message as the verdict keeps it: cut at {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH}. */
|
|
477
|
+
function keptGraphqlMessage(message: string): string {
|
|
478
|
+
return message.length > PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH ? `${message.slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH)}…` : message;
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
/**
|
|
482
|
+
* The refusal a mutation's payload states, read as its declaration says ({@link ProviderGraphqlPayloadRefusal}), or
|
|
483
|
+
* `undefined` when the payload refuses nothing.
|
|
484
|
+
*/
|
|
485
|
+
function readGraphqlPayloadRefusal(
|
|
486
|
+
data: Readonly<Record<string, unknown>>,
|
|
487
|
+
refusal: ProviderGraphqlPayloadRefusal,
|
|
488
|
+
): Pick<ProviderGraphqlResponseVerdict, 'errorMessages' | 'errorCode'> | undefined {
|
|
489
|
+
const stated = readGraphqlDotPath(data, refusal.path);
|
|
490
|
+
if (refusal.kind === ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG) {
|
|
491
|
+
return stated === false ? { errorMessages: [`the answer's ${refusal.path} is false: the vendor did not do the write`] } : undefined;
|
|
492
|
+
}
|
|
493
|
+
if (!Array.isArray(stated) || stated.length === 0) return undefined;
|
|
494
|
+
const errorMessages = stated.slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES).map((entry) => {
|
|
495
|
+
const message = readGraphqlDotPath(entry, refusal.messagePath ?? 'message');
|
|
496
|
+
const field = refusal.fieldPath === undefined ? undefined : readGraphqlDotPath(entry, refusal.fieldPath);
|
|
497
|
+
const fieldText = typeof field === 'string' ? field
|
|
498
|
+
: Array.isArray(field) && field.every((segment) => typeof segment === 'string' || typeof segment === 'number') ? field.join('.') : undefined;
|
|
499
|
+
const text = typeof message === 'string' ? message : 'the vendor refused the write without a message';
|
|
500
|
+
return keptGraphqlMessage(fieldText === undefined || fieldText.length === 0 ? text : `${fieldText}: ${text}`);
|
|
501
|
+
});
|
|
502
|
+
const errorCode = refusal.codePath === undefined ? undefined
|
|
503
|
+
: stated.map((entry) => readGraphqlErrorCode(entry, refusal.codePath!)).find((code) => code !== undefined);
|
|
504
|
+
return { errorMessages, ...(errorCode === undefined ? {} : { errorCode }) };
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
/**
|
|
508
|
+
* Reads a parsed GraphQL answer (#3392). The ONE reader: the engine's transport, for a 2xx and a non-2xx answer alike,
|
|
509
|
+
* and every test go through it. See the module header for the rule and its sources.
|
|
510
|
+
*/
|
|
511
|
+
export function readProviderGraphqlResponse(
|
|
512
|
+
body: unknown,
|
|
513
|
+
errorCodePath?: string,
|
|
514
|
+
payloadRefusal?: ProviderGraphqlPayloadRefusal,
|
|
515
|
+
): ProviderGraphqlResponseVerdict {
|
|
516
|
+
if (body === null || typeof body !== 'object' || Array.isArray(body)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
|
|
517
|
+
const answer = body as Record<string, unknown>;
|
|
518
|
+
const errors = Object.hasOwn(answer, 'errors') ? answer.errors : undefined;
|
|
519
|
+
if (errors !== undefined && errors !== null && !Array.isArray(errors)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
|
|
520
|
+
if (Array.isArray(errors) && errors.length > 0) {
|
|
521
|
+
const errorMessages = errors
|
|
522
|
+
.map((error) => (error !== null && typeof error === 'object' && typeof (error as { message?: unknown }).message === 'string' ? (error as { message: string }).message : undefined))
|
|
523
|
+
.filter((message): message is string => message !== undefined)
|
|
524
|
+
.slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES)
|
|
525
|
+
.map(keptGraphqlMessage);
|
|
526
|
+
const errorCode = errorCodePath === undefined ? undefined
|
|
527
|
+
: errors.map((error) => readGraphqlErrorCode(error, errorCodePath)).find((code) => code !== undefined);
|
|
528
|
+
return {
|
|
529
|
+
kind: Object.hasOwn(answer, 'data') ? ProviderGraphqlResponseOutcomeKind.EXECUTION_ERROR : ProviderGraphqlResponseOutcomeKind.REQUEST_ERROR,
|
|
530
|
+
errorMessages,
|
|
531
|
+
...(errorCode === undefined ? {} : { errorCode }),
|
|
532
|
+
};
|
|
533
|
+
}
|
|
534
|
+
const data = Object.hasOwn(answer, 'data') ? answer.data : undefined;
|
|
535
|
+
if (data === null || typeof data !== 'object' || Array.isArray(data)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
|
|
536
|
+
const refused = payloadRefusal === undefined ? undefined : readGraphqlPayloadRefusal(data as Record<string, unknown>, payloadRefusal);
|
|
537
|
+
if (refused !== undefined) return { kind: ProviderGraphqlResponseOutcomeKind.PAYLOAD_REFUSED, ...refused };
|
|
538
|
+
return { kind: ProviderGraphqlResponseOutcomeKind.SUCCEEDED, data: data as Record<string, unknown> };
|
|
539
|
+
}
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
### Origin Package: `@wildo-ai/external-connectors-models`
|
|
543
|
+
|
|
11
544
|
```typescript
|
|
12
545
|
/** Where a declared parameter rides on the wire. */
|
|
13
546
|
export enum ProviderRestParameterLocation {
|
|
@@ -106,6 +639,19 @@ export interface ProviderRestOperationParameter {
|
|
|
106
639
|
* above it; the origin itself cannot move, as for every path value.
|
|
107
640
|
*/
|
|
108
641
|
readonly multiSegment?: true;
|
|
642
|
+
/**
|
|
643
|
+
* PATH only (#3397): the value is the CONNECTION's vendor-reported fact of this name, never the caller's input. Every
|
|
644
|
+
* QuickBooks path is `/v3/company/{realmId}/…`, and the company is the one the person connected, so asking each caller
|
|
645
|
+
* for it would let a call name a company its connection was not made for and leave every application re-typing it.
|
|
646
|
+
*
|
|
647
|
+
* The fact must be declared on the connection's OAuth2 contract with a
|
|
648
|
+
* {@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern}; the access resolver re-admits the stored value on every
|
|
649
|
+
* call and hands it to the request compiler, which fills nothing else from it. A caller value under the same input
|
|
650
|
+
* name is refused rather than ignored, and the operation's `inputSchema` must not declare one
|
|
651
|
+
* ({@link describeProviderRestOperationConnectionFactDefects}). Exclusive with `from`, `constantValue` and
|
|
652
|
+
* `multiSegment`.
|
|
653
|
+
*/
|
|
654
|
+
readonly connectionFact?: string;
|
|
109
655
|
readonly description?: string;
|
|
110
656
|
}
|
|
111
657
|
|
|
@@ -177,11 +723,146 @@ export interface ProviderRestOperationInputOptions {
|
|
|
177
723
|
/** Dot-path, inside each listed item, to the text a person reads (`name`). Vendor content, never derived from the value. */
|
|
178
724
|
readonly labelPath: string;
|
|
179
725
|
/**
|
|
180
|
-
* Inputs the options depend on: `{ <options-operation input field>: <this operation's input field> }`.
|
|
726
|
+
* Inputs the options depend on: `{ <options-operation input field>: <this operation's input field PATH> }`.
|
|
727
|
+
* The value side is a dot path into this operation's input, like the `inputOptions` key (#3399): Jira's issue
|
|
728
|
+
* types depend on `project.key`. The key side is a top-level field of the options operation's own input.
|
|
181
729
|
* A choice that is not yet made is REFUSED by name rather than listed as empty — "no projects" and
|
|
182
730
|
* "choose a workspace first" are different answers, and only one of them is true.
|
|
183
731
|
*/
|
|
184
732
|
readonly dependsOn?: Readonly<Record<string, string>>;
|
|
733
|
+
/**
|
|
734
|
+
* Fixed values the options operation is called with, beside what `dependsOn` forwards (#3399): Jira lists only the
|
|
735
|
+
* projects a person may create in (`action: 'create'`), Box lists the root folder (`folder_id: '0'`). A field may
|
|
736
|
+
* not be both fixed and forwarded.
|
|
737
|
+
*/
|
|
738
|
+
readonly input?: Readonly<Record<string, string | number | boolean>>;
|
|
739
|
+
/**
|
|
740
|
+
* Dot path, inside the options operation's output, to the listed items, when that output is an object rather than the
|
|
741
|
+
* list itself (#3399): QuickBooks answers a query as `{ Customer: [...] }`, Box a folder as `{ entries: [...] }`. An
|
|
742
|
+
* object without that path lists nothing, which is how QuickBooks answers a query with no rows; anything else at the
|
|
743
|
+
* path that is not a list is an unreadable answer. Absent, the output itself must be the list.
|
|
744
|
+
*/
|
|
745
|
+
readonly itemsPath?: string;
|
|
746
|
+
/**
|
|
747
|
+
* Keeps only the listed items whose value at each dot path equals the given text (#3399): a folder's items are files,
|
|
748
|
+
* folders and web links, and only a folder can be a parent (`{ type: 'folder' }`). Absent, every item is a choice.
|
|
749
|
+
*/
|
|
750
|
+
readonly itemWhere?: Readonly<Record<string, string>>;
|
|
751
|
+
}
|
|
752
|
+
|
|
753
|
+
/**
|
|
754
|
+
* The schema a dot path into an operation's input names, or `undefined` when a segment names no declared field (#3399).
|
|
755
|
+
*
|
|
756
|
+
* Walked through Zod's own definition (`_zod.def`), not `instanceof`: a provider module may be built against another
|
|
757
|
+
* copy of Zod than the host's. Wrappers that leave the value's shape alone (optional, nullable, default, prefault,
|
|
758
|
+
* readonly, catch, nonoptional, a pipe's input, a lazy getter) are seen through. A union names the field when any of its
|
|
759
|
+
* options declares it, as a discriminated body does. Only an object's DECLARED fields count: a loose object admits other
|
|
760
|
+
* keys at runtime, and a picker for a key nobody declared is the typo this check exists to refuse.
|
|
761
|
+
*/
|
|
762
|
+
function providerRestInputSchemaAtPath(schema: unknown, segments: readonly string[]): unknown {
|
|
763
|
+
let current: unknown = schema;
|
|
764
|
+
for (let depth = 0; depth < 64; depth += 1) {
|
|
765
|
+
const def = (current as { _zod?: { def?: Record<string, unknown> } } | undefined)?._zod?.def;
|
|
766
|
+
if (def === undefined) return undefined;
|
|
767
|
+
switch (def.type) {
|
|
768
|
+
case 'optional': case 'nullable': case 'default': case 'prefault': case 'readonly': case 'catch': case 'nonoptional':
|
|
769
|
+
current = def.innerType;
|
|
770
|
+
continue;
|
|
771
|
+
case 'pipe':
|
|
772
|
+
current = def.in;
|
|
773
|
+
continue;
|
|
774
|
+
case 'lazy':
|
|
775
|
+
current = typeof def.getter === 'function' ? (def.getter as () => unknown)() : undefined;
|
|
776
|
+
continue;
|
|
777
|
+
case 'union': {
|
|
778
|
+
if (segments.length === 0) return current;
|
|
779
|
+
const options = Array.isArray(def.options) ? def.options : [];
|
|
780
|
+
return options.map((option) => providerRestInputSchemaAtPath(option, segments)).find((found) => found !== undefined);
|
|
781
|
+
}
|
|
782
|
+
case 'object': {
|
|
783
|
+
if (segments.length === 0) return current;
|
|
784
|
+
const shape = def.shape as Record<string, unknown> | undefined;
|
|
785
|
+
const [head, ...rest] = segments;
|
|
786
|
+
if (shape === undefined || head === undefined || !Object.hasOwn(shape, head)) return undefined;
|
|
787
|
+
return providerRestInputSchemaAtPath(shape[head], rest);
|
|
788
|
+
}
|
|
789
|
+
default:
|
|
790
|
+
return segments.length === 0 ? current : undefined;
|
|
791
|
+
}
|
|
792
|
+
}
|
|
793
|
+
return undefined;
|
|
794
|
+
}
|
|
795
|
+
|
|
796
|
+
/**
|
|
797
|
+
* Why an operation's `inputOptions` cannot be honoured, or an empty list (#3399). Each key, and each `dependsOn` value,
|
|
798
|
+
* is a dot path into the operation's input (`project.key`, `CustomerRef.value`; a top-level field is a one-segment
|
|
799
|
+
* path), and must name a field the operation's `inputSchema` declares. Checked where a catalogue loads (the operation
|
|
800
|
+
* executor, an augmentation or supplement merge) and at publish, so a mistyped path is refused once, by name, instead of
|
|
801
|
+
* offering a picker that fills nothing. An operation without an `inputSchema` passes its input through unvalidated and
|
|
802
|
+
* declares no fields, so there is nothing to check its paths against; only their shape is.
|
|
803
|
+
*/
|
|
804
|
+
export function describeProviderRestOperationInputOptionsDefects(operation: Pick<ProviderRestOperation, 'operationId' | 'inputSchema' | 'inputOptions'>): string[] {
|
|
805
|
+
const defects: string[] = [];
|
|
806
|
+
const check = (path: string, role: string) => {
|
|
807
|
+
const segments = path.split('.');
|
|
808
|
+
if (segments.some((segment) => segment.length === 0)) {
|
|
809
|
+
defects.push(`operation '${operation.operationId}': ${role} '${path}' is not a dot path of field names`);
|
|
810
|
+
return;
|
|
811
|
+
}
|
|
812
|
+
if (operation.inputSchema !== undefined && providerRestInputSchemaAtPath(operation.inputSchema, segments) === undefined) {
|
|
813
|
+
defects.push(`operation '${operation.operationId}': ${role} '${path}' names no field of its inputSchema`);
|
|
814
|
+
}
|
|
815
|
+
};
|
|
816
|
+
for (const [inputPath, declaration] of Object.entries(operation.inputOptions ?? {})) {
|
|
817
|
+
check(inputPath, 'the inputOptions key');
|
|
818
|
+
for (const sourcePath of Object.values(declaration.dependsOn ?? {})) check(sourcePath, `the dependsOn of '${inputPath}'`);
|
|
819
|
+
for (const fixed of Object.keys(declaration.input ?? {})) {
|
|
820
|
+
if (Object.hasOwn(declaration.dependsOn ?? {}, fixed)) {
|
|
821
|
+
defects.push(`operation '${operation.operationId}': the options of '${inputPath}' both fix and forward '${fixed}'`);
|
|
822
|
+
}
|
|
823
|
+
}
|
|
824
|
+
for (const listPath of [declaration.itemsPath, ...Object.keys(declaration.itemWhere ?? {})]) {
|
|
825
|
+
if (listPath !== undefined && listPath.split('.').some((segment) => segment.length === 0)) {
|
|
826
|
+
defects.push(`operation '${operation.operationId}': the options of '${inputPath}' name '${listPath}', which is not a dot path`);
|
|
827
|
+
}
|
|
828
|
+
}
|
|
829
|
+
}
|
|
830
|
+
return defects;
|
|
831
|
+
}
|
|
832
|
+
|
|
833
|
+
/**
|
|
834
|
+
* Why an operation's {@link ProviderRestOperationParameter.connectionFact} parameters cannot be honoured, or an empty
|
|
835
|
+
* list (#3397). Each must be a PATH parameter the path template uses, fed by nothing else (no `from`, `constantValue` or
|
|
836
|
+
* `multiSegment`), and the operation's `inputSchema` must not declare a field of its name: a caller is never asked for a
|
|
837
|
+
* value the connection supplies, and one it sends anyway is refused at the call. With `reportedAccountFacts` (the
|
|
838
|
+
* connection's OAuth2 declaration), each named fact must also be declared there with a `pathSegmentPattern`; without
|
|
839
|
+
* it the request compiler refuses the call, so a module walk passes them to catch it before any call.
|
|
840
|
+
*/
|
|
841
|
+
export function describeProviderRestOperationConnectionFactDefects(
|
|
842
|
+
operation: Pick<ProviderRestOperation, 'operationId' | 'pathTemplate' | 'parameters' | 'inputSchema'>,
|
|
843
|
+
reportedAccountFacts?: Readonly<Record<string, ProviderOAuth2ReportedAccountFact>>,
|
|
844
|
+
): string[] {
|
|
845
|
+
const defects: string[] = [];
|
|
846
|
+
for (const parameter of operation.parameters ?? []) {
|
|
847
|
+
const factName = parameter.connectionFact;
|
|
848
|
+
if (factName === undefined) continue;
|
|
849
|
+
const at = `operation '${operation.operationId}': the parameter '${parameter.name}' filled from the connection fact '${factName}'`;
|
|
850
|
+
if (parameter.in !== ProviderRestParameterLocation.PATH) defects.push(`${at} is a ${parameter.in} parameter; only a PATH value may come from a connection fact`);
|
|
851
|
+
if (parameter.from !== undefined || parameter.constantValue !== undefined || parameter.multiSegment !== undefined) {
|
|
852
|
+
defects.push(`${at} also declares from, constantValue or multiSegment; its value comes from the connection alone`);
|
|
853
|
+
}
|
|
854
|
+
if (!operation.pathTemplate.includes(`{${parameter.name}}`)) defects.push(`${at} fills no '{${parameter.name}}' token of the path template`);
|
|
855
|
+
if (operation.inputSchema !== undefined && providerRestInputSchemaAtPath(operation.inputSchema, [parameter.name]) !== undefined) {
|
|
856
|
+
defects.push(`${at} is also declared by the inputSchema, which would ask callers for a value the connection supplies`);
|
|
857
|
+
}
|
|
858
|
+
if (reportedAccountFacts !== undefined) {
|
|
859
|
+
const fact = Object.hasOwn(reportedAccountFacts, factName) ? reportedAccountFacts[factName] : undefined;
|
|
860
|
+
if (fact?.pathSegmentPattern === undefined) {
|
|
861
|
+
defects.push(`${at}: the connection's OAuth2 contract declares no reported fact '${factName}' with a pathSegmentPattern`);
|
|
862
|
+
}
|
|
863
|
+
}
|
|
864
|
+
}
|
|
865
|
+
return defects;
|
|
185
866
|
}
|
|
186
867
|
|
|
187
868
|
/**
|
|
@@ -285,10 +966,19 @@ export interface ProviderRestOperation {
|
|
|
285
966
|
/** Narrows the provider's semantics for this one operation (a slow export, a tight endpoint). */
|
|
286
967
|
readonly remoteCallSemantics?: Partial<ProviderRestCallSemantics>;
|
|
287
968
|
/**
|
|
288
|
-
* Where each input's choices come from, keyed by
|
|
289
|
-
*
|
|
969
|
+
* Where each input's choices come from, keyed by a dot PATH into the input (#3399): `workspace` for a top-level
|
|
970
|
+
* field, `project.key` or `CustomerRef.value` for the value a vendor nests inside a reference object. Absent for an
|
|
971
|
+
* input a caller types. Every path must name a field of `inputSchema`
|
|
972
|
+
* ({@link describeProviderRestOperationInputOptionsDefects}). See {@link ProviderRestOperationInputOptions}.
|
|
290
973
|
*/
|
|
291
974
|
readonly inputOptions?: Readonly<Record<string, ProviderRestOperationInputOptions>>;
|
|
975
|
+
/**
|
|
976
|
+
* Present for a GraphQL operation (#3392): the provider-owned document the call sends to `pathTemplate` (the vendor's
|
|
977
|
+
* GraphQL endpoint), with the operation's input as its variables. A 2xx answer carrying `errors` fails the call; the
|
|
978
|
+
* output is read from the answer's `data`. See {@link ProviderRestOperationGraphql} for what such an operation may and
|
|
979
|
+
* may not declare beside it.
|
|
980
|
+
*/
|
|
981
|
+
readonly graphql?: ProviderRestOperationGraphql;
|
|
292
982
|
/** Set when the vendor has deprecated it; the executor logs once per operation, never refuses. */
|
|
293
983
|
readonly deprecated?: {
|
|
294
984
|
readonly reason: string;
|
|
@@ -407,6 +1097,23 @@ export const PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER = '{tenant}';
|
|
|
407
1097
|
/** A tenant value the token URL admits: a GUID or a DNS name. Nothing that can leave the URL's path segment. */
|
|
408
1098
|
export const PROVIDER_CLIENT_CREDENTIALS_TENANT_SHAPE = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/;
|
|
409
1099
|
|
|
1100
|
+
/**
|
|
1101
|
+
* The placeholder that BEGINS a client-credentials token URL whose token endpoint is on the deployment's own vendor
|
|
1102
|
+
* instance (#3402): `{deploymentOrigin}/oauth2/v1/token`. Filled with the ORIGIN of the base URL the engine resolved for
|
|
1103
|
+
* the REST contract (from `baseUrlHostEnvVarName` or `baseUrlEnvVarName`), never from a connection or a request.
|
|
1104
|
+
*
|
|
1105
|
+
* Okta is the case: every org has its own host (`<org>.okta.com`, or a custom domain), and its org authorization server's
|
|
1106
|
+
* token endpoint is on that host. A fixed {@link ProviderRestClientCredentials.tokenHosts} list cannot admit a host only
|
|
1107
|
+
* the operator knows, and a `{tenant}` value would be a second, separately typed copy of the host the operations already
|
|
1108
|
+
* go to, which could disagree with it. Filling the token endpoint from the SAME resolved origin keeps them one value: the
|
|
1109
|
+
* client's assertion is sent to the host the operator named, and to nothing a person connecting could choose.
|
|
1110
|
+
*
|
|
1111
|
+
* spec-cite: Okta Developer, "Implement OAuth for Okta with a service app"
|
|
1112
|
+
* (https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/, fetched 2026-11-10) — the token
|
|
1113
|
+
* request is `POST https://{yourOktaDomain}/oauth2/v1/token`, and the assertion's `aud` is that URL.
|
|
1114
|
+
*/
|
|
1115
|
+
export const PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER = '{deploymentOrigin}';
|
|
1116
|
+
|
|
410
1117
|
/** What a {@link ProviderClientCredentialsVerifiedFact} records: a value the person typed and the vendor accepted. */
|
|
411
1118
|
export enum ProviderClientCredentialsFactSource {
|
|
412
1119
|
/** The client id the token endpoint issued a token for: Microsoft's bot App ID. */
|
|
@@ -440,9 +1147,14 @@ export interface ProviderClientCredentialsVerifiedFact {
|
|
|
440
1147
|
* secret the connection holds (#2663). The Bot Framework is the first: a Teams bot's App ID and secret, and for a
|
|
441
1148
|
* single-tenant bot the tenant it is registered in, mint a token for `https://api.botframework.com/.default`.
|
|
442
1149
|
*
|
|
1150
|
+
* Declared beside `oauth2` (#3398), it is the APPLICATION's own connection: Box's client-credentials grant and Zoom's
|
|
1151
|
+
* server-to-server OAuth renew the application's token while people and organizations connect through the exchange.
|
|
1152
|
+
* {@link providerClientCredentialsServesOwnerScope} says which door a connection takes.
|
|
1153
|
+
*
|
|
443
1154
|
* The token is minted per call when no unexpired one is cached, never stored, and attached where
|
|
444
|
-
* {@link ProviderProtocolRuntimeContract}'s `apiKey` says, so `apiKey.secretRef` names the
|
|
445
|
-
*
|
|
1155
|
+
* {@link ProviderProtocolRuntimeContract}'s `apiKey` says, so (with no `oauth2` beside it) `apiKey.secretRef` names the
|
|
1156
|
+
* client's credential, its SECRET or its private key (#3402), the slot whose absence means "not configured". The
|
|
1157
|
+
* client id, credential and tenant are read from the connection: the
|
|
446
1158
|
* application's own environment for an APPLICATION connection, the organization's typed credential for an
|
|
447
1159
|
* ORGANIZATION one.
|
|
448
1160
|
*
|
|
@@ -457,16 +1169,62 @@ export interface ProviderClientCredentialsVerifiedFact {
|
|
|
457
1169
|
* `https://api.botframework.com/.default`, fetched 2026-10-06.
|
|
458
1170
|
*/
|
|
459
1171
|
export interface ProviderRestClientCredentials {
|
|
460
|
-
/**
|
|
1172
|
+
/**
|
|
1173
|
+
* The https token endpoint. May carry {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}, or BEGIN with
|
|
1174
|
+
* {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} when the token endpoint is on the deployment's own
|
|
1175
|
+
* vendor instance (Okta's org, #3402).
|
|
1176
|
+
*/
|
|
461
1177
|
readonly tokenUrl: string;
|
|
462
|
-
/**
|
|
1178
|
+
/**
|
|
1179
|
+
* The hosts the token endpoint may be on once filled. The client secret is sent nowhere else. EMPTY exactly when the
|
|
1180
|
+
* token URL begins with {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}: its host is the one the
|
|
1181
|
+
* operator named for the operations, and no fixed list can name it.
|
|
1182
|
+
*/
|
|
463
1183
|
readonly tokenHosts: readonly string[];
|
|
464
|
-
/**
|
|
465
|
-
|
|
1184
|
+
/**
|
|
1185
|
+
* The `scope` parameter, sent as written. Omitted, no `scope` is sent: RFC 6749 makes it optional, and Box, Zoom and
|
|
1186
|
+
* Salesforce grant the scopes configured on the app instead (#3398).
|
|
1187
|
+
* spec-cite: RFC 6749 §4.4.2 — `scope`: "OPTIONAL. The scope of the access request as described by Section 3.3."
|
|
1188
|
+
* Fetched 2026-10-06.
|
|
1189
|
+
*/
|
|
1190
|
+
readonly scope?: string;
|
|
1191
|
+
/**
|
|
1192
|
+
* The `grant_type` sent. Omitted, `client_credentials` (RFC 6749 §4.4). See {@link ProviderClientCredentialsGrantType}.
|
|
1193
|
+
*/
|
|
1194
|
+
readonly grantType?: ProviderClientCredentialsGrantType;
|
|
1195
|
+
/**
|
|
1196
|
+
* Further parameters of the token request a vendor requires, by name: a fixed value, or one read from a slot of the
|
|
1197
|
+
* connection (#3398). Box's client-credentials grant names the subject it authenticates as (`box_subject_type`,
|
|
1198
|
+
* `box_subject_id`); Zoom's server-to-server grant names the account (`account_id`). A parameter the grant itself
|
|
1199
|
+
* defines (`grant_type`, `client_id`, `client_secret`, `scope`, the client assertion) is refused here: each has its own
|
|
1200
|
+
* field. See {@link ProviderClientCredentialsTokenRequestParameter}.
|
|
1201
|
+
*/
|
|
1202
|
+
readonly tokenRequestParameters?: Readonly<Record<string, ProviderClientCredentialsTokenRequestParameter>>;
|
|
1203
|
+
/**
|
|
1204
|
+
* How the client authenticates to the token endpoint. Omitted,
|
|
1205
|
+
* {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST} with a client secret: the id and secret in the
|
|
1206
|
+
* body, as Microsoft's identity platform documents. {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC}
|
|
1207
|
+
* sends them in the Basic header only (Zoom's server-to-server OAuth documents nothing else). With
|
|
1208
|
+
* {@link privateKeyJwt} the method is {@link ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT}, implied when
|
|
1209
|
+
* omitted (#3402).
|
|
1210
|
+
*/
|
|
1211
|
+
readonly tokenEndpointAuthMethod?: ProviderOAuth2ClientAuthenticationMethod;
|
|
466
1212
|
/** The slot holding the client id. */
|
|
467
1213
|
readonly clientIdSecretRef: string;
|
|
468
|
-
/**
|
|
469
|
-
|
|
1214
|
+
/**
|
|
1215
|
+
* The slot holding the client secret. Exactly one of this and {@link privateKeyJwt} (#3402): a client authenticates
|
|
1216
|
+
* with a shared secret or with a key it alone holds, never both. The client's CREDENTIAL slot (this one, or the
|
|
1217
|
+
* private key's) equals the contract's `apiKey.secretRef` when the contract declares no `oauth2` (the slot whose
|
|
1218
|
+
* absence means "not configured"); beside `oauth2`, `apiKey.secretRef` is the slot of the people's and organizations'
|
|
1219
|
+
* minted tokens and this one serves the application alone.
|
|
1220
|
+
*/
|
|
1221
|
+
readonly clientSecretSecretRef?: string;
|
|
1222
|
+
/**
|
|
1223
|
+
* The client authenticates with a JWT it signs with its own private key (`private_key_jwt`, #3402) instead of a
|
|
1224
|
+
* secret: Okta's OAuth service apps accept nothing else for the Management API. See
|
|
1225
|
+
* {@link ProviderClientCredentialsPrivateKeyJwt}.
|
|
1226
|
+
*/
|
|
1227
|
+
readonly privateKeyJwt?: ProviderClientCredentialsPrivateKeyJwt;
|
|
470
1228
|
/** The slot filling {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}. Required exactly when the token URL carries it. */
|
|
471
1229
|
readonly tenantSecretRef?: string;
|
|
472
1230
|
/** Facts an ORGANIZATION connection records once the vendor accepted its credential, keyed by fact name. */
|
|
@@ -475,6 +1233,152 @@ export interface ProviderRestClientCredentials {
|
|
|
475
1233
|
readonly tokenLifetimeFallbackSeconds?: number;
|
|
476
1234
|
}
|
|
477
1235
|
|
|
1236
|
+
/**
|
|
1237
|
+
* The `grant_type` a client-credentials token request sends. Narrower than `OAuth2_GrantType` on purpose: these are the
|
|
1238
|
+
* grants the client-credentials minter performs, each with nothing but the client's own credential and the declared
|
|
1239
|
+
* parameters, and a member joins in the change that implements it.
|
|
1240
|
+
*/
|
|
1241
|
+
export enum ProviderClientCredentialsGrantType {
|
|
1242
|
+
/**
|
|
1243
|
+
* The OAuth 2.0 client-credentials grant: the default.
|
|
1244
|
+
* spec-cite: RFC 6749 §4.4.2 — `grant_type`: "REQUIRED. Value MUST be set to "client_credentials"." Fetched 2026-10-06.
|
|
1245
|
+
*/
|
|
1246
|
+
CLIENT_CREDENTIALS = 'client_credentials',
|
|
1247
|
+
/**
|
|
1248
|
+
* Zoom's server-to-server OAuth: the same exchange (a client authenticated with Basic, one token back, no refresh
|
|
1249
|
+
* token) under Zoom's own grant name, with the account named in `account_id`.
|
|
1250
|
+
* spec-cite: https://developers.zoom.us/docs/internal-apps/s2s-oauth/ — "Use the `account_credentials` grant type to
|
|
1251
|
+
* generate an access token."; "Set up the body of the access token request using the `account_credentials`
|
|
1252
|
+
* `grant_type` and your `account_id`." Fetched 2026-11-09.
|
|
1253
|
+
*/
|
|
1254
|
+
ACCOUNT_CREDENTIALS = 'account_credentials',
|
|
1255
|
+
}
|
|
1256
|
+
|
|
1257
|
+
/**
|
|
1258
|
+
* One further parameter of a client-credentials token request ({@link ProviderRestClientCredentials.tokenRequestParameters}):
|
|
1259
|
+
* a fixed `value` the module states (`box_subject_type: enterprise`), or a `secretRef` naming the connection slot that
|
|
1260
|
+
* holds it (Box's enterprise id, Zoom's account id), read like the client id: from the application's environment for
|
|
1261
|
+
* the application's connection, from the organization's credential for an organization's.
|
|
1262
|
+
*/
|
|
1263
|
+
export type ProviderClientCredentialsTokenRequestParameter =
|
|
1264
|
+
| { readonly value: string; readonly secretRef?: never }
|
|
1265
|
+
| { readonly secretRef: string; readonly value?: never };
|
|
1266
|
+
|
|
1267
|
+
/**
|
|
1268
|
+
* The algorithms a client assertion is signed with (#3402). The JWS names (RFC 7518 §3.1) of the two asymmetric
|
|
1269
|
+
* families every vendor measured accepts: Okta lists "RS256, RS384, RS512, ES256, ES384, and ES512" for a service app's
|
|
1270
|
+
* key. A member joins when a vendor needs it.
|
|
1271
|
+
* spec-cite: RFC 7518 §3.1 — "RS256 | RSASSA-PKCS1-v1_5 using SHA-256" and "ES256 | ECDSA using P-256 and SHA-256";
|
|
1272
|
+
* https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/ — the supported algorithms. Both
|
|
1273
|
+
* fetched 2026-11-09.
|
|
1274
|
+
*/
|
|
1275
|
+
export enum ProviderClientAssertionSigningAlgorithm {
|
|
1276
|
+
/** ECDSA on P-256 with SHA-256: a short key and signature, and the default to choose for a new key. */
|
|
1277
|
+
ES256 = 'ES256',
|
|
1278
|
+
/** RSASSA-PKCS1-v1_5 with SHA-256, for a vendor or key store that issues RSA keys. */
|
|
1279
|
+
RS256 = 'RS256',
|
|
1280
|
+
}
|
|
1281
|
+
|
|
1282
|
+
/** The longest a client assertion may live: Okta refuses one whose `exp` is more than an hour away. */
|
|
1283
|
+
export const PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS = 3600;
|
|
1284
|
+
|
|
1285
|
+
/** How long a client assertion lives when the declaration says nothing: long enough for one request, and no more. */
|
|
1286
|
+
export const PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS = 300;
|
|
1287
|
+
|
|
1288
|
+
/**
|
|
1289
|
+
* `private_key_jwt` client authentication for a client-credentials token request (#3402). The client signs, per token
|
|
1290
|
+
* request, a JWT whose `iss` and `sub` are its client id, whose `aud` is the token endpoint it is sent to, with a short
|
|
1291
|
+
* `exp` and a fresh `jti`, and sends it as `client_assertion`.
|
|
1292
|
+
*
|
|
1293
|
+
* The private key is read from a slot of the connection, as an unencrypted PEM (PKCS#8, or an RSA PKCS#1 / EC key the
|
|
1294
|
+
* signer re-wraps), like a secret: the application's configured provider secrets for its own connection, an organization's sealed
|
|
1295
|
+
* credential row for an organization's.
|
|
1296
|
+
*
|
|
1297
|
+
* ## Why the platform keyring does not hold this key (decided 2026-11-10, #3402)
|
|
1298
|
+
*
|
|
1299
|
+
* The key layer (#2916) holds keys by PURPOSE, each signing the platform's own claims under its own `typ` and verified
|
|
1300
|
+
* from public halves the platform publishes. A client key is the opposite: its public half is REGISTERED BY THE OPERATOR
|
|
1301
|
+
* at the vendor (Okta's app, a Google service account), the vendor is its only verifier, and the vendor fixes the
|
|
1302
|
+
* algorithm (Okta's console and Google's uploaded keys are RSA, while the keyring signs ES256 only). A keyring rotation
|
|
1303
|
+
* would also silently break every connection whose vendor still holds the old public half. So custody signing for vendor
|
|
1304
|
+
* clients is a key purpose of its own (RS256 across the keyring providers, a public half handed to the operator, rotation
|
|
1305
|
+
* coordinated with the vendor registration), recorded on #2916, and not a missing step of this declaration.
|
|
1306
|
+
*
|
|
1307
|
+
* spec-cite: RFC 7523 §2.2 — "The value of the "client_assertion_type" is
|
|
1308
|
+
* "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"."; §3 — the JWT "MUST contain an "iss" (issuer) claim", for
|
|
1309
|
+
* client authentication "the subject MUST be the "client_id" of the OAuth client", an "aud" (audience) claim "containing
|
|
1310
|
+
* a value that identifies the authorization server", and an "exp" (expiration time) claim; OpenID Connect Core 1.0 §9,
|
|
1311
|
+
* `private_key_jwt` — `iss` and `sub` "MUST contain the client_id of the OAuth Client", "The Audience SHOULD be the URL
|
|
1312
|
+
* of the Authorization Server's Token Endpoint", `jti` REQUIRED: "These tokens MUST only be used once". Fetched
|
|
1313
|
+
* 2026-11-09 from https://www.rfc-editor.org/rfc/rfc7523 and https://openid.net/specs/openid-connect-core-1_0.html.
|
|
1314
|
+
*/
|
|
1315
|
+
export interface ProviderClientCredentialsPrivateKeyJwt {
|
|
1316
|
+
/** The slot holding the client's private key: an unencrypted PEM, PKCS#8 (`-----BEGIN PRIVATE KEY-----`) or PKCS#1 / EC. */
|
|
1317
|
+
readonly privateKeySecretRef: string;
|
|
1318
|
+
/** The JWS algorithm the key signs with. Must match the key: an EC P-256 key for ES256, an RSA key for RS256. */
|
|
1319
|
+
readonly algorithm: ProviderClientAssertionSigningAlgorithm;
|
|
1320
|
+
/**
|
|
1321
|
+
* The slot holding the key id sent as the assertion's `kid` header, when the vendor locates the key by it (Okta
|
|
1322
|
+
* requires a `kid` on every key registered with the app). Omitted, no `kid` is sent.
|
|
1323
|
+
*/
|
|
1324
|
+
readonly keyIdSecretRef?: string;
|
|
1325
|
+
/** Seconds until the assertion's `exp`. Omitted, {@link PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS}. */
|
|
1326
|
+
readonly assertionLifetimeSeconds?: number;
|
|
1327
|
+
}
|
|
1328
|
+
|
|
1329
|
+
/**
|
|
1330
|
+
* The slot of a client-credentials declaration's own CREDENTIAL: the client secret, or the private key (#3402).
|
|
1331
|
+
* `undefined` only for a declaration {@link describeProviderRestClientCredentialsDefects} refuses.
|
|
1332
|
+
*/
|
|
1333
|
+
export function providerClientCredentialsCredentialSlot(credentials: ProviderRestClientCredentials): string | undefined {
|
|
1334
|
+
return credentials.clientSecretSecretRef ?? credentials.privateKeyJwt?.privateKeySecretRef;
|
|
1335
|
+
}
|
|
1336
|
+
|
|
1337
|
+
/**
|
|
1338
|
+
* The parameter names {@link ProviderRestClientCredentials.tokenRequestParameters} may not declare: each is written by
|
|
1339
|
+
* the grant itself (the grant type, the client's credential, the scope, a client assertion), so a second value would
|
|
1340
|
+
* either be ignored or override the declared one.
|
|
1341
|
+
*/
|
|
1342
|
+
export const PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES: readonly string[] = [
|
|
1343
|
+
'grant_type', 'client_id', 'client_secret', 'scope', 'client_assertion', 'client_assertion_type',
|
|
1344
|
+
];
|
|
1345
|
+
|
|
1346
|
+
/**
|
|
1347
|
+
* Whether the client-credentials door of a REST contract serves a connection of this owner scope (#3398).
|
|
1348
|
+
*
|
|
1349
|
+
* Alone, it serves every admitted connection: the application's own (from its environment) and an organization's (from
|
|
1350
|
+
* the credential the organization typed, as a Teams bot). Beside `oauth2`, a person or an organization connects through
|
|
1351
|
+
* the authorization-code exchange, and the client-credentials grant serves the APPLICATION's own account only, so that
|
|
1352
|
+
* account renews itself instead of resting on a pasted token that expires within the hour.
|
|
1353
|
+
*/
|
|
1354
|
+
export function providerClientCredentialsServesOwnerScope(
|
|
1355
|
+
contract: { readonly clientCredentials?: ProviderRestClientCredentials; readonly oauth2?: unknown },
|
|
1356
|
+
ownerScope: ExternalProvider_Connection_OwnerScope,
|
|
1357
|
+
): boolean {
|
|
1358
|
+
if (contract.clientCredentials === undefined) return false;
|
|
1359
|
+
return contract.oauth2 === undefined || ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION;
|
|
1360
|
+
}
|
|
1361
|
+
|
|
1362
|
+
/**
|
|
1363
|
+
* The slot a connection of this owner scope AUTHENTICATES with, as the engine's REST access resolver reads it: the
|
|
1364
|
+
* client-credentials grant's own credential (its client secret or private key) when that door serves the owner scope
|
|
1365
|
+
* ({@link providerClientCredentialsServesOwnerScope}), else `apiKey.secretRef`, the stored or pasted token itself.
|
|
1366
|
+
*
|
|
1367
|
+
* For a contract declaring `clientCredentials` beside `oauth2` (Box, Zoom, #3398) the two differ by owner: the
|
|
1368
|
+
* application's own account mints from the server app's secret, while a person's connection reads its exchanged token
|
|
1369
|
+
* from `apiKey.secretRef`. A tool standing in for one connection (`wildo providers probe`, `connect`, the doctor's
|
|
1370
|
+
* configuration checks, all APPLICATION-owned) asks this instead of reading `apiKey.secretRef`, so it reads the slot the
|
|
1371
|
+
* engine would. `undefined` when the contract names neither.
|
|
1372
|
+
*/
|
|
1373
|
+
export function providerRestConnectionCredentialSlot(
|
|
1374
|
+
contract: { readonly clientCredentials?: ProviderRestClientCredentials; readonly oauth2?: unknown; readonly apiKey?: { readonly secretRef?: string } },
|
|
1375
|
+
ownerScope: ExternalProvider_Connection_OwnerScope,
|
|
1376
|
+
): string | undefined {
|
|
1377
|
+
return providerClientCredentialsServesOwnerScope(contract, ownerScope)
|
|
1378
|
+
? providerClientCredentialsCredentialSlot(contract.clientCredentials!)
|
|
1379
|
+
: contract.apiKey?.secretRef;
|
|
1380
|
+
}
|
|
1381
|
+
|
|
478
1382
|
/**
|
|
479
1383
|
* Why a client-credentials declaration cannot be honoured, or an empty list. Checked where a provider is composed:
|
|
480
1384
|
* a token URL that is not https, a token host that is not a DNS name or that the URL is not on, a tenant placeholder
|
|
@@ -483,20 +1387,70 @@ export interface ProviderRestClientCredentials {
|
|
|
483
1387
|
export function describeProviderRestClientCredentialsDefects(credentials: ProviderRestClientCredentials): string[] {
|
|
484
1388
|
const defects: string[] = [];
|
|
485
1389
|
const hasTenant = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER);
|
|
486
|
-
|
|
487
|
-
|
|
1390
|
+
// The deployment's origin forms the WHOLE origin or nothing (#3402): text before it, or anything but a path after it,
|
|
1391
|
+
// would compose a host the operator never named.
|
|
1392
|
+
const onDeploymentOrigin = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER);
|
|
1393
|
+
if (onDeploymentOrigin && !credentials.tokenUrl.startsWith(`${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}/`)) {
|
|
1394
|
+
defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} other than as its whole origin, followed by a path`);
|
|
1395
|
+
}
|
|
1396
|
+
if (onDeploymentOrigin && hasTenant) defects.push(`clientCredentials.tokenUrl carries both ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} and ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}; the token endpoint has one source`);
|
|
1397
|
+
const filled = credentials.tokenUrl
|
|
1398
|
+
.split(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER).join('tenant.example')
|
|
1399
|
+
.split(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER).join('https://deployment.example');
|
|
1400
|
+
if (/[{}]/.test(filled)) defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' carries a placeholder other than ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}`);
|
|
488
1401
|
if (hasTenant && credentials.tenantSecretRef === undefined) defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and no tenantSecretRef fills it`);
|
|
489
1402
|
if (!hasTenant && credentials.tenantSecretRef !== undefined) defects.push(`clientCredentials.tenantSecretRef '${credentials.tenantSecretRef}' fills nothing: the token URL carries no ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}`);
|
|
490
1403
|
const host = /^https:\/\/([^/:?#]+)(?::\d+)?\//.exec(filled)?.[1]?.toLowerCase();
|
|
491
1404
|
if (host === undefined) defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' is not an https URL with a path`);
|
|
492
|
-
if (
|
|
493
|
-
|
|
494
|
-
|
|
1405
|
+
if (onDeploymentOrigin) {
|
|
1406
|
+
// The host is the deployment's, admitted where the engine resolves the operations' base URL; a fixed list would be
|
|
1407
|
+
// a second, unchecked statement of it.
|
|
1408
|
+
if (credentials.tokenHosts.length > 0) defects.push(`clientCredentials.tokenHosts names hosts beside ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}; the token host is the deployment's, so declare none`);
|
|
1409
|
+
} else {
|
|
1410
|
+
if (credentials.tokenHosts.length === 0) defects.push('clientCredentials.tokenHosts admits no host');
|
|
1411
|
+
for (const tokenHost of credentials.tokenHosts) {
|
|
1412
|
+
if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(tokenHost.toLowerCase())) defects.push(`clientCredentials.tokenHosts names '${tokenHost}', which is not a DNS name`);
|
|
1413
|
+
}
|
|
1414
|
+
if (host !== undefined && !credentials.tokenHosts.some((tokenHost) => tokenHost.toLowerCase() === host)) {
|
|
1415
|
+
defects.push(`clientCredentials.tokenUrl is on '${host}', which tokenHosts does not admit`);
|
|
1416
|
+
}
|
|
1417
|
+
}
|
|
1418
|
+
if (credentials.scope !== undefined && credentials.scope.trim() === '') defects.push('clientCredentials.scope is empty; omit it to send none');
|
|
1419
|
+
const grantTypes: readonly string[] = Object.values(ProviderClientCredentialsGrantType);
|
|
1420
|
+
if (credentials.grantType !== undefined && !grantTypes.includes(credentials.grantType)) {
|
|
1421
|
+
defects.push(`clientCredentials.grantType ${JSON.stringify(credentials.grantType)} is none of ${grantTypes.join(', ')}`);
|
|
1422
|
+
}
|
|
1423
|
+
// One credential: a secret or a private key (#3402), and the method agrees with which.
|
|
1424
|
+
if ((credentials.clientSecretSecretRef === undefined) === (credentials.privateKeyJwt === undefined)) {
|
|
1425
|
+
defects.push('clientCredentials declares exactly one of clientSecretSecretRef and privateKeyJwt');
|
|
495
1426
|
}
|
|
496
|
-
|
|
497
|
-
|
|
1427
|
+
const methods: readonly string[] = credentials.privateKeyJwt !== undefined
|
|
1428
|
+
? [ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT]
|
|
1429
|
+
: [ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST, ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC];
|
|
1430
|
+
if (credentials.tokenEndpointAuthMethod !== undefined && !methods.includes(credentials.tokenEndpointAuthMethod)) {
|
|
1431
|
+
defects.push(`clientCredentials.tokenEndpointAuthMethod ${JSON.stringify(credentials.tokenEndpointAuthMethod)} is none of ${methods.join(', ')} for ${credentials.privateKeyJwt !== undefined ? 'a private key' : 'a client secret'}`);
|
|
1432
|
+
}
|
|
1433
|
+
if (credentials.privateKeyJwt !== undefined) {
|
|
1434
|
+
const { privateKeySecretRef, algorithm, keyIdSecretRef, assertionLifetimeSeconds } = credentials.privateKeyJwt;
|
|
1435
|
+
const algorithms: readonly string[] = Object.values(ProviderClientAssertionSigningAlgorithm);
|
|
1436
|
+
if (privateKeySecretRef.trim() === '') defects.push('clientCredentials.privateKeyJwt.privateKeySecretRef names no slot');
|
|
1437
|
+
if (!algorithms.includes(algorithm)) defects.push(`clientCredentials.privateKeyJwt.algorithm ${JSON.stringify(algorithm)} is none of ${algorithms.join(', ')}`);
|
|
1438
|
+
if (keyIdSecretRef !== undefined && keyIdSecretRef.trim() === '') defects.push('clientCredentials.privateKeyJwt.keyIdSecretRef names no slot');
|
|
1439
|
+
if (assertionLifetimeSeconds !== undefined
|
|
1440
|
+
&& !(Number.isInteger(assertionLifetimeSeconds) && assertionLifetimeSeconds > 0 && assertionLifetimeSeconds <= PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS)) {
|
|
1441
|
+
defects.push(`clientCredentials.privateKeyJwt.assertionLifetimeSeconds is not a whole number of seconds from 1 to ${PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS}`);
|
|
1442
|
+
}
|
|
1443
|
+
}
|
|
1444
|
+
for (const [name, parameter] of Object.entries(credentials.tokenRequestParameters ?? {})) {
|
|
1445
|
+
if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(name)) defects.push(`clientCredentials.tokenRequestParameters names '${name}', which is not a parameter name`);
|
|
1446
|
+
if (PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES.includes(name)) {
|
|
1447
|
+
defects.push(`clientCredentials.tokenRequestParameters names '${name}', which the grant itself sends; declare it in its own field`);
|
|
1448
|
+
}
|
|
1449
|
+
const hasValue = typeof parameter.value === 'string';
|
|
1450
|
+
const hasSlot = typeof parameter.secretRef === 'string';
|
|
1451
|
+
if (hasValue === hasSlot) defects.push(`clientCredentials.tokenRequestParameters '${name}' must declare exactly one of value and secretRef`);
|
|
1452
|
+
else if ((parameter.value ?? parameter.secretRef ?? '').trim() === '') defects.push(`clientCredentials.tokenRequestParameters '${name}' is empty`);
|
|
498
1453
|
}
|
|
499
|
-
if (credentials.scope.trim() === '') defects.push('clientCredentials.scope is empty');
|
|
500
1454
|
for (const [name, fact] of Object.entries(credentials.verifiedAccountFacts ?? {})) {
|
|
501
1455
|
if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name)) defects.push(`clientCredentials.verifiedAccountFacts names '${name}', which is not a fact name`);
|
|
502
1456
|
if (fact.source === ProviderClientCredentialsFactSource.TENANT && credentials.tenantSecretRef === undefined) {
|
|
@@ -509,6 +1463,68 @@ export function describeProviderRestClientCredentialsDefects(credentials: Provid
|
|
|
509
1463
|
return defects;
|
|
510
1464
|
}
|
|
511
1465
|
|
|
1466
|
+
/**
|
|
1467
|
+
* Why a REST contract's `clientCredentials` sits wrongly beside the contract's other authentication fields, or an empty
|
|
1468
|
+
* list (#2663, #3398). Checked where a provider is composed, beside {@link describeProviderRestClientCredentialsDefects}.
|
|
1469
|
+
*
|
|
1470
|
+
* - beside `requestSigning`: two ways to authenticate one call;
|
|
1471
|
+
* - alone, `apiKey.secretRef` must be the client secret's slot, the one whose absence means "not configured";
|
|
1472
|
+
* - beside `oauth2` the grant serves the APPLICATION's own account only ({@link providerClientCredentialsServesOwnerScope}),
|
|
1473
|
+
* so the module must admit that connection; `apiKey.secretRef` names the exchanged tokens' slot and may not be the
|
|
1474
|
+
* client secret's (a person's token would be read from it); and `verifiedAccountFacts`, which only an organization's
|
|
1475
|
+
* connection records, would record nothing.
|
|
1476
|
+
* - a token URL on {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} (#3402) needs a base URL the
|
|
1477
|
+
* DEPLOYMENT names (`baseUrlHostEnvVarName` or `baseUrlEnvVarName`), and may serve the APPLICATION's connection only:
|
|
1478
|
+
* the deployment's instance is the application's own (its Okta org), so an organization minting there would
|
|
1479
|
+
* authenticate against the application's vendor tenant, never its own.
|
|
1480
|
+
*/
|
|
1481
|
+
export function describeProviderRestClientCredentialsPlacementDefects(
|
|
1482
|
+
contract: {
|
|
1483
|
+
readonly clientCredentials?: ProviderRestClientCredentials;
|
|
1484
|
+
readonly oauth2?: unknown;
|
|
1485
|
+
readonly requestSigning?: unknown;
|
|
1486
|
+
readonly apiKey: { readonly secretRef: string };
|
|
1487
|
+
readonly baseUrlHostEnvVarName?: string;
|
|
1488
|
+
readonly baseUrlEnvVarName?: string;
|
|
1489
|
+
},
|
|
1490
|
+
admitsApplicationConnection: boolean,
|
|
1491
|
+
/** Whether the module admits an ORGANIZATION or USER connection. Omitted, `false`. */
|
|
1492
|
+
admitsNonApplicationConnection = false,
|
|
1493
|
+
): string[] {
|
|
1494
|
+
const credentials = contract.clientCredentials;
|
|
1495
|
+
if (credentials === undefined) return [];
|
|
1496
|
+
const defects: string[] = [];
|
|
1497
|
+
if (contract.requestSigning !== undefined) {
|
|
1498
|
+
defects.push('declares clientCredentials beside requestSigning; a call authenticates one way');
|
|
1499
|
+
}
|
|
1500
|
+
if (credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER)) {
|
|
1501
|
+
if (contract.baseUrlHostEnvVarName === undefined && contract.baseUrlEnvVarName === undefined) {
|
|
1502
|
+
defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, and the contract's base URL is not one the deployment names (baseUrlHostEnvVarName or baseUrlEnvVarName)`);
|
|
1503
|
+
}
|
|
1504
|
+
if (!admitsApplicationConnection) {
|
|
1505
|
+
defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, which serves the application's own connection only, and the module admits none`);
|
|
1506
|
+
}
|
|
1507
|
+
if (contract.oauth2 === undefined && admitsNonApplicationConnection) {
|
|
1508
|
+
defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, the application's own vendor instance, and the module admits an organization or user connection that would mint there`);
|
|
1509
|
+
}
|
|
1510
|
+
}
|
|
1511
|
+
const credentialSlot = providerClientCredentialsCredentialSlot(credentials);
|
|
1512
|
+
if (contract.oauth2 === undefined) {
|
|
1513
|
+
if (contract.apiKey.secretRef !== credentialSlot) {
|
|
1514
|
+
defects.push(`apiKey.secretRef '${contract.apiKey.secretRef}' is not the client's credential slot '${credentialSlot}' (its secret or private key); that is the slot whose absence means not configured`);
|
|
1515
|
+
}
|
|
1516
|
+
return defects;
|
|
1517
|
+
}
|
|
1518
|
+
if (!admitsApplicationConnection) defects.push('declares clientCredentials beside oauth2 and admits no APPLICATION connection, the only one that grant serves');
|
|
1519
|
+
if (contract.apiKey.secretRef === credentialSlot) {
|
|
1520
|
+
defects.push(`apiKey.secretRef '${contract.apiKey.secretRef}' is the client-credentials secret or key; beside oauth2 it names the slot of the exchanged access tokens`);
|
|
1521
|
+
}
|
|
1522
|
+
if (credentials.verifiedAccountFacts !== undefined) {
|
|
1523
|
+
defects.push('declares clientCredentials.verifiedAccountFacts beside oauth2; an organization connects through oauth2, so no client-credentials fact is ever recorded');
|
|
1524
|
+
}
|
|
1525
|
+
return defects;
|
|
1526
|
+
}
|
|
1527
|
+
|
|
512
1528
|
function readDotPath(body: unknown, path: string): unknown {
|
|
513
1529
|
let current: unknown = body;
|
|
514
1530
|
for (const segment of path.split('.')) {
|