Skip to content

docs: add v7 migration guide (v6 → v7) - #1396

Open
tusharpandey13 wants to merge 8 commits into
masterfrom
docs/v7-migration-guide
Open

docs: add v7 migration guide (v6 → v7)#1396
tusharpandey13 wants to merge 8 commits into
masterfrom
docs/v7-migration-guide

Conversation

@tusharpandey13

@tusharpandey13 tusharpandey13 commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds v7_MIGRATION_GUIDE.md, the release-level upgrade guide for 6.x7.x, following the conventions of the existing v5/v6 guides. Kept separate from the Authentication API deep-dive guide (#1395), which it references rather than duplicates.

v7 makes node-auth0 a Management-API-only SDK. This guide is the umbrella that covers the full breaking surface of that release:

  • Authentication API removed from the main entrypoint — points to AUTH_MIGRATION_GUIDE.md for the method-by-method rewrite.
  • Removed-exports tableAuthenticationClient, UserInfoClient, AuthApiError, AuthenticationClientOptions, IDTokenValidateOptions, IdTokenValidatorError, TokenSet, SUBJECT_TOKEN_TYPES, UserInfoResponse, UserInfoError, each mapped to its v7 replacement.
  • Management-side breaking changes not in scope of the auth guide: mTLS requires an explicit fetch; mTLS + client-assertion mutually exclusive; bare-hostname domain validation; token-acquisition failures throw ManagementError; uuid dependency removed.
  • Legacy entrypoint documented as a stopgap.

Also links the new guide from the README documentation list.

Why a separate guide (not a rename of AUTH_MIGRATION_GUIDE)

AUTH_MIGRATION_GUIDE.md (#1395) is a topic guide for the auth-layer rewrite and explicitly scopes out the Management API. v7 is a superset: it also covers the Management-side breaks and the export-surface removals, matching how the v6 guide is the release umbrella. Renaming the auth guide would silently drop two-thirds of the v7 breaking surface.

Related PRs

🤖 Generated with Claude Code

@tusharpandey13
tusharpandey13 requested a review from a team as a code owner August 27, 2026 08:22
@tusharpandey13
tusharpandey13 changed the base branch from feat/auth-separation-v6 to master August 27, 2026 11:19
Add v7_MIGRATION_GUIDE.md covering the 6.x to 7.x upgrade: Authentication
API removed from the main entrypoint, the removed-exports table, and the
Management-side breaking changes (mTLS explicit fetch, mTLS/client-assertion
mutual exclusion, bare-hostname domain validation, ManagementError on token
acquisition failures, uuid dependency removed).

Delegates the auth-layer rewrite detail to AUTH_MIGRATION_GUIDE.md rather
than duplicating it, and links the legacy entrypoint as a stopgap.

Link the new guide from the README documentation list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tusharpandey13
tusharpandey13 force-pushed the docs/v7-migration-guide branch from 6a628b2 to dd07f02 Compare August 27, 2026 12:18
@codecov

codecov Bot commented Aug 27, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.83%. Comparing base (4d450aa) to head (fb687db).

Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##           master    #1396   +/-   ##
=======================================
  Coverage   89.83%   89.83%           
=======================================
  Files         446      446           
  Lines       21371    21371           
  Branches     9999     9999           
=======================================
  Hits        19198    19198           
  Misses       2173     2173           
Flag Coverage Δ
alltests 89.83% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@tusharpandey13

Copy link
Copy Markdown
Contributor Author

The "Removed exports" table covers the auth-layer removals but is missing three low-level HTTP wrapper types that PR #1397 also removes from the public entrypoint:

Removed export (v6) Replacement in v7
ResponseError Management API calls throw ManagementError
FetchError Management API calls throw ManagementError
JSONApiResponse Responses return the data directly (no wrapper)

Suggest adding these rows so the guide is a complete upgrade checklist. Context: they are deleted in #1397 (src/lib/errors.ts, src/lib/models.ts), and are now documented in the README error-handling section on that branch.

tusharpandey13 and others added 4 commits September 6, 2026 18:01
- Add an agent-skill callout pointing to the auth0 migrate-node-auth0 skill.
- Point the authentication-migration section at the guide's P0 OIDC start and
  its migration/ directory.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The auth migration guide moved from AUTH_MIGRATION_GUIDE.md into the scoped
auth-migration/ directory (root file is now a stub). Update the references to
the directory and its index.md landing page.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Drop internal implementation notes from the AI-agent skill callout
- Remove all em dashes
- Replace the orphaned P0 section reference with a named link

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tusharpandey13 and others added 3 commits September 7, 2026 13:56
Short README section points to the v7 Migration Guide for method
mapping, error-handling changes, and mTLS notes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The README v6-to-v7 section ships in the auth-separation code PR, which
is the canonical owner. Keeping a competing section here caused an
add/add conflict at the same anchor. The v7 guide stays linked from the
Documentation list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…PR merge conflict

Matches the Documentation-list block in the auth-migration PR so the two
PRs make an identical insertion and merge cleanly in either order.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant