Sorting and filtering with facets in paginated feed (PP-3856)

[tdilauro]

Description

Organizes variations of the paginated / crawlable libraries feed (/libraries/crawlable) around facet query parameters alone, rather than relying on a qa route / endpoint variant to include the hidden libraries along with the production ones in the feed.

Key changes:

• Added OPDS 2.0 facet groups to every paginated feed response — sort and availability groups, each with type URI, param name, per-link values, defaults, and sort groupings.
• Pagination links now preserve the availability parameter alongside order.
• Added a group property returning an OrderFacetGroup enum value, allowing clients to identify paired variants (e.g. modified/modified-asc) without heuristics.

Supported facets

?order= — sort order

Value	Description	Group	Default
modified	Most recently modified first (reverse chronological)	modified	✓
modified-asc	Least recently modified first (chronological)	modified
name	Library name A–Z (case-insensitive)	name
name-desc	Library name Z–A (case-insensitive)	name
natural	Database natural order
default	Alias for modified (not advertised in facets)

?availability= — availability filter

Value	Description	Default
production	Libraries where both library_stage and registry_stage are PRODUCTION	✓
hidden	Libraries where at least one stage is TESTING and neither is CANCELLED
all	All non-cancelled libraries (production + hidden)

Comma-separated combinations (e.g. production,hidden) are accepted, but not advertised in facets; prefer all for the full non-cancelled list of libraries.

Motivation and Context

These changes move the crawlable feed API and contents closer to OPDS standards and idioms, which should make it more accessible to the community.

[Jira PP-3856]

How Has This Been Tested?

• Manual testing of the feed in local development environment.
• New and updated test cases.
• All tests pass locally.
• CI tests and checks.

Checklist

• I have updated the documentation accordingly.
• All new and existing tests passed.

[tdilauro]

@jonathangreen Requesting your review on this one, since you have some context from our discussion. I kept the properties we talked about in and provided some context. That said, I'm perfectly willing to pull out the ones you had questions / concerns about.

[jonathangreen]

This all looks good to me. I'm a bit nervous about defining the new facet/param, facet/value, and facet/group properties here, when we don't really need them for registry purposes. I'd rather we pilot these things in circulation, then move them out to other places as we find them useful, but I'm also not opposed to them going in here.