v6.0.0

.changeset/README.md

@@ -0,0 +1,26 @@
+# Changesets
+
+This directory is used by [@changesets/cli](https://github.com/changesets/changesets) to manage versioning and changelog entries for jira.js.
+
+## Workflow
+
+1. **Make changes** — implement your feature or fix
+2. **Add a changeset** — `pnpm changeset` (interactive prompt)
+3. **Commit** — include the generated `.md` file in your commit
+4. **Release** — maintainers run `pnpm changeset version` to bump versions, then publish
+
+## Changeset types
+
+| Type | When |
+|------|------|
+| `major` | Breaking changes (see `SEMVER_POLICY.md`) |
+| `minor` | Additive changes (new endpoints, new exports) |
+| `patch` | Bug fixes, internal improvements, declaration fixes |
+
+## Rules
+
+- Every PR that affects public API **must** include a changeset
+- PRs that only affect tests, docs, or CI may omit a changeset
+- Breaking changes require a `major` changeset with migration guidance
+- See `SEMVER_POLICY.md` for exact classification rules
+- See `DEPRECATION_POLICY.md` for the deprecation lifecycle

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "master",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/shaky-dragons-scream.md

@@ -0,0 +1,8 @@
+---
+'@jira.js/servicedesk': patch
+'@jira.js/agile': patch
+'@jira.js/cloud': patch
+'@jira.js/base': patch
+---
+
+Initial release

.env.example

@@ -1,3 +1,15 @@
-HOST=
-EMAIL=
-API_TOKEN=
+# Basic Auth — required for all live tests
+JIRA_BASE_URL=https://your-domain.atlassian.net
+JIRA_EMAIL=you@example.com
+JIRA_API_TOKEN=your-api-token
+
+# Optional — reuse an existing project instead of creating one per run
+JIRA_TEST_PROJECT_KEY=
+
+# OAuth 2.0 — required for Feature Flags, Builds, Deployments, Dev Info live tests
+# Run `pnpm tsx scripts/oauth-setup.ts` to obtain tokens
+JIRA_OAUTH_CLIENT_ID=
+JIRA_OAUTH_CLIENT_SECRET=
+JIRA_CLOUD_ID=
+JIRA_OAUTH_TOKEN=
+JIRA_OAUTH_REFRESH_TOKEN=

.github/workflows/changeset-check.yml

@@ -0,0 +1,65 @@
+name: 📦 Changeset Check
+
+on:
+  pull_request:
+    branches:
+      - master
+      - develop
+
+jobs:
+  changeset-check:
+    name: 📦 Changeset Required
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: 🔄 Checkout sources
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: ⚙️ Use Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+
+      - name: 📦 Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: 📌 Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: 📦 Check for changeset
+        run: |
+          # Get list of changed files in this PR vs base branch
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
+          echo "Changed files:"
+          echo "$CHANGED"
+
+          # Check if any package source files changed
+          SRC_CHANGED=$(echo "$CHANGED" | grep -E '^packages/[^/]+/src/' || true)
+
+          if [ -z "$SRC_CHANGED" ]; then
+            echo "✅ No package source files changed — changeset not required"
+            exit 0
+          fi
+
+          echo "Source files changed:"
+          echo "$SRC_CHANGED"
+
+          # Check if any .md changeset files exist (excluding README.md)
+          CHANGESETS=$(ls .changeset/*.md 2>/dev/null | grep -v README.md || true)
+
+          if [ -z "$CHANGESETS" ]; then
+            echo ""
+            echo "❌ Package source files changed but no changeset found."
+            echo ""
+            echo "   Run: pnpm changeset"
+            echo "   This creates a changeset file describing the impact of your changes."
+            echo "   See .changeset/README.md and SEMVER_POLICY.md for guidance."
+            echo ""
+            exit 1
+          fi
+
+          echo "✅ Changeset found:"
+          echo "$CHANGESETS"

.github/workflows/ci.yaml

@@ -3,9 +3,9 @@ name: 🛠️ CI
 on:
   push:
     branches:
-      - '**'  # Runs on all branch pushes
+      - '**'
     tags-ignore:
-      - '**'  # Ignore all tag pushes
+      - '**'
   repository_dispatch:
     types: [ pr-approved ]
 
@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20.x, 22.x]
+        node-version: [22.x, 24.x]
     steps:
       - name: 🔄 Checkout sources
         uses: actions/checkout@v4
@@ -36,7 +36,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20.x, 22.x]
+        node-version: [22.x, 24.x]
     steps:
       - name: 🔄 Checkout sources
         uses: actions/checkout@v4
@@ -53,13 +53,13 @@ jobs:
         env:
           CI: true
 
-  test_unit:
+  test:
     name: 🧪 Unit Tests
     needs: build
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20.x, 22.x]
+        node-version: [22.x, 24.x]
     steps:
       - name: 🔄 Checkout sources
         uses: actions/checkout@v4
@@ -69,37 +69,65 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: 📦 Install pnpm
         uses: pnpm/action-setup@v4
-      - name: 📌 Installing dependencies
+      - name: 📌 Install dependencies
         run: pnpm install --frozen-lockfile
-      - name: 🚀 Running unit tests
-        run: pnpm run test:unit
+      - name: 🏗️ Build packages
+        run: pnpm run build
+      - name: 🧪 Unit tests — @jira.js/base
+        run: pnpm --filter @jira.js/base test:unit
+      - name: 🧪 Unit tests — @jira.js/cloud
+        run: pnpm --filter @jira.js/cloud test:unit
 
-  test_integration:
-    name: 🧩 Integration Tests
-    needs:
-      - lint
-      - test_unit
+  governance:
+    name: 🔏 API Governance
+    needs: build
     runs-on: ubuntu-latest
-    strategy:
-      max-parallel: 1
-      matrix:
-        node-version: [20.x, 22.x]
+    permissions:
+      contents: read
     steps:
       - name: 🔄 Checkout sources
         uses: actions/checkout@v4
-      - name: ⚙️ Use Node.js ${{ matrix.node-version }}
+      - name: ⚙️ Use Node.js 22.x
         uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 22.x
       - name: 📦 Install pnpm
         uses: pnpm/action-setup@v4
-      - name: 📌 Installing dependencies
+      - name: 📌 Install dependencies
         run: pnpm install --frozen-lockfile
-      - name: 📝 Creating `.env` file
-        run: |
-          touch .env
-          echo HOST=${{ secrets.HOST }} >> .env
-          echo EMAIL=${{ secrets.EMAIL }} >> .env
-          echo API_TOKEN=${{ secrets.API_TOKEN }} >> .env
-      - name: 🚀 Running integration tests
-        run: pnpm run test:integration
+      - name: 🏗️ Build packages
+        run: pnpm run build
+      - name: 📋 Validate package exports map
+        run: node scripts/check-exports.mjs
+      - name: 🔍 Check API surface snapshots
+        run: node scripts/api-surface.mjs check
+
+  release-cert:
+    name: 🎓 Release Certification
+    needs: [build, governance]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: 🔄 Checkout sources
+        uses: actions/checkout@v4
+      - name: ⚙️ Use Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+      - name: 📦 Install pnpm
+        uses: pnpm/action-setup@v4
+      - name: 📌 Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: 🏗️ Build packages
+        run: pnpm run build
+      - name: 🗜️ Validate packed tarballs
+        run: node scripts/pack-validate.mjs
+      - name: 🔬 Type resolution check (ATTW)
+        run: node scripts/attw-check.mjs
+      - name: 📏 Install size governance
+        run: node scripts/size-check.mjs
+      - name: 🧪 Consumer smoke tests
+        run: node scripts/smoke-consumers.mjs
+        env:
+          npm_config_prefer_offline: 'false'

.github/workflows/docs.yml

@@ -0,0 +1,95 @@
+name: 📚 Docs
+
+on:
+  push:
+    branches: [master, develop]
+    paths:
+      - 'docs/**'
+      - 'packages/*/src/**'
+      - 'typedoc.json'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [master, develop]
+    paths:
+      - 'docs/**'
+      - 'packages/*/src/**'
+      - 'typedoc.json'
+  workflow_dispatch:
+
+jobs:
+  docs-build:
+    name: 🏗️ Build docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: 🔄 Checkout
+        uses: actions/checkout@v4
+
+      - name: ⚙️ Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+
+      - name: 📦 Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: 📌 Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: 🏗️ Build packages (for TypeDoc)
+        run: pnpm run build
+
+      - name: 📖 Generate API reference
+        run: pnpm docs:api
+
+      - name: 🏗️ Build VitePress site
+        run: pnpm docs:build
+
+  docs-deploy:
+    name: 🚀 Deploy to GitHub Pages
+    needs: docs-build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: 🔄 Checkout
+        uses: actions/checkout@v4
+
+      - name: ⚙️ Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+
+      - name: 📦 Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: 📌 Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: 🏗️ Build packages
+        run: pnpm run build
+
+      - name: 📖 Generate API reference
+        run: pnpm docs:api
+
+      - name: 🏗️ Build docs site
+        run: pnpm docs:build
+
+      - name: ⚙️ Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: 📤 Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+      - name: 🚀 Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish-dev.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch
 
 env:
-  NODE_VERSION: '20.x'
+  NODE_VERSION: '22.x'
 
 permissions:
   contents: read