Description

Fixes #441.

lib/ is internal, but until now the root API used eight types that only a path under lib/ could name. This PR exports them from the package root and documents the boundary in README.md. That is the 5.2.0 step #441 lays out, and it has to ship before #458 closes lib/ with an exports map in v6.

Use case

TypeScript consumers who implement or call node-saml's API have to name these types:

• a helper that builds generateServiceProviderMetadata's parameters needs GenerateServiceProviderMetadataParams;
• a subclass overriding one of SAML's protected methods needs XMLOutput or XmlJsObject;
• code wrapping InMemoryCacheProvider needs CacheProviderOptions.

Today they have to deep-import them. Once #458 lands, that import fails with ERR_PACKAGE_PATH_NOT_EXPORTED, and the types can't be named at all.

What's exported

A walk over the emitted declarations, starting from every root export, found the package's own types that the root API reaches. These eight weren't exported:

CacheProviderOptions wasn't exported even from its own module, so no import path could reach it. The others are re-exported from src/types.ts. As #441 decided, none of the runtime helpers under lib/ (parseDomFromString, xpath, signXml, signSamlPost, getVerifiedXml, and so on) is exported from the root.

Semver

This is a minor change, for 5.2.0. It adds type-only exports, and nothing that compiled before stops compiling. Deep imports still resolve throughout 5.x. README.md is the deprecation for them, as #441 decided: lib/ paths get no @deprecated marking.

Tests

None added. The exports are type-only and change nothing the library accepts, rejects or emits at run time.

The existing "still accepts the injected-dependency argument" test keeps its deep import of XmlJsObject: it models a v5.1 consumer, and v5.1 had no other way to name that type.

Documentation

README.md:

• Create a SAML instance. The list of root types now includes the eight, followed by the boundary. Import from the package root only; everything under lib/ is internal; the next major version closes that path, so deep imports fail with ERR_PACKAGE_PATH_NOT_EXPORTED. The migration is shown in code. The XML helpers under lib/ are named, with the packages to use instead: @xmldom/xmldom, xpath and xml-crypto.
• Low-level exports is replaced by Verifying a signature outside SAML. The old section presented getVerifiedXml(), parseDomFromString() and validateSignature() from lib/xml. It also gave getVerifiedXml() as the migration from validateSignature(), which moves a caller from one lib/ path to another that also closes in v6. The section now says both are internal. It sends SAML validation to the SAML methods. For other signed XML, it shows xml-crypto's SignedXml with getSignedReferences(), which xml-crypto 6.x supports. When xml-crypto releases its element verifier (XmlDSigVerifier: verify the enveloped signature of a given element xml-crypto#627), the README can point there instead.
• Cache provider adds CacheProviderOptions to its list of root exports.

Notes for the reviewer

• This reverses one decision from Export InMemoryCacheProvider from the package root #454. That PR left CacheProviderOptions unexported, because callers pass an object literal and never need to name it. Under Deprecate deep imports under lib/, and export from the root the types its API uses #441's rule that everything the root API uses is exported from the root, it goes in.
• The validateSignature() migration no longer goes to getVerifiedXml(), a change from the advice Read the verified bytes in validatePostRequestAsync, not the raw ones #440 added: that is another lib/ path, and it closes in v6. getVerifiedXml() isn't promoted to the root either, per Deprecate deep imports under lib/, and export from the root the types its API uses #441's decision. Deprecate deep imports under lib/, and export from the root the types its API uses #441's code search found no public code importing either function.

Release notes

For the 5.2.0 release, ready to paste:

Import from the package root. Every type node-saml's API uses is now exported from @node-saml/node-saml, including GenerateServiceProviderMetadataParams, CacheProviderOptions, SamlSigningOptions, and the XML types used by SAML's protected methods. The compiled modules under lib/ are internal. Deep imports such as @node-saml/node-saml/lib/types still work in 5.x, but the next major version closes them (#458), so move them to the package root now. The XML helpers under lib/xml (parseDomFromString, xpath, signXml) aren't exported from the root; use @xmldom/xmldom, xpath and xml-crypto directly.

Checklist:

• Issue Addressed: [x] Deprecate deep imports under lib/, and export from the root the types its API uses #441
• Link to SAML spec: n/a. This changes the package's module surface, not protocol behavior.
• Tests included? [ ] None: the change adds type-only exports
• Documentation updated? [x] README.md: the root types and the lib/ boundary under "Create a SAML instance", "Verifying a signature outside SAML" replacing "Low-level exports", and "Cache provider"

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added package-root exports for configuration, metadata generation, SAML signing, cache options, and XML-related types.
• Documentation
  • Updated package import guidance and clarified that deep imports and some XML helpers are not part of the public API.
  • Revised signed XML verification guidance to use xml-crypto, while keeping SAML validation in Node-SAML methods.