@elevasis/sdk 1.21.0 → 1.22.0

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

@@ -1,553 +1,553 @@
----
-title: Platform Adapters
-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).
-
-```typescript
-import {
-  acqDb, scheduler, storage, pdf, approval,
-  notifications, llm, list, execution, email,
-} from '@elevasis/sdk/worker'
-```
-
----
-
-## Quick Reference
-
-| Import          | Methods | Purpose                              |
-| --------------- | ------- | ------------------------------------ |
-| `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            |
-
----
-
-## Scheduler Adapter
-
-Singleton -- 9 methods for task schedule management.
-
-```typescript
-import { scheduler } from '@elevasis/sdk/worker'
-```
-
-### Methods
-
-| Method                           | Params                         | Returns                |
-| -------------------------------- | ------------------------------ | ---------------------- |
-| `createSchedule`                 | `CreateScheduleInput`          | `TaskSchedule`         |
-| `updateAnchor`                   | `{ scheduleId, anchorAt }`     | `TaskSchedule`         |
-| `deleteSchedule`                 | `{ scheduleId }`               | `void`                 |
-| `findByIdempotencyKey`           | `{ idempotencyKey }`           | `TaskSchedule | null` |
-| `deleteScheduleByIdempotencyKey` | `{ idempotencyKey }`           | `void`                 |
-| `listSchedules`                  | `{ status?, limit?, offset? }` | `TaskSchedule[]`       |
-| `getSchedule`                    | `{ scheduleId }`               | `TaskSchedule`         |
-| `cancelSchedule`                 | `{ scheduleId }`               | `void`                 |
-| `cancelSchedulesByMetadata`      | `{ metadata }`                 | `{ cancelledCount }`   |
-
-### Examples
-
-```typescript
-// Create a relative schedule (follow-up sequence)
-const schedule = await scheduler.createSchedule({
-  organizationId: context.organizationId,
-  name: 'Proposal follow-up',
-  target: { resourceType: 'workflow', resourceId: 'send-followup' },
-  scheduleConfig: {
-    type: 'relative',
-    anchorAt: '2026-03-15T10:00:00Z',
-    anchorLabel: 'proposal_sent_date',
-    items: [
-      { offset: '+3d', payload: { step: 'first-followup' }, label: 'First follow-up' },
-      { offset: '+7d', payload: { step: 'second-followup' }, label: 'Second follow-up' },
-    ],
-  },
-  metadata: { dealId: 'deal-123', contactEmail: 'jane@acme.com' },
-  idempotencyKey: 'proposal-followup-deal-123',
-})
-
-// Reschedule (update anchor)
-await scheduler.updateAnchor({
-  scheduleId: schedule.id,
-  anchorAt: '2026-03-20T10:00:00Z',
-})
-
-// Cancel all schedules matching metadata
-await scheduler.cancelSchedulesByMetadata({
-  metadata: { dealId: 'deal-123' },
-})
-```
-
----
-
-## Storage Adapter
-
-Singleton -- 5 methods for file storage operations. All paths are relative to the organization's storage prefix (injected server-side).
-
-```typescript
-import { storage } from '@elevasis/sdk/worker'
-```
-
-### Methods
-
-| Method            | Params                  | Returns                  |
-| ----------------- | ----------------------- | ------------------------ |
-| `upload`          | `StorageUploadInput`    | `StorageUploadOutput`    |
-| `download`        | `StorageDownloadInput`  | `StorageDownloadOutput`  |
-| `createSignedUrl` | `StorageSignedUrlInput` | `StorageSignedUrlOutput` |
-| `delete`          | `StorageDeleteInput`    | `StorageDeleteOutput`    |
-| `list`            | `StorageListInput`      | `StorageListOutput`      |
-
-### Examples
-
-```typescript
-// Upload a PDF
-await storage.upload({
-  bucket: 'acquisition',
-  path: 'proposals/deal-123/proposal.pdf',
-  content: base64PdfContent,
-  contentType: 'application/pdf',
-})
-
-// Generate a signed URL (temporary access)
-const { signedUrl } = await storage.createSignedUrl({
-  bucket: 'acquisition',
-  path: 'proposals/deal-123/proposal.pdf',
-})
-
-// List files under a prefix
-const files = await storage.list({
-  bucket: 'acquisition',
-  path: 'proposals/deal-123/',
-})
-```
-
----
-
-## LLM Adapter
-
-Singleton -- 1 method with a generic `<T>` for typed structured output. No API keys needed -- keys are resolved server-side from environment variables.
-
-```typescript
-import { llm } from '@elevasis/sdk/worker'
-```
-
-### Method
-
-| Method          | Params                                 | Returns                    |
-| --------------- | -------------------------------------- | -------------------------- |
-| `generate<T>` | `Omit<LLMGenerateRequest, 'signal'>` | `LLMGenerateResponse<T>` |
-
-The `signal` property (AbortSignal) is not serializable over the postMessage boundary. Abort is handled at the worker level.
-
-### Example
-
-```typescript
-interface Classification {
-  category: 'interested' | 'not-interested' | 'bounced'
-  confidence: number
-  summary: string
-}
-
-const response = await llm.generate<Classification>({
-  provider: 'anthropic',
-  model: 'claude-sonnet-4-5',
-  messages: [
-    { role: 'system', content: 'Classify this email reply.' },
-    { role: 'user', content: emailText },
-  ],
-  responseSchema: {
-    type: 'object',
-    properties: {
-      category: { type: 'string', enum: ['interested', 'not-interested', 'bounced'] },
-      confidence: { type: 'number', minimum: 0, maximum: 1 },
-      summary: { type: 'string' },
-    },
-    required: ['category', 'confidence', 'summary'],
-  },
-  temperature: 0.1,
-})
-
-// response.output is typed as Classification
-const { category, confidence, summary } = response.output
-```
-
-**Supported models:** See the full model table in [Platform Tools](index.mdx#llm-tool).
-
-See [Adapter Type Safety](type-safety.mdx) for required field enforcement and design rationale.
-
----
-
-## PDF Adapter
-
-Singleton -- 2 methods for rendering PDFDocument structures to files or buffers. No credential required.
-
-```typescript
-import { pdf } from '@elevasis/sdk/worker'
-```
-
-### Methods
-
-| Method           | Params                                            | Returns                     |
-| ---------------- | ------------------------------------------------- | --------------------------- |
-| `render`         | `{ document, theme?, storage: { bucket, path } }` | `{ success, pdfUrl, size }` |
-| `renderToBuffer` | `{ document, theme? }`                            | `{ buffer }`                |
-
-### Example
-
-```typescript
-// Render to storage (returns a URL)
-const result = await pdf.render({
-  document: proposalDocument,
-  storage: { bucket: 'acquisition', path: 'proposals/deal-123/proposal.pdf' },
-})
-console.log(result.pdfUrl)
-
-// Render to buffer (for inline processing)
-const { buffer } = await pdf.renderToBuffer({ document: proposalDocument })
-```
-
----
-
-## Approval Adapter
-
-Singleton -- 2 methods for creating and managing human-in-the-loop (HITL) approval tasks. No credential required.
-
-```typescript
-import { approval } from '@elevasis/sdk/worker'
-```
-
-### Methods
-
-| Method             | Params                                                                                   | Returns       |
-| ------------------ | ---------------------------------------------------------------------------------------- | ------------- |
-| `create`           | `{ actions, context, description?, priority?, humanCheckpoint?, metadata?, expiresAt? }` | `{ id }`      |
-| `deleteByMetadata` | `{ metadata, status? }`                                                                  | `{ deleted }` |
-
-### Example
-
-```typescript
-// Create an approval gate
-const task = await approval.create({
-  actions: [
-    { id: 'approve', label: 'Approve', type: 'primary' },
-    { id: 'reject', label: 'Reject', type: 'danger' },
-  ],
-  context: { dealId: 'deal-123', proposalUrl: 'https://...' },
-  description: 'Review proposal for Acme Corp',
-  humanCheckpoint: 'proposal-review',
-  metadata: { dealId: 'deal-123' },
-})
-
-// Clean up stale tasks
-await approval.deleteByMetadata({
-  metadata: { dealId: 'deal-123' },
-  status: 'pending',
-})
-```
-
----
-
-## Notifications Adapter
-
-Singleton -- 1 method for sending in-app team notifications. `userId` and `organizationId` are injected server-side.
-
-```typescript
-import { notifications } from '@elevasis/sdk/worker'
-```
-
-### Method
-
-| Method   | Params                 | Returns |
-| -------- | ---------------------- | ------- |
-| `create` | `NotificationSDKInput` | `void`  |
-
-`NotificationSDKInput` fields: `category`, `title`, `message`, `actionUrl?`, `metadata?`
-
-### Example
-
-```typescript
-await notifications.create({
-  category: 'acquisition',
-  title: 'New lead qualified',
-  message: 'Acme Corp has been qualified and moved to proposal stage.',
-  actionUrl: '/deals/deal-123',
-})
-```
-
----
-
-## AcqDb Adapter
-
-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'
-```
-
-### Methods
-
-**List operations:**
-
-| 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:**
-
-| Method          | Params                                          | Returns              |
-| --------------- | ----------------------------------------------- | -------------------- |
-| `createCompany` | `Omit<CreateCompanyParams, 'organizationId'>` | `AcqCompany`         |
-| `upsertCompany` | `Omit<UpsertCompanyParams, 'organizationId'>` | `AcqCompany`         |
-| `updateCompany` | `{ id } & UpdateCompanyParams`                  | `AcqCompany`         |
-| `getCompany`    | `{ id }`                                        | `AcqCompany | null` |
-| `listCompanies` | `{ filters? }`                                  | `AcqCompany[]`       |
-| `deleteCompany` | `{ id }`                                        | `void`               |
-
-**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`              |
-| `bulkImportCompanies`         | `Omit<BulkImportCompaniesParams, 'organizationId'>` | `BulkImportCompaniesResult`     |
-| `deactivateContactsByCompany` | `{ companyId }`                                       | `{ deactivated: number }`       |
-
-**Deal operations:**
-
-| Method                 | Params                                       | Returns           |
-| ---------------------- | -------------------------------------------- | ----------------- |
-| `upsertDeal`           | `Omit<UpsertDealParams, 'organizationId'>` | `AcqDeal`         |
-| `getDealByEmail`       | `{ email }`                                  | `AcqDeal | null` |
-| `getDealByEnvelopeId`  | `{ envelopeId }`                             | `AcqDeal | null` |
-| `updateDealEnvelopeId` | `{ attioDealId, envelopeId }`                | `AcqDeal | null` |
-| `getDealByAttioId`     | `{ attioDealId }`                            | `AcqDeal | null` |
-
-**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`                                |
-| `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
-
-```typescript
-const deal = await acqDb.getDealByEmail({ email: 'jane@acme.com' })
-if (!deal) {
-  await acqDb.upsertDeal({
-    attioDealId: 'deal-123',
-    contactEmail: 'jane@acme.com',
-  })
-}
-
-// Bulk import contacts
-await acqDb.bulkImportContacts({
-  listId: 'list-abc',
-  contacts: [
-    { email: 'a@example.com', firstName: 'Alice' },
-    { email: 'b@example.com', firstName: 'Bob' },
-  ],
-})
-```
-
----
-
-## Execution Adapter
-
-Singleton -- 1 method for triggering another resource (workflow or agent) as a nested child execution. Maximum depth: 5 levels.
-
-```typescript
-import { execution } from '@elevasis/sdk/worker'
-```
-
-### Method
-
-| Method    | Params                   | Returns                                    |
-| --------- | ------------------------ | ------------------------------------------ |
-| `trigger` | `{ resourceId, input? }` | `{ success, executionId, output, error? }` |
-
-### Example
-
-```typescript
-const result = await execution.trigger({
-  resourceId: 'send-welcome-sequence',
-  input: { userId: newUser.id, email: newUser.email },
-})
-
-if (!result.success) {
-  throw new Error(`Child workflow failed: ${result.error}`)
-}
-```
-
----
-
-## 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.
-
-```typescript
-import { email } from '@elevasis/sdk/worker'
-```
-
-### Method
-
-| Method | Params                                                                          | Returns                     |
-| ------ | ------------------------------------------------------------------------------- | --------------------------- |
-| `send` | `{ subject, html?, text?, userIds?, targetRole?, targetAll?, replyTo?, tags? }` | `{ sent, failed, errors? }` |
-
-### Example
-
-```typescript
-// Notify all org members
-await email.send({
-  subject: 'New deal closed',
-  text: 'Acme Corp has signed the contract.',
-  targetAll: true,
-})
-
-// Notify specific users
-await email.send({
-  subject: 'Action required',
-  html: '\<p\>Please review the proposal.\</p\>',
-  userIds: ['user-abc', 'user-def'],
-})
-```
-
----
-
-## Custom Adapters with `createAdapter`
-
-The generic `createAdapter` factory is exported for building adapters for any tool not already covered. Define a type map and call the factory.
-
-```typescript
-import { createAdapter } from '@elevasis/sdk/worker'
-
-// 1. Define a type map
-type MyToolMap = {
-  doSomething: { params: { input: string }; result: { output: string } }
-  listItems:   { params: { limit?: number }; result: { items: string[] } }
-  getStatus:   { params: Record<string, never>; result: { healthy: boolean } }
-}
-
-// 2. Create the adapter
-const myTool = createAdapter<MyToolMap>('my-tool', [
-  'doSomething', 'listItems', 'getStatus',
-], 'my-credential')  // credential is optional
-
-// 3. Use it (fully typed)
-const result = await myTool.doSomething({ input: 'hello' })
-//    ^-- { output: string }
-```
-
-Method names are compile-time checked against the type map keys.
-
----
-
-## Error Handling
-
-All adapter calls throw `PlatformToolError` on failure, with a `code` field and `retryable` flag:
-
-```typescript
-import { PlatformToolError } from '@elevasis/sdk/worker'
-
-try {
-  await scheduler.listSchedules({ status: 'active' })
-} catch (err) {
-  if (err instanceof PlatformToolError) {
-    console.log(err.message)    // Human-readable error
-    console.log(err.code)       // e.g., 'rate_limit_exceeded', 'service_unavailable'
-    console.log(err.retryable)  // true for transient errors
-  }
-}
-```
-
-Retryable error codes: `rate_limit_exceeded`, `network_error`, `timeout_error`, `api_error`, `service_unavailable`, `server_unavailable`.
-
-**Timeouts:** LLM calls have a 120s timeout. All other tool calls have a 60s timeout.
-
----
-
-**Last Updated:** 2026-04-15
+---
+title: Platform Adapters
+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).
+
+```typescript
+import {
+  acqDb, scheduler, storage, pdf, approval,
+  notifications, llm, list, execution, email,
+} from '@elevasis/sdk/worker'
+```
+
+---
+
+## Quick Reference
+
+| Import          | Methods | Purpose                              |
+| --------------- | ------- | ------------------------------------ |
+| `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            |
+
+---
+
+## Scheduler Adapter
+
+Singleton -- 9 methods for task schedule management.
+
+```typescript
+import { scheduler } from '@elevasis/sdk/worker'
+```
+
+### Methods
+
+| Method                           | Params                         | Returns                |
+| -------------------------------- | ------------------------------ | ---------------------- |
+| `createSchedule`                 | `CreateScheduleInput`          | `TaskSchedule`         |
+| `updateAnchor`                   | `{ scheduleId, anchorAt }`     | `TaskSchedule`         |
+| `deleteSchedule`                 | `{ scheduleId }`               | `void`                 |
+| `findByIdempotencyKey`           | `{ idempotencyKey }`           | `TaskSchedule | null` |
+| `deleteScheduleByIdempotencyKey` | `{ idempotencyKey }`           | `void`                 |
+| `listSchedules`                  | `{ status?, limit?, offset? }` | `TaskSchedule[]`       |
+| `getSchedule`                    | `{ scheduleId }`               | `TaskSchedule`         |
+| `cancelSchedule`                 | `{ scheduleId }`               | `void`                 |
+| `cancelSchedulesByMetadata`      | `{ metadata }`                 | `{ cancelledCount }`   |
+
+### Examples
+
+```typescript
+// Create a relative schedule (follow-up sequence)
+const schedule = await scheduler.createSchedule({
+  organizationId: context.organizationId,
+  name: 'Proposal follow-up',
+  target: { resourceType: 'workflow', resourceId: 'send-followup' },
+  scheduleConfig: {
+    type: 'relative',
+    anchorAt: '2026-03-15T10:00:00Z',
+    anchorLabel: 'proposal_sent_date',
+    items: [
+      { offset: '+3d', payload: { step: 'first-followup' }, label: 'First follow-up' },
+      { offset: '+7d', payload: { step: 'second-followup' }, label: 'Second follow-up' },
+    ],
+  },
+  metadata: { dealId: 'deal-123', contactEmail: 'jane@acme.com' },
+  idempotencyKey: 'proposal-followup-deal-123',
+})
+
+// Reschedule (update anchor)
+await scheduler.updateAnchor({
+  scheduleId: schedule.id,
+  anchorAt: '2026-03-20T10:00:00Z',
+})
+
+// Cancel all schedules matching metadata
+await scheduler.cancelSchedulesByMetadata({
+  metadata: { dealId: 'deal-123' },
+})
+```
+
+---
+
+## Storage Adapter
+
+Singleton -- 5 methods for file storage operations. All paths are relative to the organization's storage prefix (injected server-side).
+
+```typescript
+import { storage } from '@elevasis/sdk/worker'
+```
+
+### Methods
+
+| Method            | Params                  | Returns                  |
+| ----------------- | ----------------------- | ------------------------ |
+| `upload`          | `StorageUploadInput`    | `StorageUploadOutput`    |
+| `download`        | `StorageDownloadInput`  | `StorageDownloadOutput`  |
+| `createSignedUrl` | `StorageSignedUrlInput` | `StorageSignedUrlOutput` |
+| `delete`          | `StorageDeleteInput`    | `StorageDeleteOutput`    |
+| `list`            | `StorageListInput`      | `StorageListOutput`      |
+
+### Examples
+
+```typescript
+// Upload a PDF
+await storage.upload({
+  bucket: 'acquisition',
+  path: 'proposals/deal-123/proposal.pdf',
+  content: base64PdfContent,
+  contentType: 'application/pdf',
+})
+
+// Generate a signed URL (temporary access)
+const { signedUrl } = await storage.createSignedUrl({
+  bucket: 'acquisition',
+  path: 'proposals/deal-123/proposal.pdf',
+})
+
+// List files under a prefix
+const files = await storage.list({
+  bucket: 'acquisition',
+  path: 'proposals/deal-123/',
+})
+```
+
+---
+
+## LLM Adapter
+
+Singleton -- 1 method with a generic `<T>` for typed structured output. No API keys needed -- keys are resolved server-side from environment variables.
+
+```typescript
+import { llm } from '@elevasis/sdk/worker'
+```
+
+### Method
+
+| Method          | Params                                 | Returns                    |
+| --------------- | -------------------------------------- | -------------------------- |
+| `generate<T>` | `Omit<LLMGenerateRequest, 'signal'>` | `LLMGenerateResponse<T>` |
+
+The `signal` property (AbortSignal) is not serializable over the postMessage boundary. Abort is handled at the worker level.
+
+### Example
+
+```typescript
+interface Classification {
+  category: 'interested' | 'not-interested' | 'bounced'
+  confidence: number
+  summary: string
+}
+
+const response = await llm.generate<Classification>({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5',
+  messages: [
+    { role: 'system', content: 'Classify this email reply.' },
+    { role: 'user', content: emailText },
+  ],
+  responseSchema: {
+    type: 'object',
+    properties: {
+      category: { type: 'string', enum: ['interested', 'not-interested', 'bounced'] },
+      confidence: { type: 'number', minimum: 0, maximum: 1 },
+      summary: { type: 'string' },
+    },
+    required: ['category', 'confidence', 'summary'],
+  },
+  temperature: 0.1,
+})
+
+// response.output is typed as Classification
+const { category, confidence, summary } = response.output
+```
+
+**Supported models:** See the full model table in [Platform Tools](index.mdx#llm-tool).
+
+See [Adapter Type Safety](type-safety.mdx) for required field enforcement and design rationale.
+
+---
+
+## PDF Adapter
+
+Singleton -- 2 methods for rendering PDFDocument structures to files or buffers. No credential required.
+
+```typescript
+import { pdf } from '@elevasis/sdk/worker'
+```
+
+### Methods
+
+| Method           | Params                                            | Returns                     |
+| ---------------- | ------------------------------------------------- | --------------------------- |
+| `render`         | `{ document, theme?, storage: { bucket, path } }` | `{ success, pdfUrl, size }` |
+| `renderToBuffer` | `{ document, theme? }`                            | `{ buffer }`                |
+
+### Example
+
+```typescript
+// Render to storage (returns a URL)
+const result = await pdf.render({
+  document: proposalDocument,
+  storage: { bucket: 'acquisition', path: 'proposals/deal-123/proposal.pdf' },
+})
+console.log(result.pdfUrl)
+
+// Render to buffer (for inline processing)
+const { buffer } = await pdf.renderToBuffer({ document: proposalDocument })
+```
+
+---
+
+## Approval Adapter
+
+Singleton -- 2 methods for creating and managing human-in-the-loop (HITL) approval tasks. No credential required.
+
+```typescript
+import { approval } from '@elevasis/sdk/worker'
+```
+
+### Methods
+
+| Method             | Params                                                                                   | Returns       |
+| ------------------ | ---------------------------------------------------------------------------------------- | ------------- |
+| `create`           | `{ actions, context, description?, priority?, humanCheckpoint?, metadata?, expiresAt? }` | `{ id }`      |
+| `deleteByMetadata` | `{ metadata, status? }`                                                                  | `{ deleted }` |
+
+### Example
+
+```typescript
+// Create an approval gate
+const task = await approval.create({
+  actions: [
+    { id: 'approve', label: 'Approve', type: 'primary' },
+    { id: 'reject', label: 'Reject', type: 'danger' },
+  ],
+  context: { dealId: 'deal-123', proposalUrl: 'https://...' },
+  description: 'Review proposal for Acme Corp',
+  humanCheckpoint: 'proposal-review',
+  metadata: { dealId: 'deal-123' },
+})
+
+// Clean up stale tasks
+await approval.deleteByMetadata({
+  metadata: { dealId: 'deal-123' },
+  status: 'pending',
+})
+```
+
+---
+
+## Notifications Adapter
+
+Singleton -- 1 method for sending in-app team notifications. `userId` and `organizationId` are injected server-side.
+
+```typescript
+import { notifications } from '@elevasis/sdk/worker'
+```
+
+### Method
+
+| Method   | Params                 | Returns |
+| -------- | ---------------------- | ------- |
+| `create` | `NotificationSDKInput` | `void`  |
+
+`NotificationSDKInput` fields: `category`, `title`, `message`, `actionUrl?`, `metadata?`
+
+### Example
+
+```typescript
+await notifications.create({
+  category: 'acquisition',
+  title: 'New lead qualified',
+  message: 'Acme Corp has been qualified and moved to proposal stage.',
+  actionUrl: '/deals/deal-123',
+})
+```
+
+---
+
+## AcqDb Adapter
+
+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'
+```
+
+### Methods
+
+**List operations:**
+
+| 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:**
+
+| Method          | Params                                          | Returns              |
+| --------------- | ----------------------------------------------- | -------------------- |
+| `createCompany` | `Omit<CreateCompanyParams, 'organizationId'>` | `AcqCompany`         |
+| `upsertCompany` | `Omit<UpsertCompanyParams, 'organizationId'>` | `AcqCompany`         |
+| `updateCompany` | `{ id } & UpdateCompanyParams`                  | `AcqCompany`         |
+| `getCompany`    | `{ id }`                                        | `AcqCompany | null` |
+| `listCompanies` | `{ filters? }`                                  | `AcqCompany[]`       |
+| `deleteCompany` | `{ id }`                                        | `void`               |
+
+**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`              |
+| `bulkImportCompanies`         | `Omit<BulkImportCompaniesParams, 'organizationId'>` | `BulkImportCompaniesResult`     |
+| `deactivateContactsByCompany` | `{ companyId }`                                       | `{ deactivated: number }`       |
+
+**Deal operations:**
+
+| Method                 | Params                                       | Returns           |
+| ---------------------- | -------------------------------------------- | ----------------- |
+| `upsertDeal`           | `Omit<UpsertDealParams, 'organizationId'>` | `AcqDeal`         |
+| `getDealByEmail`       | `{ email }`                                  | `AcqDeal | null` |
+| `getDealByEnvelopeId`  | `{ envelopeId }`                             | `AcqDeal | null` |
+| `updateDealEnvelopeId` | `{ attioDealId, envelopeId }`                | `AcqDeal | null` |
+| `getDealByAttioId`     | `{ attioDealId }`                            | `AcqDeal | null` |
+
+**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`                                |
+| `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
+
+```typescript
+const deal = await acqDb.getDealByEmail({ email: 'jane@acme.com' })
+if (!deal) {
+  await acqDb.upsertDeal({
+    attioDealId: 'deal-123',
+    contactEmail: 'jane@acme.com',
+  })
+}
+
+// Bulk import contacts
+await acqDb.bulkImportContacts({
+  listId: 'list-abc',
+  contacts: [
+    { email: 'a@example.com', firstName: 'Alice' },
+    { email: 'b@example.com', firstName: 'Bob' },
+  ],
+})
+```
+
+---
+
+## Execution Adapter
+
+Singleton -- 1 method for triggering another resource (workflow or agent) as a nested child execution. Maximum depth: 5 levels.
+
+```typescript
+import { execution } from '@elevasis/sdk/worker'
+```
+
+### Method
+
+| Method    | Params                   | Returns                                    |
+| --------- | ------------------------ | ------------------------------------------ |
+| `trigger` | `{ resourceId, input? }` | `{ success, executionId, output, error? }` |
+
+### Example
+
+```typescript
+const result = await execution.trigger({
+  resourceId: 'send-welcome-sequence',
+  input: { userId: newUser.id, email: newUser.email },
+})
+
+if (!result.success) {
+  throw new Error(`Child workflow failed: ${result.error}`)
+}
+```
+
+---
+
+## 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.
+
+```typescript
+import { email } from '@elevasis/sdk/worker'
+```
+
+### Method
+
+| Method | Params                                                                          | Returns                     |
+| ------ | ------------------------------------------------------------------------------- | --------------------------- |
+| `send` | `{ subject, html?, text?, userIds?, targetRole?, targetAll?, replyTo?, tags? }` | `{ sent, failed, errors? }` |
+
+### Example
+
+```typescript
+// Notify all org members
+await email.send({
+  subject: 'New deal closed',
+  text: 'Acme Corp has signed the contract.',
+  targetAll: true,
+})
+
+// Notify specific users
+await email.send({
+  subject: 'Action required',
+  html: '\<p\>Please review the proposal.\</p\>',
+  userIds: ['user-abc', 'user-def'],
+})
+```
+
+---
+
+## Custom Adapters with `createAdapter`
+
+The generic `createAdapter` factory is exported for building adapters for any tool not already covered. Define a type map and call the factory.
+
+```typescript
+import { createAdapter } from '@elevasis/sdk/worker'
+
+// 1. Define a type map
+type MyToolMap = {
+  doSomething: { params: { input: string }; result: { output: string } }
+  listItems:   { params: { limit?: number }; result: { items: string[] } }
+  getStatus:   { params: Record<string, never>; result: { healthy: boolean } }
+}
+
+// 2. Create the adapter
+const myTool = createAdapter<MyToolMap>('my-tool', [
+  'doSomething', 'listItems', 'getStatus',
+], 'my-credential')  // credential is optional
+
+// 3. Use it (fully typed)
+const result = await myTool.doSomething({ input: 'hello' })
+//    ^-- { output: string }
+```
+
+Method names are compile-time checked against the type map keys.
+
+---
+
+## Error Handling
+
+All adapter calls throw `PlatformToolError` on failure, with a `code` field and `retryable` flag:
+
+```typescript
+import { PlatformToolError } from '@elevasis/sdk/worker'
+
+try {
+  await scheduler.listSchedules({ status: 'active' })
+} catch (err) {
+  if (err instanceof PlatformToolError) {
+    console.log(err.message)    // Human-readable error
+    console.log(err.code)       // e.g., 'rate_limit_exceeded', 'service_unavailable'
+    console.log(err.retryable)  // true for transient errors
+  }
+}
+```
+
+Retryable error codes: `rate_limit_exceeded`, `network_error`, `timeout_error`, `api_error`, `service_unavailable`, `server_unavailable`.
+
+**Timeouts:** LLM calls have a 120s timeout. All other tool calls have a 60s timeout.
+
+---
+
+**Last Updated:** 2026-04-15