[SABRA-2456] Add V2 Facets and Searchabilities API Support

[aandrukhovich]

Add V2 Facets and Searchabilities API Support

Summary

This PR adds support for the V2 versions of the /v2/facets and /v2/searchabilities endpoints, running in parallel with the existing V1 implementations.

Changes

New Facets V2 Methods

• addFacetConfigurationV2 - Create a single facet configuration
• getFacetConfigurationsV2 - Retrieve all facet configurations with pagination
• getFacetConfigurationV2 - Get a specific facet by name
• modifyFacetConfigurationsV2 - Batch partial update facets (PATCH)
• modifyFacetConfigurationV2 - Partially update a single facet
• replaceFacetConfigurationV2 - Replace a single facet configuration (PUT)
• createOrReplaceFacetConfigurationsV2 - Batch create or replace facets (PUT)
• removeFacetConfigurationV2 - Delete a facet configuration

New Searchabilities V2 Methods

• retrieveSearchabilitiesV2 - Retrieve searchabilities with filtering/pagination/sorting
• getSearchabilityV2 - Get a specific searchability by name
• patchSearchabilitiesV2 - Batch create or update searchabilities
• patchSearchabilityV2 - Update a single searchability
• deleteSearchabilitiesV2 - Batch delete searchabilities
• deleteSearchabilityV2 - Delete a single searchability

New Types (TypeScript)

• FacetConfigurationV2 - V2 facet model with pathInMetadata field
• SearchabilityConfigurationV2 - V2 searchability model with new fields (displayable, hidden, createdAt, updatedAt)
• Request/response types for all V2 operations

V2 API Differences from V1

Facets:

• Requires pathInMetadata field which specifies where in item metadata the facet data is located
• Uses /v2/facets endpoint instead of /v1/facets

Searchabilities:

• Adds displayable and hidden fields
• Adds createdAt/updatedAt timestamps
• Simplified query parameter filtering (direct boolean params)
• Uses /v2/searchabilities endpoint instead of /v1/searchabilities

Test Plan

• Added catalog-facet-configurations-v2.js with comprehensive test coverage for all facet V2 operations
• Added catalog-searchabilities-v2.js with comprehensive test coverage for all searchability V2 operations
• All tests include proper cleanup in after hooks
• Tests cover success cases, error cases, and network timeout scenarios

Breaking Changes

None. V2 methods are additive and V1 methods remain unchanged.

[constructor-claude-bedrock]

Code Review Results

✅ Strengths

Well-structured implementation with comprehensive test coverage for V2 Facets and Searchabilities APIs, maintaining backwards compatibility with V1 methods while properly handling camelCase/snake_case conversions.

🚨 Critical Issues

None

⚠️ Important Issues

Test File Issues

[File: spec/src/modules/catalog/catalog-facet-configurations-v2.js Line: L87]
The test pushes mockFacetConfiguration to facetConfigurations array for cleanup, but the cleanup logic tries to call removeFacetConfigurationV2(facetConfig) passing the entire facet object instead of just { name: facetConfig.name }. This will cause cleanup to fail because removeFacetConfigurationV2 expects a parameters object with a name property.

Fix: Update line 67 in the cleanup for await loop:

await catalog.removeFacetConfigurationV2({ name: facetConfig.name });

[File: spec/src/modules/catalog/catalog-facet-configurations-v2.js Line: L108-L112]
The backwards compatibility test creates a facet with snake_case properties but does not verify that the API actually receives the correct snake_case format. It only checks the response. Consider adding verification that the request body was properly formatted.

[File: spec/src/modules/catalog/catalog-searchabilities-v2.js Line: L50]
Inconsistent use of done() callback vs setTimeout(done, sendTimeout). Line 50 uses setTimeout(done, sendTimeout) while other places use setTimeout(() => done(), sendTimeout). While both work, consistency would be better.

Implementation Issues

[File: src/modules/catalog.js Line: L4355]
Destructuring of skip_rebuild and skipRebuild parameters creates unnecessary variables _sr and _srCamel that are never used. This can be simplified:

const { name, section = 'Products', ...rest } = parameters;
const { skip_rebuild, skipRebuild = skip_rebuild } = parameters;

[File: src/modules/catalog.js Lines: L3704, L3914, L3989, L4049, L4228, L4370, L4502]
All V2 methods use encodeURIComponent(name) when building URLs, which is good. However, there is inconsistent parameter validation - some methods check !name || typeof name !== 'string' while others do not validate at all before using the name in the URL path. All methods that use name in the URL should validate it.

Type Definition Issues

[File: src/types/catalog.d.ts Line: L298]
The ModifyFacetConfigurationsV2Parameters type requires name to be present, but for a partial modification, this is correct. However, the JSDoc comment for modifyFacetConfigurationsV2 in catalog.js does not clearly indicate that name is required in each facet configuration object.

[File: src/types/index.d.ts Line: L342]
FacetConfigurationV2 defines type as 'multiple' | 'hierarchical' | 'range' but the V1 BaseFacetConfiguration does not include 'hierarchical'. This is a V2-specific enhancement, which is fine, but should be documented in the function JSDoc comments.

💡 Suggestions

Code Quality Improvements

[File: spec/src/modules/catalog/catalog-facet-configurations-v2.js Line: L26-L34]
The createMockFacetConfigurationV2 function could benefit from accepting optional parameters to customize the mock, making tests more flexible:

function createMockFacetConfigurationV2(overrides = {}) {
  const uuid = uuidv4();
  return {
    name: \`facet-v2-\${uuid}\`,
    pathInMetadata: \`metadata.facet_v2_\${uuid}\`,
    displayName: \`Facet V2 \${uuid}\`,
    type: 'multiple',
    ...overrides,
  };
}

[File: spec/src/modules/catalog/catalog-searchabilities-v2.js Line: L26-L35]
Similar suggestion for createMockSearchabilityConfigurationV2 - accept optional overrides parameter.

[File: src/modules/catalog.js Line: L4106-L4124]
The parameter extraction in retrieveSearchabilitiesV2 has a lot of destructuring with backwards compatibility aliases. Consider extracting this to a helper function to reduce duplication across similar methods.

[File: src/modules/catalog.js Line: L3643]
The check if (!helpers.isNil(offset)) is good, but consider also validating that offset is a non-negative number to prevent API errors.

Test Coverage Improvements

[File: spec/src/modules/catalog/catalog-facet-configurations-v2.js]
Consider adding tests for:

• Invalid pathInMetadata values (empty string, special characters)
• Edge cases for offset parameter (negative values, very large values)
• Concurrent modifications to the same facet

[File: spec/src/modules/catalog/catalog-searchabilities-v2.js]
Consider adding tests for:

• Combination of page and offset parameters (should they both be present?)
• Testing skipRebuild parameter actually affects API calls

Documentation Improvements

[File: src/modules/catalog.js Line: L3536-L3570]
Excellent JSDoc comments for addFacetConfigurationV2. Consider adding a note about the key difference from V1: the required pathInMetadata field and what it represents in practical terms.

[File: src/modules/catalog.js Line: L4074-L4099]
The JSDoc for retrieveSearchabilitiesV2 should clarify the difference between V1 complex filters object and V2 direct boolean query parameters.

Performance Considerations

[File: spec/src/modules/catalog/catalog-facet-configurations-v2.js Line: L56-L73]
The cleanup loop processes facets sequentially with for await. If cleanup performance becomes an issue with many facets, consider batching deletions (though the API might not support batch delete for facets).

Overall Assessment: ✅ Pass

The implementation is solid with good test coverage and proper backwards compatibility handling. The important issues identified are minor cleanup bugs in tests that should be fixed before merge. The codebase follows existing patterns well and the V2 API additions are well-integrated.

[constructor-claude-bedrock]

Code Review Results

Strengths

This PR adds well-structured V2 endpoints for Facets and Searchabilities with comprehensive test coverage, proper TypeScript types, and backward compatibility support for snake_case parameters.

Critical Issues

None identified. The implementation is solid and ready to merge.

Important Issues

Test File Issues

File: spec/src/modules/catalog/catalog-facet-configurations-v2.js Line: 69

• Issue: The cleanup logic passes the entire facet configuration object to removeFacetConfigurationV2, but the API expects an object with just name and optionally section. While this may work due to parameter destructuring, it is inconsistent with the API design.
• Recommendation: Change line 69 to: await catalog.removeFacetConfigurationV2({ name: facetConfig.name });

File: spec/src/modules/catalog/catalog-facet-configurations-v2.js Line: 78-165

• Issue: mockFacetConfiguration is defined outside the test in addFacetConfigurationV2 describe block (line 78), which could cause test interdependency issues if tests run in unexpected orders. The test at line 122 depends on facetConfigurations[0] existing from the first test.
• Recommendation: Use a before hook to set up the initial facet configuration for the duplicate test, similar to other describe blocks in the file.

Implementation Issues

File: src/modules/catalog.js Line: 3704, 3914, 3989, 4049, 4228, 4370, 4502

• Issue: Inconsistent URL encoding - encodeURIComponent(name) is used for path parameters, but the name parameter itself is not validated for potentially problematic characters before encoding.
• Recommendation: While the current implementation is functional, consider adding validation or sanitization for special characters in facet/searchability names to provide clearer error messages to users.

File: src/modules/catalog.js Line: 4355

• Issue: Unused destructured variables _sr and _srCamel in patchSearchabilityV2. These are destructured but never used.
• Recommendation: This appears intentional to exclude them from the rest spread, but the underscore prefix convention could be clearer. Consider adding a comment.

TypeScript Type Issues

File: src/types/catalog.d.ts Line: 727, 759

• Issue: Return type consistency - modifyFacetConfigurationV2 and patchSearchabilityV2 both return singular response types. Both are PATCH operations on single resources, which is correct.
• Recommendation: Verify that the actual API responses match these types. The implementation looks correct.

Suggestions

File: spec/src/modules/catalog/catalog-facet-configurations-v2.js Line: 26-35

• Suggestion: The createMockFacetConfigurationV2 helper could benefit from accepting optional parameters to customize the generated facets, making tests more flexible.

File: src/modules/catalog.js Line: 3577-3579, 3631-3633

• Suggestion: The default section value Products is repeated across multiple V2 methods. Consider extracting this as a constant at the module level for better maintainability.

File: spec/src/modules/catalog/catalog-facet-configurations-v2.js Line: 103-120

• Suggestion: The backwards compatibility test for display_name is excellent. Consider adding similar tests for other camelCase/snake_case conversions to ensure comprehensive coverage.

File: src/modules/catalog.js Line: 4106-4124

• Suggestion: The retrieveSearchabilitiesV2 method has extensive parameter handling with both camelCase and snake_case support. Consider extracting this pattern into a helper function to reduce code duplication.

General

• Suggestion: Consider adding a migration guide or code examples in the PR description or documentation showing how to migrate from V1 to V2 APIs, highlighting the key differences.

Overall Assessment: Pass

This is high-quality work with excellent test coverage and proper implementation. The V2 APIs are well-designed with backward compatibility support. The few issues identified are minor and the suggestions are for code quality improvements rather than functional problems. The PR is ready to merge after addressing the test cleanup inconsistency if desired.