sjbillingclient 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

sjbillingclient/jclass/purchase.py

@@ -1,8 +1,16 @@
-from jnius import JavaClass, MetaJavaClass, JavaStaticMethod
+from jnius import JavaClass, MetaJavaClass, JavaStaticMethod, JavaMethod
 
-__all__ = ("PendingPurchasesParams",)
+__all__ = ("PendingPurchasesParams", "PendingPurchasesParamsBuilder")
 
 
 class PendingPurchasesParams(JavaClass, metaclass=MetaJavaClass):
     __javaclass__ = f"com/android/billingclient/api/PendingPurchasesParams"
     newBuilder = JavaStaticMethod("()Lcom/android/billingclient/api/PendingPurchasesParams$Builder;")
+
+
+class PendingPurchasesParamsBuilder(JavaClass, metaclass=MetaJavaClass):
+    __javaclass__ = f"com/android/billingclient/api/PendingPurchasesParams$Builder"
+
+    build = JavaMethod("()Lcom/android/billingclient/api/PendingPurchasesParams;")
+    enableOneTimeProducts = JavaMethod("()Lcom/android/billingclient/api/PendingPurchasesParams$Builder;")
+    enablePrepaidPlans = JavaMethod("()Lcom/android/billingclient/api/PendingPurchasesParams$Builder;")

sjbillingclient/jclass/queryproduct.py

@@ -1,4 +1,4 @@
-from jnius import JavaClass, MetaJavaClass, JavaStaticMethod
+from jnius import JavaClass, MetaJavaClass, JavaStaticMethod, JavaMethod
 
 __all__ = ("QueryProductDetailsParams", "QueryProductDetailsParamsProduct")
 
@@ -11,3 +11,11 @@ class QueryProductDetailsParams(JavaClass, metaclass=MetaJavaClass):
 class QueryProductDetailsParamsProduct(JavaClass, metaclass=MetaJavaClass):
     __javaclass__ = f"com/android/billingclient/api/QueryProductDetailsParams$Product"
     newBuilder = JavaStaticMethod("()Lcom/android/billingclient/api/QueryProductDetailsParams$Product$Builder;")
+
+
+class QueryProductDetailsResult(JavaClass, metaclass=MetaJavaClass):
+    __javaclass__ = f"com/android/billingclient/api/QueryProductDetailsResult"
+    create = JavaStaticMethod("(Ljava/util/List;Ljava/util/List;)"
+                              "Lcom/android/billingclient/api/QueryProductDetailsResult;")
+    getProductDetailsList = JavaMethod("()Ljava/util/List;")
+    getUnfetchedProductList = JavaMethod("()Ljava/util/List;")

sjbillingclient/jinterface/product.py

@@ -10,6 +10,7 @@ class ProductDetailsResponseListener(PythonJavaClass):
     def __init__(self, callback):
         self.callback = callback
 
-    @java_method("(Lcom/android/billingclient/api/BillingResult;Ljava/util/List;)V")
-    def onProductDetailsResponse(self, billing_result, product_details_list):
-        self.callback(billing_result, product_details_list)
+    @java_method("(Lcom/android/billingclient/api/BillingResult;"
+                 "Lcom/android/billingclient/api/QueryProductDetailsResult;)V")
+    def onProductDetailsResponse(self, billing_result, product_details_result):
+        self.callback(billing_result, product_details_result)

sjbillingclient/tools/__init__.py

@@ -1,9 +1,48 @@
+"""
+A Python wrapper for the Google Play Billing Library that facilitates in-app purchases and subscriptions.
+
+This module provides a high-level interface to interact with Google Play's billing system through
+the BillingClient class. It handles various billing operations including:
+
+- Establishing and managing billing service connections
+- Querying product details for in-app purchases and subscriptions
+- Processing purchase flows
+- Handling consumption of purchased items
+- Managing purchase acknowledgments
+
+Key Features:
+- Asynchronous billing operations
+- Support for both one-time purchases (INAPP) and subscriptions (SUBS)
+- Product details querying with price formatting
+- Purchase flow management
+- Consumption and acknowledgment handling
+
+Example:
+    ```python
+    def on_purchases_updated(billing_result, purchases):
+        # Handle purchase updates
+        pass
+
+    client = BillingClient(on_purchases_updated)
+    client.start_connection(
+        on_billing_setup_finished=lambda result: print("Billing setup complete"),
+        on_billing_service_disconnected=lambda: print("Billing service disconnected")
+    )
+    ```
+
+Dependencies:
+    - jnius: For Java/Android interop
+    - android.activity: For access to the Android activity context
+"""
+
+from typing import List, Dict, Optional
 from jnius import autoclass, JavaException
 from sjbillingclient.jclass.acknowledge import AcknowledgePurchaseParams
 from sjbillingclient.jclass.billing import BillingClient as SJBillingClient, ProductType, ProductDetailsParams, \
     BillingFlowParams
 from android.activity import _activity as activity  # noqa
 from sjbillingclient.jclass.consume import ConsumeParams
+from sjbillingclient.jclass.purchase import PendingPurchasesParams
 from sjbillingclient.jclass.queryproduct import QueryProductDetailsParams, QueryProductDetailsParamsProduct
 from sjbillingclient.jinterface.acknowledge import AcknowledgePurchaseResponseListener
 from sjbillingclient.jinterface.billing import BillingClientStateListener
@@ -11,115 +50,365 @@ from sjbillingclient.jinterface.consume import ConsumeResponseListener
 from sjbillingclient.jinterface.product import ProductDetailsResponseListener
 from sjbillingclient.jinterface.purchases import PurchasesUpdatedListener
 
+ERROR_NO_BASE_PLAN = "You don't have a base plan"
+ERROR_NO_BASE_PLAN_ID = "You don't have a base plan id"
+ERROR_INVALID_PRODUCT_TYPE = "product_type not supported. Must be one of `ProductType.SUBS`, `ProductType.INAPP`"
+
 
 class BillingClient:
-    __billing_client = None
-    __purchase_update_listener = None
-    __billing_client_state_listener = None
-    __product_details_response_listener = None
-    __consume_response_listener = None
-    __acknowledge_purchase_response_listener = None
-
-    def __init__(self, on_purchases_updated):
-        self.__purchase_update_listener = PurchasesUpdatedListener(on_purchases_updated)
+    """
+    Provides methods and functionality to manage billing operations, including starting and terminating
+    billing connections, querying product details, launching billing flows, consuming purchases, and
+    acknowledging purchases.
+
+    This class acts as a wrapper around the Google Play Billing Library, simplifying the process of in-app
+    purchases and subscriptions by integrating higher-level methods for essential billing features.
+
+    :ivar __billing_client: The main billing client that interacts with the Google Play Billing Library.
+    :type __billing_client: SJBillingClient
+    :ivar __purchase_update_listener: Listener for purchase updates and processing purchase-related events.
+    :type __purchase_update_listener: PurchasesUpdatedListener
+    :ivar __billing_client_state_listener: Listener for tracking the state of the billing client connection.
+    :type __billing_client_state_listener: BillingClientStateListener | None
+    :ivar __product_details_response_listener: Listener that handles the response for product details queries.
+    :type __product_details_response_listener: ProductDetailsResponseListener | None
+    :ivar __consume_response_listener: Listener handling responses for consumption requests.
+    :type __consume_response_listener: ConsumeResponseListener | None
+    :ivar __acknowledge_purchase_response_listener: Listener handling responses for acknowledging purchases.
+    :type __acknowledge_purchase_response_listener: AcknowledgePurchaseResponseListener | None
+    """
+
+    def __init__(
+            self,
+            on_purchases_updated,
+            enable_one_time_products: bool = True,
+            enable_prepaid_plans: bool = False
+    ) -> None:
+        """
+        Initializes an instance of the class with the given purchase update callback.
 
+        :param on_purchases_updated: A callback function that will be triggered when purchases
+            are updated. This function typically handles updates to purchases such as
+            processing the results or actions related to the purchases.
+        :type on_purchases_updated: callable
+        """
+        self.__billing_client_state_listener = None
+        self.__product_details_response_listener = None
+        self.__consume_response_listener = None
+        self.__acknowledge_purchase_response_listener = None
+
+        self.__purchase_update_listener = PurchasesUpdatedListener(on_purchases_updated)
+        pending_purchase_params = PendingPurchasesParams.newBuilder()
+        if enable_one_time_products:
+            pending_purchase_params.enableOneTimeProducts()
+        if enable_prepaid_plans:
+            pending_purchase_params.enablePrepaidPlans()
         self.__billing_client = (
             SJBillingClient.newBuilder(activity.context)
             .setListener(self.__purchase_update_listener)
-            .enablePendingPurchases()
+            .enablePendingPurchases(pending_purchase_params.build())
             .build()
         )
 
-    def start_connection(self, on_billing_setup_finished, on_billing_service_disconnected):
+    def start_connection(self, on_billing_setup_finished, on_billing_service_disconnected) -> None:
+        """
+        Starts a connection with the billing client and initializes the billing
+        client state listener. This method sets up a listener to handle billing
+        setup finished and billing service disconnection callbacks.
+
+        :param on_billing_setup_finished: A callable that will be invoked when
+            the billing setup has finished.
+        :param on_billing_service_disconnected: A callable that will be invoked
+            when the billing service gets disconnected.
+        :return: None
+        """
         self.__billing_client_state_listener = BillingClientStateListener(
             on_billing_setup_finished,
             on_billing_service_disconnected
         )
         self.__billing_client.startConnection(self.__billing_client_state_listener)
 
-    def end_connection(self):
+    def end_connection(self) -> None:
+        """
+        Ends the connection with the billing client.
+
+        This method terminates the active connection with the billing client
+        by calling its `endConnection` method. It ensures proper cleanup of
+        resources related to the billing client.
+
+        :return: None
+        """
         self.__billing_client.endConnection()
 
-    def query_product_details_async(self, product_type, products_ids: list, on_product_details_response):
-        List = autoclass("java.util.List")
-        queryProductDetailsParams = (
-            QueryProductDetailsParams.newBuilder()
-            .setProductList(
-                List.of(*[
-                    QueryProductDetailsParamsProduct.newBuilder()
-                    .setProductId(product_id)
-                    .setProductType(product_type)
-                    .build()
-                    for product_id in products_ids
-                ])
-            )
-            .build()
-        )
+    def query_product_details_async(self, product_type: str, products_ids: List[str],
+                                    on_product_details_response) -> None:
+        """
+        Queries product details asynchronously for a given list of product IDs and product type.
+
+        This function utilizes the provided product details response callback to handle the
+        resulting response from the query.
+
+        :param product_type: The type of the products to be queried (e.g., "inapp" or "subs").
+        :param products_ids: A list of product IDs to query details for.
+        :param on_product_details_response: A callback function that is triggered when the
+                                             product details query is complete.
+        :return: None
+        """
+        JavaList = autoclass("java.util.List")
+        product_list = [
+            self._build_product_params(product_id, product_type)
+            for product_id in products_ids
+        ]
+
+        params = (QueryProductDetailsParams.newBuilder()
+                  .setProductList(JavaList.of(*product_list))
+                  .build())
 
         self.__product_details_response_listener = ProductDetailsResponseListener(on_product_details_response)
+        self.__billing_client.queryProductDetailsAsync(params, self.__product_details_response_listener)
 
-        self.__billing_client.queryProductDetailsAsync(
-            queryProductDetailsParams,
-            self.__product_details_response_listener
-        )
+    @staticmethod
+    def _build_product_params(product_id: str, product_type: str):
+        """
+        Builds product parameters using the provided product ID and product type.
+
+        This is a static helper method designed to construct and return an object
+        representing the parameters for querying product details. It uses a builder
+        pattern for constructing the product details object.
+
+        :param product_id: The unique identifier of the product.
+        :type product_id: str
+        :param product_type: The type/category of the product (e.g., consumable, subscription).
+        :type product_type: str
+        :return: A constructed product details parameter object.
+        :rtype: QueryProductDetailsParamsProduct
+        """
+        return (QueryProductDetailsParamsProduct.newBuilder()
+                .setProductId(product_id)
+                .setProductType(product_type)
+                .build())
 
     @staticmethod
-    def get_product_details(product_details, product_type):
-        details = []
+    def get_unfetched_product(unfetched_product) -> Dict:
+        """
+        Retrieves detailed product information for an unfetched product.
+
+        This function takes an object representing an unfetched product and extracts
+        important details such as the product ID, product type, and status code.
+        The extracted details are then returned as a dictionary.
+
+        :param unfetched_product: The product object that has not yet been fetched.
+            Must provide methods to retrieve product ID, type, and status code.
+        :type unfetched_product: Any
+        :return: A dictionary containing detailed information about the unfetched
+            product, including its ID, type, and status code.
+        :rtype: Dict
+        """
+        return {
+            "product_id": unfetched_product.getProductId(),
+            "product_type": unfetched_product.getProductType(),
+            "status_code": unfetched_product.getStatusCode(),
+        }
+
+    def get_product_details(self, product_details, product_type: str) -> List[Dict]:
+        """
+        Retrieves the details of a product based on the provided product type. The function processes
+        different types of products, such as subscriptions and in-app purchases, and returns the corresponding
+        details.
+
+        If the product type is not recognized, an exception is raised.
+
+        :param product_details: The details of the product to process.
+        :param product_type: The type of the product. It can either be 'SUBS' for subscriptions or 'INAPP' for in-app purchases.
+        :return: A list of dictionaries containing the processed product details.
+        :rtype: List[Dict]
+        :raises Exception: If the specified product type is invalid.
+        """
         if product_type == ProductType.SUBS:
-            offer_details = product_details.getSubscriptionOfferDetails()
-            for offer in offer_details:
-                pricing_phase = offer.getPricingPhases().getPricingPhaseList().get(0)
-                details.append({
-                    "product_id": product_details.getProductId(),
-                    "formatted_price": pricing_phase.getFormattedPrice(),
-                    "price_amount_micros": pricing_phase.getPriceAmountMicros,
-                    "price_currency_code": pricing_phase.getPriceCurrencyCode(),
-                })
-            return details
+            return self._get_subscription_details(product_details)
         elif product_type == ProductType.INAPP:
-            offer_details = product_details.getOneTimePurchaseOfferDetails()
-            details.append({
-                "product_id": product_details.getProductId(),
-                "formatted_price": offer_details.getFormattedPrice(),
-                "price_amount_micros": offer_details.getPriceAmountMicros,
-                "price_currency_code": offer_details.getPriceCurrencyCode(),
-            })
-            return details
-        raise Exception("product_type not supported. Must be one of `ProductType.SUBS`, `ProductType.INAPP`")
-
-    def launch_billing_flow(self, product_details: list, offer_token: str = None):
-
-        product_details_param_list = []
-
-        for product_detail in product_details:
-            params = ProductDetailsParams.newBuilder()
-            params.setProductDetails(product_detail)
-            if product_detail.getProductType() == ProductType.SUBS:
-                if not offer_token:
-                    offer_list = product_detail.getSubscriptionOfferDetails()
-                    if not offer_list or offer_list.isEmpty():
-                        raise JavaException("You don't have a base plan")
-                    base_plan_id = offer_list.get(0).getBasePlanId()
-                    offer_token = offer_list.get(0).getOfferToken()
-                    if not base_plan_id:
-                        raise JavaException("You don't have a base plan id")
-                    params.setOfferToken(offer_token)
-                else:
-                    params.setOfferToken(offer_token)
-            product_details_param_list.append(params.build())
-        List = autoclass("java.util.List")
-
-        billing_flow_params = (
-            BillingFlowParams.newBuilder()
-            .setProductDetailsParamsList(List.of(*product_details_param_list))
-            .build()
-        )
+            return self._get_inapp_purchase_details(product_details)
+        raise Exception(ERROR_INVALID_PRODUCT_TYPE)
+
+    def _get_subscription_details(self, product_details) -> List[Dict]:
+        """
+        Retrieves subscription details from the provided product details by parsing its
+        subscription offer details and related pricing phases. The extracted details
+        include product ID, formatted price, price amount in micros, and the currency code.
+
+        :param product_details: Contains information about the product including
+            subscription offers and pricing.
+        :type product_details: Any
+        :return: List of dictionaries, each containing subscription details such as
+            product ID, formatted price, price amount in micros, and currency code.
+        :rtype: List[Dict]
+        """
+        details = []
+        offer_details = product_details.getSubscriptionOfferDetails()
+        for offer in offer_details:
+            pricing_phase = offer.getPricingPhases().getPricingPhaseList().get(0)
+            details.append(self._create_product_detail_dict(
+                product_details.getProductId(),
+                pricing_phase.getFormattedPrice(),
+                pricing_phase.getPriceAmountMicros,
+                pricing_phase.getPriceCurrencyCode()
+            ))
+        return details
+
+    def _get_inapp_purchase_details(self, product_details) -> List[Dict]:
+        """
+        Retrieve and construct in-app purchase product details.
+
+        This function takes product details from an in-app purchase API response and
+        constructs a list of dictionaries containing formatted product details. Each
+        dictionary includes details such as product ID, formatted price, raw price
+        amount, and currency code. Only one-time purchase offer details are supported.
+
+        :param product_details: Product details object containing information about
+            an in-app purchase product.
+        :type product_details: Any
+        :return: A list of dictionaries representing constructed product details
+            based on the provided product information.
+        :rtype: List[Dict]
+        """
+        offer_details = product_details.getOneTimePurchaseOfferDetails()
+        return [self._create_product_detail_dict(
+            product_details.getProductId(),
+            offer_details.getFormattedPrice(),
+            offer_details.getPriceAmountMicros,
+            offer_details.getPriceCurrencyCode()
+        )]
+
+    @staticmethod
+    def _create_product_detail_dict(product_id: str, formatted_price: str,
+                                    price_amount_micros, price_currency_code: str) -> Dict:
+        """
+        Creates a dictionary containing product details.
+
+        This method generates and returns a dictionary that encapsulates product
+        details such as the product identifier, formatted price, price in micros,
+        and the price currency code.
+
+        :param product_id: The unique identifier for the product.
+        :type product_id: str
+        :param formatted_price: The human-readable price of the product.
+        :type formatted_price: str
+        :param price_amount_micros: The price of the product in micro-units.
+        :type price_amount_micros: int
+        :param price_currency_code: The currency code associated with the product price.
+        :type price_currency_code: str
+        :return: A dictionary holding the product details.
+        :rtype: Dict
+        """
+        return {
+            "product_id": product_id,
+            "formatted_price": formatted_price,
+            "price_amount_micros": price_amount_micros,
+            "price_currency_code": price_currency_code,
+        }
+
+    def launch_billing_flow(self, product_details: List, offer_token: Optional[str] = None):
+        """
+        Initiates the in-app billing flow for the specified product details and an optional
+        offer token. The method constructs billing flow parameters using the provided product
+        details and triggers the billing process.
+
+        :param product_details: A list of product detail objects representing the items
+                                available for purchase through the billing flow.
+        :param offer_token: Optional string representing a unique token to identify
+                            specific offers for the product being purchased.
+        :return: An integer identifier returned by the billing client representing the
+                 result of the billing flow launch attempt.
+        """
+        JavaList = autoclass("java.util.List")
+        product_params_list = [
+            self._create_product_params(product_detail, offer_token)
+            for product_detail in product_details
+        ]
+        print(product_params_list)
+
+        billing_flow_params = (BillingFlowParams.newBuilder()
+                               .setProductDetailsParamsList(JavaList.of(*product_params_list))
+                               .build())
+
+        return self.__billing_client.launchBillingFlow(activity, billing_flow_params)
 
-        billing_result = self.__billing_client.launchBillingFlow(activity, billing_flow_params)
-        return billing_result
+    def _create_product_params(self, product_detail, offer_token: Optional[str]):
+        """
+        Creates and builds product parameters for a given product detail and optional offer token.
+
+        This method initializes the `ProductDetailsParams` through its builder,
+        populates it with the provided product detail, and conditionally sets the
+        offer token if the product type is a subscription (SUBS). Once all
+        necessary values are set, it builds and returns the params.
+
+        :param product_detail: The product details used for generating the params.
+        :type product_detail: ProductDetails
+
+        :param offer_token: Optional token specific to the offer for the subscription
+            product. Will be resolved internally if not provided and the product type
+            is a subscription.
+        :type offer_token: Optional[str]
+
+        :return: A fully constructed `ProductDetailsParams` object populated
+            with the input product data and offer token, if applicable.
+        :rtype: ProductDetailsParams
+        """
+        params = ProductDetailsParams.newBuilder()
+        params.setProductDetails(product_detail)
+
+        if product_detail.getProductType() == ProductType.SUBS:
+            offer_token = self._resolve_offer_token(product_detail, offer_token)
+            params.setOfferToken(offer_token)
+
+        return params.build()
+
+    @staticmethod
+    def _resolve_offer_token(product_detail, offer_token: Optional[str]) -> str:
+        """
+        Resolves the offer token for a given product detail. If the provided offer token is
+        not `None`, it returns the same. Otherwise, it determines the offer token using
+        the subscription offer details from the product detail. Raises exceptions if the
+        required information is missing.
+
+        :param product_detail: The product detail object containing subscription offer
+            details.
+        :type product_detail: Any
+        :param offer_token: A string value representing the offer token if provided,
+            or None to attempt resolving it from the product detail.
+        :type offer_token: Optional[str]
+        :return: The resolved offer token as a string.
+        :rtype: str
+        :raises JavaException: When no base plan or base plan ID is found in the
+            subscription offer details.
+        """
+        if offer_token:
+            return offer_token
+
+        offer_list = product_detail.getSubscriptionOfferDetails()
+        if not offer_list or offer_list.isEmpty():
+            raise JavaException(ERROR_NO_BASE_PLAN)
+
+        base_plan_id = offer_list.get(0).getBasePlanId()
+        if not base_plan_id:
+            raise JavaException(ERROR_NO_BASE_PLAN_ID)
+
+        return offer_list.get(0).getOfferToken()
 
     def consume_async(self, purchase, on_consume_response):
+        """
+        Consumes a given purchase asynchronously using the billing client. The method takes
+        a purchase object and a callback function that is triggered upon the consumption's
+        completion. This process involves creating appropriate consume parameters and invoking
+        the consume operation on the billing client.
+
+        :param purchase: The purchase object to consume.
+        :type purchase: Purchase
+        :param on_consume_response: The callback to execute upon completion of the consumption
+            process. This should handle the result of the consumption.
+        :type on_consume_response: Callable
+        :return: None
+        """
         consume_params = (
             ConsumeParams.newBuilder()
             .setPurchaseToken(purchase.getPurchaseToken())
@@ -129,6 +418,20 @@ class BillingClient:
         self.__billing_client.consumeAsync(consume_params, self.__consume_response_listener)
 
     def acknowledge_purchase(self, purchase_token, on_acknowledge_purchase_response):
+        """
+        Acknowledges a purchase using the provided purchase token. This method communicates
+        with the billing client to confirm the completion of a purchase, ensuring its validity
+        and acknowledgment. A callback function is triggered once the acknowledgment process
+        is complete.
+
+        :param purchase_token: The token representing the purchase to be acknowledged.
+        :type purchase_token: str
+        :param on_acknowledge_purchase_response: A callback function to handle the
+            response of the acknowledgment process. It is triggered upon completion.
+        :type on_acknowledge_purchase_response: Callable[[AcknowledgePurchaseResponse], None]
+
+        :return: None
+        """
         acknowledge_purchase_params = (
             AcknowledgePurchaseParams.newBuilder()
             .setPurchaseToken(purchase_token)

sjbillingclient-0.2.0.dist-info/METADATA

@@ -0,0 +1,507 @@
+Metadata-Version: 2.1
+Name: sjbillingclient
+Version: 0.2.0
+Summary: 
+Author: Kenechukwu Akubue
+Author-email: kengoon19@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: poetry-core (>=2.1.3,<3.0.0)
+Requires-Dist: pyjnius (>=1.6.1,<2.0.0)
+Description-Content-Type: text/markdown
+
+# SJBillingClient (Google Play Billing SDK for Python)
+
+<!-- GitAds-Verify: 71CCWMQSMVD67LS4WF4N44EXISSL2UTQ -->
+## GitAds Sponsored
+[![Sponsored by GitAds](https://gitads.dev/v1/ad-serve?source=simplejnius/sj-android-billingclient@github)](https://gitads.dev/v1/ad-track?source=simplejnius/sj-android-billingclient@github)
+
+## Overview
+
+SJBillingClient is a Python wrapper for the Google Play Billing Library that facilitates in-app purchases and subscriptions in Android applications. It provides a high-level, Pythonic interface to interact with Google Play's billing system, making it easier to implement and manage in-app purchases in Python-based Android apps (like those built with Kivy/Python-for-Android).
+
+### Key Features
+
+- **Simplified Billing Integration**: Easy-to-use Python API for Google Play Billing
+- **Asynchronous Operations**: Non-blocking billing operations
+- **Comprehensive Purchase Management**: Support for querying, purchasing, consuming, and acknowledging products
+- **Product Types Support**: Handles both one-time purchases (INAPP) and subscriptions (SUBS)
+- **Detailed Product Information**: Access to formatted prices, currency codes, and other product details
+
+## Requirements
+
+- Python 3.9+
+- pyjnius 1.6.1+
+- Android application with Google Play Billing Library (version 8.0.0 recommended)
+
+## Installation
+
+```shell
+# Using pip
+pip install sjbillingclient
+
+# In Buildozer (add to buildozer.spec)
+requirements = sjbillingclient
+android.gradle_dependencies = com.android.billingclient:billing:8.0.0
+```
+
+## Quick Start
+
+Here's a basic example of how to initialize the billing client and start a connection:
+
+```python
+from sjbillingclient.tools import BillingClient
+from sjbillingclient.jclass.billing import ProductType, BillingResponseCode
+
+# Define callback for purchase updates
+def on_purchases_updated(billing_result, is_null, purchases):
+    if billing_result.getResponseCode() == BillingResponseCode.OK:
+        if not is_null:
+            for purchase in purchases:
+                print(f"Purchase: {purchase.getProducts().get(0)}")
+                # Handle purchase here
+
+# Create billing client
+client = BillingClient(on_purchases_updated)
+
+# Start connection
+client.start_connection(
+    on_billing_setup_finished=lambda result: print(f"Billing setup complete: {result.getResponseCode()}"),
+    on_billing_service_disconnected=lambda: print("Billing service disconnected")
+)
+```
+
+## Usage Examples
+
+### Querying Product Details
+
+```python
+from sjbillingclient.tools import BillingClient
+from sjbillingclient.jclass.billing import ProductType, BillingResponseCode
+
+def on_product_details_response(billing_result, product_details_list):
+    if billing_result.getResponseCode() == BillingResponseCode.OK:
+        if product_details_list and not product_details_list.isEmpty():
+            # Process product details
+            for i in range(product_details_list.size()):
+                product_detail = product_details_list.get(i)
+                print(f"Product: {product_detail.getProductId()}")
+
+                # Get formatted details
+                details = client.get_product_details(product_detail, ProductType.INAPP)
+                for detail in details:
+                    print(f"Price: {detail['formatted_price']}")
+
+# Query product details
+client.query_product_details_async(
+    product_type=ProductType.INAPP,
+    products_ids=["product_id_1", "product_id_2"],
+    on_product_details_response=on_product_details_response
+)
+```
+
+### Launching a Purchase Flow
+
+```python
+from sjbillingclient.tools import BillingClient
+from sjbillingclient.jclass.billing import ProductType, BillingResponseCode
+
+def on_product_details_response(billing_result, product_details_list):
+    if billing_result.getResponseCode() == BillingResponseCode.OK:
+        if product_details_list and not product_details_list.isEmpty():
+            # Launch billing flow with the first product
+            product_detail = product_details_list.get(0)
+            result = client.launch_billing_flow([product_detail])
+            print(f"Launch billing flow result: {result.getResponseCode()}")
+
+# Query product details and then launch purchase
+client.query_product_details_async(
+    product_type=ProductType.INAPP,
+    products_ids=["product_id"],
+    on_product_details_response=on_product_details_response
+)
+```
+
+### Consuming a Purchase
+
+```python
+from sjbillingclient.tools import BillingClient
+from sjbillingclient.jclass.billing import BillingResponseCode
+
+def on_consume_response(billing_result, purchase_token):
+    print(f"Consume result: {billing_result.getResponseCode()}")
+    if billing_result.getResponseCode() == BillingResponseCode.OK:
+        print(f"Successfully consumed: {purchase_token}")
+
+# Consume a purchase
+client.consume_async(purchase, on_consume_response)
+```
+
+### Acknowledging a Purchase
+
+```python
+from sjbillingclient.tools import BillingClient
+from sjbillingclient.jclass.billing import BillingResponseCode
+
+def on_acknowledge_purchase_response(billing_result):
+    print(f"Acknowledge result: {billing_result.getResponseCode()}")
+    if billing_result.getResponseCode() == BillingResponseCode.OK:
+        print("Successfully acknowledged purchase")
+
+# Acknowledge a purchase
+client.acknowledge_purchase(purchase.getPurchaseToken(), on_acknowledge_purchase_response)
+```
+
+### Kivy Integration Example
+
+Here's a complete example of integrating SJBillingClient with a Kivy application:
+
+#### Python Code (main.py)
+
+```python
+from os.path import join, dirname, basename
+from kivy.app import App
+from kivy.lang import Builder
+from kivy.uix.screenmanager import ScreenManager, Screen
+from sjbillingclient.jclass.billing import BillingResponseCode, ProductType
+from sjbillingclient.tools import BillingClient
+
+Builder.load_file(join(dirname(__file__), basename(__file__).split(".")[0] + ".kv"))
+
+
+class HomeScreen(Screen):
+    """
+    A screen that demonstrates Google Play Billing integration with Kivy.
+
+    This screen provides functionality to make in-app purchases and subscriptions
+    using the Google Play Billing Library through the SJBillingClient wrapper.
+
+    Attributes:
+        billing_client (BillingClient): The client used to interact with Google Play Billing.
+    """
+    billing_client = None
+
+    def support(self):
+        """
+        Initializes the billing client and starts a connection to the Google Play Billing service.
+
+        This method is called when the user wants to make a purchase or subscription.
+        If a billing client already exists, it ends the connection before creating a new one.
+        """
+        if self.billing_client:
+            self.billing_client.end_connection()
+
+        self.billing_client = BillingClient(on_purchases_updated=self.on_purchases_updated)
+        self.billing_client.start_connection(
+            on_billing_setup_finished=self.on_billing_setup_finished,
+            on_billing_service_disconnected=lambda: print("disconnected")
+        )
+
+    def on_purchases_updated(self, billing_result, null, purchases):
+        """
+        Callback method that is called when purchases are updated.
+
+        This method handles the result of a purchase flow, either acknowledging
+        a subscription or consuming a one-time purchase.
+
+        Args:
+            billing_result: The result of the billing operation.
+            null: Boolean indicating if the purchases list is null.
+            purchases: List of purchases that were updated.
+        """
+        if billing_result.getResponseCode() == BillingResponseCode.OK and not null:
+            for purchase in purchases:
+                if self.ids.subscribe.active:
+                    self.billing_client.acknowledge_purchase(
+                        purchase_token=purchase.getPurchaseToken(),
+                        on_acknowledge_purchase_response=self.on_acknowledge_purchase_response
+                    )
+                else:
+                    self.billing_client.consume_async(purchase, self.on_consume_response)
+        print(billing_result.getResponseCode(), billing_result.getDebugMessage())
+
+    def on_acknowledge_purchase_response(self, billing_result):
+        """
+        Callback method that is called when a purchase acknowledgement is complete.
+
+        Args:
+            billing_result: The result of the acknowledgement operation.
+        """
+        print(billing_result.getDebugMessage())
+        if billing_result.getResponseCode() == BillingResponseCode.OK:
+            self.toast("Thank you for subscribing to buy us a cup of coffee! monthly")
+
+    def on_consume_response(self, billing_result):
+        """
+        Callback method that is called when a purchase consumption is complete.
+
+        Args:
+            billing_result: The result of the consumption operation.
+        """
+        if billing_result.getResponseCode() == BillingResponseCode.OK:
+            self.toast("Thank you for buying us a cup of coffee!")
+
+    def on_product_details_response(self, billing_result, product_details_result):
+        """
+        Callback method that is called when product details are retrieved.
+
+        This method processes the product details and launches the billing flow.
+
+        Args:
+            billing_result: The result of the product details query.
+            product_details_result: The result containing product details and unfetched products.
+        """
+        product_details_list = product_details_result.getProductDetailsList()
+        unfetched_product_list = product_details_result.getUnfetchedProductList()
+
+        if billing_result.getResponseCode() == BillingResponseCode.OK:
+            for product_details in product_details_list:
+                self.billing_client.get_product_details(
+                    product_details,
+                    ProductType.SUBS if self.ids.subscribe.active else ProductType.INAPP)
+            for unfetched_product in unfetched_product_list:
+                print(self.billing_client.get_unfetched_product(unfetched_product))
+            self.billing_client.launch_billing_flow(product_details=product_details_list)
+
+    def on_billing_setup_finished(self, billing_result):
+        """
+        Callback method that is called when the billing setup is complete.
+
+        This method queries product details if the billing setup was successful.
+
+        Args:
+            billing_result: The result of the billing setup operation.
+        """
+        product_id = self.ids.btn.product_id
+        if billing_result.getResponseCode() == BillingResponseCode.OK:
+            self.billing_client.query_product_details_async(
+                product_type=ProductType.SUBS if self.ids.subscribe else ProductType.INAPP,
+                products_ids=[product_id],
+                on_product_details_response=self.on_product_details_response,
+            )
+
+    def toast(self, message):
+        """
+        Display a toast message.
+
+        This is a simple implementation that just prints the message.
+        In a real app, you would use platform-specific toast functionality.
+
+        Args:
+            message: The message to display.
+        """
+        # Implementation of toast message (platform specific)
+        print(message)
+
+
+class BillingApp(App):
+    """
+    Main application class for the SJBillingClient demo.
+
+    This class sets up the application and creates the screen manager
+    with the HomeScreen.
+    """
+    def build(self):
+        """
+        Build the application UI.
+
+        Returns:
+            ScreenManager: The root widget of the application.
+        """
+        # Create screen manager
+        sm = ScreenManager()
+        sm.add_widget(HomeScreen(name='home'))
+        return sm
+
+
+if __name__ == '__main__':
+    BillingApp().run()
+```
+
+#### Kivy Layout File (main.kv)
+
+```kivy
+<HomeScreen>:
+    BoxLayout:
+        orientation: 'vertical'
+        padding: '20dp'
+        spacing: '10dp'
+
+        Label:
+            text: 'SJBillingClient Demo'
+            font_size: '24sp'
+            size_hint_y: None
+            height: '50dp'
+
+        BoxLayout:
+            orientation: 'horizontal'
+            size_hint_y: None
+            height: '50dp'
+
+            Label:
+                text: 'Subscribe'
+                size_hint_x: 0.5
+
+            CheckBox:
+                id: subscribe
+                size_hint_x: 0.5
+                active: False
+
+        Button:
+            id: btn
+            text: 'Buy Coffee'
+            product_id: 'coffee_product_id'
+            size_hint_y: None
+            height: '60dp'
+            on_release: root.support()
+
+        Widget:
+            # Spacer
+```
+
+This example demonstrates:
+
+1. A `HomeScreen` class that extends `Screen` and handles all billing operations
+2. A `BillingApp` class that sets up the Kivy application and screen manager
+3. A Kivy layout file that defines the UI with:
+   - A checkbox to toggle between one-time purchase and subscription
+   - A button to initiate the purchase flow
+
+The `support` method is called when the button is pressed, which initializes the billing client and starts the connection. The various callback methods handle different stages of the billing process, including:
+- Handling purchase updates with `on_purchases_updated`
+- Acknowledging subscription purchases with `acknowledge_purchase`
+- Consuming one-time purchases with `consume_async`
+- Processing product details with `on_product_details_response`, including handling unfetched products
+- Querying product details with `query_product_details_async`
+
+This example is designed to be copy-and-paste runnable, with no need for the user to add or remove anything to test it.
+
+## API Reference
+
+### BillingClient
+
+The main class for interacting with Google Play Billing.
+
+#### Constructor
+
+- `__init__(on_purchases_updated, enable_one_time_products=True, enable_prepaid_plans=False)`: 
+  - Initializes a new BillingClient instance
+  - `on_purchases_updated`: Callback function that will be triggered when purchases are updated
+  - `enable_one_time_products`: Boolean to enable one-time products (default: True)
+  - `enable_prepaid_plans`: Boolean to enable prepaid plans (default: False)
+
+#### Connection Methods
+
+- `start_connection(on_billing_setup_finished, on_billing_service_disconnected)`: 
+  - Starts a connection with the billing client
+  - `on_billing_setup_finished`: Callback when billing setup is complete
+  - `on_billing_service_disconnected`: Callback when billing service is disconnected
+
+- `end_connection()`: 
+  - Ends the connection with the billing client
+
+#### Product Details Methods
+
+- `query_product_details_async(product_type, products_ids, on_product_details_response)`: 
+  - Queries product details asynchronously
+  - `product_type`: Type of products (INAPP or SUBS)
+  - `products_ids`: List of product IDs to query
+  - `on_product_details_response`: Callback for product details response
+
+- `get_product_details(product_details, product_type)`: 
+  - Gets formatted product details
+  - `product_details`: Product details object
+  - `product_type`: Type of product (INAPP or SUBS)
+  - Returns a list of dictionaries with product details
+
+- `get_unfetched_product(unfetched_product)`: 
+  - Gets details about an unfetched product
+  - `unfetched_product`: Unfetched product object
+  - Returns a dictionary with product ID, type, and status code
+
+#### Purchase Methods
+
+- `launch_billing_flow(product_details, offer_token=None)`: 
+  - Launches the billing flow for purchase
+  - `product_details`: List of product details objects
+  - `offer_token`: Optional token for subscription offers
+
+- `consume_async(purchase, on_consume_response)`: 
+  - Consumes a purchase asynchronously
+  - `purchase`: Purchase object to consume
+  - `on_consume_response`: Callback for consume response
+
+- `acknowledge_purchase(purchase_token, on_acknowledge_purchase_response)`: 
+  - Acknowledges a purchase
+  - `purchase_token`: Token of the purchase to acknowledge
+  - `on_acknowledge_purchase_response`: Callback for acknowledge response
+
+### PendingPurchasesParams
+
+Parameters for handling pending purchases.
+
+#### Methods
+
+- `newBuilder()`: Creates a new builder for PendingPurchasesParams
+- `build()`: Builds the PendingPurchasesParams object
+- `enableOneTimeProducts()`: Enables one-time products
+- `enablePrepaidPlans()`: Enables prepaid plans
+
+### QueryProductDetailsParams
+
+Parameters for querying product details.
+
+#### Methods
+
+- `newBuilder()`: Creates a new builder for QueryProductDetailsParams
+- `setProductList(product_list)`: Sets the list of products to query
+- `build()`: Builds the QueryProductDetailsParams object
+
+### QueryProductDetailsResult
+
+Result of a product details query.
+
+#### Methods
+
+- `getProductDetailsList()`: Gets the list of product details
+- `getUnfetchedProductList()`: Gets the list of unfetched products
+
+### ProductType
+
+Constants for product types:
+
+- `ProductType.INAPP`: One-time purchases
+- `ProductType.SUBS`: Subscriptions
+
+### BillingResponseCode
+
+Constants for billing response codes:
+
+- `BillingResponseCode.OK`: Success (0)
+- `BillingResponseCode.USER_CANCELED`: User canceled (1)
+- `BillingResponseCode.SERVICE_UNAVAILABLE`: Service unavailable (2)
+- `BillingResponseCode.BILLING_UNAVAILABLE`: Billing unavailable (3)
+- `BillingResponseCode.ITEM_UNAVAILABLE`: Item unavailable (4)
+- `BillingResponseCode.DEVELOPER_ERROR`: Developer error (5)
+- `BillingResponseCode.ERROR`: General error (6)
+- `BillingResponseCode.ITEM_ALREADY_OWNED`: Item already owned (7)
+- `BillingResponseCode.ITEM_NOT_OWNED`: Item not owned (8)
+- `BillingResponseCode.SERVICE_DISCONNECTED`: Service disconnected (10)
+- `BillingResponseCode.FEATURE_NOT_SUPPORTED`: Feature not supported (12)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Author
+
+Kenechukwu Akubue <kengoon19@gmail.com>
+

{sjbillingclient-0.1.3.dist-info → sjbillingclient-0.2.0.dist-info}/RECORD

@@ -3,15 +3,15 @@ sjbillingclient/jclass/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3
 sjbillingclient/jclass/acknowledge.py,sha256=FeaiOsIR2_WxJQC56gaeCtOPTEWb7Dz7AuWE6VYVMJI,358
 sjbillingclient/jclass/billing.py,sha256=Hkk_yvnPQel0Fw_SFVdhP3unmhRkWNDVUa4RM1qhzdY,5499
 sjbillingclient/jclass/consume.py,sha256=Hh8sLGosVvs22NhdQRudFc_NP_ahvrJSJdJTM-_nLBQ,310
-sjbillingclient/jclass/purchase.py,sha256=sLEihOLiyvwDIWBhHSpmMj1swNr4RJizceQOKmBqHM4,346
-sjbillingclient/jclass/queryproduct.py,sha256=0JkaC9E1Juxl79t7gJCUfrQntWiLWjfScSEI-mss8Lg,671
+sjbillingclient/jclass/purchase.py,sha256=trFRSDHdMUPZsAxdyU7HuChT0qicDO-EjfPp9d6unrA,844
+sjbillingclient/jclass/queryproduct.py,sha256=Akuxy3fO1djerVPidqmjUclKVtIDmlaNJxZDbyUWOUw,1115
 sjbillingclient/jinterface/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sjbillingclient/jinterface/acknowledge.py,sha256=OG5GWYO1TXfC7nscn8pPjsrdm2BGOCASRCzscKfyPFM,522
 sjbillingclient/jinterface/billing.py,sha256=lwBGN8Xe0Qbc1DCRSShrhL8oGqRbjugwrgNspEK-nmc,1265
 sjbillingclient/jinterface/consume.py,sha256=DiugwpRreoVLpPjeHSkNMgncg5f3HnIBCUh0OIyrWhI,524
-sjbillingclient/jinterface/product.py,sha256=rtlc-4hxToCa3buwNp8QufMYkoiUZHp_YXKeE-QZZyk,562
+sjbillingclient/jinterface/product.py,sha256=kr_oPhRnQd0xbZItFLtACjBhZsnUV8q-kooqG_biVPs,627
 sjbillingclient/jinterface/purchases.py,sha256=BG6xF3H-35_XhiRr2kWDb1jzsxJ-hIw-jaEi-uSkTmY,574
-sjbillingclient/tools/__init__.py,sha256=SSq-BgkGt-4ws517TWL5aabaT2gS2pjb38AMXY-OKwU,6458
-sjbillingclient-0.1.3.dist-info/METADATA,sha256=uCryoWp-Phbmm_J5yf4hfoSJjztXuFRNv8-f7YUyYBg,721
-sjbillingclient-0.1.3.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-sjbillingclient-0.1.3.dist-info/RECORD,,
+sjbillingclient/tools/__init__.py,sha256=PqsUr6tIBdAUN4NNKvWR3aRdNQ-ZN84MAzkBKcm6sik,21127
+sjbillingclient-0.2.0.dist-info/METADATA,sha256=DICVzpmYPMuAUP9Co-yyBchoBMpT-oOOOTokqC6zAwY,18430
+sjbillingclient-0.2.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+sjbillingclient-0.2.0.dist-info/RECORD,,

sjbillingclient-0.1.3.dist-info/METADATA

@@ -1,29 +0,0 @@
-Metadata-Version: 2.1
-Name: sjbillingclient
-Version: 0.1.3
-Summary: 
-Author: Kenechukwu Akubue
-Author-email: kengoon19@gmail.com
-Requires-Python: >=3.9,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: pyjnius (>=1.6.1,<2.0.0)
-Description-Content-Type: text/markdown
-
-# SJBillingClient (Google Play Billing SDK for Python)
-
-
-## Installation
-```shell
-# pip
-
-pip install sjbillingclient
-
-# buildozer
-requirements=sjbillingclient
-android.gradle_dependencies=com.android.billingclient:billing:7.1.1
-```
-