feat(semantic-tags): Add CurrencyAmount struct with amount and currencyCode fields

[njausteve]

Title

feat(semantic-tags): Add CurrencyAmount struct with amount and currencyCode fields

Type of Change

• New feature
• Bug fix
• Documentation update
• Refactoring
• Hotfix
• Security patch
• UI/UX improvement

Description

This PR implements Issues #115 and #98 by adding the ExPass.Structs.SemanticTags.CurrencyAmount module that represents monetary values with their associated currency for use in Apple Wallet pass semantic tags.

Key Features:

• Required amount field (string) for the monetary value
• Required currency_code field validated against ISO 4217 currency codes
• Accepts currency codes as both strings and atoms (atoms automatically converted to strings)
• Comprehensive validation with clear error messages
• JSON encoding with proper camelCase conversion for Apple Wallet compatibility

Implementation Details:
The CurrencyAmount struct follows the established patterns from other semantic tags (like Seat) and validates:

• amount must be a non-empty string
• currency_code must be a valid ISO 4217 code (using existing Validators.validate_currency_code/1)

classDiagram
    class CurrencyAmount {
        +amount: String*
        +currency_code: String*
        +new(attrs) CurrencyAmount
        -normalize_currency_code(attrs) attrs
        -validate_required_currency_code(value) ok or error
    }
    
    note for CurrencyAmount "Both fields are required.\ncurrency_code validates against ISO 4217."

Loading

Testing

Comprehensive Test Coverage:

• 21 test cases covering all functionality (6 doctests + 15 tests)
• Tests for required field validation
• Tests for valid/invalid currency codes
• Tests for atom-to-string currency code conversion
• Tests for string trimming
• Tests for JSON encoding with camelCase keys

All Tests Pass:

• ✅ 239 total project tests pass (216 tests + 23 doctests)
• ✅ Credo analysis shows no issues for new files
• ✅ No new warnings generated

Impact

Positive Impact:

• Enables representation of monetary values in Apple Wallet semantic tags
• Provides foundation for balance, price, and other financial semantic data
• Follows existing patterns for consistency and maintainability

Technical Considerations:

• No breaking changes - Pure additive feature
• No new dependencies - Uses existing infrastructure
• Minimal performance impact - Reuses existing validators
• Full backward compatibility

Additional Information

• Implementation follows established patterns from other structs (Seat, NFC, etc.)
• Module properly documented with moduledoc, typespecs, and comprehensive doctests
• JSON encoding correctly converts snake_case to camelCase per Apple Wallet specification

Apple Documentation Compliance:
This implementation aligns with Apple's PassKit documentation for currency amounts in semantic tags.

Checklist

• My code adheres to the coding and style guidelines of the project.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings

Closes #115
Closes #98

---

Note

Introduces ExPass.Structs.SemanticTags.CurrencyAmount to represent monetary values for Apple Wallet semantic tags.

• Defines required amount and currency_code fields with validation (required string for amount; ISO 4217 check for currency_code), including atom-to-string normalization
• Integrates existing Converter and Validators utilities and encodes to JSON with camelCase keys (currencyCode)
• Adds comprehensive tests covering validations, normalization, trimming, and JSON encoding

^{Written by Cursor Bugbot for commit b4160dd. This will update automatically on new commits. Configure here.}

[github-actions]

File	Coverage	Lines	Branches		Missing
All files	98%	98%	0%	✅

Minimum allowed coverage is 97%

Generated by 🐒 cobertura-action against b4160dd

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

This PR is being reviewed by Cursor Bugbot

Details

You are on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.