@iota-uz/sdk 0.46.0 → 0.47.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -0
- package/dist/client-host/identity.d.ts +4 -4
- package/dist/client-host/identity.js +2 -2
- package/dist/lens/{CascadePanel-Bha4qY7J.js → CascadePanel-BlYJd18G.js} +1 -1
- package/dist/lens/{ChartDataEquivalent-Bwgn4yYB.js → ChartDataEquivalent-B6xSOdzC.js} +1 -1
- package/dist/lens/{ChartPanel-BZpzBuwl.js → ChartPanel-BIJjrs5D.js} +159 -159
- package/dist/lens/{CoveragePanel-D40AuKkD.js → CoveragePanel-CHtXDMtt.js} +1 -1
- package/dist/lens/{GaugePanel-C9k2TuJH.js → GaugePanel-By0TOJPa.js} +1 -1
- package/dist/lens/LensDashboard.d.ts +13 -0
- package/dist/lens/LensDashboard.d.ts.map +1 -1
- package/dist/lens/{MapPanel-ZYxfDsPM.js → MapPanel-Cw4ELCiM.js} +3 -3
- package/dist/lens/{MetricFlowPanel-CmESLoLK.js → MetricFlowPanel-Gr5wi3nI.js} +2 -2
- package/dist/lens/{MetricHierarchyPanel-UZVuJ5P2.js → MetricHierarchyPanel-VLA_5LXX.js} +2 -2
- package/dist/lens/{MetricRelationshipPanel-CXLdScAy.js → MetricRelationshipPanel-DFP566_c.js} +2 -2
- package/dist/lens/{PrintReport-lrfdCTZO.js → PrintReport-C0OV1iHP.js} +5 -5
- package/dist/lens/{QualityChip-BYz-DHfs.js → QualityChip-DTi-0jdh.js} +1 -1
- package/dist/lens/SaveInvestigation-CX1Abyl8.js +309 -0
- package/dist/lens/TablePanel-BusKU7cU.js +994 -0
- package/dist/lens/{adapter-CeAqYWqm.js → adapter-CQg4-M7p.js} +7 -7
- package/dist/lens/contract/schemas.d.ts +2 -0
- package/dist/lens/contract/schemas.d.ts.map +1 -1
- package/dist/lens/contract/types.d.ts +12 -0
- package/dist/lens/contract/types.d.ts.map +1 -1
- package/dist/lens/{dashboardEdit-DKVE_6J_.js → dashboardEdit-CJgCVfi_.js} +1 -1
- package/dist/lens/explore/DrillOverlay.d.ts +38 -0
- package/dist/lens/explore/DrillOverlay.d.ts.map +1 -1
- package/dist/lens/explore/ExplorePanel.d.ts.map +1 -1
- package/dist/lens/explore/SaveInvestigation.d.ts +21 -0
- package/dist/lens/explore/SaveInvestigation.d.ts.map +1 -0
- package/dist/lens/explore/drillHost.d.ts +25 -0
- package/dist/lens/explore/drillHost.d.ts.map +1 -0
- package/dist/lens/explore/investigation.d.ts +174 -0
- package/dist/lens/explore/investigation.d.ts.map +1 -0
- package/dist/lens/explore/provenanceLabels.d.ts +10 -0
- package/dist/lens/explore/provenanceLabels.d.ts.map +1 -0
- package/dist/lens/index-DR7Hf8Km.js +19805 -0
- package/dist/lens/{index-DkVTXC8W.js → index-DZFw4cqF.js} +1 -1
- package/dist/lens/index.d.ts +7 -1
- package/dist/lens/index.d.ts.map +1 -1
- package/dist/lens/index.js +67 -53
- package/dist/lens/{install-CQ_iMuAE.js → install-B2lTK6uo.js} +1 -1
- package/dist/lens/{install-Ch0_qifK.js → install-BXr4Mnc0.js} +1 -1
- package/dist/lens/{install-CKmxqMe1.js → install-CicNQ_ks.js} +1 -1
- package/dist/lens/{install-BwD_xNlp.js → install-d8A0WPiw.js} +1 -1
- package/dist/lens/{keys-BBmWdfaH.js → keys-C-Akc9lZ.js} +2 -2
- package/dist/lens/panels/ChartPanel.d.ts.map +1 -1
- package/dist/lens/panels/TablePanel.d.ts.map +1 -1
- package/dist/lens/panels/actions.d.ts.map +1 -1
- package/dist/lens/panels/panelFailure.d.ts.map +1 -1
- package/dist/lens/{prefetch-BXoUIIgq.js → prefetch-C9kxuIs8.js} +2 -2
- package/dist/lens/{prefetchPanels-a-zs_bDm.js → prefetchPanels-gbY9RIqL.js} +1 -1
- package/dist/lens/{print-CpgWJxDG.js → print-CllsAP3d.js} +1 -1
- package/dist/lens/reports/ReportCompositionEditor.d.ts +8 -2
- package/dist/lens/reports/ReportCompositionEditor.d.ts.map +1 -1
- package/dist/lens/reports/ReportDefinitionEditor.d.ts +54 -0
- package/dist/lens/reports/ReportDefinitionEditor.d.ts.map +1 -0
- package/dist/lens/reports/ReportPicker.d.ts +6 -0
- package/dist/lens/reports/ReportPicker.d.ts.map +1 -1
- package/dist/lens/reports/dashboardEdit.d.ts +3 -0
- package/dist/lens/reports/dashboardEdit.d.ts.map +1 -1
- package/dist/lens/reports/editing.d.ts +35 -0
- package/dist/lens/reports/editing.d.ts.map +1 -1
- package/dist/lens/reports/picker.d.ts +4 -1
- package/dist/lens/reports/picker.d.ts.map +1 -1
- package/dist/lens/runtime/index.d.ts +0 -1
- package/dist/lens/runtime/index.d.ts.map +1 -1
- package/dist/lens/runtime/messages.d.ts +2 -2
- package/dist/lens/runtime/messages.d.ts.map +1 -1
- package/dist/lens/runtime/provider.d.ts +5 -1
- package/dist/lens/runtime/provider.d.ts.map +1 -1
- package/dist/lens/runtime/returnContext.d.ts +62 -0
- package/dist/lens/runtime/returnContext.d.ts.map +1 -0
- package/dist/lens/runtime/tableSummary.d.ts +9 -0
- package/dist/lens/runtime/tableSummary.d.ts.map +1 -0
- package/dist/lens/{scales-BLf9OweG.js → scales-CO6Q9RtG.js} +1 -1
- package/dist/lens/style.css +1 -1
- package/dist/runtime/README.md +24 -0
- package/dist/runtime/assert.d.ts +51 -0
- package/dist/runtime/assert.js +172 -0
- package/dist/runtime/build/README.txt +1 -0
- package/dist/runtime/build/extract.mjs +342 -0
- package/dist/runtime/build/shared-exports.json +388 -0
- package/dist/runtime/build/test-child.mjs +136 -0
- package/dist/runtime/build/theme/tailwind.config.js +121 -0
- package/dist/runtime/build/theme/theme.css +462 -0
- package/dist/runtime/build/theme/utilities.css +1 -0
- package/dist/runtime/build/vendor/lib/lib.d.ts +22 -0
- package/dist/runtime/build/vendor/lib/lib.decorators.d.ts +384 -0
- package/dist/runtime/build/vendor/lib/lib.decorators.legacy.d.ts +22 -0
- package/dist/runtime/build/vendor/lib/lib.dom.asynciterable.d.ts +41 -0
- package/dist/runtime/build/vendor/lib/lib.dom.d.ts +28983 -0
- package/dist/runtime/build/vendor/lib/lib.dom.iterable.d.ts +491 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.collection.d.ts +147 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.core.d.ts +597 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.d.ts +28 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.generator.d.ts +77 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.iterable.d.ts +590 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.promise.d.ts +81 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.proxy.d.ts +128 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.reflect.d.ts +144 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.symbol.d.ts +46 -0
- package/dist/runtime/build/vendor/lib/lib.es2015.symbol.wellknown.d.ts +326 -0
- package/dist/runtime/build/vendor/lib/lib.es2016.array.include.d.ts +116 -0
- package/dist/runtime/build/vendor/lib/lib.es2016.d.ts +21 -0
- package/dist/runtime/build/vendor/lib/lib.es2016.full.d.ts +23 -0
- package/dist/runtime/build/vendor/lib/lib.es2016.intl.d.ts +31 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.arraybuffer.d.ts +21 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.d.ts +26 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.date.d.ts +31 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.full.d.ts +23 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.intl.d.ts +44 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.object.d.ts +49 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.sharedmemory.d.ts +135 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.string.d.ts +45 -0
- package/dist/runtime/build/vendor/lib/lib.es2017.typedarrays.d.ts +53 -0
- package/dist/runtime/build/vendor/lib/lib.es2018.asyncgenerator.d.ts +77 -0
- package/dist/runtime/build/vendor/lib/lib.es2018.asynciterable.d.ts +53 -0
- package/dist/runtime/build/vendor/lib/lib.es2018.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2018.full.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2018.intl.d.ts +83 -0
- package/dist/runtime/build/vendor/lib/lib.es2018.promise.d.ts +30 -0
- package/dist/runtime/build/vendor/lib/lib.es2018.regexp.d.ts +37 -0
- package/dist/runtime/build/vendor/lib/lib.es2019.array.d.ts +79 -0
- package/dist/runtime/build/vendor/lib/lib.es2019.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2019.full.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2019.intl.d.ts +23 -0
- package/dist/runtime/build/vendor/lib/lib.es2019.object.d.ts +33 -0
- package/dist/runtime/build/vendor/lib/lib.es2019.string.d.ts +37 -0
- package/dist/runtime/build/vendor/lib/lib.es2019.symbol.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.bigint.d.ts +731 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.d.ts +27 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.date.d.ts +42 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.full.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.intl.d.ts +474 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.number.d.ts +28 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.promise.d.ts +47 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.sharedmemory.d.ts +99 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.string.d.ts +44 -0
- package/dist/runtime/build/vendor/lib/lib.es2020.symbol.wellknown.d.ts +41 -0
- package/dist/runtime/build/vendor/lib/lib.es2021.d.ts +23 -0
- package/dist/runtime/build/vendor/lib/lib.es2021.full.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2021.intl.d.ts +166 -0
- package/dist/runtime/build/vendor/lib/lib.es2021.promise.d.ts +48 -0
- package/dist/runtime/build/vendor/lib/lib.es2021.string.d.ts +33 -0
- package/dist/runtime/build/vendor/lib/lib.es2021.weakref.d.ts +78 -0
- package/dist/runtime/build/vendor/lib/lib.es2022.array.d.ts +121 -0
- package/dist/runtime/build/vendor/lib/lib.es2022.d.ts +25 -0
- package/dist/runtime/build/vendor/lib/lib.es2022.error.d.ts +75 -0
- package/dist/runtime/build/vendor/lib/lib.es2022.full.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2022.intl.d.ts +121 -0
- package/dist/runtime/build/vendor/lib/lib.es2022.object.d.ts +26 -0
- package/dist/runtime/build/vendor/lib/lib.es2022.regexp.d.ts +39 -0
- package/dist/runtime/build/vendor/lib/lib.es2022.string.d.ts +25 -0
- package/dist/runtime/build/vendor/lib/lib.es2023.array.d.ts +924 -0
- package/dist/runtime/build/vendor/lib/lib.es2023.collection.d.ts +21 -0
- package/dist/runtime/build/vendor/lib/lib.es2023.d.ts +22 -0
- package/dist/runtime/build/vendor/lib/lib.es2023.full.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2023.intl.d.ts +56 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.arraybuffer.d.ts +65 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.collection.d.ts +29 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.d.ts +26 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.full.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.object.d.ts +29 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.promise.d.ts +35 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.regexp.d.ts +25 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.sharedmemory.d.ts +68 -0
- package/dist/runtime/build/vendor/lib/lib.es2024.string.d.ts +29 -0
- package/dist/runtime/build/vendor/lib/lib.es5.d.ts +4585 -0
- package/dist/runtime/build/vendor/lib/lib.es6.d.ts +23 -0
- package/dist/runtime/build/vendor/lib/lib.esnext.array.d.ts +35 -0
- package/dist/runtime/build/vendor/lib/lib.esnext.collection.d.ts +96 -0
- package/dist/runtime/build/vendor/lib/lib.esnext.d.ts +25 -0
- package/dist/runtime/build/vendor/lib/lib.esnext.decorators.d.ts +28 -0
- package/dist/runtime/build/vendor/lib/lib.esnext.disposable.d.ts +193 -0
- package/dist/runtime/build/vendor/lib/lib.esnext.full.d.ts +24 -0
- package/dist/runtime/build/vendor/lib/lib.esnext.intl.d.ts +21 -0
- package/dist/runtime/build/vendor/lib/lib.esnext.iterator.d.ts +148 -0
- package/dist/runtime/build/vendor/node-types/assert/strict.d.ts +111 -0
- package/dist/runtime/build/vendor/node-types/assert.d.ts +1115 -0
- package/dist/runtime/build/vendor/node-types/async_hooks.d.ts +619 -0
- package/dist/runtime/build/vendor/node-types/buffer.buffer.d.ts +477 -0
- package/dist/runtime/build/vendor/node-types/buffer.d.ts +1941 -0
- package/dist/runtime/build/vendor/node-types/child_process.d.ts +1480 -0
- package/dist/runtime/build/vendor/node-types/cluster.d.ts +578 -0
- package/dist/runtime/build/vendor/node-types/compatibility/iterators.d.ts +21 -0
- package/dist/runtime/build/vendor/node-types/console.d.ts +453 -0
- package/dist/runtime/build/vendor/node-types/constants.d.ts +21 -0
- package/dist/runtime/build/vendor/node-types/crypto.d.ts +5484 -0
- package/dist/runtime/build/vendor/node-types/dgram.d.ts +715 -0
- package/dist/runtime/build/vendor/node-types/diagnostics_channel.d.ts +576 -0
- package/dist/runtime/build/vendor/node-types/dns/promises.d.ts +503 -0
- package/dist/runtime/build/vendor/node-types/dns.d.ts +923 -0
- package/dist/runtime/build/vendor/node-types/domain.d.ts +166 -0
- package/dist/runtime/build/vendor/node-types/events.d.ts +967 -0
- package/dist/runtime/build/vendor/node-types/fs/promises.d.ts +1354 -0
- package/dist/runtime/build/vendor/node-types/fs.d.ts +4777 -0
- package/dist/runtime/build/vendor/node-types/globals.d.ts +170 -0
- package/dist/runtime/build/vendor/node-types/globals.typedarray.d.ts +41 -0
- package/dist/runtime/build/vendor/node-types/http.d.ts +2246 -0
- package/dist/runtime/build/vendor/node-types/http2.d.ts +2882 -0
- package/dist/runtime/build/vendor/node-types/https.d.ts +585 -0
- package/dist/runtime/build/vendor/node-types/index.d.ts +101 -0
- package/dist/runtime/build/vendor/node-types/inspector.d.ts +323 -0
- package/dist/runtime/build/vendor/node-types/inspector.generated.d.ts +4406 -0
- package/dist/runtime/build/vendor/node-types/module.d.ts +844 -0
- package/dist/runtime/build/vendor/node-types/net.d.ts +1197 -0
- package/dist/runtime/build/vendor/node-types/os.d.ts +507 -0
- package/dist/runtime/build/vendor/node-types/package.json +140 -0
- package/dist/runtime/build/vendor/node-types/path.d.ts +200 -0
- package/dist/runtime/build/vendor/node-types/perf_hooks.d.ts +1054 -0
- package/dist/runtime/build/vendor/node-types/process.d.ts +2101 -0
- package/dist/runtime/build/vendor/node-types/punycode.d.ts +117 -0
- package/dist/runtime/build/vendor/node-types/querystring.d.ts +152 -0
- package/dist/runtime/build/vendor/node-types/readline/promises.d.ts +161 -0
- package/dist/runtime/build/vendor/node-types/readline.d.ts +600 -0
- package/dist/runtime/build/vendor/node-types/repl.d.ts +438 -0
- package/dist/runtime/build/vendor/node-types/sea.d.ts +162 -0
- package/dist/runtime/build/vendor/node-types/sqlite.d.ts +1182 -0
- package/dist/runtime/build/vendor/node-types/stream/consumers.d.ts +45 -0
- package/dist/runtime/build/vendor/node-types/stream/promises.d.ts +90 -0
- package/dist/runtime/build/vendor/node-types/stream/web.d.ts +596 -0
- package/dist/runtime/build/vendor/node-types/stream.d.ts +1707 -0
- package/dist/runtime/build/vendor/node-types/string_decoder.d.ts +67 -0
- package/dist/runtime/build/vendor/node-types/test.d.ts +2656 -0
- package/dist/runtime/build/vendor/node-types/timers/promises.d.ts +108 -0
- package/dist/runtime/build/vendor/node-types/timers.d.ts +285 -0
- package/dist/runtime/build/vendor/node-types/tls.d.ts +1314 -0
- package/dist/runtime/build/vendor/node-types/trace_events.d.ts +197 -0
- package/dist/runtime/build/vendor/node-types/ts5.6/buffer.buffer.d.ts +473 -0
- package/dist/runtime/build/vendor/node-types/ts5.6/compatibility/float16array.d.ts +71 -0
- package/dist/runtime/build/vendor/node-types/ts5.6/globals.typedarray.d.ts +36 -0
- package/dist/runtime/build/vendor/node-types/ts5.6/index.d.ts +103 -0
- package/dist/runtime/build/vendor/node-types/ts5.7/compatibility/float16array.d.ts +72 -0
- package/dist/runtime/build/vendor/node-types/ts5.7/index.d.ts +103 -0
- package/dist/runtime/build/vendor/node-types/tty.d.ts +209 -0
- package/dist/runtime/build/vendor/node-types/url.d.ts +1103 -0
- package/dist/runtime/build/vendor/node-types/util.d.ts +2379 -0
- package/dist/runtime/build/vendor/node-types/v8.d.ts +1010 -0
- package/dist/runtime/build/vendor/node-types/vm.d.ts +1160 -0
- package/dist/runtime/build/vendor/node-types/wasi.d.ts +202 -0
- package/dist/runtime/build/vendor/node-types/web-globals/abortcontroller.d.ts +34 -0
- package/dist/runtime/build/vendor/node-types/web-globals/crypto.d.ts +32 -0
- package/dist/runtime/build/vendor/node-types/web-globals/domexception.d.ts +68 -0
- package/dist/runtime/build/vendor/node-types/web-globals/events.d.ts +97 -0
- package/dist/runtime/build/vendor/node-types/web-globals/fetch.d.ts +62 -0
- package/dist/runtime/build/vendor/node-types/web-globals/navigator.d.ts +25 -0
- package/dist/runtime/build/vendor/node-types/web-globals/storage.d.ts +24 -0
- package/dist/runtime/build/vendor/node-types/web-globals/streams.d.ts +22 -0
- package/dist/runtime/build/vendor/node-types/worker_threads.d.ts +894 -0
- package/dist/runtime/build/vendor/node-types/zlib.d.ts +768 -0
- package/dist/runtime/build/vendor/node_modules/csstype/LICENSE +19 -0
- package/dist/runtime/build/vendor/node_modules/csstype/index.d.ts +22569 -0
- package/dist/runtime/build/vendor/node_modules/csstype/index.js.flow +6863 -0
- package/dist/runtime/build/vendor/node_modules/csstype/package.json +70 -0
- package/dist/runtime/build/vendor/node_modules/seroval/LICENSE +7 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/cjs/development/index.cjs +4232 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/cjs/production/index.cjs +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/esm/development/index.mjs +4209 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/esm/production/index.mjs +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/Serializer.d.ts +28 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/base-primitives.d.ts +28 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/compat.d.ts +15 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/constants.d.ts +105 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/constructors.d.ts +50 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/context/async-parser.d.ts +20 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/context/deserializer.d.ts +52 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/context/parser.d.ts +62 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/context/serializer.d.ts +103 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/context/sync-parser.d.ts +61 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/cross/index.d.ts +24 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/errors.d.ts +47 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/function-string.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/keys.d.ts +4 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/literals.d.ts +10 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/node.d.ts +8 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/opaque-reference.d.ts +9 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/plugin.d.ts +52 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/reference.d.ts +6 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/sequence.d.ts +11 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/special-reference.d.ts +16 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/stream.d.ts +17 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/string.d.ts +4 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/symbols.d.ts +14 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/tree/index.d.ts +21 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/types.d.ts +233 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/utils/error.d.ts +6 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/utils/get-identifier.d.ts +2 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/utils/get-object-flag.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/utils/is-valid-identifier.d.ts +2 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/utils/promise-to-result.d.ts +2 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/utils/typed-array.d.ts +6 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/core/utils/valid-properties.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval/dist/types/index.d.ts +18 -0
- package/dist/runtime/build/vendor/node_modules/seroval/package.json +67 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/Serializer.ts +119 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/base-primitives.ts +537 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/compat.ts +23 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/constants.ts +202 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/constructors.ts +265 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/context/async-parser.ts +666 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/context/deserializer.ts +832 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/context/parser.ts +335 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/context/serializer.ts +1524 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/context/sync-parser.ts +943 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/cross/index.ts +190 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/errors.ts +196 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/function-string.ts +31 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/keys.ts +17 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/literals.ts +43 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/node.ts +40 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/opaque-reference.ts +9 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/plugin.ts +105 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/reference.ts +66 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/sequence.ts +59 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/special-reference.ts +42 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/stream.ts +71 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/string.ts +86 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/symbols.ts +20 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/tree/index.ts +134 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/types.ts +377 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/utils/error.ts +73 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/utils/get-identifier.ts +18 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/utils/get-object-flag.ts +14 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/utils/is-valid-identifier.ts +12 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/utils/promise-to-result.ts +9 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/utils/typed-array.ts +56 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/core/utils/valid-properties.ts +34 -0
- package/dist/runtime/build/vendor/node_modules/seroval/src/index.ts +36 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/LICENSE +7 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/cjs/development/web.cjs +826 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/cjs/production/web.cjs +1 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/esm/development/web.mjs +803 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/esm/production/web.mjs +1 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/abort-signal.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/blob.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/custom-event.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/dom-exception.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/event.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/file.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/form-data.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/headers.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/image-data.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/index.d.ts +15 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/readable-stream.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/request.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/response.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/url-search-params.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/dist/types/web/url.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/package.json +70 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/abort-signal.ts +131 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/blob.ts +41 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/custom-event.ts +66 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/dom-exception.ts +57 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/event.ts +62 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/file.ts +50 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/form-data.ts +105 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/headers.ts +49 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/image-data.ts +74 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/index.ts +14 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/readable-stream.ts +148 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/request.ts +82 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/response.ts +65 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/url-search-params.ts +40 -0
- package/dist/runtime/build/vendor/node_modules/seroval-plugins/web/url.ts +37 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/dist/server.cjs +824 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/dist/server.js +770 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/dist/solid.cjs +1808 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/dist/solid.js +1753 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/jsx-runtime.d.ts +1 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/package.json +243 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/dist/server.cjs +133 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/dist/server.js +121 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/dist/store.cjs +463 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/dist/store.js +454 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/package.json +46 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/types/index.d.ts +12 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/types/modifiers.d.ts +6 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/types/mutable.d.ts +5 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/types/server.d.ts +17 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/store/types/store.d.ts +108 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/index.d.ts +23 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/jsx.d.ts +4253 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/reactive/array.d.ts +44 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/reactive/observable.d.ts +36 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/reactive/scheduler.d.ts +10 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/reactive/signal.d.ts +581 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/render/Suspense.d.ts +26 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/render/component.d.ts +111 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/render/flow.d.ts +118 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/render/hydration.d.ts +24 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/render/index.d.ts +4 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/server/index.d.ts +3 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/server/reactive.d.ts +98 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/types/server/rendering.d.ts +160 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/dist/server.cjs +900 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/dist/server.js +786 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/dist/web.cjs +884 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/dist/web.js +772 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/package.json +46 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/storage/dist/storage.cjs +12 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/storage/dist/storage.js +10 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/storage/package.json +15 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/storage/types/index.d.ts +2 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/types/client.d.ts +93 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/types/core.d.ts +2 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/types/index.d.ts +50 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/types/jsx.d.ts +1 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/types/server-mock.d.ts +65 -0
- package/dist/runtime/build/vendor/node_modules/solid-js/web/types/server.d.ts +187 -0
- package/dist/runtime/build/worker.mjs +293415 -0
- package/dist/runtime/catalog/sdk-natives.json +655 -0
- package/dist/runtime/cli/iota-ext.mjs +1028 -0
- package/dist/runtime/client-host/entry.d.ts +10 -0
- package/dist/runtime/client-host/entry.js +124 -0
- package/dist/runtime/client-host/hooks.d.ts +43 -0
- package/dist/runtime/client-host/hooks.js +94 -0
- package/dist/runtime/client-host/index.d.ts +9 -0
- package/dist/runtime/client-host/index.js +9 -0
- package/dist/runtime/client-host/islands.d.ts +44 -0
- package/dist/runtime/client-host/islands.js +165 -0
- package/dist/runtime/client-host/kit.d.ts +10 -0
- package/dist/runtime/client-host/kit.js +37 -0
- package/dist/runtime/client-host/page.d.ts +53 -0
- package/dist/runtime/client-host/page.js +217 -0
- package/dist/runtime/client-host/params.d.ts +8 -0
- package/dist/runtime/client-host/params.js +36 -0
- package/dist/runtime/client-host/protocol.d.ts +78 -0
- package/dist/runtime/client-host/protocol.js +26 -0
- package/dist/runtime/client-host/shared.d.ts +12 -0
- package/dist/runtime/client-host/shared.js +49 -0
- package/dist/runtime/client-host/shell.d.ts +88 -0
- package/dist/runtime/client-host/shell.js +195 -0
- package/dist/runtime/client-host/slots.d.ts +54 -0
- package/dist/runtime/client-host/slots.js +90 -0
- package/dist/runtime/client-host/styles.d.ts +7 -0
- package/dist/runtime/client-host/styles.js +61 -0
- package/dist/runtime/client-host/transport.d.ts +45 -0
- package/dist/runtime/client-host/transport.js +115 -0
- package/dist/runtime/client.d.ts +226 -0
- package/dist/runtime/client.js +121 -0
- package/dist/runtime/contracts.d.ts +204 -0
- package/dist/runtime/contracts.js +195 -0
- package/dist/runtime/docs/authoring.md +1609 -0
- package/dist/runtime/docs/example/docs/en/admin/limits.md +10 -0
- package/dist/runtime/docs/example/docs/en/getting-started.md +13 -0
- package/dist/runtime/docs/example/docs/en/points.md +9 -0
- package/dist/runtime/docs/example/docs/ru/getting-started.md +12 -0
- package/dist/runtime/docs/example/package.json +27 -0
- package/dist/runtime/docs/example/src/ClientScreen.tsx +10 -0
- package/dist/runtime/docs/example/src/RedemptionScreen.tsx +7 -0
- package/dist/runtime/docs/example/src/RewardsScreen.module.css +13 -0
- package/dist/runtime/docs/example/src/RewardsScreen.tsx +51 -0
- package/dist/runtime/docs/example/src/client.tsx +40 -0
- package/dist/runtime/docs/example/src/contracts.ts +132 -0
- package/dist/runtime/docs/example/src/css-modules.d.ts +5 -0
- package/dist/runtime/docs/example/src/server.test.ts +156 -0
- package/dist/runtime/docs/example/src/server.ts +188 -0
- package/dist/runtime/docs/example/tsconfig.json +16 -0
- package/dist/runtime/entity.d.ts +237 -0
- package/dist/runtime/entity.js +201 -0
- package/dist/runtime/fakes.d.ts +80 -0
- package/dist/runtime/fakes.js +88 -0
- package/dist/runtime/fixtures.d.ts +34 -0
- package/dist/runtime/fixtures.js +60 -0
- package/dist/runtime/help.d.ts +22 -0
- package/dist/runtime/help.js +51 -0
- package/dist/runtime/host/context.mjs +392 -0
- package/dist/runtime/host/errors.mjs +64 -0
- package/dist/runtime/host/loader.mjs +28 -0
- package/dist/runtime/host/protocol.mjs +4 -0
- package/dist/runtime/host/register.mjs +8 -0
- package/dist/runtime/host/sdk/assert.mjs +153 -0
- package/dist/runtime/host/sdk/client-host/hooks.mjs +86 -0
- package/dist/runtime/host/sdk/client-host/protocol.mjs +30 -0
- package/dist/runtime/host/sdk/client-host/slots.mjs +82 -0
- package/dist/runtime/host/sdk/client-host/styles.mjs +45 -0
- package/dist/runtime/host/sdk/client-host/transport.mjs +102 -0
- package/dist/runtime/host/sdk/client.mjs +115 -0
- package/dist/runtime/host/sdk/contracts.mjs +185 -0
- package/dist/runtime/host/sdk/entity.mjs +183 -0
- package/dist/runtime/host/sdk/fakes.mjs +88 -0
- package/dist/runtime/host/sdk/fixtures.mjs +56 -0
- package/dist/runtime/host/sdk/help.mjs +37 -0
- package/dist/runtime/host/sdk/index.mjs +83 -0
- package/dist/runtime/host/sdk/kit.mjs +11 -0
- package/dist/runtime/host/sdk/manifest.mjs +276 -0
- package/dist/runtime/host/sdk/model.mjs +4 -0
- package/dist/runtime/host/sdk/resource.mjs +34 -0
- package/dist/runtime/host/sdk/schema.mjs +75 -0
- package/dist/runtime/host/sdk/server.mjs +43 -0
- package/dist/runtime/host/sdk/testhost.mjs +992 -0
- package/dist/runtime/host/sdk/testing.mjs +21 -0
- package/dist/runtime/host/sdk/wire.mjs +207 -0
- package/dist/runtime/host/worker.mjs +252 -0
- package/dist/runtime/index.d.ts +10 -0
- package/dist/runtime/index.js +5 -0
- package/dist/runtime/kit.d.ts +5 -0
- package/dist/runtime/kit.js +14 -0
- package/dist/runtime/manifest.d.ts +17 -0
- package/dist/runtime/manifest.js +323 -0
- package/dist/runtime/model.d.ts +224 -0
- package/dist/runtime/model.js +3 -0
- package/dist/runtime/resource.d.ts +31 -0
- package/dist/runtime/resource.js +35 -0
- package/dist/runtime/schema.d.ts +97 -0
- package/dist/runtime/schema.js +73 -0
- package/dist/runtime/server.d.ts +445 -0
- package/dist/runtime/server.js +41 -0
- package/dist/runtime/testhost.d.ts +216 -0
- package/dist/runtime/testhost.js +1146 -0
- package/dist/runtime/testing.d.ts +10 -0
- package/dist/runtime/testing.js +7 -0
- package/dist/runtime/wire.d.ts +26 -0
- package/dist/runtime/wire.js +236 -0
- package/dist/sdk-identity.cjs +3 -3
- package/dist/sdk-identity.js +3 -3
- package/dist/sdk-identity.json +2 -2
- package/dist/solid-ui/embedded-css.d.ts +2 -0
- package/dist/solid-ui/embedded-css.js +1 -0
- package/dist/solid-ui/embedded.css +2 -0
- package/dist/testing/components.d.ts +73 -0
- package/dist/testing/components.js +96 -0
- package/dist/testing/htmx.d.ts +44 -0
- package/dist/testing/htmx.js +284 -0
- package/dist/testing/index.d.ts +4 -41
- package/dist/testing/index.js +3 -206
- package/dist/testing/scenarios.d.ts +83 -0
- package/dist/testing/scenarios.js +74 -0
- package/dist/testing/wait.d.ts +7 -0
- package/dist/testing/wait.js +19 -0
- package/package.json +33 -2
- package/dist/lens/TablePanel-C09tzJOL.js +0 -980
- package/dist/lens/index-DcVtZneD.js +0 -18473
- package/dist/lens/runtime/recovery.d.ts +0 -26
- package/dist/lens/runtime/recovery.d.ts.map +0 -1
|
@@ -0,0 +1,1609 @@
|
|
|
1
|
+
# Writing extension packages
|
|
2
|
+
|
|
3
|
+
An **extension package** adds data, behaviour, workflows, notifications and UI to an iota-sdk application without
|
|
4
|
+
touching its Go code. You write TypeScript against `@iota-uz/sdk`, test it on your machine, and publish it through the
|
|
5
|
+
application's configurator UI or MCP tools. This guide is the author's manual; the implementation contract between the
|
|
6
|
+
platform's own slices is [`../extension-runtime.md`](../extension-runtime.md) (read it only if you build the platform).
|
|
7
|
+
Enabling the runtime in an application and operating it is [`consumer.md`](consumer.md).
|
|
8
|
+
|
|
9
|
+
Everything here compiles and passes: the complete example package is [`example/`](example) (`acme.loyalty`, a loyalty
|
|
10
|
+
programme for CRM clients), and the code blocks below that start with `// example/<file>` are quoted from it. CI
|
|
11
|
+
typechecks, builds and tests the example with the same CLI you use.
|
|
12
|
+
|
|
13
|
+
## 1. Concepts in five minutes
|
|
14
|
+
|
|
15
|
+
| Term | Meaning |
|
|
16
|
+
|---|---|
|
|
17
|
+
| **package** | a directory with a `package.json` that has an `iota` section, and TypeScript sources |
|
|
18
|
+
| **namespace** | the dotted owner prefix of every ID the package declares: `acme.loyalty`. Two or more lowercase segments; the first must not be a platform namespace (`core`, `crm`, …) |
|
|
19
|
+
| **resource** | anything the package declares: entity, overlay, command, query, operation, event, notice, workflow, permission, error, route, page, column… Its ID is `<namespace>.<name>` |
|
|
20
|
+
| **contract** | the *description* of a resource (`command("acme.loyalty.redeem", { input, output })`). Pure data: no handler |
|
|
21
|
+
| **implementation** | a handler bound to a contract by typed reference: `implement(Redeem, async (ctx, input) => …)` |
|
|
22
|
+
| **kit** | generated `@iota-kit/*` modules: typed references to what the platform and other packages publish (`@iota-kit/core`, `@iota-kit/crm`, …). References only, never handlers |
|
|
23
|
+
| **version** | an immutable build of the package. One version is *active* for the whole application |
|
|
24
|
+
| **binding** | which implementation serves a *replaceable* contract (a native command, a screen, the shell). One active binding per contract |
|
|
25
|
+
|
|
26
|
+
A package has up to three **graphs**, each an ES module entry declared in `package.json`:
|
|
27
|
+
|
|
28
|
+
| graph | file | may import | runs |
|
|
29
|
+
|---|---|---|---|
|
|
30
|
+
| contracts | `src/contracts.ts` | `@iota-uz/sdk/runtime`, `@iota-kit/*`, pure files, pure npm packages | everywhere (it is pure data) |
|
|
31
|
+
| server | `src/server.ts` | everything above, `@iota-uz/sdk/runtime/server`, Node built-ins, npm | in the platform's Node worker pool |
|
|
32
|
+
| client | `src/client.tsx` | contracts and the pure files the contracts graph reaches, `@iota-uz/sdk/runtime/client`, `@iota-uz/sdk/solid-ui`, `solid-js`, browser-safe npm | in the browser (Solid) |
|
|
33
|
+
|
|
34
|
+
The registry of a package is the set of **named exports** of the three entry modules that carry the SDK brand. There is
|
|
35
|
+
no `register()` call and no manifest to write: export a contract, a page or an implementation and it exists. A violated
|
|
36
|
+
graph rule (the client importing the server, a contract importing Node) is a build error with a file and line.
|
|
37
|
+
|
|
38
|
+
**Sharing code between the server and the browser.** The contracts graph is the shared, pure layer: whatever it reaches
|
|
39
|
+
can be imported by the server *and* the client. A file that only the server graph reaches is server code, and the client
|
|
40
|
+
may not import it (`graph.serverInClient`): it could carry business logic or secrets you never meant to ship to a
|
|
41
|
+
browser. So a calculation both sides need (a score, a price, a verdict) lives in a pure file — no `runtime/server`, no
|
|
42
|
+
Node built-ins — that `contracts.ts` imports or re-exports:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
// src/calc.ts — pure: numbers in, numbers out
|
|
46
|
+
export function weightedScore(scores: readonly number[], weights: readonly number[]): number { … }
|
|
47
|
+
|
|
48
|
+
// src/contracts.ts
|
|
49
|
+
export * as calc from "./calc" // or `import "./calc"`: either puts calc.ts in the shared layer
|
|
50
|
+
|
|
51
|
+
// src/server.ts and src/AssessmentScreen.tsx
|
|
52
|
+
import { weightedScore } from "./calc" // both graphs may import it now
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Two things surprise newcomers:
|
|
56
|
+
|
|
57
|
+
* **Data lives in Go.** Your handlers never open a database connection. They receive a *transaction handle* (`tx`) or a
|
|
58
|
+
read-only context and ask the platform to read and write. A transaction is opened and committed by Go; your Node code
|
|
59
|
+
only asks for it.
|
|
60
|
+
* **Handlers replay or restart.** Workflow code is replayed from a journal; an ordinary command may be retried by an
|
|
61
|
+
operator. Write them so that effects are named (`wf.step("voucher", …)`) and idempotent where they leave the system.
|
|
62
|
+
|
|
63
|
+
## 2. Quick start
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
npm install --save-dev @iota-uz/sdk esbuild@^0.25 # iota-ext, and the bundler its build worker loads (an optional peer)
|
|
67
|
+
npx iota-ext init loyalty --namespace acme.loyalty
|
|
68
|
+
cd loyalty
|
|
69
|
+
npm install # editor support and the lockfile publishing needs; the kit is not in node_modules
|
|
70
|
+
npx iota-ext check # typecheck + graph rules + manifest
|
|
71
|
+
npx iota-ext test # run *.test.ts on the in-memory test host
|
|
72
|
+
npx iota-ext build # artifacts and manifest in .iota/build
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`init` writes `package.json`, `tsconfig.json`, `.gitignore`, `src/contracts.ts`, `src/server.ts`, `src/server.test.ts`
|
|
76
|
+
(a passing test) and, unless you pass `--no-client`, `src/client.tsx` with a page `src/NotesScreen.tsx` that uses a UI kit
|
|
77
|
+
component, Tailwind utilities and `src/NotesScreen.module.css`, plus `src/css-modules.d.ts` (§13.6), and generates the kit for the SDK's own natives (`@iota-kit/core`,
|
|
78
|
+
`@iota-kit/crm`) **offline** into `.iota/kit/`. Everything works before you have access to any server. When you do,
|
|
79
|
+
`iota-ext kit pull` replaces the offline kit with the application's real one (see §5).
|
|
80
|
+
|
|
81
|
+
`iota-ext` is the `bin` of `@iota-uz/sdk` (Node ≥ 20.19). Full reference: §16.
|
|
82
|
+
|
|
83
|
+
`init` writes `"@iota-uz/sdk"` into `package.json` **exactly as you installed it**: a registry install becomes the exact
|
|
84
|
+
version of the CLI that ran it (`iota-ext --version`), not a range; a tarball, `file:` or `link:` install keeps that spec,
|
|
85
|
+
with a relative path rewritten for the new package directory, so the `npm install` that follows works. The extension runtime (`iota-ext`, `@iota-uz/sdk/runtime/*`) ships from that release on; earlier public builds of the
|
|
86
|
+
package have no `dist/runtime`, and a caret range could resolve to one of them. Keep the dependency on a release that
|
|
87
|
+
contains the runtime, and when you upgrade the SDK, upgrade it together with a fresh `kit generate`/`kit pull`.
|
|
88
|
+
|
|
89
|
+
## 3. Package layout
|
|
90
|
+
|
|
91
|
+
```text
|
|
92
|
+
loyalty/
|
|
93
|
+
├─ package.json the iota section: namespace, entries, capabilities
|
|
94
|
+
├─ package-lock.json required to publish when the package has any dependency besides @iota-uz/sdk
|
|
95
|
+
├─ tsconfig.json for your editor (see §4)
|
|
96
|
+
├─ .iota/kit/ the generated developer kit (§5): commit it
|
|
97
|
+
├─ .iota/build/ `iota-ext build` output: do not commit
|
|
98
|
+
├─ .gitignore node_modules and .iota/build (never .iota/kit)
|
|
99
|
+
├─ src/
|
|
100
|
+
│ ├─ contracts.ts contracts graph
|
|
101
|
+
│ ├─ server.ts server graph
|
|
102
|
+
│ ├─ client.tsx client graph (pages, navigation, cells)
|
|
103
|
+
│ ├─ *.tsx screens, loaded lazily from client.tsx
|
|
104
|
+
│ └─ *.test.ts tests (run by `iota-ext test`; never part of an artifact)
|
|
105
|
+
└─ docs/<locale>/ documentation for your users, markdown (§13.5)
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{
|
|
110
|
+
"name": "@acme/loyalty",
|
|
111
|
+
"type": "module",
|
|
112
|
+
"iota": {
|
|
113
|
+
"namespace": "acme.loyalty",
|
|
114
|
+
"contracts": "./src/contracts.ts",
|
|
115
|
+
"server": "./src/server.ts",
|
|
116
|
+
"client": "./src/client.tsx",
|
|
117
|
+
"capabilities": { "network": ["api.partner.example"], "secrets": ["PARTNER_TOKEN"] }
|
|
118
|
+
},
|
|
119
|
+
"dependencies": { "@iota-uz/sdk": "0.5.6" }
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
* Every entry is optional, but at least one is required. Paths must stay inside the package.
|
|
124
|
+
* `capabilities.network` lists the hosts server code may reach with `fetch`; `capabilities.secrets` lists the secret
|
|
125
|
+
names `ctx.secrets.get("NAME")` may read. Anything undeclared is refused. Secrets are never in the source or the
|
|
126
|
+
artifact: an administrator provides their values to the application.
|
|
127
|
+
* Any other dependency (npm packages for the server or client graph) needs a committed `package-lock.json`; the platform
|
|
128
|
+
installs with `npm ci --ignore-scripts`. `@iota-uz/sdk` itself is provided by the platform and never installed from
|
|
129
|
+
the registry.
|
|
130
|
+
* Kit modules and npm dependencies are **bundled** into the artifacts; only `@iota-uz/sdk/runtime*` stays external.
|
|
131
|
+
Client chunks do not carry Solid either: the host shares one Solid with every package.
|
|
132
|
+
|
|
133
|
+
## 4. TypeScript configuration
|
|
134
|
+
|
|
135
|
+
The platform compiles with fixed options so that `iota-ext check`, the configurator and the server always agree:
|
|
136
|
+
`strict`, target ES2022, `module: ESNext`, `moduleResolution: Bundler`, `jsx: preserve` with
|
|
137
|
+
`jsxImportSource: "solid-js"`, libs `ES2022` + `DOM`, Node typings (`@types/node`), `skipLibCheck`. Your `tsconfig.json`
|
|
138
|
+
only serves the editor and should mirror those options. The scaffold writes:
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
{
|
|
142
|
+
"compilerOptions": {
|
|
143
|
+
"target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler",
|
|
144
|
+
"strict": true, "noEmit": true, "skipLibCheck": true,
|
|
145
|
+
"lib": ["ES2022", "DOM", "DOM.Iterable"],
|
|
146
|
+
"types": ["node"],
|
|
147
|
+
"paths": { "@iota-kit/*": ["./.iota/kit/*"] },
|
|
148
|
+
"jsx": "preserve", "jsxImportSource": "solid-js"
|
|
149
|
+
},
|
|
150
|
+
"include": ["src"]
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
* Install `typescript`, `@types/node` and (for a client graph) `solid-js` as dev dependencies; `npm install` after
|
|
155
|
+
`init` does it. The SDK's own typings come from `@iota-uz/sdk`.
|
|
156
|
+
* `types: ["node"]` is what lets tests import `node:assert`; you do not need it if you use the SDK's `assert` (§14).
|
|
157
|
+
* Import local files without extensions (`import * as c from "./contracts"`); the bundler resolves them.
|
|
158
|
+
* `paths` is the one alias you need: it lets the editor (and your own `tsc`) resolve `@iota-kit/*` from `.iota/kit/`, where
|
|
159
|
+
the kit lives (§5). `iota-ext` does not read it: it resolves the kit itself. `iota-ext kit generate` adds the entry to a
|
|
160
|
+
`tsconfig.json` written before the kit moved out of `node_modules` (a tsconfig with comments is left alone and the
|
|
161
|
+
command prints the line to add).
|
|
162
|
+
* Do not rely on other options the platform does not use (other path aliases, `experimentalDecorators`, JSX other than Solid).
|
|
163
|
+
|
|
164
|
+
## 5. The developer kit
|
|
165
|
+
|
|
166
|
+
Contracts you did not declare (users, CRM clients, other packages' commands) are referenced through **kit modules**:
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
import * as core from "@iota-kit/core" // core.User, core.Created (the user-created event)
|
|
170
|
+
import * as crm from "@iota-kit/crm" // crm.Client, crm.ListsClients (the native list), crm.Created, crm.Updated, crm.SaveClient, crm.UpsertClient
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
A kit module is generated from a **catalog snapshot**: native entities (with fields and key types), native lists, native
|
|
174
|
+
events and the Go-implemented commands, operations and queries of the application, plus the public contracts of the
|
|
175
|
+
packages that are active. You get one of three ways:
|
|
176
|
+
|
|
177
|
+
| how | command | when |
|
|
178
|
+
|---|---|---|
|
|
179
|
+
| the SDK's own natives, offline | `iota-ext kit generate` (also done by `init`) | no server yet; everything the SDK itself publishes |
|
|
180
|
+
| an application's snapshot file | `iota-ext kit generate --catalog app.json` | the application exported its native catalog; works offline |
|
|
181
|
+
| the live kit | `iota-ext kit pull --server https://erp.example.com --token-env IOTA_TOKEN` | you can reach the application's `/_ext/manage` API |
|
|
182
|
+
|
|
183
|
+
`kit generate` and `kit pull` write the modules to **`.iota/kit/<ns>/`** (`index.js`, `index.d.ts`, `package.json`) and
|
|
184
|
+
the snapshot in `.iota/kit/kit.json`: its hash and the SHA-256 of every file. The kit is deliberately **not** in
|
|
185
|
+
`node_modules`: a package manager deletes what it did not install, so a generated `node_modules/@iota-kit` vanished on
|
|
186
|
+
every `npm install`. `.iota/kit` is yours to commit (it pins the snapshot the package was written against and needs no
|
|
187
|
+
server to restore); `iota-ext` and its build worker resolve `@iota-kit/*` from it (the application builds against its own
|
|
188
|
+
kit), your editor through the `paths` entry of `tsconfig.json` (§4). A package that still has the old `node_modules/@iota-kit` layout keeps
|
|
189
|
+
working (the CLI says so); the next `kit generate` or `kit pull` moves it. `iota-ext kit status` verifies the kit
|
|
190
|
+
against its record: each module is `ok`, `missing` (a module or file is gone), `modified` (a file was edited) or
|
|
191
|
+
`unrecorded`, and the exit code is 1 when the kit is damaged. The token is read
|
|
192
|
+
from the environment variable you name (never from the command line); `--cookie-env VAR` sends a session cookie header
|
|
193
|
+
instead. The user needs the extensions *read* permission. An application exports a snapshot with
|
|
194
|
+
`GET /_ext/manage/catalog/natives` or `catalog.Natives(set).Snapshot()` over its composed `native.Set`; the SDK's own
|
|
195
|
+
(the set of `modules.Natives()`) is committed as
|
|
196
|
+
`web/runtime/catalog/sdk-natives.json` (regenerate it with `go run ./cmd/extruntime-catalog`) and ships in the
|
|
197
|
+
distribution. Rerun the command whenever the application's natives or other packages change; the build pins the kit hash
|
|
198
|
+
in the manifest.
|
|
199
|
+
|
|
200
|
+
What a module exports:
|
|
201
|
+
|
|
202
|
+
* **Native entities** (`core.User`, `crm.Client`) with their real fields and **key type** (`int64` for both; a ref's key
|
|
203
|
+
is a decimal string such as `"42"`). You can read them, reference them in fields, put an overlay on them, but not
|
|
204
|
+
write them with `tx.insert/update/delete` (§6).
|
|
205
|
+
* **Native lists** (`crm.ListsClients`) that your `column(...)` contracts extend.
|
|
206
|
+
* **Native routes** (`crm.Clients`, the CRM clients page) you link to or replace with a screen binding.
|
|
207
|
+
* **Events** (`core.Created`, `crm.Created`, `crm.Updated`), to subscribe to. Native events are published by Go in
|
|
208
|
+
the transaction of the change they report, so a subscription sees them only after that change committed and never
|
|
209
|
+
for a change that rolled back.
|
|
210
|
+
* **Native commands, operations and queries**, implemented in Go (`crm.SaveClient`, `crm.UpsertClient`). You call them,
|
|
211
|
+
guard them and — for commands — replace them (§7.4).
|
|
212
|
+
* The public contracts of other active packages.
|
|
213
|
+
|
|
214
|
+
Export names are the PascalCase of the last segment of the ID, a version suffix dropped; when two IDs would collide
|
|
215
|
+
they take more segments (`crm.clients` the route and `crm.lists.clients` the list become `Clients` and
|
|
216
|
+
`ListsClients`). The offline SDK kit and an application built on the SDK modules are generated from the same module
|
|
217
|
+
registrations, so they agree on these names; an application that adds natives of its own can add names (and push an
|
|
218
|
+
existing one to more segments when it collides), so pull the kit of the application you target.
|
|
219
|
+
|
|
220
|
+
If an import fails, the module is not in the kit: the diagnostic is `graph.unknownKit` (once per file and module, instead of
|
|
221
|
+
TS2307) and names the commands that install it (`kit generate`, `kit generate --catalog <file>`, `kit pull`). The follow-on
|
|
222
|
+
type errors it causes (implicit `any`, missing properties on values typed through the missing module) are hidden, with one
|
|
223
|
+
`kit.followOn` warning saying how many, so the first error you see is the cause. When the kit's files are gone or edited, the
|
|
224
|
+
hint says so and points at `kit status`.
|
|
225
|
+
|
|
226
|
+
## 6. Data
|
|
227
|
+
|
|
228
|
+
### 6.1 Entities
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
// example/src/contracts.ts
|
|
232
|
+
export const Reward = entity("acme.loyalty.reward", {
|
|
233
|
+
name: field.text({ maxLength: 80 }).unique(),
|
|
234
|
+
cost: field.int(),
|
|
235
|
+
active: field.bool().default(true),
|
|
236
|
+
})
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Each entity is one tenant-scoped PostgreSQL table owned by your package. Every row also has `key` (a uuid), `ref` (the
|
|
240
|
+
typed pointer to itself: `row.ref`), `createdAt`, `updatedAt` and `rowVersion`. These names are reserved.
|
|
241
|
+
|
|
242
|
+
Field builders: `field.text({maxLength})` (`string` is an alias), `int`, `int64` (a decimal string on the wire),
|
|
243
|
+
`decimal({precision, scale})` (a string), `bool`, `date` (`"YYYY-MM-DD"`), `datetime` (RFC 3339), `uuid`,
|
|
244
|
+
`enum([...])`, `json<T>()` (JSON `T` only; not filterable), `ref(Entity)`. Modifiers:
|
|
245
|
+
|
|
246
|
+
* `.optional()` – nullable and may be omitted on insert: `T | null` on read, `T | null | undefined` on write.
|
|
247
|
+
* `.nullable()` – a nullable column that must be given.
|
|
248
|
+
* `.default(x)` – may be omitted on insert; the default is validated and recorded even when falsy.
|
|
249
|
+
* `.unique()`, `.index()`, `.label({...})`, `.renamedFrom("oldKey")` (the column follows the field across renames).
|
|
250
|
+
|
|
251
|
+
Use `t.*` (the same builders without column semantics) for inputs and outputs.
|
|
252
|
+
|
|
253
|
+
**Money and other exact numbers.** `decimal` and `int64` travel as strings (JSON numbers lose precision), typed as
|
|
254
|
+
branded `Decimal` / `Int64`. Build them with the wire helpers from `@iota-uz/sdk/runtime`; they validate the format and,
|
|
255
|
+
for a decimal, precision and scale:
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
import { decimal, int64 } from "@iota-uz/sdk/runtime"
|
|
259
|
+
|
|
260
|
+
await tx.insert(Assessment, { premium: decimal("100000.00", { precision: 18, scale: 2 }), sum: decimal("10000000") })
|
|
261
|
+
const premium = Number(row.premium) // arithmetic is yours: the platform stores and compares exactly
|
|
262
|
+
const ours = decimal((premium * share / 100).toFixed(2))
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
The platform never does arithmetic on your behalf. Converting to `Number` is fine for ratios and display; for sums that
|
|
266
|
+
must stay exact, compute on integers of the smallest unit (`int64` cents) or use a decimal library in your package.
|
|
267
|
+
|
|
268
|
+
### 6.2 Reading and writing
|
|
269
|
+
|
|
270
|
+
```ts
|
|
271
|
+
// example/src/server.ts
|
|
272
|
+
export const catalog = implement(c.Catalog, async (q, input) => {
|
|
273
|
+
const rewards = await q.find(c.Reward, {
|
|
274
|
+
where: input.onlyActive === true ? { active: true } : {},
|
|
275
|
+
orderBy: [{ field: "cost" }, { field: "name" }],
|
|
276
|
+
})
|
|
277
|
+
return rewards.map((r) => ({ reward: r.ref, name: r.name, cost: r.cost, active: r.active }))
|
|
278
|
+
})
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
`get(entity, ref)`, `find(entity, { where, orderBy, limit, offset })` (default limit 100, maximum 1000) and
|
|
282
|
+
`count(entity, where)` exist on every context. `tx.insert`, `tx.update(entity, ref, patch, { rowVersion })`,
|
|
283
|
+
`tx.delete` and `tx.put(overlay, baseRef, values)` exist on transactions only. Rules the types and the host enforce:
|
|
284
|
+
|
|
285
|
+
* **Filters** are a conjunction of conditions on fields, system columns (`createdAt`, `updatedAt`, `key`) or dotted paths
|
|
286
|
+
through refs (`"holder.name"`, at most four segments). A bare value means equality. Operators: `eq ne in isNull`,
|
|
287
|
+
ranges `lt lte gt gte` on `int int64 decimal date datetime string`, `like` on strings only (`%` and `_`), `or: [...]`.
|
|
288
|
+
`null` follows SQL: `eq: null` is `IS NULL`, `ne: x` is `IS DISTINCT FROM`.
|
|
289
|
+
* **Ordering** works on `int int64 decimal date datetime string` fields and `createdAt`/`updatedAt` (also through
|
|
290
|
+
refs). Nulls sort last ascending. Ordering by an enum, bool, uuid or ref field is a type error whose text says so.
|
|
291
|
+
* Read **access rules** and **hidden fields** (below) apply before filtering, counting and paging.
|
|
292
|
+
* `tx.update(..., { rowVersion })` fails with `data.versionConflict` unless the row is still at that version.
|
|
293
|
+
* `tx.insert/update/delete` take **your package's own** entities only. A native or foreign entity gives a type error
|
|
294
|
+
that names the published operation to call instead (`tx.call(crm.UpsertClient, …)`), and a runtime `data.nativeWrite`
|
|
295
|
+
/ `data.foreignWrite` denial if you cast around it.
|
|
296
|
+
|
|
297
|
+
### 6.3 Access rules
|
|
298
|
+
|
|
299
|
+
Rules and gates refer to **permissions**, which you declare in the contracts graph. A permission is a named capability with a
|
|
300
|
+
label for the role editor; the ID lives in your namespace, and the label is a map of locale to text:
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
// example/src/contracts.ts
|
|
304
|
+
export const Manage = permission("acme.loyalty.manage", { label: { en: "Manage loyalty", ru: "Управление лояльностью" } })
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
```ts
|
|
308
|
+
// example/src/contracts.ts
|
|
309
|
+
export const Redemption = entity(
|
|
310
|
+
"acme.loyalty.redemption",
|
|
311
|
+
{
|
|
312
|
+
client: field.ref(crm.Client).index(),
|
|
313
|
+
reward: field.ref(Reward),
|
|
314
|
+
cost: field.int(),
|
|
315
|
+
status: field.enum(["pending", "approved", "rejected"]).default("pending"),
|
|
316
|
+
requestedBy: field.ref(core.User),
|
|
317
|
+
},
|
|
318
|
+
// Managers see every redemption, everybody else the ones they requested.
|
|
319
|
+
{ access: { read: [{ when: Manage, rows: "all" }, { rows: { requestedBy: $.user } }] } },
|
|
320
|
+
)
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
`access.read` is a list of rules; a row is visible when any rule whose permission the user holds matches. `rows` is
|
|
324
|
+
`"all"`, `"none"` (an explicit deny; an empty list is an error) or a filter. `$.user` stands for the acting user and
|
|
325
|
+
compares only with refs to `core.user`. `access.fields` lists the permissions needed to read a field; a user who cannot
|
|
326
|
+
read a field cannot write it either. These rules hold on **every surface**: handlers, the native lists, exports, MCP.
|
|
327
|
+
|
|
328
|
+
> **Contract permission vs read rules.** A contract's `permission` (on a command, query or operation) is a **gate on the
|
|
329
|
+
> call**: the host checks that the acting user holds it before dispatching, from the browser (`POST /_ext/rpc`), MCP,
|
|
330
|
+
> workflows and triggers alike. Read rules are **row filters inside the data layer**: they decide which rows a read
|
|
331
|
+
> returns, whoever calls and through whichever contract. Use the first to say who may *do* something, the second to say
|
|
332
|
+
> who may *see* which records. A page's `permission` only controls whether the page and its menu entry are offered.
|
|
333
|
+
|
|
334
|
+
### 6.4 Overlays and list columns
|
|
335
|
+
|
|
336
|
+
```ts
|
|
337
|
+
// example/src/contracts.ts
|
|
338
|
+
export const ClientLoyalty = overlay(
|
|
339
|
+
"acme.loyalty.clientLoyalty",
|
|
340
|
+
crm.Client,
|
|
341
|
+
{
|
|
342
|
+
tier: field.enum(["standard", "silver", "gold"]).default("standard"),
|
|
343
|
+
points: field.int().default(0),
|
|
344
|
+
note: field.text().optional(),
|
|
345
|
+
},
|
|
346
|
+
{ access: { fields: { note: [Manage] } } },
|
|
347
|
+
)
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
An overlay is a separate 1:1 table keyed by the base record's key; it is how you add fields to a native entity. Every
|
|
351
|
+
overlay field must be optional, nullable or defaulted, because most clients have no overlay row: `tx.get(overlay, ref)`
|
|
352
|
+
returns `null` for them (absence is explicit in the type) and the defaults apply to filters and lists. Write with
|
|
353
|
+
`tx.put(overlay, baseRef, { points })`; omitted fields keep their value.
|
|
354
|
+
|
|
355
|
+
```ts
|
|
356
|
+
// example/src/contracts.ts
|
|
357
|
+
export const TierColumn = column(crm.ListsClients, {
|
|
358
|
+
id: "acme.loyalty.tier",
|
|
359
|
+
field: ClientLoyalty.fields.tier,
|
|
360
|
+
label: { en: "Loyalty tier", ru: "Уровень" },
|
|
361
|
+
filterable: true,
|
|
362
|
+
sortable: true,
|
|
363
|
+
exportable: true,
|
|
364
|
+
})
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
`column` adds an overlay field to a native list: display, filter, sort and CSV/Excel export. **Its `id` must be the full
|
|
368
|
+
namespaced ID** (`acme.loyalty.tier`, not `tier`); a short one fails the manifest check. A custom renderer for the cell
|
|
369
|
+
is a client-graph value (§13.1).
|
|
370
|
+
|
|
371
|
+
## 7. Contracts and handlers
|
|
372
|
+
|
|
373
|
+
### 7.1 The four callable kinds
|
|
374
|
+
|
|
375
|
+
| kind | context | transaction | callable from |
|
|
376
|
+
|---|---|---|---|
|
|
377
|
+
| `query` | `QueryContext` (read-only) | a read snapshot | browser, MCP, other handlers (`q.query`, `tx.query`, `ctx.query`) |
|
|
378
|
+
| `command` (ordinary) | `CommandContext` | opens its own with `ctx.transaction(cb)` (zero or more times) | browser, MCP, workflows (`wf.call`), `ctx.call` |
|
|
379
|
+
| `command` with `atomic: true` | `Tx` | the whole handler is one transaction | as above, and `tx.call` |
|
|
380
|
+
| `operation` | `Tx` | joins the caller's | `tx.call`, `wf.transaction(name, Op, input)`; **never** from the browser |
|
|
381
|
+
|
|
382
|
+
An **operation** is the reusable, atomic domain primitive: other packages and your own commands call it, and guards
|
|
383
|
+
attach to it. Atomicity (`atomic: true`) is part of the public contract: a replacement implementation of an atomic
|
|
384
|
+
command also receives a `Tx`.
|
|
385
|
+
|
|
386
|
+
```ts
|
|
387
|
+
// example/src/contracts.ts
|
|
388
|
+
export const AdjustPoints = operation("acme.loyalty.adjustPoints", {
|
|
389
|
+
input: t.object({ client: t.ref(crm.Client), delta: t.int() }),
|
|
390
|
+
output: t.object({ points: t.int() }),
|
|
391
|
+
errors: [NotEnoughPoints],
|
|
392
|
+
})
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
Inputs and outputs are validated against their schemas by Go on every call, independently of TypeScript. `errors` is the
|
|
396
|
+
closed list of domain errors the contract may raise.
|
|
397
|
+
|
|
398
|
+
### 7.2 Handlers
|
|
399
|
+
|
|
400
|
+
```ts
|
|
401
|
+
// example/src/server.ts
|
|
402
|
+
export const adjustPoints = implement(c.AdjustPoints, async (tx, input) => {
|
|
403
|
+
const current = (await tx.get(c.ClientLoyalty, input.client))?.points ?? 0
|
|
404
|
+
const next = current + input.delta
|
|
405
|
+
if (next < 0) throw c.NotEnoughPoints.of({ have: current, need: -input.delta })
|
|
406
|
+
const row = await tx.put(c.ClientLoyalty, input.client, { points: next })
|
|
407
|
+
await tx.emit(c.PointsChanged, { subject: input.client, payload: { points: next, delta: input.delta } })
|
|
408
|
+
return { points: row.points }
|
|
409
|
+
})
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
A handler may return synchronously; `async` is the norm. Each context also has `user` (the acting principal and
|
|
413
|
+
`user.has(permission)`), `invocation`, and `log`. Command contexts have `secrets`.
|
|
414
|
+
|
|
415
|
+
### 7.3 Transaction semantics
|
|
416
|
+
|
|
417
|
+
* **A transaction is Go's.** `ctx.transaction(cb)` asks Go to open one, runs `cb(tx)`, then commits (or rolls back when
|
|
418
|
+
`cb` throws). It cannot be nested. Reads and writes inside see the transaction's own writes.
|
|
419
|
+
* **An atomic command or operation is one transaction** from the first line to the return.
|
|
420
|
+
* **`tx.call(Operation | AtomicCommand, input)` joins the caller's transaction**: one commit, one rollback. Ordinary
|
|
421
|
+
commands and queries are rejected at the type level with a message that names the right call
|
|
422
|
+
(`ctx.call`, `tx.query`).
|
|
423
|
+
* **`tx.emit`, `tx.notify`, `tx.start`, `tx.signal` are enqueued with the data.** They take effect when the transaction
|
|
424
|
+
commits and vanish on rollback. After commit, each active subscription gets its own transaction; notices are rendered
|
|
425
|
+
and sent after commit.
|
|
426
|
+
* **An ordinary command is not atomic.** Each `ctx.transaction` commits on its own, so a crash between two of them
|
|
427
|
+
leaves the first committed; the command is never retried blindly. Put work that must be all-or-nothing in one
|
|
428
|
+
transaction, or make the command atomic.
|
|
429
|
+
* **Outside calls belong between transactions.** Call `fetch`, read secrets and wait *outside* `ctx.transaction`, as
|
|
430
|
+
`redeem` does below; do not hold a database transaction open across the network.
|
|
431
|
+
* **One thing at a time inside a transaction.** Concurrent calls on one `tx` (`Promise.all`) fail fast; `await` them.
|
|
432
|
+
* **`tx.start(Workflow, input, { key })`** needs a `key` outside subscriptions and workflows (the key dedupes the start:
|
|
433
|
+
the same key never starts a second instance). Inside a subscription or a workflow the key is derived and optional.
|
|
434
|
+
Omitting it where it is required is a compile error (`Expected 3 arguments`) and the CLI adds the hint
|
|
435
|
+
`tx.start needs a start key`.
|
|
436
|
+
* **`ctx.query` reads a snapshot**; inside a transaction `tx.get/find/count/query` read that transaction's state.
|
|
437
|
+
|
|
438
|
+
```ts
|
|
439
|
+
// example/src/server.ts
|
|
440
|
+
export const redeem = implement(c.Redeem, async (ctx, input) => {
|
|
441
|
+
const reward = await ctx.query.get(c.Reward, input.reward)
|
|
442
|
+
if (reward === null || !reward.active) throw c.RewardUnavailable.of({ reward: input.reward.key })
|
|
443
|
+
const stock = await fetch(`https://api.partner.example/stock/${encodeURIComponent(reward.name)}`, {
|
|
444
|
+
headers: { authorization: `Bearer ${await ctx.secrets.get("PARTNER_TOKEN")}` },
|
|
445
|
+
})
|
|
446
|
+
if (!stock.ok) throw c.RewardUnavailable.of({ reward: input.reward.key })
|
|
447
|
+
|
|
448
|
+
const redemption = await ctx.transaction(async (tx) => {
|
|
449
|
+
await tx.call(c.AdjustPoints, { client: input.client, delta: -reward.cost })
|
|
450
|
+
const row = await tx.insert(c.Redemption, {
|
|
451
|
+
client: input.client, reward: input.reward, cost: reward.cost, requestedBy: ref(core.User, ctx.user.userId),
|
|
452
|
+
})
|
|
453
|
+
// Outside subscriptions and workflows a start needs a key: the same key never starts a second instance.
|
|
454
|
+
await tx.start(c.Approval, { redemption: row.ref }, { key: `approval:${row.key}` })
|
|
455
|
+
return row
|
|
456
|
+
})
|
|
457
|
+
return { redemption: redemption.ref }
|
|
458
|
+
})
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
### 7.4 Calling and replacing native commands
|
|
462
|
+
|
|
463
|
+
Go modules publish **native contracts**: operations, atomic commands, ordinary commands and queries implemented in Go and
|
|
464
|
+
visible in the kit. The CRM publishes two for its clients:
|
|
465
|
+
|
|
466
|
+
* `crm.UpsertClient` (operation): the invariant behind every client write: authorization, value validation
|
|
467
|
+
(phone, e-mail, PIN, country), persistence, change history and the client events (`crm.Created` / `crm.Updated`,
|
|
468
|
+
in the same transaction, §9).
|
|
469
|
+
* `crm.SaveClient` (ordinary command): the intent the client forms run; its Go default calls `UpsertClient` in one
|
|
470
|
+
transaction.
|
|
471
|
+
|
|
472
|
+
You **call** a native operation like your own: `tx.call(crm.UpsertClient, { client, phone })`. A package that wants to
|
|
473
|
+
change *what saving a client means* **replaces the command**: it implements `crm.SaveClient` and writes through the
|
|
474
|
+
same operation, so the invariants and every guard on the operation still hold.
|
|
475
|
+
|
|
476
|
+
```ts
|
|
477
|
+
// example/src/server.ts
|
|
478
|
+
export const saveClient = implement(crm.SaveClient, async (ctx, input) =>
|
|
479
|
+
ctx.transaction(async (tx) => {
|
|
480
|
+
const saved = await tx.call(crm.UpsertClient, input)
|
|
481
|
+
if (saved.created) await tx.call(c.AdjustPoints, { client: saved.client, delta: 50 })
|
|
482
|
+
return saved
|
|
483
|
+
}),
|
|
484
|
+
)
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
Publishing this does **not** change behaviour by itself: an implementation of a contract you do not own is a
|
|
488
|
+
*replacement candidate*. It runs when an administrator binds it (`ext_bind` over MCP, `POST /_ext/manage/bindings` with
|
|
489
|
+
`{"slotKind":"command","targetId":"crm.commands.saveClient","package":"acme.loyalty","version":"…","export":"saveClient"}`,
|
|
490
|
+
or the configurator's Bindings tab). One implementation is active per command for the whole application, there is no
|
|
491
|
+
fallback if it fails, and unbinding (`ext_unbind`) returns the Go default. Rules to remember:
|
|
492
|
+
|
|
493
|
+
* The replacement has the shape of the original: ordinary command → `CommandContext`, atomic → `Tx`.
|
|
494
|
+
* A generic write to `crm.client` is refused (`data.nativeWrite`); the operation is the only way in.
|
|
495
|
+
* A guard on `crm.UpsertClient` (yours, or another package's) applies to every caller, replacement or Go default alike.
|
|
496
|
+
* In tests the Go default does not exist: bind a double of the operation (§14.4).
|
|
497
|
+
|
|
498
|
+
## 8. Errors and validation
|
|
499
|
+
|
|
500
|
+
Handlers signal failure by **throwing**; the host turns it into a wire error `{kind, code, params, issues}`:
|
|
501
|
+
|
|
502
|
+
| you throw | kind | use for |
|
|
503
|
+
|---|---|---|
|
|
504
|
+
| `NotEnoughPoints.of({ have, need })` | `domain` | an expected business outcome a caller can handle; declared in the contract's `errors` (a closed list) |
|
|
505
|
+
| `validation(CostMustBePositive.at(["cost"], { min: 1 }))` | `validation` | field-level problems; any number of namespaced issues |
|
|
506
|
+
| *(host)* | `denied` | permission or access refusals (`data.denied`, `data.fieldNotAccessible`, `data.nativeWrite`) |
|
|
507
|
+
| any other `Error` | `internal` | bugs; the message is hidden from the caller |
|
|
508
|
+
|
|
509
|
+
```ts
|
|
510
|
+
// example/src/contracts.ts
|
|
511
|
+
export const NotEnoughPoints = domainError("acme.loyalty.notEnoughPoints", t.object({ have: t.int(), need: t.int() }))
|
|
512
|
+
export const RewardUnavailable = domainError("acme.loyalty.rewardUnavailable", t.object({ reward: t.string() }))
|
|
513
|
+
export const CostMustBePositive = issue("acme.loyalty.costMustBePositive", t.object({ min: t.int() }))
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
```ts
|
|
517
|
+
// example/src/server.ts
|
|
518
|
+
export const createReward = implement(c.CreateReward, async (tx, input) => {
|
|
519
|
+
if (input.cost <= 0) throw validation(c.CostMustBePositive.at(["cost"], { min: 1 }))
|
|
520
|
+
const row = await tx.insert(c.Reward, { name: input.name.trim(), cost: input.cost })
|
|
521
|
+
return { reward: row.ref }
|
|
522
|
+
})
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
`validation()` accepts only `Issue.at(...)` results; `ContractError` has no public constructor. The host enforces the closed `errors` list: a domain error the contract does not declare is rejected. The data layer raises stable codes you can match in tests:
|
|
526
|
+
`data.notFound`, `data.versionConflict` (domain), `data.unique`, `data.reference` (validation, issue path = field),
|
|
527
|
+
`data.denied`, `data.fieldNotAccessible`, `data.nativeWrite`, `data.foreignWrite` (denied).
|
|
528
|
+
|
|
529
|
+
In the browser, `isError(err, NotEnoughPoints)` narrows a failed call to the declared error with typed `params`, and
|
|
530
|
+
`issuesOf(err, CostMustBePositive)` returns the typed issues (see `RewardsScreen.tsx`).
|
|
531
|
+
|
|
532
|
+
Guards are *additive* checks that run in the same transaction regardless of who implements the contract:
|
|
533
|
+
|
|
534
|
+
```ts
|
|
535
|
+
// example/src/server.ts
|
|
536
|
+
export const deltaLimit = guard("acme.loyalty.deltaLimit", c.AdjustPoints, async (_ctx, input) => {
|
|
537
|
+
if (Math.abs(input.delta) > 10_000) throw validation(c.DeltaTooLarge.at(["delta"], { max: 10_000 }))
|
|
538
|
+
})
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
```ts
|
|
542
|
+
// example/src/server.ts
|
|
543
|
+
export const rewardRule = writeRule("acme.loyalty.rewardRule", c.Reward, async (_ctx, change) => {
|
|
544
|
+
if (change.proposed !== null && change.proposed.cost > 1_000_000) throw validation(c.CostMustBePositive.at(["cost"], { min: 1 }))
|
|
545
|
+
})
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
* `guard(id, Operation | AtomicCommand, (ctx, input) => …)` checks an operation or atomic command call.
|
|
549
|
+
* `writeRule(id, Entity, (ctx, { op, existing, proposed, changed }) => …)` runs in the writing transaction before any
|
|
550
|
+
write of that entity, whatever code path writes it.
|
|
551
|
+
* `precheck(id, OrdinaryCommand, (q, input) => …)` is a *preliminary* check on a read snapshot for an ordinary command:
|
|
552
|
+
useful for early feedback, not a race-free guarantee.
|
|
553
|
+
|
|
554
|
+
`change.op` is `"insert"`, `"update"` or `"delete"`; `existing` is the row before (null on insert), `proposed` the row
|
|
555
|
+
after (null on delete) and `changed` the fields an update patches. That makes rules such as *append-only* or *frozen
|
|
556
|
+
once published* one line each:
|
|
557
|
+
|
|
558
|
+
```ts
|
|
559
|
+
// an append-only log: rows are written once and never changed or removed
|
|
560
|
+
export const logIsAppendOnly = writeRule("acme.reinsurance.logIsAppendOnly", c.ChangeLog, async (_ctx, change) => {
|
|
561
|
+
if (change.op !== "insert") throw validation(c.LogIsImmutable.at([], {}))
|
|
562
|
+
})
|
|
563
|
+
// a published parameter set is frozen
|
|
564
|
+
export const publishedIsFrozen = writeRule("acme.reinsurance.publishedIsFrozen", c.ParameterSet, async (_ctx, change) => {
|
|
565
|
+
if (change.existing?.status === "published") throw validation(c.PublishedIsFrozen.at([], {}))
|
|
566
|
+
})
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
A rule refuses with a validation issue (or a declared domain error); it applies to every write through the platform,
|
|
570
|
+
whoever makes it. Purging a package's data (`ext_package_purge`, an administrator action that drops the package's tables)
|
|
571
|
+
is not a write and runs no rules.
|
|
572
|
+
|
|
573
|
+
All three get a **read-only** context (`get find count query user log`) and reject by throwing. Their IDs become the
|
|
574
|
+
`source` of the issues they raise. A guard on an operation applies to every caller, including other packages and Go.
|
|
575
|
+
|
|
576
|
+
## 9. Events and subscriptions
|
|
577
|
+
|
|
578
|
+
```ts
|
|
579
|
+
// example/src/contracts.ts
|
|
580
|
+
export const PointsChanged = event("acme.loyalty.pointsChanged.v1", {
|
|
581
|
+
subject: crm.Client,
|
|
582
|
+
payload: t.object({ points: t.int(), delta: t.int() }),
|
|
583
|
+
})
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
```ts
|
|
587
|
+
// example/src/server.ts
|
|
588
|
+
export const onPointsChanged = subscribe("acme.loyalty.onPointsChanged", c.PointsChanged, async (tx, event) => {
|
|
589
|
+
const tier = event.payload.points >= 1000 ? "gold" : event.payload.points >= 300 ? "silver" : "standard"
|
|
590
|
+
await tx.put(c.ClientLoyalty, event.subject, { tier })
|
|
591
|
+
})
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
* Event IDs end in a version (`.v1`); a published payload never changes, publish `.v2` instead.
|
|
595
|
+
* `tx.emit(Event, { subject, payload })` is atomic with the data. After the commit, every active subscription receives
|
|
596
|
+
the event in **its own transaction**; a receipt per `(subscription, event)` makes redelivery a no-op, and one failing
|
|
597
|
+
event is retried with back-off and finally dead-lettered without blocking the others.
|
|
598
|
+
* A subscription runs as the event's initiator, or — for events without a user — as the **owner-user** an administrator
|
|
599
|
+
assigns to the trigger (`ext_owner_assign`). Without an owner the delivery is `blocked`, not lost.
|
|
600
|
+
* Subscribe to platform events through the kit (`subscribe("…", core.Created, handler)`). `tx.start` inside a
|
|
601
|
+
subscription needs no key: the delivery derives one, so redelivery cannot start a second workflow.
|
|
602
|
+
* Platform events are published by Go through the same outbox, **in the transaction of the change**: `core.Created`
|
|
603
|
+
(`core.user.created.v1`) when a user is created; `crm.Created` / `crm.Updated` (`crm.client.created.v1` /
|
|
604
|
+
`crm.client.updated.v1`, subject `crm.client`) by `crm.UpsertClient`, so every client write that goes through it
|
|
605
|
+
— the CRM forms, a `crm.SaveClient` replacement, your own `tx.call(crm.UpsertClient, …)` — publishes one. The
|
|
606
|
+
payload carries the client's published fields (`clientId`, `firstName`, optional `lastName`, `middleName`,
|
|
607
|
+
`phone`, `email`; never PIN or passport) and, for updates, `changed`: the `crm.client` field IDs the write changed.
|
|
608
|
+
A save that rolls back publishes nothing.
|
|
609
|
+
|
|
610
|
+
```ts
|
|
611
|
+
export const onClientUpdated = subscribe("acme.loyalty.onClientUpdated", crm.Updated, async (tx, event) => {
|
|
612
|
+
if (event.payload.changed.includes("phone")) tx.log.info("client phone changed", { client: event.payload.clientId })
|
|
613
|
+
})
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
## 10. Workflows
|
|
617
|
+
|
|
618
|
+
A workflow is a long-running function that survives restarts. The platform stores a **journal** of completed steps and
|
|
619
|
+
**replays** your function from the top, answering finished primitives from the journal; a primitive that cannot finish
|
|
620
|
+
yet (a sleep, a signal, a human task) *suspends* the run and frees the worker.
|
|
621
|
+
|
|
622
|
+
```ts
|
|
623
|
+
// example/src/contracts.ts
|
|
624
|
+
export const Approval = workflow("acme.loyalty.approval", {
|
|
625
|
+
input: t.object({ redemption: t.ref(Redemption) }),
|
|
626
|
+
output: t.object({ approved: t.bool(), voucher: t.string().nullable() }),
|
|
627
|
+
signals: { withdraw: t.object({ reason: t.string() }) },
|
|
628
|
+
})
|
|
629
|
+
```
|
|
630
|
+
|
|
631
|
+
```ts
|
|
632
|
+
// example/src/server.ts
|
|
633
|
+
export const approval = implement(c.Approval, async (wf, input) => {
|
|
634
|
+
const verdict = await wf.task("approve", {
|
|
635
|
+
subject: input.redemption,
|
|
636
|
+
assignee: wf.user,
|
|
637
|
+
decision: t.object({ approved: t.bool() }),
|
|
638
|
+
timeout: "3d",
|
|
639
|
+
})
|
|
640
|
+
const approved = verdict.outcome === "decided" && verdict.decision.approved
|
|
641
|
+
|
|
642
|
+
// An external effect: may run again after a crash, so it gets a provider idempotency key.
|
|
643
|
+
const voucher = approved
|
|
644
|
+
? await wf.step("voucher", async ({ idempotencyKey }) => {
|
|
645
|
+
const res = await fetch("https://api.partner.example/vouchers", {
|
|
646
|
+
method: "POST",
|
|
647
|
+
headers: { "content-type": "application/json", "idempotency-key": idempotencyKey },
|
|
648
|
+
body: JSON.stringify({ redemption: input.redemption.key }),
|
|
649
|
+
})
|
|
650
|
+
const body = (await res.json()) as { code: string }
|
|
651
|
+
return { code: body.code }
|
|
652
|
+
})
|
|
653
|
+
: null
|
|
654
|
+
|
|
655
|
+
// Data effects commit together with their journal entry. The result must be JSON.
|
|
656
|
+
await wf.transaction("settle", async (tx) => {
|
|
657
|
+
const row = await tx.get(c.Redemption, input.redemption)
|
|
658
|
+
if (row === null) return { settled: false }
|
|
659
|
+
const reward = await tx.get(c.Reward, row.reward)
|
|
660
|
+
await tx.update(c.Redemption, row.ref, { status: approved ? "approved" : "rejected" })
|
|
661
|
+
if (!approved) await tx.call(c.AdjustPoints, { client: row.client, delta: row.cost })
|
|
662
|
+
await tx.notify(c.RedemptionResult, {
|
|
663
|
+
subject: row.ref,
|
|
664
|
+
payload: { reward: reward?.name ?? "", approved },
|
|
665
|
+
to: [recipient.record(row.client)],
|
|
666
|
+
channels: ["sms", "email"],
|
|
667
|
+
})
|
|
668
|
+
return { settled: true }
|
|
669
|
+
})
|
|
670
|
+
return { approved, voucher: voucher?.code ?? null }
|
|
671
|
+
})
|
|
672
|
+
```
|
|
673
|
+
|
|
674
|
+
| primitive | what it does |
|
|
675
|
+
|---|---|
|
|
676
|
+
| `wf.transaction(name, cb)` | a Go transaction; the data effects and the journal entry commit together, so a replay does not repeat them. Also `(name, { output: schema }, cb)` and `(name, Operation \| AtomicCommand, input)` |
|
|
677
|
+
| `wf.step(name, effect)` | a re-runnable external effect (HTTP, e-mail). **At-least-once**: it may run again after a crash, with the same `idempotencyKey` (`<instance>:<name>:<n>`) |
|
|
678
|
+
| `wf.sleep(name, "30d")` | durable timer (`ms s m h d`) |
|
|
679
|
+
| `wf.waitFor(name, Signal)` | wait for a signal sent with `tx.signal` / `ctx.signal` / an endpoint; with `{ timeout }` it returns `{ outcome: "received" \| "timeout" }` |
|
|
680
|
+
| `wf.task(name, { subject, assignee, decision, timeout })` | a human task; completes with `{ outcome: "decided", decision, by }` or `"timeout"`. `assignee` is one user (a `core.User` ref, or `wf.user` for the principal) or `{ permission: P }`: anyone holding `P` decides (below) |
|
|
681
|
+
| `wf.call(name, Command, input)` | a new command invocation that uses the *currently active* binding; the receipt is journaled |
|
|
682
|
+
| `wf.start(name, Workflow, input)` | start a child instance |
|
|
683
|
+
| `wf.now(name)`, `wf.uuid(name)` | journaled clock and id, deterministic across replays |
|
|
684
|
+
|
|
685
|
+
**A task for a group: assign it to a permission.** A committee, a desk or "any authorized underwriter" is a permission,
|
|
686
|
+
not a person. `assignee: { permission: c.ApproveRisks }` (a `permission(...)` your package declares) makes the task
|
|
687
|
+
decidable by **anyone who holds it at the time of the decision**; the first decision wins, and `by` in the result is the
|
|
688
|
+
user who decided. An operator with the workflow administration right can decide any task, as for user tasks. The
|
|
689
|
+
permission must be declared by an active package when the task is created (else the call fails with
|
|
690
|
+
`workflow.invalidAssignee`); a replayed run does not check it again. In tests, give the host the users and their
|
|
691
|
+
permissions and decide as one of them:
|
|
692
|
+
|
|
693
|
+
```ts
|
|
694
|
+
const host = createTestHost({ users: { "7": ["acme.reinsurance.approveRisks"], "8": [] } })
|
|
695
|
+
const run = host.workflow(approval, { assessment })
|
|
696
|
+
await run.run() // suspended on the task
|
|
697
|
+
run.decide("approve", { approved: true }, { by: "7" }) // a holder: accepted
|
|
698
|
+
// { by: "8" } throws workflow.forbidden: user 8 does not hold the permission
|
|
699
|
+
await run.run() // completed
|
|
700
|
+
```
|
|
701
|
+
|
|
702
|
+
Rules for replay-safe code:
|
|
703
|
+
|
|
704
|
+
* **Every primitive takes a stable `name`.** Its identity is `(instance, name, n)`, where `n` counts repeated uses of the
|
|
705
|
+
same name in one run. In a loop put the item in the name (`send:${policy.number}`), so a changed list does not
|
|
706
|
+
re-attribute results.
|
|
707
|
+
* **Code between primitives must be deterministic.** Use `wf.now` / `wf.uuid` instead of `Date.now()` / `crypto`. Do not
|
|
708
|
+
branch on anything that can change between replays (the current time, random numbers, unjournaled reads); read it in a
|
|
709
|
+
`wf.transaction` or `wf.step` and branch on the recorded result.
|
|
710
|
+
* **`wf.transaction` and `wf.step` results must be JSON** (strings, numbers, booleans, `null`, arrays and plain objects
|
|
711
|
+
of those). A result with a `Date`, a `Map`, a class or `undefined` fields is a type error whose text says
|
|
712
|
+
"result is not JSON"; return the fields you need, not the row object. Replays return the recorded JSON.
|
|
713
|
+
* **Effects that leave the system go in `wf.step`**, with the idempotency key as the provider's idempotency header.
|
|
714
|
+
Effects on your own data go in `wf.transaction`.
|
|
715
|
+
* A workflow is pinned to the package version that started it; new versions affect new instances only. An administrator
|
|
716
|
+
can terminate, resume or restart (start-v2) an instance, deliver a signal, decide a task, or resolve a blocked step
|
|
717
|
+
(`ext_workflow_*`).
|
|
718
|
+
* `Promise.all` over primitives suspends sequentially in this release; prefer a loop or child workflows for fan-out.
|
|
719
|
+
|
|
720
|
+
Start a workflow with `tx.start(W, input, { key })` (§7.3) or `wf.start`. Send it a signal with
|
|
721
|
+
`tx.signal(instance, "name", payload)` using the handle `tx.start` returned, or `ctx.signal({ workflow: W.id, instance }, …)`.
|
|
722
|
+
|
|
723
|
+
## 11. Notifications
|
|
724
|
+
|
|
725
|
+
A **notice** is a typed message with a payload; **templates** turn it into SMS, e-mail, in-app or push content;
|
|
726
|
+
`tx.notify` sends it to recipients over channels. Recipient, subject and channel target are three different things:
|
|
727
|
+
|
|
728
|
+
* the **recipient** is who gets it: `recipient.user(ref(core.User, "42"))`, `recipient.record(clientRef)` (a record whose
|
|
729
|
+
contact data a contact resolver provides), or `recipient.address({ sms: "+998…", email: "…" })`;
|
|
730
|
+
* the **subject** is the record the message is about (`subject: row.ref`);
|
|
731
|
+
* the **target** is the resolved phone number, address or device.
|
|
732
|
+
|
|
733
|
+
```ts
|
|
734
|
+
// example/src/contracts.ts
|
|
735
|
+
export const RedemptionResult = notice("acme.loyalty.redemptionResult.v1", {
|
|
736
|
+
subject: Redemption,
|
|
737
|
+
payload: t.object({ reward: t.string(), approved: t.bool() }),
|
|
738
|
+
})
|
|
739
|
+
```
|
|
740
|
+
|
|
741
|
+
```ts
|
|
742
|
+
// example/src/server.ts
|
|
743
|
+
export const resultTemplates = templates(c.RedemptionResult, {
|
|
744
|
+
sms: ({ payload }) => (payload.approved ? `Your reward "${payload.reward}" is approved.` : `Your reward "${payload.reward}" was declined.`),
|
|
745
|
+
email: ({ payload, locale }) => ({
|
|
746
|
+
subject: payload.approved ? "Reward approved" : "Reward declined",
|
|
747
|
+
html: `<p lang="${locale}">${payload.reward}</p>`,
|
|
748
|
+
text: payload.reward,
|
|
749
|
+
}),
|
|
750
|
+
})
|
|
751
|
+
```
|
|
752
|
+
|
|
753
|
+
A record recipient needs a **contact resolver**: a contract for the entity, declared in the contracts graph, and its
|
|
754
|
+
implementation, bound in the server graph:
|
|
755
|
+
|
|
756
|
+
```ts
|
|
757
|
+
// example/src/contracts.ts
|
|
758
|
+
export const ClientContacts = contactResolver("acme.loyalty.clientContacts", crm.Client)
|
|
759
|
+
```
|
|
760
|
+
|
|
761
|
+
```ts
|
|
762
|
+
// example/src/server.ts
|
|
763
|
+
export const clientContacts = implement(c.ClientContacts, async (q, record) => {
|
|
764
|
+
const client = await q.get(crm.Client, record)
|
|
765
|
+
if (client === null) return {}
|
|
766
|
+
return {
|
|
767
|
+
...(client.phone === null ? {} : { sms: [client.phone] }),
|
|
768
|
+
...(client.email === null ? {} : { email: [client.email] }),
|
|
769
|
+
}
|
|
770
|
+
})
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
* `tx.notify(Notice, { subject, payload, to: [...], channels: [...] })` is enqueued **with the transaction**; rendering
|
|
774
|
+
(with the template version pinned when it was sent) and provider delivery happen after the commit and never roll it
|
|
775
|
+
back. A notice needs templates in some active package, or the call fails.
|
|
776
|
+
* A template renderer exists per channel (`sms`, `email`, `inApp`, `push`); a channel without a renderer is skipped for
|
|
777
|
+
that notice. Renderers receive `{ payload, subject, locale }` and may be async.
|
|
778
|
+
* `recipient.record(ref)` needs the **contact resolver** above for that entity (`contactResolver(id, Entity)` +
|
|
779
|
+
`implement`); it returns the targets per channel (`sms`, `email`, `push`); a `push` target is a device token and each
|
|
780
|
+
token is its own delivery with its own outcome. It has no `inApp` target: an in-app message addresses an ERP user.
|
|
781
|
+
* A **delivery policy** (`deliveryPolicy(id, Entity)` + `implement`) is where consent and opt-out live: the SDK has no
|
|
782
|
+
consent schema, the package that owns the data decides. See [Delivery policies](#delivery-policies).
|
|
783
|
+
* `recipient.user(...)` addresses an ERP user through the platform's notification preferences; it takes a ref to
|
|
784
|
+
`core.user`.
|
|
785
|
+
* **Mixed recipients.** `channels` apply to **every** recipient of the call: the platform tries each recipient × channel
|
|
786
|
+
pair and records a skipped delivery (with the reason) for a pair that has no target, instead of failing the call. A
|
|
787
|
+
record recipient is reachable over `sms`, `email` and `push` only if its resolver returns targets; `inApp` reaches ERP users
|
|
788
|
+
only (`recipient.user`), so `to: [recipient.record(client), recipient.user(agent)], channels: ["sms", "inApp"]` sends the
|
|
789
|
+
SMS to the client, the in-app message to the agent, and records `record × inApp` and (with no phone on the user) `user × sms`
|
|
790
|
+
as skipped. That is rarely what you mean: **send one `tx.notify` per audience**, each with the channels that fit it
|
|
791
|
+
(`wf.transaction` can hold both calls), and read the skipped rows in `host.deliveries` (§14.2) when a message does not
|
|
792
|
+
arrive.
|
|
793
|
+
* Use a stable `name`/key on repeated sends in workflows (`wf.transaction("send:${id}", …)`) so a replay does not notify
|
|
794
|
+
twice.
|
|
795
|
+
|
|
796
|
+
### Delivery policies
|
|
797
|
+
|
|
798
|
+
```ts
|
|
799
|
+
// example/src/contracts.ts
|
|
800
|
+
export const ClientConsent = deliveryPolicy("acme.loyalty.clientConsent", crm.Client)
|
|
801
|
+
```
|
|
802
|
+
|
|
803
|
+
```ts
|
|
804
|
+
// example/src/server.ts
|
|
805
|
+
export const clientConsent = implement(c.ClientConsent, async (q, request) => {
|
|
806
|
+
const loyalty = await q.get(c.ClientLoyalty, request.recipient.ref)
|
|
807
|
+
if (request.channel === "sms" && loyalty?.smsOptOut === true) return { allow: false, reason: "sms_opt_out" }
|
|
808
|
+
return { allow: true }
|
|
809
|
+
})
|
|
810
|
+
```
|
|
811
|
+
|
|
812
|
+
Once per notice, channel and **target** about to be created for a record recipient of the policy's entity, the platform
|
|
813
|
+
calls every active policy of that entity. The call is made after the sender's transaction committed and never inside
|
|
814
|
+
any write transaction; it runs as the **trigger owner** of the policy (assign one like for a contact resolver:
|
|
815
|
+
`PUT /_ext/manage/triggers/{policyId}/owner`, `ext_owner_assign`) with that user's current rights. A policy of a
|
|
816
|
+
package that is not active (deactivated, replaced, never activated) is simply not consulted.
|
|
817
|
+
|
|
818
|
+
The request and the answer are a **public, versioned contract**; fields are only ever added. The test host evaluates bound
|
|
819
|
+
policies with the same request (§14.2).
|
|
820
|
+
|
|
821
|
+
```jsonc
|
|
822
|
+
// request (the second argument of the handler)
|
|
823
|
+
{
|
|
824
|
+
"notice": { "key": "acme.loyalty.redemption_result.v1", "version": 1, "snapshot": "acme.loyalty@1.4.0" },
|
|
825
|
+
"subject": { "entity": "acme.loyalty.redemption", "key": "r-1" }, // null when the notice has none
|
|
826
|
+
"recipient": { "kind": "record", "ref": { "entity": "crm.client", "key": "c-1" }, "address": null },
|
|
827
|
+
"channel": "sms", // "sms" | "email" | "push"
|
|
828
|
+
"target": { "address": "+998901234567", "deviceId": null } // deviceId only for a registered push device
|
|
829
|
+
}
|
|
830
|
+
// answer
|
|
831
|
+
{ "allow": true }
|
|
832
|
+
{ "allow": false, "reason": "sms_opt_out" }
|
|
833
|
+
```
|
|
834
|
+
|
|
835
|
+
* `notice.key` is the catalog key of the notice: its ID with each segment in snake_case and a trailing `.vN`.
|
|
836
|
+
`snapshot` is the package version that rendered it.
|
|
837
|
+
* `recipient.kind` is `"record"` today (`ref` set, `address` null). Handle kinds you do not know by allowing; new kinds
|
|
838
|
+
will only be added with their own fields. Address recipients (a bare phone or email) have no entity to bind a policy
|
|
839
|
+
to and are governed by the application's Go-configured policy only.
|
|
840
|
+
* `reason` is optional: a short machine code of `[a-z0-9_.-]`, at most 64 characters, without personal data. A denial
|
|
841
|
+
is stored per target as a **skipped** delivery with error code `policy_denied:<reason>` (or `policy_denied`); the
|
|
842
|
+
provider is not called and sibling targets (other channels, the other device) are unaffected.
|
|
843
|
+
* Composition is deterministic: the Go-configured `ModuleOptions.NotificationDeliveryPolicy` is consulted first, then
|
|
844
|
+
the policies of active packages ordered by policy ID and package. **Any denial wins**; the first denial's reason is the
|
|
845
|
+
one stored and later policies are not asked.
|
|
846
|
+
* A policy that cannot answer is never an implicit allow. No owner assigned, a handler that throws, or an answer that is
|
|
847
|
+
not `{ allow: boolean, reason?: string }` all leave the delivery waiting and retried (visible as `unresolved`, and
|
|
848
|
+
`failed` with `resolution_attempt_limit` when attempts run out, after which an operator can retry it). Assign the
|
|
849
|
+
owner or fix the policy and the waiting deliveries proceed.
|
|
850
|
+
|
|
851
|
+
## 12. Triggers
|
|
852
|
+
|
|
853
|
+
Besides calls from users and other code, a package can run on a schedule and answer HTTP requests.
|
|
854
|
+
|
|
855
|
+
```ts
|
|
856
|
+
// example/src/server.ts
|
|
857
|
+
export const closeStale = schedule("acme.loyalty.closeStale", { cron: "0 3 * * *", timezone: "Asia/Tashkent" }, async (ctx) => {
|
|
858
|
+
const cutoff: ISODateTime = isoDateTime(new Date(Date.parse(ctx.slot) - 7 * 86_400_000).toISOString())
|
|
859
|
+
await ctx.transaction(async (tx) => {
|
|
860
|
+
const stale = await tx.find(c.Redemption, { where: { status: "pending", createdAt: { lt: cutoff } } })
|
|
861
|
+
for (const row of stale) {
|
|
862
|
+
await tx.update(c.Redemption, row.ref, { status: "rejected" })
|
|
863
|
+
await tx.call(c.AdjustPoints, { client: row.client, delta: row.cost })
|
|
864
|
+
}
|
|
865
|
+
})
|
|
866
|
+
})
|
|
867
|
+
```
|
|
868
|
+
|
|
869
|
+
```ts
|
|
870
|
+
// example/src/server.ts
|
|
871
|
+
export const publicCatalog = endpoint("acme.loyalty.publicCatalog", { method: "GET", path: "/catalog", public: true }, async (ctx) => {
|
|
872
|
+
const rewards = await ctx.query.find(c.Reward, { where: { active: true }, orderBy: [{ field: "name" }] })
|
|
873
|
+
return { status: 200, body: rewards.map((r) => ({ name: r.name, cost: r.cost })) }
|
|
874
|
+
})
|
|
875
|
+
```
|
|
876
|
+
|
|
877
|
+
* `schedule(id, cron | { cron, timezone }, handler)`: a 5-field cron expression and an optional IANA time zone (publish
|
|
878
|
+
refuses a zone the platform does not know). `ctx.slot` is the scheduled instant. A slot older than 15 minutes (after downtime) is skipped, not replayed.
|
|
879
|
+
* `endpoint(id, { method, path, public }, handler)` (`method` is `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or
|
|
880
|
+
`OPTIONS`; `path` starts with `/` and has no spaces, control characters, backticks or backslashes — publish refuses
|
|
881
|
+
anything else) is served at `/_ext/endpoints/<namespace>/<path>`; the handler gets the
|
|
882
|
+
command context plus `ctx.request` (`method path headers query body rawBody text()`) and returns
|
|
883
|
+
`{ status, headers?, body? }`. `rawBody` is for signature checks. Response `headers` are an allowlist (content type,
|
|
884
|
+
caching, `ETag`, `Content-Disposition`, a same-origin `Location` on a redirect, your own `X-` headers); `Set-Cookie`, CORS
|
|
885
|
+
and `Content-Security-Policy` are dropped, and HTML/SVG/XML is served sandboxed (`Content-Security-Policy: sandbox`).
|
|
886
|
+
* **Who runs it.** A schedule, a subscription on a user-less event and a *public* endpoint run as the trigger's
|
|
887
|
+
**owner-user**, assigned per tenant by an administrator (`ext_owner_assign`) and executed with that user's current
|
|
888
|
+
rights. An authenticated (non-public) endpoint runs as the calling user; a *public* endpoint ignores the caller's session
|
|
889
|
+
and always runs as the owner, even when it is called from a signed-in browser. A trigger without an owner is `blocked`.
|
|
890
|
+
|
|
891
|
+
## 13. User interface
|
|
892
|
+
|
|
893
|
+
The client graph exports Solid pages, navigation, slot contributions, cell renderers and (rarely) a shell. Pages are mounted by the canonical
|
|
894
|
+
client host inside the application's authenticated layout, the same boundary as the built-in pages.
|
|
895
|
+
|
|
896
|
+
```tsx
|
|
897
|
+
// example/src/client.tsx
|
|
898
|
+
export const rewards = page("acme.loyalty.rewards", {
|
|
899
|
+
path: "/loyalty/rewards",
|
|
900
|
+
nav: { label: { en: "Rewards", ru: "Награды" }, group: "acme.loyalty.menu", icon: "gift" },
|
|
901
|
+
permission: c.Manage,
|
|
902
|
+
component: lazy(() => import("./RewardsScreen")),
|
|
903
|
+
})
|
|
904
|
+
```
|
|
905
|
+
|
|
906
|
+
```tsx
|
|
907
|
+
// example/src/client.tsx
|
|
908
|
+
export const nav = navigation({
|
|
909
|
+
groups: [{ id: "acme.loyalty.menu", label: { en: "Loyalty", ru: "Лояльность" } }],
|
|
910
|
+
})
|
|
911
|
+
```
|
|
912
|
+
|
|
913
|
+
* **`nav.group` is the ID of a group declared by `navigation({ groups })`** (here `acme.loyalty.menu`), in this package or,
|
|
914
|
+
checked at activation, in another one. `nav.parent`, palette targets and `patches` refs must resolve the same way. An
|
|
915
|
+
unknown group is a manifest error. The page's own ID (`acme.loyalty.rewards`) is separate.
|
|
916
|
+
* `page(id, { path, nav?, permission?, component })` declares a page by ID and path; `:name` segments arrive as string
|
|
917
|
+
`props.params`. `page(Route, { component })` binds a page to a typed route and gets the ID `<route id>.page`; link to a
|
|
918
|
+
route with `href(Route, { id })`, which validates and percent-encodes.
|
|
919
|
+
* `navigation({ groups, patches, workspaces, palette })` — `patches` hide, rename or move existing nodes by resource ID;
|
|
920
|
+
`workspaces` and `palette` add workspaces and command-palette entries.
|
|
921
|
+
* **Data from the browser**: `useQuery(Q, input)` and `useCommand(C)` from `@iota-uz/sdk/runtime/client` call
|
|
922
|
+
`POST /_ext/rpc` as the signed-in user. Queries and commands are callable from the browser; **operations never are**.
|
|
923
|
+
The contract's `permission` is checked there, and read rules filter the rows.
|
|
924
|
+
* **Page for a platform route.** `page(foreignRoute, …)` with a route from the kit is a *screen replacement candidate*,
|
|
925
|
+
active only through a `screen` binding (like command replacement, §7.4); see §13.3.
|
|
926
|
+
|
|
927
|
+
### 13.1 Slots
|
|
928
|
+
|
|
929
|
+
A *slot* is a place in a page where other packages mount components. The **page that owns it declares it**: a stable ID,
|
|
930
|
+
the typed props it passes to every contribution and, optionally, a permission. Contributions are **additive**: they need no
|
|
931
|
+
binding, they are active while their package version is, and every contribution of every active package is mounted.
|
|
932
|
+
|
|
933
|
+
**Slots of the platform** are declared by Go and arrive in the kit like any other contract. The CRM declares
|
|
934
|
+
`crm.slots.clientSidebar` (props `{ clientId }`) on its client view page and in the client drawer; contribute to it with the
|
|
935
|
+
typed reference:
|
|
936
|
+
|
|
937
|
+
```tsx
|
|
938
|
+
// example/src/client.tsx
|
|
939
|
+
export const loyaltyCard = slot(crm.ClientSidebar, (props) => <p class="loyalty-card">Loyalty for client {props.clientId}</p>, {
|
|
940
|
+
order: 10,
|
|
941
|
+
permission: c.Manage,
|
|
942
|
+
})
|
|
943
|
+
```
|
|
944
|
+
|
|
945
|
+
* `slot(target, Component, { order?, permission?, id? })`. `target` is the typed reference from the kit (`crm.ClientSidebar`) or
|
|
946
|
+
from your own `defineSlot`; a plain slot ID string is accepted but its props are untyped. The component receives the props of
|
|
947
|
+
the declaring page.
|
|
948
|
+
* **Order.** Contributions to one slot are mounted by ascending `order` (default 0), ties broken by package namespace, then
|
|
949
|
+
contribution ID. The order is the same on every render.
|
|
950
|
+
* **Permission.** The server decides who gets a contribution: the slot's own permission (set by its declaration) and the
|
|
951
|
+
contribution's `permission` must both be held by the viewer. A contribution the viewer may not have is **absent from the page
|
|
952
|
+
data / HTML**, not hidden by the browser. The permission is the same kind of name as a page's (`permission(...)`).
|
|
953
|
+
* A broken contribution (its module fails to load, or its component throws) is reported to the console and leaves the page and
|
|
954
|
+
the other contributions alone. A module that arrives after the user already left the page is dropped.
|
|
955
|
+
|
|
956
|
+
**Your own slots.** Declare a slot in the contracts graph (it is a contract: other packages import it through the kit) and
|
|
957
|
+
render it in a page of yours with `<Slot>`:
|
|
958
|
+
|
|
959
|
+
```ts
|
|
960
|
+
// example/src/contracts.ts
|
|
961
|
+
export const RewardActions = defineSlot("acme.loyalty.rewardActions", { props: t.object({ reward: t.string() }) })
|
|
962
|
+
```
|
|
963
|
+
|
|
964
|
+
```tsx
|
|
965
|
+
// example/src/RewardsScreen.tsx
|
|
966
|
+
{r.name}: {r.cost} <Slot slot={c.RewardActions} props={{ reward: r.name }} />
|
|
967
|
+
```
|
|
968
|
+
|
|
969
|
+
```tsx
|
|
970
|
+
// example/src/client.tsx
|
|
971
|
+
export const exportAction = slot(c.RewardActions, (props) => <button type="button">Export {props.reward}</button>)
|
|
972
|
+
```
|
|
973
|
+
|
|
974
|
+
`<Slot slot={…} props={…}/>` comes from `@iota-uz/sdk/runtime/client` and works in a package page and in a shell renderer. (The
|
|
975
|
+
prop is `slot`, not `ref`: Solid's compiler reserves `ref` on every component.) `props` must match the declared props.
|
|
976
|
+
|
|
977
|
+
**Slots in Go-rendered (Templ/HTMX) pages** use `shellext.Slot(ctx, "module.slots.name", props)` in the template. It renders a
|
|
978
|
+
mount element with the props and the contributions the viewer gets; nothing when none applies. The browser runtime mounts each
|
|
979
|
+
contribution into its own Solid root and releases it when the element is swapped out by HTMX or the page is left. A Go page
|
|
980
|
+
declares its slot as a native resource (`manifest.Resource{ID, Kind: slot, Props, Permission}`), see
|
|
981
|
+
`modules/crm/extension` for the CRM's.
|
|
982
|
+
|
|
983
|
+
### 13.2 Cell renderers
|
|
984
|
+
|
|
985
|
+
```tsx
|
|
986
|
+
// example/src/client.tsx
|
|
987
|
+
export const tierCell = cell(c.TierColumn, (props) => <span class={`tier tier-${props.value}`}>{props.value}</span>)
|
|
988
|
+
```
|
|
989
|
+
|
|
990
|
+
`cell(column, component)` customises how a `column(...)` renders in the native list. Without it the value is shown as text.
|
|
991
|
+
|
|
992
|
+
* The list stays **server-rendered**: the cell is the standard cell for the column's type, wrapped in a mount element. Your
|
|
993
|
+
component replaces it in the browser once the module has loaded; if it never loads or throws, the standard cell stays. The
|
|
994
|
+
page reads the same without JavaScript.
|
|
995
|
+
* `props.value` is the column's value as wire JSON (`int` is a number; `int64` and `decimal` are strings; `null` when absent).
|
|
996
|
+
`props.row` is the row's contributed values by column ID (only columns the viewer may read) and `ref`, the native record
|
|
997
|
+
(`{ entity, key }`). Access to the column follows the overlay field's access rules: a viewer who may not read the column gets
|
|
998
|
+
no cell and no value.
|
|
999
|
+
* **Exports, filters and sorting never use the renderer**: they read the raw value.
|
|
1000
|
+
* One renderer serves a column. If several packages supply one, the package that declares the column wins, otherwise the first
|
|
1001
|
+
by package name; the others are ignored and reported.
|
|
1002
|
+
|
|
1003
|
+
### 13.3 Replacing a native screen
|
|
1004
|
+
|
|
1005
|
+
`page(crm.ClientView, { component })` with a route from the kit makes your page a *screen replacement candidate* for that
|
|
1006
|
+
route; the CRM client view (`crm.routes.clientView`, `/crm/clients/:id`) is the reference:
|
|
1007
|
+
|
|
1008
|
+
```tsx
|
|
1009
|
+
// example/src/client.tsx
|
|
1010
|
+
export const clientView = page(crm.ClientView, { component: lazy(() => import("./ClientScreen")) })
|
|
1011
|
+
```
|
|
1012
|
+
|
|
1013
|
+
```tsx
|
|
1014
|
+
// example/src/ClientScreen.tsx
|
|
1015
|
+
export default function ClientScreen(props: PageProps<{ id: number }>) {
|
|
1016
|
+
```
|
|
1017
|
+
|
|
1018
|
+
* The page is **not served** by itself. An administrator binds it: `POST /_ext/manage/bindings` with
|
|
1019
|
+
`{"slotKind":"screen","targetId":"crm.routes.clientView","package":"…","version":"…","export":"clientView"}` (or `ext_bind`).
|
|
1020
|
+
One package page holds a route at a time; unbinding restores the native page without a restart.
|
|
1021
|
+
* **Typed params.** The route declares its parameters (`id` is an `int`), so `props.params.id` is a number, decoded from the path
|
|
1022
|
+
before the page renders; a path the type refuses (`/crm/clients/abc`) is a 404 and never reaches your page.
|
|
1023
|
+
* **Access never widens.** The replacement is served only to viewers who hold what the native screen requires (the route's
|
|
1024
|
+
permission, `Client.Read` here) and what your page's own `permission` requires.
|
|
1025
|
+
* Only the *screen* is replaced: HTMX requests for fragments of the native page (the client drawer) still reach the native
|
|
1026
|
+
handlers.
|
|
1027
|
+
|
|
1028
|
+
### 13.4 The shell
|
|
1029
|
+
|
|
1030
|
+
`shellRenderer((p) => <MyShell {...p} />)` replaces the whole authenticated shell (navigation, header) around every page,
|
|
1031
|
+
once an administrator binds it to the `shell` slot. The component receives the host-owned `outlet` element that already
|
|
1032
|
+
contains the current page; render it exactly once:
|
|
1033
|
+
|
|
1034
|
+
```tsx
|
|
1035
|
+
export const shell = shellRenderer((p) => (
|
|
1036
|
+
<div class="shell">
|
|
1037
|
+
<nav><For each={p.nav.groups}>{(group) => <For each={group.items}>{(item) => <a href={item.href}>{item.label}</a>}</For>}</For></nav>
|
|
1038
|
+
<header>{p.user.name}</header>
|
|
1039
|
+
<main>{p.outlet}</main>
|
|
1040
|
+
</div>
|
|
1041
|
+
))
|
|
1042
|
+
```
|
|
1043
|
+
|
|
1044
|
+
Client chunks must not import the server entry, anything only the server reaches, `@iota-uz/sdk/runtime/server` or a Node
|
|
1045
|
+
built-in (`graph.serverInClient`); Solid and the runtime client are not bundled: the host provides them.
|
|
1046
|
+
|
|
1047
|
+
### 13.5 Documentation for your users
|
|
1048
|
+
|
|
1049
|
+
A package ships its own end-user documentation. It is markdown in the package tree, so it is versioned with the code,
|
|
1050
|
+
reviewed with it (the source and artifact hashes cover every word) and replaced by the next version when that version is
|
|
1051
|
+
activated. It appears in the Help Center under **Applications** (`/help/doc/apps/<namespace>/<document>`), for the
|
|
1052
|
+
people who use the package. It is not the developer reference: that is generated from your contracts and lives under
|
|
1053
|
+
**Extensions** (§19).
|
|
1054
|
+
|
|
1055
|
+
```text
|
|
1056
|
+
docs/
|
|
1057
|
+
├─ en/ the default locale: every document exists here
|
|
1058
|
+
│ ├─ getting-started.md → /help/doc/apps/acme.loyalty/getting-started
|
|
1059
|
+
│ └─ admin/
|
|
1060
|
+
│ └─ setup.md → /help/doc/apps/acme.loyalty/admin/setup
|
|
1061
|
+
└─ ru/
|
|
1062
|
+
└─ getting-started.md the Russian translation of getting-started
|
|
1063
|
+
```
|
|
1064
|
+
|
|
1065
|
+
**Rules.** Everything under `docs/` follows one rule, `docs/<locale>/<path>.md`:
|
|
1066
|
+
|
|
1067
|
+
* The first directory is the **locale**: a lowercase language tag such as `en`, `ru`, `uz` or `pt-br`. There are no
|
|
1068
|
+
un-localized documents; a package with one language puts everything in `docs/en/`.
|
|
1069
|
+
* `<path>` is the document's address: up to five segments of lowercase letters, digits, `-` and `_`, without the
|
|
1070
|
+
extension (`admin/setup`). The same path in another locale is a translation of the same document.
|
|
1071
|
+
* **`en` is the default locale and is complete**: a document that exists in another locale must exist in `en` too
|
|
1072
|
+
(`docs.missingDefault`). A reader gets the translation for their locale (`ru-RU` → `ru`), else the English one.
|
|
1073
|
+
* Only `.md` files. Images and other files are **not supported** (`docs.unsupportedFile`); a relative image is refused
|
|
1074
|
+
(`docs.image`). Describe in words, or link an absolute `https://` URL.
|
|
1075
|
+
* A document is at most 256 KiB, UTF-8, a version's documents at most 4 MiB in 200 files.
|
|
1076
|
+
|
|
1077
|
+
**Front matter** is optional, a block of flat `key: value` lines between `---` lines at the very top (a deliberate
|
|
1078
|
+
subset of YAML: no lists, no nesting; quote a value with `"…"` when it contains `#` or starts with a quote):
|
|
1079
|
+
|
|
1080
|
+
```md
|
|
1081
|
+
---
|
|
1082
|
+
title: Setting up limits # sidebar label and heading; default: the first # heading, else the file name
|
|
1083
|
+
order: 2 # position among the documents; lower first, then by title (default 0)
|
|
1084
|
+
audience: Managers # a short hint of who the document is for
|
|
1085
|
+
permission: acme.loyalty.manage # only holders of this permission see the document
|
|
1086
|
+
---
|
|
1087
|
+
|
|
1088
|
+
# Setting up limits
|
|
1089
|
+
```
|
|
1090
|
+
|
|
1091
|
+
* `title` and `audience` are **plain text**: one line, no `<` or `>`. They are shown literally; markdown in them is not
|
|
1092
|
+
interpreted.
|
|
1093
|
+
* `permission` is a permission the package declares (`permission("acme.loyalty.manage", …)`, which must be exported) or
|
|
1094
|
+
a native one (`Client.Update`). A permission in the package's own namespace that the package does not declare is an
|
|
1095
|
+
error (`docs.unknownPermission`); a permission of another package or a native contract is checked against the
|
|
1096
|
+
catalog when you publish. All translations of a document carry the same permission (`docs.permissionMismatch`).
|
|
1097
|
+
A reader without it gets *not found*, and the document is not in their sidebar. Holders of `Extensions.Read` see
|
|
1098
|
+
every document, as they see every resource of the reference.
|
|
1099
|
+
|
|
1100
|
+
**Who sees a package's documentation.** The same people who can use the package: a reader sees its documentation when
|
|
1101
|
+
they can use at least one of its resources — run a command or query, read an entity's rows, open a page or route, start a
|
|
1102
|
+
workflow, or see a column, slot, cell or shell it contributes — or when they hold `Extensions.Read`. Declarations
|
|
1103
|
+
(permissions, events, notices, issues, domain errors, operations, navigation, resolvers, policies) do not count: they carry
|
|
1104
|
+
no permission of their own. A package whose usable resources are all gated is invisible to readers without those
|
|
1105
|
+
permissions, and so is its documentation; a package with one open page or query is visible to every signed-in reader. Use
|
|
1106
|
+
a document's `permission` to keep one document private inside a visible package.
|
|
1107
|
+
|
|
1108
|
+
**Links.** Markdown links are written against the source tree and checked at build time:
|
|
1109
|
+
|
|
1110
|
+
```md
|
|
1111
|
+
Read the [limits](limits.md), or [how to set them up](admin/setup.md#cards). <!-- another document, by file name -->
|
|
1112
|
+
Back to the [start](../getting-started.md). <!-- relative to this file -->
|
|
1113
|
+
Open the [cards page](route:acme.loyalty.cards). <!-- a page or route of this package -->
|
|
1114
|
+
Pay at [the bank](https://bank.example/pay). <!-- http, https, mailto, tel -->
|
|
1115
|
+
```
|
|
1116
|
+
|
|
1117
|
+
* A relative link names another document by its file name with `.md`; it may end with `#section` (the fragment itself
|
|
1118
|
+
is not checked, neither here nor in `helpHref`). It must stay inside
|
|
1119
|
+
the locale's tree (`docs.linkEscapes`) and name a document that exists (`docs.brokenLink`). The Help Center serves
|
|
1120
|
+
documents without the extension; the platform drops `.md` for you.
|
|
1121
|
+
* `route:<resource id>` links a `page` or `route` of the package with a fixed address (no `:param`) to its path
|
|
1122
|
+
(`docs.unknownRoute`).
|
|
1123
|
+
* `javascript:`, `data:` and other schemes, protocol-relative `//host` links and query strings on document links are
|
|
1124
|
+
refused (`docs.linkScheme`, `docs.linkTarget`). Only markdown links are rewritten; a raw HTML `<a href="x.md">` is
|
|
1125
|
+
passed to the Help Center's sanitizer as written.
|
|
1126
|
+
* Links inside code spans and fenced blocks are text, not links.
|
|
1127
|
+
|
|
1128
|
+
Markdown is rendered by the Help Center's sanitizer: raw HTML is cleaned like any Help Center article (scripts, event
|
|
1129
|
+
handlers and `javascript:` URLs never survive).
|
|
1130
|
+
|
|
1131
|
+
**Linking from your pages.** `helpHref` gives the address of one of your documents:
|
|
1132
|
+
|
|
1133
|
+
```tsx
|
|
1134
|
+
import { helpHref } from "@iota-uz/sdk/runtime/client"
|
|
1135
|
+
|
|
1136
|
+
<a href={helpHref("getting-started")}>How does this work?</a>
|
|
1137
|
+
<a href={helpHref("admin/setup#cards")}>Limits</a>
|
|
1138
|
+
```
|
|
1139
|
+
|
|
1140
|
+
`helpHref` always means **your** package: the build binds it to the namespace of the bundle that calls it, so a slot or a
|
|
1141
|
+
cell of yours links to your documents on any page, native or another package's. Pass `{ namespace: "other.pkg" }` to link
|
|
1142
|
+
another package's documents. A call with a string literal is checked by `iota-ext check` against
|
|
1143
|
+
your `docs/en` documents (`docs.unknownHelpHref`, with the file, line and column of the call), so a renamed document
|
|
1144
|
+
breaks the build rather than the link. A computed argument cannot be checked. `helpHref` throws on a malformed path.
|
|
1145
|
+
|
|
1146
|
+
`iota-ext check` and `build` report every rule above with `docs/<locale>/<path>.md:line:col code message`; a document that
|
|
1147
|
+
passes ships in the artifact (front matter removed) and its title, order, audience and permission in the manifest
|
|
1148
|
+
(`docs`). Publishing re-checks the structure and the permissions against the catalog. The assistant tool `ext_docs` reads
|
|
1149
|
+
the same documents with the same visibility as the Help Center.
|
|
1150
|
+
|
|
1151
|
+
### 13.6 Styling: the UI kit, Tailwind and CSS modules
|
|
1152
|
+
|
|
1153
|
+
Packages share one page with the application and with each other, so a package styles itself with three tools, none of
|
|
1154
|
+
which leaks: the SDK's Solid UI kit, Tailwind utility classes and scoped CSS modules. Do not write inline `style=` attributes
|
|
1155
|
+
for what these provide, and do not import global stylesheets (below). A value that comes from data — the width of a bar,
|
|
1156
|
+
a colour per status — is the one thing classes cannot hold: pass it as a CSS custom property and let a module use it.
|
|
1157
|
+
|
|
1158
|
+
```tsx
|
|
1159
|
+
// a screen of your package
|
|
1160
|
+
import { Button, Card, Tabs, TabsContent, TabsList, TabsTrigger } from "@iota-uz/sdk/solid-ui"
|
|
1161
|
+
import styles from "./RewardsScreen.module.css"
|
|
1162
|
+
|
|
1163
|
+
export default function RewardsScreen() {
|
|
1164
|
+
return (
|
|
1165
|
+
<section class={`${styles.board} p-6`}>
|
|
1166
|
+
<Card><Button variant="primary" onClick={save}>Save</Button></Card>
|
|
1167
|
+
<Tabs defaultValue="terms">…</Tabs>
|
|
1168
|
+
</section>
|
|
1169
|
+
)
|
|
1170
|
+
}
|
|
1171
|
+
```
|
|
1172
|
+
|
|
1173
|
+
```tsx
|
|
1174
|
+
// data-driven values: a custom property, consumed by the module (`.fill { width: calc(var(--share) * 1%) }`)
|
|
1175
|
+
<div class={styles.bar}><div class={styles.fill} style={{ "--share": String(share()) }} /></div>
|
|
1176
|
+
```
|
|
1177
|
+
|
|
1178
|
+
* **The UI kit** is `import { … } from "@iota-uz/sdk/solid-ui"` (forms, overlays, navigation, tables, charts…). It is the **host's own
|
|
1179
|
+
instance**: your bundle does not contain it, it shares the host's Solid and the host's theme (light/dark, tokens), so a `Button` looks like
|
|
1180
|
+
every other button of the application. There is exactly one import path; subpaths of the kit are not importable from packages.
|
|
1181
|
+
The host loads the kit **lazily**, only when a package version that imports it is mounted, together with the kit's own
|
|
1182
|
+
utility stylesheet; an installation whose packages do not use it never downloads it. **Version coupling**: the kit is the
|
|
1183
|
+
version of the host that serves your package, the same release as the runtime (`@iota-uz/sdk` and the Go module are one
|
|
1184
|
+
release). Components added in a newer SDK are not there on an older host; `iota-ext check` typechecks against the kit of the
|
|
1185
|
+
SDK you installed, so pin `@iota-uz/sdk` to the version of the instance you deploy to. Only the client graph can import it
|
|
1186
|
+
(`graph.clientInServer` / `graph.impureContract` otherwise); package tests (`iota-ext test`) can import client code that uses it, as an inert stand-in.
|
|
1187
|
+
* **Tailwind utilities** (`class="flex gap-4 p-6 bg-primary-600 md:flex-col"`). At build the worker compiles the classes the **client
|
|
1188
|
+
sources** use (string-like tokens in the files of the client graph, so write class names as whole strings; a name assembled from
|
|
1189
|
+
parts such as `` `bg-${tone}-500` `` is not found, and an ordinary string that happens to be a class name, like `"block"`,
|
|
1190
|
+
emits that utility: harmless, a few bytes) with the SDK's design tokens: the same `tailwind.config.js` mapping the application's
|
|
1191
|
+
own pipeline uses, so `bg-primary-600`, `text-gray-700`, `border-subtle` and `bg-surface-300` mean what they mean in the application, in
|
|
1192
|
+
both themes. The result is `client/tailwind.css` in the version's artifact: utilities only — no `:root` variables (theme values are
|
|
1193
|
+
inlined), no base styles, no layer order; only the `@property` registrations some utilities need, identical to the
|
|
1194
|
+
application's — and only the classes you use. There is no Tailwind config of your own and no `@apply`.
|
|
1195
|
+
* **Scoped CSS modules** for what utilities do not express (`*.module.css`). `import styles from "./Panel.module.css"`;
|
|
1196
|
+
`styles.panel` is a class name unique to your package, file and content (`Panel_1a2b3c4d_panel`), so it cannot collide with the application or another
|
|
1197
|
+
package, or with the same package's other version. Declare the type once per package, as `iota-ext init` does:
|
|
1198
|
+
|
|
1199
|
+
```ts
|
|
1200
|
+
// src/css-modules.d.ts
|
|
1201
|
+
declare module "*.module.css" {
|
|
1202
|
+
const classes: Readonly<Record<string, string>>
|
|
1203
|
+
export default classes
|
|
1204
|
+
}
|
|
1205
|
+
```
|
|
1206
|
+
|
|
1207
|
+
A module's rules are unlayered, so they win over utilities and the kit when both set a property on one element. Plain CSS (`@import` of
|
|
1208
|
+
another module file, `composes: x from "./other.module.css"`, nesting, media queries) works; local `url()` assets do not: use `data:` URIs.
|
|
1209
|
+
* **Global stylesheets are refused.** `import "./global.css"` (or any plain `.css`, from code or from `@import` in a module) fails with
|
|
1210
|
+
`graph.globalCss` at the import: every package shares one page, so a global rule would restyle the host and other packages. Use utilities
|
|
1211
|
+
or a module. A stylesheet imported by the server or contracts graph is `graph.cssOutsideClient`. Malformed CSS is `css.syntax` at its line.
|
|
1212
|
+
|
|
1213
|
+
Both stylesheets belong to the version: they are built with it, covered by its artifact hash and reviewed with it, served from the same
|
|
1214
|
+
immutable `/_ext/assets/<artifactHash>/client/…` URLs, and `client/manifest.json` lists them under `css`. The application links them
|
|
1215
|
+
before the first render of any page, slot, cell or shell of the version — in the page HTML for a package page, and in the document head for
|
|
1216
|
+
slots, cells and the shell (once per document, however many islands or HTMX swaps) — so nothing paints unstyled and a swap never loses
|
|
1217
|
+
a stylesheet a neighbour still needs. `iota-ext init` scaffolds a page that uses a kit component, a utility and a CSS module.
|
|
1218
|
+
|
|
1219
|
+
**What the kit offers.** The authoritative list with every prop is the kit's typings in your installed SDK,
|
|
1220
|
+
`node_modules/@iota-uz/sdk/dist/solid-ui/index.d.ts` (your editor shows them on hover). The pieces a business screen uses most:
|
|
1221
|
+
|
|
1222
|
+
| Need | Components | Key props |
|
|
1223
|
+
|---|---|---|
|
|
1224
|
+
| Actions | `Button` (and `PrimaryButton`, `SecondaryButton`, `DangerButton`, `GhostButton`) | `variant`: `primary` `secondary` `primary-outline` `danger` `ghost` `sidebar`; `size`: `normal` `md` `sm` `xs`; `loading`, `disabled`, `href`, `icon` |
|
|
1225
|
+
| Text fields | `Input` (`TextInput`, `NumberInput`, `DateInput`, …), `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`, `Toggle`, `Slider`, `DatePicker`, `Combobox`, `SearchSelect`, `PhoneInput`, `Upload` | `label`, `description`, `error`, `placeholder`; `Select`: `options: { value, label }[]`, `defaultValue` |
|
|
1226
|
+
| Layout | `Card`, `CardHeader`, `DescriptionList` (`DescriptionListItem`, `DescriptionListLabel`, `DescriptionListValue`), `Breadcrumbs` | |
|
|
1227
|
+
| Tabs | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`; `NavTabs`, `TabLink` for links | `Tabs`: `value` + `onValueChange` (controlled) or `defaultValue`; trigger and content share a `value` |
|
|
1228
|
+
| Tables | `Table` composed of `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`; `EmptyState`, `Pagination`, `Skeleton`, `Loader` | `TableHead`: sorting props; `EmptyState`: `title`, `description` |
|
|
1229
|
+
| Status | `Badge`, `Alert` (`ErrorAlert`, `SuccessAlert`), `Progress`, `Spinner`, `Toast` | `Badge.variant`: `pink` `yellow` `green` `blue` `purple` `gray`; `Alert.variant`: `error` `success` |
|
|
1230
|
+
| Overlays | `Dialog`, `ConfirmationDialog`, `Drawer`, `ViewDrawer`, `Dropdown` | `open` + `onOpenChange` or `defaultOpen`; `Drawer.direction`: `rtl` `ltr` `btt` `ttb` |
|
|
1231
|
+
| Charts | `Chart` | `options` (ApexCharts options); it draws with the `ApexCharts` the page provides (`window.ApexCharts`) or a `factory` you pass |
|
|
1232
|
+
|
|
1233
|
+
Anything the kit does not have — a custom gauge, a layered bar — is plain Solid markup styled with utilities and a module, as
|
|
1234
|
+
in the snippet above.
|
|
1235
|
+
|
|
1236
|
+
## 14. Testing
|
|
1237
|
+
|
|
1238
|
+
`iota-ext test` runs every `*.test.ts` file against an **in-memory test host**: the real contract definitions, your
|
|
1239
|
+
real handlers, no database, no worker pool, no network. Tests are fast and deterministic, and run before you publish.
|
|
1240
|
+
|
|
1241
|
+
```ts
|
|
1242
|
+
// example/src/server.test.ts
|
|
1243
|
+
import {
|
|
1244
|
+
assert, createTestHost, fixture, overlayFixture, test, type TestHostOptions,
|
|
1245
|
+
} from "@iota-uz/sdk/runtime/testing"
|
|
1246
|
+
```
|
|
1247
|
+
|
|
1248
|
+
Import everything test-related from **`@iota-uz/sdk/runtime/testing`**. (`@iota-uz/sdk/testing`, without `runtime`, is a different
|
|
1249
|
+
package, the Playwright helpers.)
|
|
1250
|
+
|
|
1251
|
+
```ts
|
|
1252
|
+
// example/src/server.test.ts
|
|
1253
|
+
function host(options: TestHostOptions = {}) {
|
|
1254
|
+
return createTestHost({
|
|
1255
|
+
implementations: [s.adjustPoints, s.createReward, s.redeem, s.catalog, s.approval, s.reminder, s.clientContacts, s.clientConsent, s.resultTemplates, s.reminderTemplates],
|
|
1256
|
+
user: { permissions: [c.Manage.id] },
|
|
1257
|
+
secrets: { PARTNER_TOKEN: "token-for-tests" },
|
|
1258
|
+
...options,
|
|
1259
|
+
fixtures: [ali, agent, ...(options.fixtures ?? [])],
|
|
1260
|
+
})
|
|
1261
|
+
}
|
|
1262
|
+
```
|
|
1263
|
+
|
|
1264
|
+
Register cases with `test(name, fn)` (and group with `describe(name, body)`). A case passes unless it throws or rejects.
|
|
1265
|
+
The command type-checks the package first and runs nothing when it does not compile; failures print the assertion
|
|
1266
|
+
message and the line in **your** `.ts` file (the bundles are source-mapped), `--json` gives the same as data.
|
|
1267
|
+
|
|
1268
|
+
### 14.1 The host
|
|
1269
|
+
|
|
1270
|
+
| `createTestHost({ … })` option | meaning |
|
|
1271
|
+
|---|---|
|
|
1272
|
+
| `fixtures` | initial rows: `fixture(Entity, values, { key })` (returns `{ key, ref, record }`) and `overlayFixture(Overlay, baseRef, values)`; defaults apply (`createdAt` / `updatedAt` default to `EPOCH` on every entity), values are validated; native entities need an explicit `key` |
|
|
1273
|
+
| `implementations` | handlers `tx.call` / `ctx.call` / `wf.call` dispatch to, by contract; also `templates(...)`, and the `contactResolver` and `deliveryPolicy` implementations notice delivery uses |
|
|
1274
|
+
| `templates` | `templates(...)` exports (alternatively list them in `implementations`) |
|
|
1275
|
+
| `contacts` | `(record) => ContactTargets \| undefined`: contact data of record recipients, answered before a bound resolver |
|
|
1276
|
+
| `guards` | `guard`, `precheck` and `writeRule` values to apply |
|
|
1277
|
+
| `entities` | entity definitions the host cannot learn from calls (targets of ref paths) |
|
|
1278
|
+
| `user` | `{ id, permissions, locale, kind }` of the acting principal; read rules and hidden fields follow `permissions` |
|
|
1279
|
+
| `users` | `{ "<userId>": permissions }`: other users, for tasks assigned to a permission (`run.decide(task, decision, { by })`) |
|
|
1280
|
+
| `secrets` | values for `ctx.secrets.get` |
|
|
1281
|
+
| `fakes` | your own `fakeEffects()` instance |
|
|
1282
|
+
| `now` | start of the host clock |
|
|
1283
|
+
| `snapshot` | the `package@version` that delivery policies receive as `notice.snapshot` (default `<owner>.<module>@0.0.0`) |
|
|
1284
|
+
|
|
1285
|
+
| `host.` | meaning |
|
|
1286
|
+
|---|---|
|
|
1287
|
+
| `transaction(cb)` | runs `cb(tx)` in one transaction: commit, or rollback when it throws. `host.transaction((tx) => impl.handler(tx, input))` |
|
|
1288
|
+
| `command()` / `query()` | an ordinary-command context (`ctx.transaction`, `ctx.query`, `ctx.call`, secrets) / a read-only context |
|
|
1289
|
+
| `deliver(subscription, { subject, payload })` | deliver an event to a subscription in its own transaction |
|
|
1290
|
+
| `workflow(impl, input)` | a driven run: `run()`, `decide(task, decision, { by }?)` (`by` defaults to the host user and must be allowed to decide), `signal(...)`, `tasks`, `journal`; `run()` returns `completed`, `suspended` (on a sleep, signal or task) or `failed`. A `tx.start` inside a command is only recorded in `started`: drive the started run yourself with `host.workflow` |
|
|
1291
|
+
| `clock.advance("30d")` | move time; timers fire on the next `run()` |
|
|
1292
|
+
| `table(Entity)`, `overlayRow(Overlay, ref)` | committed rows, typed from the entity |
|
|
1293
|
+
| `emitted`, `notices`, `started`, `signals`, `logs` | what committed transactions recorded (rolled back work is not there) |
|
|
1294
|
+
| `deliveries` | the outcome of every notice delivery (§14.2) |
|
|
1295
|
+
| `fakes` | `sms`, `email`, `push`, `inApp`, `http` |
|
|
1296
|
+
|
|
1297
|
+
What the host reproduces from the Go data layer: SQL null semantics, filters through refs, ordering with the primary-key
|
|
1298
|
+
tie-break, read rules before filter and paging, hidden fields (not readable, filterable, sortable or writable), overlay
|
|
1299
|
+
rows readable only with their base row, unique constraints (`data.unique`), `rowVersion` conflicts, native-write
|
|
1300
|
+
refusal (`data.nativeWrite`), the `tx.call` / `ctx.call` rules (`runtime.ordinaryCommandInTx`,
|
|
1301
|
+
`runtime.intentInTransaction`, `runtime.nestedTransaction`), write rules, rollback of events/notices/starts/signals.
|
|
1302
|
+
These semantics are pinned by a shared conformance suite (`web/runtime/tests/conformance/cases.json`) that runs the
|
|
1303
|
+
same package and cases on this host and on the Go host with PostgreSQL, so the two cannot drift apart. **What it does not do**: it does not check a contract's
|
|
1304
|
+
`permission` (you call the handler directly; test the gate in the application's end-to-end suite), it does not verify
|
|
1305
|
+
that a ref points at an existing row, and handlers see one logical process (no concurrency).
|
|
1306
|
+
|
|
1307
|
+
### 14.2 Notifications in tests
|
|
1308
|
+
|
|
1309
|
+
With any `templates` bound, a committed `tx.notify` is rendered and delivered, per recipient and channel, to the fakes:
|
|
1310
|
+
|
|
1311
|
+
* **address** recipients are used as given (`address.sms` → `fakes.sms`);
|
|
1312
|
+
* **record** recipients go through `contacts`, else the `contactResolver` implementation bound for that entity;
|
|
1313
|
+
* **user** recipients read the `core.user` fixture: `sms` → phone, `email` → e-mail, `inApp` and `push` → the user key, and
|
|
1314
|
+
`uiLanguage` becomes the template `locale`.
|
|
1315
|
+
|
|
1316
|
+
```ts
|
|
1317
|
+
// example/src/server.test.ts
|
|
1318
|
+
const agent = fixture(core.User, { firstName: "Agent", lastName: "A", email: "agent@example.uz", uiLanguage: "en" }, { key: "42" })
|
|
1319
|
+
```
|
|
1320
|
+
|
|
1321
|
+
A native entity's fixture needs an explicit `key` and the fields the entity requires (`firstName`, `lastName`, `email` and
|
|
1322
|
+
`uiLanguage` for `core.User`); `createdAt` and `updatedAt` default to `EPOCH` (`"2026-01-01T00:00:00Z"`, exported by the same
|
|
1323
|
+
module) on every entity, whether or not it declares them as fields, so you never write them. Pass them to test time-dependent
|
|
1324
|
+
code.
|
|
1325
|
+
|
|
1326
|
+
```ts
|
|
1327
|
+
// example/src/server.test.ts
|
|
1328
|
+
// Rendered with the templates, delivered per recipient and channel to the fakes.
|
|
1329
|
+
assert.deepEqual(h.fakes.sms.delivered.map((m) => [m.to, m.text]), [["+998901112233", 'Your reward "Mug" is approved.']])
|
|
1330
|
+
assert.deepEqual(h.fakes.email.delivered.map((m) => m.to), ["ali@example.uz"])
|
|
1331
|
+
assert.deepEqual(h.deliveries.map((d) => [d.channel, d.status]), [["sms", "delivered"], ["email", "delivered"]])
|
|
1332
|
+
```
|
|
1333
|
+
|
|
1334
|
+
Each `host.deliveries` entry is `{ notice, channel, recipient, target, status, reason?, content? }` with status
|
|
1335
|
+
`delivered`, `skipped` (no renderer for the channel, no address, no contact data, a denied policy; `reason` says which) or
|
|
1336
|
+
`failed` (the fake channel rejected it: `fakes.sms.failNext(new Error("down"))`, the template threw, or a policy failed).
|
|
1337
|
+
Delivery happens after commit, so a rolled-back transaction delivers nothing. Without any templates, `tx.notify` is only
|
|
1338
|
+
recorded in `host.notices`; with templates, a notice none of them covers is a `notify.noTemplates` error, as in the runtime.
|
|
1339
|
+
|
|
1340
|
+
**Every channel is tried for every recipient** (§11, mixed recipients). The rows tell you which pair had no target:
|
|
1341
|
+
|
|
1342
|
+
```ts
|
|
1343
|
+
// example/src/server.test.ts
|
|
1344
|
+
assert.deepEqual(h.deliveries.map((d) => [d.recipient.kind, d.channel, d.status]), [
|
|
1345
|
+
["record", "sms", "delivered"],
|
|
1346
|
+
["record", "inApp", "skipped"], // in-app messages address ERP users, not client records
|
|
1347
|
+
["user", "sms", "skipped"], // the core.User fixture has no phone
|
|
1348
|
+
["user", "inApp", "delivered"],
|
|
1349
|
+
])
|
|
1350
|
+
```
|
|
1351
|
+
|
|
1352
|
+
**Delivery policies are evaluated.** For a record recipient, before a message is sent to a target over `sms`, `email` or
|
|
1353
|
+
`push`, the host asks every `deliveryPolicy` implementation bound for the recipient's entity (list it in
|
|
1354
|
+
`implementations`), with the request shape of §11: `notice.key` and `version` derived from the notice ID, `snapshot` from
|
|
1355
|
+
the `snapshot` option, `target.address` the resolved phone or e-mail and `deviceId` null. Policies run in contract-ID order
|
|
1356
|
+
with the rights of the test host's user and the first denial wins: the delivery is `skipped` with reason
|
|
1357
|
+
`policy_denied:<reason>` (or `policy_denied`; a `reason` that is not `[a-z0-9_.-]{1,64}` is dropped as in production) and the
|
|
1358
|
+
fake channel is not called, while the other targets and channels go on. A policy that throws, or answers anything but
|
|
1359
|
+
`{ allow: boolean, reason?: string }`, makes the delivery `failed`: like the platform, it is never an implicit allow.
|
|
1360
|
+
In-app, user and address recipients have no policy.
|
|
1361
|
+
|
|
1362
|
+
```ts
|
|
1363
|
+
// example/src/server.test.ts
|
|
1364
|
+
const h = host({ fixtures: [mug, redemption, overlayFixture(c.ClientLoyalty, ali.ref, { smsOptOut: true })] })
|
|
1365
|
+
await h.transaction((tx) =>
|
|
1366
|
+
tx.notify(c.RedemptionResult, { subject: redemption.ref, payload: { reward: "Mug", approved: true }, to: [recipient.record(ali.ref)], channels: ["sms", "email"] }),
|
|
1367
|
+
)
|
|
1368
|
+
assert.deepEqual(h.fakes.sms.delivered, [])
|
|
1369
|
+
assert.deepEqual(h.fakes.email.delivered.map((m) => m.to), ["ali@example.uz"])
|
|
1370
|
+
assert.deepEqual(h.deliveries.map((d) => [d.channel, d.status, d.reason]), [["sms", "skipped", "policy_denied:sms_opt_out"], ["email", "delivered", undefined]])
|
|
1371
|
+
```
|
|
1372
|
+
|
|
1373
|
+
What stays outside the host: the trigger-owner assignment (a policy with no owner is retried in production; the host just
|
|
1374
|
+
runs it) and the application's Go-configured policy. Unit-test a policy in isolation by calling its handler with a request
|
|
1375
|
+
object, as you would any query handler.
|
|
1376
|
+
|
|
1377
|
+
### 14.3 `fetch` and the fakes
|
|
1378
|
+
|
|
1379
|
+
Inside `iota-ext test` outbound network is blocked: `fetch`, sockets and DNS fail. The one way out is a **fake HTTP
|
|
1380
|
+
route**: while a test host exists, the global `fetch` in the code under test is answered by `host.fakes.http`.
|
|
1381
|
+
|
|
1382
|
+
```ts
|
|
1383
|
+
// example/src/server.test.ts
|
|
1384
|
+
h.fakes.http.route("GET", "https://api.partner.example/stock/Mug", { status: 200, body: { available: 3 } })
|
|
1385
|
+
```
|
|
1386
|
+
|
|
1387
|
+
`route(method, url, response | (request) => response)` matches the method and the exact URL; an unrouted request throws
|
|
1388
|
+
`UnmatchedRequestError`; `fakes.http.calls` records method, url, headers and parsed JSON body. The other channels record
|
|
1389
|
+
every attempt in `calls` and every unique delivery in `delivered` (idempotency keys dedupe). Create the host *inside*
|
|
1390
|
+
each test (the last host created owns the routes) and call `fakes.reset()` if you share one.
|
|
1391
|
+
|
|
1392
|
+
### 14.4 Assertions and doubles
|
|
1393
|
+
|
|
1394
|
+
`assert` (from the same module) needs no Node typings and prints diffs: `ok`, `equal` (`Object.is`), `notEqual`,
|
|
1395
|
+
`deepEqual` (first differing path in the message), `partial` (the actual value contains these properties), `match`,
|
|
1396
|
+
`throws`, `rejects`, `fail`. `assert.rejects(promiseOrFn, matcher)` takes a message substring or RegExp, an error class,
|
|
1397
|
+
a **domain error contract** (`NotEnoughPoints`), or `{ code, kind, message, issue }`:
|
|
1398
|
+
|
|
1399
|
+
```ts
|
|
1400
|
+
// example/src/server.test.ts
|
|
1401
|
+
await assert.rejects(h.transaction((tx) => tx.call(c.AdjustPoints, { client: ali.ref, delta: 20_000 })), { kind: "validation", issue: c.DeltaTooLarge })
|
|
1402
|
+
```
|
|
1403
|
+
|
|
1404
|
+
You may use `node:assert/strict` instead (install `@types/node`). A native contract has no handler in a test host: bind a
|
|
1405
|
+
double with `implement(crm.UpsertClient, async (tx, input) => …)` and pass it in `implementations`:
|
|
1406
|
+
|
|
1407
|
+
```ts
|
|
1408
|
+
// example/src/server.test.ts
|
|
1409
|
+
const upsert = implement(crm.UpsertClient, async (_tx, input) => ({ client: input.client ?? ali.ref, created: input.client === undefined }))
|
|
1410
|
+
```
|
|
1411
|
+
|
|
1412
|
+
A subscription, schedule or endpoint handler is a plain function: call `sub.handler(tx, event)` inside
|
|
1413
|
+
`host.transaction`, or `host.deliver(sub, event)`; for a schedule or endpoint pass `{ ...host.command(), slot }` /
|
|
1414
|
+
`{ ...host.command(), request }`.
|
|
1415
|
+
|
|
1416
|
+
### 14.5 What the offline tools do not cover: the client graph
|
|
1417
|
+
|
|
1418
|
+
`iota-ext test` runs your **server** code. There is no offline surface that mounts a Solid page, slot or cell renderer: that
|
|
1419
|
+
needs a DOM, a browser build of Solid and the host's shared module registry, none of which the Node test host has, and a
|
|
1420
|
+
stub would only hide differences from the browser. What you do have offline:
|
|
1421
|
+
|
|
1422
|
+
* `iota-ext check` / `build` typecheck the client graph (props, `useQuery` / `useCommand` inputs and results are typed from
|
|
1423
|
+
your contracts), enforce its rules (no server imports, no Node built-ins, no global stylesheets), bundle it for the browser and
|
|
1424
|
+
build its stylesheets (§13.6), so a screen that compiles calls your contracts correctly;
|
|
1425
|
+
* every query and command a screen calls is a plain contract you can test on the host (§14.1), including its permission
|
|
1426
|
+
behaviour through read rules; keep screen logic that deserves a test in a pure `.ts` file and test that file;
|
|
1427
|
+
* the loading, error and empty states and the markup are checked in the application: activate the package on a development
|
|
1428
|
+
instance, or render the component in your own Vitest + jsdom setup (below).
|
|
1429
|
+
|
|
1430
|
+
**Rendering a screen in Vitest.** Install `vitest`, `jsdom`, `vite-plugin-solid`, `@solidjs/testing-library` and
|
|
1431
|
+
**`vite@^6`** (newer Vite majors require a newer esbuild than the SDK's `esbuild@^0.25` peer and npm refuses the tree):
|
|
1432
|
+
|
|
1433
|
+
```ts
|
|
1434
|
+
// vitest.config.ts
|
|
1435
|
+
import { defineConfig } from "vitest/config"
|
|
1436
|
+
import solid from "vite-plugin-solid"
|
|
1437
|
+
import { fileURLToPath } from "node:url"
|
|
1438
|
+
|
|
1439
|
+
export default defineConfig({
|
|
1440
|
+
plugins: [solid()],
|
|
1441
|
+
resolve: {
|
|
1442
|
+
conditions: ["browser"],
|
|
1443
|
+
// the developer kit is not in node_modules (§5): point the import at the generated modules
|
|
1444
|
+
alias: [{ find: /^@iota-kit\/(.+)$/, replacement: fileURLToPath(new URL("./.iota/kit/$1/index.js", import.meta.url)) }],
|
|
1445
|
+
},
|
|
1446
|
+
test: { environment: "jsdom", include: ["dom/**/*.spec.tsx"], server: { deps: { inline: [/@iota-uz\/sdk/] } } },
|
|
1447
|
+
})
|
|
1448
|
+
```
|
|
1449
|
+
|
|
1450
|
+
In a test, wrap the screen in `RuntimeProvider` (from `@iota-uz/sdk/runtime/client`) with a fake transport,
|
|
1451
|
+
`{ invoke: async (kind, resource, input) => … }`, which is what `useQuery` and `useCommand` call. Here the UI kit is the real
|
|
1452
|
+
one (imported directly, not through the host) and your `*.module.css` classes resolve through Vite. Pass `helpHref` an
|
|
1453
|
+
explicit `{ namespace }` in such tests, or the page context it otherwise reads is missing.
|
|
1454
|
+
|
|
1455
|
+
## 15. Errors the tools print
|
|
1456
|
+
|
|
1457
|
+
Every diagnostic is `file:line:col code message` and points at **your** source.
|
|
1458
|
+
|
|
1459
|
+
| code | meaning |
|
|
1460
|
+
|---|---|
|
|
1461
|
+
| `ts.<n>` | a TypeScript error (the number is the compiler's). Messages for the usual mistakes name the fix: a write to a native entity → "use a published operation (`tx.call`)"; ordering by an enum → "cannot order by 'status'"; a range on a non-orderable field; a filter on a `json` field; `tx.call` of an ordinary command → "use `ctx.call`"; a keyless `tx.start` → "needs a start key" |
|
|
1462
|
+
| `graph.impureContract` | the contracts graph imported `@iota-uz/sdk/runtime/server\|client`, Solid or a Node built-in |
|
|
1463
|
+
| `graph.clientInServer` / `graph.serverInClient` | a graph reached the other one (the message names the file and, for npm, "through …"); the UI kit (`@iota-uz/sdk/solid-ui`) counts as client-only. For a local file only the server reaches, the message names the fix: put shared pure code in the contracts layer (§1) |
|
|
1464
|
+
| `graph.globalCss` | client code (or one of its stylesheets) imported a global stylesheet: use utilities or a `*.module.css` (§13.6) |
|
|
1465
|
+
| `graph.cssOutsideClient` | the server or contracts graph imported a stylesheet |
|
|
1466
|
+
| `css.syntax` / `css.tailwind` | a malformed stylesheet (located in the file) / the Tailwind compiler failed on the package's styles |
|
|
1467
|
+
| `graph.unknownKit` | an `@iota-kit/<ns>` module is not in the kit: `iota-ext kit generate` or `kit pull` (reported once per file and module; the type errors it causes are hidden and counted by the `kit.followOn` warning) |
|
|
1468
|
+
| `manifest.duplicateId` / `outsideNamespace` / `invalidId` | an ID is declared twice, outside the namespace, or malformed. Entities, routes and workflows share one ID space: give them different names |
|
|
1469
|
+
| `manifest.undeclaredReference` | a resource refers to a contract that is not exported from the contracts graph |
|
|
1470
|
+
| `manifest.wrongGraph` | a contract exported from the server graph, a server value from the client one, … |
|
|
1471
|
+
| `manifest.duplicateImplementation` / `duplicateTemplates` | two exports implement one contract / one notice |
|
|
1472
|
+
| `manifest.invalidDeclaration` | an invalid cron expression, endpoint path, guard target, … |
|
|
1473
|
+
| `manifest.import` | importing a bundle failed (a top-level error in your code) |
|
|
1474
|
+
| `build.unresolved` / `build.error` / `build.jsx` | a bundling error at the import in your source: a missing module, a JSX problem; a UI kit subpath (`@iota-uz/sdk/solid-ui/forms/Button`) is unresolved by rule: import from `@iota-uz/sdk/solid-ui` |
|
|
1475
|
+
| `docs.*` | a problem in `docs/` (§13.5): `frontMatter`, `title`, `audience`, `badPermission` / `unknownPermission` / `permissionMismatch`, `noLocale` / `badLocale` / `badPath` / `unsupportedFile` / `missingDefault` / `tooLarge` / `encoding` / `symlink`, `brokenLink` / `linkEscapes` / `linkTarget` / `linkScheme` / `unknownRoute` / `image`, `unknownHelpHref` |
|
|
1476
|
+
| `package.*` | `package.json` problems: missing `iota` section, a bad namespace, an entry that does not exist |
|
|
1477
|
+
| `npm.lockfileMissing` | published packages with dependencies need `package-lock.json` |
|
|
1478
|
+
|
|
1479
|
+
Export resources as **top-level named exports**: a contract nested inside an exported object or array is an error
|
|
1480
|
+
("export resources as top-level named exports"). A client export's implicit ID lowers the first letter of the export
|
|
1481
|
+
name (`PolicyBadge` → `<namespace>.policyBadge`).
|
|
1482
|
+
|
|
1483
|
+
## 16. The `iota-ext` command
|
|
1484
|
+
|
|
1485
|
+
```text
|
|
1486
|
+
iota-ext init <dir> --namespace <owner.module> [--name <npm name>] [--no-client] [--no-kit] [--force]
|
|
1487
|
+
iota-ext kit generate [--catalog <file|sdk>]... # offline; default: the SDK natives
|
|
1488
|
+
iota-ext kit pull --server <url> [--token-env VAR] [--cookie-env VAR]
|
|
1489
|
+
iota-ext kit status [--json] # verify .iota/kit: modules, files, hashes, tsconfig paths; exit 1 when damaged
|
|
1490
|
+
iota-ext check [--json]
|
|
1491
|
+
iota-ext build [--out <dir>] [--json] # default .iota/build: artifacts/ and manifest.json
|
|
1492
|
+
iota-ext test [filter...] [--json]
|
|
1493
|
+
```
|
|
1494
|
+
|
|
1495
|
+
All commands except `init` take `--dir <package dir>` (default: the current directory). Output is for people; `--json`
|
|
1496
|
+
prints one JSON document for machines:
|
|
1497
|
+
|
|
1498
|
+
| command | `--json` document |
|
|
1499
|
+
|---|---|
|
|
1500
|
+
| `check` | `{ ok, diagnostics: [{ file, line?, column?, severity, code, message }], manifest }` |
|
|
1501
|
+
| `build` | `{ ok, out, diagnostics, artifacts: [path], manifest }` |
|
|
1502
|
+
| `test` | `{ ok, passed, failed, diagnostics, cases: [{ name, file, passed, durationMs, message?, location?: { file, line, column }, frames? }] }` |
|
|
1503
|
+
| `kit generate` / `kit pull` | `{ ok, hash, modules, dir, editor }` (`editor`: `present`, `added`, `manual` or `absent`, the state of the tsconfig `paths` entry) |
|
|
1504
|
+
| `kit status` | `{ ok, installed, dir, location, hash, source, modules: [{ name, state, problems }], editor }` (`state`: `ok`, `missing`, `modified`, `unrecorded`) |
|
|
1505
|
+
|
|
1506
|
+
**Exit codes**: `0` success; `1` the package has errors or a test failed; `2` usage (unknown option, bad namespace, not a
|
|
1507
|
+
package directory); `3` environment (the network, the build worker, an unreadable catalog file, an HTTP 401/403 from
|
|
1508
|
+
`kit pull`).
|
|
1509
|
+
|
|
1510
|
+
`check` typechecks, enforces the graph rules, builds all three graphs and extracts the manifest, writing nothing.
|
|
1511
|
+
`build` does the same and writes `artifacts/` (`contracts.mjs`, `server.mjs`, `client/…`) and `manifest.json`; the
|
|
1512
|
+
artifacts are what the platform would build from your sources, byte for byte. `test` compiles first and refuses to run a
|
|
1513
|
+
package with type errors.
|
|
1514
|
+
|
|
1515
|
+
## 17. Publishing and operating
|
|
1516
|
+
|
|
1517
|
+
The CLI is for the loop on your machine. A package goes live through the application, by the configurator UI
|
|
1518
|
+
(`/extensions`, with a Monaco editor, versions and workflows) or by MCP tools / the HTTP API under `/_ext/manage`.
|
|
1519
|
+
Both do the same things:
|
|
1520
|
+
|
|
1521
|
+
1. **Create a draft** (`ext_package_create`) and put your files in it: write them (`ext_file_write`), upload the tree, or
|
|
1522
|
+
import a Git commit (`ext_import_git`). Include `package-lock.json` when you have dependencies.
|
|
1523
|
+
2. **Check, test, build** (`ext_check`, `ext_test`, `ext_build`): the same worker and rules as the CLI, against the
|
|
1524
|
+
application's *real* kit.
|
|
1525
|
+
3. **Publish** (`ext_publish`): an immutable version with source and artifact hashes, the manifest and the kit snapshot it
|
|
1526
|
+
resolved against. Foreign references are validated against that snapshot.
|
|
1527
|
+
4. **Review** (`ext_review`): a reviewer approves a version, bound to its exact source and artifact hashes. A version runs
|
|
1528
|
+
only while its newest review is an approval.
|
|
1529
|
+
5. **Activate** (`ext_activate`): the version becomes the live one for the whole application: its schema is applied
|
|
1530
|
+
(new fields and tables; incompatible changes are refused), its resources, subscriptions, schedules and endpoints
|
|
1531
|
+
start. Assign **trigger owners** for user-less triggers (`ext_owner_assign`) and **bind** replacement candidates
|
|
1532
|
+
(`ext_bind`: a native command, a screen, the shell).
|
|
1533
|
+
6. **Operate**: `ext_workflow_*` (inspect, signal, decide tasks, terminate, restart, resolve), `ext_audit_list`,
|
|
1534
|
+
`ext_deactivate`, `ext_purge` (deletes the package's data).
|
|
1535
|
+
|
|
1536
|
+
Permissions: *read* (kit, versions), *author* (drafts), *review*, *publish* (activate, deactivate, purge, bind, owners), *operate* (execute, workflow actions, requeue).
|
|
1537
|
+
Source control is yours: `ext_export` returns the draft as a tree to commit.
|
|
1538
|
+
|
|
1539
|
+
What is installed documents itself. In the application's Help Center, *Extensions → Reference* lists every namespace you may
|
|
1540
|
+
see with its entities, commands, queries, events, workflows, endpoints and the JSON Schemas and examples of their inputs and
|
|
1541
|
+
outputs, taken from the live catalog (your own package appears there as soon as it is active); the same reference is the
|
|
1542
|
+
**Reference** tab of the configurator and the `ext_reference` MCP tool. You see the resources your permissions allow, and
|
|
1543
|
+
`Extensions.Read` shows everything. `GET /_ext/openapi.json` serves the HTTP interface as an OpenAPI 3.1 document, and
|
|
1544
|
+
operators can export one offline for Swagger UI (see [`consumer.md`](consumer.md), §9).
|
|
1545
|
+
|
|
1546
|
+
## 18. Building a business module: patterns
|
|
1547
|
+
|
|
1548
|
+
The platform gives you entities, contracts, rules, workflows and screens; a real module — say, reinsurance underwriting:
|
|
1549
|
+
assessments of offered risks, a verdict against limits, approval by a committee, a contract booked in the host
|
|
1550
|
+
application — is a combination of a few patterns. Each is built from what the sections above describe.
|
|
1551
|
+
|
|
1552
|
+
**Rules that change over time: a versioned parameter set.** Limits, thresholds and weights live in an entity, not in
|
|
1553
|
+
code, so an administrator changes them without a release. Keep every version, and pin each assessment to the version it
|
|
1554
|
+
was judged on, so a verdict never changes behind the user's back:
|
|
1555
|
+
|
|
1556
|
+
```ts
|
|
1557
|
+
export const ParameterSet = entity("acme.reinsurance.parameterSet", {
|
|
1558
|
+
label: field.text({ maxLength: 40 }), // "v1 of 01.10.2026"
|
|
1559
|
+
status: field.enum(["draft", "published", "retired"]).default("draft"),
|
|
1560
|
+
maxScore: field.decimal({ precision: 4, scale: 2 }),
|
|
1561
|
+
authorityLimit: field.decimal({ precision: 18, scale: 2 }),
|
|
1562
|
+
})
|
|
1563
|
+
export const Assessment = entity("acme.reinsurance.assessment", {
|
|
1564
|
+
parameters: field.ref(ParameterSet), // the version this assessment is judged on
|
|
1565
|
+
/* … */
|
|
1566
|
+
})
|
|
1567
|
+
```
|
|
1568
|
+
|
|
1569
|
+
A `writeRule` freezes a published set (§8); publishing a new version is a command that inserts it and retires the old one
|
|
1570
|
+
in one transaction. **Before** an administrator publishes, show the impact: a query that recomputes every open assessment
|
|
1571
|
+
with the draft and counts the verdicts that would change, using the same calculation module as the verdict itself.
|
|
1572
|
+
|
|
1573
|
+
**One calculation, everywhere.** Put the formulas (score, our share of the loss, the price check, the verdict) in a pure
|
|
1574
|
+
module the contracts layer reaches (§1). The server queries return the authoritative verdict; the screen imports the same
|
|
1575
|
+
module and recalculates as the user types, with no round trip and no second implementation to drift.
|
|
1576
|
+
|
|
1577
|
+
**An audit trail nobody can edit.** A log entity written by your commands (who, when, what, the version of the
|
|
1578
|
+
parameters) and an append-only `writeRule` (§8). The runtime also records every invocation and every management action
|
|
1579
|
+
(§17); your log is the business history users read on the screen.
|
|
1580
|
+
|
|
1581
|
+
**Approval by a committee.** A workflow started by the "submit" command: a human task assigned to a permission (§10), a
|
|
1582
|
+
timeout that escalates, and the status change plus a log line in one `wf.transaction` when the decision arrives. A notice
|
|
1583
|
+
tells the approvers that a task is waiting (§11).
|
|
1584
|
+
|
|
1585
|
+
**What the host application owns.** Offers, cedents and their contracts, a blacklist, currency rates, document approval,
|
|
1586
|
+
booking a contract: these are the application's data and commands. You reach them through the developer kit
|
|
1587
|
+
(`@iota-kit/<namespace>`) as native contracts the application publishes (§7.4), never through its tables. If the
|
|
1588
|
+
application does not publish one yet, that is a contract to add on the application side (consumer guide), not a reason to
|
|
1589
|
+
copy its data into your package.
|
|
1590
|
+
|
|
1591
|
+
**Screens that look native.** The UI kit for controls and tables, Tailwind utilities for layout, a CSS module for the one
|
|
1592
|
+
custom visualization, and custom properties for data-driven sizes (§13.6). Link each screen to its user documentation
|
|
1593
|
+
with `helpHref` (§13.5).
|
|
1594
|
+
|
|
1595
|
+
## 19. Reference: where to look
|
|
1596
|
+
|
|
1597
|
+
* The API by import path: `@iota-uz/sdk/runtime` (contracts, `t`, `field`, `entity`, `overlay`, `column`, `defineSlot`, `ref`, `$`,
|
|
1598
|
+
`href`, wire helpers), `@iota-uz/sdk/runtime/server` (`implement`, `subscribe`, `guard`, `precheck`, `writeRule`, `schedule`,
|
|
1599
|
+
`endpoint`, `templates`, `recipient`, context types), `@iota-uz/sdk/runtime/client` (`page`, `navigation`, `slot`, `Slot`, `cell`,
|
|
1600
|
+
`shellRenderer`, `useQuery`, `useCommand`, `isError`, `issuesOf`, `helpHref`), `@iota-uz/sdk/runtime/testing` (everything in §14: the test
|
|
1601
|
+
host, `fixture`, `EPOCH`, `assert`, the fakes; **not** `@iota-uz/sdk/testing`, which is the Playwright package).
|
|
1602
|
+
`@iota-uz/sdk/runtime/kit` is internal to generated modules; never import it.
|
|
1603
|
+
* The complete working package: [`example/`](example). More real packages (an overlay with columns, a custom cell, slot contributions and a slot of your own, a replacement
|
|
1604
|
+
client view, a campaign workflow with an SMS gateway endpoint, a replacement shell, versioned packages) are in `pkg/extruntime/e2e/testdata/`.
|
|
1605
|
+
* The platform contract: [`../extension-runtime.md`](../extension-runtime.md), §9.1 onwards.
|
|
1606
|
+
* Documentation for your own users: §13.5. It lands in the Help Center under *Applications*, next to (not inside) the developer
|
|
1607
|
+
reference below.
|
|
1608
|
+
* The live API reference of the application you publish to: *Extensions → Reference* in the Help Center (`/help`), the
|
|
1609
|
+
configurator's Reference tab, `ext_reference` over MCP, and `GET /_ext/openapi.json` (OpenAPI 3.1).
|