feat: enhance customer resources with real examples and OAuth2 documentation

[dfcoffin]

Summary

• Update all 16 customer resource response examples with real ESPI sample data
• Add 25 customer supporting schemas to components section
• Enhance OAuth2 documentation with detailed function block descriptions
• Restore OAuth2 visibility in Redocly and Swagger UI documentation

What Changed

1. Real Customer Resource Examples (16 files)

Replaced placeholder XML examples in all customer response files with real data from ESPI_Customer_Sample.xml:

Customer:

• Full Organisation structure with streetAddress
• Real address: 200 SECOND AVE, OLDCASTLE, ON N9V 2T7
• Customer name: JOHN DOE

CustomerAccount:

• Complete contactInfo with address details
• Real accountId: 30000000-00

CustomerAgreement:

• Real agreementId: 30000000-00_004_electric

ServiceSupplier:

• Organisation name: Acme Energy Supplier
• Kind: retailer

ServiceLocation:

• Full mainAddress structure
• UsagePoints link to actual usage point

Meter & EndDevice:

• Real serial numbers: EPP00004, inverter-01-51111111111

ProgramDateIdMappings:

• DR program enrollment details

2. Customer Supporting Schemas (25 schemas added)

Added all customer supporting schemas to components.schemas section to match energy section format:

Address Schemas:

• Organisation, StreetAddress, StreetDetail, TownDetail
• TelephoneNumber, ElectronicAddress

Document Schemas:

• Document, Agreement

Asset Schemas:

• Asset, Location, PositionPoint
• LifecycleDate, AcceptanceTest

Status Schemas:

• Status, Priority

Program Schemas:

• DemandResponseProgram, ProgramDate, ProgramDateIdMapping

Account Schemas:

• AccountNotification, MeterMultiplier

Reference Schemas:

• StatementRef, PricingStructure, BatchItemInfo

3. Enhanced OAuth2 Documentation

Completely rewrote OAuth2 security scheme documentation to be visible in generated docs:

Added:

• Comprehensive description of both Authorization Code and Client Credentials flows
• Detailed explanation of all 17 ESPI function blocks (FB_1 through FB_58)
• 4 scope options for different access levels:
  • Full scope with customer resources (FB_1-39 + FB_50-58)
  • Full scope energy only (FB_1-39)
  • Usage data and summaries only (FB_4,5,8,13,14,15)
  • Customer and billing data only (FB_50-58)

Function Blocks Documented:

• FB_1: Provide Subscription
• FB_3-5: Usage Point and Reading Type
• FB_8, 13-15: Meter Reading and Summaries
• FB_18-19: Local Time Parameters and Application Info
• FB_31-39: Authorization and Batch Operations
• FB_50-58: Customer Resources (NEW)

Test Plan

• OpenAPI spec validates with zero errors (npm test)
• Documentation builds successfully (npm run build)
• OAuth2 security scheme appears in Redocly docs
• OAuth2 authorization button appears in Swagger UI
• All customer examples use real ESPI sample data
• All 25 supporting schemas properly registered

Documentation Impact

• ✅ OAuth2 "Authorize" button now visible in Swagger UI
• ✅ Security requirements section shows in Redocly docs
• ✅ Function block scopes clearly explained
• ✅ Customer resource examples show realistic PII data
• ✅ All supporting schemas properly documented

Before/After

Before (OAuth2):

• Single generic scope
• No function block explanations
• Not visible in generated docs

After (OAuth2):

• 4 detailed scope options
• Complete function block documentation
• Fully visible with "Authorize" button in Swagger UI

Before (Customer Examples):

<Customer xmlns="http://naesb.org/espi/customer">
  <kind>0</kind>
  <locale>en_US</locale>
  <customerName>John Smith</customerName>
</Customer>

After (Customer Examples):

<Customer xmlns="http://naesb.org/espi/customer">
  <Organisation>
    <streetAddress>
      <streetDetail>
        <addressGeneral>200 SECOND AVE</addressGeneral>
      </streetDetail>
      <townDetail>
        <name>OLDCASTLE</name>
        <stateOrProvince>ON</stateOrProvince>
      </townDetail>
      <postalCode>N9V 2T7</postalCode>
    </streetAddress>
  </Organisation>
  <kind>other</kind>
  <customerName>JOHN DOE</customerName>
</Customer>

🤖 Generated with Claude Code