Connector Development Guide

​

Connector responsibilities, and what a Connector must never do

import {
  connectorCapabilities,
  type Connector,
  type ConnectorExecutionContext,
  type ConnectorRequest,
  type ConnectorResponse,
} from "@parmana/connector-sdk";

class ExampleConnector implements Connector {
  readonly connectorId = "example";
  readonly capabilities = connectorCapabilities(["crm:read"]);

  async execute(
    request: ConnectorRequest,
    context: ConnectorExecutionContext,
  ): Promise<ConnectorResponse> {
    if (!this.capabilities.includes(request.capability)) {
      throw new Error(`does not declare capability "${request.capability}"`);
    }
    // context.credential is an opaque CredentialHandle, read it, never log it.
    return { success: true, metadata: { recordId: "example-1" } };
  }
}

​

Capabilities are namespaced verbs

​

Registering a connector

import { GatewayConnectorRegistry } from "@parmana/execution-gateway";
import { StaticCredentialProvider, healthyNow } from "@parmana/connector-sdk";

const registry = new GatewayConnectorRegistry();

registry.register({
  connector: new ExampleConnector(),
  metadata: {
    connectorId: "example",
    displayName: "Example CRM",
    version: { major: 1, minor: 0, patch: 0 },
    health: healthyNow(),
  },
  connectorIdentity: {
    connectorId: "example",
    publicIdentity: "spiffe://parmana/connectors/example",
    authenticationMetadata: {},
  },
  credentialProvider: new StaticCredentialProvider({
    example: { token: "..." },
  }),
  policy, // a ConnectorPolicy, e.g. CapabilityConnectorPolicy(new DefaultConnectorPolicy(...))
  gatewayAuthentication,
  crypto, // @parmana/crypto CryptoProvider, reused for evidence hashing, not reimplemented
});

​

Testing your connector hermetically

import { MockConnector, connectorCapabilities } from "@parmana/connector-sdk";

const mock = new MockConnector({
  connectorId: "example",
  capabilities: connectorCapabilities(["crm:read"]),
  script: {
    respond: () => ({ success: true, metadata: { recordId: "example-1" } }),
  },
});

const result = await mock.execute(
  {
    capability: "crm:read",
    businessTransactionId: "t1",
    action: "crm:read",
    target: "crm://record/1",
    parameters: {},
  },
  { credential: undefined as never },
);

mock result: { success: true, metadata: { recordId: 'example-1' } }
mock invocations: 1

​

Version and health checks fail closed

• an expectedVersion was configured at registration and the connector’s own metadata.version doesn’t match (guards a rolling deployment that swapped connector builds underneath a pinned expectation), or
• metadata.health.status === "unavailable".

​

What every connector’s evidence looks like

​

What reaching the default server actually requires

// packages/api/src/bootstrap/createConnectorRegistry.ts (abridged, real source)
const hubspotCredentialProvider = createHubSpotCredentialProvider();
if (hubspotCredentialProvider === undefined) {
  console.warn({
    event: "hubspot_connector_unavailable",
    reason: "HUBSPOT_PRIVATE_APP_TOKEN is not configured.",
  });
} else {
  registrations.push({
    connector: createHubSpotConnector(),
    metadata: HubSpotMetadata,
    connectorIdentity: {
      connectorId: "hubspot",
      publicIdentity: "spiffe://parmana/connectors/hubspot",
      authenticationMetadata: {},
    },
    credentialProvider: hubspotCredentialProvider,
    policy: new DefaultConnectorPolicy(authenticator, sessions),
    gatewayAuthentication,
    crypto,
    audit,
  });
}

​

The pattern, proven twice: Razorpay and HubSpot

• Refuse a placeholder test credential against the real endpoint, before any network call. Don’t rely on the vendor happening to reject it, that’s an accident of their behavior, not something this codebase controls. RazorpayConnector didn’t have this check originally, it survived only because Razorpay’s real API happened to reject an unrecognized key — a defense-in-depth fix was added after the fact. The HubSpot connector refuses its own placeholder token against https://api.hubapi.com from its first commit, see HubSpot and packages/execution-gateway/src/connector-execution/GatewayHubSpotAdapter.ts.
• Read the documented test-credential environment variable name directly, never through a bridge variable. createRazorpayCredentialProvider.ts’s test-mode branch originally read a word-order-swapped bridge variable instead of the name .env.example actually documented, fixed only after it drifted out of sync. createHubSpotCredentialProvider.ts reads TEST_HUBSPOT_PRIVATE_APP_TOKEN, the exact documented name, with no bridge to get wrong.

1. Hermetic first. The full authorize → verify → execute → confirm chain against a mock server, zero network calls. Both connectors’ unit suites run this way on every npm test.
2. Policy-denial-makes-zero-calls, proven at two layers. A direct state check against the mock server (nothing changed), and a fetch spy at the HTTP boundary (literally zero calls reached the mock or real endpoint). See HubSpot for what that looks like in a captured response.
3. A gated live suite last, behind an ALLOW_LIVE_<CONNECTOR>=1 flag checked alongside a real test credential, skipped by default so a routine npm test never makes a live call by accident.

​

Troubleshoot

• does not declare capability "..." thrown by MockConnector or your own connector. request.capability didn’t match anything in connectorCapabilities([...]). Check for a typo, capability strings are exact, case-sensitive matches.
• SdkConnectorExecutor rejects with a version mismatch. An expectedVersion was configured at registration and your connector’s metadata.version doesn’t match, this guards a rolling deployment that swapped connector builds underneath a pinned expectation.
• Registered your connector but POST /execute still answers 503 CONNECTOR_NOT_REGISTERED. Registration in a ConnectorSdkRegistry you constructed yourself doesn’t reach the running default server, that server builds its own registry in createConnectorRegistry.ts, see the Warning above.

​

Next