@elevasis/sdk 0.7.11 → 0.7.13

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

@@ -0,0 +1,342 @@
+---
+title: Integration Adapters
+description: Type-safe wrappers for third-party integrations -- Attio, Stripe, Notion, Google Sheets, Instantly, SignatureAPI, Resend, Dropbox, Apify, Gmail, Mailso, and Tomba -- with full autocomplete and compile-time checking
+loadWhen: "Using typed adapters for integration tools, or needs to know what integration adapter methods are available"
+---
+
+Integration adapters are factory functions that bind a credential once and return a typed object with all methods available for that service. They wrap `platform.call()` with full TypeScript autocomplete and compile-time method checking.
+
+All integration adapters are imported from `@elevasis/sdk/worker`. For platform service adapters (scheduler, storage, llm, etc.), see [Platform Adapters](adapters-platform.mdx).
+
+```typescript
+import {
+  createAttioAdapter, createStripeAdapter, createNotionAdapter,
+  createGoogleSheetsAdapter, createInstantlyAdapter,
+  createSignatureApiAdapter, createResendAdapter, createDropboxAdapter,
+  createApifyAdapter, createGmailAdapter, createMailsoAdapter,
+  createTombaAdapter,
+} from '@elevasis/sdk/worker'
+```
+
+---
+
+## Quick Reference
+
+| Import                            | Methods | Category            |
+| --------------------------------- | ------- | ------------------- |
+| `createAttioAdapter(cred)`        | 12      | CRM                 |
+| `createGoogleSheetsAdapter(cred)` | 13      | Spreadsheets        |
+| `createNotionAdapter(cred)`       | 8       | Knowledge Base      |
+| `createStripeAdapter(cred)`       | 6       | Payments            |
+| `createInstantlyAdapter(cred)`    | 5       | Email Campaigns     |
+| `createSignatureApiAdapter(cred)` | 4       | eSignature          |
+| `createTombaAdapter(cred)`        | 3       | Email Discovery     |
+| `createResendAdapter(cred)`       | 2       | Transactional Email |
+| `createDropboxAdapter(cred)`      | 2       | File Storage        |
+| `createApifyAdapter(cred)`        | 1       | Web Scraping        |
+| `createGmailAdapter(cred)`        | 1       | Email (Gmail)       |
+| `createMailsoAdapter(cred)`       | 1       | Email Verification  |
+
+Multiple adapters with different credentials work simultaneously:
+
+```typescript
+const prodAttio = createAttioAdapter('prod-attio')
+const testAttio = createAttioAdapter('test-attio')
+```
+
+---
+
+## Attio CRM Adapter
+
+Factory pattern -- bind a credential once, use 12 typed methods.
+
+```typescript
+const attio = createAttioAdapter('my-attio-credential')
+```
+
+### Methods
+
+| Method            | Params                  | Returns                 |
+| ----------------- | ----------------------- | ----------------------- |
+| `createRecord`    | `CreateRecordParams`    | `CreateRecordResult`    |
+| `updateRecord`    | `UpdateRecordParams`    | `UpdateRecordResult`    |
+| `listRecords`     | `QueryRecordsParams`    | `QueryRecordsResult`    |
+| `getRecord`       | `GetRecordParams`       | `GetRecordResult`       |
+| `deleteRecord`    | `DeleteRecordParams`    | `DeleteRecordResult`    |
+| `listObjects`     | none                    | `ListObjectsResult`     |
+| `listAttributes`  | `ListAttributesParams`  | `ListAttributesResult`  |
+| `createAttribute` | `CreateAttributeParams` | `CreateAttributeResult` |
+| `updateAttribute` | `UpdateAttributeParams` | `UpdateAttributeResult` |
+| `createNote`      | `CreateNoteParams`      | `CreateNoteResult`      |
+| `listNotes`       | `ListNotesParams`       | `ListNotesResult`       |
+| `deleteNote`      | `DeleteNoteParams`      | `DeleteNoteResult`      |
+
+### Examples
+
+```typescript
+// Create a company record
+const company = await attio.createRecord({
+  object: 'companies',
+  values: {
+    name: [{ value: 'Acme Corp' }],
+    domains: [{ domain: 'acme.com' }],
+  },
+})
+
+// Query deals with filters
+const deals = await attio.listRecords({
+  object: 'deals',
+  filter: {
+    operator: 'and',
+    filters: [
+      { field: 'stage', operator: 'equals', value: 'proposal' },
+    ],
+  },
+  sorts: [{ field: 'created_at', direction: 'desc' }],
+  limit: 20,
+})
+
+// Create a note on a record
+await attio.createNote({
+  parentObject: 'deals',
+  parentRecordId: 'rec_abc123',
+  title: 'Discovery call notes',
+  content: 'Key takeaways from the call...',
+})
+```
+
+---
+
+## Google Sheets Adapter
+
+Factory pattern -- 13 methods including workflow-friendly helpers (`getRowByValue`, `upsertRow`, `filterRows`).
+
+```typescript
+const sheets = createGoogleSheetsAdapter('my-google-credential')
+```
+
+### Methods
+
+| Method                   | Params                         | Returns                        |
+| ------------------------ | ------------------------------ | ------------------------------ |
+| `readSheet`              | `ReadSheetParams`              | `ReadSheetResult`              |
+| `writeSheet`             | `WriteSheetParams`             | `WriteSheetResult`             |
+| `appendRows`             | `AppendRowsParams`             | `AppendRowsResult`             |
+| `clearRange`             | `ClearRangeParams`             | `ClearRangeResult`             |
+| `getSpreadsheetMetadata` | `GetSpreadsheetMetadataParams` | `GetSpreadsheetMetadataResult` |
+| `batchUpdate`            | `BatchUpdateParams`            | `BatchUpdateResult`            |
+| `getHeaders`             | `GetHeadersParams`             | `GetHeadersResult`             |
+| `getLastRow`             | `GetLastRowParams`             | `GetLastRowResult`             |
+| `getRowByValue`          | `GetRowByValueParams`          | `GetRowByValueResult`          |
+| `updateRowByValue`       | `UpdateRowByValueParams`       | `UpdateRowByValueResult`       |
+| `upsertRow`              | `UpsertRowParams`              | `UpsertRowResult`              |
+| `filterRows`             | `FilterRowsParams`             | `FilterRowsResult`             |
+| `deleteRowByValue`       | `DeleteRowByValueParams`       | `DeleteRowByValueResult`       |
+
+---
+
+## Notion Adapter
+
+Factory pattern -- 8 methods for page and block operations.
+
+```typescript
+const notion = createNotionAdapter('my-notion-credential')
+```
+
+### Methods
+
+| Method            | Params                  | Returns                 |
+| ----------------- | ----------------------- | ----------------------- |
+| `listAllPages`    | none                    | `ListAllPagesResult`    |
+| `readPage`        | `ReadPageParams`        | `ReadPageResult`        |
+| `createPage`      | `CreatePageParams`      | `CreatePageResult`      |
+| `updatePageTitle` | `UpdatePageTitleParams` | `UpdatePageTitleResult` |
+| `appendBlocks`    | `AppendBlocksParams`    | `AppendBlocksResult`    |
+| `updateBlocks`    | `UpdateBlocksParams`    | `UpdateBlocksResult`    |
+| `deletePage`      | `DeletePageParams`      | `DeletePageResult`      |
+| `deleteBlocks`    | `DeleteBlocksParams`    | `DeleteBlocksResult`    |
+
+---
+
+## Stripe Adapter
+
+Factory pattern -- 6 methods for payment links and checkout sessions.
+
+```typescript
+const stripe = createStripeAdapter('my-stripe-credential')
+```
+
+### Methods
+
+| Method                  | Params                        | Returns                       |
+| ----------------------- | ----------------------------- | ----------------------------- |
+| `createPaymentLink`     | `CreatePaymentLinkParams`     | `CreatePaymentLinkResult`     |
+| `getPaymentLink`        | `GetPaymentLinkParams`        | `GetPaymentLinkResult`        |
+| `updatePaymentLink`     | `UpdatePaymentLinkParams`     | `UpdatePaymentLinkResult`     |
+| `listPaymentLinks`      | `ListPaymentLinksParams`      | `ListPaymentLinksResult`      |
+| `createAutoPaymentLink` | `CreateAutoPaymentLinkParams` | `CreateAutoPaymentLinkResult` |
+| `createCheckoutSession` | `CreateCheckoutSessionParams` | `CreateCheckoutSessionResult` |
+
+---
+
+## Instantly Adapter
+
+Factory pattern -- 5 methods for email campaign management.
+
+```typescript
+const instantly = createInstantlyAdapter('my-instantly-credential')
+```
+
+### Methods
+
+| Method                  | Params                        | Returns                       |
+| ----------------------- | ----------------------------- | ----------------------------- |
+| `sendReply`             | `SendReplyParams`             | `SendReplyResult`             |
+| `removeFromSubsequence` | `RemoveFromSubsequenceParams` | `RemoveFromSubsequenceResult` |
+| `getEmails`             | `GetEmailsParams`             | `GetEmailsResult`             |
+| `updateInterestStatus`  | `UpdateInterestStatusParams`  | `UpdateInterestStatusResult`  |
+| `addToCampaign`         | `AddToCampaignParams`         | `AddToCampaignResult`         |
+
+---
+
+## SignatureAPI Adapter
+
+Factory pattern -- 4 methods for eSignature envelope operations.
+
+```typescript
+const signatureApi = createSignatureApiAdapter('my-signatureapi-credential')
+```
+
+### Methods
+
+| Method             | Params                   | Returns                  |
+| ------------------ | ------------------------ | ------------------------ |
+| `createEnvelope`   | `CreateEnvelopeParams`   | `CreateEnvelopeResult`   |
+| `voidEnvelope`     | `VoidEnvelopeParams`     | `VoidEnvelopeResult`     |
+| `downloadDocument` | `DownloadDocumentParams` | `DownloadDocumentResult` |
+| `getEnvelope`      | `GetEnvelopeParams`      | `GetEnvelopeResult`      |
+
+---
+
+## Tomba Adapter
+
+Factory pattern -- 3 methods for email discovery and verification.
+
+```typescript
+const tomba = createTombaAdapter('elevasis-tomba')
+```
+
+**Credential type:** `api-key-secret` (requires both API Key and API Secret)
+
+### Methods
+
+| Method          | Params                     | Returns                    |
+| --------------- | -------------------------- | -------------------------- |
+| `emailFinder`   | `TombaEmailFinderParams`   | `TombaEmailFinderResult`   |
+| `domainSearch`  | `TombaDomainSearchParams`  | `TombaDomainSearchResult`  |
+| `emailVerifier` | `TombaEmailVerifierParams` | `TombaEmailVerifierResult` |
+
+### Examples
+
+```typescript
+// Find email by name + domain
+const found = await tomba.emailFinder({
+  domain: 'stripe.com',
+  firstName: 'John',
+  lastName: 'Doe',
+})
+
+// List all emails at a domain (up to 10)
+const results = await tomba.domainSearch({ domain: 'stripe.com' })
+
+// Verify a known email address
+const verified = await tomba.emailVerifier({ email: 'john@stripe.com' })
+```
+
+---
+
+## Resend Adapter
+
+Factory pattern -- 2 methods for transactional email.
+
+```typescript
+const resend = createResendAdapter('my-resend-credential')
+```
+
+### Methods
+
+| Method      | Params                  | Returns                 |
+| ----------- | ----------------------- | ----------------------- |
+| `sendEmail` | `ResendSendEmailParams` | `ResendSendEmailResult` |
+| `getEmail`  | `ResendGetEmailParams`  | `ResendGetEmailResult`  |
+
+---
+
+## Dropbox Adapter
+
+Factory pattern -- 2 methods for file operations.
+
+```typescript
+const dropbox = createDropboxAdapter('my-dropbox-credential')
+```
+
+### Methods
+
+| Method         | Params               | Returns              |
+| -------------- | -------------------- | -------------------- |
+| `uploadFile`   | `UploadFileParams`   | `UploadFileResult`   |
+| `createFolder` | `CreateFolderParams` | `CreateFolderResult` |
+
+---
+
+## Apify Adapter
+
+Factory pattern -- 1 method for running web scraping actors.
+
+```typescript
+const apify = createApifyAdapter('my-apify-credential')
+```
+
+### Methods
+
+| Method     | Params           | Returns          |
+| ---------- | ---------------- | ---------------- |
+| `runActor` | `RunActorParams` | `RunActorResult` |
+
+---
+
+## Gmail Adapter
+
+Factory pattern -- 1 method for sending email via Gmail API.
+
+```typescript
+const gmail = createGmailAdapter('my-gmail-credential')
+```
+
+### Methods
+
+| Method      | Params                 | Returns                |
+| ----------- | ---------------------- | ---------------------- |
+| `sendEmail` | `GmailSendEmailParams` | `GmailSendEmailResult` |
+
+---
+
+## Mailso Adapter
+
+Factory pattern -- 1 method for email verification.
+
+```typescript
+const mailso = createMailsoAdapter('my-mailso-credential')
+```
+
+### Methods
+
+| Method        | Params                    | Returns                   |
+| ------------- | ------------------------- | ------------------------- |
+| `verifyEmail` | `MailsoVerifyEmailParams` | `MailsoVerifyEmailResult` |
+
+---
+
+For platform service adapters (scheduler, storage, llm, pdf, approval, acqDb, notifications, execution, email), see [Platform Adapters](adapters-platform.mdx).
+
+**Last Updated:** 2026-03-05