@elevasis/sdk 1.24.0 → 1.25.0

package/reference/scaffold/recipes/customize-crm-actions.md

@@ -23,14 +23,14 @@ Use this recipe when a user asks for work like:
 
 ## How Platform Action Dispatch Works
 
-Every default action in `DEFAULT_CRM_ACTIONS` maps to a deployed workflow via its `workflowId` field. When the shared UI calls `POST /deals/:dealId/actions/:actionKey`, the platform:
+Every action in the CRM action catalog maps to a deployed workflow via its `workflowId` field. When the shared UI calls `POST /deals/:dealId/actions/:actionKey`, the platform:
 
 1. Validates `isAvailableFor(deal)` server-side (security gate -- cannot be skipped).
 2. Resolves `actionDef.workflowId` to a deployed resource.
 3. Dispatches through `SingleExecutionCoordinator` -- same execution engine as every other workflow.
 4. Returns the refetched deal.
 
-External projects override an action's behavior by deploying a workflow with the same `workflowId` as the default. The resource registry picks the project-owned workflow over the platform default. The `isAvailableFor` predicate is not overridable in V1 -- it stays in `@core` `DEFAULT_CRM_ACTIONS`. Override what the action does, not when the button shows.
+External projects override an action's behavior by deploying a workflow with the same `workflowId` as the action entry. The resource registry picks the project-owned workflow over the platform default. The `isAvailableFor` predicate comes from the caller-supplied action catalog; override what the action does and keep button availability aligned with the server-side gate.
 
 ## ActionDef Shape
 
@@ -120,7 +120,7 @@ export const moveToProposalWorkflow: WorkflowDefinition = {
 }
 ```
 
-To add side effects (create a task, send a Slack message, log a deal activity), extend the handler before the `return`. The OM descriptor ID must match the action's `workflowId` in `DEFAULT_CRM_ACTIONS` from `@elevasis/sdk` exactly.
+To add side effects (create a task, send a Slack message, log a deal activity), extend the handler before the `return`. The OM descriptor ID must match the action entry's `workflowId` exactly.
 
 Register the workflow in the operations manifest:
 
@@ -144,23 +144,23 @@ pnpm exec elevasis-sdk deploy
 
 To hide, reorder, or relabel buttons in the shared deal UI, create a local action config module:
 
-```ts
-// ui/src/config/crm-actions.ts
-import { DEFAULT_CRM_ACTIONS, type ActionDef } from '@elevasis/sdk'
-
-export const crmActions: ActionDef[] = [
-  ...DEFAULT_CRM_ACTIONS.filter((action) => action.key !== 'move_to_closed_lost')
-]
-```
+```ts
+// ui/src/config/crm-actions.ts
+import type { ActionDef } from '@elevasis/sdk'
+import { platformCrmActions } from './platform-crm-actions'
+
+export const crmActions: ActionDef[] = platformCrmActions.filter((action) => action.key !== 'move_to_closed_lost')
+```
 
 To add a new action entry alongside the defaults (note: brand-new keys are not server-dispatched until the platform knows their `workflowId`):
 
-```ts
-// ui/src/config/crm-actions.ts
-import { DEFAULT_CRM_ACTIONS, type ActionDef } from '@elevasis/sdk'
-
-export const crmActions: ActionDef[] = [
-  ...DEFAULT_CRM_ACTIONS,
+```ts
+// ui/src/config/crm-actions.ts
+import type { ActionDef } from '@elevasis/sdk'
+import { platformCrmActions } from './platform-crm-actions'
+
+export const crmActions: ActionDef[] = [
+  ...platformCrmActions,
   {
     key: 'send_quote',
     label: 'Send Quote',
@@ -357,20 +357,21 @@ When you own the full page, use the primitives directly:
 - `useExecuteAction({ dealId })` dispatches platform-known action keys.
 - Project-owned workflow buttons call `/execute` or `/execute-async` directly when they are outside the server-dispatched action set.
 
-```tsx
-import { DEFAULT_CRM_ACTIONS, deriveActions } from '@elevasis/sdk'
-import { Group, Stack } from '@mantine/core'
-import { useMemo } from 'react'
-import { useDealDetail, useExecuteAction } from '@elevasis/ui/hooks'
-import { SendQuoteButton } from './SendQuoteButton'
+```tsx
+import { deriveActions } from '@elevasis/sdk'
+import { Group, Stack } from '@mantine/core'
+import { useMemo } from 'react'
+import { useDealDetail, useExecuteAction } from '@elevasis/ui/hooks'
+import { crmActions } from '../config/crm-actions'
+import { SendQuoteButton } from './SendQuoteButton'
 
 export function CustomDealPage({ dealId }: { dealId: string }) {
   const { data: deal } = useDealDetail(dealId)
-  const executeAction = useExecuteAction({ dealId })
-
-  const platformActions = useMemo(() => {
-    return deal ? deriveActions(deal, DEFAULT_CRM_ACTIONS) : []
-  }, [deal])
+  const executeAction = useExecuteAction({ dealId })
+
+  const platformActions = useMemo(() => {
+    return deal ? deriveActions(deal, crmActions) : []
+  }, [deal])
 
   if (!deal) return null
 
@@ -395,24 +396,22 @@ export function CustomDealPage({ dealId }: { dealId: string }) {
 
 ## CRM State-Key Source of Truth
 
-`CRM_PIPELINE_DEFINITION` in `packages/core/src/organization-model/domains/sales.ts` is the single canonical source for CRM `state_key` values. It exports a `StatefulPipelineDefinition` that enumerates every valid state per stage (e.g. `interested` → `discovery_replied`, `discovery_link_sent`, `discovery_nudging`, etc.). Named per-state constants (`CRM_DISCOVERY_REPLIED_STATE`, `CRM_DISCOVERY_LINK_SENT_STATE`, and siblings) are also exported for use in conditional logic.
-
-Import via `@repo/core/organization-model`:
-
-```ts
-import {
-  CRM_PIPELINE_DEFINITION,
-  CRM_DISCOVERY_REPLIED_STATE,
-  getValidStatesForStage
-} from '@repo/core/organization-model'
-
-const validStates = getValidStatesForStage(CRM_PIPELINE_DEFINITION, 'interested')
-// [{ stateKey: 'discovery_replied', label: '...' }, ...]
-```
-
-Workflows that write `state_key` should import from this definition rather than hardcoding string literals. This keeps the vocabulary in one place and lets the API validate against the allowed set for a deal's current stage.
-
-**Current gap:** `@elevasis/core` v0.13.0 does not yet expose the `organization-model` subpath. Until a new release ships that export, hardcoded strings in `packages/elevasis-operations/...` are tracked as follow-up. Document usages with a `// TODO: replace with CRM_PIPELINE_DEFINITION import once @elevasis/core exposes organization-model` comment so they are easy to find.
+CRM `stage_key` and `state_key` values are tenant/runtime data. In the Elevasis workspace, the canonical CRM pipeline definition lives in `@repo/elevasis-core/organization-model` and is authored into the `sales.crm:catalog/crm.pipeline` ontology catalog on the canonical organization model. Published `@elevasis/core` keeps only generic `StatefulPipelineDefinition` types/helpers and transport schemas.
+
+Within the Elevasis monorepo, import runtime CRM definitions from `@repo/elevasis-core/organization-model`:
+
+```ts
+import {
+  CRM_PIPELINE_DEFINITION,
+  CRM_DISCOVERY_REPLIED_STATE,
+  getValidStatesForStage
+} from '@repo/elevasis-core/organization-model'
+
+const validStates = getValidStatesForStage(CRM_PIPELINE_DEFINITION, 'interested')
+// [{ stateKey: 'discovery_replied', label: '...' }, ...]
+```
+
+Template-derived projects should define their own CRM catalog/action config in project code rather than importing Elevasis runtime constants from published core.
 
 ## Activity Log Conventions