@formfactory-dev/toolkit

Shared API primitives for @formfactory-dev/cli and @formfactory-dev/workflows. Most users get this transitively. Install directly when writing custom workflow code that wants these primitives without the agent/sandbox runtime:

pnpm add @formfactory-dev/toolkit

Everything is exported from the package root — import { ... } from "@formfactory-dev/toolkit".

Surface

Jira

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

// 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. With options.site, runs acli jira auth switch first and serializes concurrent calls so different-site invocations can't interleave. Without it, uses the operator's current acli auth state as-is.

Confluence

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

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 }

const { host, pageId } = parseConfluenceUrl(url)

Hits the Confluence Cloud REST API v1 with Basic auth (acli doesn't cover Confluence content). HTTP errors throw ConfluenceFetchError with status so callers can tailor on 401 / 403 / 404.

Credentials

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

Plain credential type used by fetchConfluencePage. Callers pass credentials in; toolkit stays free of settings-tier semantics.

ADF

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

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

Publishing

Published via pnpm publish from GitHub Actions using OIDC (the npm scope is configured as a "trusted publisher" tied to this repo and the release workflow — local publishes are rejected). pnpm publish rewrites catalog: and workspace: protocol references in package.json to concrete version ranges before upload, so consumers installing via npm, yarn, pnpm, or bun see normal version strings.

License

MIT — see LICENSE.