Fix Shopify HMAC base64 verification and improve webhook error diagnostics

[Prateek32177]

Motivation

• Shopify webhooks were failing verification because the X-Shopify-Hmac-SHA256 signature is base64-encoded while the verifier previously treated some providers as hex/Clerk-style secrets.
• Secret decoding logic was leaking Clerk/Svix assumptions into other providers which caused incorrect HMAC key material for Shopify.
• verifyAny() returned opaque failures when multiple platform attempts existed, making it hard to debug which platform or reason failed.
• Framework adapters returned minimal 400 responses; adding errorCode and metadata makes failures actionable for integrators.

Description

• Updated platform configs in src/platforms/algorithms.ts to treat Shopify as a base64-signed HMAC (headerName: 'x-shopify-hmac-sha256', customConfig.encoding: 'base64', customConfig.secretEncoding: 'utf8') and finalized Polar’s Standard Webhooks config (webhook-signature, webhook-timestamp, customConfig payload).
• Made base64 HMAC verifier robust in src/verifiers/algorithms.ts by decoding the secret only when config.customConfig?.secretEncoding === 'base64' and handling underscore-prefixed secret formats safely; Shopify secrets remain UTF-8 and are not base64-decoded.
• Improved multi-secret discovery in src/index.ts by collecting per-platform failedAttempts and returning an aggregated error string plus metadata.attempts containing { platform, error, errorCode } for each attempt.
• Updated framework adapters src/adapters/express.ts, src/adapters/nextjs.ts, and src/adapters/cloudflare.ts to include errorCode and metadata in 400 responses to aid troubleshooting.
• Enhanced header-based detection in src/utils.ts and src/index.ts so Polar can be auto-detected from webhook-signature with a Polar user-agent.
• Added tests in src/test.ts for Shopify verification, verifyAny diagnostic reporting, and Polar Standard Webhooks, and updated documentation in README.md, USAGE.md, FRAMEWORK_SUMMARY.md, and ARCHITECTURE.md to reflect these behaviors.

Testing

• Built the project with npm run build, which completed successfully.
• Ran the test suite with npm test; tests were iterated during fixes and the final run shows all tests passing (dist/test.js execution completed with all test cases PASSED).

---

Codex Task