@elevasis/sdk 1.44.2 → 1.45.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/dist/cli.cjs +1001 -652
- package/dist/index.d.ts +1045 -509
- package/dist/index.js +748 -690
- package/dist/node/index.d.ts +105 -97
- package/dist/test-utils/index.d.ts +42 -28
- package/dist/test-utils/index.js +549 -732
- package/dist/worker/index.d.ts +12112 -0
- package/dist/worker/index.js +211 -186
- package/package.json +6 -9
- package/reference/_navigation.md +151 -21
- package/reference/_reference-manifest.json +186 -4
- package/reference/claude-config.md +8 -0
- package/reference/core/index.mdx +3 -3
- package/reference/examples/organization-model.ts +117 -111
- package/reference/index.mdx +4 -4
- package/reference/rules/active-change-index.md +40 -54
- package/reference/rules/agent-runtime.md +81 -0
- package/reference/rules/agent-start-here.md +71 -163
- package/reference/rules/deployment.md +33 -10
- package/reference/rules/error-handling.md +26 -0
- package/reference/rules/execution.md +13 -0
- package/reference/rules/frontend.md +10 -3
- package/reference/rules/observability.md +9 -1
- package/reference/rules/operations.md +26 -17
- package/reference/rules/organization-model.md +74 -88
- package/reference/rules/organization-os.md +71 -88
- package/reference/rules/package-taxonomy.md +11 -2
- package/reference/rules/platform.md +13 -7
- package/reference/rules/shared-types.md +15 -0
- package/reference/rules/task-tracking.md +30 -5
- package/reference/rules/ui.md +145 -3
- package/reference/rules/vibe-intents.md +271 -0
- package/reference/rules/vibe.md +17 -243
- package/reference/scaffold/core/organization-graph.mdx +111 -97
- package/reference/scaffold/core/organization-model.mdx +234 -214
- package/reference/scaffold/operations/propagation-pipeline.md +1 -1
- package/reference/scaffold/operations/scaffold-maintenance.md +19 -18
- package/reference/scaffold/operations/workflow-recipes.md +71 -19
- package/reference/scaffold/recipes/add-a-feature.md +156 -146
- package/reference/scaffold/recipes/add-a-resource.md +123 -117
- package/reference/scaffold/recipes/customize-crm-actions.md +25 -10
- package/reference/scaffold/recipes/customize-knowledge-browser.md +52 -117
- package/reference/scaffold/recipes/customize-organization-model.md +161 -149
- package/reference/scaffold/recipes/extend-a-base-entity.md +156 -140
- package/reference/scaffold/recipes/extend-crm.md +16 -11
- package/reference/scaffold/recipes/extend-lead-gen.md +25 -7
- package/reference/scaffold/recipes/gate-by-feature-or-admin.md +160 -118
- package/reference/scaffold/recipes/index.md +2 -2
- package/reference/scaffold/recipes/query-the-knowledge-graph.md +23 -23
- package/reference/scaffold/reference/contracts.md +12 -1
- package/reference/scaffold/reference/glossary.md +3 -3
- package/reference/scaffold/reference/system-interface-capabilities.md +5 -4
- package/reference/scaffold/ui/composition-extensibility.mdx +271 -232
- package/reference/scaffold/ui/feature-flags-and-gating.md +14 -6
- package/reference/scaffold/ui/feature-shell.mdx +279 -62
- package/reference/scaffold/ui/recipes.md +229 -197
- package/reference/sdk/cli-management.mdx +77 -29
- package/reference/sdk/concepts.mdx +2 -0
- package/reference/sdk/define-builders.mdx +76 -0
- package/reference/sdk/deployment/command-center.mdx +6 -2
- package/reference/sdk/deployment/execution-reference.mdx +64 -186
- package/reference/sdk/deployment/index.mdx +2 -0
- package/reference/sdk/exports.mdx +4 -4
- package/reference/sdk/framework/agent.mdx +49 -119
- package/reference/sdk/framework/index.mdx +46 -65
- package/reference/sdk/framework/project-structure.mdx +150 -205
- package/reference/sdk/framework/tutorial-system.mdx +2 -2
- package/reference/sdk/human-in-the-loop.mdx +152 -0
- package/reference/sdk/index.mdx +6 -7
- package/reference/sdk/platform-tools/index.mdx +12 -0
- package/reference/sdk/platform-tools/type-safety.mdx +4 -0
- package/reference/sdk/project-deployment-spec.mdx +131 -0
- package/reference/sdk/resources/index.mdx +23 -7
- package/reference/sdk/resources/patterns.mdx +54 -24
- package/reference/sdk/resources/types.mdx +7 -4
- package/reference/sdk/templates/data-enrichment.mdx +7 -3
- package/reference/sdk/templates/email-sender.mdx +139 -135
- package/reference/sdk/templates/lead-scorer.mdx +5 -1
- package/reference/sdk/templates/pdf-generator.mdx +155 -151
- package/reference/sdk/templates/recurring-job.mdx +195 -189
- package/reference/sdk/templates/text-classifier.mdx +4 -0
- package/reference/sdk/templates/web-scraper.mdx +139 -135
- package/reference/spine/spine-primer.md +135 -96
- package/reference/ui/index.mdx +14 -7
- package/dist/types/worker/adapters/anymailfinder.d.ts +0 -14
- package/dist/types/worker/adapters/apify.d.ts +0 -14
- package/dist/types/worker/adapters/approval.d.ts +0 -23
- package/dist/types/worker/adapters/attio.d.ts +0 -22
- package/dist/types/worker/adapters/clickup.d.ts +0 -22
- package/dist/types/worker/adapters/create-adapter.d.ts +0 -41
- package/dist/types/worker/adapters/crm.d.ts +0 -20
- package/dist/types/worker/adapters/dropbox.d.ts +0 -14
- package/dist/types/worker/adapters/email.d.ts +0 -25
- package/dist/types/worker/adapters/execution.d.ts +0 -22
- package/dist/types/worker/adapters/gmail.d.ts +0 -14
- package/dist/types/worker/adapters/google-sheets.d.ts +0 -14
- package/dist/types/worker/adapters/index.d.ts +0 -33
- package/dist/types/worker/adapters/instantly.d.ts +0 -14
- package/dist/types/worker/adapters/lead.d.ts +0 -28
- package/dist/types/worker/adapters/list.d.ts +0 -9
- package/dist/types/worker/adapters/llm.d.ts +0 -45
- package/dist/types/worker/adapters/millionverifier.d.ts +0 -14
- package/dist/types/worker/adapters/notification.d.ts +0 -28
- package/dist/types/worker/adapters/pdf.d.ts +0 -22
- package/dist/types/worker/adapters/projects.d.ts +0 -20
- package/dist/types/worker/adapters/resend.d.ts +0 -14
- package/dist/types/worker/adapters/scheduler.d.ts +0 -25
- package/dist/types/worker/adapters/signature-api.d.ts +0 -14
- package/dist/types/worker/adapters/storage.d.ts +0 -33
- package/dist/types/worker/adapters/stripe.d.ts +0 -14
- package/dist/types/worker/adapters/tomba.d.ts +0 -14
- package/dist/types/worker/index.d.ts +0 -60
- package/dist/types/worker/platform.d.ts +0 -90
- package/dist/types/worker/utils.d.ts +0 -9
- package/reference/claude-config/Overview.md +0 -230
- package/reference/claude-config/hooks/post-edit-validate.mjs +0 -98
- package/reference/claude-config/hooks/scaffold-registry-reminder.mjs +0 -187
- package/reference/claude-config/hooks/tool-failure-recovery.mjs +0 -73
- package/reference/claude-config/registries/graph-skills.json +0 -4
- package/reference/claude-config/registries/knowledge-flags.json +0 -154
- package/reference/claude-config/registries/skill-coverage.json +0 -20
- package/reference/claude-config/rules/active-change-index.md +0 -22
- package/reference/claude-config/rules/agent-start-here.md +0 -22
- package/reference/claude-config/rules/deployment.md +0 -22
- package/reference/claude-config/rules/error-handling.md +0 -22
- package/reference/claude-config/rules/execution.md +0 -22
- package/reference/claude-config/rules/frontend.md +0 -22
- package/reference/claude-config/rules/observability.md +0 -22
- package/reference/claude-config/rules/operations.md +0 -22
- package/reference/claude-config/rules/organization-model.md +0 -22
- package/reference/claude-config/rules/organization-os.md +0 -22
- package/reference/claude-config/rules/package-taxonomy.md +0 -22
- package/reference/claude-config/rules/platform.md +0 -22
- package/reference/claude-config/rules/shared-types.md +0 -22
- package/reference/claude-config/rules/task-tracking.md +0 -22
- package/reference/claude-config/rules/topbar-actions.md +0 -70
- package/reference/claude-config/rules/ui.md +0 -22
- package/reference/claude-config/rules/vibe.md +0 -22
- package/reference/claude-config/scripts/statusline-command.js +0 -18
- package/reference/claude-config/settings.json +0 -30
- package/reference/claude-config/skills/client/SKILL.md +0 -201
- package/reference/claude-config/skills/deploy/SKILL.md +0 -159
- package/reference/claude-config/skills/dsp/SKILL.md +0 -66
- package/reference/claude-config/skills/elevasis/SKILL.md +0 -251
- package/reference/claude-config/skills/explore/SKILL.md +0 -78
- package/reference/claude-config/skills/git-sync/SKILL.md +0 -166
- package/reference/claude-config/skills/om/SKILL.md +0 -475
- package/reference/claude-config/skills/om/operations/build.md +0 -237
- package/reference/claude-config/skills/om/operations/codify-level-a.md +0 -109
- package/reference/claude-config/skills/om/operations/codify-level-b.md +0 -159
- package/reference/claude-config/skills/om/operations/customers.md +0 -114
- package/reference/claude-config/skills/om/operations/features.md +0 -88
- package/reference/claude-config/skills/om/operations/goals.md +0 -123
- package/reference/claude-config/skills/om/operations/identity.md +0 -97
- package/reference/claude-config/skills/om/operations/labels.md +0 -110
- package/reference/claude-config/skills/om/operations/offerings.md +0 -114
- package/reference/claude-config/skills/om/operations/roles.md +0 -104
- package/reference/claude-config/skills/om/operations/scaffold.md +0 -163
- package/reference/claude-config/skills/om/operations/techStack.md +0 -38
- package/reference/claude-config/skills/project/SKILL.md +0 -1114
- package/reference/claude-config/skills/run-ui/SKILL.md +0 -73
- package/reference/claude-config/skills/save/SKILL.md +0 -183
- package/reference/claude-config/skills/setup/SKILL.md +0 -290
- package/reference/claude-config/skills/status/SKILL.md +0 -59
- package/reference/claude-config/skills/submit-request/SKILL.md +0 -180
- package/reference/claude-config/skills/sync/SKILL.md +0 -47
- package/reference/claude-config/skills/tutorial/SKILL.md +0 -259
- package/reference/claude-config/skills/tutorial/progress-template.md +0 -74
- package/reference/claude-config/skills/tutorial/technical.md +0 -1303
- package/reference/claude-config/skills/tutorial/vibe-coder.md +0 -890
- package/reference/claude-config/sync-notes/2026-04-22-git-sync-and-sync-notes.md +0 -27
- package/reference/claude-config/sync-notes/2026-04-22-lead-gen-deliverability-removal.md +0 -30
- package/reference/claude-config/sync-notes/2026-04-24-test-utils-and-template-tests.md +0 -73
- package/reference/claude-config/sync-notes/2026-04-24-ui-consolidation-and-sdk-cli-train.md +0 -86
- package/reference/claude-config/sync-notes/2026-04-25-auth-role-system-and-settings-roles.md +0 -55
- package/reference/claude-config/sync-notes/2026-04-27-crm-hitl-action-layer-cutover.md +0 -97
- package/reference/claude-config/sync-notes/2026-04-27-lead-gen-substrate-train.md +0 -112
- package/reference/claude-config/sync-notes/2026-04-29-crm-state-and-lead-gen-processing-status.md +0 -93
- package/reference/claude-config/sync-notes/2026-05-02-crm-ownership-next-action.md +0 -58
- package/reference/claude-config/sync-notes/2026-05-02-template-hardcode-workos-config.md +0 -56
- package/reference/claude-config/sync-notes/2026-05-04-elevasis-workspace.md +0 -71
- package/reference/claude-config/sync-notes/2026-05-04-knowledge-bundle.md +0 -83
- package/reference/claude-config/sync-notes/2026-05-04-template-skills-run-ui-and-tutorial.md +0 -59
- package/reference/claude-config/sync-notes/2026-05-05-list-builder.md +0 -42
- package/reference/claude-config/sync-notes/2026-05-06-crm-spine.md +0 -60
- package/reference/claude-config/sync-notes/2026-05-06-sdk-changes-release-train.md +0 -37
- package/reference/claude-config/sync-notes/2026-05-07-sdk-changes-release-train.md +0 -34
- package/reference/claude-config/sync-notes/2026-05-08-resource-governance-scaffold-guidance.md +0 -38
- package/reference/claude-config/sync-notes/2026-05-09-clients-domain.md +0 -32
- package/reference/claude-config/sync-notes/2026-05-09-command-system.md +0 -33
- package/reference/claude-config/sync-notes/2026-05-09-resource-governance-and-misc.md +0 -69
- package/reference/claude-config/sync-notes/2026-05-12-sdk-ready-release-train.md +0 -30
- package/reference/claude-config/sync-notes/2026-05-14-organization-model-ontology-refactor.md +0 -45
- package/reference/claude-config/sync-notes/2026-05-15-om-skill-rename-and-write-family.md +0 -52
- package/reference/claude-config/sync-notes/2026-05-17-sdk-boundary-consolidation.md +0 -33
- package/reference/claude-config/sync-notes/2026-05-20-om-define-helpers.md +0 -32
- package/reference/claude-config/sync-notes/2026-05-22-access-model-and-right-panel.md +0 -43
- package/reference/claude-config/sync-notes/2026-05-22-lead-gen-tenant-config.md +0 -40
- package/reference/claude-config/sync-notes/2026-05-22-org-model-multi-file-split.md +0 -61
- package/reference/claude-config/sync-notes/2026-05-23-branding-names-to-identity.md +0 -49
- package/reference/claude-config/sync-notes/2026-05-23-lead-gen-manage-access.md +0 -31
- package/reference/claude-config/sync-notes/2026-05-23-om-deployment-drift-detection.md +0 -42
- package/reference/claude-config/sync-notes/2026-05-23-om-full-model-deploy-contract.md +0 -33
- package/reference/claude-config/sync-notes/2026-05-23-ui-sdk-package-fixes.md +0 -37
- package/reference/claude-config/sync-notes/2026-05-24-platform-invite-router-core-baseline.md +0 -28
- package/reference/claude-config/sync-notes/2026-05-24-system-interface-readiness.md +0 -43
- package/reference/claude-config/sync-notes/2026-05-25-invitation-login-loader.md +0 -26
- package/reference/claude-config/sync-notes/2026-05-25-om-topbar-requests.md +0 -33
- package/reference/claude-config/sync-notes/2026-05-25-system-interface-profile-registry-and-substrate.md +0 -35
- package/reference/claude-config/sync-notes/2026-05-25-tenant-om-scaffold-cli.md +0 -49
- package/reference/claude-config/sync-notes/2026-05-25-vibe-operate-intent.md +0 -47
- package/reference/claude-config/sync-notes/2026-05-28-om-snapshot-sdk-workflow-config.md +0 -33
- package/reference/claude-config/sync-notes/2026-05-30-client-source-and-om-profiles.md +0 -39
- package/reference/claude-config/sync-notes/2026-06-02-knowledge-nested-group-routing.md +0 -27
- package/reference/claude-config/sync-notes/2026-06-02-nest-projects-under-platform.md +0 -45
- package/reference/claude-config/sync-notes/2026-06-03-skill-autogen-and-client-skill.md +0 -34
- package/reference/claude-config/sync-notes/2026-06-04-scaffold-registry-lane-severity.md +0 -34
- package/reference/claude-config/sync-notes/2026-06-05-appearance-app-mode-decouple.md +0 -29
- package/reference/claude-config/sync-notes/2026-06-05-ontology-endpoint-rename-and-knowledge-browser-ui.md +0 -86
- package/reference/claude-config/sync-notes/2026-06-06-om-build-systems-scaffold.md +0 -47
- package/reference/claude-config/sync-notes/2026-06-06-om-item-copy-references.md +0 -50
- package/reference/claude-config/sync-notes/2026-06-08-knowledge-base-page-not-found-fix.md +0 -76
- package/reference/claude-config/sync-notes/2026-06-09-agent-sessions-public-agent-chat-route.md +0 -75
- package/reference/claude-config/sync-notes/2026-06-09-sdk-cli-load-org-model-resolution.md +0 -42
- package/reference/claude-config/sync-notes/2026-06-12-agent-grants-visualizer-operations.md +0 -30
- package/reference/claude-config/sync-notes/2026-06-14-session-ux-and-project-cli-json.md +0 -33
- package/reference/claude-config/sync-notes/2026-06-14-shared-session-conversation-view.md +0 -26
- package/reference/claude-config/sync-notes/2026-06-15-session-chat-zero-wiring.md +0 -46
- package/reference/claude-config/sync-notes/2026-06-17-agent-session-ux-features.md +0 -34
- package/reference/claude-config/sync-notes/2026-06-25-shared-page-scroll-contract-guard.md +0 -52
- package/reference/claude-config/sync-notes/2026-06-26-leadgen-overview-om-telemetry.md +0 -47
- package/reference/claude-config/sync-notes/2026-07-21-agent-scaffold-hardening.md +0 -75
- package/reference/claude-config/sync-notes/2026-07-23-agent-session-memory.md +0 -49
- package/reference/claude-config/sync-notes/2026-07-23-workos-org-marker.md +0 -50
- package/reference/claude-config/sync-notes/2026-07-24-claude-5-models-and-session-surface-fixes.md +0 -116
- package/reference/claude-config/sync-notes/2026-07-27-agent-strict-output-and-turn-drift.md +0 -73
- package/reference/claude-config/sync-notes/2026-07-28-agent-reply-is-its-own-field.md +0 -84
- package/reference/claude-config/sync-notes/2026-07-30-login-screen-and-member-provisioning-state.md +0 -114
- package/reference/claude-config/sync-notes/2026-08-02-auth-guard-defaults-and-truncation-fix.md +0 -122
- package/reference/claude-config/sync-notes/2026-08-03-cli-gateway-errors-and-request-timeout.md +0 -120
- package/reference/claude-config/sync-notes/README.md +0 -43
- package/reference/sdk/framework/interaction-guidance.mdx +0 -182
- package/reference/sdk/framework/memory.mdx +0 -326
- package/reference/sdk/framework/resource-documentation.mdx +0 -90
- package/reference/sdk/roadmap.mdx +0 -164
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: When to Reach for the define* Builders
|
|
3
|
+
description: defineWorkflow, defineStep, defineContract, defineResource, and defineTopology exist for two different reasons -- this page teaches which reason applies before you pick a builder over a plain object literal.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`@elevasis/sdk`'s root export includes a family of `define*` functions: `defineWorkflow`, `defineStep`, `defineContract`, `defineWorkflowConfig`, `defineResource`, `defineResources`, `defineResourceOntology`, `defineTopology`, `defineTopologyRelationship`, plus the `topologyRelationship` / `topologyRef` helpers. Every existing recipe in this bundle teaches the plain object-literal shape instead (a `WorkflowDefinition` written out by hand with a `: WorkflowDefinition` annotation), which is completely valid TypeScript -- but it means the builders are never actually demonstrated, so there is nothing here to tell you when reaching for one buys you something real versus when it is just a different way to write the same object. This page is that judgment call. For the full list of what `@elevasis/sdk` exports, see the [Export Catalog](exports.mdx).
|
|
7
|
+
|
|
8
|
+
The family splits into two groups that do genuinely different things, and the judgment call is different for each.
|
|
9
|
+
|
|
10
|
+
## Group 1: Workflow Builders Are Type Inference, Not Validation
|
|
11
|
+
|
|
12
|
+
`defineWorkflow`, `defineStep`, and `defineContract` do nothing at runtime. Their entire implementation is an identity function constrained by a generic:
|
|
13
|
+
|
|
14
|
+
{/* doc-snippet:skip: source excerpt (WorkflowDefinition intentionally unimported), not a standalone compilable file */}
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
export function defineWorkflow<TWorkflow extends WorkflowDefinition>(workflow: TWorkflow): TWorkflow {
|
|
18
|
+
return workflow
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`defineStep` and `defineContract` are the same three lines against `WorkflowStep` and `Contract`. Calling one of these does not validate, transform, or check anything beyond what TypeScript's structural typing already does on the argument you pass it.
|
|
23
|
+
|
|
24
|
+
What it buys you is narrower inference. Annotate a literal `const echo: WorkflowDefinition = { ... }` and TypeScript widens every field to the interface's declared type -- `config.resourceId` becomes `string`, not `'echo'`. Pass the same object to `defineWorkflow({ ... })` with no annotation and `TWorkflow` is inferred from the literal you wrote, so `defineWorkflow(...).config.resourceId` keeps the literal type `'echo'`. That distinction only matters if something downstream reads the value back and wants the narrower type -- a test asserting on `resourceId`, a lookup table keyed by it, a second resource that imports the first and needs its literal id. A workflow file that is only ever consumed by the deploy pipeline, which just needs it to satisfy `WorkflowDefinition`, gets nothing extra from the wrapper.
|
|
25
|
+
|
|
26
|
+
That is a real, but narrow, upside -- and it is honestly reflected in what ships. The scaffolded template's own workflow files (`echo.ts`, `email-notification.ts`) use the plain annotated-literal form, not `defineWorkflow`. The builder is real, exported, and demonstrated in the SDK's own test fixtures with exactly the calling convention above -- it is simply not the house style the template ships with. Use the annotated literal by default, matching what a scaffolded project already contains; reach for `defineWorkflow` / `defineStep` / `defineContract` specifically when you want the object's literal types preserved past its own definition.
|
|
27
|
+
|
|
28
|
+
`defineWorkflowConfig` is a different kind of helper in this same group -- it derives `config` fields from an Organization Model resource descriptor instead of preserving literal types. It has its own page: see [The Deployment Spec Pattern](project-deployment-spec.mdx#defineworkflowconfig-deriving-config-from-one-om-descriptor).
|
|
29
|
+
|
|
30
|
+
## Group 2: Resource and Topology Builders Do Real Work
|
|
31
|
+
|
|
32
|
+
`defineResource`, `defineResources`, `defineResourceOntology`, `defineTopology`, and `defineTopologyRelationship` are a different animal entirely -- each one calls a Zod schema's `.parse()` on its way out:
|
|
33
|
+
|
|
34
|
+
{/* doc-snippet:skip: source excerpt (ResourceEntry/ResourceEntrySchema intentionally unimported), not a standalone compilable file */}
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
export function defineResource<const TResource extends ResourceEntry>(resource: TResource): TResource {
|
|
38
|
+
return ResourceEntrySchema.parse(resource) as TResource
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
A hand-typed object that satisfies the `ResourceEntry` TypeScript interface skips that check entirely at the point you write it. It is not unvalidated forever -- the whole Organization Model gets parsed eventually -- but a mistake surfaces later, at whole-model validation, as a less specific error than the one `defineResource` would have raised on the exact line that defined the bad resource.
|
|
43
|
+
|
|
44
|
+
`defineTopology` and `defineTopologyRelationship` go a step further: they compile human-authored references into the canonical shape the graph actually stores. A relationship's `from` / `to` can be written as an already-typed node ref, or as a resource descriptor object handed to you by another part of the model -- `compileTopologyNodeRef` resolves either into the canonical `{ kind, id }` form. This is not something a plain object literal can replicate without reimplementing that resolution step by hand:
|
|
45
|
+
|
|
46
|
+
{/* doc-snippet:skip: illustrative excerpt (someWorkflowResourceDescriptor intentionally undefined), not a standalone compilable file */}
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
import { defineTopology, topologyRef, topologyRelationship } from '@elevasis/sdk'
|
|
50
|
+
|
|
51
|
+
const topology = defineTopology({
|
|
52
|
+
'trigger-handles-webhook': topologyRelationship.triggers(
|
|
53
|
+
topologyRef.trigger('inbound-webhook'),
|
|
54
|
+
someWorkflowResourceDescriptor, // a resource object, resolved for you
|
|
55
|
+
{ systemPath: 'sales.lead-gen', required: true }
|
|
56
|
+
)
|
|
57
|
+
})
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
For this group, reaching for the builder is not a style preference -- it is the only path that gets you both the validation and the reference compilation. Do not hand-author the parsed topology shape (`{ from: { kind: 'resource', id: '...' }, to: ... }`) directly; author against the helpers and let them produce it.
|
|
61
|
+
|
|
62
|
+
**Tenant caveat:** these builders live in the Organization Model authoring layer. In a template-based project, `core/config/organization-model.ts` and its split sibling files are edited through the `/om` command, not by hand -- so day to day you are unlikely to call `defineResource` or `defineTopology` yourself even though they are part of the published surface. Understanding what they do is still useful: it is why hand-editing those files instead of going through `/om` is risky, since you would be reproducing Zod validation and reference compilation by hand and likely getting one of them wrong.
|
|
63
|
+
|
|
64
|
+
## Quick Decision Guide
|
|
65
|
+
|
|
66
|
+
- Writing a workflow, step, or contract, and nothing downstream needs the literal types back -- use the plain annotated object literal. This is what the scaffolded template ships.
|
|
67
|
+
- Writing a workflow, step, or contract, and something downstream reads the value back and needs its literal types preserved -- wrap it in `defineWorkflow` / `defineStep` / `defineContract`.
|
|
68
|
+
- Deriving a workflow's `config` from an OM resource descriptor that already has `ontology.primaryAction` set -- use `defineWorkflowConfig`.
|
|
69
|
+
- Authoring an Organization Model resource, resource ontology binding, or topology relationship directly (Elevasis's own workspace-internal model, or inside the tooling `/om` itself runs) -- always use `defineResource` / `defineResourceOntology` / `defineTopology` / `defineTopologyRelationship`, never the raw parsed shape.
|
|
70
|
+
- Authoring a tenant project's own Organization Model -- go through `/om`; you generally will not call the Group 2 builders yourself.
|
|
71
|
+
|
|
72
|
+
## Documentation
|
|
73
|
+
|
|
74
|
+
- [Export Catalog](exports.mdx) -- the generated, per-subpath inventory of everything `@elevasis/sdk` exports
|
|
75
|
+
- [Resources](resources/index.mdx) -- the `WorkflowDefinition` / `AgentDefinition` shape these builders wrap
|
|
76
|
+
- [The Deployment Spec Pattern](project-deployment-spec.mdx) -- `defineWorkflowConfig` and `projectDeploymentSpec` in context
|
|
@@ -54,6 +54,8 @@ Every resource you deploy becomes a node in the graph. Some nodes are executable
|
|
|
54
54
|
|
|
55
55
|
Relationships are edges in the graph. Declare them in `DeploymentSpec`:
|
|
56
56
|
|
|
57
|
+
{/* doc-snippet:skip: illustrative excerpt -- DeploymentSpec, scoreLeadWorkflow, sendProposalWorkflow are shown as already-defined resources from elsewhere in the project, not a standalone compilable file */}
|
|
58
|
+
|
|
57
59
|
```typescript
|
|
58
60
|
const org: DeploymentSpec = {
|
|
59
61
|
workflows: [scoreLeadWorkflow, sendProposalWorkflow],
|
|
@@ -126,7 +128,9 @@ The Command Queue surfaces all pending Human-in-the-Loop (HITL) approval request
|
|
|
126
128
|
- Approve or reject with an optional comment
|
|
127
129
|
- See the history of past decisions
|
|
128
130
|
|
|
129
|
-
**How it connects to your code:** Approval requests appear when a workflow step calls `approval.create()`. The workflow
|
|
131
|
+
**How it connects to your code:** Approval requests appear when a workflow step calls `approval.create()`. The step then **completes normally — the workflow does not pause.** Resolving the request later triggers a **new** execution of whichever resource the selected action's `target` names. Structure the work accordingly: everything that must happen after the decision belongs in that target resource, not in later steps of the workflow that raised the request.
|
|
132
|
+
|
|
133
|
+
{/* doc-snippet:skip: illustrative excerpt -- dealId/proposalUrl are shorthand for values from the enclosing step handler's input, not a standalone compilable file */}
|
|
130
134
|
|
|
131
135
|
```typescript
|
|
132
136
|
import { approval } from '@elevasis/sdk/worker'
|
|
@@ -141,7 +145,7 @@ const task = await approval.create({
|
|
|
141
145
|
})
|
|
142
146
|
```
|
|
143
147
|
|
|
144
|
-
> **SDK takeaway:** Use `approval.create()` to
|
|
148
|
+
> **SDK takeaway:** Use `approval.create()` to raise an approval request, and put the post-decision work in the resource each action targets. Provide rich `context` so reviewers have what they need to decide. See [Human-in-the-Loop Workflows](../human-in-the-loop.mdx) for the full path from workflow to checkpoint to queue resolution.
|
|
145
149
|
|
|
146
150
|
---
|
|
147
151
|
|
|
@@ -290,227 +290,105 @@ The SDK CLI wraps all execution endpoints. Use these commands instead of calling
|
|
|
290
290
|
|
|
291
291
|
## UI Execution
|
|
292
292
|
|
|
293
|
-
`@elevasis/ui` ships
|
|
293
|
+
`@elevasis/ui` ships components and hooks that let your custom React pages trigger workflow and agent executions without wiring up API calls manually. This section is for template users building interactive resource pages who want to add Run buttons, input forms, and execution result displays.
|
|
294
294
|
|
|
295
|
-
|
|
295
|
+
Two published pieces cover triggering: `useExecuteAsync` (the mutation) and `ExecuteWorkflowModal` (the modal chrome). You supply the input UI -- there is no built-in form renderer. `@elevasis/ui/features/operations` also publishes ready-made panels (`ExecutionPanel`, `WorkflowExecutionPanel`, `AgentExecutionPanel`) for when you want an execution history view rather than a trigger.
|
|
296
296
|
|
|
297
|
-
###
|
|
297
|
+
### `useExecuteAsync`
|
|
298
298
|
|
|
299
|
-
`
|
|
299
|
+
`useExecuteAsync()` is a TanStack Query mutation that POSTs to the execution engine and resolves to `{ executionId, status, resourceId }`.
|
|
300
300
|
|
|
301
301
|
```tsx
|
|
302
|
-
import {
|
|
303
|
-
import { Button } from '@mantine/core'
|
|
304
|
-
import { ResourceExecuteDialog } from '@elevasis/ui/features/operations'
|
|
305
|
-
import { useNavigate } from '@tanstack/react-router'
|
|
306
|
-
|
|
307
|
-
const resource = {
|
|
308
|
-
resourceId: 'qualify-lead-workflow',
|
|
309
|
-
resourceType: 'workflow' as const,
|
|
310
|
-
name: 'Qualify Lead',
|
|
311
|
-
formSchema: {
|
|
312
|
-
fields: [
|
|
313
|
-
{ name: 'email', label: 'Lead email', type: 'text', required: true },
|
|
314
|
-
{ name: 'company', label: 'Company', type: 'text', required: false },
|
|
315
|
-
],
|
|
316
|
-
},
|
|
317
|
-
}
|
|
318
|
-
|
|
319
|
-
export function QualifyLeadPage() {
|
|
320
|
-
const [opened, setOpened] = useState(false)
|
|
321
|
-
const navigate = useNavigate()
|
|
302
|
+
import { useExecuteAsync } from '@elevasis/ui/hooks'
|
|
322
303
|
|
|
323
|
-
|
|
324
|
-
<>
|
|
325
|
-
<Button onClick={() => setOpened(true)}>Run</Button>
|
|
304
|
+
const { mutateAsync, mutate, isPending, error, data, reset } = useExecuteAsync()
|
|
326
305
|
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
navigate({ to: '/logs/$executionId', params: { executionId } })
|
|
333
|
-
}
|
|
334
|
-
/>
|
|
335
|
-
</>
|
|
336
|
-
)
|
|
337
|
-
}
|
|
306
|
+
await mutateAsync({
|
|
307
|
+
resourceId: 'qualify-lead-workflow',
|
|
308
|
+
resourceType: 'workflow',
|
|
309
|
+
input: { email: 'lead@example.com' }
|
|
310
|
+
})
|
|
338
311
|
```
|
|
339
312
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
- A modal opens titled "Run workflow" with the resource ID displayed.
|
|
343
|
-
- The form renders one field per entry in `formSchema.fields`. Required fields show validation errors on submit.
|
|
344
|
-
- On submit, a loading overlay appears while the POST is in flight.
|
|
345
|
-
- On success, a teal confirmation card shows the execution ID. A "View execution" button calls `onViewExecution` with that ID.
|
|
346
|
-
- On error, a red alert shows the error message with a "Try again" option.
|
|
313
|
+
`ExecuteAsyncParams`:
|
|
347
314
|
|
|
348
|
-
|
|
315
|
+
| Field | Type | Notes |
|
|
316
|
+
| -------------- | -------------- | -------------------------------------------------------- |
|
|
317
|
+
| `resourceId` | `string` | Deployed resource ID |
|
|
318
|
+
| `resourceType` | `ResourceType` | `'workflow'` or `'agent'` |
|
|
319
|
+
| `input` | `unknown` | Passed through to the resource's input schema |
|
|
320
|
+
| `listId` | `string` | Optional; also attaches the execution to a lead-gen list |
|
|
349
321
|
|
|
350
|
-
|
|
322
|
+
On success it invalidates the executions list query keyed by organization plus `resourceId`, so any `useExecutions` query on the page refreshes automatically.
|
|
351
323
|
|
|
352
|
-
|
|
353
|
-
| --------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
|
|
354
|
-
| Convenience | `ResourceExecuteDialog` | One-tag Run button + modal + form. Parent only manages `opened` state. |
|
|
355
|
-
| Controlled form | `ResourceExecuteForm` | Custom modal chrome; parent owns the mutation and decides where to show results. |
|
|
356
|
-
| Low-level | `ExecuteWorkflowModal` + `useExecuteAsync` | Fully custom rendering, non-standard modal behavior, or composing execution into a larger flow. |
|
|
324
|
+
### `ExecuteWorkflowModal`
|
|
357
325
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
### Controlled Usage with `ResourceExecuteForm`
|
|
361
|
-
|
|
362
|
-
Use `ResourceExecuteForm` when you want to own the modal or display the result somewhere outside the dialog -- for example, rendering the execution ID inline on the page after submission.
|
|
363
|
-
|
|
364
|
-
`ResourceExecuteForm` accepts `onSubmit` and `isPending` from the parent. The parent calls `useExecuteAsync()` directly and passes `mutateAsync` as the submit handler.
|
|
326
|
+
`ExecuteWorkflowModal` is a Mantine Modal pre-wired with a loading overlay, a success card (execution ID plus a "View execution" button), and an error alert. Pass your input UI as `children`.
|
|
365
327
|
|
|
366
328
|
```tsx
|
|
367
329
|
import { useState } from 'react'
|
|
368
|
-
import {
|
|
369
|
-
import {
|
|
330
|
+
import { Button, TextInput } from '@mantine/core'
|
|
331
|
+
import { ExecuteWorkflowModal } from '@elevasis/ui/features/operations'
|
|
370
332
|
import { useExecuteAsync } from '@elevasis/ui/hooks'
|
|
333
|
+
import { useNavigate } from '@tanstack/react-router'
|
|
371
334
|
|
|
372
|
-
|
|
373
|
-
fields: [
|
|
374
|
-
{ name: 'topic', label: 'Topic', type: 'text', required: true },
|
|
375
|
-
],
|
|
376
|
-
}
|
|
377
|
-
|
|
378
|
-
export function CustomRunPanel() {
|
|
335
|
+
export function QualifyLeadPage() {
|
|
379
336
|
const [opened, setOpened] = useState(false)
|
|
380
|
-
const
|
|
381
|
-
|
|
382
|
-
const
|
|
383
|
-
await mutation.mutateAsync({
|
|
384
|
-
resourceId: 'research-agent',
|
|
385
|
-
resourceType: 'agent',
|
|
386
|
-
input,
|
|
387
|
-
})
|
|
388
|
-
}
|
|
337
|
+
const [email, setEmail] = useState('')
|
|
338
|
+
const navigate = useNavigate()
|
|
339
|
+
const { mutateAsync, isPending, error, data, reset } = useExecuteAsync()
|
|
389
340
|
|
|
390
341
|
return (
|
|
391
342
|
<>
|
|
392
|
-
<Button onClick={() => setOpened(true)}>Run
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
343
|
+
<Button onClick={() => setOpened(true)}>Run</Button>
|
|
344
|
+
|
|
345
|
+
<ExecuteWorkflowModal
|
|
346
|
+
opened={opened}
|
|
347
|
+
onClose={() => setOpened(false)}
|
|
348
|
+
resource={{ resourceId: 'qualify-lead-workflow', resourceType: 'workflow', name: 'Qualify Lead' }}
|
|
349
|
+
isPending={isPending}
|
|
350
|
+
error={error}
|
|
351
|
+
result={data ?? null}
|
|
352
|
+
onReset={reset}
|
|
353
|
+
onViewExecution={(executionId) => navigate({ to: '/logs/$executionId', params: { executionId } })}
|
|
354
|
+
>
|
|
355
|
+
<TextInput label="Lead email" value={email} onChange={(e) => setEmail(e.currentTarget.value)} />
|
|
356
|
+
<Button
|
|
357
|
+
mt="md"
|
|
358
|
+
loading={isPending}
|
|
359
|
+
onClick={() => mutateAsync({ resourceId: 'qualify-lead-workflow', resourceType: 'workflow', input: { email } })}
|
|
360
|
+
>
|
|
361
|
+
Run
|
|
362
|
+
</Button>
|
|
363
|
+
</ExecuteWorkflowModal>
|
|
407
364
|
</>
|
|
408
365
|
)
|
|
409
366
|
}
|
|
410
367
|
```
|
|
411
368
|
|
|
412
|
-
`
|
|
413
|
-
|
|
414
|
-
| Prop | Type | Default | Notes |
|
|
415
|
-
| ------------- | ------------------------------------ | -------- | ------------------------------------ |
|
|
416
|
-
| `formSchema` | `SerializedExecutionFormSchema` | required | Drives field rendering |
|
|
417
|
-
| `onSubmit` | `(input) => void | Promise<void>` | required | Called with mapped field values |
|
|
418
|
-
| `isPending` | `boolean` | `false` | Shows loading state on submit button |
|
|
419
|
-
| `disabled` | `boolean` | `false` | Disables all fields and button |
|
|
420
|
-
| `submitLabel` | `string` | `'Run'` | Button label when not pending |
|
|
421
|
-
|
|
422
|
-
### Low-Level: Hooks and `ExecuteWorkflowModal`
|
|
423
|
-
|
|
424
|
-
For complete rendering control, use `useExecuteAsync` and `ExecuteWorkflowModal` independently. `ExecuteWorkflowModal` is a Mantine Modal pre-wired with a loading overlay, a success card (execution ID + "View execution" button), and an error alert. You pass `children` for the input area.
|
|
425
|
-
|
|
426
|
-
```tsx
|
|
427
|
-
import { ExecuteWorkflowModal } from '@elevasis/ui/features/operations'
|
|
428
|
-
import { useExecuteAsync } from '@elevasis/ui/hooks'
|
|
369
|
+
`ExecuteWorkflowModalProps`:
|
|
429
370
|
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
>
|
|
442
|
-
{/* your custom form or content here */}
|
|
443
|
-
</ExecuteWorkflowModal>
|
|
444
|
-
```
|
|
371
|
+
| Prop | Type | Default | Notes |
|
|
372
|
+
| ----------------- | ------------------------------- | -------- | ---------------------------------------------------- |
|
|
373
|
+
| `opened` | `boolean` | required | Modal visibility |
|
|
374
|
+
| `onClose` | `() => void` | required | Ignored while `isPending` |
|
|
375
|
+
| `resource` | `ExecuteWorkflowModalResource` | required | `{ resourceId, resourceType, name? }` |
|
|
376
|
+
| `isPending` | `boolean` | `false` | Shows the loading overlay and locks dismissal |
|
|
377
|
+
| `error` | `Error | null` | -- | Renders the error alert |
|
|
378
|
+
| `result` | `ExecuteAsyncResult | null` | -- | Renders the success card |
|
|
379
|
+
| `onViewExecution` | `(executionId: string) => void` | -- | Adds the "View execution" button to the success card |
|
|
380
|
+
| `onReset` | `() => void` | -- | Backs the "Try again" action |
|
|
381
|
+
| `children` | `ReactNode` | -- | Your input UI |
|
|
445
382
|
|
|
446
383
|
The modal locks close interactions (click-outside, Escape, close button) while `isPending` is true, preventing accidental dismissal mid-execution.
|
|
447
384
|
|
|
448
|
-
Source: `packages/ui/src/features/operations/executions/ExecuteWorkflowModal.tsx`, `packages/ui/src/hooks/executions/useExecuteAsync.ts`
|
|
449
|
-
|
|
450
|
-
### Zod-Validated Execution with `useExecuteWorkflow`
|
|
451
|
-
|
|
452
|
-
`useExecuteWorkflow` wraps `useExecuteAsync` with a Zod parse step before the POST. Use it when you are constructing input programmatically (not from a form) and want to catch schema mismatches before they reach the API.
|
|
453
|
-
|
|
454
|
-
```tsx
|
|
455
|
-
import { z } from 'zod'
|
|
456
|
-
import { useExecuteWorkflow } from '@elevasis/ui/hooks'
|
|
457
|
-
|
|
458
|
-
const inputSchema = z.object({
|
|
459
|
-
email: z.string().email(),
|
|
460
|
-
score: z.number().min(0).max(100),
|
|
461
|
-
})
|
|
462
|
-
|
|
463
|
-
function useScoredExecution() {
|
|
464
|
-
return useExecuteWorkflow({ schema: inputSchema })
|
|
465
|
-
}
|
|
466
|
-
|
|
467
|
-
// In a component:
|
|
468
|
-
const { execute, isPending, data, error } = useScoredExecution()
|
|
469
|
-
|
|
470
|
-
await execute({
|
|
471
|
-
resourceId: 'score-lead-workflow',
|
|
472
|
-
resourceType: 'workflow',
|
|
473
|
-
input: { email: 'lead@example.com', score: 72 },
|
|
474
|
-
})
|
|
475
|
-
```
|
|
476
|
-
|
|
477
|
-
If `input` fails the Zod parse, `execute` throws synchronously with the message `"Invalid workflow input: ..."` before making any network request. The `mutation` object on the return value is the underlying `useExecuteAsync` mutation, giving you full TanStack Query state if needed.
|
|
478
|
-
|
|
479
|
-
Prefer `useExecuteWorkflow` over raw `useExecuteAsync` when:
|
|
480
|
-
|
|
481
|
-
- Input is assembled from multiple sources (not a single form submit).
|
|
482
|
-
- You want TypeScript inference on the input shape via `z.infer`.
|
|
483
|
-
- You want a clear validation error message rather than a 400 from the API.
|
|
484
|
-
|
|
485
|
-
Source: `packages/ui/src/hooks/executions/useExecuteWorkflow.ts`
|
|
486
|
-
|
|
487
|
-
### Input Forms
|
|
488
|
-
|
|
489
|
-
`ResourceExecuteDialog` and `ResourceExecuteForm` auto-render form fields from `formSchema.fields`. Each field is a `SerializedFormField` with at minimum `name`, `label`, and `type`.
|
|
490
|
-
|
|
491
|
-
Supported field types:
|
|
492
|
-
|
|
493
|
-
- `text` -- single-line text input
|
|
494
|
-
- `textarea` -- multi-line text input
|
|
495
|
-
- `number` -- numeric input
|
|
496
|
-
- `select` -- dropdown with `options` array
|
|
497
|
-
- `checkbox` -- boolean toggle; defaults to `false`
|
|
498
|
-
- `radio` -- radio group with `options` array
|
|
499
|
-
- `richtext` -- rich text editor
|
|
500
|
-
|
|
501
|
-
Required fields (`required: true`) are validated on submit. Custom field-to-input-key remapping is supported via `formSchema.fieldMappings` -- a `Record<string, string>` that renames field values before they are passed to `onSubmit`.
|
|
502
|
-
|
|
503
|
-
If `formSchema` is undefined, an empty object, or has `fields: []`, the form skips rendering fields entirely and shows "This workflow takes no input." with a single Run button.
|
|
504
|
-
|
|
505
385
|
### Error and Result Handling
|
|
506
386
|
|
|
507
|
-
Mutation state flows
|
|
387
|
+
Mutation state flows into the modal chrome automatically:
|
|
508
388
|
|
|
509
389
|
- **Success** -- a teal alert card displays the execution ID from `result.executionId`. If `onViewExecution` is provided, a "View execution" button calls it with the ID. This is the recommended way to deep-link to the Execution Logs page.
|
|
510
|
-
- **Error** -- a red alert displays `error.message`. A "Try again" button calls `onReset`, which clears the mutation state and re-shows the
|
|
511
|
-
- **Pending** -- a blur overlay covers the
|
|
512
|
-
|
|
513
|
-
`useExecuteAsync` also invalidates the executions list query on success (keyed by `organizationId` + `resourceId`), so any `useExecutions` query on the page refreshes automatically.
|
|
390
|
+
- **Error** -- a red alert displays `error.message`. A "Try again" button calls `onReset`, which clears the mutation state and re-shows the children.
|
|
391
|
+
- **Pending** -- a blur overlay covers the content area while the POST is in flight. The modal cannot be dismissed during this state.
|
|
514
392
|
|
|
515
393
|
---
|
|
516
394
|
|
|
@@ -248,6 +248,8 @@ Host apps still own TanStack route registration, topbar behavior, branding, auth
|
|
|
248
248
|
|
|
249
249
|
Manifest `systemId` values must match Organization Model System IDs. Sidebar placement is authored in the Organization Model navigation domain:
|
|
250
250
|
|
|
251
|
+
{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
|
|
252
|
+
|
|
251
253
|
```ts
|
|
252
254
|
systems: {
|
|
253
255
|
dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
|
|
@@ -8,7 +8,7 @@ description: "Auto-generated catalog of all published @elevasis/sdk subpath expo
|
|
|
8
8
|
|
|
9
9
|
| Import | Title | Group | Description |
|
|
10
10
|
| --- | --- | --- | --- |
|
|
11
|
-
| `@elevasis/sdk` | SDK | Getting Started |
|
|
12
|
-
| `@elevasis/sdk/worker` | Worker Runtime | Runtime |
|
|
13
|
-
| `@elevasis/sdk/test-utils` | Test Utils | Testing |
|
|
14
|
-
| `@elevasis/sdk/node` | Node Build Tooling | Tooling |
|
|
11
|
+
| `@elevasis/sdk` | SDK | Getting Started | |
|
|
12
|
+
| `@elevasis/sdk/worker` | Worker Runtime | Runtime | |
|
|
13
|
+
| `@elevasis/sdk/test-utils` | Test Utils | Testing | |
|
|
14
|
+
| `@elevasis/sdk/node` | Node Build Tooling | Tooling | |
|