in_app_purchase.hpp

Go to the documentation of this file.

#pragma once
 
// pulp::events::IapClient — host-overridable in-app purchase seam.
//
// Pulp does not ship a production billing, marketplace, or entitlement
// layer. This API gives hosts a small testable seam they can replace with
// product-specific StoreKit / Microsoft Store / Play Billing code while the
// built-in backend reports `Unavailable` everywhere.
//
// Supported operations:
//   * Product lookup: `request_products(skus, callback)` resolves an SKU list
//     into `Product` records (title / description / localized price).
//   * Purchase: `purchase(sku, callback)` initiates a purchase flow and
//     reports the resulting `Purchase` (state + transaction id + receipt).
//   * Restore: `restore(callback)` re-issues previously-completed purchases
//     so the user can recover entitlements on a new device.
//   * Observer: `set_observer(callback)` registers a single sink that fires
//     whenever the backend resolves a purchase asynchronously (out-of-band
//     transactions, subscription renewals, family-sharing grants).
//
// Not currently implemented by Pulp's built-in backend:
//   * Real StoreKit2 wiring on Apple platforms (sandbox round-trip).
//   * Microsoft Store SDK / StoreContext wiring on Windows.
//   * Google Play Billing on Android.
//   * Server-side receipt validation helpers.
//   * Subscription-specific surfaces (auto-renew status, grace periods,
//     promotional offers).
//
// Built-in behavior:
//   * All platforms default to the stub backend unless a host or test installs
//     another `IapClient` with `install_iap_backend()`.
//   * The stub returns `is_available() == false`, `backend_id() == "none"`,
//     and every operation reports `Unavailable` / empty result.
//   * Production billing stays host-owned so Pulp remains MIT-clean and avoids
//     app-store-specific policy, packaging, and receipt-validation choices.
 
#include <cstdint>
#include <functional>
#include <memory>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::events {

enum class PurchaseState {
    Unknown,        
    Purchasing,     
    Purchased,      
    Restored,       
    Failed,         
    Cancelled,      
    Deferred,       
    Unavailable,    
};

enum class ProductLookupStatus {
    Ok,             
    PartiallyOk,    
    Failed,         
    Unavailable,    
};

struct Product {
    std::string sku;                 
    std::string title;               
    std::string description;         
    std::string price_formatted;     
    std::string price_currency_code; 
    double price_amount = 0.0;       
    bool is_subscription = false;    
};

struct ProductLookupResult {
    ProductLookupStatus status = ProductLookupStatus::Unavailable;
    std::vector<Product> products;
    std::vector<std::string> unknown_skus; 
    std::string error;                     
};

struct Purchase {
    std::string sku;            
    PurchaseState state = PurchaseState::Unknown;
    std::string transaction_id; 
    std::string receipt;        
    std::string error;          
};
 
using ProductLookupCallback = std::function<void(const ProductLookupResult&)>;
using PurchaseCallback = std::function<void(const Purchase&)>;
using RestoreCallback = std::function<void(const std::vector<Purchase>&)>;
using PurchaseObserver = std::function<void(const Purchase&)>;

class IapClient {
public:
    static IapClient& instance();
 
    virtual ~IapClient() = default;

    virtual bool is_available() const = 0;

    virtual std::string backend_id() const = 0;

    virtual void request_products(const std::vector<std::string>& skus,
                                  ProductLookupCallback callback) = 0;

    virtual void purchase(const std::string& sku, PurchaseCallback callback) = 0;

    virtual void restore(RestoreCallback callback) = 0;

    virtual void set_observer(PurchaseObserver observer) = 0;

    virtual bool finish_transaction(const std::string& transaction_id) = 0;
 
protected:
    IapClient() = default;
    IapClient(const IapClient&) = delete;
    IapClient& operator=(const IapClient&) = delete;
};
 
} // namespace pulp::events