feat: standardize format field naming for clarity and consistency

[bokelley]

Summary

Implement consistent naming convention to eliminate confusion between format objects and format IDs across the AdCP API.

Problem

The current API has inconsistent usage of "formats" which causes developer confusion:

• Sometimes "formats" contains format objects (with full details)
• Sometimes "formats" contains format ID strings (just references)
• The get_products request had redundant "formats" and "format_types" filters

Solution

Establish clear, consistent naming convention:

• "formats" = array of format objects (with full details like name, type, requirements)
• "format_ids" = array of format ID strings (references to format objects)
• "format_types" = array of high-level type strings (video, display, audio)

Changes Made

Schema Changes

• Product schema: "formats" → "format_ids" (array of format ID strings)
• get_products request: Remove redundant "formats" filter (duplicated format_types functionality)
• create_media_buy request: "formats" → "format_ids" (array of format ID strings)

Documentation Updates

• Updated all examples and field descriptions in get_products.md and create_media_buy.md
• Fixed parameter tables and API documentation
• Updated validation examples and tests

What Stayed the Same

These correctly kept "formats" because they contain format objects:

• list_creative_formats response (returns full format objects)
• list_creatives filters (filters by format types like "video", "audio")
• Standard formats documentation (shows format objects)

Benefits

✅ Eliminates confusion - Field names immediately indicate content type
✅ Consistent API design - Same pattern across all endpoints
✅ Better developer experience - Self-documenting field names
✅ Cleaner filtering - Removed redundant filter options

Testing

• ✅ All schema validation tests pass
• ✅ All example validation tests pass
• ✅ TypeScript compilation succeeds
• ✅ Build process completes successfully

Breaking Changes

This is a breaking change for:

• Product responses: formats field renamed to format_ids
• create_media_buy requests: formats field renamed to format_ids
• get_products request filters: formats filter removed (use format_types or format_ids)

Clients will need to update their code to use the new field names.

🤖 Generated with Claude Code