Skip to content

Commit c62f515

Browse files
TDanks2000TDanks2000
committed
chore: remove outdated plugin documentation and add new release workflow
- Deleted the old plugin guide from `docs/plugins.md`. - Added a new release workflow in `.github/workflows/release.yml` for npm Trusted Publishing. - Introduced CI workflow in `.github/workflows/ci.yml` to run tests and checks on pull requests and pushes to main. - Configured Dependabot in `.github/dependabot.yml` for weekly updates on GitHub Actions. - Updated `package.json` to include a new CI check script. - Created new documentation files for getting started, built-in plugins, error handling, GraphQL, plugins, REST requests, testing, client API, configuration reference, and exports.
1 parent d9e8ee7 commit c62f515

19 files changed

Lines changed: 1549 additions & 540 deletions

‎.github/RELEASE.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Release Workflow
2+
3+
Releases are published by `.github/workflows/release.yml` when a semver tag is
4+
pushed, for example `v1.2.3`.
5+
6+
## npm Trusted Publishing
7+
8+
The release workflow is designed for npm Trusted Publishing with OIDC. It does
9+
not use `NPM_TOKEN`.
10+
11+
Configure the package on npmjs.com:
12+
13+
1. Open the package settings for `@api-wrappers/api-core`.
14+
2. Add a GitHub Actions trusted publisher.
15+
3. Set the repository owner and repository name.
16+
4. Set the workflow filename to `release.yml`.
17+
5. Set the environment name to `npm`.
18+
6. After a successful trusted publish, set publishing access to require 2FA and
19+
disallow traditional tokens.
20+
21+
The workflow grants `id-token: write`, uses Node.js 24, and verifies the npm CLI
22+
is at least `11.5.1`, matching npm's trusted publishing requirements.
23+
GitHub Actions are pinned to current release tags rather than deprecated major
24+
versions. Dependabot is configured to keep workflow action pins current.
25+
26+
## Release Steps
27+
28+
1. Update `package.json` version.
29+
2. Commit the version change.
30+
3. Create and push a matching tag:
31+
32+
```bash
33+
git tag v1.2.3
34+
git push origin v1.2.3
35+
```
36+
37+
The workflow checks that `package.json` version matches the tag without the
38+
leading `v`, runs lint/tests/build, verifies package contents, publishes to npm,
39+
and creates a GitHub release with generated notes.
40+
41+
## CI Workflow
42+
43+
`.github/workflows/ci.yml` runs on pull requests, pushes to `main`, and manual
44+
dispatch. It runs:
45+
46+
- non-mutating Biome check
47+
- Bun test suite
48+
- package build
49+
- ESM and CommonJS smoke tests
50+
- npm package dry-run
51+
- dependency review on pull requests
52+
53+
Pushes to `main` also upload a short-lived `.tgz` package artifact for manual
54+
inspection.

‎.github/dependabot.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
version: 2
2+
3+
updates:
4+
- package-ecosystem: "github-actions"
5+
directory: "/"
6+
schedule:
7+
interval: "weekly"
8+
day: "monday"
9+
time: "08:00"
10+
timezone: "UTC"
11+
groups:
12+
github-actions:
13+
patterns:
14+
- "*"

‎.github/workflows/ci.yml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
push:
8+
branches:
9+
- main
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
15+
concurrency:
16+
group: ci-${{ github.workflow }}-${{ github.ref }}
17+
cancel-in-progress: true
18+
19+
jobs:
20+
test:
21+
name: Check, test, build, and pack
22+
runs-on: ubuntu-latest
23+
timeout-minutes: 15
24+
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v6.0.0
28+
29+
- name: Setup Bun
30+
uses: oven-sh/setup-bun@v2.0.2
31+
with:
32+
bun-version: latest
33+
34+
- name: Setup Node.js
35+
uses: actions/setup-node@v6.3.0
36+
with:
37+
node-version: 24
38+
package-manager-cache: false
39+
40+
- name: Install dependencies
41+
run: bun install --frozen-lockfile
42+
43+
- name: Check formatting and lint
44+
run: bun run check:ci
45+
46+
- name: Run tests
47+
run: bun test
48+
49+
- name: Build package
50+
run: bun run build
51+
52+
- name: Smoke test built entrypoints
53+
run: |
54+
node --input-type=module -e "const m = await import('./dist/index.mjs'); if (typeof m.createClient !== 'function') throw new Error('missing ESM createClient')"
55+
node -e "const m = require('./dist/index.cjs'); if (typeof m.createClient !== 'function') throw new Error('missing CJS createClient')"
56+
57+
- name: Verify package contents
58+
run: npm pack --dry-run --json
59+
60+
- name: Pack artifact
61+
if: github.event_name != 'pull_request'
62+
run: npm pack --json
63+
64+
- name: Upload package artifact
65+
if: github.event_name != 'pull_request'
66+
uses: actions/upload-artifact@v7.0.1
67+
with:
68+
name: npm-package
69+
path: "*.tgz"
70+
if-no-files-found: error
71+
retention-days: 7
72+
73+
dependency-review:
74+
name: Dependency review
75+
runs-on: ubuntu-latest
76+
timeout-minutes: 5
77+
if: github.event_name == 'pull_request'
78+
permissions:
79+
contents: read
80+
pull-requests: read
81+
82+
steps:
83+
- name: Checkout
84+
uses: actions/checkout@v6.0.0
85+
86+
- name: Review dependency changes
87+
uses: actions/dependency-review-action@v4.9.0

‎.github/workflows/release.yml‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*.*.*"
7+
workflow_dispatch:
8+
inputs:
9+
tag:
10+
description: "Existing semver tag to release, for example v1.2.3"
11+
required: true
12+
type: string
13+
14+
permissions:
15+
contents: read
16+
17+
concurrency:
18+
group: release-${{ github.ref_name }}
19+
cancel-in-progress: false
20+
21+
jobs:
22+
publish:
23+
name: Publish to npm and create GitHub release
24+
runs-on: ubuntu-latest
25+
timeout-minutes: 20
26+
environment: npm
27+
permissions:
28+
contents: write
29+
id-token: write
30+
31+
steps:
32+
- name: Checkout tag
33+
uses: actions/checkout@v6.0.0
34+
with:
35+
ref: ${{ github.event.inputs.tag || github.ref }}
36+
fetch-depth: 0
37+
38+
- name: Setup Bun
39+
uses: oven-sh/setup-bun@v2.0.2
40+
with:
41+
bun-version: latest
42+
43+
- name: Setup Node.js for npm trusted publishing
44+
uses: actions/setup-node@v6.3.0
45+
with:
46+
node-version: 24
47+
registry-url: "https://registry.npmjs.org"
48+
package-manager-cache: false
49+
50+
- name: Verify npm trusted publishing requirements
51+
run: |
52+
node --version
53+
npm --version
54+
node -e "const [major, minor] = process.versions.node.split('.').map(Number); if (major < 22 || (major === 22 && minor < 14)) throw new Error('npm trusted publishing requires Node 22.14.0 or newer')"
55+
npm --version | node -e "let v=''; process.stdin.on('data', d => v += d); process.stdin.on('end', () => { const [major, minor, patch] = v.trim().split('.').map(Number); if (major < 11 || (major === 11 && (minor < 5 || (minor === 5 && patch < 1)))) throw new Error('npm trusted publishing requires npm 11.5.1 or newer'); })"
56+
57+
- name: Install dependencies
58+
run: bun install --frozen-lockfile
59+
60+
- name: Check formatting and lint
61+
run: bun run check:ci
62+
63+
- name: Run tests
64+
run: bun test
65+
66+
- name: Build package
67+
run: bun run build
68+
69+
- name: Verify tag matches package version
70+
run: |
71+
TAG="${GITHUB_REF_NAME}"
72+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
73+
TAG="${{ github.event.inputs.tag }}"
74+
fi
75+
VERSION="$(node -p "require('./package.json').version")"
76+
if [ "${TAG#v}" != "$VERSION" ]; then
77+
echo "Tag $TAG does not match package.json version $VERSION" >&2
78+
exit 1
79+
fi
80+
81+
- name: Verify package contents
82+
run: npm pack --dry-run --json
83+
84+
- name: Publish to npm
85+
run: npm publish --access public
86+
87+
- name: Create GitHub release
88+
env:
89+
GH_TOKEN: ${{ github.token }}
90+
run: |
91+
TAG="${GITHUB_REF_NAME}"
92+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
93+
TAG="${{ github.event.inputs.tag }}"
94+
fi
95+
if gh release view "$TAG" >/dev/null 2>&1; then
96+
echo "GitHub release $TAG already exists"
97+
else
98+
gh release create "$TAG" --verify-tag --generate-notes
99+
fi

0 commit comments

Comments
 (0)