feat(connectors): Outreach/Salesloft/Gong/RingCentral/DialPad/Demandbase OAuth2 + release 0.43.0 (#111)

6 declarative-REST OAuth2 GTM connectors (Outreach, Salesloft, Gong, RingCentral, DialPad authorization_code; Demandbase client_credentials) for Toolverse #2330 R2+R3, plus release bump 0.43.0. Refs tangle-network/agent-dev-container#2330.

Author: AtelyPham

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.42.0",
+  "version": "0.43.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/connectors/adapters/__tests__/demandbase.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { demandbaseConnector } from '../demandbase.js'
+import { validateConnectorManifest, type ResolvedDataSource } from '../../types.js'
+
+const ACCESS_TOKEN = 'demandbase_jwt_test'
+
+const source: ResolvedDataSource = {
+  id: 'src_demandbase',
+  projectId: 'project_1',
+  publishedAgentId: null,
+  kind: 'demandbase',
+  label: 'Demandbase',
+  consistencyModel: 'authoritative',
+  scopes: [],
+  metadata: {},
+  // client_credentials grant: the hub exchanges the API Key Set and stores
+  // the resulting JWT as an oauth2 access token.
+  credentials: { kind: 'oauth2', accessToken: ACCESS_TOKEN },
+  status: 'active',
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+function mockFetch(body: unknown, init: { status?: number; headers?: Record<string, string> } = {}) {
+  const fetchMock = vi.fn(async (_input: URL | string, _init?: RequestInit) => new Response(JSON.stringify(body), {
+    status: init.status ?? 200,
+    headers: { 'content-type': 'application/json', ...init.headers },
+  }))
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+describe('demandbase adapter', () => {
+  it('ships a valid connector manifest', () => {
+    expect(validateConnectorManifest(demandbaseConnector.manifest)).toEqual({ ok: true, issues: [] })
+  })
+
+  it('declares a client_credentials oauth2 grant with no authorize URL and sales-intelligence classification', () => {
+    const auth = demandbaseConnector.manifest.auth
+    expect(auth.kind).toBe('oauth2')
+    if (auth.kind !== 'oauth2') throw new Error('auth narrowing failed')
+    expect(auth.grantType).toBe('client_credentials')
+    expect(auth.authorizationUrl).toBeUndefined()
+    expect(auth.tokenUrl).toBe('https://uapi.demandbase.com/auth/v1/token')
+    expect(auth.clientIdEnv).toBe('DEMANDBASE_OAUTH_CLIENT_ID')
+    expect(auth.clientSecretEnv).toBe('DEMANDBASE_OAUTH_CLIENT_SECRET')
+    expect(demandbaseConnector.manifest.category).toBe('sales-intelligence')
+  })
+
+  it('exposes the expected capability surface and read/mutation split', () => {
+    const names = demandbaseConnector.manifest.capabilities.map((c) => c.name).sort()
+    expect(names).toEqual(['users.create', 'users.get', 'users.list'])
+    const reads = demandbaseConnector.manifest.capabilities.filter((c) => c.class === 'read').map((c) => c.name).sort()
+    const mutations = demandbaseConnector.manifest.capabilities.filter((c) => c.class === 'mutation').map((c) => c.name).sort()
+    expect(reads).toEqual(['users.get', 'users.list'])
+    expect(mutations).toEqual(['users.create'])
+  })
+
+  it('exposes both executeRead and executeMutation handlers', () => {
+    expect(typeof demandbaseConnector.executeRead).toBe('function')
+    expect(typeof demandbaseConnector.executeMutation).toBe('function')
+  })
+
+  it('declares a CAS strategy for every mutation', () => {
+    for (const cap of demandbaseConnector.manifest.capabilities) {
+      if (cap.class !== 'mutation') continue
+      expect(cap.cas).toBeDefined()
+    }
+  })
+
+  it('lists users via GET /admin/v1/users (plural) with bearer auth', async () => {
+    const fetchMock = mockFetch({ users: [] })
+    await demandbaseConnector.executeRead!({ source, capabilityName: 'users.list', args: { limit: 10 }, idempotencyKey: 'op_0' })
+    const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.origin).toBe('https://uapi.demandbase.com')
+    expect(url.pathname).toBe('/admin/v1/users')
+    expect(init.method).toBe('GET')
+    expect((init.headers as Record<string, string>).authorization).toBe(`Bearer ${ACCESS_TOKEN}`)
+    expect(url.searchParams.get('limit')).toBe('10')
+  })
+
+  it('reads a single user via GET /admin/v1/user/{userId} (singular)', async () => {
+    const fetchMock = mockFetch({ id: 'u1' })
+    await demandbaseConnector.executeRead!({ source, capabilityName: 'users.get', args: { userId: 'u1' }, idempotencyKey: 'op_1' })
+    const [url] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.pathname).toBe('/admin/v1/user/u1')
+  })
+
+  it('creates a user via POST /admin/v1/user (singular) forwarding the args body', async () => {
+    const fetchMock = mockFetch({ id: 'u2' })
+    const result = await demandbaseConnector.executeMutation!({
+      source,
+      capabilityName: 'users.create',
+      args: { email: 'a@b.com', first_name: 'Ada', last_name: 'L', role: 'analyst' },
+      idempotencyKey: 'op_2',
+    })
+    expect(result.status).toBe('committed')
+    const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.pathname).toBe('/admin/v1/user')
+    expect(init.method).toBe('POST')
+    expect(JSON.parse(String(init.body))).toEqual({ email: 'a@b.com', first_name: 'Ada', last_name: 'L', role: 'analyst' })
+  })
+
+  it('throws CredentialsExpired when Demandbase rejects the token', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('unauthorized', { status: 401 })))
+    await expect(
+      demandbaseConnector.executeRead!({ source, capabilityName: 'users.list', args: {}, idempotencyKey: 'unauth_1' }),
+    ).rejects.toMatchObject({ name: 'CredentialsExpired' })
+  })
+
+  it('rejects unknown capabilities', async () => {
+    await expect(
+      demandbaseConnector.executeRead!({ source, capabilityName: 'does.not.exist', args: {}, idempotencyKey: 'unknown_1' }),
+    ).rejects.toThrow(/unknown read capability/)
+  })
+})

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

@@ -0,0 +1,120 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { dialpadConnector } from '../dialpad.js'
+import { validateConnectorManifest, type ResolvedDataSource } from '../../types.js'
+
+const ACCESS_TOKEN = 'dialpad_at_test'
+
+const source: ResolvedDataSource = {
+  id: 'src_dialpad',
+  projectId: 'project_1',
+  publishedAgentId: null,
+  kind: 'dialpad',
+  label: 'Dialpad',
+  consistencyModel: 'authoritative',
+  scopes: [],
+  metadata: {},
+  credentials: { kind: 'oauth2', accessToken: ACCESS_TOKEN },
+  status: 'active',
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+function mockFetch(body: unknown, init: { status?: number; headers?: Record<string, string> } = {}) {
+  const fetchMock = vi.fn(async (_input: URL | string, _init?: RequestInit) => new Response(JSON.stringify(body), {
+    status: init.status ?? 200,
+    headers: { 'content-type': 'application/json', ...init.headers },
+  }))
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+describe('dialpad adapter', () => {
+  it('ships a valid connector manifest', () => {
+    expect(validateConnectorManifest(dialpadConnector.manifest)).toEqual({ ok: true, issues: [] })
+  })
+
+  it('declares authorization_code oauth2 against dialpad.com with comms classification', () => {
+    const auth = dialpadConnector.manifest.auth
+    expect(auth.kind).toBe('oauth2')
+    if (auth.kind !== 'oauth2') throw new Error('auth narrowing failed')
+    expect(auth.authorizationUrl).toBe('https://dialpad.com/oauth2/authorize')
+    expect(auth.tokenUrl).toBe('https://dialpad.com/oauth2/token')
+    expect(auth.clientIdEnv).toBe('DIALPAD_OAUTH_CLIENT_ID')
+    expect(auth.clientSecretEnv).toBe('DIALPAD_OAUTH_CLIENT_SECRET')
+    // Least-privilege: only Call--List/Get need a documented scope (calls:list);
+    // contacts/users/sms use base bearer access. Webhook-export scopes are not
+    // requested because this connector exposes no webhook subscriptions.
+    expect(auth.scopes).toEqual(['calls:list', 'offline_access'])
+    expect(dialpadConnector.manifest.category).toBe('comms')
+  })
+
+  it('exposes the expected capability surface and read/mutation split', () => {
+    const names = dialpadConnector.manifest.capabilities.map((c) => c.name).sort()
+    expect(names).toEqual(['calls.get', 'calls.list', 'contacts.create', 'contacts.list', 'sms.send', 'users.list'])
+    const reads = dialpadConnector.manifest.capabilities.filter((c) => c.class === 'read').map((c) => c.name).sort()
+    const mutations = dialpadConnector.manifest.capabilities.filter((c) => c.class === 'mutation').map((c) => c.name).sort()
+    expect(reads).toEqual(['calls.get', 'calls.list', 'contacts.list', 'users.list'])
+    expect(mutations).toEqual(['contacts.create', 'sms.send'])
+  })
+
+  it('exposes both executeRead and executeMutation handlers', () => {
+    expect(typeof dialpadConnector.executeRead).toBe('function')
+    expect(typeof dialpadConnector.executeMutation).toBe('function')
+  })
+
+  it('declares a CAS strategy for every mutation', () => {
+    for (const cap of dialpadConnector.manifest.capabilities) {
+      if (cap.class !== 'mutation') continue
+      expect(cap.cas).toBeDefined()
+    }
+  })
+
+  it('routes calls.list as GET /api/v2/call (singular) with bearer auth', async () => {
+    const fetchMock = mockFetch({ items: [] })
+    await dialpadConnector.executeRead!({ source, capabilityName: 'calls.list', args: { started_after: 1700000000000 }, idempotencyKey: 'op_0' })
+    const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.origin).toBe('https://dialpad.com')
+    expect(url.pathname).toBe('/api/v2/call')
+    expect(init.method).toBe('GET')
+    expect((init.headers as Record<string, string>).authorization).toBe(`Bearer ${ACCESS_TOKEN}`)
+    expect(url.searchParams.get('started_after')).toBe('1700000000000')
+  })
+
+  it('routes calls.get to /api/v2/call/{id}', async () => {
+    const fetchMock = mockFetch({ id: '5' })
+    await dialpadConnector.executeRead!({ source, capabilityName: 'calls.get', args: { id: 5 }, idempotencyKey: 'op_1' })
+    const [url] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.pathname).toBe('/api/v2/call/5')
+  })
+
+  it('sends an SMS via POST /api/v2/sms forwarding the args body', async () => {
+    const fetchMock = mockFetch({ id: 'sms_1' })
+    const result = await dialpadConnector.executeMutation!({
+      source,
+      capabilityName: 'sms.send',
+      args: { to_numbers: ['+14155550111'], text: 'Hello', user_id: 99 },
+      idempotencyKey: 'op_2',
+    })
+    expect(result.status).toBe('committed')
+    const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.pathname).toBe('/api/v2/sms')
+    expect(init.method).toBe('POST')
+    expect((init.headers as Record<string, string>).authorization).toBe(`Bearer ${ACCESS_TOKEN}`)
+    expect(JSON.parse(String(init.body))).toEqual({ to_numbers: ['+14155550111'], text: 'Hello', user_id: 99 })
+  })
+
+  it('throws CredentialsExpired when Dialpad rejects the token', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('unauthorized', { status: 401 })))
+    await expect(
+      dialpadConnector.executeRead!({ source, capabilityName: 'calls.list', args: {}, idempotencyKey: 'unauth_1' }),
+    ).rejects.toMatchObject({ name: 'CredentialsExpired' })
+  })
+
+  it('rejects unknown capabilities', async () => {
+    await expect(
+      dialpadConnector.executeRead!({ source, capabilityName: 'does.not.exist', args: {}, idempotencyKey: 'unknown_1' }),
+    ).rejects.toThrow(/unknown read capability/)
+  })
+})

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

@@ -0,0 +1,146 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { gongConnector } from '../gong.js'
+import { validateConnectorManifest, type ResolvedDataSource } from '../../types.js'
+
+const ACCESS_TOKEN = 'gong_at_test'
+// A normally-connected Gong source carries the per-customer host the hub
+// persisted from the token exchange; tests that exercise real calls default
+// to it. The fail-loud test below passes `source({})` to drop it.
+const PER_CUSTOMER_BASE = 'https://company-17.api.gong.io'
+
+function source(metadata: Record<string, unknown> = { apiBaseUrlForCustomer: PER_CUSTOMER_BASE }): ResolvedDataSource {
+  return {
+    id: 'src_gong',
+    projectId: 'project_1',
+    publishedAgentId: null,
+    kind: 'gong',
+    label: 'Gong',
+    consistencyModel: 'authoritative',
+    scopes: [],
+    metadata,
+    credentials: { kind: 'oauth2', accessToken: ACCESS_TOKEN },
+    status: 'active',
+  }
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+function mockFetch(body: unknown, init: { status?: number; headers?: Record<string, string> } = {}) {
+  const fetchMock = vi.fn(async (_input: URL | string, _init?: RequestInit) => new Response(JSON.stringify(body), {
+    status: init.status ?? 200,
+    headers: { 'content-type': 'application/json', ...init.headers },
+  }))
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+describe('gong adapter', () => {
+  it('ships a valid connector manifest', () => {
+    expect(validateConnectorManifest(gongConnector.manifest)).toEqual({ ok: true, issues: [] })
+  })
+
+  it('declares authorization_code oauth2 against app.gong.io with comms classification', () => {
+    const auth = gongConnector.manifest.auth
+    expect(auth.kind).toBe('oauth2')
+    if (auth.kind !== 'oauth2') throw new Error('auth narrowing failed')
+    expect(auth.authorizationUrl).toBe('https://app.gong.io/oauth2/authorize')
+    expect(auth.tokenUrl).toBe('https://app.gong.io/oauth2/generate-customer-token')
+    expect(auth.clientIdEnv).toBe('GONG_OAUTH_CLIENT_ID')
+    expect(auth.clientSecretEnv).toBe('GONG_OAUTH_CLIENT_SECRET')
+    expect(gongConnector.manifest.category).toBe('comms')
+  })
+
+  it('exposes the expected capability surface and read/mutation split', () => {
+    const names = gongConnector.manifest.capabilities.map((c) => c.name).sort()
+    expect(names).toEqual([
+      'calls.create',
+      'calls.getExtensive',
+      'calls.getTranscripts',
+      'calls.list',
+      'flows.assignProspects',
+      'users.list',
+    ])
+    const mutations = gongConnector.manifest.capabilities.filter((c) => c.class === 'mutation').map((c) => c.name).sort()
+    expect(mutations).toEqual(['calls.create', 'flows.assignProspects'])
+  })
+
+  it('exposes both executeRead and executeMutation handlers', () => {
+    expect(typeof gongConnector.executeRead).toBe('function')
+    expect(typeof gongConnector.executeMutation).toBe('function')
+  })
+
+  it('declares a CAS strategy for every mutation', () => {
+    for (const cap of gongConnector.manifest.capabilities) {
+      if (cap.class !== 'mutation') continue
+      expect(cap.cas).toBeDefined()
+    }
+  })
+
+  it('fails loud (no silent fallback host) when the per-customer base URL is absent', async () => {
+    // The generic api.gong.io host is invalid for OAuth apps, so a missing
+    // metadata.apiBaseUrlForCustomer must throw rather than route to a host
+    // where every call would fail while the connection looks active.
+    const fetchMock = mockFetch({ users: [] })
+    await expect(
+      gongConnector.executeRead!({ source: source({}), capabilityName: 'users.list', args: {}, idempotencyKey: 'op_0' }),
+    ).rejects.toThrow(/missing metadata\.apiBaseUrlForCustomer/)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('targets the per-customer base URL from metadata.apiBaseUrlForCustomer when present', async () => {
+    const fetchMock = mockFetch({ calls: [] })
+    await gongConnector.executeRead!({
+      source: source({ apiBaseUrlForCustomer: 'https://company-17.api.gong.io' }),
+      capabilityName: 'calls.list',
+      args: { fromDateTime: '2026-01-01T00:00:00Z' },
+      idempotencyKey: 'op_1',
+    })
+    const [url] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.origin).toBe('https://company-17.api.gong.io')
+    expect(url.pathname).toBe('/v2/calls')
+    expect(url.searchParams.get('fromDateTime')).toBe('2026-01-01T00:00:00Z')
+  })
+
+  it('retrieves transcripts via POST /v2/calls/transcript forwarding the filter object', async () => {
+    const fetchMock = mockFetch({ callTranscripts: [] })
+    await gongConnector.executeRead!({
+      source: source(),
+      capabilityName: 'calls.getTranscripts',
+      args: { filter: { callIds: ['c1', 'c2'] } },
+      idempotencyKey: 'op_2',
+    })
+    const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.pathname).toBe('/v2/calls/transcript')
+    expect(init.method).toBe('POST')
+    expect(JSON.parse(String(init.body))).toEqual({ filter: { callIds: ['c1', 'c2'] } })
+  })
+
+  it('assigns prospects to an Engage flow via POST /v2/flows/prospects/assign', async () => {
+    const fetchMock = mockFetch({ ok: true })
+    const result = await gongConnector.executeMutation!({
+      source: source(),
+      capabilityName: 'flows.assignProspects',
+      args: { flowId: 'flow_1', prospects: [{ crmProspectId: 'p1' }] },
+      idempotencyKey: 'op_3',
+    })
+    expect(result.status).toBe('committed')
+    const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.pathname).toBe('/v2/flows/prospects/assign')
+    expect(JSON.parse(String(init.body))).toEqual({ flowId: 'flow_1', prospects: [{ crmProspectId: 'p1' }] })
+  })
+
+  it('throws CredentialsExpired when Gong rejects the token', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('unauthorized', { status: 401 })))
+    await expect(
+      gongConnector.executeRead!({ source: source(), capabilityName: 'users.list', args: {}, idempotencyKey: 'unauth_1' }),
+    ).rejects.toMatchObject({ name: 'CredentialsExpired' })
+  })
+
+  it('rejects unknown capabilities', async () => {
+    await expect(
+      gongConnector.executeRead!({ source: source(), capabilityName: 'does.not.exist', args: {}, idempotencyKey: 'unknown_1' }),
+    ).rejects.toThrow(/unknown read capability/)
+  })
+})