solvapay 0.1.0.dev4__py3-none-any.whl

solvapay/paywall/state.py

@@ -0,0 +1,371 @@
+"""Paywall state and copy, ported from ``@solvapay/server``'s ``paywall-state.ts``.
+
+Classifies a limits response into the recovery the customer needs, and writes
+the gate and nudge messages. Inputs and outputs are JSON objects with the
+API's camelCase keys. The conformance suite checks the result against the
+TypeScript SDK, message text included.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any, Literal
+
+from .._js import UNDEFINED, coalesce, get, num_str, number, to_locale_string, truthy
+from ..money import credits_to_display_minor_units, format_minor
+
+CHECKOUT_SESSION_TTL_MINUTES = 15
+
+PaywallStateKind = Literal[
+    "activation_required",
+    "topup_required",
+    "upgrade_required",
+    "limit_reached",
+    "reactivation_required",
+]
+PaywallNextAction = Literal["activate", "topup", "checkout", "account"]
+
+Json = dict[str, Any]
+
+
+def credit_signals(limits: Json | None) -> Json:
+    """Coalesces the two credit-balance channels; nested ``balance`` wins."""
+    if not limits:
+        return {
+            "creditBalance": UNDEFINED,
+            "creditsPerCall": UNDEFINED,
+            "shortfallCredits": UNDEFINED,
+            "remainingCalls": UNDEFINED,
+            "isCreditBased": False,
+        }
+    balance = get(limits, "balance")
+    credit_balance = coalesce(get(balance, "creditBalance"), get(limits, "creditBalance"))
+    credits_per_call = coalesce(get(balance, "creditsPerUnit"), get(limits, "creditsPerUnit"))
+    is_credit_based = credit_balance is not UNDEFINED or credits_per_call is not UNDEFINED
+    shortfall: Any = UNDEFINED
+    if credit_balance is not UNDEFINED and credits_per_call is not UNDEFINED:
+        shortfall = max(0, number(credits_per_call) - number(credit_balance))
+        shortfall = _same_kind(shortfall, credits_per_call, credit_balance)
+    remaining_calls: Any = UNDEFINED
+    if get(balance, "remainingUnits") is not UNDEFINED:
+        remaining_calls = balance["remainingUnits"]
+    elif (
+        credit_balance is not UNDEFINED
+        and credits_per_call is not UNDEFINED
+        and number(credits_per_call) > 0
+    ):
+        remaining_calls = math.floor(number(credit_balance) / number(credits_per_call))
+    elif number(get(limits, "remaining")) >= 0:
+        remaining_calls = get(limits, "remaining")
+    return {
+        "creditBalance": credit_balance,
+        "creditsPerCall": credits_per_call,
+        "shortfallCredits": shortfall,
+        "remainingCalls": remaining_calls,
+        "isCreditBased": is_credit_based,
+    }
+
+
+def _same_kind(value: float, *sources: Any) -> float | int:
+    """Arithmetic on JSON ints stays an int, as it prints in JavaScript."""
+    if all(isinstance(s, int) and not isinstance(s, bool) for s in sources if s is not None):
+        return int(value)
+    return value
+
+
+def next_action_for(kind: PaywallStateKind) -> PaywallNextAction:
+    return {
+        "activation_required": "activate",
+        "topup_required": "topup",
+        "upgrade_required": "checkout",
+        "limit_reached": "checkout",
+        "reactivation_required": "account",
+    }[kind]  # type: ignore[return-value]
+
+
+def _active_plan_ref(limits: Json) -> Any:
+    ref = coalesce(get(limits, "planRef"), get(limits, "plan"))
+    return ref if truthy(ref) and len(ref) > 0 else UNDEFINED
+
+
+def classify_paywall_state(limits: Json | None) -> PaywallStateKind:
+    """Which recovery the customer needs. Same precedence as the TypeScript SDK."""
+    if not limits:
+        return "upgrade_required"
+    reason = get(limits, "paywallReason")
+    if get(limits, "activationRequired") is True or reason == "activation_required":
+        return "activation_required"
+    if reason == "limit_reached":
+        return "limit_reached"
+    if reason == "topup_required":
+        return "topup_required"
+    if get(limits, "needsTopUp") is True:
+        return "topup_required"
+
+    signals = credit_signals(limits)
+    balance, cost = signals["creditBalance"], signals["creditsPerCall"]
+    if signals["isCreditBased"]:
+        if balance is not UNDEFINED and cost is not UNDEFINED and number(balance) < number(cost):
+            return "topup_required"
+        if balance == 0 and not isinstance(balance, bool):
+            return "topup_required"
+        if cost is UNDEFINED and get(limits, "remaining") == 0:
+            return "topup_required"
+
+    if (truthy(get(limits, "purchaseRef")) or truthy(_active_plan_ref(limits))) and number(
+        get(limits, "remaining")
+    ) <= 0:
+        return "limit_reached"
+    if signals["isCreditBased"]:
+        return "topup_required"
+    if truthy(get(limits, "purchaseRef")):
+        return "limit_reached"
+    return "upgrade_required"
+
+
+def _format_credits(value: Any) -> str:
+    return to_locale_string(number(value))
+
+
+def _format_credits_with_money(credits: Any, gate: Json) -> str:
+    amount = _format_credits(credits)
+    peg = get(gate, "creditsPerMinorUnit")
+    currency = get(gate, "currency")
+    rate = get(gate, "displayExchangeRate")
+    # `rate != null` in the TypeScript: neither null nor undefined.
+    has_rate = rate is not None and rate is not UNDEFINED and number(rate) > 0
+    if truthy(peg) and number(peg) > 0 and truthy(currency) and has_rate:
+        minor = credits_to_display_minor_units(
+            credits=number(credits),
+            credits_per_minor_unit=number(peg),
+            display_exchange_rate=number(rate),
+            display_currency=currency,
+        )
+        if minor is not None:
+            return f"{amount} credits (~{format_minor(minor, currency)})"
+    return f"{amount} credits"
+
+
+def _is_free_meter(name: Any) -> bool:
+    return isinstance(name, str) and name.startswith("free-")
+
+
+def _meter_label(gate: Json) -> str:
+    name = get(gate, "meterName")
+    if not truthy(name):
+        return "units"
+    return re.sub(r"[_-]", " ", name)
+
+
+def _named_checkout_markdown(url: str, label: str = "Open checkout") -> str:
+    return f"[{label}]({url})"
+
+
+def link_label(name: str) -> str:
+    """Escapes markdown link-label delimiters: plan names are merchant-authored."""
+    return re.sub(r"([\[\]])", r"\\\1", name)
+
+
+def plan_ladder(gate: Json) -> str | None:
+    plans = coalesce(get(gate, "plans"), [])
+    plan_ref = get(gate, "planRef")
+    linkable = [
+        p
+        for p in plans
+        if isinstance(get(p, "checkoutUrl"), str)
+        and len(p["checkoutUrl"]) > 0
+        and get(p, "reference") != plan_ref
+    ]
+    linkable = sorted(linkable, key=lambda p: number(get(p, "price")))[:4]
+    if not linkable:
+        return None
+    links = " · ".join(
+        f"[{link_label(coalesce(get(p, 'name'), get(p, 'reference')))}]({p['checkoutUrl']})"
+        for p in linkable
+    )
+    return (
+        f"{links} (first link used closes the rest; "
+        f"links expire in {CHECKOUT_SESSION_TTL_MINUTES} minutes)"
+    )
+
+
+_VIEWER_TOOL = "account"
+
+
+def _call_viewer(view: str | None = None) -> str:
+    if view:
+        return f"call the `{_VIEWER_TOOL}` tool with view: '{view}'"
+    return f"call the `{_VIEWER_TOOL}` tool"
+
+
+def _capital(text: str) -> str:
+    return "C" + text[1:] if text.startswith("c") else text
+
+
+def _recover_clause(
+    url: str | None, verb: str, view: str | None = None, label: str = "Open checkout"
+) -> str:
+    if url:
+        return (
+            f" {_named_checkout_markdown(url, label)} to {verb} "
+            f"(expires in {CHECKOUT_SESSION_TTL_MINUTES} minutes), or {_call_viewer(view)}."
+        )
+    return f" {_capital(_call_viewer(view))}."
+
+
+def _has_active_plan(gate: Json) -> bool:
+    plan_ref = get(gate, "planRef")
+    return truthy(get(gate, "purchaseRef")) or (truthy(plan_ref) and len(plan_ref) > 0)
+
+
+def _auto_recharge_disabled(gate: Json) -> bool:
+    return get(get(gate, "autoRecharge"), "enabled") is False
+
+
+def build_gate_message(kind: PaywallStateKind, gate: Json) -> str:
+    """The gate message: names one recovery tool and inlines the checkout link."""
+    checkout_url = get(gate, "checkoutUrl")
+    url = checkout_url if truthy(checkout_url) and len(checkout_url) > 0 else None
+    ladder = plan_ladder(gate)
+
+    if kind == "limit_reached":
+        included = get(gate, "included")
+        if _is_free_meter(get(gate, "meterName")):
+            total = get(included, "total")
+            used_line = (
+                f"You've used all {num_str(total)} {_meter_label(gate)} for this period."
+                if total is not UNDEFINED
+                else f"You've used all {_meter_label(gate)} for this period."
+            )
+            switch_line = (
+                f" Pick a plan to keep going: {ladder}. "
+                f"{_capital(_call_viewer('account'))} for usage and recovery."
+                if ladder
+                else _recover_clause(url, "keep going", "checkout")
+            )
+            return f"{used_line}{switch_line}"
+        unit_price = get(gate, "unitPriceMinor")
+        currency = get(gate, "currency")
+        price = (
+            format_minor(number(unit_price), currency)
+            if unit_price is not None and unit_price is not UNDEFINED and truthy(currency)
+            else None
+        )
+        used_line = (
+            f"You've used {num_str(get(included, 'used'))} of "
+            f"{num_str(get(included, 'total'))} included {_meter_label(gate)} this period."
+            if truthy(included)
+            else "You've reached the included usage for this period."
+        )
+        next_line = f" The next call is {price}." if price else ""
+        plan_name = coalesce(get(gate, "planName"), "This plan")
+        credit_balance = get(gate, "creditBalance")
+        credits_per_call = get(gate, "creditsPerCall")
+        anti_trap = (
+            f" Adding credits will not help, because {plan_name} does not spend them."
+            if credit_balance is not UNDEFINED
+            and number(credit_balance) > 0
+            and (credits_per_call is UNDEFINED or credits_per_call == 0)
+            else ""
+        )
+        switch_line = (
+            f" Or switch plan: {ladder}. "
+            f"{_capital(_call_viewer('account'))} for usage and recovery."
+            if ladder
+            else _recover_clause(url, "continue", "checkout")
+        )
+        return f"{used_line}{next_line}{anti_trap}{switch_line}"
+
+    if kind == "activation_required":
+        return (
+            f"Your plan needs activation.{_recover_clause(url, 'activate', 'checkout')} "
+            "Or call `activate_plan` with a `planRef`."
+        )
+
+    if kind == "topup_required":
+        balance = get(gate, "creditBalance")
+        cost = get(gate, "creditsPerCall")
+        shortfall = get(gate, "shortfallCredits")
+        if UNDEFINED not in (balance, cost, shortfall):
+            have = _format_credits_with_money(balance, gate)
+            need = _format_credits_with_money(cost, gate)
+            lead = (
+                f"Out of credits for this call. Balance {have}; this call costs {need} — "
+                f"{_format_credits(shortfall)} short."
+            )
+        else:
+            lead = "Included usage is exhausted."
+        topup = _recover_clause(url, "add credits", "topup", "Add credits")
+        auto = (
+            f" Auto-recharge is off — {_call_viewer('account')} to turn it on "
+            "and avoid this next time."
+            if _auto_recharge_disabled(gate)
+            else ""
+        )
+        if ladder:
+            switch_line = f" Or switch plan: {ladder}."
+        elif _has_active_plan(gate):
+            switch_line = ""
+        else:
+            switch_line = f" Or {_call_viewer('checkout')} to pick a plan."
+        return f"{lead}{topup}{auto}{switch_line}"
+
+    if kind == "upgrade_required":
+        if ladder:
+            return (
+                f"You don't have an active plan for this tool. Pick a plan to use this tool: "
+                f"{ladder}, or {_call_viewer('checkout')}. "
+                f"{_capital(_call_viewer('account'))} for usage and recovery."
+            )
+        return (
+            "You don't have an active plan for this tool."
+            f"{_recover_clause(url, 'pick a plan', 'checkout')}"
+        )
+
+    return (
+        f"Your previous plan is no longer active. {_capital(_call_viewer('account'))} "
+        f"to reactivate it, or {_call_viewer('checkout')} to pick a new plan."
+    )
+
+
+def build_nudge_message(kind: PaywallStateKind, limits: Json | None) -> str:
+    """The softer message appended to a successful call that is near a limit."""
+    checkout_url = get(limits, "checkoutUrl")
+    url = checkout_url if truthy(checkout_url) and len(checkout_url) > 0 else None
+    visit = f", or {_named_checkout_markdown(url)}" if url else ""
+    signals = credit_signals(limits)
+    remaining = signals["remainingCalls"]
+    # `limits && …` in the TypeScript: any object, even an empty one, is truthy.
+    if kind == "topup_required" and limits is not None and not signals["isCreditBased"]:
+        kind = "limit_reached"
+
+    if kind == "topup_required":
+        if remaining == 0:
+            return (
+                "Heads up — 0 calls left — the next call needs a top-up. "
+                f"{_capital(_call_viewer('topup'))} to add more{visit}."
+            )
+        return (
+            "Heads up — running low on credits. "
+            f"{_capital(_call_viewer('topup'))} to add more{visit}."
+        )
+    if kind in ("upgrade_required", "limit_reached"):
+        if remaining == 0:
+            return (
+                "Heads up — 0 calls left — the next call needs a top-up. "
+                f"{_capital(_call_viewer('checkout'))} for more headroom{visit}."
+            )
+        return (
+            "Heads up — approaching your plan's limit this period. "
+            f"{_capital(_call_viewer('checkout'))} for more headroom{visit}."
+        )
+    if kind == "activation_required":
+        return (
+            "Heads up — this plan still needs activation. "
+            f"Call the `activate_plan` tool with a `planRef`{visit}."
+        )
+    return (
+        "Heads up — your plan is no longer active. "
+        f"{_capital(_call_viewer('account'))} to reactivate it{visit}."
+    )

solvapay/pricing.py

@@ -0,0 +1,281 @@
+"""Readers for a plan's ``options[]`` pricing, ported from ``@solvapay/core``'s
+``pricing-options.ts``.
+
+Every plan-shaped payload (a catalog plan, the frozen ``planSnapshot`` on a
+purchase) describes its pricing as an ordered list of ``options``, each with a
+``kind``. These helpers read that list structurally, as the TypeScript SDK
+does: an option kind this version does not know is skipped, never an error.
+Inputs are JSON objects with the API's camelCase keys.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, TypeGuard
+
+from ._js import UNDEFINED, coalesce, get, js_round
+
+Json = dict[str, Any]
+
+
+def _is_number(value: Any) -> TypeGuard[float]:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _options(priced: Any) -> list[Mapping[str, Any]]:
+    options = get(priced, "options")
+    if not isinstance(options, Sequence) or isinstance(options, str):
+        return []
+    return [option for option in options if isinstance(option, Mapping)]
+
+
+def _as_charge(option: Mapping[str, Any]) -> Json | None:
+    if option.get("kind") != "charge":
+        return None
+    per, amount, currency = option.get("per"), option.get("amountMinor"), option.get("currency")
+    if per not in ("flat", "unit", "seat"):
+        return None
+    if not _is_number(amount) or not isinstance(currency, str):
+        return None
+    charge: Json = {"per": per, "amountMinor": amount, "currency": currency}
+    if isinstance(option.get("meter"), str):
+        charge["meter"] = option["meter"]
+    if option.get("oneTime") is True:
+        charge["oneTime"] = True
+    return charge
+
+
+def charges(priced: Any) -> list[Json]:
+    """Every charge option on the plan, in wire order."""
+    return [c for c in (_as_charge(option) for option in _options(priced)) if c is not None]
+
+
+def headline_charges(priced: Any) -> list[Json]:
+    """The base flat charge in each currency, first seen first; setup fees excluded."""
+    flat = [charge for charge in charges(priced) if charge["per"] == "flat"]
+    base = [charge for charge in flat if not charge.get("oneTime")]
+    seen: set[str] = set()
+    out = []
+    for charge in base or flat:
+        key = charge["currency"].upper()
+        if key not in seen:
+            seen.add(key)
+            out.append(charge)
+    return out
+
+
+def per_unit_charge(priced: Any, meter: str | None = None) -> Json | None:
+    """The first ``per: 'unit'`` charge, optionally for one meter."""
+    unit = [charge for charge in charges(priced) if charge["per"] == "unit"]
+    if meter:
+        return next((charge for charge in unit if charge.get("meter") == meter), None)
+    return unit[0] if unit else None
+
+
+def billing_cycle(priced: Any) -> Json | None:
+    """``{"interval", "count"?}``, or None for a one-time or pure usage plan."""
+    for option in _options(priced):
+        if option.get("kind") != "billingCycle":
+            continue
+        interval, count = option.get("interval"), option.get("count")
+        if interval not in ("week", "month", "year"):
+            continue
+        cycle: Json = {"interval": interval}
+        if _is_number(count) and count > 1:
+            cycle["count"] = count
+        return cycle
+    return None
+
+
+def _as_tier(option: Mapping[str, Any]) -> Json | None:
+    if option.get("kind") != "tier":
+        return None
+    start, end, mode = option.get("from"), get(option, "to"), option.get("mode")
+    if not _is_number(start):
+        return None
+    if end is not None and not _is_number(end):
+        return None
+    if mode not in ("graduated", "volume"):
+        return None
+    embedded = option.get("charge")
+    if not isinstance(embedded, Mapping):
+        return None
+    charge = _as_charge({**embedded, "kind": "charge"})
+    if charge is None:
+        return None
+    return {"from": start, "to": end, "mode": mode, "charge": charge}
+
+
+def tier_bands(priced: Any, meter: str | None = None) -> list[Json]:
+    """The bands ``meter`` (else the first tiered meter) is priced in, by floor."""
+    tiers = [t for t in (_as_tier(option) for option in _options(priced)) if t is not None]
+    if not tiers:
+        return []
+    target = meter if meter is not None else tiers[0]["charge"].get("meter")
+    bands = [t for t in tiers if target is None or t["charge"].get("meter") == target]
+    return sorted(bands, key=lambda tier: tier["from"])
+
+
+def tier_meters(priced: Any) -> list[str]:
+    seen: list[str] = []
+    for option in _options(priced):
+        tier = _as_tier(option)
+        meter = tier["charge"].get("meter") if tier else None
+        if meter and meter not in seen:
+            seen.append(meter)
+    return seen
+
+
+def usage_rate(priced: Any, meter: str | None = None) -> Json | None:
+    """What one metered unit costs: the per-unit charge, else the first paying band.
+    ``tiered`` is True when later bands may cost differently (present it as a floor)."""
+    charge = per_unit_charge(priced, meter)
+    if charge and charge["amountMinor"] > 0:
+        return {**charge, "tiered": False}
+    paying = [band for band in tier_bands(priced, meter) if band["charge"]["amountMinor"] > 0]
+    if paying:
+        return {**paying[0]["charge"], "tiered": len(paying) > 1}
+    return {**charge, "tiered": False} if charge else None
+
+
+def trial_days(priced: Any) -> Any:
+    """Free trial length in days, or None."""
+    for option in _options(priced):
+        if option.get("kind") != "trial":
+            continue
+        days = option.get("days")
+        if _is_number(days) and days > 0:
+            return days
+    return None
+
+
+def _first_limit(priced: Any, meter: str | None = None) -> Json | None:
+    for option in _options(priced):
+        if option.get("kind") != "limit":
+            continue
+        if meter and option.get("meter") != meter:
+            continue
+        if not _is_number(option.get("cap")):
+            continue
+        name = option.get("meter")
+        return {"cap": option["cap"], "meter": name if isinstance(name, str) and name else None}
+    return None
+
+
+def included_units(priced: Any, meter: str | None = None) -> Any:
+    """Included units from the limit option. ``0`` means unlimited. None without a limit."""
+    limit = _first_limit(priced, meter)
+    return limit["cap"] if limit else None
+
+
+def meter_name(priced: Any) -> str | None:
+    """The meter the plan counts against: per-unit charge, else tier, else limit."""
+    charge = per_unit_charge(priced)
+    if charge and charge.get("meter"):
+        return str(charge["meter"])
+    meters = tier_meters(priced)
+    if meters:
+        return meters[0]
+    limit = _first_limit(priced)
+    return limit["meter"] if limit else None
+
+
+def counts_usage(priced: Any) -> bool:
+    """True when the plan counts usage: a per-unit charge, a limit or a tier."""
+    if per_unit_charge(priced) is not None:
+        return True
+    if included_units(priced) is not None:
+        return True
+    return len(tier_bands(priced)) > 0
+
+
+def pegged_credits_per_unit(
+    charge_minor: float, credits_per_minor_unit: float, usd_to_charge_rate: float = 1
+) -> int:
+    """Credits per metered unit, as the platform's debit engine computes them."""
+    if not charge_minor > 0 or not credits_per_minor_unit > 0:
+        return 0
+    rate = usd_to_charge_rate if usd_to_charge_rate > 0 else 1
+    return js_round((charge_minor / rate) * credits_per_minor_unit)
+
+
+def _is_metered(priced: Any) -> bool:
+    return per_unit_charge(priced) is not None or len(tier_bands(priced)) > 0
+
+
+def _is_billable_metered(priced: Any) -> bool:
+    rate = usage_rate(priced)
+    if rate is not None and rate["amountMinor"] > 0:
+        return True
+    return any(band["charge"]["amountMinor"] > 0 for band in tier_bands(priced))
+
+
+def _headline_price_minor(priced: Any) -> Any:
+    if billing_cycle(priced):
+        flat = next(
+            (c for c in charges(priced) if c["per"] == "flat" and not c.get("oneTime")), None
+        )
+    else:
+        flat = next((c for c in charges(priced) if c["per"] == "flat"), None)
+    return flat["amountMinor"] if flat else 0
+
+
+def plan_pricing_shape(priced: Any) -> Json:
+    """``{"shape", "headlineMinor", "currency", "cycle", "rate"}``; ``shape`` is one of
+    free, usage, recurring, hybrid, oneTime."""
+    fallback = str(coalesce(get(priced, "currency"), "USD")).upper()
+    if not isinstance(priced, Mapping):
+        return {
+            "shape": "oneTime",
+            "headlineMinor": 0,
+            "currency": fallback,
+            "cycle": None,
+            "rate": None,
+        }
+    if priced.get("requiresPayment") is False:
+        return {
+            "shape": "free",
+            "headlineMinor": 0,
+            "currency": fallback,
+            "cycle": billing_cycle(priced),
+            "rate": usage_rate(priced),
+        }
+    recurring = billing_cycle(priced) is not None
+    metered = _is_metered(priced)
+    if recurring and _is_billable_metered(priced):
+        shape = "hybrid"
+    elif recurring:
+        shape = "recurring"
+    elif metered:
+        shape = "usage"
+    else:
+        shape = "oneTime"
+    headline = headline_charges(priced)
+    currency = coalesce(
+        headline[0]["currency"] if headline else UNDEFINED, get(priced, "currency"), "USD"
+    )
+    return {
+        "shape": shape,
+        "headlineMinor": _headline_price_minor(priced),
+        "currency": str(currency).upper(),
+        "cycle": billing_cycle(priced) if recurring else None,
+        "rate": usage_rate(priced) if metered else None,
+    }
+
+
+def credits_per_unit_from_balance(priced: Any, balance: Any, meter: str | None = None) -> Any:
+    """Credits per metered call against the customer's balance peg; None when the charge is
+    not in the balance's display currency (the SDK does not hold that FX rate)."""
+    charge = usage_rate(priced, meter)
+    if not charge or not charge["amountMinor"] > 0:
+        return None
+    display_currency = get(balance, "displayCurrency")
+    per_minor = get(balance, "creditsPerMinorUnit")
+    if not isinstance(display_currency, str) or not _is_number(per_minor):
+        return None
+    if charge["currency"].upper() != display_currency.upper():
+        return None
+    credits = pegged_credits_per_unit(
+        charge["amountMinor"], per_minor, coalesce(get(balance, "displayExchangeRate"), 1)
+    )
+    return credits if credits > 0 else None