Validate and update links (STF-557)

.github/workflows/links.yml

@@ -0,0 +1,32 @@
+name: Links
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 13 * * 1" # weekly, to catch external link rot without a commit
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup mise
+        uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8 # v3.6.1
+        with:
+          install: false
+
+      # Install only lychee (not the repo's full toolchain) and run the check.
+      - name: Check links
+        env:
+          MISE_AUTO_INSTALL: "false"
+        run: |
+          mise install lychee
+          mise run check-links

.gitignore

@@ -1,5 +1,6 @@
 dist
 docs
+.lycheecache
 
 # Logs
 logs

README.dev.md

@@ -15,7 +15,7 @@
    - Commit changes and push
    - Create a GitHub release (which triggers the npm publish workflow)
 6. Merge the release PR after the workflow succeeds.
-7. Verify the release on [npm](https://npmjs.com/package/@maxmind/minfraud-api-node).
+7. Verify the release on [npm](https://www.npmjs.com/package/@maxmind/minfraud-api-node).
 
 Note: Publishing is done via GitHub Actions using npm Trusted Publishing
 (OIDC). Manual `npm publish` is not supported.

README.md

@@ -132,7 +132,7 @@ Thrown by the request and transaction models:
 * `ArgumentError` - Thrown when invalid data is passed to the Transaction
 and Transaction property constructors.
 
-In addition to the [response errors](https://dev.maxmind.com/minfraud/api-documentation/responses?lang=en#errors)
+In addition to the [response errors](https://dev.maxmind.com/minfraud/api-documentation/responses/?lang=en#errors)
 returned by the web API, we also return:
 
 ```js
@@ -286,7 +286,7 @@ Please report all issues with this code using the
 
 If you are having an issue with the minFraud service that is not specific
 to the client API, please see
-[our support page](https://www.maxmind.com/en/support).
+[our support page](https://support.maxmind.com/knowledge-base).
 
 ## Contributing
 

lychee.toml

@@ -0,0 +1,70 @@
+# Lychee link checker configuration
+# https://lychee.cli.rs/#/usage/config
+#
+# Run locally with:
+#   lychee './**/*.md' './src/**/*.ts' './package.json'
+
+# Include URL fragments in checks
+include_fragments = true
+
+# Don't allow any redirects, so links that have moved are surfaced and updated
+# to their canonical destination.
+max_redirects = 0
+
+# Accept these HTTP status codes
+# 100-103: Informational responses
+# 200-299: Success responses
+# 403: Forbidden (some sites use this for rate limiting)
+# 429: Too Many Requests
+# 500-599: Server errors (temporary issues shouldn't fail CI)
+# 999: LinkedIn's custom status code
+accept = ["100..=103", "200..=299", "403", "429", "500..=599", "999"]
+
+# Exclude URL patterns from checking (treated as regular expressions)
+exclude = [
+    '^file://',
+    # Live / auth-gated endpoints that appear as string literals or require login
+    '^https://geoip\.maxmind\.com',
+    '^https://geolite\.info',
+    '^https://minfraud\.maxmind\.com',
+    '^https://sandbox\.maxmind\.com',
+    '^https://updates\.maxmind\.com',
+    '^https://www\.maxmind\.com/en/accounts/',
+    'https://www\.maxmind\.com/en/account/login',
+    # package.json repository.url uses the canonical npm git clone URL
+    # (https://github.com/maxmind/minfraud-api-node.git); the ".git" form 301s to
+    # the web UI but is the correct packaging metadata, so it is not a "link" to
+    # fix.
+    '^https://github\.com/maxmind/minfraud-api-node\.git$',
+    # dev.maxmind.com API docs are client-side rendered, so schema anchors
+    # (#schema--...) are generated in the browser and are not present in the
+    # static HTML lychee fetches. The page itself resolves 200; only the
+    # fragment cannot be verified, so exclude these schema-fragment URLs.
+    '^https://dev\.maxmind\.com/minfraud/api-documentation/responses/#schema--',
+    # Placeholders / example URLs used in tests and docstrings
+    '^https?://example\.(com|org|net)',
+    '^https?://(www\.)?foobar\.com',
+    '^http://google\.com',
+    '^http://localhost',
+    '127\.0\.0\.1',
+]
+
+# Exclude file paths from getting checked (treated as regular expressions)
+exclude_path = [
+    '(^|/)node_modules/',
+    '(^|/)dist/',
+    '(^|/)build/',
+    '(^|/)coverage/',
+    # docs/ contains generated TypeDoc HTML (gitignored)
+    '(^|/)docs/',
+    '(^|/)\.git/',
+    # Changelog: historical entries are preserved as-is, not rewritten
+    '(^|/)CHANGELOG\.md$',
+]
+
+# Cache results for 1 day to speed up repeated checks
+cache = true
+max_cache_age = "1d"
+
+# Skip missing input files instead of erroring
+skip_missing = true

mise.lock

@@ -0,0 +1,29 @@
+# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
+
+[[tools.lychee]]
+version = "0.23.0"
+backend = "aqua:lycheeverse/lychee"
+
+[tools.lychee."platforms.linux-arm64"]
+checksum = "sha256:97eb93b02a7d78a752fc33e5b0983439ccaadbf3db952b68a0a4401acd92e6e0"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.23.0/lychee-aarch64-unknown-linux-gnu.tar.gz"
+
+[tools.lychee."platforms.linux-arm64-musl"]
+checksum = "sha256:97eb93b02a7d78a752fc33e5b0983439ccaadbf3db952b68a0a4401acd92e6e0"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.23.0/lychee-aarch64-unknown-linux-gnu.tar.gz"
+
+[tools.lychee."platforms.linux-x64"]
+checksum = "sha256:5538440d2c69a45a0a09983271e5dee0c2fe7137d8035d25b2632e10a66a090a"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.23.0/lychee-x86_64-unknown-linux-musl.tar.gz"
+
+[tools.lychee."platforms.linux-x64-musl"]
+checksum = "sha256:5538440d2c69a45a0a09983271e5dee0c2fe7137d8035d25b2632e10a66a090a"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.23.0/lychee-x86_64-unknown-linux-musl.tar.gz"
+
+[tools.lychee."platforms.macos-arm64"]
+checksum = "sha256:4c8034900e11083b68ac6f6582c377ff1f704e268991999e09d717973e493e7f"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.23.0/lychee-arm64-macos.dmg"
+
+[tools.lychee."platforms.windows-x64"]
+checksum = "sha256:0fda7ff0a60c0250939fc25361c2d4e6e7853c31c996733fdd5a1dd760bcb824"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.23.0/lychee-x86_64-windows.exe"

mise.toml

@@ -0,0 +1,9 @@
+[settings]
+lockfile = true
+
+[tools]
+lychee = "latest"
+
+[tasks.check-links]
+description = "Check links with lychee"
+run = "lychee --no-progress './**/*.md' './src/**/*.ts' './package.json'"