# @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:

```bash
pnpm add @formfactory-dev/toolkit
```

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

## Surface

### Jira

```ts
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

```ts
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: "you@acme.com", 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

```ts
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

```ts
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`](../../LICENSE).