@elevasis/sdk 1.15.0 → 1.15.1

package/reference/scaffold/recipes/extend-crm.md

@@ -58,7 +58,9 @@ Read the generated contracts before changing typed boundaries:
 
 `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 
-Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
+Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
+
+Deal list and detail responses include a server-derived `priority` object. Use `deal.priority.bucketKey`, `rank`, `label`, `reason`, `latestActivityAt`, and `nextActionAt` when composing custom deal workspaces or workflow-side follow-up logic instead of re-deriving priority from `updated_at`.
 
 ## 1. Extend CRM Navigation or Sidebar
 
@@ -192,13 +194,15 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
       outputSchema,
       next: null,
       handler: async (input) => {
-        const deals = await crm.listDeals({ stage: input.stage })
-
-        for (const deal of deals) {
-          await crm.createDealTask({
-            dealId: deal.id,
-            title: 'Follow up',
-            kind: 'email'
+        const deals = await crm.listDeals({ stage: input.stage })
+
+        for (const deal of deals) {
+          if (!['follow_up_due', 'stale'].includes(deal.priority.bucketKey)) continue
+
+          await crm.createDealTask({
+            dealId: deal.id,
+            title: 'Follow up',
+            kind: 'email'
           })
           await crm.recordActivity({
             dealId: deal.id,

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -34,8 +34,8 @@ Lead gen is a layered platform surface, not one component:
 | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
 | Change lead-gen feature availability, labels, quick access, or pipeline semantics | `core/config/organization-model.ts` plus `core/config/organization-model.examples.ts`                             | Treat this as Organization OS work. Use the project's configure ceremony if available.                          |
 | Add lead-gen sidebar nav or a lead-gen route                                      | `@elevasis/ui/features/lead-gen` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`          | Prefer manifest/sidebar composition. Do not fork shared source first.                                           |
-| Wrap a shared lead-gen page with project chrome                                   | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage` | Keep route files thin and put project-specific behavior in local feature modules.                               |
-| Build a custom campaign/list workspace                                            | `useLists`, `useList`, `useListMembers`, `useArtifacts`, `useTransitionListMember` from `@elevasis/ui/hooks`      | Use hooks for platform data and compose your own UI.                                                            |
+| Wrap a shared lead-gen page with project chrome                                   | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage` | Keep route files thin and put project-specific behavior in local feature modules.                               |
+| Build a custom campaign/list workspace                                            | `ListBuilderPage`, `useLists`, `useList`, `useListProgress`, `useListExecutions`, `useWorkflowExecution`, `useExecutionSSE` from `@elevasis/ui` | Use the shared builder when possible; otherwise compose hooks for platform data and workflow execution.          |
 | Render artifacts or list-member detail                                            | `LeadGenListDetailPage`, `useArtifacts`, `useCreateArtifact`, `useListMember`                                     | Artifacts are a substrate primitive. Keep vertical-specific rendering local until there are repeated use cases. |
 | Read or mutate lead-gen data inside a workflow                                    | `acqDb` or `list` from `@elevasis/sdk/worker`                                                                     | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.         |
 | Add a new persisted lead-gen field, artifact kind, or transition API              | Platform/API migration work, not just scaffold work                                                               | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.              |
@@ -45,13 +45,15 @@ Lead gen is a layered platform surface, not one component:
 | Surface                                                                                                                                                      | Import from                      | Use for                                                              |
 | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | -------------------------------------------------------------------- |
 | `leadGenManifest`, `LEAD_GEN_ITEMS`, `LeadGenSidebar`, `LeadGenSidebarTop`, `LeadGenSidebarMiddle`                                                           | `@elevasis/ui/features/lead-gen` | Feature registration and sidebar composition                         |
-| `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                                            | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                       |
+| `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                          | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                       |
+| `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, MVP workflow form components                                           | `@elevasis/ui/features/lead-gen` | List Builder workflow registry, run modal inputs, and project-owned action wiring |
 | `LeadGenRouteShell`, `CompanyDetailModal`, `ContactDetailModal`, `LIST_TEMPLATE_OPTIONS`, `buildListConfig`                                                  | `@elevasis/ui/features/lead-gen` | Route shell helpers, detail modals, and list creation config helpers |
 | `useLists`, `useList`, `useListsTelemetry`, `useListProgress`, `useListExecutions`, `useCreateList`, `useUpdateList`, `useUpdateListConfig`, `useDeleteList` | `@elevasis/ui/hooks`             | Headless list and telemetry data access                              |
+| `useWorkflowExecution`, `useExecutionSSE`, `useAddCompaniesToList`, `useRemoveCompaniesFromList`, `useAddContactsToList`                                    | `@elevasis/ui/hooks`             | List Builder workflow triggering, live execution tailing, and list membership mutations |
 | `useCompanies`, `useCompany`, `useContacts`, `useContact`                                                                                                    | `@elevasis/ui/hooks`             | Acquisition company/contact data access                              |
 | `useArtifacts`, `useCreateArtifact`, `useListMembers`, `useListMember`                                                                                       | `@elevasis/ui/hooks`             | Lead-gen substrate data access                                       |
 | `useTransitionList`, `useTransitionListMember`, `useTransitionListCompany`, `useDeriveActions`                                                               | `@elevasis/ui/hooks`             | Stateful transition mutations and contextual action derivation       |
-| `ElevasisUIProvider`, `ElevasisCoreProvider`, `useElevasisServices`                                                                                          | `@elevasis/ui/provider`          | Provider setup, API access, and organization context                 |
+| `ElevasisUIProvider`, `ElevasisCoreProvider`, `useElevasisServices`                                                                                          | `@elevasis/ui/provider`          | Provider setup, API access, organization context, and `listActions` registry injection |
 | `acqDb`, `list`                                                                                                                                              | `@elevasis/sdk/worker`           | Workflow-side acquisition and list-scoped platform adapters          |
 
 Read the generated contracts before changing typed boundaries:
@@ -135,6 +137,78 @@ function ListDetailRoute() {
 
 Use the same wrapping pattern for `LeadGenOverviewPage`, `LeadGenCompaniesPage`, and `LeadGenContactsPage`.
 
+For the real-time List Builder workspace, add a thin route that passes the route param into `ListBuilderPage`:
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { ListBuilderPage } from '@elevasis/ui/features/lead-gen'
+
+export const Route = createFileRoute('/lead-gen/list-builder/$listId')({
+  component: ListBuilderRoute
+})
+
+function ListBuilderRoute() {
+  const { listId } = Route.useParams()
+  return <ListBuilderPage listId={listId} />
+}
+```
+
+Register project workflow actions at the provider boundary. The shared UI owns the contract; each project owns workflow ids and form choices:
+
+```tsx
+import {
+  CompanyCleanupForm,
+  EmailDiscoveryForm,
+  EmailVerificationForm,
+  WebsiteExtractForm,
+  type ListBuilderRegistry
+} from '@elevasis/ui/features/lead-gen'
+import { ElevasisUIProvider } from '@elevasis/ui/provider'
+
+const listActions: ListBuilderRegistry = [
+  {
+    resourceId: 'lgn-04-email-discovery-workflow',
+    label: 'Email Discovery',
+    description: 'Discover contact email addresses for companies in the list.',
+    category: 'enrich',
+    stagesAffected: ['discovered'],
+    inputForm: EmailDiscoveryForm
+  },
+  {
+    resourceId: 'lgn-05-email-verification-workflow',
+    label: 'Email Verification',
+    description: 'Verify deliverability for contact emails in the list.',
+    category: 'enrich',
+    stagesAffected: ['verified'],
+    inputForm: EmailVerificationForm
+  },
+  {
+    resourceId: 'lgn-02-website-extract-workflow',
+    label: 'Website Extract',
+    description: 'Extract website intelligence for companies in the list.',
+    category: 'scrape',
+    stagesAffected: ['extracted'],
+    inputForm: WebsiteExtractForm
+  },
+  {
+    resourceId: 'lgn-company-cleanup-workflow',
+    label: 'Company Cleanup',
+    description: 'Normalize and clean company records for the list.',
+    category: 'utility',
+    stagesAffected: ['populated'],
+    inputForm: CompanyCleanupForm
+  }
+]
+
+export function App() {
+  return (
+    <ElevasisUIProvider listActions={listActions} {...providerProps}>
+      {children}
+    </ElevasisUIProvider>
+  )
+}
+```
+
 ## 3. Build a Custom Campaign Workspace
 
 When the project needs custom layout or vertical-specific rendering, use the hooks directly: