@elevasis/sdk 1.2.0 → 1.3.0

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