SyntaxCircus.RevenueCat.Maui 0.1.4

SyntaxCircus.RevenueCat.Maui

Client-side RevenueCat helpers for MAUI apps, built on top of Kebechet.Maui.RevenueCat.InAppBilling (the vendor SDK binding — not reimplemented here). Covers SDK initialization, identity sync on login, offering-to-DTO mapping, and a purchase/restore orchestrator.

For backend-side RevenueCat integration (webhook verification, REST clients), see SyntaxCircus.RevenueCat.

No support guaranteed. Published as-is and maintained on a best-effort basis. Issues and PRs are welcome, but there's no SLA — fork it or vendor what you need if that's not enough.

Targets

net10.0-android and net10.0-ios only, matching the vendor SDK's proven real-world coverage. Add maccatalyst/windows yourself if you've verified Kebechet.Maui.RevenueCat.InAppBilling supports them for your use case.

What this library does

Quick start

1. Register the service

// MauiProgram.cs
builder.Services.AddRevenueCatMaui(builder.Configuration); // binds "RevenueCat", registers IRevenueCatBilling

{
  "RevenueCat": {
    "AndroidApiKey": "goog_...",
    "IosApiKey": "appl_..."
  }
}

2. Initialize the SDK early

// App.xaml.cs — initialize once, early in the app lifecycle
protected override void OnStart()
{
    RevenueCatInitializer.TryInitialize(_billing, _options.Value);
    base.OnStart();
}

For test hosts or other non-mobile entry points, you can also choose the platform explicitly:

RevenueCatInitializer.TryInitialize(_billing, _options.Value, RevenueCatPlatform.Android);

Or supply your own key resolver:

RevenueCatInitializer.TryInitialize(_billing, _options.Value, options => options.IosApiKey);

These are the public (publishable) per-platform keys from the RevenueCat dashboard — safe to ship inside the app binary, distinct from the server-side secret key SyntaxCircus.RevenueCat uses.

If your app's user id is already known at startup (e.g. the user is already signed in), pass it along so RevenueCat initializes directly with that id instead of creating an anonymous user you'd otherwise alias later via SyncLoginAsync:

RevenueCatInitializer.TryInitialize(_billing, _options.Value, appUserId: userId);

Common flows

Identity sync

Point RevenueCat's app_user_id at your own user id as soon as you know it (e.g. after login), so purchases and the TRANSFER webhook event correctly re-associate across reinstalls and new devices:

await RevenueCatIdentitySync.SyncLoginAsync(billing, userId, logger, ct);

Failures are logged and swallowed — this is best-effort, not something worth failing app startup over.

Call SyncLogoutAsync at sign-out to detach the app_user_id and return RevenueCat to an anonymous identity — same best-effort swallow behavior as SyncLoginAsync:

await RevenueCatIdentitySync.SyncLogoutAsync(billing, logger, ct);

Products

IReadOnlyList<RevenueCatProduct> products =
    await RevenueCatOfferingsMapper.GetCurrentProductsAsync(billing, ct: ct);

Purchases and restore

RevenueCatPurchaseResult result =
    await RevenueCatPurchaseOrchestrator.PurchaseAsync(billing, productIdentifier, logger, ct);

if (result.Success)
{
    // record result.TransactionId / result.AppUserId against your own backend here
}
else if (result.WasCancelled)
{
    // user-initiated cancellation, not an error
}

If you need custom package selection logic, use the resolver overload of PurchaseAsync(...).

RevenueCatPurchaseResult customResult =
    await RevenueCatPurchaseOrchestrator.PurchaseAsync(
        billing,
        productIdentifier,
        logger,
        (packages, id) => packages.FirstOrDefault(p => p.Identifier == id || p.Product.Sku == id),
        ct);

RevenueCatPurchaseResult restoreResult =
    await RevenueCatPurchaseOrchestrator.RestoreAsync(billing, userId, logger, ct);

PurchaseAsync and RestoreAsync only own the store interaction — recording a successful purchase against your own backend (subscriber verification, entitlement grants, etc.) is deliberately left to the caller, the same split SyntaxCircus.RevenueCat's webhook reader uses on the backend side.

A failed RevenueCatPurchaseResult also carries ErrorStatus — the vendor SDK's typed PurchaseErrorStatus — alongside the human-readable ErrorMessage, so you can switch on specific failure modes (network error, payment pending, etc.) instead of string-matching:

switch (result.ErrorStatus)
{
    case PurchaseErrorStatus.NetworkError:
        // offer a retry
        break;
    case PurchaseErrorStatus.PaymentPendingError:
        // tell the user the payment is still settling
        break;
}

Customer info & entitlements

RevenueCatCustomerInfo customerInfo = await RevenueCatCustomerInfoReader.GetAsync(billing, ct);
bool isPro = RevenueCatCustomerInfoReader.IsEntitled(customerInfo, "pro");

This is a convenience for perceived responsiveness only, not a source of truth. Client-reported entitlement info can be stale (the device hasn't synced yet) or spoofed (a jailbroken/rooted device can lie to the SDK). Use it for immediate UI feedback (e.g. showing a "Pro" badge without waiting on a network round trip) — always verify server-side, via SyntaxCircus.RevenueCat's webhook handling and subscriber verification, before actually granting access to paid functionality.

Payment eligibility

Check before showing a purchase button (e.g. the device may be blocked by parental controls or a region restriction):

if (await RevenueCatPaymentEligibility.CanMakePaymentsAsync(billing, ct))
{
    // show the purchase button
}

Subscriber attributes

RevenueCatSubscriberAttributes.SetEmail(billing, email);
RevenueCatSubscriberAttributes.SetDisplayName(billing, displayName);
RevenueCatSubscriberAttributes.SetPhoneNumber(billing, phoneNumber);
RevenueCatSubscriberAttributes.SetAttributes(billing, new Dictionary<string, string> { ["plan"] = "annual" });

Subscription management URL

string? managementUrl = await RevenueCatManagementUrl.GetAsync(billing, ct);

Unlike the identity-sync helpers, failures here are not swallowed — this is typically used to populate a "Manage Subscription" link, so a thrown exception is more useful to the caller than a silently missing or broken link.

Behavior notes

• PurchaseAsync returns WasCancelled = true for a user-cancelled store flow instead of throwing.
• RestoreAsync logs and returns a failure result for non-cancellation errors.
• The default TryInitialize(billing, options) method keeps the existing compile-time Android/iOS behavior.
• The explicit RevenueCatPlatform and resolver overloads are the non-breaking escape hatches for tests and custom hosts.
• SyncLogoutAsync mirrors SyncLoginAsync's best-effort swallow-and-log behavior (cancellation still propagates).
• RevenueCatManagementUrl.GetAsync does not swallow exceptions — like GetCurrentProductsAsync, it's a direct query and lets failures propagate to the caller.
• RevenueCatCustomerInfoReader.GetAsync and RevenueCatPaymentEligibility.CanMakePaymentsAsync also don't swallow exceptions — same direct-query behavior as RevenueCatManagementUrl.GetAsync.
• RevenueCatPurchaseResult.ErrorStatus is populated wherever the vendor SDK reports a typed PurchaseErrorStatus; it's null for outcomes that aren't a store error (e.g. "product not found") and for the thrown-exception fallback path in RestoreAsync.

Contributing

Issues and pull requests are welcome:

• Keep changes focused, with a clear description of the behavior change.
• Match the existing code style (see .editorconfig).
• Call out any breaking changes to the public API in your PR description.

License

MIT — see LICENSE.txt.