@commandable/integration-data 0.0.6 → 0.0.7

package/integrations/hubspot/schemas/search_tasks.json

@@ -0,0 +1,43 @@
+{
+  "type": "object",
+  "properties": {
+    "query": { "type": "string", "description": "Free-text search query (optional)." },
+    "filters": {
+      "type": "array",
+      "description": "Property-based filters converted into HubSpot filterGroups.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "propertyName": { "type": "string" },
+          "operator": {
+            "type": "string",
+            "enum": [
+              "EQ",
+              "NEQ",
+              "LT",
+              "LTE",
+              "GT",
+              "GTE",
+              "BETWEEN",
+              "HAS_PROPERTY",
+              "NOT_HAS_PROPERTY",
+              "CONTAINS_TOKEN"
+            ]
+          },
+          "value": { "type": ["string", "number", "boolean"] }
+        },
+        "required": ["propertyName", "operator"],
+        "additionalProperties": false
+      }
+    },
+    "properties": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Which task properties to return (e.g. hs_task_subject, hs_task_status, hs_timestamp)."
+    },
+    "limit": { "type": "integer", "minimum": 1, "maximum": 100 },
+    "after": { "type": "string", "description": "Paging cursor token." }
+  },
+  "additionalProperties": false
+}
+

package/integrations/hubspot/schemas/search_tickets.json

@@ -0,0 +1,43 @@
+{
+  "type": "object",
+  "properties": {
+    "query": { "type": "string", "description": "Free-text search query (optional)." },
+    "filters": {
+      "type": "array",
+      "description": "Property-based filters converted into HubSpot filterGroups.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "propertyName": { "type": "string" },
+          "operator": {
+            "type": "string",
+            "enum": [
+              "EQ",
+              "NEQ",
+              "LT",
+              "LTE",
+              "GT",
+              "GTE",
+              "BETWEEN",
+              "HAS_PROPERTY",
+              "NOT_HAS_PROPERTY",
+              "CONTAINS_TOKEN"
+            ]
+          },
+          "value": { "type": ["string", "number", "boolean"] }
+        },
+        "required": ["propertyName", "operator"],
+        "additionalProperties": false
+      }
+    },
+    "properties": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Which ticket properties to return."
+    },
+    "limit": { "type": "integer", "minimum": 1, "maximum": 100 },
+    "after": { "type": "string", "description": "Paging cursor token." }
+  },
+  "additionalProperties": false
+}
+

package/integrations/hubspot/schemas/update_company.json

@@ -0,0 +1,20 @@
+{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "title": "Company ID",
+      "description": "HubSpot company object ID."
+    },
+    "name": { "type": "string" },
+    "domain": { "type": "string" },
+    "properties": {
+      "type": "object",
+      "description": "HubSpot company properties to update (propertyName -> value).",
+      "additionalProperties": true
+    }
+  },
+  "required": ["id"],
+  "additionalProperties": false
+}
+

package/integrations/hubspot/schemas/update_contact.json

@@ -0,0 +1,21 @@
+{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "title": "Contact ID",
+      "description": "HubSpot contact object ID."
+    },
+    "firstname": { "type": "string" },
+    "lastname": { "type": "string" },
+    "email": { "type": "string" },
+    "properties": {
+      "type": "object",
+      "description": "HubSpot contact properties to update (propertyName -> value).",
+      "additionalProperties": true
+    }
+  },
+  "required": ["id"],
+  "additionalProperties": false
+}
+

package/integrations/hubspot/schemas/update_deal.json

@@ -0,0 +1,19 @@
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "HubSpot deal object ID." },
+    "dealname": { "type": "string" },
+    "amount": { "type": ["string", "number"] },
+    "pipeline": { "type": "string" },
+    "dealstage": { "type": "string" },
+    "closedate": { "type": ["string", "number"] },
+    "properties": {
+      "type": "object",
+      "description": "HubSpot deal properties to update (propertyName -> value).",
+      "additionalProperties": true
+    }
+  },
+  "required": ["id"],
+  "additionalProperties": false
+}
+

package/integrations/hubspot/schemas/update_task.json

@@ -0,0 +1,31 @@
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "HubSpot task object ID." },
+    "subject": { "type": "string", "description": "Maps to hs_task_subject." },
+    "body": { "type": "string", "description": "Maps to hs_task_body." },
+    "status": {
+      "type": "string",
+      "enum": ["NOT_STARTED", "COMPLETED"],
+      "description": "Maps to hs_task_status."
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["LOW", "MEDIUM", "HIGH"],
+      "description": "Maps to hs_task_priority."
+    },
+    "dueTimestamp": {
+      "type": ["string", "number"],
+      "description": "Maps to hs_timestamp (task due date/time). Prefer Unix timestamp in milliseconds."
+    },
+    "hubspot_owner_id": { "type": ["string", "number"] },
+    "properties": {
+      "type": "object",
+      "description": "Advanced: raw HubSpot task properties to update (propertyName -> value).",
+      "additionalProperties": true
+    }
+  },
+  "required": ["id"],
+  "additionalProperties": false
+}
+

package/integrations/hubspot/schemas/update_ticket.json

@@ -0,0 +1,18 @@
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "HubSpot ticket object ID." },
+    "subject": { "type": "string" },
+    "content": { "type": "string" },
+    "hs_pipeline": { "type": "string" },
+    "hs_pipeline_stage": { "type": "string" },
+    "properties": {
+      "type": "object",
+      "description": "HubSpot ticket properties to update (propertyName -> value).",
+      "additionalProperties": true
+    }
+  },
+  "required": ["id"],
+  "additionalProperties": false
+}
+

package/integrations/jira/.env.test

@@ -0,0 +1,46 @@
+# Jira (Jira Cloud)
+# Credentials mode uses an Atlassian API token (easy for local/CI).
+#
+# ----------------------
+# Variant: api_token
+# ----------------------
+# JIRA_DOMAIN:
+# - If your site URL is https://YOUR_DOMAIN.atlassian.net, then YOUR_DOMAIN is the value.
+JIRA_DOMAIN=commandable
+#
+# JIRA_EMAIL:
+# - The email address of the Atlassian account that owns the API token.
+JIRA_EMAIL=theo@commandable.ai
+#
+# JIRA_API_TOKEN:
+# - Create an Atlassian API token at:
+#   https://id.atlassian.com/manage-profile/security/api-tokens
+JIRA_API_TOKEN=ATATT3xFfGF0q1hqu1FdEJJHaLHdP6aHe2YwVWg2gu4TEBtP0ZWfFh46z7ZQDg0VHIE2PuVLw2MB7tgR-47cjuyVTXGS_UO1-VoKbODopCGCAR_BOWdcdWc5yN4QnIsU_V7LsWqj8hRNn9wEwkxthy3Um5brD26ehgEUeY9cvpjboiIqLcvEA6k=787A1BCE
+#
+# ----------------------
+# Jira write test configuration (required for write suite)
+# ----------------------
+# These tests create/update/comment/assign (and optionally transition/delete) issues.
+# Use a dedicated test project.
+
+# JIRA_TEST_PROJECT_KEY:
+# - The project key visible in the Jira UI, e.g. "PROJ".
+# - You can also get it from the URL when viewing a project (the key is usually shown in the URL and in the project header).
+JIRA_TEST_PROJECT_KEY=INTTEST
+#
+# Optional: transition testing
+# JIRA_TEST_TRANSITION_NAME:
+# - A transition name that exists in your project's workflow (case-insensitive).
+# - To find a valid transition name in the UI:
+#   1) Open any issue in the test project
+#   2) Click the status dropdown (e.g. \"To Do\" / \"In Progress\" / \"Done\")
+#   3) Use one of the visible transition actions as the name (e.g. \"Start Progress\", \"Done\")
+JIRA_TEST_TRANSITION_NAME="In Progress"
+#
+# Optional: sprint roundtrip testing (create_sprint -> move_issues_to_sprint -> delete_sprint)
+# JIRA_TEST_BOARD_ID:
+# - Numeric board ID (a Scrum board recommended).
+# - To find it in the UI:
+#   1) Open the board in Jira (Board view)
+#   2) The URL usually contains `/boards/<id>` — that number is the boardId
+JIRA_TEST_BOARD_ID=37

package/integrations/jira/.env.test.example

@@ -0,0 +1,41 @@
+# Jira (Jira Cloud) live integration tests
+#
+# Credentials mode uses an Atlassian API token (easy for local/CI).
+#
+# ----------------------
+# Variant: api_token
+# ----------------------
+# JIRA_DOMAIN:
+# - If your site URL is https://YOUR_DOMAIN.atlassian.net, then YOUR_DOMAIN is the value.
+JIRA_DOMAIN=
+#
+# JIRA_EMAIL:
+# - The email address of the Atlassian account that owns the API token.
+JIRA_EMAIL=
+#
+# JIRA_API_TOKEN:
+# - Create an Atlassian API token at: https://id.atlassian.com/manage-profile/security/api-tokens
+JIRA_API_TOKEN=
+#
+# ----------------------
+# Write test configuration
+# ----------------------
+# These tests create/update/comment/assign (and optionally transition/delete) issues.
+# Use a dedicated test project.
+#
+# JIRA_TEST_PROJECT_KEY:
+# - The project key visible in the Jira UI, e.g. "PROJ".
+JIRA_TEST_PROJECT_KEY=
+#
+# Optional: transition testing
+# JIRA_TEST_TRANSITION_NAME:
+# - A transition name that exists in your project's workflow (case-insensitive).
+# - To find one: open any issue → click the status dropdown → use a visible action name
+#   (e.g. "Start Progress", "Done")
+JIRA_TEST_TRANSITION_NAME=
+#
+# Optional: sprint roundtrip testing (create_sprint → move_issues_to_sprint → delete_sprint)
+# JIRA_TEST_BOARD_ID:
+# - Numeric board ID (a Scrum board recommended).
+# - To find it: open the board in Jira → the URL contains /boards/<id>
+JIRA_TEST_BOARD_ID=

package/integrations/jira/README.md

@@ -0,0 +1,46 @@
+# Jira
+
+**23 tools** across 2 toolsets
+
+![Jira tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/theomccabe/771bd329f303087690c522afa1baa6f3/raw/test-jira.json)
+
+## Credential variants
+
+| Variant | Label |
+|---|---|
+| `api_token` | API Token (Email + Token) _(default)_ |
+
+## Toolsets
+
+| Toolset | Description |
+|---|---|
+| `issues` | Search, read, create, and manage Jira issues |
+| `boards` | Work with Jira Software boards, sprints, and backlogs |
+
+## Tools
+
+| Tool | Scope | Toolset | Description |
+|---|---|---|---|
+| `search_issues` | read | `issues` | Search for issues using JQL. Returns a compact list of issues with key fields. Uses the m… |
+| `get_issue` | read | `issues` | Get details for a Jira issue by key (e.g. PROJ-123). Converts the issue description from … |
+| `get_issue_comments` | read | `issues` | List comments on an issue. Converts each comment body from Jira ADF into Markdown. |
+| `list_projects` | read | `issues` | List accessible Jira projects (key, name, type). Use this before creating issues to disco… |
+| `get_project` | read | `issues` | Get a project by key or ID. Includes issue types when expandIssueTypes=true, which is use… |
+| `get_transitions` | read | `issues` | List available workflow transitions for an issue. Use this to discover valid transition n… |
+| `get_myself` | read | `issues` | Get the authenticated Jira user profile for the current credentials. |
+| `search_users` | read | `issues` | Search for users and return accountIds for assignment. Use this to find assigneeAccountId… |
+| `create_issue` | write | `issues` | Create a new Jira issue. Provide descriptionText as Markdown; the handler converts it to … |
+| `update_issue` | write | `issues` | Update a Jira issue. You can use simple fields like summary/descriptionText/labels/priori… |
+| `transition_issue` | write | `issues` | Transition an issue to a new workflow status. Provide transitionId or transitionName. If … |
+| `add_comment` | write | `issues` | Add a comment to an issue. Provide bodyText as Markdown; the handler converts it to Jira … |
+| `assign_issue` | write | `issues` | Assign an issue to a user (by accountId) or unassign it (accountId=null). Use search_user… |
+| `delete_issue` | write | `issues` | Delete an issue. This is irreversible. Use with care. |
+| `list_boards` | read | `boards` | List Jira Software boards. Filter by projectKeyOrId and board type (scrum/kanban). |
+| `get_board` | read | `boards` | Get details for a Jira Software board by boardId. |
+| `list_sprints` | read | `boards` | List sprints for a board. Optionally filter by sprint state (future/active/closed). |
+| `get_sprint` | read | `boards` | Get sprint details by sprintId (name, state, start/end dates, goal). |
+| `get_sprint_issues` | read | `boards` | List issues in a sprint. Useful for sprint status reports and review preparation. |
+| `get_backlog_issues` | read | `boards` | List issues in the backlog for a board. |
+| `move_issues_to_sprint` | write | `boards` | Move one or more issues into a sprint (agile API). |
+| `create_sprint` | write | `boards` | Create a sprint in a board (agile API). Use this for sprint-planning workflows and for in… |
+| `update_sprint` | write | `boards` | Update a sprint (agile API). Use to rename, set/change goal, start a sprint (state: activ… |

package/integrations/jira/__tests__/get_handlers.test.ts

@@ -0,0 +1,193 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import { createCredentialStore, createIntegrationNode, createProxy, createToolbox, hasEnv } from '../../__tests__/liveHarness.js'
+
+// LIVE Jira read tests using credentials
+//
+// Variant: api_token
+// - JIRA_DOMAIN
+// - JIRA_EMAIL
+// - JIRA_API_TOKEN
+//
+// Optional (improves coverage):
+// - JIRA_TEST_PROJECT_KEY
+
+const env = process.env as Record<string, string | undefined>
+
+const suiteOrSkip = hasEnv('JIRA_DOMAIN', 'JIRA_EMAIL', 'JIRA_API_TOKEN') ? describe : describe.skip
+
+suiteOrSkip('jira read handlers (live)', () => {
+  describe('variant: api_token', () => {
+      const ctx: {
+        projectKey?: string
+        issueKey?: string
+        boardId?: number
+        sprintId?: number
+      } = {}
+
+      let jira: ReturnType<typeof createToolbox>
+
+      beforeAll(async () => {
+        const credentialStore = createCredentialStore(async () => ({
+          domain: env.JIRA_DOMAIN!,
+          email: env.JIRA_EMAIL!,
+          apiToken: env.JIRA_API_TOKEN!,
+        }))
+        const proxy = createProxy(credentialStore)
+        jira = createToolbox('jira', proxy, createIntegrationNode('jira', { label: 'Jira', credentialId: 'jira-creds', credentialVariant: 'api_token' }), 'api_token')
+
+        try {
+          const list_projects = jira.read('list_projects')
+          const projectsResp = await list_projects({ maxResults: 5 })
+          const first = projectsResp?.projects?.[0]
+          ctx.projectKey = env.JIRA_TEST_PROJECT_KEY || first?.key
+        }
+        catch {}
+
+        try {
+          if (ctx.projectKey) {
+            const search_issues = jira.read('search_issues')
+            const issuesResp = await search_issues({
+              jql: `project = ${ctx.projectKey} ORDER BY updated DESC`,
+              fields: ['summary', 'updated'],
+              maxResults: 1,
+            })
+            const firstIssue = issuesResp?.issues?.[0]
+            ctx.issueKey = firstIssue?.key
+          }
+        }
+        catch {}
+
+        try {
+          const list_boards = jira.read('list_boards')
+          const boardsResp = await list_boards({ maxResults: 5 })
+          const firstBoard = boardsResp?.boards?.[0]
+          ctx.boardId = typeof firstBoard?.id === 'number' ? firstBoard.id : undefined
+        }
+        catch {}
+
+        try {
+          if (ctx.boardId) {
+            const list_sprints = jira.read('list_sprints')
+            const sprintsResp = await list_sprints({ boardId: ctx.boardId, maxResults: 5 })
+            const firstSprint = sprintsResp?.sprints?.[0]
+            ctx.sprintId = typeof firstSprint?.id === 'number' ? firstSprint.id : undefined
+          }
+        }
+        catch {}
+      }, 60000)
+
+      it('get_myself returns authenticated user', async () => {
+        const get_myself = jira.read('get_myself')
+        const me = await get_myself({})
+        expect(me?.accountId).toBeTruthy()
+      }, 30000)
+
+      it('list_projects returns projects', async () => {
+        const list_projects = jira.read('list_projects')
+        const res = await list_projects({ maxResults: 5 })
+        expect(res?.projects).toBeTruthy()
+        expect(Array.isArray(res.projects)).toBe(true)
+      }, 30000)
+
+      it('get_project returns issueTypes when available', async () => {
+        if (!ctx.projectKey)
+          return expect(true).toBe(true)
+        const get_project = jira.read('get_project')
+        const project = await get_project({ projectIdOrKey: ctx.projectKey, expandIssueTypes: true })
+        expect(project?.key?.toUpperCase?.()).toBe(ctx.projectKey.toUpperCase())
+        expect(Array.isArray(project?.issueTypes)).toBe(true)
+      }, 30000)
+
+      it('search_issues returns issue list (best effort)', async () => {
+        if (!ctx.projectKey)
+          return expect(true).toBe(true)
+        const search_issues = jira.read('search_issues')
+        const res = await search_issues({ jql: `project = ${ctx.projectKey} ORDER BY updated DESC`, maxResults: 5 })
+        expect(res?.issues).toBeTruthy()
+        expect(Array.isArray(res.issues)).toBe(true)
+      }, 30000)
+
+      it('get_issue returns issue details (if any issue key discovered)', async () => {
+        if (!ctx.issueKey)
+          return expect(true).toBe(true)
+        const get_issue = jira.read('get_issue')
+        const issue = await get_issue({ issueIdOrKey: ctx.issueKey })
+        expect(issue?.key).toBe(ctx.issueKey)
+      }, 30000)
+
+      it('get_issue_comments returns comments (if any issue key discovered)', async () => {
+        if (!ctx.issueKey)
+          return expect(true).toBe(true)
+        const get_issue_comments = jira.read('get_issue_comments')
+        const comments = await get_issue_comments({ issueIdOrKey: ctx.issueKey, maxResults: 5 })
+        expect(comments?.comments).toBeTruthy()
+        expect(Array.isArray(comments.comments)).toBe(true)
+      }, 30000)
+
+      it('get_transitions returns transitions (if any issue key discovered)', async () => {
+        if (!ctx.issueKey)
+          return expect(true).toBe(true)
+        const get_transitions = jira.read('get_transitions')
+        const res = await get_transitions({ issueIdOrKey: ctx.issueKey })
+        expect(Array.isArray(res?.transitions)).toBe(true)
+      }, 30000)
+
+      it('search_users returns users (best effort)', async () => {
+        const get_myself = jira.read('get_myself')
+        const me = await get_myself({})
+        const query = me?.displayName || 'a'
+        const search_users = jira.read('search_users')
+        const res = await search_users({ query, maxResults: 5 })
+        expect(Array.isArray(res?.users)).toBe(true)
+      }, 30000)
+
+      it('boards: list_boards works (best effort)', async () => {
+        const list_boards = jira.read('list_boards')
+        const res = await list_boards({ maxResults: 5 })
+        expect(res?.boards).toBeTruthy()
+        expect(Array.isArray(res.boards)).toBe(true)
+      }, 30000)
+
+      it('boards: get_board works when boardId is available', async () => {
+        if (!ctx.boardId)
+          return expect(true).toBe(true)
+        const get_board = jira.read('get_board')
+        const board = await get_board({ boardId: ctx.boardId })
+        expect(board?.id).toBe(ctx.boardId)
+      }, 30000)
+
+      it('boards: list_sprints works when boardId is available', async () => {
+        if (!ctx.boardId)
+          return expect(true).toBe(true)
+        const list_sprints = jira.read('list_sprints')
+        const res = await list_sprints({ boardId: ctx.boardId, maxResults: 5 })
+        expect(res?.sprints).toBeTruthy()
+        expect(Array.isArray(res.sprints)).toBe(true)
+      }, 30000)
+
+      it('boards: get_sprint works when sprintId is available', async () => {
+        if (!ctx.sprintId)
+          return expect(true).toBe(true)
+        const get_sprint = jira.read('get_sprint')
+        const sprint = await get_sprint({ sprintId: ctx.sprintId })
+        expect(sprint?.id).toBe(ctx.sprintId)
+      }, 30000)
+
+      it('boards: get_sprint_issues works when sprintId is available', async () => {
+        if (!ctx.sprintId)
+          return expect(true).toBe(true)
+        const get_sprint_issues = jira.read('get_sprint_issues')
+        const res = await get_sprint_issues({ sprintId: ctx.sprintId, maxResults: 5 })
+        expect(res).toBeTruthy()
+      }, 30000)
+
+      it('boards: get_backlog_issues works when boardId is available', async () => {
+        if (!ctx.boardId)
+          return expect(true).toBe(true)
+        const get_backlog_issues = jira.read('get_backlog_issues')
+        const res = await get_backlog_issues({ boardId: ctx.boardId, maxResults: 5 })
+        expect(res).toBeTruthy()
+      }, 30000)
+  })
+})
+

package/integrations/jira/__tests__/usage_parity.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { getMissingToolUsages } from '../../__tests__/usageParity.js'
+
+describe('jira static usage parity', () => {
+  it('every api_token tool is referenced in tests', () => {
+    const missing = getMissingToolUsages({
+      integrationName: 'jira',
+      importMetaUrl: import.meta.url,
+      credentialVariant: 'api_token',
+    })
+    expect(missing, `Missing handler usages in tests: ${missing.join(', ')}`).toEqual([])
+  })
+})
+