Summary
The library exports four types with "Package" in the name, and there's no documentation or naming convention that tells you which one to use where:
| Type |
What it actually is |
PackageRequest |
Input to create_media_buy (what the buyer sends) |
Package |
Output from CreateMediaBuySuccessResponse.packages |
MediaBuyPackage |
Output from GetMediaBuysResponse (delivery state) |
AssignedPackage |
Output from CreateMediaBuySuccessResponse (v2 pattern?) |
When building create_media_buy, I tried MediaBuyPackage first (name suggests "a package in a media buy"), then AssignedPackage, and finally discovered Package was correct — after two Pydantic validation failures at runtime.
The Confusion
The names don't indicate directionality (input vs output) or lifecycle stage:
Package sounds generic/canonical — but it's specifically the response type for create_media_buyMediaBuyPackage sounds like "a package within a media buy" — but it's the delivery/reporting variantAssignedPackage sounds like what you get after assignment — but it's a different response shapePackageRequest is the only one with a clear name
Suggested Improvements
Option A: Documentation — Add a type map to the README or a docstring on each type explaining where it's used:
class Package(BaseModel):
"""Package as returned by create_media_buy.
For creating media buys, use PackageRequest.
For delivery reporting, see MediaBuyPackage.
"""Option B: Naming (breaking, but clearer for next major version):
| Current |
Suggested |
PackageRequest |
PackageRequest (fine) |
Package |
PackageConfirmation or CreatedPackage |
MediaBuyPackage |
PackageDeliveryState or ActivePackage |
AssignedPackage |
PackageAssignment |
Option C: Re-export with aliases — Keep generated names but add semantic aliases:
# In adcp/types/aliases.py
CreateMediaBuyPackage = Package # type used in CreateMediaBuySuccessResponse
Impact
This is the second-biggest friction point after the PricingOption RootModel issue (#145). Every new sales agent implementation will hit this trial-and-error cycle.
Environment
Summary
The library exports four types with "Package" in the name, and there's no documentation or naming convention that tells you which one to use where:
PackageRequestcreate_media_buy(what the buyer sends)PackageCreateMediaBuySuccessResponse.packagesMediaBuyPackageGetMediaBuysResponse(delivery state)AssignedPackageCreateMediaBuySuccessResponse(v2 pattern?)When building
create_media_buy, I triedMediaBuyPackagefirst (name suggests "a package in a media buy"), thenAssignedPackage, and finally discoveredPackagewas correct — after two Pydantic validation failures at runtime.The Confusion
The names don't indicate directionality (input vs output) or lifecycle stage:
Packagesounds generic/canonical — but it's specifically the response type forcreate_media_buyMediaBuyPackagesounds like "a package within a media buy" — but it's the delivery/reporting variantAssignedPackagesounds like what you get after assignment — but it's a different response shapePackageRequestis the only one with a clear nameSuggested Improvements
Option A: Documentation — Add a type map to the README or a docstring on each type explaining where it's used:
Option B: Naming (breaking, but clearer for next major version):
PackageRequestPackageRequest(fine)PackagePackageConfirmationorCreatedPackageMediaBuyPackagePackageDeliveryStateorActivePackageAssignedPackagePackageAssignmentOption C: Re-export with aliases — Keep generated names but add semantic aliases:
Impact
This is the second-biggest friction point after the PricingOption RootModel issue (#145). Every new sales agent implementation will hit this trial-and-error cycle.
Environment