Connector
View as MarkdownA Connector connects a Flow to an external provider, such as an email, payment, or news service. It gives your Flow ready-made Steps that call the provider, and Triggers that turn provider events into Flow starts or RPC calls. Your application imports a Connector package and uses its Steps like your own. Provider credentials never enter durable Flow state.
Official Connectors are released separately from Dex. Before you write provider integration code yourself, find a Connector for that provider.
Capabilities
A Connector can expose five capabilities:
- Auth authorizes a named connection to the provider.
- Trigger turns a provider event into a typed event. The event can start a Flow or call a typed RPC.
- Query reads provider state from a Connector Step.
- Mutation changes provider state. It sends an idempotency key and handles calls whose outcome is unknown.
- UI supplies reusable configuration units. Dex Web combines them into the settings form for a Step or a Trigger binding.
A Connector exposes only the capabilities its provider needs. Your application uses the types generated for the exact Connector release it imports.
Operations are ready-made Steps
Each operation has a factory that creates a Connector Step. Your application maps the current Step input to the provider input. It connects each required result branch to another Step. The provider call runs in Execute, so it gets Dex retries, timeouts, durability, and recovery like any other Step.
A Connector result contains the operation output, a receipt, the selected branch, and a safe failure classification when one exists. The result does not carry the previous Step input forward. Keep business context in an Attribute, or pass it through an application Step before the Connector.
Only the happy-path branch must be connected. You can leave optional branches unconnected. If the Connector selects an unconnected branch, the Flow fails. The provider outcome stays visible for recovery.
Effect classes
Each operation is a Query or a Mutation. A Query reads provider state. A Mutation changes it. Each operation has an effect class that says what a repeated call does:
| Effect class | Operations | What a repeated call does |
|---|---|---|
| Read | Every Query | Changes nothing. |
| Idempotent write | A Mutation that its Connector marks safe to repeat | Makes no second effect. The Connector author has confirmed that the provider ignores a repeat with the same idempotency key. |
| Non-idempotent write | Every other Mutation | Can make a second effect. |
A Mutation sends the same idempotency key every time Dex retries its Step.
When a Mutation's outcome is unknown, the Connector selects an uncertainty branch. Connect it to a Step that queries the provider and reconciles. Do not send the Mutation again blindly.
Triggers start or update Flows
A Connector Trigger is a long-running event source outside the Flow. It keeps the provider event ID and occurrence time. It delivers each event at least once to a target that your application owns.
Your application supplies the final filter, resolves the Flow ID, and maps the provider event to a typed input. It chooses whether the event starts a Flow or calls a typed RPC on an existing Flow. A Flow start uses the provider event ID as its request ID, so a repeated event does not start a second Flow. An RPC target must handle duplicates itself, in its own bounded state.
Local Trigger runners save a matched event before they acknowledge it to the provider. After a restart, they deliver the events that were still pending.
Connections
A connection is a named, authorized account at a provider. Flow definitions refer to a connection by its name, not by its credentials. Your application resolves the name to credentials when it calls the provider.
Stored credentials never enter Flow input, Attributes, results, receipts, Streams, logs, or generated artifacts.
Languages
Connectors support Go, Python, and TypeScript. Java and Rust do not support Connectors yet. Each language package implements only the operations and Triggers that the Connector lists for that language. Use the language filter in the Connector catalog to see what each Connector offers.
Go packages are the Go module of each Connector. Python packages are on PyPI as dex-connector-<slug>. TypeScript packages are on npm as @superdurable/connector-<slug>. Every Python and TypeScript package is tested against the same provider scenarios that verify the Go package. Runnable examples are under connectors/<directory>/<language>/examples/ in the Dex Connectors Library. If you need another language, open a Dex Connectors Library issue.
Find a Connector
Browse the Connector catalog. It lists each released Connector, its operations, and its language support. The catalog is the reference for each Connector.
The Dex Connectors Library contains manifests, generated APIs, provider implementations, UI units, and runnable examples.
Use the Dex SDK skill when an application uses a released Connector. Use the Dex Connector Contributor skill to add or change an official Connector, operation, Trigger, or UI unit.
Set up Connectors locally
For local development, Dex Web configures Connector connections and Trigger bindings for a Go application. It does this only in dexcli dev.
- Start dexcli dev with your Flow Definition Graph directory.
- Open the Connectors page in Dex Web. It lists the connection names that your Flow definitions use. Authorize each one.
- Start your application with the connection file that Dex Web shows.
To use a connection that no Flow definition names, such as one an agent tool uses, add it by name on the same page. Then authorize it like any other.
Dex Web configures only the exact official Connector release. A Connector's UI runs in a sandboxed iframe, and stored credentials never enter it.
The connection file holds plaintext secrets for local use only. Do not commit it or use it in production.
Local Connector setup describes each step and its settings.