@elevasis/sdk 0.7.11 → 0.7.12

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

@@ -0,0 +1,494 @@
+---
+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)"
+---
+
+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, execution, email,
+} from '@elevasis/sdk/worker'
+```
+
+---
+
+## Quick Reference
+
+| Import          | Methods | Purpose                              |
+| --------------- | ------- | ------------------------------------ |
+| `acqDb`         | 35      | 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 |
+| `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).
+
+---
+
+## 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 -- 35 methods for acquisition database management (lists, companies, contacts, deals, deal-sync). `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`      |
+
+**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`              |
+
+**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`                                |
+
+### 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}`)
+}
+```
+
+---
+
+## 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-03-05