Connectors

What a connector is

A connector is a small Fastify service that:

1. Accepts gateway requests authenticated with X-Synchronity-Connector-Key.
2. Translates them into the storefront's native API call (Shopify GraphQL, Woo REST, your custom endpoints).
3. Reshapes the response into AMPS — the unified protocol the gateway speaks.

The gateway never talks to a storefront directly. It only talks to connectors.

Built-in connectors

Each connector is independently deployable and communicates with the gateway over HTTPS.

Registering a site

1. Deploy the connector with its own env (SHOPIFY_STORE_DOMAIN, SHOPIFY_ADMIN_TOKEN, etc).

2. Register the site with the gateway. The merchant calls:

   curl -X POST https://api.synchronity.app/v1/register-site \
     -H 'authorization: Bearer <merchant_token>' \
     -H 'content-type: application/json' \
     -d '{
       "name": "Pronto Partners",
       "platform": "shopify",
       "connector_base_url": "https://shopify-connector.example.com",
       "api_key": "<raw connector key>"
     }'

   The gateway HMAC-hashes the raw key (so the raw key only lives in the connector's env from then on), stores the site record, and returns the new site_id.

3. Agents discover the site via list_sites. Done.

Writing a new connector

The REST-generic connector is the starting point, and the Shopify connector is the canonical example of reshaping a platform-native payload into AMPS.

1. Start from the REST-generic connector.
2. Implement the HTTP routes the gateway expects (/products/search, /cart/create, /checkout/execute, …) — the full contract ships with the connector reference.
3. Make sure every response conforms to the AMPS protocol. The gateway rejects anything it doesn't recognise.
4. Validate the connector key against your own env on every request.
5. Deploy. Register. Test.

Why connectors instead of direct integrations?

Three reasons:

• Connector keys never leak. Merchant credentials live in one place — the connector's env. The gateway never sees them.
• Per-platform isolation. A bug in the Shopify normalizer can't break WooCommerce traffic. Each connector is a separate process.
• Capability discovery. Connectors publish a manifest (GET /manifest) telling the gateway what they support — manage_cart, execute_checkout, apply_coupon. Sites are flagged accordingly; agents only see capabilities the underlying connector supports.