@commandable/integration-data 0.0.6 → 0.1.0

package/integrations/confluence/handlers/get_page_children.js

@@ -0,0 +1,30 @@
+async (input) => {
+  const pageId = encodeURIComponent(String(input.pageId))
+  const params = new URLSearchParams()
+
+  const limit = typeof input.limit === 'number' ? input.limit : undefined
+  if (limit) params.set('limit', String(limit))
+  if (input.cursor) params.set('cursor', String(input.cursor))
+  if (typeof input.sort === 'string' && input.sort) params.set('sort', input.sort)
+
+  const res = await integration.fetch(`/wiki/api/v2/pages/${pageId}/children${params.toString() ? `?${params}` : ''}`)
+  const data = await res.json()
+
+  const results = Array.isArray(data?.results)
+    ? data.results.map((c) => ({
+        id: c.id,
+        type: c.type,
+        status: c.status,
+        title: c.title,
+        parentId: c.parentId,
+        spaceId: c.spaceId,
+        links: c?._links || {},
+      }))
+    : []
+
+  return {
+    results,
+    links: data?._links || {},
+  }
+}
+

package/integrations/confluence/handlers/get_space.js

@@ -0,0 +1,22 @@
+async (input) => {
+  const spaceId = encodeURIComponent(String(input.spaceId))
+  const params = new URLSearchParams()
+  if (input.includePermissions) params.set('include-permissions', 'true')
+
+  const path = `/wiki/api/v2/spaces/${spaceId}${params.toString() ? `?${params}` : ''}`
+  const res = await integration.fetch(path)
+  const data = await res.json()
+
+  return {
+    id: data?.id,
+    key: data?.key,
+    name: data?.name,
+    type: data?.type,
+    status: data?.status,
+    homepageId: data?.homepageId,
+    description: data?.description,
+    links: data?._links || {},
+    raw: data,
+  }
+}
+

package/integrations/confluence/handlers/list_spaces.js

@@ -0,0 +1,39 @@
+async (input) => {
+  const params = new URLSearchParams()
+
+  if (Array.isArray(input.ids))
+    for (const id of input.ids) params.append('ids', String(id))
+  if (Array.isArray(input.keys))
+    for (const key of input.keys) params.append('keys', String(key))
+  if (typeof input.type === 'string' && input.type)
+    params.set('type', input.type)
+  if (typeof input.status === 'string' && input.status)
+    params.set('status', input.status)
+
+  const limit = typeof input.limit === 'number' ? input.limit : undefined
+  if (limit) params.set('limit', String(limit))
+
+  if (input.cursor) params.set('cursor', String(input.cursor))
+
+  const path = `/wiki/api/v2/spaces${params.toString() ? `?${params}` : ''}`
+  const res = await integration.fetch(path)
+  const data = await res.json()
+
+  const results = Array.isArray(data?.results)
+    ? data.results.map((s) => ({
+        id: s.id,
+        key: s.key,
+        name: s.name,
+        type: s.type,
+        status: s.status,
+        homepageId: s.homepageId,
+        webui: s?._links?.webui,
+      }))
+    : []
+
+  return {
+    results,
+    links: data?._links || {},
+  }
+}
+

package/integrations/confluence/handlers/read_page.js

@@ -0,0 +1,49 @@
+async (input) => {
+  const buildWebUrl = (links) => {
+    const base = links?.base
+    const webui = links?.webui
+    if (!webui) return null
+    if (/^https?:\/\//.test(webui)) return webui
+    if (base && /^https?:\/\//.test(base)) {
+      try { return new URL(webui, base).toString() } catch {}
+    }
+    return webui
+  }
+
+  const pageId = encodeURIComponent(String(input.pageId))
+
+  const params = new URLSearchParams()
+  params.set('body-format', 'storage')
+  if (input.includeLabels) params.set('include-labels', 'true')
+  if (input.includeProperties) params.set('include-properties', 'true')
+
+  const res = await integration.fetch(`/wiki/api/v2/pages/${pageId}?${params}`)
+  const data = await res.json()
+
+  const storage = data?.body?.storage
+  const storageValue = typeof storage === 'string'
+    ? storage
+    : (typeof storage?.value === 'string' ? storage.value : '')
+
+  const meta = {
+    id: data?.id,
+    title: data?.title,
+    spaceId: data?.spaceId,
+    parentId: data?.parentId,
+    status: data?.status,
+    version: data?.version?.number,
+    createdAt: data?.createdAt,
+    webUrl: buildWebUrl(data?._links),
+    labels: data?.labels?.results,
+    links: data?._links || {},
+  }
+
+  if (input.outputMarkdown) {
+    const md = storageValue ? (utils.html?.toMarkdown(storageValue) || '') : ''
+    const note = '\n\n---\n_System note: this is a Markdown representation of the page. If you intend to edit it, re-fetch without `outputMarkdown` to get the storage XHTML and avoid accidentally deleting macros or hidden content._'
+    return { ...meta, contentMarkdown: md ? md + note : null }
+  }
+
+  return { ...meta, contentStorage: storageValue || null }
+}
+

package/integrations/confluence/handlers/search_pages.js

@@ -0,0 +1,42 @@
+async (input) => {
+  const limit = typeof input.limit === 'number' ? input.limit : 10
+  const start = typeof input.start === 'number' ? input.start : 0
+
+  const params = new URLSearchParams()
+  params.set('cql', String(input.cql))
+  params.set('limit', String(limit))
+  params.set('start', String(start))
+  params.set('expand', 'content.space,content.version')
+
+  const res = await integration.fetch(`/wiki/rest/api/search?${params}`)
+  const data = await res.json()
+
+  const results = Array.isArray(data?.results)
+    ? data.results
+        .map((r) => {
+          const c = r?.content || {}
+          return {
+            id: c.id,
+            type: c.type,
+            title: c.title,
+            spaceKey: c?.space?.key,
+            version: c?.version?.number,
+            lastModified: c?.version?.when,
+            excerpt: r?.excerpt,
+            webui: c?._links?.webui,
+          }
+        })
+        .filter((x) => x.id)
+    : []
+
+  return {
+    cql: input.cql,
+    start: data?.start ?? start,
+    limit: data?.limit ?? limit,
+    size: data?.size ?? results.length,
+    totalSize: data?.totalSize,
+    results,
+    links: data?._links || {},
+  }
+}
+

package/integrations/confluence/handlers/update_page.js

@@ -0,0 +1,42 @@
+async (input) => {
+  const pageId = encodeURIComponent(String(input.pageId))
+
+  // Fetch current page to get current version and preserve defaults.
+  const currentRes = await integration.fetch(`/wiki/api/v2/pages/${pageId}`)
+  const current = await currentRes.json()
+
+  const currentVersion = Number(current?.version?.number || 0)
+  if (!currentVersion)
+    throw new Error('Unable to determine current Confluence page version.')
+
+  const nextVersion = currentVersion + 1
+  const title = input.title ? String(input.title) : String(current?.title || '')
+  if (!title)
+    throw new Error('Missing page title (current page has no title and no new title was provided).')
+
+  const body = {
+    id: String(current?.id || input.pageId),
+    status: String(current?.status || 'current'),
+    title,
+    body: {
+      representation: 'storage',
+      value: String(input.bodyStorage),
+    },
+    version: {
+      number: nextVersion,
+      message: input.versionMessage ? String(input.versionMessage) : undefined,
+      minorEdit: Boolean(input.minorEdit),
+    },
+  }
+
+  // Remove undefined version message to keep payload clean.
+  if (body.version.message === undefined)
+    delete body.version.message
+
+  const res = await integration.fetch(`/wiki/api/v2/pages/${pageId}`, {
+    method: 'PUT',
+    body,
+  })
+  return await res.json()
+}
+

package/integrations/confluence/manifest.json

@@ -0,0 +1,85 @@
+{
+  "name": "confluence",
+  "version": "0.1.0",
+  "utils": ["html"],
+  "tools": [
+    {
+      "name": "list_spaces",
+      "description": "List Confluence spaces you can access. Use this to discover `spaceId`/`spaceKey` before searching or creating pages. Pagination uses `cursor` from the previous response.",
+      "inputSchema": "schemas/list_spaces.json",
+      "handler": "handlers/list_spaces.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_space",
+      "description": "Get a Confluence space by `spaceId`, including its homepage and basic metadata.",
+      "inputSchema": "schemas/get_space.json",
+      "handler": "handlers/get_space.js",
+      "scope": "read"
+    },
+    {
+      "name": "search_pages",
+      "description": "Search for pages using CQL (Confluence Query Language). Use this as the primary discovery tool to find page IDs. Example CQL: `space = \"ENG\" AND type = page AND text ~ \"onboarding\" ORDER BY lastmodified DESC`.",
+      "inputSchema": "schemas/search_pages.json",
+      "handler": "handlers/search_pages.js",
+      "scope": "read"
+    },
+    {
+      "name": "read_page",
+      "description": "Read a page and return its content in Confluence storage format (XHTML). Set `outputMarkdown: true` to get Markdown instead — useful for quick reading or summarisation but lossy, do not use it if you plan to edit the page.",
+      "inputSchema": "schemas/read_page.json",
+      "handler": "handlers/read_page.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_page_children",
+      "description": "List child content under a page (typically child pages). Use this to navigate page hierarchies and build a table-of-contents workflow.",
+      "inputSchema": "schemas/get_page_children.json",
+      "handler": "handlers/get_page_children.js",
+      "scope": "read"
+    },
+    {
+      "name": "get_comments",
+      "description": "List footer comments for a page, optionally including their child replies. Use this to review discussion threads on a page.",
+      "inputSchema": "schemas/get_comments.json",
+      "handler": "handlers/get_comments.js",
+      "scope": "read"
+    },
+    {
+      "name": "create_page",
+      "description": "Create a new Confluence page. Provide the body as Confluence storage format (XHTML). For simple pages you can use basic HTML like `<h1>`, `<p>`, `<ul>`, `<li>`, `<code>`, and links.",
+      "inputSchema": "schemas/create_page.json",
+      "handler": "handlers/create_page.js",
+      "scope": "write"
+    },
+    {
+      "name": "update_page",
+      "description": "Update an existing Confluence page. This tool auto-fetches the current version number and increments it, so you don't need to manage versioning. Provide the body as Confluence storage format (XHTML).",
+      "inputSchema": "schemas/update_page.json",
+      "handler": "handlers/update_page.js",
+      "scope": "write"
+    },
+    {
+      "name": "delete_page",
+      "description": "Delete a Confluence page (moves it to trash by default). Use carefully.",
+      "inputSchema": "schemas/delete_page.json",
+      "handler": "handlers/delete_page.js",
+      "scope": "write"
+    },
+    {
+      "name": "add_comment",
+      "description": "Add a footer comment to a Confluence page. Provide the body as Confluence storage format (XHTML). Optionally set `parentCommentId` to create a threaded reply.",
+      "inputSchema": "schemas/add_comment.json",
+      "handler": "handlers/add_comment.js",
+      "scope": "write"
+    },
+    {
+      "name": "add_label",
+      "description": "Add one or more labels to a Confluence page. Labels are useful for discovery via CQL (`label = \"...\"`).",
+      "inputSchema": "schemas/add_label.json",
+      "handler": "handlers/add_label.js",
+      "scope": "write"
+    }
+  ]
+}
+

package/integrations/confluence/prompt.md

@@ -0,0 +1,55 @@
+# Confluence usage guide
+
+## Recommended workflow
+
+1. Use `list_spaces` (or `search_pages`) to discover where content lives.
+2. Use `search_pages` with CQL to find the right page ID(s).
+3. Use `read_page` to get the page content as Confluence storage format (XHTML).
+4. For edits, use `update_page` with storage XHTML in `bodyStorage` (it automatically handles version increments).
+
+## Content format
+
+All content is exchanged in **Confluence storage format (XHTML)**. This applies to both reads (`contentStorage` field in `read_page`) and writes (`bodyStorage` field in `create_page`, `update_page`, `add_comment`).
+
+Common markup:
+
+- Headings: `<h1>Title</h1>`, `<h2>Section</h2>`
+- Paragraphs: `<p>Text</p>`
+- Lists: `<ul><li>Item</li></ul>`, `<ol><li>Item</li></ol>`
+- Inline code: `<code>const x = 1</code>`
+- Code blocks: `<pre><code>...</code></pre>`
+- Links: `<a href="https://example.com">Example</a>`
+- Tables: `<table><tr><th>A</th></tr><tr><td>1</td></tr></table>`
+- Macros: `<ac:structured-macro ac:name="info"><ac:rich-text-body><p>Note</p></ac:rich-text-body></ac:structured-macro>`
+
+Using XHTML natively means round-tripping pages preserves all formatting, macros, and Confluence-specific markup.
+
+`read_page` accepts `outputMarkdown: true` to return content as Markdown instead of XHTML. 
+
+## CQL (Confluence Query Language) quick reference
+
+Common patterns for `search_pages.cql`:
+
+- Restrict to a space:
+  - `space = "ENG" AND type = page`
+- Title match:
+  - `title ~ "runbook" AND type = page`
+- Full-text match:
+  - `text ~ "oncall" AND type = page`
+- Label match:
+  - `label = "runbook" AND type = page`
+- Combine filters:
+  - `space = "ENG" AND type = page AND (title ~ "onboarding" OR text ~ "onboarding")`
+- Sort:
+  - `... ORDER BY lastmodified DESC`
+
+Tips:
+- Prefer small `limit` (e.g. 10) and paginate with `start`.
+- Use labels as a stable way to group pages for later discovery.
+
+## Page hierarchy
+
+- Spaces contain pages.
+- Pages can be nested under a parent page (`parentId`).
+- Use `get_page_children` to traverse a documentation tree (e.g. a handbook or runbook index).
+

package/integrations/confluence/schemas/add_comment.json

@@ -0,0 +1,22 @@
+{
+  "type": "object",
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "title": "Page ID",
+      "description": "The Confluence page ID to comment on."
+    },
+    "bodyStorage": {
+      "type": "string",
+      "title": "Comment body (storage XHTML)",
+      "description": "Confluence storage format (XHTML) comment body."
+    },
+    "parentCommentId": {
+      "type": ["string", "null"],
+      "description": "Optional parent footer comment ID to create a threaded reply."
+    }
+  },
+  "required": ["pageId", "bodyStorage"],
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/add_label.json

@@ -0,0 +1,19 @@
+{
+  "type": "object",
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "title": "Page ID",
+      "description": "The Confluence page ID."
+    },
+    "labels": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Labels to add (without the `global:` prefix). Example: `design-doc`, `runbook`."
+    }
+  },
+  "required": ["pageId", "labels"],
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/create_page.json

@@ -0,0 +1,33 @@
+{
+  "type": "object",
+  "properties": {
+    "spaceId": {
+      "type": "string",
+      "title": "Space ID",
+      "description": "The space ID where the page will be created."
+    },
+    "title": {
+      "type": "string",
+      "title": "Title",
+      "description": "Page title."
+    },
+    "bodyStorage": {
+      "type": "string",
+      "title": "Body (storage XHTML)",
+      "description": "Confluence storage format (XHTML) body value."
+    },
+    "parentId": {
+      "type": ["string", "null"],
+      "description": "Optional parent page ID to create this page under."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["current", "draft"],
+      "default": "current",
+      "description": "Create as published (current) or as a draft."
+    }
+  },
+  "required": ["spaceId", "title", "bodyStorage"],
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/delete_page.json

@@ -0,0 +1,23 @@
+{
+  "type": "object",
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "title": "Page ID",
+      "description": "The Confluence page ID."
+    },
+    "purge": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, permanently purge the page (only works for trashed pages with admin permission)."
+    },
+    "draft": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, delete a draft page."
+    }
+  },
+  "required": ["pageId"],
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/empty.json

@@ -0,0 +1,6 @@
+{
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/get_comments.json

@@ -0,0 +1,24 @@
+{
+  "type": "object",
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "title": "Page ID",
+      "description": "The Confluence page ID."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 250,
+      "default": 50,
+      "description": "Maximum number of comments to return."
+    },
+    "cursor": {
+      "type": ["string", "null"],
+      "description": "Pagination cursor from a previous response."
+    }
+  },
+  "required": ["pageId"],
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/get_page_children.json

@@ -0,0 +1,28 @@
+{
+  "type": "object",
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "title": "Page ID",
+      "description": "The Confluence page ID."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 250,
+      "default": 50,
+      "description": "Maximum number of children to return."
+    },
+    "cursor": {
+      "type": ["string", "null"],
+      "description": "Pagination cursor from a previous response."
+    },
+    "sort": {
+      "type": "string",
+      "description": "Optional sort key (API-specific)."
+    }
+  },
+  "required": ["pageId"],
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/get_space.json

@@ -0,0 +1,18 @@
+{
+  "type": "object",
+  "properties": {
+    "spaceId": {
+      "type": "string",
+      "title": "Space ID",
+      "description": "The Confluence space ID."
+    },
+    "includePermissions": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, include permissions in the response (may be verbose)."
+    }
+  },
+  "required": ["spaceId"],
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/list_spaces.json

@@ -0,0 +1,36 @@
+{
+  "type": "object",
+  "properties": {
+    "ids": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional list of space IDs to filter by."
+    },
+    "keys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional list of space keys to filter by."
+    },
+    "type": {
+      "type": "string",
+      "description": "Optional space type filter (e.g. global, personal)."
+    },
+    "status": {
+      "type": "string",
+      "description": "Optional space status filter (e.g. current, archived)."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 250,
+      "default": 50,
+      "description": "Maximum number of spaces to return."
+    },
+    "cursor": {
+      "type": ["string", "null"],
+      "description": "Pagination cursor from a previous response."
+    }
+  },
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/read_page.json

@@ -0,0 +1,28 @@
+{
+  "type": "object",
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "title": "Page ID",
+      "description": "The Confluence page ID."
+    },
+    "includeLabels": {
+      "type": "boolean",
+      "default": true,
+      "description": "Include labels in the response."
+    },
+    "includeProperties": {
+      "type": "boolean",
+      "default": false,
+      "description": "Include content properties (may be verbose)."
+    },
+    "outputMarkdown": {
+      "type": "boolean",
+      "default": false,
+      "description": "Return content as Markdown instead of Confluence storage XHTML. Useful for quick reading or summarisation. Lossy — macros and rich formatting are stripped. Do not use this format if you intend to edit the page."
+    }
+  },
+  "required": ["pageId"],
+  "additionalProperties": false
+}
+

package/integrations/confluence/schemas/search_pages.json

@@ -0,0 +1,26 @@
+{
+  "type": "object",
+  "properties": {
+    "cql": {
+      "type": "string",
+      "title": "CQL",
+      "description": "Confluence Query Language string. Example: `space = \"ENG\" AND type = page AND text ~ \"onboarding\" ORDER BY lastmodified DESC`."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 50,
+      "default": 10,
+      "description": "Maximum results to return."
+    },
+    "start": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Offset into results for pagination (v1 search)."
+    }
+  },
+  "required": ["cql"],
+  "additionalProperties": false
+}
+