feat(connectors): add SimilarWeb, Semrush, Cognism, Clay, ZoomInfo, Paychex, ADP (#103) (#107)

7 new library connectors, each w/ adapter + barrel export (auto-registers) + isolation tests:
- market-intel: similarweb, semrush (api-key; JSON-only v4 surfaces)
- sales-intel: cognism (api-key bearer), zoominfo (oauth2 GTM Data API)
- crm: clay (outbound push_row + inbound clayWebhookProvider; clay has no general REST API)
- hr: paychex (oauth2 client_credentials), adp (oauth2; manifest+tests only — mandatory mTLS not yet presentable by shared runtime)

types: category union +sales-intelligence/market-intelligence/hr (mapCategory translates to hub taxonomy); OAuth2AuthSpec gains optional grantType + optional authorizationUrl for client_credentials; validator + startAuth guard updated.

Author: AtelyPham

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.40.1",
+  "version": "0.41.0",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {

src/adapter-provider.ts

@@ -96,6 +96,12 @@ export function createConnectorAdapterProvider(options: ConnectorAdapterProvider
           'config_missing',
         )
       }
+      if (!auth.authorizationUrl) {
+        throw new IntegrationError(
+          `Connector ${request.connectorId} uses the ${auth.grantType ?? 'authorization_code'} grant and has no authorization URL to redirect to.`,
+          'auth_not_supported',
+        )
+      }
       const scopes =
         request.requestedScopes && request.requestedScopes.length > 0
           ? request.requestedScopes
@@ -407,6 +413,11 @@ function mapCategory(category: ConnectorAdapter['manifest']['category']): Integr
   if (category === 'spreadsheet') return 'database'
   if (category === 'doc') return 'docs'
   if (category === 'commerce') return 'workflow'
+  // The manifest taxonomy is richer than the hub-facade taxonomy. Sales/market
+  // intelligence and HR/payroll connectors collapse to the nearest hub bucket:
+  // contact/company intelligence reads like CRM; the rest have no closer fit.
+  if (category === 'sales-intelligence') return 'crm'
+  if (category === 'market-intelligence' || category === 'hr') return 'other'
   return category === 'other' ? 'other' : category
 }
 

src/connectors/adapters/__tests__/contentful.test.ts

@@ -85,6 +85,7 @@ describe('contentful startAuth URL construction', () => {
   it('builds an OAuth2 authorize URL via startOAuthFlow with the manifest endpoint and scopes', () => {
     const m = contentfulConnector.manifest
     if (m.auth.kind !== 'oauth2') throw new Error('contentful auth must be oauth2')
+    if (!m.auth.authorizationUrl) throw new Error('contentful authorization_code auth must expose authorizationUrl')
 
     const { authorizationUrl, state } = startOAuthFlow({
       projectId: 'project_1',

src/connectors/adapters/__tests__/whatsapp-business.test.ts

@@ -87,6 +87,7 @@ describe('whatsappBusiness adapter', () => {
     const adapter = whatsappBusiness(opts)
     const auth = adapter.manifest.auth
     if (auth.kind !== 'oauth2') throw new Error('expected oauth2')
+    if (!auth.authorizationUrl) throw new Error('expected authorizationUrl')
     // The hub constructs the authorize URL by appending standard OAuth2 params; assert the
     // adapter exposes everything the constructor needs to build a correct URL.
     const url = new URL(auth.authorizationUrl)

src/connectors/adapters/adp.ts

@@ -0,0 +1,187 @@
+import { declarativeRestConnector } from './declarative-rest.js'
+
+/**
+ * ADP (Workforce Now / ADP Marketplace) — HR/payroll reads over workers, worker
+ * demographics, pay statements, and pay distributions.
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │ RUNTIME GAP — MANDATORY mTLS. NOT EXECUTABLE THROUGH THE SHARED RUNTIME.  │
+ * │                                                                           │
+ * │ ADP requires MUTUAL TLS (a client X.509 certificate, CSR-signed by ADP)  │
+ * │ presented at the TLS handshake on EVERY call — both the token endpoint   │
+ * │ (accounts.adp.com) and the data gateway (api.adp.com). The shared        │
+ * │ declarative-REST fetch path cannot attach a client certificate to its    │
+ * │ outbound TLS connection, so every request here will fail the handshake   │
+ * │ until per-connection client-cert plumbing is added to the runtime.       │
+ * │                                                                           │
+ * │ This adapter therefore ships the MANIFEST + ISOLATION TESTS only. The     │
+ * │ capability set, paths, and auth shape are correct and validated against   │
+ * │ stubbed fetch; live execution is gated on a follow-up that teaches the    │
+ * │ runtime to present client certs (tracked separately — see the PR).        │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ *
+ * Auth is OAuth2; ADP supports both client_credentials (server-to-server Data
+ * Connector apps — the natural fit for bulk reads) and authorization_code
+ * (delegated End-User apps). We declare the authorization_code shape here so
+ * the manifest carries both the authorize and token URLs; the access token is
+ * still injected by the platform and sent as `Authorization: Bearer`.
+ *
+ * Most HR/payroll endpoints also require a `roleCode` header
+ * (practitioner|employee|manager|administrator|supervisor); we default it to
+ * `practitioner`. SSN/birth-date are masked unless the caller adds
+ * `Accept: application/json;masked=false` with a practitioner role + scopes —
+ * we leave masking ON by default. The `associateOID` (AOID) is the primary key
+ * resolved from worker.list and threaded into every per-worker endpoint.
+ *
+ * The pay-statement IMAGE endpoint is intentionally excluded — it returns a
+ * binary PDF, which the JSON runtime cannot parse.
+ */
+export const adpConnector = declarativeRestConnector({
+  kind: 'adp',
+  displayName: 'ADP',
+  description:
+    'Read HR and payroll data from ADP Workforce Now: workers, worker demographics, pay statements, and pay distributions. Requires mutual-TLS client certificates (see adapter notes) in addition to OAuth2.',
+  auth: {
+    kind: 'oauth2',
+    authorizationUrl: 'https://accounts.adp.com/auth/oauth/v2/authorize',
+    tokenUrl: 'https://accounts.adp.com/auth/oauth/v2/token',
+    scopes: [
+      'hr/workerInformationManagement/read',
+      'payroll/payStatementManagement/read',
+    ],
+    clientIdEnv: 'ADP_OAUTH_CLIENT_ID',
+    clientSecretEnv: 'ADP_OAUTH_CLIENT_SECRET',
+  },
+  category: 'hr',
+  defaultConsistencyModel: 'authoritative',
+  baseUrl: 'https://api.adp.com',
+  // ADP requires a roleCode on most HR/payroll endpoints; practitioner is the
+  // broadest read role. (PII stays masked unless the caller opts into
+  // `Accept: application/json;masked=false`.)
+  defaultHeaders: { roleCode: 'practitioner' },
+  test: { method: 'GET', path: '/hr/v2/workers/meta' },
+  capabilities: [
+    {
+      name: 'worker.list',
+      class: 'read',
+      description:
+        'Collection of all workers for the authenticated client. OData paging via $top/$skip (default 50, max 100); total at meta.totalNumber. The associateOID on each worker is the key for per-worker endpoints. SSN/birth date are masked.',
+      parameters: {
+        type: 'object',
+        properties: {
+          top: { type: 'integer', description: 'OData $top page size (default 50, max 100).' },
+          skip: { type: 'integer', description: 'OData $skip offset for pagination.' },
+          filter: { type: 'string', description: 'OData $filter expression.' },
+          select: { type: 'string', description: 'OData $select field projection.' },
+        },
+      },
+      request: {
+        method: 'GET',
+        path: '/hr/v2/workers',
+        query: { $top: '{top}', $skip: '{skip}', $filter: '{filter}', $select: '{select}' },
+      },
+    },
+    {
+      name: 'worker.get',
+      class: 'read',
+      description: 'A single worker by Associate OID (aoid). SSN/birth date are masked unless unmasking is requested.',
+      parameters: {
+        type: 'object',
+        properties: {
+          aoid: { type: 'string', description: 'Associate OID from worker.list.' },
+          select: { type: 'string', description: 'OData $select field projection.' },
+        },
+        required: ['aoid'],
+      },
+      request: {
+        method: 'GET',
+        path: '/hr/v2/workers/{aoid}',
+        query: { $select: '{select}' },
+      },
+    },
+    {
+      name: 'worker.demographics.list',
+      class: 'read',
+      description:
+        'Worker collection WITHOUT PII/SPI (no SSN, no full birth date) — a lighter payload than worker.list. OData paging supported.',
+      parameters: {
+        type: 'object',
+        properties: {
+          top: { type: 'integer' },
+          skip: { type: 'integer' },
+          filter: { type: 'string' },
+          select: { type: 'string' },
+        },
+      },
+      request: {
+        method: 'GET',
+        path: '/hr/v2/worker-demographics',
+        query: { $top: '{top}', $skip: '{skip}', $filter: '{filter}', $select: '{select}' },
+      },
+    },
+    {
+      name: 'worker.demographics.get',
+      class: 'read',
+      description: 'Demographic data for one worker by Associate OID, without PII/SPI.',
+      parameters: {
+        type: 'object',
+        properties: {
+          aoid: { type: 'string' },
+          select: { type: 'string' },
+        },
+        required: ['aoid'],
+      },
+      request: {
+        method: 'GET',
+        path: '/hr/v2/worker-demographics/{aoid}',
+        query: { $select: '{select}' },
+      },
+    },
+    {
+      name: 'paystatements.list',
+      class: 'read',
+      description:
+        'Pay statements for one worker: payDate, net/gross pay amounts, total hours, and a statement image URI. Use numberoflastpaydates to cap results.',
+      parameters: {
+        type: 'object',
+        properties: {
+          aoid: { type: 'string', description: 'Associate OID from worker.list.' },
+          numberoflastpaydates: { type: 'integer', description: 'Limit to the N most recent pay dates.' },
+        },
+        required: ['aoid'],
+      },
+      request: {
+        method: 'GET',
+        path: '/payroll/v1/workers/{aoid}/pay-statements',
+        query: { numberoflastpaydates: '{numberoflastpaydates}' },
+      },
+    },
+    {
+      name: 'paystatements.get',
+      class: 'read',
+      description:
+        'Full detail of one pay statement: pay period, net/gross/YTD amounts, earnings, deductions, and memos. The pay-statement id is resolved from paystatements.list.',
+      parameters: {
+        type: 'object',
+        properties: {
+          aoid: { type: 'string' },
+          payStatementId: { type: 'string', description: 'Pay statement id from paystatements.list.' },
+        },
+        required: ['aoid', 'payStatementId'],
+      },
+      request: { method: 'GET', path: '/payroll/v1/workers/{aoid}/pay-statements/{payStatementId}' },
+    },
+    {
+      name: 'paydistributions.get',
+      class: 'read',
+      description:
+        'Direct-deposit distribution setup for one worker: accounts, routing numbers, distribution amounts, and remaining-balance flags.',
+      parameters: {
+        type: 'object',
+        properties: { aoid: { type: 'string' } },
+        required: ['aoid'],
+      },
+      request: { method: 'GET', path: '/payroll/v2/workers/{aoid}/pay-distributions' },
+    },
+  ],
+})

src/connectors/adapters/clay.ts

@@ -0,0 +1,119 @@
+/**
+ * Clay (clay.com) — GTM enrichment platform.
+ *
+ * Clay has NO general request/response REST API. Per Clay's own docs: "Clay
+ * isn't built like a typical SaaS tool where you send a request to an endpoint
+ * and get data back in milliseconds." The only programmatic surfaces are:
+ *   1. INBOUND webhook source — POST a flat JSON row INTO a Clay table via a
+ *      per-table webhook URL. This is the outbound direction for THIS connector
+ *      (the agent pushes a row into Clay) and is implemented here as the
+ *      `push_row` mutation.
+ *   2. OUTBOUND "HTTP API" action — Clay calls an external URL the operator
+ *      configures, to deliver enriched rows back out. That is the inbound
+ *      direction for us and is handled by `clayWebhookProvider` in
+ *      `src/webhooks/providers.ts` (Clay signs nothing, so the provider
+ *      verifies a pre-shared secret header the operator configures).
+ *
+ * Because there is no read/enrich endpoint on standard plans, this connector
+ * is intentionally write-only (ingest). The per-table webhook URL lives in
+ * `DataSource.metadata.webhookUrl` (each Clay table generates its own
+ * UUID-suffixed URL). The optional `x-clay-webhook-auth` token (shown once at
+ * table-webhook creation) is the only Clay-native auth; if the table was
+ * created without a token, requests are unauthenticated and the operator can
+ * leave the credential empty. Ingest is async — the response does NOT echo
+ * enriched data — so the consistency model is `advisory`.
+ */
+
+import {
+  type CapabilityMutationResult,
+  type ConnectorAdapter,
+  type ConnectorCredentials,
+  type ConnectorInvocation,
+  CredentialsExpired,
+} from '../types.js'
+
+export const clayConnector: ConnectorAdapter = {
+  manifest: {
+    kind: 'clay',
+    displayName: 'Clay',
+    description:
+      'Push rows into a Clay table to trigger GTM enrichment workflows. Clay has no general REST API — this sends a JSON row to your table’s inbound webhook URL; enriched results flow back out via Clay’s HTTP API action (received through the clay webhook provider).',
+    auth: {
+      kind: 'api-key',
+      hint: 'Optional Clay table webhook token (x-clay-webhook-auth), shown once when you add a webhook source to a table. Leave blank if the table’s webhook has no token. The per-table webhook URL goes in the connection metadata as `webhookUrl`.',
+    },
+    category: 'crm',
+    defaultConsistencyModel: 'advisory',
+    capabilities: [
+      {
+        name: 'push_row',
+        class: 'mutation',
+        description:
+          'Send a flat JSON object to the configured Clay table webhook URL, creating a new row. Keys map to table columns (no fixed schema). Processing is asynchronous — the response acknowledges receipt but does not return enriched data.',
+        cas: 'native-idempotency',
+        externalEffect: true,
+        parameters: {
+          type: 'object',
+          additionalProperties: true,
+          description:
+            'Flat JSON whose keys become Clay table columns, e.g. { "firstName": "Jane", "email": "jane@acme.com", "company": "Acme" }.',
+        },
+      },
+    ],
+  },
+
+  async executeMutation(inv: ConnectorInvocation): Promise<CapabilityMutationResult> {
+    const url = readWebhookUrl(inv.source.metadata)
+    const body = JSON.stringify(inv.args ?? {})
+    const headers: Record<string, string> = { 'content-type': 'application/json' }
+    const token = clayToken(inv.source.credentials)
+    if (token) headers['x-clay-webhook-auth'] = token
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body,
+      signal: AbortSignal.timeout(15_000),
+    })
+    if (res.status === 401 || res.status === 403) {
+      throw new CredentialsExpired(`Clay rejected the webhook token (${res.status})`, inv.source.id)
+    }
+    if (!res.ok) {
+      throw new Error(`clay push_row ${res.status}: ${(await res.text().catch(() => res.statusText)).slice(0, 200)}`)
+    }
+    // Clay returns a small JSON ack (often {} ); ingest is async so there is no
+    // enriched payload to surface here.
+    const data = (await res.json().catch(() => ({}))) as unknown
+    return {
+      status: 'committed',
+      data,
+      committedAt: Date.now(),
+      idempotentReplay: false,
+    }
+  },
+
+  async test(source) {
+    try {
+      // The table webhook URL is write-only (POST ingest) — we can't probe it
+      // without polluting the table, so a healthy connection is one that has a
+      // syntactically valid webhook URL configured.
+      readWebhookUrl(source.metadata)
+      return { ok: true }
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+    }
+  },
+}
+
+function readWebhookUrl(metadata: Record<string, unknown>): string {
+  const value = metadata.webhookUrl
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error('clay DataSource.metadata.webhookUrl is missing')
+  }
+  // Surface an invalid URL eagerly rather than failing inside fetch().
+  return new URL(value).toString()
+}
+
+function clayToken(credentials: ConnectorCredentials): string | undefined {
+  if (credentials.kind === 'api-key' && credentials.apiKey) return credentials.apiKey
+  return undefined
+}