@elevasis/sdk 0.5.12 → 0.5.13

package/reference/platform-tools/adapters.mdx

@@ -1,6 +1,6 @@
 ---
 title: Typed Adapters
-description: Type-safe wrappers over platform.call() for all integrations and platform tools -- Attio, Stripe, Notion, Google Sheets, Trello, and more -- with full autocomplete, compile-time checking, and zero boilerplate
+description: Type-safe wrappers over platform.call() for all integrations and platform tools -- Attio, Stripe, Notion, Google Sheets, and more -- with full autocomplete, compile-time checking, and zero boilerplate
 loadWhen: "Using typed adapters instead of raw platform.call(), or needs to know what adapter methods are available"
 ---
 
@@ -8,6 +8,8 @@ Typed adapters are ergonomic wrappers over `platform.call()` that provide full T
 
 Both patterns work simultaneously -- adapters compile down to `platform.call()` with zero runtime overhead.
 
+**Coverage:** 11 integration adapters (55 methods) + 9 platform tool adapters (57 methods) = 112 total typed methods.
+
 ```typescript
 // Before: raw platform.call()
 const records = await platform.call({
@@ -37,7 +39,6 @@ All adapters are imported from `@elevasis/sdk/worker` -- the same subpath as `pl
 | `createStripeAdapter(cred)` | 6 |
 | `createNotionAdapter(cred)` | 8 |
 | `createGoogleSheetsAdapter(cred)` | 13 |
-| `createTrelloAdapter(cred)` | 10 |
 | `createInstantlyAdapter(cred)` | 5 |
 | `createSignatureApiAdapter(cred)` | 4 |
 | `createResendAdapter(cred)` | 2 |
@@ -70,7 +71,7 @@ All adapters are imported from `@elevasis/sdk/worker` -- the same subpath as `pl
 import {
   // Integration adapters
   createAttioAdapter, createStripeAdapter, createNotionAdapter,
-  createGoogleSheetsAdapter, createTrelloAdapter, createInstantlyAdapter,
+  createGoogleSheetsAdapter, createInstantlyAdapter,
   createSignatureApiAdapter, createResendAdapter, createDropboxAdapter,
   createApifyAdapter, createGmailAdapter, createMailsoAdapter,
   // Platform adapters
@@ -231,31 +232,6 @@ const sheets = createGoogleSheetsAdapter('my-google-credential')
 
 ---
 
-## Trello Adapter
-
-Factory pattern -- 10 methods for boards, lists, cards, and checklists.
-
-```typescript
-const trello = createTrelloAdapter('my-trello-credential')
-```
-
-### Methods
-
-| Method | Params | Returns |
-|--------|--------|---------|
-| `getBoard` | `GetBoardParams` | `GetBoardResult` |
-| `getLists` | `GetListsParams` | `GetListsResult` |
-| `getCards` | `GetCardsParams` | `GetCardsResult` |
-| `createCard` | `CreateCardParams` | `CreateCardResult` |
-| `updateCard` | `UpdateCardParams` | `UpdateCardResult` |
-| `createList` | `TrelloCreateListParams` | `TrelloCreateListResult` |
-| `createChecklist` | `CreateChecklistParams` | `CreateChecklistResult` |
-| `addChecklistItem` | `AddChecklistItemParams` | `AddChecklistItemResult` |
-| `updateChecklistItem` | `UpdateChecklistItemParams` | `UpdateChecklistItemResult` |
-| `getCardChecklists` | `GetCardChecklistsParams` | `GetCardChecklistsResult` |
-
----
-
 ## Instantly Adapter
 
 Factory pattern -- 5 methods for email campaign management.
@@ -846,6 +822,176 @@ Method names are compile-time checked against the type map keys -- misspelling a
 
 ---
 
+## Why `platform.call()` Must Stay
+
+The postMessage boundary between worker and main thread is load-bearing. Adapters wrap it -- they cannot replace it.
+
+- **Multi-tenancy enforcement** -- The main thread overwrites `organizationId` on every tool call from parent-owned JWT context. Workers cannot forge a different org's identity.
+- **Secrets isolation** -- API keys, decrypted OAuth tokens, and Supabase service-role credentials never cross the postMessage boundary. Workers only receive `NODE_ENV`.
+- **Service lifecycle** -- `toolServicesRegistry` is initialized once at API startup. Workers don't have access to `initialize()` or the singleton services.
+- **Bundle boundary** -- Org bundles only import `@elevasis/sdk/worker`. Server-side code is not in the dependency graph.
+- **Crash isolation** -- 256MB heap cap per worker means a runaway workflow kills only its worker, not the API process.
+
+Adapters are a pure DX layer on top of this boundary.
+
+---
+
+## Architecture
+
+### Call Flow
+
+```
+Developer Code
+  |
+  v
+attio.listRecords(params)           <-- typed adapter (SDK-side)
+  |
+  v
+createAdapter<AttioToolMap>(...)     <-- generic factory (SDK-side)
+  |
+  v
+platform.call({ tool, method, params, credential })   <-- existing generic proxy
+  |
+  v
+postMessage boundary                <-- unchanged
+  |
+  v
+tool-dispatcher.ts                  <-- routing
+  |
+  v
+integrationService.call()           <-- unchanged execution
+  |
+  v
+AttioAdapter.call()                 <-- unchanged server adapter
+```
+
+### ToolMap Type System
+
+Per-tool method maps are defined once in `@repo/core` as pure types (zero runtime code, browser-safe). A generic `createAdapter` factory generates the full typed adapter from these maps.
+
+**Before (hand-written, per-method boilerplate):**
+
+```typescript
+export function createAttioAdapter(credential: string) {
+  return {
+    createRecord: (params: CreateRecordParams) =>
+      platform.call({ tool: 'attio', method: 'createRecord', params, credential }) as Promise<CreateRecordResult>,
+    // ... 12 methods, each with manual type import + literal strings + as cast
+  }
+}
+```
+
+**After (ToolMap + factory):**
+
+```typescript
+import { createAdapter } from './create-adapter.js'
+import type { AttioToolMap } from '../../types/index.js'
+
+export function createAttioAdapter(credential: string) {
+  return createAdapter<AttioToolMap>('attio', METHODS, credential)
+}
+```
+
+The `methods` array is constrained to `(keyof TMap & string)[]` -- misspelling a method name is a compile error.
+
+### Type Sharing Strategy
+
+Types are defined once in `@repo/core` and shared across SDK and server:
+
+```
+packages/core/src/execution/engine/tools/
+  tool-maps.ts                      <-- 16 ToolMap type definitions (browser-safe)
+  integration/types/
+    attio.ts, stripe.ts, notion.ts, google-sheets.ts
+    instantly.ts, signature-api.ts, resend.ts, dropbox.ts
+    apify.ts, gmail.ts, mailso.ts
+    index.ts                        <-- barrel export (all 12 integrations)
+  platform/storage/types.ts         <-- Storage Zod schemas and inferred types
+```
+
+**Export chain:**
+
+1. Types defined in `@repo/core` (browser-safe locations)
+2. ToolMaps reference these types in `tools/tool-maps.ts`
+3. Exported via `packages/core/src/execution/engine/index.ts`
+4. Available at `@repo/core/execution` subpath
+5. `packages/sdk/src/types/index.ts` re-exports named types
+6. SDK adapters import from `../../types/index.js`
+
+---
+
+## Design Decisions
+
+### ToolMap + Generic Factory
+
+All adapters (except LLM) use `createAdapter<TMap>()` instead of hand-written method objects:
+
+- Method names are compile-time checked against ToolMap keys (misspelling = compile error)
+- No manual `as Promise<T>` casts -- `TypedAdapter` mapped type handles it
+- Adding a method = one entry in the ToolMap type + one string in the methods array
+
+### Factory with Credential Binding
+
+Integration adapters use `createXxxAdapter(credential)` pattern:
+
+- Credential is bound once, not repeated on every call
+- Mirrors how `createIntegrationTool(credentialName)` works server-side
+- Multiple adapters for same integration with different credentials work simultaneously
+
+### LLM Adapter is Hand-Written
+
+The LLM adapter stays hand-written because its `generate()` method uses a generic `<T>` for typed output that cannot be expressed in a static ToolMap:
+
+```typescript
+generate: <T = unknown>(params: Omit<LLMGenerateRequest, 'signal'>) =>
+  platform.call({ tool: 'llm', method: 'generate', params }) as Promise<LLMGenerateResponse<T>>
+```
+
+### Name Collision and Browser Safety
+
+- **Gmail/Resend prefix**: Both integrations have `SendEmailParams`/`SendEmailResult`. Gmail types use `Gmail*` prefix, Resend types use `Resend*` prefix.
+- **Mailso prefix**: `Mailso*` prefix for namespace clarity.
+- **Browser safety**: `UploadFileParams.contents` and `DownloadDocumentResult.content` use `Uint8Array` instead of Node.js `Buffer`. Server adapters still use `Buffer` internally.
+- **Snake\_case preservation**: Instantly types preserve snake\_case field names (`lead_email`, `campaign_id`) because the server adapter sends them as-is to the Instantly API.
+- **No server-side changes**: All 11 server adapters keep their local type definitions. Shared types are additive.
+
+### `NotificationSDKInput` Derived from Core
+
+`NotificationSDKInput` is `Omit<CreateNotificationParams, 'userId' | 'organizationId'>` -- derived from the canonical core type, not a local duplicate. Re-exported as `NotificationInput` for backward compatibility.
+
+---
+
+## Known Issues
+
+### Attio `listRecords` Type Mismatch (Server-Side Only)
+
+The server-side `attio-adapter.ts` defines a local `ListRecordsParams` with `filter?: Record<string, unknown>`, which is weaker than the shared `QueryRecordsParams` with `filter?: FilterExpression`. The SDK adapter correctly uses `QueryRecordsParams`. Updating `attio-adapter.ts` to use shared types is separate refactoring work.
+
+### Dispatcher Still Untyped
+
+`tool-dispatcher.ts` still uses `eslint-disable @typescript-eslint/no-explicit-any`. The same ToolMap types could be used server-side to type the dispatcher's switch cases. Future improvement.
+
+### Intentionally Not Migrated
+
+- `full-diagnostic.ts` and `integration-test.ts` -- use generic `platform.call()` loops for connectivity testing
+- All `supabase`, `session-memory`, `hitl`, `status`, `http` calls -- no typed adapters exist (platform-internal tools)
+
+---
+
+## Official SDK Comparison
+
+| Adapter | Official SDK | Strategy Used | Mirror Accuracy |
+|---------|-------------|---------------|-----------------|
+| Attio | None exists | Raw HTTP fetch | Exact -- endpoints and body shapes match Attio v2 REST API |
+| Stripe | `stripe` (official) | Official SDK | Exact -- uses `stripe.paymentLinks.*`, `stripe.checkout.sessions.*` |
+| Notion | `@notionhq/client` (official) | Official SDK | High -- uses `notion.pages.*`, `notion.blocks.*`; custom method names |
+| Google Sheets | `@googleapis/sheets` (official) | Official SDK + helpers | High -- adds 7 workflow-friendly helpers on top of raw SDK |
+| Apify | `apify-client` exists, not used | Raw HTTP fetch | N/A -- custom polling loop |
+| Resend | `resend` exists, not used | Raw HTTP fetch | High -- matches REST API surface |
+| Gmail | `@googleapis/gmail` (official) | Official SDK | High -- parallel to Sheets pattern |
+
+---
+
 ## When to Use Adapters vs `platform.call()`
 
 | Scenario | Use |
@@ -869,7 +1015,6 @@ Not all platform tools have typed adapters. Here is the complete list of tools a
 |------|--------------|---------|-----------------|
 | `attio` | `createAttioAdapter` | 12 (CRUD + schema + notes) | `{ apiKey }` |
 | `google-sheets` | `createGoogleSheetsAdapter` | 13 (read/write/filter/upsert) | OAuth2 / service account |
-| `trello` | `createTrelloAdapter` | 10 (cards/lists/checklists) | `{ apiKey, token }` |
 | `notion` | `createNotionAdapter` | 8 (pages + blocks) | `{ token }` |
 | `stripe` | `createStripeAdapter` | 6 (payment links + checkout) | `{ secretKey }` |
 | `instantly` | `createInstantlyAdapter` | 5 (email campaigns) | `{ apiKey }` |
@@ -924,6 +1069,4 @@ Timeouts: LLM calls have a 120s timeout. All other tool calls have a 60s timeout
 
 ---
 
-**Last Updated:** 2026-03-02
-
-
+**Last Updated:** 2026-03-05