feat(api): add cart promo-code endpoint

[mgouia]

Summary

Adds a new POST /api/cart/promo-code endpoint that validates cart/promo inputs and applies percentage-based promo discounts to cart totals. The change also extends cart discount logic with reusable percentage helpers and adds tests that cover discount resolution and endpoint responses.

Changes

• Added app/api/cart/promo-code/route.ts with boundary validation, authN/authZ checks, promo applicability checks, and totals response.
• Updated lib/cart.ts to centralize percentage promo resolution (resolvePromoCodePercent) and bounded discount calculation (applyPercentageDiscount), then reused this logic in applyDiscount.
• Extended tests/cart.test.ts with promo percentage and clamping coverage.
• Added tests/promo-code-route.test.ts to cover unauthorized, forbidden, invalid/inapplicable promo code, and successful discount application cases.
• Added lint baseline files (.eslintrc.json, next-env.d.ts) and Next TypeScript plugin/include defaults in tsconfig.json so next lint runs non-interactively.

Testing

• npm run lint: PASS
• npm test: PASS

Out of scope (noted for follow-up)

• UI changes for entering promo codes in storefront pages.
• Persistence of promo-code usage in database.
• New CI/CD pipeline changes.

Check failures (if any)

None -- all checks green

Guideline compliance

• No secrets committed (secure-coding-base s.1)
• All new handlers have auth (secure-coding-base s.3)
• All new DB queries parameterized (secure-coding-base s.2)
• CI/CD changes follow golden paths (ci-cd-golden-paths)
• Docs updated where code changed meaning (docs-style-guide)