Skip to content

Commit 9ab64e5

Browse files
waleedlatif1waleedlatif1
authored
feat(integrations): add Convex integration with function execution and data export tools (#4981)
* feat(integrations): add Convex integration with function execution and data export tools * fix(convex): separate List Documents page cursor from deltas cursor and surface HTTP errors in transforms * fix(convex): rename List Documents pagination cursor to pageCursor end-to-end for unambiguous chaining * fix(convex): validate deployment URL with shared SSRF guard * improvement(convex): polish from final validation pass — reject query strings in deployment URL, validate object args, fix sync skill wording * docs(convex): note streaming export plan requirement on data-export tools (verified via live E2E)
1 parent 5ab6d0d commit 9ab64e5

20 files changed

Lines changed: 1368 additions & 0 deletions

File tree

‎apps/docs/components/icons.tsx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2056,6 +2056,32 @@ export function ConfluenceIcon(props: SVGProps<SVGSVGElement>) {
20562056
)
20572057
}
20582058

2059+
export function ConvexIcon(props: SVGProps<SVGSVGElement>) {
2060+
return (
2061+
<svg
2062+
{...props}
2063+
width='24'
2064+
height='24'
2065+
viewBox='31 31.5 122 125'
2066+
fill='none'
2067+
xmlns='http://www.w3.org/2000/svg'
2068+
>
2069+
<path
2070+
d='M108.092 130.021C126.258 128.003 143.385 118.323 152.815 102.167C148.349 142.128 104.653 167.385 68.9858 151.878C65.6992 150.453 62.8702 148.082 60.9288 145.034C52.9134 132.448 50.2786 116.433 54.0644 101.899C64.881 120.567 86.8748 132.01 108.092 130.021Z'
2071+
fill='#F3B01C'
2072+
/>
2073+
<path
2074+
d='M53.4012 90.1735C46.0375 107.191 45.7186 127.114 54.7463 143.51C22.9759 119.608 23.3226 68.4578 54.358 44.7949C57.2286 42.6078 60.64 41.3097 64.2178 41.1121C78.9312 40.336 93.8804 46.0225 104.364 56.6193C83.0637 56.831 62.318 70.4756 53.4012 90.1735Z'
2075+
fill='#8D2676'
2076+
/>
2077+
<path
2078+
d='M114.637 61.8552C103.89 46.8701 87.0686 36.6684 68.6387 36.358C104.264 20.1876 148.085 46.4045 152.856 85.1654C153.3 88.7635 152.717 92.4322 151.122 95.6775C144.466 109.195 132.124 119.679 117.702 123.559C128.269 103.96 126.965 80.0151 114.637 61.8552Z'
2079+
fill='#EE342F'
2080+
/>
2081+
</svg>
2082+
)
2083+
}
2084+
20592085
export function TwilioIcon(props: SVGProps<SVGSVGElement>) {
20602086
return (
20612087
<svg {...props} xmlns='http://www.w3.org/2000/svg' viewBox='-8 -8 272 272'>

‎apps/docs/components/ui/icon-mapping.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ import {
3838
CloudWatchIcon,
3939
CodePipelineIcon,
4040
ConfluenceIcon,
41+
ConvexIcon,
4142
CrowdStrikeIcon,
4243
CursorIcon,
4344
DagsterIcon,
@@ -259,6 +260,7 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
259260
codepipeline: CodePipelineIcon,
260261
confluence: ConfluenceIcon,
261262
confluence_v2: ConfluenceIcon,
263+
convex: ConvexIcon,
262264
crowdstrike: CrowdStrikeIcon,
263265
cursor: CursorIcon,
264266
cursor_v2: CursorIcon,

‎apps/docs/content/docs/en/integrations/convex.mdx‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: Convex
3+
description: Use Convex database
4+
---
5+
6+
import { BlockInfoCard } from "@/components/ui/block-info-card"
7+
8+
<BlockInfoCard
9+
type="convex"
10+
color="#FFFFFF"
11+
/>
12+
13+
{/* MANUAL-CONTENT-START:intro */}
14+
[Convex](https://www.convex.dev/) is an open-source reactive backend platform that combines a document database, serverless functions, and real-time sync in one developer-friendly package. Instead of writing SQL, you define queries, mutations, and actions in TypeScript that run right next to your data, and every client subscribed to a query updates automatically when the underlying data changes.
15+
16+
**Why Convex?**
17+
18+
- **Functions as the API:** Queries (reads), mutations (transactional writes), and actions (side effects like calling external APIs) are the building blocks of your backend — typed, versioned, and deployed together.
19+
- **Reactive by default:** Query results update live as data changes, with no cache invalidation or polling logic to maintain.
20+
- **Transactional writes:** Mutations run as ACID transactions with serializable isolation, so your data stays consistent without manual locking.
21+
- **Built-in schema awareness:** Convex tracks the shape of every table, so tooling can introspect your data model without a separate migration system.
22+
23+
**Using Convex in Sim**
24+
25+
Sim's Convex integration connects your workflows to any Convex deployment with two fields: the deployment URL and a deploy key from the dashboard Settings page. From there you can:
26+
27+
- **Run functions:** Call query, mutation, and action functions with named JSON arguments — or use Run Function when you don't want to specify the function type.
28+
- **Inspect your data model:** List Tables returns every table in the deployment with the JSON schema of its documents.
29+
- **Export and sync data:** List Documents pages through a consistent snapshot of a table, and Document Deltas returns only the documents that changed since a snapshot — including deletions — making incremental syncs to warehouses, search indexes, or other tools straightforward.
30+
31+
The Run Query, Run Mutation, Run Action, and Run Function operations work on every Convex plan. List Tables, List Documents, and Document Deltas use Convex's streaming export API, which is available on Convex paid plans.
32+
33+
Typical patterns include agents that read and write application data through your existing Convex functions, scheduled exports to analytics destinations, and change-driven automations that react to new or updated documents.
34+
{/* MANUAL-CONTENT-END */}
35+
36+
37+
## Usage Instructions
38+
39+
Integrate Convex into the workflow. Run query, mutation, and action functions on your deployment, list tables with their schemas, and export documents with snapshot pagination and change deltas.
40+
41+
42+
43+
## Actions
44+
45+
### `convex_query`
46+
47+
Run a Convex query function and return its result
48+
49+
#### Input
50+
51+
| Parameter | Type | Required | Description |
52+
| --------- | ---- | -------- | ----------- |
53+
| `deploymentUrl` | string | Yes | Convex deployment URL \(e.g., https://your-deployment.convex.cloud\) |
54+
| `deployKey` | string | Yes | Convex deploy key from the dashboard Settings page |
55+
| `functionPath` | string | Yes | Path to the query function \(e.g., messages:list or folder/file:myQuery\) |
56+
| `args` | json | No | Named arguments to pass to the function as a JSON object |
57+
58+
#### Output
59+
60+
| Parameter | Type | Description |
61+
| --------- | ---- | ----------- |
62+
| `value` | json | Result returned by the query function |
63+
| `logLines` | array | Log lines printed during the function execution |
64+
65+
### `convex_mutation`
66+
67+
Run a Convex mutation function to write data and return its result
68+
69+
#### Input
70+
71+
| Parameter | Type | Required | Description |
72+
| --------- | ---- | -------- | ----------- |
73+
| `deploymentUrl` | string | Yes | Convex deployment URL \(e.g., https://your-deployment.convex.cloud\) |
74+
| `deployKey` | string | Yes | Convex deploy key from the dashboard Settings page |
75+
| `functionPath` | string | Yes | Path to the mutation function \(e.g., messages:send or folder/file:myMutation\) |
76+
| `args` | json | No | Named arguments to pass to the function as a JSON object |
77+
78+
#### Output
79+
80+
| Parameter | Type | Description |
81+
| --------- | ---- | ----------- |
82+
| `value` | json | Result returned by the mutation function |
83+
| `logLines` | array | Log lines printed during the function execution |
84+
85+
### `convex_action`
86+
87+
Run a Convex action function and return its result
88+
89+
#### Input
90+
91+
| Parameter | Type | Required | Description |
92+
| --------- | ---- | -------- | ----------- |
93+
| `deploymentUrl` | string | Yes | Convex deployment URL \(e.g., https://your-deployment.convex.cloud\) |
94+
| `deployKey` | string | Yes | Convex deploy key from the dashboard Settings page |
95+
| `functionPath` | string | Yes | Path to the action function \(e.g., emails:send or folder/file:myAction\) |
96+
| `args` | json | No | Named arguments to pass to the function as a JSON object |
97+
98+
#### Output
99+
100+
| Parameter | Type | Description |
101+
| --------- | ---- | ----------- |
102+
| `value` | json | Result returned by the action function |
103+
| `logLines` | array | Log lines printed during the function execution |
104+
105+
### `convex_run_function`
106+
107+
Run any Convex function (query, mutation, or action) by path without specifying its type
108+
109+
#### Input
110+
111+
| Parameter | Type | Required | Description |
112+
| --------- | ---- | -------- | ----------- |
113+
| `deploymentUrl` | string | Yes | Convex deployment URL \(e.g., https://your-deployment.convex.cloud\) |
114+
| `deployKey` | string | Yes | Convex deploy key from the dashboard Settings page |
115+
| `functionPath` | string | Yes | Path to the function \(e.g., messages:list or folder/file:myFunction\) |
116+
| `args` | json | No | Named arguments to pass to the function as a JSON object |
117+
118+
#### Output
119+
120+
| Parameter | Type | Description |
121+
| --------- | ---- | ----------- |
122+
| `value` | json | Result returned by the function |
123+
| `logLines` | array | Log lines printed during the function execution |
124+
125+
### `convex_list_tables`
126+
127+
List all tables in a Convex deployment along with their JSON schemas. Requires streaming export, available on Convex paid plans.
128+
129+
#### Input
130+
131+
| Parameter | Type | Required | Description |
132+
| --------- | ---- | -------- | ----------- |
133+
| `deploymentUrl` | string | Yes | Convex deployment URL \(e.g., https://your-deployment.convex.cloud\) |
134+
| `deployKey` | string | Yes | Convex deploy key from the dashboard Settings page |
135+
136+
#### Output
137+
138+
| Parameter | Type | Description |
139+
| --------- | ---- | ----------- |
140+
| `tables` | array | Names of the tables in the deployment |
141+
| `schemas` | json | Map of table name to the JSON schema of its documents |
142+
143+
### `convex_list_documents`
144+
145+
List documents from a Convex table via a paginated snapshot. Pass the returned snapshot and page cursor back in to fetch the next page. Requires streaming export, available on Convex paid plans.
146+
147+
#### Input
148+
149+
| Parameter | Type | Required | Description |
150+
| --------- | ---- | -------- | ----------- |
151+
| `deploymentUrl` | string | Yes | Convex deployment URL \(e.g., https://your-deployment.convex.cloud\) |
152+
| `deployKey` | string | Yes | Convex deploy key from the dashboard Settings page |
153+
| `tableName` | string | No | Table to list documents from. Omit to list documents from all tables. |
154+
| `snapshot` | string | No | Snapshot timestamp from a previous page. Omit on the first request to start a new snapshot. |
155+
| `pageCursor` | string | No | Page cursor from a previous page of the same snapshot. Omit on the first request. |
156+
157+
#### Output
158+
159+
| Parameter | Type | Description |
160+
| --------- | ---- | ----------- |
161+
| `documents` | array | Documents in this page of the snapshot |
162+
| `hasMore` | boolean | Whether more pages remain in the snapshot |
163+
| `snapshot` | string | Snapshot timestamp to pass back in when fetching the next page |
164+
| `pageCursor` | string | Page cursor to pass back in when fetching the next page |
165+
166+
### `convex_document_deltas`
167+
168+
List documents that changed after a snapshot or previous delta cursor. Deleted documents are returned with a _deleted flag. Requires streaming export, available on Convex paid plans.
169+
170+
#### Input
171+
172+
| Parameter | Type | Required | Description |
173+
| --------- | ---- | -------- | ----------- |
174+
| `deploymentUrl` | string | Yes | Convex deployment URL \(e.g., https://your-deployment.convex.cloud\) |
175+
| `deployKey` | string | Yes | Convex deploy key from the dashboard Settings page |
176+
| `cursor` | string | Yes | Timestamp cursor to read deltas after. Use the snapshot value from List Documents or the cursor from a previous Document Deltas page. |
177+
| `tableName` | string | No | Table to read deltas from. Omit to read deltas from all tables. |
178+
179+
#### Output
180+
181+
| Parameter | Type | Description |
182+
| --------- | ---- | ----------- |
183+
| `documents` | array | Changed documents, each including _table and _ts fields |
184+
| `hasMore` | boolean | Whether more delta pages remain |
185+
| `cursor` | string | Cursor to pass back in when fetching the next page of deltas |
186+
187+

‎apps/docs/content/docs/en/integrations/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
"cloudwatch",
3636
"codepipeline",
3737
"confluence",
38+
"convex",
3839
"crowdstrike",
3940
"cursor",
4041
"dagster",

0 commit comments

Comments
 (0)