@elevasis/sdk 1.2.0 → 1.4.0

package/reference/packages/ui/src/auth/README.md

@@ -0,0 +1,18 @@
+# Auth
+
+The auth surface is the published authentication entry point for UI shells.
+
+## Exports
+
+- `AuthProvider`
+- `useAuthContext`
+- `useStableAccessToken`
+- `useSessionCheck`
+- `ProtectedRoute`
+- `AdminGuard`
+
+## Use When
+
+- You need auth state, access tokens, or session lifecycle checks.
+- You need route-level guards for protected or admin-only UI.
+

package/reference/packages/ui/src/components/README.md

@@ -0,0 +1,24 @@
+# Components
+
+This barrel groups the shared visual and domain UI surfaces that remain part of the published component layer.
+
+## What It Covers
+
+- Acquisition and CRM UI primitives
+- Navigation, breadcrumbs, tables, forms, modals, and display components
+- Charts, monitoring widgets, notifications, and error states
+- Layout shells, backgrounds, and sidebar primitives
+- Typeform, rich text, content, and resource-definition helpers
+- Operations UI surfaces that are still shared at the component layer
+
+## Related Subpaths
+
+- `./components/navigation`
+- `./components/chat`
+- `./layout`
+- `./charts`
+
+## Notes
+
+- The component layer is broad by design, but feature-oriented application shells should still prefer `./features/*` when a dedicated feature surface exists.
+

package/reference/packages/ui/src/execution/README.md

@@ -0,0 +1,16 @@
+# Execution
+
+The execution surface contains headless helpers for execution timelines, workflow layouts, and execution-specific data shaping.
+
+## Exports
+
+- Hooks under `./hooks`
+- Utilities under `./utils`
+- Execution types under `./types`
+- Shared execution constants
+
+## Use When
+
+- You need execution timeline or workflow graph helpers without pulling in visual shells.
+- You need shared execution math or formatting utilities.
+

package/reference/packages/ui/src/features/README.md

@@ -0,0 +1,28 @@
+# Features
+
+Feature subpaths package complete shell-level UI flows for downstream apps.
+
+## Published Feature Surfaces
+
+- `./features/auth`
+- `./features/crm`
+- `./features/dashboard`
+- `./features/delivery`
+- `./features/lead-gen`
+- `./features/operations`
+- `./features/monitoring`
+- `./features/seo`
+- `./features/settings`
+
+## What They Contain
+
+- Route shells and page-level components
+- Sidebars and feature-specific navigation
+- Feature manifests for registry consumers
+- Feature-specific hooks and shared constants
+
+## Notes
+
+- These surfaces are meant for app composition, not for low-level design-system primitives.
+- Some feature exports are also re-exported through `./components` for convenience in legacy or mixed consumers.
+

package/reference/packages/ui/src/graph/README.md

@@ -0,0 +1,16 @@
+# Graph
+
+The graph surface is headless. It provides hooks, types, constants, and utilities for ReactFlow-based graph behavior.
+
+## Exports
+
+- Graph constants
+- Graph types
+- Graph hooks
+- Graph utilities
+
+## Notes
+
+- Visual graph components moved out of this package surface.
+- Use this subpath when you need graph behavior without the visual shell.
+

package/reference/packages/ui/src/hooks/README.md

@@ -0,0 +1,24 @@
+# Hooks
+
+The hooks barrel is the published headless hook surface for the UI package.
+
+## Grouped Areas
+
+- Execution and workflow hooks
+- Scheduling hooks
+- Monitoring, observability, and notification hooks
+- Session and SSE hooks
+- Operations hooks, including command-view and knowledge-base helpers
+- Feature access, table state, and service helpers
+- Acquisition and delivery hooks
+
+## Published Subpaths
+
+- `./hooks`
+- `./hooks/delivery`
+- `./hooks/operations/command-view/utils/transformCommandViewData`
+
+## Notes
+
+- This barrel is intentionally headless. It should not pull in the visual component layer.
+

package/reference/packages/ui/src/initialization/README.md

@@ -0,0 +1,19 @@
+# Initialization
+
+The initialization surface coordinates org-aware app startup.
+
+## Exports
+
+- `InitializationProvider`
+- `useInitialization`
+- `InitializationContext`
+- `createUseAppInitialization`
+- `InitializationError`
+- `AppInitializationState`
+- `SupabaseUserProfile` type re-export
+
+## Use When
+
+- You need zero-config app bootstrap inside an organization-aware provider tree.
+- You still need the deprecated factory pattern for older consumers.
+

package/reference/packages/ui/src/organization/README.md

@@ -0,0 +1,18 @@
+# Organization
+
+The organization surface manages multi-tenancy state and the related UI controls.
+
+## Exports
+
+- `OrganizationProvider`
+- `OrganizationContext`
+- `useOrganization`
+- `OrganizationSwitcher`
+- Store types and the legacy slice creator
+- Deprecated hook factories for older consumers
+
+## Notes
+
+- Prefer the provider and context exports for new code.
+- Legacy Zustand-based helpers remain exported for migration compatibility.
+

package/reference/packages/ui/src/profile/README.md

@@ -0,0 +1,19 @@
+# Profile
+
+The profile surface manages the user profile context and profile-backed helpers.
+
+## Exports
+
+- `ProfileProvider`
+- `useProfile`
+- `ProfileContextValue`
+- `useUserProfile`
+- `UseUserProfileReturn`
+- `UserProfileService`
+- `SupabaseUserProfile` type re-export
+
+## Use When
+
+- You need a shared user profile context.
+- You need a standalone profile service or hook for sync and access.
+

package/reference/packages/ui/src/provider/README.md

@@ -0,0 +1,31 @@
+# Provider
+
+The provider surface composes the shared Elevasis service, feature, appearance, notification, and UI providers.
+
+## Exports
+
+- `ElevasisCoreProvider`
+- `ElevasisFeaturesProvider`
+- `useElevasisFeatures`
+- `useOptionalElevasisFeatures`
+- `FeatureShell`
+- `AppearanceProvider`
+- `useAppearance`
+- `ElevasisServiceProvider`
+- `useElevasisServices`
+- `NotificationProvider`
+- `useNotificationAdapter`
+- `ElevasisUIProvider`
+- Related provider and service types
+
+## Related Published Subpaths
+
+- `./provider`
+- `./provider/ui`
+- `./provider/ElevasisServiceContext`
+
+## Notes
+
+- `published.ts` is the external consumer surface.
+- `ElevasisUIProvider` is the Mantine-facing visual layer; `ElevasisCoreProvider` and `ElevasisFeaturesProvider` handle the platform shell.
+

package/reference/packages/ui/src/router/README.md

@@ -0,0 +1,18 @@
+# Router
+
+The router surface provides the shared TanStack Router bridge and router context helpers.
+
+## Exports
+
+- `RouterProvider`
+- `useRouterContext`
+- `RouterAdapter`
+- `LinkProps`
+- `TanStackRouterBridge`
+- `ScrollToTop`
+
+## Use When
+
+- You need the shared routing abstraction for Elevasis apps.
+- You need a small adapter layer around TanStack Router in a consuming app.
+

package/reference/packages/ui/src/sse/README.md

@@ -0,0 +1,13 @@
+# SSE
+
+The SSE surface provides connection management and token-refresh helpers for server-sent events.
+
+## Exports
+
+- `SSEConnectionManager`
+- `fetchEventSourceWithTokenRefresh`
+
+## Use When
+
+- You need a shared SSE client with auth-aware reconnect behavior.
+

package/reference/packages/ui/src/theme/README.md

@@ -0,0 +1,23 @@
+# Theme
+
+The theme surface provides the preset system, CSS variable bridge, and Mantine theme integration.
+
+## Exports
+
+- `getPreset`
+- `generateShades`
+- `presets`
+- Theme preset types
+- `createCssVariablesResolver`
+- `TOKEN_VAR_MAP`
+- `mantineThemeOverride`
+- `componentThemes`
+- `PresetsProvider`
+- `usePresetsContext`
+- `useAvailablePresets`
+
+## Use When
+
+- You need to build or customize the Elevasis visual theme.
+- You need access to the shared preset registry or CSS variable mapping.
+

package/reference/packages/ui/src/types/README.md

@@ -0,0 +1,16 @@
+# Types
+
+The types surface re-exports the shared platform types that UI consumers need without a direct `@repo/core` dependency.
+
+## Exports
+
+- Execution and resource types
+- Command queue and scheduling types
+- Monitoring, observability, and notification types
+- Session, feature-access, and webhook types
+- Multi-tenancy, deployment, and CRM acquisition types
+
+## Notes
+
+- This is a type-only bridge. It should stay aligned with the current platform contracts.
+

package/reference/packages/ui/src/utils/README.md

@@ -0,0 +1,18 @@
+# Utils
+
+The utils surface groups shared date, formatting, validation, error, and resource helper functions.
+
+## Exports
+
+- Date formatting helpers
+- Relative time helpers
+- Email validation
+- Error helpers
+- Resource icon helpers
+- Shared constants
+- Warning suppression helpers
+
+## Use When
+
+- You need lightweight shared helpers that do not belong in a feature barrel.
+

package/reference/packages/ui/src/zustand/README.md

@@ -0,0 +1,18 @@
+# Zustand
+
+The Zustand surface exposes the shared slice creators used by the UI package.
+
+## Exports
+
+- `createSSESlice`
+- `resetSSEState`
+- `createThemeSlice`
+- `resetThemeState`
+- `createTimeRangeSlice`
+- `resetTimeRangeState`
+- Slice state and configuration types
+
+## Use When
+
+- You need the shared state slices used by the UI package internals or a compatible consumer.
+

package/reference/platform-tools/adapters-platform.mdx

@@ -1,7 +1,7 @@
 ---
 title: Platform Adapters
-description: Type-safe singleton adapters for built-in platform services -- scheduler, storage, LLM, PDF, approval, notifications, acqDb, execution, and email -- no credentials required
-loadWhen: "Using platform service adapters (scheduler, storage, llm, pdf, approval, acqDb, notifications, execution, email)"
+description: Type-safe singleton adapters for built-in platform services -- scheduler, storage, LLM, PDF, approval, notifications, acqDb, list, execution, and email -- no credentials required
+loadWhen: "Using platform service adapters (scheduler, storage, llm, pdf, approval, notifications, acqDb, list, execution, email)"
 ---
 
 Platform adapters are singleton objects imported directly from `@elevasis/sdk/worker`. They require no credential argument because the platform injects context server-side. For integration adapters (Attio, Stripe, etc.), see [Integration Adapters](adapters-integration.mdx).
@@ -9,7 +9,7 @@ Platform adapters are singleton objects imported directly from `@elevasis/sdk/wo
 ```typescript
 import {
   acqDb, scheduler, storage, pdf, approval,
-  notifications, llm, execution, email,
+  notifications, llm, list, execution, email,
 } from '@elevasis/sdk/worker'
 ```
 
@@ -19,13 +19,14 @@ import {
 
 | Import          | Methods | Purpose                              |
 | --------------- | ------- | ------------------------------------ |
-| `acqDb`         | 35      | Acquisition database CRUD and sync   |
+| `acqDb`         | 49      | Acquisition database CRUD and sync   |
 | `scheduler`     | 9       | Task schedule management             |
 | `storage`       | 5       | File upload, download, signed URLs   |
 | `pdf`           | 2       | PDF rendering to storage or buffer   |
 | `approval`      | 2       | Human-in-the-loop approval gates     |
 | `notifications` | 1       | In-app team notifications            |
 | `llm`           | 1       | LLM inference with structured output |
+| `list`          | 4       | List-scoped execution and stage ops  |
 | `execution`     | 1       | Trigger nested child executions      |
 | `email`         | 1       | Send email to org members            |
 
@@ -287,7 +288,7 @@ await notifications.create({
 
 ## AcqDb Adapter
 
-Singleton -- 35 methods for acquisition database management (lists, companies, contacts, deals, deal-sync). `organizationId` is injected server-side -- never pass it.
+Singleton -- 41 methods for acquisition database management (lists, companies, contacts, deals, deal-sync, enrichment, social monitoring). `organizationId` is injected server-side -- never pass it.
 
 ```typescript
 import { acqDb } from '@elevasis/sdk/worker'
@@ -297,12 +298,13 @@ import { acqDb } from '@elevasis/sdk/worker'
 
 **List operations:**
 
-| Method       | Params                                       | Returns     |
-| ------------ | -------------------------------------------- | ----------- |
-| `listLists`  | none                                         | `AcqList[]` |
-| `createList` | `Omit<CreateListParams, 'organizationId'>` | `AcqList`   |
-| `updateList` | `{ id } & UpdateListParams`                  | `AcqList`   |
-| `deleteList` | `{ id }`                                     | `void`      |
+| Method              | Params                                              | Returns                   |
+| ------------------- | --------------------------------------------------- | ------------------------- |
+| `listLists`         | none                                                | `AcqList[]`               |
+| `createList`        | `Omit<CreateListParams, 'organizationId'>`        | `AcqList`                 |
+| `updateList`        | `{ id } & UpdateListParams`                         | `AcqList`                 |
+| `deleteList`        | `{ id }`                                            | `void`                    |
+| `addContactsToList` | `Omit<AddContactsToListParams, 'organizationId'>` | `AddContactsToListResult` |
 
 **Company operations:**
 
@@ -317,16 +319,18 @@ import { acqDb } from '@elevasis/sdk/worker'
 
 **Contact operations:**
 
-| Method               | Params                                          | Returns                         |
-| -------------------- | ----------------------------------------------- | ------------------------------- |
-| `createContact`      | `Omit<CreateContactParams, 'organizationId'>` | `AcqContact`                    |
-| `upsertContact`      | `Omit<UpsertContactParams, 'organizationId'>` | `AcqContact`                    |
-| `updateContact`      | `{ id } & UpdateContactParams`                  | `AcqContact`                    |
-| `getContact`         | `{ id }`                                        | `AcqContact | null`            |
-| `getContactByEmail`  | `{ email }`                                     | `AcqContact | null`            |
-| `listContacts`       | `{ filters?, pagination? }`                     | `PaginatedResult<AcqContact>` |
-| `deleteContact`      | `{ id }`                                        | `void`                          |
-| `bulkImportContacts` | `Omit<BulkImportParams, 'organizationId'>`    | `BulkImportResult`              |
+| Method                        | Params                                                | Returns                         |
+| ----------------------------- | ----------------------------------------------------- | ------------------------------- |
+| `createContact`               | `Omit<CreateContactParams, 'organizationId'>`       | `AcqContact`                    |
+| `upsertContact`               | `Omit<UpsertContactParams, 'organizationId'>`       | `AcqContact`                    |
+| `updateContact`               | `{ id } & UpdateContactParams`                        | `AcqContact`                    |
+| `getContact`                  | `{ id }`                                              | `AcqContact | null`            |
+| `getContactByEmail`           | `{ email }`                                           | `AcqContact | null`            |
+| `listContacts`                | `{ filters?, pagination? }`                           | `PaginatedResult<AcqContact>` |
+| `deleteContact`               | `{ id }`                                              | `void`                          |
+| `bulkImportContacts`          | `Omit<BulkImportParams, 'organizationId'>`          | `BulkImportResult`              |
+| `bulkImportCompanies`         | `Omit<BulkImportCompaniesParams, 'organizationId'>` | `BulkImportCompaniesResult`     |
+| `deactivateContactsByCompany` | `{ companyId }`                                       | `{ deactivated: number }`       |
 
 **Deal operations:**
 
@@ -340,20 +344,34 @@ import { acqDb } from '@elevasis/sdk/worker'
 
 **Deal-sync operations:**
 
-| Method                          | Params                                                  | Returns                               |
-| ------------------------------- | ------------------------------------------------------- | ------------------------------------- |
-| `updateDiscoveryData`           | `Omit<UpdateDiscoveryDataParams, 'organizationId'>`   | `void`                                |
-| `updateProposalData`            | `Omit<UpdateProposalDataParams, 'organizationId'>`    | `void`                                |
-| `markProposalSent`              | `Omit<MarkProposalSentParams, 'organizationId'>`      | `void`                                |
-| `markProposalReviewed`          | `Omit<MarkProposalReviewedParams, 'organizationId'>`  | `void`                                |
-| `updateCloseLostReason`         | `Omit<UpdateCloseLostReasonParams, 'organizationId'>` | `void`                                |
-| `updateFees`                    | `Omit<UpdateFeesParams, 'organizationId'>`            | `void`                                |
-| `syncDealStage`                 | `Omit<SyncDealStageParams, 'organizationId'>`         | `void`                                |
-| `setContactNurture`             | `Omit<SetContactNurtureParams, 'organizationId'>`     | `void`                                |
-| `cancelSchedulesAndHitlByEmail` | `Omit<..., 'organizationId'>`                         | `{ schedulesCancelled, hitlDeleted }` |
-| `cancelHitlByDealId`            | `Omit<..., 'organizationId'>`                         | `{ hitlDeleted }`                     |
-| `clearDealFields`               | `Omit<ClearDealFieldsParams, 'organizationId'>`       | `void`                                |
-| `deleteDeal`                    | `Omit<DeleteDealParams, 'organizationId'>`            | `void`                                |
+| Method                          | Params                                                      | Returns                               |
+| ------------------------------- | ----------------------------------------------------------- | ------------------------------------- |
+| `updateDiscoveryData`           | `Omit<UpdateDiscoveryDataParams, 'organizationId'>`       | `void`                                |
+| `updateProposalData`            | `Omit<UpdateProposalDataParams, 'organizationId'>`        | `void`                                |
+| `markProposalSent`              | `Omit<MarkProposalSentParams, 'organizationId'>`          | `void`                                |
+| `markProposalReviewed`          | `Omit<MarkProposalReviewedParams, 'organizationId'>`      | `void`                                |
+| `updateCloseLostReason`         | `Omit<UpdateCloseLostReasonParams, 'organizationId'>`     | `void`                                |
+| `updateFees`                    | `Omit<UpdateFeesParams, 'organizationId'>`                | `void`                                |
+| `syncDealStage`                 | `Omit<SyncDealStageParams, 'organizationId'>`             | `void`                                |
+| `setContactNurture`             | `Omit<SetContactNurtureParams, 'organizationId'>`         | `void`                                |
+| `cancelSchedulesAndHitlByEmail` | `Omit<..., 'organizationId'>`                             | `{ schedulesCancelled, hitlDeleted }` |
+| `cancelHitlByDealId`            | `Omit<..., 'organizationId'>`                             | `{ hitlDeleted }`                     |
+| `clearDealFields`               | `Omit<ClearDealFieldsParams, 'organizationId'>`           | `void`                                |
+| `deleteDeal`                    | `Omit<DeleteDealParams, 'organizationId'>`                | `void`                                |
+| `recordReply`                   | `{ contactEmail, replyText, replySubject?, campaignName? }` | `void`                                |
+| `recordDealActivity`            | `{ attioDealId?, contactEmail?, type, ... }`                | `void`                                |
+
+**Enrichment operations:**
+
+| Method                | Params                                                   | Returns |
+| --------------------- | -------------------------------------------------------- | ------- |
+| `mergeEnrichmentData` | `{ id, table: 'acq_companies' | 'acq_contacts', data }` | `void`  |
+
+**Social monitoring operations:**
+
+| Method              | Params                                                          | Returns                   |
+| ------------------- | --------------------------------------------------------------- | ------------------------- |
+| `upsertSocialPosts` | `{ posts: Omit<UpsertSocialPostParams, 'organizationId'>[] }` | `UpsertSocialPostsResult` |
 
 ### Example
 
@@ -407,6 +425,45 @@ if (!result.success) {
 
 ---
 
+## List Adapter
+
+Singleton -- 4 methods for list-scoped lead-gen runtime operations. This is the focused companion to `acqDb` for list-oriented workflows.
+
+```typescript
+import { list } from '@elevasis/sdk/worker'
+```
+
+### Methods
+
+| Method | Params | Returns |
+| ------ | ------ | ------- |
+| `getConfig` | `{ listId }` | `ListConfig` |
+| `recordExecution` | `{ listId, executionId, payload? }` | `void` |
+| `updateCompanyStage` | `{ listId, companyId, stage, metadata? }` | `void` |
+| `updateContactStage` | `{ listId, contactId, stage, metadata? }` | `void` |
+
+### Example
+
+```typescript
+const config = await list.getConfig({ listId })
+
+await list.recordExecution({
+  listId,
+  executionId: context.executionId,
+  payload: { resourceId: context.resourceId, step: 'qualification' },
+})
+
+await list.updateCompanyStage({
+  listId,
+  companyId,
+  stage: 'qualified',
+})
+```
+
+Use `list` when the workflow is explicitly operating on a list pipeline run. Use `acqDb` when you need broader list, company, contact, or deal CRUD.
+
+---
+
 ## Email Adapter
 
 Singleton -- 1 method for sending platform emails to organization members (from `notifications@elevasis.io`). For client-facing emails, use the Resend or Instantly integration adapters instead.
@@ -493,4 +550,4 @@ Retryable error codes: `rate_limit_exceeded`, `network_error`, `timeout_error`,
 
 ---
 
-**Last Updated:** 2026-03-05
+**Last Updated:** 2026-04-15

package/reference/resources/patterns.mdx

@@ -352,4 +352,52 @@ The keys in `workflows` and `agents` are the resource identifiers used in CLI co
 
 ---
 
+---
+
+## Human-in-the-Loop UI Integration
+
+The platform's HITL mechanism works in two parts: your workflow code creates an approval task, and a UI surfaces that task to a reviewer.
+
+### Creating approval tasks
+
+Call `approval.create()` from any workflow step to pause execution and emit a task to the Command Queue:
+
+```typescript
+import { approval } from '@elevasis/sdk/worker'
+
+const task = await approval.create({
+  actions: [
+    { id: 'approve', label: 'Approve', type: 'primary' },
+    { id: 'reject', label: 'Reject', type: 'danger' },
+  ],
+  context: { dealId, proposalUrl },
+  description: 'Review proposal before sending',
+})
+
+if (task.actionId === 'approve') {
+  // continue with approved path
+}
+```
+
+The workflow step suspends at `approval.create()` and resumes only after a reviewer submits an action. See [Platform Adapters](../platform-tools/adapters-platform.mdx) for the full `approval.create()` reference.
+
+### Built-in Command Center handling
+
+The Command Queue page in the Command Center surfaces all pending approval tasks automatically. Reviewers can filter by resource, approve or reject with an optional comment, and view decision history. No custom UI code is required -- deploy your workflow and the queue populates as tasks arrive.
+
+### Custom UI handling
+
+`@elevasis/ui` exposes the following hooks for approval task operations, exported from `@elevasis/ui/hooks`:
+
+- `useCommandQueue` -- fetches the list of pending tasks for the organization
+- `useSubmitAction` -- POSTs an action decision to `/command-queue/{taskId}/action`
+- `usePatchTask` -- updates task metadata
+- `useDeleteTask` -- removes a task
+
+Use these hooks to build a custom approval queue surface in your template UI. `useSubmitAction` accepts `taskId`, `actionId`, and optional `notes`, and optimistically marks the task as `processing` while the request is in flight.
+
+For triggering executions from custom pages (the other side of the workflow interaction), see [UI Execution](../deployment/ui-execution.mdx).
+
+---
+
 **Last Updated:** 2026-02-25