fix: warn and skip deprecated guardian phone provider on 403 during import

[harshithRai]

🔧 Changes

Importing a YAML configuration exported from an older tenant into a newer tenant could abort the entire import when the legacy per-factor phone provider API is disabled on the target tenant. The Management API returns 403 legacy_mfa_phone_provider_not_allowed ("Insufficient privileges to use this deprecated feature"), and the import failed hard during the processChanges stage.

The export/getType path already handled such 403s gracefully via isForbiddenFeatureError (warn + skip). This change wires the same behavior into the import/processChanges path for the guardian phone resources, so a deprecated/forbidden feature now logs a warning and is skipped instead of failing the deployment.

• guardianFactorTemplates, guardianPhoneFactorSelectedProvider, guardianPhoneFactorMessageTypes: wrapped the write API calls in processChanges to catch a deprecated/forbidden 403 and skip instead of throwing.
• isForbiddenFeatureError (utils): cleaned up the warning to read the human-readable message and errorCode from the response body (originalError.response.body) instead of logging the full serialized error blob. This improves logging for every 403-skippable resource that uses the helper.
• guardianPhoneFactorSelectedProvider, guardianPhoneFactorMessageTypes: simplified isFeatureUnavailableError to only handle the 404 (endpoint-not-available) case. The hooks_not_allowed / voice_mfa_not_allowed 403 branches were redundant since isForbiddenFeatureError already catches any 403 - these 403s now emit a warn log instead of being skipped silently, consistent with other forbidden-feature handling.

📚 References

• Error legacy_mfa_phone_provider_not_allowed is returned at runtime by the Management API but is not documented in the OpenAPI spec or typed in auth0-node (v6.x) - verified against management-api-oas.json. The fix therefore treats any 403 on these guardian phone endpoints as a skippable deprecated/forbidden feature rather than matching a specific errorCode string.
• GET / PUT /guardian/factors/sms/templates are documented as deprecated in favor of the phone-templates endpoints: https://auth0.com/docs/api/management/v2/guardian/put-factor-phone-templates

🔬 Testing

Verified end-to-end against a live tenant with "Use Tenant-Level Messaging Provider" enabled (which disables the legacy per-factor phone API):

• Before the fix: a0deploy import with guardianPhoneFactorSelectedProvider in the YAML failed with Problem running command import during stage processChanges when processing type guardianPhoneFactorSelectedProvider and exited with code 1.
• After the fix: the same import logged warn: Insufficient privileges to use this deprecated feature. (legacy_mfa_phone_provider_not_allowed) - Skipping guardianPhoneFactorSelectedProvider, reported Import Successful, and exited with code 0.

Unit tests added/updated:

• guardianFactorTemplates: verifies processChanges warns and skips on a legacy-feature 403 instead of throwing.
• isForbiddenFeatureError: verifies the cleaned-up warning message and errorCode are extracted from the response body.
• guardianPhoneFactorSelectedProvider / guardianPhoneFactorMessageTypes: existing "endpoint is disabled for tenant" tests still pass, now routing the 403 through isForbiddenFeatureError (returns null/skips, with a warn log).

📝 Checklist

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

[ankita10119]

Hey, curious about the hooks_not_allowed errorCode here, is this specific to the phone provider endpoint, or could it have been carried over from somewhere else?

Asking because I'd expect Auth0 to return something like legacy_mfa_phone_provider_not_allowed here rather than a hooks related errorCode

If it's not needed, we could simplify isFeatureUnavailableError to just handle the 404 case and let isForbiddenFeatureError take care of 403s (which it already does)

Totally a nit though, not a blocker!

[harshithRai]

Good catch! you're right. hooks_not_allowed was pre-existing and redundant since isForbiddenFeatureError already handles any 403. Simplified isFeatureUnavailableError to just the 404 case in both handlers. Pushed the change 👍

[codecov-commenter]

Codecov Report

❌ Patch coverage is 50.00000% with 11 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (master@52b338f). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...rc/tools/auth0/handlers/guardianFactorTemplates.ts	37.50%	3 Missing and 2 partials ⚠️
.../auth0/handlers/guardianPhoneFactorMessageTypes.ts	40.00%	3 Missing ⚠️
...h0/handlers/guardianPhoneFactorSelectedProvider.ts	40.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##             master    #1429   +/-   ##
=========================================
  Coverage          ?   80.20%           
=========================================
  Files             ?      163           
  Lines             ?     7542           
  Branches          ?     1665           
=========================================
  Hits              ?     6049           
  Misses            ?      805           
  Partials          ?      688           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 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.