fix(gong): capture api_base_url_for_customer into connection metadata via tokenMetadata + release 0.44.0 (#112)

Adds declarative auth.tokenMetadata manifest contract; completeAuth persists declared token-response fields into connection metadata; Gong declares apiBaseUrlForCustomer <- api_base_url_for_customer (required, fail-loud). Release 0.44.0.

Author: AtelyPham

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.43.0",
+  "version": "0.44.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/__tests__/adapter-provider-oauth.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, it, vi } from 'vitest'
 import { createConnectorAdapterProvider } from '../adapter-provider.js'
 import { IntegrationError } from '../index.js'
-import type { ConnectorAdapter } from '../connectors/types.js'
+import type { ConnectorAdapter, TokenMetadataSource } from '../connectors/types.js'
 
 const OWNER = { type: 'user' as const, id: 'user_42' }
 const REDIRECT = 'https://app.example/oauth/callback'
 
-function oauthAdapter(): ConnectorAdapter {
+function oauthAdapter(tokenMetadata?: Record<string, TokenMetadataSource>): ConnectorAdapter {
   return {
     manifest: {
       kind: 'demo-oauth',
@@ -20,6 +20,7 @@ function oauthAdapter(): ConnectorAdapter {
         clientIdEnv: 'DEMO_CLIENT_ID',
         clientSecretEnv: 'DEMO_CLIENT_SECRET',
         extraAuthParams: { access_type: 'offline' },
+        ...(tokenMetadata ? { tokenMetadata } : {}),
       },
       capabilities: [],
       defaultConsistencyModel: 'authoritative',
@@ -223,4 +224,150 @@ describe('createConnectorAdapterProvider OAuth flow', () => {
       }),
     ).rejects.toMatchObject({ code: 'provider_failure' })
   })
+
+  it('completeAuth captures declared tokenMetadata fields (string + object form), merging with — and overriding same-key — request.metadata', async () => {
+    const fetchImpl = vi.fn(async () =>
+      tokenResponse({
+        access_token: 'acc_xyz',
+        token_type: 'Bearer',
+        // Provider-specific fields the standard parser would otherwise drop.
+        api_base_url_for_customer: 'https://company-17.api.gong.io',
+        instance_url: 'https://eu.example.com',
+      }),
+    ) as unknown as typeof fetch
+
+    const provider = createConnectorAdapterProvider({
+      adapters: [
+        oauthAdapter({
+          // object form (required) + string shorthand
+          apiBaseUrlForCustomer: { field: 'api_base_url_for_customer', required: true },
+          instanceUrl: 'instance_url',
+        }),
+      ],
+      resolveDataSource: () => ({ kind: 'demo-oauth', id: 'ds_demo' }) as never,
+      resolveOAuthClient: () => ({ clientId: 'cid_live', clientSecret: 'sec_live' }),
+      fetchImpl,
+    })
+
+    const conn = await provider.completeAuth!({
+      connectorId: 'demo-oauth',
+      owner: OWNER,
+      code: 'the_code',
+      state: 'state_xyz',
+      redirectUri: REDIRECT,
+      // `tenant` is a non-colliding key → preserved (merge, not replace).
+      // `apiBaseUrlForCustomer` collides → the token-exchange value is
+      // authoritative and MUST win over the stale request.metadata value.
+      metadata: { tenant: 'acme', apiBaseUrlForCustomer: 'https://stale.example' },
+    })
+
+    expect(conn.metadata).toEqual({
+      tenant: 'acme',
+      apiBaseUrlForCustomer: 'https://company-17.api.gong.io',
+      instanceUrl: 'https://eu.example.com',
+    })
+  })
+
+  it('completeAuth omits a non-required tokenMetadata field that is absent (capture-if-present)', async () => {
+    const fetchImpl = vi.fn(async () =>
+      tokenResponse({ access_token: 'acc_xyz', token_type: 'Bearer' }),
+    ) as unknown as typeof fetch
+
+    const provider = createConnectorAdapterProvider({
+      adapters: [oauthAdapter({ instanceUrl: 'instance_url' })],
+      resolveDataSource: () => ({ kind: 'demo-oauth', id: 'ds_demo' }) as never,
+      resolveOAuthClient: () => ({ clientId: 'cid_live', clientSecret: 'sec_live' }),
+      fetchImpl,
+    })
+
+    const conn = await provider.completeAuth!({
+      connectorId: 'demo-oauth',
+      owner: OWNER,
+      code: 'the_code',
+      state: 'state_xyz',
+      redirectUri: REDIRECT,
+    })
+
+    expect(conn.metadata).toEqual({})
+    expect('instanceUrl' in (conn.metadata ?? {})).toBe(false)
+  })
+
+  it('completeAuth fails loud (provider_failure) when a required tokenMetadata field is absent', async () => {
+    const fetchImpl = vi.fn(async () =>
+      tokenResponse({ access_token: 'acc_xyz', token_type: 'Bearer' }),
+    ) as unknown as typeof fetch
+
+    const provider = createConnectorAdapterProvider({
+      adapters: [oauthAdapter({ apiBaseUrlForCustomer: { field: 'api_base_url_for_customer', required: true } })],
+      resolveDataSource: () => ({ kind: 'demo-oauth', id: 'ds_demo' }) as never,
+      resolveOAuthClient: () => ({ clientId: 'cid_live', clientSecret: 'sec_live' }),
+      fetchImpl,
+    })
+
+    let caught: unknown
+    try {
+      await provider.completeAuth!({
+        connectorId: 'demo-oauth',
+        owner: OWNER,
+        code: 'the_code',
+        state: 'state_xyz',
+        redirectUri: REDIRECT,
+      })
+    } catch (e) {
+      caught = e
+    }
+    expect(caught).toBeInstanceOf(IntegrationError)
+    expect((caught as IntegrationError).code).toBe('provider_failure')
+    expect((caught as Error).message).toMatch(/api_base_url_for_customer/)
+  })
+
+  it('completeAuth treats a present-but-empty required tokenMetadata field as absent and fails loud', async () => {
+    // Locks the `=== ''` (post-trim) emptiness guard against a regression to a
+    // null-only check that would mint an active connection whose every call 404s.
+    for (const emptyish of ['', '   ', '\n\t']) {
+      const fetchImpl = vi.fn(async () =>
+        tokenResponse({ access_token: 'acc_xyz', token_type: 'Bearer', api_base_url_for_customer: emptyish }),
+      ) as unknown as typeof fetch
+
+      const provider = createConnectorAdapterProvider({
+        adapters: [oauthAdapter({ apiBaseUrlForCustomer: { field: 'api_base_url_for_customer', required: true } })],
+        resolveDataSource: () => ({ kind: 'demo-oauth', id: 'ds_demo' }) as never,
+        resolveOAuthClient: () => ({ clientId: 'cid_live', clientSecret: 'sec_live' }),
+        fetchImpl,
+      })
+
+      await expect(
+        provider.completeAuth!({
+          connectorId: 'demo-oauth',
+          owner: OWNER,
+          code: 'the_code',
+          state: 'state_xyz',
+          redirectUri: REDIRECT,
+        }),
+      ).rejects.toMatchObject({ code: 'provider_failure' })
+    }
+  })
+
+  it('completeAuth omits a non-required tokenMetadata field that is present but empty/whitespace', async () => {
+    const fetchImpl = vi.fn(async () =>
+      tokenResponse({ access_token: 'acc_xyz', token_type: 'Bearer', instance_url: '   ' }),
+    ) as unknown as typeof fetch
+
+    const provider = createConnectorAdapterProvider({
+      adapters: [oauthAdapter({ instanceUrl: 'instance_url' })],
+      resolveDataSource: () => ({ kind: 'demo-oauth', id: 'ds_demo' }) as never,
+      resolveOAuthClient: () => ({ clientId: 'cid_live', clientSecret: 'sec_live' }),
+      fetchImpl,
+    })
+
+    const conn = await provider.completeAuth!({
+      connectorId: 'demo-oauth',
+      owner: OWNER,
+      code: 'the_code',
+      state: 'state_xyz',
+      redirectUri: REDIRECT,
+    })
+
+    expect('instanceUrl' in (conn.metadata ?? {})).toBe(false)
+  })
 })

src/adapter-provider.ts

@@ -5,6 +5,7 @@ import type {
   ConnectorCredentials,
   ConnectorInvocation,
   ResolvedDataSource,
+  TokenMetadataSource,
 } from './connectors/types.js'
 import type {
   CompleteAuthRequest,
@@ -204,7 +205,7 @@ export function createConnectorAdapterProvider(options: ConnectorAdapterProvider
         expires_in?: number
         scope?: string
         token_type?: string
-      }
+      } & Record<string, unknown>
       try {
         json = await res.json()
       } catch {
@@ -227,6 +228,11 @@ export function createConnectorAdapterProvider(options: ConnectorAdapterProvider
       const expiresAt = typeof json.expires_in === 'number' && json.expires_in > 0
         ? new Date(issued.getTime() + json.expires_in * 1000).toISOString()
         : undefined
+      // Persist provider-specific token-response fields the connector declared
+      // via `auth.tokenMetadata` into the connection metadata (e.g. Gong's
+      // per-customer `api_base_url_for_customer`). The captured values win over
+      // any same-key request.metadata — the token exchange is authoritative.
+      const capturedMetadata = captureTokenMetadata(auth.tokenMetadata, json, request.connectorId)
       return {
         id: randomConnectionId(),
         owner: request.owner,
@@ -237,7 +243,7 @@ export function createConnectorAdapterProvider(options: ConnectorAdapterProvider
         createdAt: issuedIso,
         updatedAt: issuedIso,
         expiresAt,
-        metadata: request.metadata,
+        metadata: { ...request.metadata, ...capturedMetadata },
       }
     },
     async invokeAction(connection, request) {
@@ -408,6 +414,42 @@ function oauthManifestAuth(auth: ConnectorAdapter['manifest']['auth']): Extract<
   return auth.options.find((option): option is Extract<typeof option, { kind: 'oauth2' }> => option.kind === 'oauth2')
 }
 
+/** Project the declared `auth.tokenMetadata` mappings out of an OAuth
+ *  token-response body into connection metadata. Each entry maps a
+ *  connection-metadata key → the token-response field to read (string
+ *  shorthand) or `{ field, required }`. Required fields that are absent/empty
+ *  throw `provider_failure` so the break surfaces at connect; non-required
+ *  fields are captured if present and otherwise skipped. */
+function captureTokenMetadata(
+  tokenMetadata: Record<string, TokenMetadataSource> | undefined,
+  json: Record<string, unknown>,
+  connectorId: string,
+): Record<string, string> {
+  if (!tokenMetadata) return {}
+  const captured: Record<string, string> = {}
+  for (const [metaKey, source] of Object.entries(tokenMetadata)) {
+    const field = typeof source === 'string' ? source : source.field
+    const required = typeof source === 'string' ? false : source.required === true
+    const raw = json[field]
+    // Trim string values so capture-side emptiness matches the consumer's
+    // emptiness check (e.g. resolveBaseUrl's `.trim()` guard). A whitespace-only
+    // value must fail loud here at connect for a required field, not defer the
+    // break to first call where the host already looks active.
+    const value = typeof raw === 'string' ? raw.trim() : raw
+    if (value === undefined || value === null || value === '') {
+      if (required) {
+        throw new IntegrationError(
+          `OAuth token exchange for ${connectorId} did not return required field "${field}" for metadata.${metaKey}.`,
+          'provider_failure',
+        )
+      }
+      continue
+    }
+    captured[metaKey] = String(value)
+  }
+  return captured
+}
+
 function mapCategory(category: ConnectorAdapter['manifest']['category']): IntegrationConnector['category'] {
   if (category === 'comms') return 'chat'
   if (category === 'spreadsheet') return 'database'

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

@@ -52,6 +52,18 @@ describe('gong adapter', () => {
     expect(gongConnector.manifest.category).toBe('comms')
   })
 
+  it('declares a required tokenMetadata capture for the per-customer base URL', () => {
+    // The contract that completeAuth honors: persist the token-exchange
+    // `api_base_url_for_customer` into metadata.apiBaseUrlForCustomer (required).
+    // The companion test below proves call-time `baseUrl` resolution reads that
+    // same metadata key, closing the loop from token exchange to first call.
+    const auth = gongConnector.manifest.auth
+    if (auth.kind !== 'oauth2') throw new Error('auth narrowing failed')
+    expect(auth.tokenMetadata).toEqual({
+      apiBaseUrlForCustomer: { field: 'api_base_url_for_customer', required: true },
+    })
+  })
+
   it('exposes the expected capability surface and read/mutation split', () => {
     const names = gongConnector.manifest.capabilities.map((c) => c.name).sort()
     expect(names).toEqual([

src/connectors/adapters/gong.ts

@@ -8,14 +8,15 @@ import { declarativeRestConnector } from './declarative-rest.js'
  * app.gong.io/oauth2/generate-customer-token. The token response carries an
  * `api_base_url_for_customer` (e.g. https://company-17.api.gong.io) that ALL
  * subsequent API calls must target — the generic api.gong.io host is only
- * valid for the legacy access-key (Basic) auth, NOT for OAuth apps. The hub
- * connect flow MUST persist that per-customer host (returned at token
- * exchange) into `metadata.apiBaseUrlForCustomer`; we resolve `baseUrl`
- * strictly from it with NO fallback. If the metadata is absent every call
- * fails loud (`missing metadata.apiBaseUrlForCustomer base URL`) rather than
- * silently routing to the OAuth-invalid generic host and looking active while
- * every request fails. Because the resolved base is a bare host (no version),
- * each capability path carries its own `/v2` prefix.
+ * valid for the legacy access-key (Basic) auth, NOT for OAuth apps. We capture
+ * that per-customer host into `metadata.apiBaseUrlForCustomer` declaratively
+ * via `auth.tokenMetadata` (required), so the token-exchange path persists it;
+ * we then resolve `baseUrl` strictly from that metadata key with NO fallback.
+ * If the metadata is absent every call fails loud (`missing
+ * metadata.apiBaseUrlForCustomer base URL`) rather than silently routing to
+ * the OAuth-invalid generic host and looking active while every request fails.
+ * Because the resolved base is a bare host (no version), each capability path
+ * carries its own `/v2` prefix.
  *
  * Scopes are selected when registering the OAuth app in Gong's admin center
  * and echoed back on the token; we request the read+create scopes that back
@@ -40,6 +41,12 @@ export const gongConnector = declarativeRestConnector({
     ],
     clientIdEnv: 'GONG_OAUTH_CLIENT_ID',
     clientSecretEnv: 'GONG_OAUTH_CLIENT_SECRET',
+    // Gong returns the per-customer API host on the token response; capture it
+    // into metadata.apiBaseUrlForCustomer so `baseUrl` resolution below finds
+    // it. Required: the generic api.gong.io host is invalid for OAuth apps, so
+    // a missing value fails the exchange loud rather than minting a connection
+    // that looks active while every call 404s.
+    tokenMetadata: { apiBaseUrlForCustomer: { field: 'api_base_url_for_customer', required: true } },
   },
   category: 'comms',
   defaultConsistencyModel: 'authoritative',

src/connectors/types.ts

@@ -343,6 +343,12 @@ export interface RateLimitSpec {
   scope?: 'oauth-client' | 'data-source'
 }
 
+/** Source mapping for `OAuth2AuthSpec.tokenMetadata`. A bare string names the
+ *  token-response field to capture (capture-if-present). The object form marks
+ *  the field `required` so a missing/empty value fails the token exchange loud
+ *  rather than silently capturing nothing. */
+export type TokenMetadataSource = string | { field: string; required?: boolean }
+
 type OAuth2AuthSpec = {
   kind: 'oauth2'
   /** OAuth2 grant type. Defaults to `'authorization_code'` (the interactive
@@ -374,6 +380,18 @@ type OAuth2AuthSpec = {
    *  Defaults to true. Set false for providers that reject a per-request
    *  scope and pin scopes app-side (e.g. HelloSign/Dropbox Sign). */
   sendScopeParam?: boolean
+  /** Declarative capture of provider-specific fields from the OAuth token
+   *  response into the connection's `metadata`, keyed by the connection-metadata
+   *  key to write → the token-response field to read. The counterpart to
+   *  `baseUrl.metadataKey`: providers like Gong return a per-customer host
+   *  (`api_base_url_for_customer`) at token exchange that every later call must
+   *  target, but the standard token parser keeps only the canonical OAuth
+   *  fields and drops the rest. Declaring the mapping here makes `completeAuth`
+   *  persist the value into `metadata` so `baseUrl` resolution finds it. Mark a
+   *  field `required` to fail the exchange loud when it is absent (surfacing the
+   *  break at connect, not first call). Optional and backward-compatible —
+   *  connectors that omit it are unaffected. */
+  tokenMetadata?: Record<string, TokenMetadataSource>
 }
 type ApiKeyAuthSpec = {
   kind: 'api-key'