@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/references/integrations.md

@@ -0,0 +1,914 @@
+# Unmeshed Integrations — Input Schemas
+
+All integrations use `"type": "INTEGRATION"` as the step type.
+The `input.type` field selects the specific integration.
+
+---
+
+## LLM — Claude (Anthropic)
+
+**`input.type`**: `"llm-claude"`
+
+```json
+{
+  "type": "llm-claude",
+  "name": "unmeshed",
+  "publishProperties": {
+    "allowedTokens": 500,
+    "temperature": 0.1
+  },
+  "messageBody": {
+    "systemPrompt": "You are a ... Return only valid JSON. Do not include markdown or explanation.",
+    "userPrompt": "Your prompt here with {{steps.<ref>.output.result.<field>}} references.\n\nReturn JSON in this exact format:\n{ ... }"
+  }
+}
+```
+
+**Rules:**
+- Always instruct the model to return only JSON in the system prompt when structured output is needed
+- `allowedTokens`: max tokens — can be a number `500` or a string `"100"` — both are valid
+- `temperature`: 0.0–0.1 for deterministic/classification tasks; 0.5–0.9 for generative/creative
+- Output accessed via `steps.<ref>.output.results.<field>` (note: `.results` not `.result`)
+- Always defensively access both: `steps.<ref>.output.results || steps.<ref>.output.result || {}`
+- The `name` field references the configured Claude connection name in Unmeshed (typically `"unmeshed"`)
+
+---
+
+## MongoDB
+
+**`input.type`**: `"mongodb"`
+
+All operations use `publishProperties.collection` and `messageBody.collection` (both required).
+The connection `name` must match the configured MongoDB connection in Unmeshed.
+
+### FIND_ONE
+```json
+{
+  "type": "mongodb",
+  "name": "mongo-test",
+  "publishProperties": { "collection": "users" },
+  "messageBody": {
+    "operation": "FIND_ONE",
+    "collection": "users",
+    "filter": { "email": "user@example.com" }
+  }
+}
+```
+Output: `steps.<ref>.output.results.<field>` (document fields directly on `.results`)
+
+### INSERT_ONE
+```json
+{
+  "messageBody": {
+    "operation": "INSERT_ONE",
+    "collection": "users",
+    "document": {
+      "name": "test user",
+      "email": "test@example.com",
+      "password": "hashed"
+    }
+  }
+}
+```
+
+### UPDATE_ONE
+```json
+{
+  "messageBody": {
+    "operation": "UPDATE_ONE",
+    "collection": "users",
+    "filter": { "email": "user@example.com" },
+    "update": { "$set": { "name": "New Name" } }
+  }
+}
+```
+
+### DELETE_ONE
+```json
+{
+  "messageBody": {
+    "operation": "DELETE_ONE",
+    "collection": "users",
+    "filter": { "email": "user@example.com" }
+  }
+}
+```
+
+### COUNT
+```json
+{
+  "messageBody": {
+    "operation": "COUNT",
+    "collection": "users"
+  }
+}
+```
+Output: `steps.<ref>.output.results.count`
+
+### CREATE_COLLECTION / DELETE_COLLECTION
+```json
+{ "messageBody": { "operation": "CREATE_COLLECTION", "collection": "my_collection" } }
+{ "messageBody": { "operation": "DELETE_COLLECTION", "collection": "my_collection" } }
+```
+Output: `steps.<ref>.output.results.success` (boolean)
+
+### LIST_INDEXES
+```json
+{ "messageBody": { "operation": "LIST_INDEXES", "collection": "users" } }
+```
+Output: `steps.<ref>.output.results.result` (array of index objects, each with a `.key` field)
+
+### CREATE_INDEX
+```json
+{
+  "messageBody": {
+    "operation": "CREATE_INDEX",
+    "collection": "users",
+    "indexName": "my_index",
+    "index": { "name": 1, "email": -1 }
+  }
+}
+```
+Index direction: `1` = ascending, `-1` = descending
+
+### DROP_INDEX
+```json
+{ "messageBody": { "operation": "DROP_INDEX", "collection": "users", "indexName": "my_index" } }
+```
+
+**MongoDB output access patterns:**
+```javascript
+steps.<ref>.output.results.<field>        // FIND_ONE document fields
+steps.<ref>.output.results.count          // COUNT
+steps.<ref>.output.results.success        // CREATE/DELETE_COLLECTION
+steps.<ref>.output.results.result         // LIST_INDEXES (array)
+steps.<ref>.output.results.result.length  // number of indexes
+steps.<ref>.output.results.result[n].key  // index key definition
+```
+
+---
+
+## Redis
+
+**`input.type`**: `"redis"`
+
+`publishProperties` is always `{}`. All config goes in `messageBody`.
+
+### SET
+```json
+{
+  "type": "redis",
+  "name": "redis_integration",
+  "publishProperties": {},
+  "messageBody": {
+    "operation": "SET",
+    "key": "user:1",
+    "value": "John Doe"
+  }
+}
+```
+`value` can be a string or a JSON object — Redis stores objects as serialized JSON.
+
+### GET
+```json
+{ "messageBody": { "operation": "GET", "key": "user:1" } }
+```
+Output: `steps.<ref>.output.results.result` (string) or `steps.<ref>.output.results.<field>` (object fields directly if value was an object)
+
+### DEL
+```json
+{ "messageBody": { "operation": "DEL", "keys": ["user:1", "user:2"] } }
+```
+`keys` is always an array.
+
+### KEYS (pattern match)
+```json
+{ "messageBody": { "operation": "KEYS", "pattern": "user:*" } }
+```
+Output: `steps.<ref>.output.results.result` (array of matching key strings)
+
+### TYPE
+```json
+{ "messageBody": { "operation": "TYPE", "key": "user:1" } }
+```
+Output: `steps.<ref>.output.results.result` (string: `"string"`, `"hash"`, `"list"`, `"set"`, `"zset"`)
+
+### RENAME
+```json
+{ "messageBody": { "operation": "RENAME", "oldKey": "user:10", "newKey": "user:profile:10" } }
+```
+
+### EVAL (Lua scripting)
+```json
+{
+  "messageBody": {
+    "operation": "EVAL",
+    "script": "return redis.call('SET', KEYS[1], ARGV[1])",
+    "keys": ["user:2"],
+    "args": ["value"]
+  }
+}
+```
+Output: `steps.<ref>.output.results.result`
+
+**Redis output access patterns:**
+```javascript
+steps.<ref>.output.results.result         // string value, array (KEYS), or Lua script result
+steps.<ref>.output.results.<field>        // object fields when value was stored as JSON object
+// Example: if SET key="user:10" value={"name":"Alice","age":30}
+// then GET → steps.<ref>.output.results.name === "Alice"
+//           steps.<ref>.output.results.age === 30
+```
+
+---
+
+## Airtable
+
+**`input.type`**: `"airtable"`
+
+`publishProperties` is always `{}`. All config goes in `messageBody`.
+
+### GET_TABLES
+```json
+{
+  "type": "airtable",
+  "name": "airtable-test",
+  "publishProperties": {},
+  "messageBody": {
+    "action": "GET_TABLES"
+  }
+}
+```
+Output: `steps.<ref>.output.tables` (array of table objects with `.name`, `.id`)
+Access first table: `steps.<ref>.output.tables[0].name`
+
+### LIST (read all records)
+```json
+{
+  "messageBody": {
+    "action": "LIST",
+    "tableName": "{{ steps.get_all_tables.output.tables[0].name }}",
+    "pageSize": "100",
+    "maxRecords": "100"
+  }
+}
+```
+Output: `steps.<ref>.output.records` (array of record objects)
+Each record: `{ id, fields: { FieldName: value } }`
+
+### CREATE
+```json
+{
+  "messageBody": {
+    "action": "CREATE",
+    "tableName": "Table 1",
+    "records": [
+      { "fields": { "Name": "Sample", "Email": "user@example.com" } }
+    ]
+  }
+}
+```
+Output: `steps.<ref>.output.records[0].id` — the created record ID
+
+### READ (single record by ID)
+```json
+{
+  "messageBody": {
+    "action": "READ",
+    "tableName": "Table 1",
+    "recordId": "{{ steps.<ref>.output.records[0].id }}"
+  }
+}
+```
+Output: `steps.<ref>.output.fields.<FieldName>`
+
+### UPDATE
+```json
+{
+  "messageBody": {
+    "action": "UPDATE",
+    "tableName": "Table 1",
+    "records": [
+      {
+        "id": "{{ steps.<ref>.output.records[0].id }}",
+        "fields": { "Email": "new@example.com" }
+      }
+    ]
+  }
+}
+```
+
+### DELETE
+```json
+{
+  "messageBody": {
+    "action": "DELETE",
+    "tableName": "Table 1",
+    "recordIds": ["{{ steps.<ref>.output.records[0].id }}"]
+  }
+}
+```
+
+**Airtable rules:**
+- `tableName` can be a static string or a `{{...}}` template (e.g. `steps.get_all_tables.output.tables[0].name`)
+- `pageSize` and `maxRecords` are strings, not numbers: `"100"` not `100`
+- Mark upstream Airtable steps `optional: true` when rate-limiting is possible; use a SWITCH after to check for `HTTP 429` errors
+- Rate-limit check script: `steps.get_all_tables.output.error?.includes("HTTP 429 429 TOO_MANY_REQUESTS")`
+
+---
+
+## Jira
+
+**`input.type`**: `"jira"`
+
+All operations use `publishProperties` (no `messageBody` payload). The `action` field in `publishProperties` selects the operation.
+
+```json
+{
+  "type": "jira",
+  "name": "jira-test",
+  "publishProperties": {
+    "action": "<ACTION>",
+    "project_key": "KAN",
+    "issue_type": "Task",
+    "summary": "Issue summary",
+    "description": "Description",
+    "priority": "Medium",
+    "assignee": "",
+    ...
+  },
+  "messageBody": {}
+}
+```
+
+### GET_ISSUE
+```json
+{ "action": "GET_ISSUE", "issue_key": "KAN-2", "fields": "*all" }
+```
+Output: `steps.<ref>.output.status`, `steps.<ref>.output.summary`, `steps.<ref>.output.description`, etc.
+
+### SEARCH_ISSUES
+```json
+{ "action": "SEARCH_ISSUES", "jql": "project = KAN AND issuetype = Bug", "maxResults": "100", "fields": "*all" }
+```
+Output: `steps.<ref>.output.issues` (array)
+Each issue: `steps.<ref>.output.issues[0].key`, `steps.<ref>.output.issues[0].fields.summary`, `steps.<ref>.output.issues[0].fields.description.content[0].content[0].text`
+
+### CREATE_ISSUE
+```json
+{
+  "action": "CREATE_ISSUE",
+  "project_key": "KAN",
+  "issue_type": "Task",
+  "summary": "Issue summary",
+  "description": "Description",
+  "priority": "Medium",
+  "assignee": "",
+  "labels": ["backend", "testing"],
+  "components": ["API", "Backend"]
+}
+```
+Output: `steps.<ref>.output.key` (e.g. `"KAN-5"`)
+
+### DELETE_ISSUE
+```json
+{ "action": "DELETE_ISSUE", "issue_key": "{{ steps.create_issue.output.key }}" }
+```
+Output: `steps.<ref>.output.message` (e.g. `"Issue deleted successfully"`)
+
+### ADD_COMMENT
+```json
+{ "action": "ADD_COMMENT", "issue_key": "KAN-1", "body": "Comment text" }
+```
+Output: `steps.<ref>.output.id` (comment ID)
+
+### GET_COMMENTS
+```json
+{ "action": "GET_COMMENTS", "issue_key": "KAN-1" }
+```
+Output: `steps.<ref>.output.comments` (array)
+Comment text: `steps.<ref>.output.comments[0].body.content[0].content[0].text`
+
+### UPDATE_COMMENT
+```json
+{ "action": "UPDATE_COMMENT", "issue_key": "KAN-1", "comment_id": "{{ steps.add_comment.output.id }}", "body": "Updated text" }
+```
+
+### DELETE_COMMENT
+```json
+{ "action": "DELETE_COMMENT", "issue_key": "KAN-1", "comment_id": "{{ steps.add_comment.output.id }}" }
+```
+
+### GET_TRANSITIONS
+```json
+{ "action": "GET_TRANSITIONS", "issue_key": "KAN-1" }
+```
+Output: `steps.<ref>.output.transitions` (array of transition objects)
+
+### GET_ATTACHMENTS
+```json
+{ "action": "GET_ATTACHMENTS", "issue_key": "KAN-1" }
+```
+Output: `steps.<ref>.output.attachments` (array), each with `.filename`, `.id`, `.content`
+
+### SEARCH_USERS
+```json
+{ "action": "SEARCH_USERS", "query": ".", "maxResults": "100" }
+```
+Output: `steps.<ref>.output.users` (array)
+
+### GET_CURRENT_USER
+```json
+{ "action": "GET_CURRENT_USER" }
+```
+Output: `steps.<ref>.output.emailAddress`, `steps.<ref>.output.displayName`
+
+**Jira rules:**
+- `messageBody` is always `{}`
+- `maxResults` is a string: `"100"` not `100`
+- `fields`: `"*all"` returns all fields; omit to get default fields only
+- Comment body uses Atlassian Document Format (ADF) — nested `content[0].content[0].text` to reach plain text
+- Always add a WAIT step after CREATE_ISSUE before attempting DELETE_ISSUE to avoid race conditions
+
+---
+
+## Microsoft Outlook
+
+**`input.type`**: `"ms-outlook"`
+
+```json
+{
+  "type": "ms-outlook",
+  "name": "devs-a-outlook-integration",
+  "publishProperties": {
+    "mailBox": "user@company.io",
+    "action": "<ACTION>",
+    "folderId": "<folder-id>",
+    "folderName": "Inbox",
+    "folderParentId": "<parent-folder-id>",
+    "receivedFromMinutesAgo": "60",
+    "receivedUntilMinutesAgo": "0",
+    "readStatusFilter": "UNREAD",
+    "messagesInputType": "STEP_REF",
+    "markAs": "READ",
+    "fromFilter": "",
+    "includeAttachments": true
+  },
+  "messageBody": {}
+}
+```
+
+### readEmail
+```json
+{ "action": "readEmail", "mailBox": "user@company.io", "readStatusFilter": "UNREAD", "includeAttachments": true }
+```
+Output: `steps.<ref>.output.messages` (array of email objects)
+Each message: `.subject`, `.from`, `.body`, `.attachments` (array with `.name`, `.contentBytes`)
+Attachments are saved to `/app/files/_outlook_attachments_/` on the Unmeshed filesystem.
+
+### sendEmail
+```json
+{
+  "action": "sendEmail",
+  "mailBox": "DEFAULT",
+  "subject": "Email subject",
+  "to": "recipient@example.com",
+  "body": "<html><p>Email body</p></html>",
+  "attachments": "{{ steps.python_1.output.result.attachments }}"
+}
+```
+- `mailBox: "DEFAULT"` uses the configured mailbox
+- `body` can be HTML string
+- `attachments`: array of objects with `{ name, contentType, type: "CONTENT_BYTES", contentBase64 }` — build this in a preceding PYTHON step
+
+### markReadUnread
+```json
+{
+  "action": "markReadUnread",
+  "markAs": "READ",
+  "messagesInputType": "STEP_REF",
+  "stepRef": "read"
+}
+```
+- `messagesInputType: "STEP_REF"` — takes messages from a previous readEmail step
+- `stepRef`: the `ref` of the readEmail step to mark
+
+**Outlook rules:**
+- `folderId` and `folderParentId` are opaque Outlook folder ID strings (from Outlook API)
+- `receivedFromMinutesAgo` and `receivedUntilMinutesAgo` are strings: `"60"` not `60`
+- `messageBody` is always `{}`
+- Use `errorPolicyName: "retry_ep"` on readEmail steps — email delivery can have slight delays
+- Pattern: SUB_PROCESS (trigger send) → WAIT (allow delivery) → readEmail → assert on messages
+
+---
+
+## Google Sheets
+
+**`input.type`**: `"google-sheets"`
+
+### CREATE_SPREADSHEET
+```json
+{
+  "type": "google-sheets",
+  "name": "g-sheets",
+  "publishProperties": {
+    "action": "CREATE_SPREADSHEET",
+    "title": "{{ steps.<ref>.output.result.<titleField> }}"
+  },
+  "messageBody": {}
+}
+```
+Output: `steps.<ref>.output.spreadsheetId`
+
+### APPEND_ROWS
+```json
+{
+  "publishProperties": {
+    "action": "APPEND_ROWS",
+    "spreadsheetId": "{{ steps.<ref>.output.spreadsheetId }}",
+    "range": "Sheet1!A:Z",
+    "values": [["col1_value", "col2_value"]]
+  },
+  "messageBody": {}
+}
+```
+
+### GET_ROWS
+```json
+{
+  "publishProperties": { "action": "GET_ROWS", "spreadsheetId": "<id>", "range": "Sheet1!A:Z" },
+  "messageBody": {}
+}
+```
+Output: `steps.<ref>.output.result.rows`
+
+**Rules:**
+- `values` is a 2D array — each inner array is one row
+- Common pattern: CREATE → store ID in PERSISTED_STATE → APPEND on subsequent runs
+
+---
+
+## Google Drive
+
+**`input.type`**: `"google-drive"`
+
+### UPLOAD_FROM_UNMESHED_FILES
+```json
+{
+  "type": "google-drive",
+  "name": "google-drive",
+  "publishProperties": {
+    "action": "UPLOAD_FROM_UNMESHED_FILES",
+    "folderId": "REPLACE_WITH_GOOGLE_DRIVE_FOLDER_ID",
+    "fileName": "{{ steps.<ref>.output.result.fileName }}",
+    "fileLocation": "{{ steps.<ref>.output.result.location }}",
+    "unmeshedFilePath": "{{ steps.<ref>.output.result.location }}/{{ steps.<ref>.output.result.fileName }}",
+    "googleDrivePath": "/"
+  },
+  "messageBody": {}
+}
+```
+Output: `steps.<ref>.output.id`, `steps.<ref>.output.webViewLink`, `steps.<ref>.output.webContentLink`
+
+---
+
+## Gmail
+
+Gmail has **two separate integration types** depending on whether you only need to send, or also need to read:
+
+| `input.type` | `name` | Use when |
+|---|---|---|
+| `"google-gmail-send"` | your send-only connection | sending email only |
+| `"google-gmail-read-send"` | your read+send connection | sending, reading, or marking email |
+
+---
+
+### Send email (send-only connection)
+
+**`input.type`**: `"google-gmail-send"`
+
+```json
+{
+  "type": "google-gmail-send",
+  "name": "unmeshed-mail",
+  "publishProperties": {
+    "action": "sendEmail",
+    "subject": "Your subject here",
+    "to": "{{ steps.<ref>.output.result.email }}",
+    "cc": "",
+    "bcc": "",
+    "body": "Email body text or HTML",
+    "bodyContentType": "plain",
+    "from": "sender@yourdomain.com"
+  },
+  "messageBody": {}
+}
+```
+
+---
+
+### Send email (read+send connection)
+
+**`input.type`**: `"google-gmail-read-send"`
+
+```json
+{
+  "type": "google-gmail-read-send",
+  "name": "gmail-read-send",
+  "publishProperties": {
+    "action": "sendEmail",
+    "subject": "Your subject here",
+    "to": "{{ steps.<ref>.output.result.email }}",
+    "cc": "",
+    "bcc": "",
+    "body": "Email body text or HTML",
+    "bodyContentType": "plain"
+  },
+  "messageBody": {}
+}
+```
+
+---
+
+### Read email
+
+**`input.type`**: `"google-gmail-read-send"`
+
+```json
+{
+  "type": "google-gmail-read-send",
+  "name": "unmeshed-mail",
+  "publishProperties": {
+    "action": "readEmail",
+    "userId": "",
+    "labelId": "INBOX",
+    "receivedFromMinutesAgo": "30",
+    "receivedUntilMinutesAgo": "0",
+    "fromFilter": "",
+    "subjectFilter": "",
+    "readStatusFilter": "ALL",
+    "includeAttachments": false,
+    "maxCount": 10
+  },
+  "messageBody": {}
+}
+```
+
+`readStatusFilter` options: `"ALL"`, `"READ"`, `"UNREAD"`
+
+---
+
+### Mark read / unread
+
+**`input.type`**: `"google-gmail-read-send"`
+
+```json
+{
+  "type": "google-gmail-read-send",
+  "name": "gmail-read-send",
+  "publishProperties": {
+    "action": "markReadUnread",
+    "messagesInputType": "STEP_REF",
+    "messageIds": "",
+    "stepRef": "<ref-of-readEmail-step>",
+    "markAs": "READ"
+  },
+  "messageBody": {}
+}
+```
+
+`messagesInputType`: `"STEP_REF"` to take messages from a prior readEmail step; `stepRef` is that step's `ref`.
+`markAs`: `"READ"` or `"UNREAD"`
+
+---
+
+**Gmail rules:**
+- `messageBody` is always `{}`
+- `action` is camelCase: `"sendEmail"`, `"readEmail"`, `"markReadUnread"` — not uppercase like other integrations
+- `bodyContentType`: `"plain"` for plain text, `"html"` for HTML body
+- `from` is only on the `google-gmail-send` type — omit it on `google-gmail-read-send`
+- `receivedFromMinutesAgo` and `receivedUntilMinutesAgo` are strings: `"30"` not `30`
+- `maxCount` is a number: `10` not `"10"`
+- The `name` field must match the connection configured in Unmeshed — check with your team which connection name to use
+
+---
+
+## Slack
+
+**`input.type`**: `"slack-messaging"`
+
+```json
+{
+  "type": "slack-messaging",
+  "name": "",
+  "publishProperties": { "durationType": "MINUTES", "receiverType": "CHANNEL" },
+  "messageBody": {
+    "type": "MESSAGE",
+    "message": "{{ steps.<ref>.output.result.slackMessage }}",
+    "messageBlocks": [
+      { "type": "section", "text": { "type": "mrkdwn", "text": "{{ steps.<ref>.output.result.slackMessage }}" } }
+    ]
+  }
+}
+```
+
+**Rules:**
+- `input.type` is `"slack-messaging"` not `"slack"`
+- Build the full message string in a preceding JAVASCRIPT step
+- `receiverType`: `"CHANNEL"` or `"USER"`
+
+---
+
+## Notion
+
+**`input.type`**: `"notion"`
+
+All operations go in `messageBody.operation`. `publishProperties` is `{}` or omitted.
+
+### CREATE_DATABASE
+```json
+{
+  "messageBody": {
+    "operation": "CREATE_DATABASE",
+    "parent": { "page_id": "<page-id>" },
+    "title": [{ "type": "text", "text": { "content": "DB Title" } }],
+    "properties": {
+      "Name": { "title": {} },
+      "Status": { "select": { "options": [{ "name": "Active", "color": "green" }] } },
+      "Due Date": { "date": {} },
+      "Tags": { "multi_select": { "options": [{ "name": "Bug", "color": "red" }] } },
+      "Progress": { "number": { "format": "percent" } },
+      "Notes": { "rich_text": {} },
+      "Completed": { "checkbox": {} }
+    },
+    "icon": { "emoji": "🗂️" },
+    "cover": { "external": { "url": "https://..." } }
+  }
+}
+```
+Output: `steps.<ref>.output.id` (database ID)
+
+### GET_DATABASE / UPDATE_DATABASE
+```json
+{ "operation": "GET_DATABASE", "database_id": "{{ steps.create_database.output.id }}" }
+{ "operation": "UPDATE_DATABASE", "database_id": "...", "title": [...], "description": [...] }
+```
+Output: `steps.<ref>.output.title[0].plain_text`
+
+### QUERY_DATABASE
+```json
+{
+  "operation": "QUERY_DATABASE",
+  "database_id": "{{ steps.create_database.output.id }}",
+  "filter": { "property": "Status", "select": { "equals": "In Progress" } },
+  "sorts": [{ "property": "Due Date", "direction": "ascending" }],
+  "page_size": 50
+}
+```
+Filter types: `select`, `multi_select` (`contains`), `date`, `checkbox`, `rich_text`, `number`
+Output: `steps.<ref>.output.results` (array of page objects)
+Record name: `steps.<ref>.output.results[0].properties.Name.title[0].plain_text`
+
+### CREATE_PAGE
+```json
+{
+  "operation": "CREATE_PAGE",
+  "parent": { "database_id": "{{ steps.create_database.output.id }}" },
+  "properties": {
+    "Name": { "title": [{ "text": { "content": "Page Title" } }] },
+    "Status": { "select": { "name": "In Progress" } },
+    "Tags": { "multi_select": [{ "name": "Feature" }] },
+    "Due Date": { "date": { "start": "2025-10-31" } },
+    "Progress": { "number": 0.45 },
+    "Notes": { "rich_text": [{ "text": { "content": "Note text" } }] },
+    "Completed": { "checkbox": false }
+  },
+  "children": [
+    { "object": "block", "type": "heading_2", "heading_2": { "rich_text": [{ "text": { "content": "Section" } }] } },
+    { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{ "text": { "content": "Text" } }] } },
+    { "object": "block", "type": "to_do", "to_do": { "rich_text": [{ "text": { "content": "Task" } }], "checked": false } }
+  ],
+  "icon": { "emoji": "🔐" }
+}
+```
+Output: `steps.<ref>.output.id` (page ID)
+
+### GET_PAGE / UPDATE_PAGE / DELETE_PAGE / ARCHIVE_PAGE
+```json
+{ "operation": "GET_PAGE", "page_id": "{{ steps.create_page_task_1.output.id }}" }
+{ "operation": "UPDATE_PAGE", "page_id": "...", "properties": { ... }, "icon": { "emoji": "🚀" } }
+{ "operation": "UPDATE_PAGE", "page_id": "...", "archived": true }  // archive
+{ "operation": "DELETE_PAGE", "page_id": "..." }
+```
+Output: `steps.<ref>.output.properties.Notes.rich_text[0].plain_text`
+Archived check: `steps.<ref>.output.archived` (boolean)
+Trashed check: `steps.<ref>.output.in_trash` (boolean)
+
+### GET_PAGE_PROPERTIES
+```json
+{ "operation": "GET_PAGE_PROPERTIES", "page_id": "...", "property_id": "title" }
+```
+
+### GET_BLOCK / UPDATE_BLOCK / DELETE_BLOCK
+```json
+{ "operation": "GET_BLOCK", "block_id": "{{ steps.create_page_task_1.output.id }}" }
+{ "operation": "UPDATE_BLOCK", "block_id": "{{ steps.get_block_children.output.results[0].id }}", "heading_2": { "rich_text": [{ "text": { "content": "Updated" } }] } }
+{ "operation": "DELETE_BLOCK", "block_id": "..." }
+```
+Output GET_BLOCK: `steps.<ref>.output.child_page.title` (for page blocks), `steps.<ref>.output.heading_2.rich_text[0].plain_text` (for heading blocks)
+Trashed check: `steps.<ref>.output.in_trash`
+
+### GET_BLOCK_CHILDREN / APPEND_BLOCK_CHILDREN
+```json
+{ "operation": "GET_BLOCK_CHILDREN", "block_id": "...", "page_size": 100 }
+{
+  "operation": "APPEND_BLOCK_CHILDREN",
+  "block_id": "...",
+  "children": [
+    { "object": "block", "type": "divider", "divider": {} },
+    { "object": "block", "type": "callout", "callout": { "rich_text": [{ "text": { "content": "Note" } }], "icon": { "emoji": "⚠️" }, "color": "yellow_background" } },
+    { "object": "block", "type": "numbered_list_item", "numbered_list_item": { "rich_text": [{ "text": { "content": "Step 1" } }] } },
+    { "object": "block", "type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [{ "text": { "content": "Item" } }] } },
+    { "object": "block", "type": "quote", "quote": { "rich_text": [{ "text": { "content": "Quote text" } }] } },
+    { "object": "block", "type": "toggle", "toggle": { "rich_text": [{ "text": { "content": "Toggle title" } }], "children": [...] } }
+  ]
+}
+```
+Output GET_BLOCK_CHILDREN: `steps.<ref>.output.results` (array), each with `.id`, `.type`
+
+### SEARCH
+```json
+{
+  "operation": "SEARCH",
+  "query": "Authentication",
+  "filter": { "property": "object", "value": "page" },
+  "sort": { "direction": "descending", "timestamp": "last_edited_time" },
+  "page_size": 20
+}
+```
+`filter.value`: `"page"` or `"database"` — omit `filter` to search both
+Output: `steps.<ref>.output.results` (array), `steps.<ref>.output.has_more` (boolean)
+
+### LIST_USERS / GET_USER
+```json
+{ "operation": "LIST_USERS", "page_size": 100 }
+{ "operation": "GET_USER", "user_id": "{{ steps.list_users.output.results[0].id }}" }
+```
+Output LIST_USERS: `steps.<ref>.output.results` (array), each with `.id`, `.type` (`"person"`), `.name`
+Output GET_USER: `steps.<ref>.output.person.email`
+
+**Notion rules:**
+- `publishProperties` is `{}` or omitted — all config in `messageBody`
+- `page_id` and `database_id` are 32-char hex strings (no hyphens in Unmeshed, but Notion API accepts both)
+- Block types supported in children: `heading_2`, `heading_3`, `paragraph`, `to_do`, `divider`, `callout`, `numbered_list_item`, `bulleted_list_item`, `quote`, `toggle`
+- `toggle` blocks support `children` array for nested content
+- Use `errorPolicyName: "retry_ep"` on QUERY_DATABASE steps that run soon after mutations
+- `UPDATE_PAGE` with `"archived": true` archives the page (soft delete); `DELETE_PAGE` puts it in trash (`in_trash: true`)
+
+---
+
+## PostgreSQL / MySQL
+
+**`input.type`**: `"postgres"` or `"mysql"`
+
+```json
+{
+  "type": "postgres",
+  "name": "postgres",
+  "publishProperties": {
+    "action": "EXECUTE_QUERY",
+    "query": "INSERT INTO table_name (col1, col2) VALUES ($1, $2)",
+    "params": ["{{ steps.<ref>.output.result.field1 }}", "{{ steps.<ref>.output.result.field2 }}"]
+  },
+  "messageBody": {}
+}
+```
+
+Output: `steps.<ref>.output.result.rows` (SELECT), `steps.<ref>.output.result.rowCount` (INSERT/UPDATE/DELETE)
+
+**Rules:**
+- Always parameterise queries — `$1`, `$2` for Postgres; `?` for MySQL
+- `params` is always an array of strings/values
+
+---
+
+## HTTP / REST API (as INTEGRATION)
+
+**`input.type`**: `"http"`
+
+```json
+{
+  "type": "http",
+  "name": "http",
+  "publishProperties": {
+    "method": "POST",
+    "url": "https://api.example.com/endpoint",
+    "headers": { "Content-Type": "application/json", "Authorization": "Bearer <token>" }
+  },
+  "messageBody": { "field1": "{{ steps.<ref>.output.result.value }}" }
+}
+```
+
+Output: `steps.<ref>.output.result` (response body), `steps.<ref>.output.status` (HTTP status code)
+
+**Note:** There is also a native `HTTP` step type (uppercase) with polling support — see step-types.md.