@formfactory-dev/toolkit

Shared API primitives used by @formfactory-dev/cli and @formfactory-dev/workflows. Lives separately so each consumer can depend on just the surface it needs, and so both stay focused on their own concerns (terminal UX vs. workflow runtime).

Most users get this transitively via cli or workflows. Install directly only if you're writing custom workflow code that wants these primitives without the agent/sandbox runtime:

pnpm add @formfactory-dev/toolkit
# or:
# npm install @formfactory-dev/toolkit
# bun add @formfactory-dev/toolkit
# yarn add @formfactory-dev/toolkit

Surface

@formfactory-dev/toolkit/atlassian/jira

import { fetchJiraTicket, type JiraTicket } from "@formfactory-dev/toolkit/atlassian/jira"

// Use the operator's current acli site:
const ticket = await fetchJiraTicket("ENG-17")

// Or pin a site explicitly (required for multi-site operators):
const sameTicket = await fetchJiraTicket("ENG-17", { site: "formfactory" })
// → { key, summary, descriptionMarkdown, issueType?, status?, assigneeDisplayName? }

Shells out to acli jira workitem view <key> --json. The ADF description is flattened to Markdown. When options.site is provided, the function runs acli jira auth switch --site <site>.atlassian.net before the fetch and serializes concurrent calls so different-site invocations can't interleave. Without site, the operator's current acli auth state is used as-is.

@formfactory-dev/toolkit/atlassian/confluence

import {
  fetchConfluencePage,
  ConfluenceFetchError,
  type ConfluencePage,
} from "@formfactory-dev/toolkit/atlassian/confluence"

const page = await fetchConfluencePage({
  url: "https://acme.atlassian.net/wiki/spaces/DEV/pages/123456",
  credentials: { email: "[email protected]", apiToken: "..." },
})
// → { id, title, spaceKey, version, markdown, url }

Hits the Confluence Cloud REST API v1 with Basic auth (acli doesn't expose Confluence content fetching). Returns structured data; callers handle rendering and error reporting. HTTP errors throw ConfluenceFetchError with the status code so callers can tailor responses (401 vs 403 vs 404).

@formfactory-dev/toolkit/atlassian/confluence-url

import { parseConfluenceUrl } from "@formfactory-dev/toolkit/atlassian/confluence-url"

const { host, pageId } = parseConfluenceUrl(url)

@formfactory-dev/toolkit/atlassian/credentials

import type { AtlassianCredentials } from "@formfactory-dev/toolkit/atlassian/credentials"
// { email: string; apiToken: string }

Plain credential type used by fetchConfluencePage (and any future REST callers). Toolkit doesn't resolve credentials from disk — callers pass them in, so the toolkit stays free of settings-tier semantics.

@formfactory-dev/toolkit/atlassian/adf

import { adfToMarkdown } from "@formfactory-dev/toolkit/atlassian/adf"

Atlassian Document Format → Markdown. Handles headings, paragraphs, lists, code blocks, blockquotes, tables, panels, and inline marks (bold/italic/code/strike/underline/link).

Barrels

• @formfactory-dev/toolkit/atlassian re-exports all five modules above.
• @formfactory-dev/toolkit re-exports the entire surface.

License

MIT — see LICENSE.