@commandable/integration-data 0.4.0 → 0.5.0

package/integrations/hubspot/__tests__/write_handlers.test.ts

@@ -0,0 +1,244 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import {
+  createCredentialStore,
+  createIntegrationNode,
+  createProxy,
+  createToolbox,
+  hasEnv,
+  safeCleanup,
+} from '../../__tests__/liveHarness.js'
+
+// LIVE HubSpot write tests using credentials
+// Required env vars:
+// - HUBSPOT_TOKEN
+//
+// Optional env vars (pin pipeline/stage IDs):
+// - HUBSPOT_TEST_DEAL_PIPELINE_ID
+// - HUBSPOT_TEST_DEAL_STAGE_ID
+// - HUBSPOT_TEST_TICKET_PIPELINE_ID
+// - HUBSPOT_TEST_TICKET_STAGE_ID
+
+const env = process.env as Record<string, string | undefined>
+const suite = hasEnv('HUBSPOT_TOKEN') ? describe : describe.skip
+
+function pickFirstPipelineAndStage(resp: any): { pipelineId?: string, stageId?: string } {
+  const pipelines = resp?.results || resp?.pipelines || resp
+  if (!Array.isArray(pipelines))
+    return {}
+
+  for (const p of pipelines) {
+    const pipelineId = p?.id
+    const stages = p?.stages
+    if (!pipelineId || !Array.isArray(stages) || stages.length === 0)
+      continue
+    const stageId = stages.find((s: any) => s?.id)?.id
+    if (stageId)
+      return { pipelineId: String(pipelineId), stageId: String(stageId) }
+  }
+
+  return {}
+}
+
+suite('hubspot write handlers (live)', () => {
+  const ctx: {
+    contactId?: string
+    companyId?: string
+    taskId?: string
+    dealId?: string
+    ticketId?: string
+  } = {}
+
+  let read: Record<string, (input: any) => Promise<any>>
+  let write: Record<string, (input: any) => Promise<any>>
+
+  beforeAll(async () => {
+    const credentialStore = createCredentialStore(async () => ({ token: env.HUBSPOT_TOKEN || '' }))
+    const proxy = createProxy(credentialStore)
+    const node = createIntegrationNode('hubspot')
+    const toolbox = createToolbox('hubspot', proxy, node)
+
+    // IMPORTANT: These literal tool-name strings are intentionally present so usage-parity can verify coverage.
+    read = {
+      list_pipelines: toolbox.read('list_pipelines'),
+    }
+
+    write = {
+      create_contact: toolbox.write('create_contact'),
+      update_contact: toolbox.write('update_contact'),
+      archive_contact: toolbox.write('archive_contact'),
+
+      create_company: toolbox.write('create_company'),
+      update_company: toolbox.write('update_company'),
+      archive_company: toolbox.write('archive_company'),
+
+      create_association: toolbox.write('create_association'),
+      remove_association: toolbox.write('remove_association'),
+
+      create_note: toolbox.write('create_note'),
+
+      create_task: toolbox.write('create_task'),
+      update_task: toolbox.write('update_task'),
+
+      create_deal: toolbox.write('create_deal'),
+      update_deal: toolbox.write('update_deal'),
+      archive_deal: toolbox.write('archive_deal'),
+
+      create_ticket: toolbox.write('create_ticket'),
+      update_ticket: toolbox.write('update_ticket'),
+      archive_ticket: toolbox.write('archive_ticket'),
+    }
+
+    expect(read).toBeTruthy()
+    expect(write).toBeTruthy()
+  }, 60000)
+
+  it('contact/company/engagements roundtrip', async () => {
+    const uniq = Date.now()
+
+    // Create contact
+    const createdContact = await write.create_contact({
+      firstname: 'CmdTest',
+      lastname: `HubSpot ${uniq}`,
+      email: `cmdtest+hubspot-${uniq}@example.com`,
+    })
+    ctx.contactId = createdContact?.id
+    expect(ctx.contactId).toBeTruthy()
+
+    // Update contact
+    await write.update_contact({
+      id: ctx.contactId,
+      firstname: 'CmdTestUpdated',
+    })
+
+    // Create company
+    const createdCompany = await write.create_company({
+      name: `CmdTest HubSpot Company ${uniq}`,
+      domain: `cmdtest-${uniq}.example.com`,
+    })
+    ctx.companyId = createdCompany?.id
+    expect(ctx.companyId).toBeTruthy()
+
+    // Associate contact <-> company
+    await write.create_association({
+      fromObjectType: 'contacts',
+      fromObjectId: ctx.contactId,
+      toObjectType: 'companies',
+      toObjectId: ctx.companyId,
+    })
+
+    // Remove association
+    await write.remove_association({
+      fromObjectType: 'contacts',
+      fromObjectId: ctx.contactId,
+      toObjectType: 'companies',
+      toObjectId: ctx.companyId,
+    })
+
+    // Create note associated to contact
+    await write.create_note({
+      body: `CmdTest note ${uniq}`,
+      associateWith: [{ objectType: 'contacts', objectId: ctx.contactId }],
+    })
+
+    // Create task associated to contact
+    const createdTask = await write.create_task({
+      subject: `CmdTest task ${uniq}`,
+      body: 'Created by integration test',
+      status: 'NOT_STARTED',
+      priority: 'MEDIUM',
+      dueTimestamp: Date.now() + 60 * 60 * 1000,
+      associateWith: [{ objectType: 'contacts', objectId: ctx.contactId }],
+    })
+    ctx.taskId = createdTask?.task?.id || createdTask?.id
+    expect(ctx.taskId).toBeTruthy()
+
+    // Mark task completed
+    await write.update_task({
+      id: ctx.taskId,
+      status: 'COMPLETED',
+    })
+
+    // Cleanup (best-effort)
+    await safeCleanup(async () => {
+      if (ctx.companyId)
+        await write.archive_company({ id: ctx.companyId })
+    })
+    await safeCleanup(async () => {
+      if (ctx.contactId)
+        await write.archive_contact({ id: ctx.contactId })
+    })
+  }, 120000)
+
+  it('deal and ticket roundtrip when pipeline + stage IDs are available', async () => {
+    const uniq = Date.now()
+
+    // Deals
+    let dealPipelineId = env.HUBSPOT_TEST_DEAL_PIPELINE_ID
+    let dealStageId = env.HUBSPOT_TEST_DEAL_STAGE_ID
+    if (!dealPipelineId || !dealStageId) {
+      try {
+        const pipelinesResp = await read.list_pipelines({ objectType: 'deals' })
+        const picked = pickFirstPipelineAndStage(pipelinesResp)
+        dealPipelineId = dealPipelineId || picked.pipelineId
+        dealStageId = dealStageId || picked.stageId
+      } catch {
+        // If scopes don't allow pipelines, skip deal tests.
+      }
+    }
+
+    if (dealPipelineId && dealStageId) {
+      const createdDeal = await write.create_deal({
+        dealname: `CmdTest Deal ${uniq}`,
+        amount: 123,
+        pipeline: dealPipelineId,
+        dealstage: dealStageId,
+      })
+      ctx.dealId = createdDeal?.id
+      expect(ctx.dealId).toBeTruthy()
+
+      await write.update_deal({ id: ctx.dealId, amount: 456 })
+
+      await safeCleanup(async () => {
+        if (ctx.dealId)
+          await write.archive_deal({ id: ctx.dealId })
+      })
+    } else {
+      expect(true).toBe(true)
+    }
+
+    // Tickets
+    let ticketPipelineId = env.HUBSPOT_TEST_TICKET_PIPELINE_ID
+    let ticketStageId = env.HUBSPOT_TEST_TICKET_STAGE_ID
+    if (!ticketPipelineId || !ticketStageId) {
+      try {
+        const pipelinesResp = await read.list_pipelines({ objectType: 'tickets' })
+        const picked = pickFirstPipelineAndStage(pipelinesResp)
+        ticketPipelineId = ticketPipelineId || picked.pipelineId
+        ticketStageId = ticketStageId || picked.stageId
+      } catch {
+        // If scopes don't allow pipelines, skip ticket tests.
+      }
+    }
+
+    if (ticketPipelineId && ticketStageId) {
+      const createdTicket = await write.create_ticket({
+        subject: `CmdTest Ticket ${uniq}`,
+        content: 'Created by integration test',
+        hs_pipeline: ticketPipelineId,
+        hs_pipeline_stage: ticketStageId,
+      })
+      ctx.ticketId = createdTicket?.id
+      expect(ctx.ticketId).toBeTruthy()
+
+      await write.update_ticket({ id: ctx.ticketId, subject: `CmdTest Ticket Updated ${uniq}` })
+
+      await safeCleanup(async () => {
+        if (ctx.ticketId)
+          await write.archive_ticket({ id: ctx.ticketId })
+      })
+    } else {
+      expect(true).toBe(true)
+    }
+  }, 180000)
+})
+

package/integrations/hubspot/credentials.json

@@ -0,0 +1,50 @@
+{
+  "variants": {
+    "private_app_token": {
+      "label": "Private App Token",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "title": "Private app access token",
+            "description": "HubSpot private app access token. This is sent as a Bearer token in the Authorization header."
+          }
+        },
+        "required": ["token"],
+        "additionalProperties": false
+      },
+      "injection": {
+        "headers": {
+          "Authorization": "Bearer {{token}}",
+          "Accept": "application/json"
+        }
+      },
+      "healthCheck": { "path": "/crm/v3/owners?limit=1" }
+    },
+    "oauth_token": {
+      "label": "OAuth Access Token",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "title": "OAuth access token",
+            "description": "OAuth 2.0 access token for HubSpot (Bearer token)."
+          }
+        },
+        "required": ["token"],
+        "additionalProperties": false
+      },
+      "injection": {
+        "headers": {
+          "Authorization": "Bearer {{token}}",
+          "Accept": "application/json"
+        }
+      },
+      "healthCheck": { "path": "/crm/v3/owners?limit=1" }
+    }
+  },
+  "default": "private_app_token"
+}
+

package/integrations/hubspot/credentials_hint.md

@@ -0,0 +1,20 @@
+## HubSpot credentials (Private App Token)
+
+1. In HubSpot, open **Settings**.
+2. Go to **Integrations** → **Private Apps**.
+3. Click **Create private app**.
+4. Name the app (e.g. "Commandable MCP") and save.
+5. In **Scopes**, enable at least:
+   - `crm.objects.contacts.read` / `crm.objects.contacts.write`
+   - `crm.objects.companies.read` / `crm.objects.companies.write`
+   - `crm.objects.deals.read` / `crm.objects.deals.write`
+   - `tickets` (for tickets read/write)
+   - `crm.objects.owners.read`
+   - `crm.schemas.contacts.read`, `crm.schemas.companies.read`, `crm.schemas.deals.read`, `crm.schemas.tickets.read` (for listing properties)
+6. Create the app and copy the generated **Access token**.
+7. Paste the token into this integration's `token` credential field.
+
+Notes:
+- Keep this token secret. Anyone with the token can access your HubSpot account within the app's scopes.
+- If you get 401/403 errors, double-check the app scopes and that the token is still active.
+

package/integrations/hubspot/credentials_hint_oauth_token.md

@@ -0,0 +1,16 @@
+## HubSpot credentials (OAuth access token)
+
+1. Create (or use an existing) HubSpot public app that can issue OAuth 2.0 access tokens.
+2. Ensure the app requests the scopes you need (for example):
+   - `crm.objects.contacts.read` / `crm.objects.contacts.write`
+   - `crm.objects.companies.read` / `crm.objects.companies.write`
+   - `crm.objects.deals.read` / `crm.objects.deals.write`
+   - `tickets`
+   - `crm.objects.owners.read`
+   - relevant `crm.schemas.*.read` scopes if you want to list properties
+3. Complete the OAuth authorization code flow to obtain an **access token**.
+4. Paste the access token into this integration's `token` credential field.
+
+Notes:
+- HubSpot OAuth access tokens are short-lived. If calls start failing with 401, refresh and provide a new access token.
+

package/integrations/hubspot/handlers/archive_company.js

@@ -0,0 +1,13 @@
+async (input) => {
+  const res = await integration.fetch(`/crm/v3/objects/companies/${encodeURIComponent(input.id)}`, {
+    method: 'DELETE',
+  })
+  const text = await res.text()
+  if (!text) return { ok: res.ok, status: res.status }
+  try {
+    return JSON.parse(text)
+  } catch {
+    return { ok: res.ok, status: res.status, body: text }
+  }
+}
+

package/integrations/hubspot/handlers/archive_contact.js

@@ -0,0 +1,13 @@
+async (input) => {
+  const res = await integration.fetch(`/crm/v3/objects/contacts/${encodeURIComponent(input.id)}`, {
+    method: 'DELETE',
+  })
+  const text = await res.text()
+  if (!text) return { ok: res.ok, status: res.status }
+  try {
+    return JSON.parse(text)
+  } catch {
+    return { ok: res.ok, status: res.status, body: text }
+  }
+}
+

package/integrations/hubspot/handlers/archive_deal.js

@@ -0,0 +1,13 @@
+async (input) => {
+  const res = await integration.fetch(`/crm/v3/objects/deals/${encodeURIComponent(input.id)}`, {
+    method: 'DELETE',
+  })
+  const text = await res.text()
+  if (!text) return { ok: res.ok, status: res.status }
+  try {
+    return JSON.parse(text)
+  } catch {
+    return { ok: res.ok, status: res.status, body: text }
+  }
+}
+

package/integrations/hubspot/handlers/archive_ticket.js

@@ -0,0 +1,13 @@
+async (input) => {
+  const res = await integration.fetch(`/crm/v3/objects/tickets/${encodeURIComponent(input.id)}`, {
+    method: 'DELETE',
+  })
+  const text = await res.text()
+  if (!text) return { ok: res.ok, status: res.status }
+  try {
+    return JSON.parse(text)
+  } catch {
+    return { ok: res.ok, status: res.status, body: text }
+  }
+}
+

package/integrations/hubspot/handlers/create_association.js

@@ -0,0 +1,18 @@
+async (input) => {
+  const res = await integration.fetch(
+    `/crm/v4/objects/${encodeURIComponent(input.fromObjectType)}/${encodeURIComponent(
+      input.fromObjectId
+    )}/associations/default/${encodeURIComponent(input.toObjectType)}/${encodeURIComponent(
+      input.toObjectId
+    )}`,
+    { method: 'PUT' }
+  )
+  const text = await res.text()
+  if (!text) return { ok: res.ok, status: res.status }
+  try {
+    return JSON.parse(text)
+  } catch {
+    return { ok: res.ok, status: res.status, body: text }
+  }
+}
+

package/integrations/hubspot/handlers/create_company.js

@@ -0,0 +1,13 @@
+async (input) => {
+  const props = { ...(input.properties || {}) }
+  if (input.name !== undefined) props.name = input.name
+  if (input.domain !== undefined) props.domain = input.domain
+
+  const body = { properties: props }
+  const res = await integration.fetch(`/crm/v3/objects/companies`, {
+    method: 'POST',
+    body,
+  })
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/create_contact.js

@@ -0,0 +1,14 @@
+async (input) => {
+  const props = { ...(input.properties || {}) }
+  if (input.firstname !== undefined) props.firstname = input.firstname
+  if (input.lastname !== undefined) props.lastname = input.lastname
+  if (input.email !== undefined) props.email = input.email
+
+  const body = { properties: props }
+  const res = await integration.fetch(`/crm/v3/objects/contacts`, {
+    method: 'POST',
+    body,
+  })
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/create_deal.js

@@ -0,0 +1,16 @@
+async (input) => {
+  const props = { ...(input.properties || {}) }
+  if (input.dealname !== undefined) props.dealname = input.dealname
+  if (input.amount !== undefined) props.amount = String(input.amount)
+  if (input.pipeline !== undefined) props.pipeline = input.pipeline
+  if (input.dealstage !== undefined) props.dealstage = input.dealstage
+  if (input.closedate !== undefined) props.closedate = String(input.closedate)
+
+  const body = { properties: props }
+  const res = await integration.fetch(`/crm/v3/objects/deals`, {
+    method: 'POST',
+    body,
+  })
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/create_note.js

@@ -0,0 +1,44 @@
+async (input) => {
+  const nowMs = Date.now()
+
+  const props = {
+    hs_note_body: input.body,
+    hs_timestamp: input.timestamp !== undefined ? String(input.timestamp) : String(nowMs),
+    ...(input.properties || {}),
+  }
+
+  if (input.hubspot_owner_id !== undefined) {
+    props.hubspot_owner_id = String(input.hubspot_owner_id)
+  }
+
+  const createRes = await integration.fetch(`/crm/v3/objects/notes`, {
+    method: 'POST',
+    body: { properties: props },
+  })
+  const note = await createRes.json()
+
+  const associationResults = []
+  if (Array.isArray(input.associateWith) && input.associateWith.length > 0 && note?.id) {
+    for (const a of input.associateWith) {
+      const res = await integration.fetch(
+        `/crm/v4/objects/notes/${encodeURIComponent(String(note.id))}/associations/default/${encodeURIComponent(
+          a.objectType
+        )}/${encodeURIComponent(a.objectId)}`,
+        { method: 'PUT' }
+      )
+      const text = await res.text()
+      if (!text) {
+        associationResults.push({ ok: res.ok, status: res.status })
+      } else {
+        try {
+          associationResults.push(JSON.parse(text))
+        } catch {
+          associationResults.push({ ok: res.ok, status: res.status, body: text })
+        }
+      }
+    }
+  }
+
+  return { note, associationResults }
+}
+

package/integrations/hubspot/handlers/create_task.js

@@ -0,0 +1,48 @@
+async (input) => {
+  const nowMs = Date.now()
+
+  const props = {
+    hs_task_subject: input.subject,
+    hs_task_body: input.body,
+    hs_task_status: input.status,
+    hs_task_priority: input.priority,
+    hs_timestamp:
+      input.dueTimestamp !== undefined ? String(input.dueTimestamp) : String(nowMs),
+    ...(input.properties || {}),
+  }
+
+  if (input.hubspot_owner_id !== undefined) {
+    props.hubspot_owner_id = String(input.hubspot_owner_id)
+  }
+
+  const createRes = await integration.fetch(`/crm/v3/objects/tasks`, {
+    method: 'POST',
+    body: { properties: props },
+  })
+  const task = await createRes.json()
+
+  const associationResults = []
+  if (Array.isArray(input.associateWith) && input.associateWith.length > 0 && task?.id) {
+    for (const a of input.associateWith) {
+      const res = await integration.fetch(
+        `/crm/v4/objects/tasks/${encodeURIComponent(String(task.id))}/associations/default/${encodeURIComponent(
+          a.objectType
+        )}/${encodeURIComponent(a.objectId)}`,
+        { method: 'PUT' }
+      )
+      const text = await res.text()
+      if (!text) {
+        associationResults.push({ ok: res.ok, status: res.status })
+      } else {
+        try {
+          associationResults.push(JSON.parse(text))
+        } catch {
+          associationResults.push({ ok: res.ok, status: res.status, body: text })
+        }
+      }
+    }
+  }
+
+  return { task, associationResults }
+}
+

package/integrations/hubspot/handlers/create_ticket.js

@@ -0,0 +1,15 @@
+async (input) => {
+  const props = { ...(input.properties || {}) }
+  if (input.subject !== undefined) props.subject = input.subject
+  if (input.content !== undefined) props.content = input.content
+  if (input.hs_pipeline !== undefined) props.hs_pipeline = input.hs_pipeline
+  if (input.hs_pipeline_stage !== undefined) props.hs_pipeline_stage = input.hs_pipeline_stage
+
+  const body = { properties: props }
+  const res = await integration.fetch(`/crm/v3/objects/tickets`, {
+    method: 'POST',
+    body,
+  })
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/get_associations.js

@@ -0,0 +1,14 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input?.after) params.set('after', String(input.after))
+  if (input?.limit) params.set('limit', String(input.limit))
+
+  const suffix = params.toString() ? `?${params.toString()}` : ''
+  const res = await integration.fetch(
+    `/crm/v4/objects/${encodeURIComponent(input.fromObjectType)}/${encodeURIComponent(
+      input.fromObjectId
+    )}/associations/${encodeURIComponent(input.toObjectType)}${suffix}`
+  )
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/get_company.js

@@ -0,0 +1,18 @@
+async (input) => {
+  const params = new URLSearchParams()
+
+  if (Array.isArray(input.properties)) {
+    for (const p of input.properties) params.append('properties', p)
+  }
+
+  if (Array.isArray(input.associations)) {
+    for (const a of input.associations) params.append('associations', a)
+  }
+
+  if (typeof input.archived === 'boolean') params.set('archived', String(input.archived))
+
+  const suffix = params.toString() ? `?${params.toString()}` : ''
+  const res = await integration.fetch(`/crm/v3/objects/companies/${encodeURIComponent(input.id)}${suffix}`)
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/get_contact.js

@@ -0,0 +1,18 @@
+async (input) => {
+  const params = new URLSearchParams()
+
+  if (Array.isArray(input.properties)) {
+    for (const p of input.properties) params.append('properties', p)
+  }
+
+  if (Array.isArray(input.associations)) {
+    for (const a of input.associations) params.append('associations', a)
+  }
+
+  if (typeof input.archived === 'boolean') params.set('archived', String(input.archived))
+
+  const suffix = params.toString() ? `?${params.toString()}` : ''
+  const res = await integration.fetch(`/crm/v3/objects/contacts/${encodeURIComponent(input.id)}${suffix}`)
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/get_deal.js

@@ -0,0 +1,18 @@
+async (input) => {
+  const params = new URLSearchParams()
+
+  if (Array.isArray(input.properties)) {
+    for (const p of input.properties) params.append('properties', p)
+  }
+
+  if (Array.isArray(input.associations)) {
+    for (const a of input.associations) params.append('associations', a)
+  }
+
+  if (typeof input.archived === 'boolean') params.set('archived', String(input.archived))
+
+  const suffix = params.toString() ? `?${params.toString()}` : ''
+  const res = await integration.fetch(`/crm/v3/objects/deals/${encodeURIComponent(input.id)}${suffix}`)
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/get_ticket.js

@@ -0,0 +1,20 @@
+async (input) => {
+  const params = new URLSearchParams()
+
+  if (Array.isArray(input.properties)) {
+    for (const p of input.properties) params.append('properties', p)
+  }
+
+  if (Array.isArray(input.associations)) {
+    for (const a of input.associations) params.append('associations', a)
+  }
+
+  if (typeof input.archived === 'boolean') params.set('archived', String(input.archived))
+
+  const suffix = params.toString() ? `?${params.toString()}` : ''
+  const res = await integration.fetch(
+    `/crm/v3/objects/tickets/${encodeURIComponent(input.id)}${suffix}`
+  )
+  return await res.json()
+}
+

package/integrations/hubspot/handlers/list_owners.js

@@ -0,0 +1,12 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input?.email) params.set('email', input.email)
+  if (input?.after) params.set('after', String(input.after))
+  if (input?.limit) params.set('limit', String(input.limit))
+  if (typeof input?.archived === 'boolean') params.set('archived', String(input.archived))
+
+  const suffix = params.toString() ? `?${params.toString()}` : ''
+  const res = await integration.fetch(`/crm/v3/owners/${suffix}`)
+  return await res.json()
+}
+