Skip to main content
Super Durable
Menu

Dex Connector Contributor

View as Markdown

Dex Connector Contributor is a specialist sub-skill. It adds one capability to the official Dex Connectors Library, tests it, and submits it upstream as one pull request that is easy to review.

Language requirements

Every new official Connector needs a Go implementation. The Go implementation is the tested reference. Python and TypeScript packages are optional, and they may implement only some of the capabilities. They must pass the conformance scenarios recorded from the Go implementation.

Applications can use released Connectors from Go, Python, and TypeScript. The detailed rules are in the library's AGENTS.md and docs/.

Install and use

Install Dex Skills once; it installs all three Skills. Then call this Skill in your coding agent, for example in Codex and in Claude Code with the Plugin:

$dex-connector-contributor Add <XYZ> to Dex official connector library
/superdurable-dex:dex-connector-contributor Add <XYZ> to Dex official connector library

Install and use Dex Skills has the invocation for every host.

If your application only uses a released Connector, use Dex App Builder or Dex SDK instead.

Scope and source requirements

The skill works only in the official Connector library. It starts from the provider's documented public API or official SDK. It checks the provider's authentication scopes, rate limits, idempotency support, pagination, event acknowledgement, and failure behavior.

It stays within what the provider documents publicly: no scraping of private endpoints, copying of browser credentials, or reverse-engineering of internal protocols.

Repository and fork workflow

The skill first looks for your GitHub fork of superdurable/dex-connectors-library and checks it. If you have no fork, it asks your permission and opens GitHub's fork page. You click Create fork. Only then does the agent clone the fork and start work.

In the local clone, your fork is origin and the official repository is upstream. The agent works on its own codex/ branch, created from the latest upstream/main. It leaves unrelated local changes untouched.

Contribution workflow

The skill follows this order:

  1. Confirm the provider capability and its public contract.
  2. Update connector.yaml before writing provider code.
  3. Run code generation. Config, Credentials, definitions, branches, operation factories, UI constants, and defaults stay generated, never hand-written.
  4. Implement the provider adapter and the tests that call the provider.
  5. Add Trigger and configuration UI behavior when needed.
  6. Add or extend a runnable example inside the Connector module.
  7. Run every required check, and check that the registry and catalog still match the code.
  8. Commit one clean change that touches only this module, push it to your fork, open an upstream pull request that is ready for review, and watch the required CI.

Durability and security boundaries

  • Provider calls run only in the Execute method of a Connector Step.
  • RPCs only route requests or change Dex state. They never call providers.
  • Calls that change data at the provider are idempotent. When the result of such a call is unknown, the Connector first queries the provider to find out what happened.
  • Credentials and raw secrets stay out of Flow input, Attributes, Results, receipts, Streams, logs, fixtures, generated values, or release artifacts.
  • Each module pins an exact published Dex Go SDK version. Branches, SHAs, pseudo-versions, and local replacements are never committed.
  • Each pull request releases one Connector module. The only exception is a mechanical change that must touch the whole repository.

A Connector may need something the Dex SDK does not offer yet. You can test the SDK change and the Connector together locally. The SDK change must be released before the Connector pull request can use it.

Example and verification gates

A new Connector or major capability usually comes with a runnable local example. If the Connector has a Trigger, the example shows real provider events starting a typed Flow or calling an RPC. It also shows that duplicate events and restarts are handled. Without a Trigger, the example produces a valid FDG 2.0 graph and runs from the Start Flow button in Dex Web.

The contribution is complete only when all of these pass: race tests and vet for the module on its own, generated-code checks, catalog checks, integration with a real Dex server, compatibility with the current version, the relevant UI tests and builds, and the repository checks. When credentials are available, safe tests also run against the live provider. Otherwise the pull request states exactly which live behavior was not tested.

Relationship to App Builder

App Builder hands work to this skill only after it confirms that an official Connector capability the application needs is missing or broken. While the contribution is in review, the application can use a local override that is not committed. It is not ready for production until the Connector is released with an exact version.

Return to Dex Skills overview and installation.