feat: Add transaction preview operations (#45)

* feat: Add transaction preview operations * fix: Fixed TransactionItemPreviewWithNonCatalogPrice.from_dict
PaddleHQ · Sep 27, 2024 · 5c9815d · 5c9815d
1 parent 5fa760f
commit 5c9815d
Show file tree

Hide file tree

Showing 18 changed files with 657 additions and 78 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -42,6 +42,7 @@ Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx
 - `AvailablePaymentMethods` - replaced by `PaymentMethodType`
 - Removed `receipt_data` from `CreateOneTimeCharge` and `PreviewOneTimeCharge` subscription operations
 - Removed `receipt_data` from `Transaction`
+- Removed `paddle_billing.Resources.Transactions.Operations.PreviewTransaction` - replaced by `PreviewTransactionByAddress` | `PreviewTransactionByCustomer` | `PreviewTransactionByIP`
 
 ## 0.2.2 - 2024-09-03
 

diff --git a/UPGRADING.md b/UPGRADING.md
@@ -35,6 +35,12 @@ Existing usages of `paddle_billing.Entities.Shared.TimePeriod` will need to be c
 - `paddle_billing.Notifications.Entities.Shared.AdjustmentProration`
 - `paddle_billing.Notifications.Entities.Transactions.TransactionProration`
 
+### 3. Transaction preview operation `PreviewTransaction` is removed
+
+Usage of `paddle_billing.Resources.Transactions.Operations.PreviewTransaction` should be replaced with one of:
+- `paddle_billing.Resources.Transactions.Operations.PreviewTransactionByAddress`
+- `paddle_billing.Resources.Transactions.Operations.PreviewTransactionByCustomer`
+- `paddle_billing.Resources.Transactions.Operations.PreviewTransactionByIP`
 
 ## v0.2.0
 

diff --git a/paddle_billing/Entities/Transactions/TransactionItemPreviewWithNonCatalogPrice.py b/paddle_billing/Entities/Transactions/TransactionItemPreviewWithNonCatalogPrice.py
@@ -15,7 +15,15 @@ class TransactionItemPreviewWithNonCatalogPrice:
     @staticmethod
     def from_dict(data: dict) -> TransactionItemPreviewWithNonCatalogPrice:
         return TransactionItemPreviewWithNonCatalogPrice(
-            price             = data['price'],
+            price             = TransactionItemPreviewWithNonCatalogPrice._create_price(data['price']),
             quantity          = data['quantity'],
             include_in_totals = data.get('include_in_totals'),
         )
+
+
+    @staticmethod
+    def _create_price(data: dict) -> TransactionNonCatalogPrice | TransactionNonCatalogPriceWithProduct:
+        if data.get('product') is not None:
+            return TransactionNonCatalogPriceWithProduct.from_dict(data)
+
+        return TransactionNonCatalogPrice.from_dict(data)
diff --git a/paddle_billing/Entities/Transactions/TransactionNonCatalogPriceWithProduct.py b/paddle_billing/Entities/Transactions/TransactionNonCatalogPriceWithProduct.py
@@ -33,7 +33,7 @@ def from_dict(data: dict) -> TransactionNonCatalogPriceWithProduct:
             tax_mode             = data['tax_mode'],
             unit_price           = Money.from_dict(data['unit_price']),
             quantity             = PriceQuantity.from_dict(data['quantity']),
-            product              = TransactionNonCatalogProduct.from_dict(data['product_id']),
+            product              = TransactionNonCatalogProduct.from_dict(data['product']),
             unit_price_overrides = [UnitPriceOverride.from_dict(item) for item in data['unit_price_overrides']],
             billing_cycle        = Duration.from_dict(data['billing_cycle']) if data.get('billing_cycle') else None,
             trial_period         = Duration.from_dict(data['trial_period'])  if data.get('trial_period')  else None,

diff --git a/...sactions/Operations/PreviewTransaction.py → ...Operations/PreviewTransactionByAddress.py b/...sactions/Operations/PreviewTransaction.py → ...Operations/PreviewTransactionByAddress.py
@@ -1,22 +1,17 @@
 from dataclasses import asdict, dataclass
 
 from paddle_billing.Undefined             import Undefined
-from paddle_billing.Entities.Shared       import AddressPreview, CollectionMode, CurrencyCode
+from paddle_billing.Entities.Shared       import AddressPreview, CurrencyCode
 from paddle_billing.Entities.Transactions import TransactionItemPreviewWithPriceId, TransactionItemPreviewWithNonCatalogPrice
 
 
-
 @dataclass
-class PreviewTransaction:
+class PreviewTransactionByAddress:
+    address:             AddressPreview
     items:               list[TransactionItemPreviewWithPriceId | TransactionItemPreviewWithNonCatalogPrice]
     customer_id:         str            | None | Undefined = Undefined()
-    address_id:          str            | None | Undefined = Undefined()
-    business_id:         str            | None | Undefined = Undefined()
     currency_code:       CurrencyCode          | Undefined = Undefined()
-    collection_mode:     CollectionMode        | Undefined = Undefined()
     discount_id:         str            | None | Undefined = Undefined()
-    customer_ip_address: str            | None | Undefined = Undefined()
-    address:             AddressPreview | None | Undefined = Undefined()
     ignore_trials:       bool                  | Undefined = Undefined()
 
 

diff --git a/paddle_billing/Resources/Transactions/Operations/PreviewTransactionByCustomer.py b/paddle_billing/Resources/Transactions/Operations/PreviewTransactionByCustomer.py
@@ -0,0 +1,20 @@
+from dataclasses import asdict, dataclass
+
+from paddle_billing.Undefined             import Undefined
+from paddle_billing.Entities.Shared       import CurrencyCode
+from paddle_billing.Entities.Transactions import TransactionItemPreviewWithPriceId, TransactionItemPreviewWithNonCatalogPrice
+
+
+@dataclass
+class PreviewTransactionByCustomer:
+    address_id:          str
+    customer_id:         str
+    items:               list[TransactionItemPreviewWithPriceId | TransactionItemPreviewWithNonCatalogPrice]
+    business_id:         str            | None | Undefined = Undefined()
+    currency_code:       CurrencyCode          | Undefined = Undefined()
+    discount_id:         str            | None | Undefined = Undefined()
+    ignore_trials:       bool                  | Undefined = Undefined()
+
+
+    def get_parameters(self) -> dict:
+        return asdict(self)
diff --git a/paddle_billing/Resources/Transactions/Operations/PreviewTransactionByIP.py b/paddle_billing/Resources/Transactions/Operations/PreviewTransactionByIP.py
@@ -0,0 +1,19 @@
+from dataclasses import asdict, dataclass
+
+from paddle_billing.Undefined             import Undefined
+from paddle_billing.Entities.Shared       import CurrencyCode
+from paddle_billing.Entities.Transactions import TransactionItemPreviewWithPriceId, TransactionItemPreviewWithNonCatalogPrice
+
+
+@dataclass
+class PreviewTransactionByIP:
+    customer_ip_address: str
+    items:               list[TransactionItemPreviewWithPriceId | TransactionItemPreviewWithNonCatalogPrice]
+    customer_id:         str            | None | Undefined = Undefined()
+    currency_code:       CurrencyCode          | Undefined = Undefined()
+    discount_id:         str            | None | Undefined = Undefined()
+    ignore_trials:       bool                  | Undefined = Undefined()
+
+
+    def get_parameters(self) -> dict:
+        return asdict(self)
diff --git a/paddle_billing/Resources/Transactions/Operations/__init__.py b/paddle_billing/Resources/Transactions/Operations/__init__.py
@@ -1,7 +1,9 @@
-from paddle_billing.Resources.Transactions.Operations.CreateTransaction     import CreateTransaction
-from paddle_billing.Resources.Transactions.Operations.ListTransactions      import ListTransactions
-from paddle_billing.Resources.Transactions.Operations.List.Includes         import Includes as TransactionIncludes
-from paddle_billing.Resources.Transactions.Operations.List.Origin           import Origin   as TransactionOrigin
-from paddle_billing.Resources.Transactions.Operations.PreviewTransaction    import PreviewTransaction
-from paddle_billing.Resources.Transactions.Operations.UpdateTransaction     import UpdateTransaction
-from paddle_billing.Resources.Transactions.Operations.GetTransactionInvoice import GetTransactionInvoice
+from paddle_billing.Resources.Transactions.Operations.CreateTransaction            import CreateTransaction
+from paddle_billing.Resources.Transactions.Operations.ListTransactions             import ListTransactions
+from paddle_billing.Resources.Transactions.Operations.List.Includes                import Includes as TransactionIncludes
+from paddle_billing.Resources.Transactions.Operations.List.Origin                  import Origin   as TransactionOrigin
+from paddle_billing.Resources.Transactions.Operations.PreviewTransactionByAddress  import PreviewTransactionByAddress
+from paddle_billing.Resources.Transactions.Operations.PreviewTransactionByCustomer import PreviewTransactionByCustomer
+from paddle_billing.Resources.Transactions.Operations.PreviewTransactionByIP       import PreviewTransactionByIP
+from paddle_billing.Resources.Transactions.Operations.UpdateTransaction            import UpdateTransaction
+from paddle_billing.Resources.Transactions.Operations.GetTransactionInvoice        import GetTransactionInvoice
diff --git a/paddle_billing/Resources/Transactions/TransactionsClient.py b/paddle_billing/Resources/Transactions/TransactionsClient.py
@@ -11,7 +11,9 @@
     CreateTransaction,
     ListTransactions,
     UpdateTransaction,
-    PreviewTransaction,
+    PreviewTransactionByAddress,
+    PreviewTransactionByCustomer,
+    PreviewTransactionByIP,
     TransactionIncludes,
     GetTransactionInvoice,
 )
@@ -77,7 +79,7 @@ def update(self, transaction_id: str, operation: UpdateTransaction) -> Transacti
         return Transaction.from_dict(parser.get_data())
 
 
-    def preview(self, operation: PreviewTransaction) -> TransactionPreview:
+    def preview(self, operation: PreviewTransactionByAddress | PreviewTransactionByCustomer | PreviewTransactionByIP) -> TransactionPreview:
         self.response = self.client.post_raw('/transactions/preview', operation.get_parameters())
         parser        = ResponseParser(self.response)
 

diff --git a/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_address_basic.json b/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_address_basic.json
@@ -0,0 +1,13 @@
+{
+  "address": {
+    "postal_code": "12345",
+    "country_code": "US"
+  },
+  "items": [
+    {
+      "quantity": 1,
+      "price_id": "pri_01he5kxqey1k8ankgef29cj4bv",
+      "include_in_totals": true
+    }
+  ]
+}
diff --git a/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_address_full.json b/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_address_full.json
@@ -0,0 +1,70 @@
+{
+  "address": {
+    "postal_code": "12345",
+    "country_code": "US"
+  },
+  "customer_id": "ctm_01h844q4mznqpgqgm6evgw1w63",
+  "currency_code": "USD",
+  "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3",
+  "ignore_trials": true,
+  "items": [
+    {
+      "quantity": 20,
+      "price": {
+        "description": "Annual (per seat)",
+        "name": "Annual (per seat)",
+        "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
+        "billing_cycle": {
+          "interval": "year",
+          "frequency": 1
+        },
+        "trial_period": null,
+        "tax_mode": "account_setting",
+        "unit_price": {
+          "amount": "30000",
+          "currency_code": "USD"
+        },
+        "unit_price_overrides": [],
+        "quantity": {
+          "minimum": 10,
+          "maximum": 999
+        },
+        "custom_data": null
+      },
+      "include_in_totals": true
+    },
+    {
+      "quantity": 20,
+      "price": {
+        "description": "Annual (per seat)",
+        "name": "Annual (per seat)",
+        "product": {
+          "name": "Analytics addon",
+          "description": "Some Description",
+          "tax_category": "standard",
+          "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
+          "custom_data": {
+            "key": "value"
+          }
+        },
+        "billing_cycle": {
+          "interval": "year",
+          "frequency": 1
+        },
+        "trial_period": null,
+        "tax_mode": "account_setting",
+        "unit_price": {
+          "amount": "30000",
+          "currency_code": "USD"
+        },
+        "unit_price_overrides": [],
+        "quantity": {
+          "minimum": 10,
+          "maximum": 999
+        },
+        "custom_data": null
+      },
+      "include_in_totals": true
+    }
+  ]
+}
diff --git a/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_customer_basic.json b/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_customer_basic.json
@@ -0,0 +1,11 @@
+{
+  "address_id": "add_01hv8h6jj90jjz0d71m6hj4r9z",
+  "customer_id": "ctm_01h844q4mznqpgqgm6evgw1w63",
+  "items": [
+    {
+      "quantity": 1,
+      "price_id": "pri_01he5kxqey1k8ankgef29cj4bv",
+      "include_in_totals": true
+    }
+  ]
+}
diff --git a/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_customer_full.json b/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_customer_full.json
@@ -0,0 +1,68 @@
+{
+  "address_id": "add_01hv8h6jj90jjz0d71m6hj4r9z",
+  "customer_id": "ctm_01h844q4mznqpgqgm6evgw1w63",
+  "business_id": "biz_01hv8j0z17hv4ew8teebwjmfcb",
+  "currency_code": "USD",
+  "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3",
+  "ignore_trials": true,
+  "items": [
+    {
+      "quantity": 20,
+      "price": {
+        "description": "Annual (per seat)",
+        "name": "Annual (per seat)",
+        "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
+        "billing_cycle": {
+          "interval": "year",
+          "frequency": 1
+        },
+        "trial_period": null,
+        "tax_mode": "account_setting",
+        "unit_price": {
+          "amount": "30000",
+          "currency_code": "USD"
+        },
+        "unit_price_overrides": [],
+        "quantity": {
+          "minimum": 10,
+          "maximum": 999
+        },
+        "custom_data": null
+      },
+      "include_in_totals": true
+    },
+    {
+      "quantity": 20,
+      "price": {
+        "description": "Annual (per seat)",
+        "name": "Annual (per seat)",
+        "product": {
+          "name": "Analytics addon",
+          "description": "Some Description",
+          "tax_category": "standard",
+          "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
+          "custom_data": {
+            "key": "value"
+          }
+        },
+        "billing_cycle": {
+          "interval": "year",
+          "frequency": 1
+        },
+        "trial_period": null,
+        "tax_mode": "account_setting",
+        "unit_price": {
+          "amount": "30000",
+          "currency_code": "USD"
+        },
+        "unit_price_overrides": [],
+        "quantity": {
+          "minimum": 10,
+          "maximum": 999
+        },
+        "custom_data": null
+      },
+      "include_in_totals": true
+    }
+  ]
+}
diff --git a/...ions/_fixtures/request/preview_basic.json → ...fixtures/request/preview_by_ip_basic.json b/...ions/_fixtures/request/preview_basic.json → ...fixtures/request/preview_by_ip_basic.json
@@ -1,4 +1,5 @@
 {
+  "customer_ip_address": "203.0.113.0",
   "items": [
     {
       "quantity": 1,

diff --git a/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_ip_full.json b/tests/Functional/Resources/Transactions/_fixtures/request/preview_by_ip_full.json
@@ -0,0 +1,67 @@
+{
+  "customer_ip_address": "203.0.113.0",
+  "customer_id": "ctm_01h844q4mznqpgqgm6evgw1w63",
+  "currency_code": "USD",
+  "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3",
+  "ignore_trials": true,
+  "items": [
+    {
+      "quantity": 20,
+      "price": {
+        "description": "Annual (per seat)",
+        "name": "Annual (per seat)",
+        "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
+        "billing_cycle": {
+          "interval": "year",
+          "frequency": 1
+        },
+        "trial_period": null,
+        "tax_mode": "account_setting",
+        "unit_price": {
+          "amount": "30000",
+          "currency_code": "USD"
+        },
+        "unit_price_overrides": [],
+        "quantity": {
+          "minimum": 10,
+          "maximum": 999
+        },
+        "custom_data": null
+      },
+      "include_in_totals": true
+    },
+    {
+      "quantity": 20,
+      "price": {
+        "description": "Annual (per seat)",
+        "name": "Annual (per seat)",
+        "product": {
+          "name": "Analytics addon",
+          "description": "Some Description",
+          "tax_category": "standard",
+          "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
+          "custom_data": {
+            "key": "value"
+          }
+        },
+        "billing_cycle": {
+          "interval": "year",
+          "frequency": 1
+        },
+        "trial_period": null,
+        "tax_mode": "account_setting",
+        "unit_price": {
+          "amount": "30000",
+          "currency_code": "USD"
+        },
+        "unit_price_overrides": [],
+        "quantity": {
+          "minimum": 10,
+          "maximum": 999
+        },
+        "custom_data": null
+      },
+      "include_in_totals": true
+    }
+  ]
+}