fix: Support optional properties on operation payloads (#66)

* fix: Support optional properties on transaction endpoints

* fix: Support optional properties on subscription operations

* fix: Handle null product and price IDs in preview responses

CHANGELOG.md

@@ -12,6 +12,20 @@ Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx
 
 - `paddle_billing.Resources.Discounts.Operations.CreateDiscount` `expires_at` is now `paddle_billing.Entities.DateTime`
 - `paddle_billing.Resources.Discounts.Operations.UpdateDiscount` `expires_at` is now `paddle_billing.Entities.DateTime`
+- Transaction and Subscription operation items now allow optional properties to be omitted.
+  - The following property types have changed (See UPGRADING.md for further details)
+    - `paddle_billing.Resources.Subscriptions.Operations`:
+      - `UpdateSubscription.items`
+      - `PreviewUpdateSubscription.items`
+      - `CreateOneTimeCharge.items`
+      - `PreviewOneTimeCharge.items`
+    - `paddle_billing.Resources.Transactions.Operations`:
+      - `CreateTransaction.items`
+      - `UpdateTransaction.items`
+      - `PreviewTransactionByAddress.items`
+      - `PreviewTransactionByCustomer.items`
+      - `PreviewTransactionByIP.items`
+- Transaction and Subscription preview responses now support preview products and prices without IDs (see UPGRADING.md for further details)
 
 ### Removed
 - `get_parameters()` method on request operation classes is now removed or replaced by `to_json()` (see UPGRADING.md for further details)

UPGRADING.md

@@ -62,6 +62,71 @@ All breaking changes prior to v1 will be documented in this file to assist with
   - `paddle_billing.Resources.Transactions.Operations.PreviewTransactionByCustomer`
   - `paddle_billing.Resources.Transactions.Operations.PreviewTransactionByIP`
 
+### 2. Transaction and Subscription operation items now allow optional properties to be omitted.
+
+Transaction and Subscription operation item types have changed to new types that allow optional properties to be omitted.
+
+- `paddle_billing.Resources.Subscriptions.Operations` `UpdateSubscription` and `PreviewUpdateSubscription` `items` are now list of:
+  - `paddle_billing.Resources.Subscriptions.Operations.Update.SubscriptionUpdateItem`
+  - `paddle_billing.Resources.Subscriptions.Operations.Update.SubscriptionUpdateItemWithPrice`
+- `paddle_billing.Resources.Subscriptions.Operations` `CreateOneTimeCharge` and `PreviewOneTimeCharge` `items` are now list of:
+  - `paddle_billing.Resources.Subscriptions.Operations.Charge.SubscriptionChargeItem`
+  - `paddle_billing.Resources.Subscriptions.Operations.Charge.SubscriptionChargeItemWithPrice`
+- `paddle_billing.Resources.Transactions.Operations.CreateTransaction.items` is now list of:
+  - `paddle_billing.Resources.Transactions.Operations.Create.TransactionCreateItem`
+  - `paddle_billing.Resources.Transactions.Operations.Create.TransactionCreateItemWithPrice`
+- `paddle_billing.Resources.Transactions.Operations.UpdateTransaction.items` is now list of:
+  - `paddle_billing.Resources.Transactions.Operations.Update.TransactionUpdateItem`
+  - `paddle_billing.Resources.Transactions.Operations.Update.TransactionUpdateItemWithPrice`
+- `paddle_billing.Resources.Transactions.Operations` `PreviewTransactionByAddress`, `PreviewTransactionByCustomer` and `PreviewTransactionByIP` `items` are now list of:
+  - `paddle_billing.Resources.Transactions.Operations.Preview.TransactionItemPreviewWithNonCatalogPrice`
+  - `paddle_billing.Resources.Transactions.Operations.Preview.TransactionItemPreviewWithPriceId`
+
+
+The following classes have been removed:
+- `paddle_billing.Entities.Subscriptions`:
+  - `SubscriptionItems`
+    - replaced by `paddle_billing.Resources.Subscriptions.Operations.Update.SubscriptionUpdateItem`
+  - `SubscriptionItemsWithPrice`
+    - replaced by `paddle_billing.Resources.Subscriptions.Operations.Update.SubscriptionUpdateItemWithPrice`
+  - `SubscriptionNonCatalogPrice`
+    - replaced by `paddle_billing.Resources.Subscriptions.Operations.Price.SubscriptionNonCatalogPrice`
+  - `SubscriptionNonCatalogPriceWithProduct`
+    - replaced by `paddle_billing.Resources.Subscriptions.Operations.Price.SubscriptionNonCatalogPriceWithProduct`
+  - `SubscriptionNonCatalogProduct`
+    - replaced by `paddle_billing.Resources.Subscriptions.Operations.Price.SubscriptionNonCatalogProduct`
+- `paddle_billing.Entities.Transactions`:
+  - `TransactionCreateItem`
+    - replaced by:
+      - `paddle_billing.Resources.Transactions.Operations.Create.TransactionCreateItem` (for create)
+      - `paddle_billing.Resources.Transactions.Operations.Update.TransactionUpdateItem` (for update)
+  - `TransactionCreateItemWithPrice`
+    - replaced by:
+      - `paddle_billing.Resources.Transactions.Operations.Create.TransactionCreateItemWithPrice` (for create)
+      - `paddle_billing.Resources.Transactions.Operations.Update.TransactionUpdateItemWithPrice` (for update)
+  - `TransactionNonCatalogPrice`
+    - replaced by `paddle_billing.Resources.Transactions.Operations.Price.TransactionNonCatalogPrice`
+  - `TransactionNonCatalogPriceWithProduct`
+    - replaced by `paddle_billing.Resources.Transactions.Operations.Price.TransactionNonCatalogPriceWithProduct`
+  - `TransactionNonCatalogProduct`
+    - replaced by `paddle_billing.Resources.Transactions.Operations.Price.TransactionNonCatalogProduct`
+  - `TransactionItemPreviewWithNonCatalogPrice`
+    - replaced by `paddle_billing.Resources.Transactions.Operations.Preview.TransactionItemPreviewWithNonCatalogPrice`
+  - `TransactionItemPreviewWithPriceId`
+    - replaced by `paddle_billing.Resources.Transactions.Operations.Preview.TransactionItemPreviewWithPriceId`
+
+### 3. Transaction and Subscription preview responses now support preview products and prices without IDs
+
+- `SubscriptionPreview.immediate_transaction.details.line_items[].price_id` can now be `None`
+- `SubscriptionPreview.immediate_transaction.details.line_items[].product` is now `paddle_billing.Entities.Shared.TransactionPreviewProduct`
+- `SubscriptionPreview.next_transaction.details.line_items[].price_id` can now be `None`
+- `SubscriptionPreview.next_transaction.details.line_items[].product` is now `paddle_billing.Entities.Shared.TransactionPreviewProduct`
+- `SubscriptionPreview.recurring_transaction_details.line_items[].price_id` can now be `None`
+- `SubscriptionPreview.recurring_transaction_details.line_items[].product` is now `paddle_billing.Entities.Shared.TransactionPreviewProduct`
+- `TransactionPreview.items[].price` is now `TransactionPreviewPrice`
+- `TransactionPreview.details.line_items[].price_id` can now be `None`
+- `TransactionPreview.details.line_items[].product` is now `paddle_billing.Entities.Shared.TransactionPreviewProduct`
+
 ## v0.3.0
 
 ### 1. `AvailablePaymentMethods` has been replaced by `PaymentMethodType`.

paddle_billing/Entities/Price.py

@@ -15,10 +15,6 @@
     UnitPriceOverride,
 )
 
-from paddle_billing.Logger import get_logger
-
-log = get_logger()
-
 
 @dataclass
 class Price(Entity):

paddle_billing/Entities/Shared/TransactionLineItemPreview.py

@@ -1,30 +1,30 @@
 from __future__ import annotations
 from dataclasses import dataclass
 
-from paddle_billing.Entities.Product import Product
+from paddle_billing.Entities.Shared.TransactionPreviewProduct import TransactionPreviewProduct
 from paddle_billing.Entities.Shared.Totals import Totals
 from paddle_billing.Entities.Shared.UnitTotals import UnitTotals
 from paddle_billing.Entities.Shared.Proration import Proration
 
 
 @dataclass
 class TransactionLineItemPreview:
-    price_id: str
+    price_id: str | None
     quantity: int
     tax_rate: str
     unit_totals: UnitTotals
     totals: Totals
-    product: Product
+    product: TransactionPreviewProduct
     proration: Proration | None
 
     @staticmethod
     def from_dict(data: dict) -> TransactionLineItemPreview:
         return TransactionLineItemPreview(
-            price_id=data["price_id"],
+            price_id=data.get("price_id"),
             quantity=data["quantity"],
             tax_rate=data["tax_rate"],
             unit_totals=UnitTotals.from_dict(data["unit_totals"]),
             totals=Totals.from_dict(data["totals"]),
-            product=Product.from_dict(data["product"]),
+            product=TransactionPreviewProduct.from_dict(data["product"]),
             proration=Proration.from_dict(data["proration"]) if data.get("proration") else None,
         )

paddle_billing/Entities/Shared/TransactionPreviewProduct.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from datetime import datetime
+
+from paddle_billing.Entities.Entity import Entity
+from paddle_billing.Entities.Shared import CatalogType, CustomData, ImportMeta, Status, TaxCategory
+
+
+@dataclass
+class TransactionPreviewProduct(Entity):
+    id: str | None
+    name: str
+    description: str | None
+    tax_category: TaxCategory
+    image_url: str | None
+    status: Status
+    created_at: datetime
+    updated_at: datetime
+    type: CatalogType | None = None
+    custom_data: CustomData | None = None
+    import_meta: ImportMeta | None = None
+
+    @staticmethod
+    def from_dict(data: dict) -> TransactionPreviewProduct:
+        return TransactionPreviewProduct(
+            id=data.get("id"),
+            name=data["name"],
+            description=data.get("description"),
+            tax_category=TaxCategory(data["tax_category"]),
+            image_url=data.get("image_url"),
+            status=Status(data["status"]),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            updated_at=datetime.fromisoformat(data["updated_at"]),
+            type=CatalogType(data["type"]) if data.get("type") else None,
+            custom_data=CustomData(data["custom_data"]) if data.get("custom_data") else None,
+            import_meta=ImportMeta.from_dict(data["import_meta"]) if data.get("import_meta") else None,
+        )

paddle_billing/Entities/Subscriptions/SubscriptionAdjustmentItem.py

@@ -9,7 +9,7 @@ class SubscriptionAdjustmentItem:
     item_id: str
     type: AdjustmentType
     amount: str | None
-    proration: Proration
+    proration: Proration | None
     totals: AdjustmentItemTotals
 
     @staticmethod
@@ -18,6 +18,6 @@ def from_dict(data: dict) -> SubscriptionAdjustmentItem:
             item_id=data["item_id"],
             type=AdjustmentType(data["type"]),
             amount=data.get("amount"),
-            proration=Proration.from_dict(data["proration"]),
+            proration=Proration.from_dict(data["proration"]) if data.get("proration") else None,
             totals=AdjustmentItemTotals.from_dict(data["totals"]),
         )

paddle_billing/Entities/Subscriptions/__init__.py

@@ -6,15 +6,8 @@
 from paddle_billing.Entities.Subscriptions.SubscriptionEffectiveFrom import SubscriptionEffectiveFrom
 from paddle_billing.Entities.Subscriptions.SubscriptionItem import SubscriptionItem
 from paddle_billing.Entities.Subscriptions.SubscriptionItemStatus import SubscriptionItemStatus
-from paddle_billing.Entities.Subscriptions.SubscriptionItems import SubscriptionItems
-from paddle_billing.Entities.Subscriptions.SubscriptionItemsWithPrice import SubscriptionItemsWithPrice
 from paddle_billing.Entities.Subscriptions.SubscriptionManagementUrls import SubscriptionManagementUrls
 from paddle_billing.Entities.Subscriptions.SubscriptionNextTransaction import SubscriptionNextTransaction
-from paddle_billing.Entities.Subscriptions.SubscriptionNonCatalogPrice import SubscriptionNonCatalogPrice
-from paddle_billing.Entities.Subscriptions.SubscriptionNonCatalogPriceWithProduct import (
-    SubscriptionNonCatalogPriceWithProduct,
-)
-from paddle_billing.Entities.Subscriptions.SubscriptionNonCatalogProduct import SubscriptionNonCatalogProduct
 from paddle_billing.Entities.Subscriptions.SubscriptionOnPaymentFailure import SubscriptionOnPaymentFailure
 from paddle_billing.Entities.Subscriptions.SubscriptionPreviewSubscriptionUpdateSummary import (
     SubscriptionPreviewSubscriptionUpdateSummary,
@@ -26,4 +19,3 @@
 from paddle_billing.Entities.Subscriptions.SubscriptionScheduledChange import SubscriptionScheduledChange
 from paddle_billing.Entities.Subscriptions.SubscriptionScheduledChangeAction import SubscriptionScheduledChangeAction
 from paddle_billing.Entities.Subscriptions.SubscriptionStatus import SubscriptionStatus
-from paddle_billing.Entities.Subscriptions.SubscriptionUpdateItem import SubscriptionUpdateItem

paddle_billing/Entities/Transactions/TransactionItem.py

@@ -8,15 +8,13 @@
 
 @dataclass
 class TransactionItem:
-    price_id: str | None
     price: Price
     quantity: int
     proration: Proration | None
 
     @staticmethod
     def from_dict(data: dict) -> TransactionItem:
         return TransactionItem(
-            price_id=data.get("price_id"),
             price=Price.from_dict(data["price"]),
             quantity=data["quantity"],
             proration=Proration.from_dict(data["proration"]) if data.get("proration") else None,