feat(paywalls): add web_view message model and parsing (PWENG-98)

[alexrepty]

Checklist

• If applicable, unit tests
• If applicable, create follow-up issues for purchases-ios and hybrids

Motivation

Defines the inbound message model and parsing for web_view ↔ native communication, so messages from web content are validated before reaching app code.

Part of PWENG-98.

Description

• Adds the public PaywallWebViewMessage plus the PaywallWebViewMessageHandler / PaywallWebViewController surface.
• Adds the internal WebViewMessageType and WebViewMessageParser: validates the flat envelope, enforces payload size / nesting-depth caps, requires the component_id to match the rendered component, and validates per-type fields (rc:step-loaded, rc:step-complete, rc:request-variables, rc:error); unknown types are dropped.
• Pure data/logic — no live WebView bridge yet.
• Tested by WebViewMessageParserTest.

iOS parity: mirrors purchases-ios (web-view-bridge-wiring).
Stack (merge bottom-up): schema → rendering → CSP → value types → message model → variables provider → JS bridge → wiring.

---

Note

Low Risk
Additive public API and internal validation logic with no runtime WebView integration or purchase flow changes in this PR.

Overview
Introduces the public surface for Paywalls V2 web_view ↔ native messaging: PaywallWebViewMessage, PaywallWebViewMessageHandler, and PaywallWebViewController (reply via postVariables / postMessage using PaywallWebViewValue). App code will wire the handler through PaywallOptions.Builder.setWebViewMessageHandler in a follow-up; the SDK does not auto-dismiss or purchase on rc:step-complete.

Adds internal parsing via WebViewMessageParser: validates the flat postMessage envelope, caps payload size (64KB) and nesting depth, requires component_id to match the rendered web view, handles rc:step-loaded, rc:step-complete, rc:request-variables, and rc:error, and drops unknown types and invalid payloads. api.txt is updated for the new types.

No live WebView bridge in this PR—data and validation only, covered by WebViewMessageParserTest.

^{Reviewed by Cursor Bugbot for commit a1cc787. Bugbot is set up for automated code reviews on this repo. Configure here.}

[alexrepty]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(paywalls): wire web_view messaging into the paywall (PWENG-98) #3653
• feat(paywalls): add web_view JavaScript bridge (PWENG-98) #3655
• feat(paywalls): add web_view SDK variables provider (PWENG-98) #3663
• feat(paywalls): add web_view message model and parsing (PWENG-98) #3654 👈 (View in Graphite)
• feat(paywalls): add web_view message value types (PWENG-98) #3662
• feat(paywalls): isolate web_view content with a fixed CSP (PWENG-98) #3652
• feat(paywalls): render web_view component (PWENG-98) #3651
• feat(paywalls): add web_view component schema (PWENG-98) #3650
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit cdc1156. Configure here.}

[cursor]

Payload check unbounded allocation

Medium Severity

The 64KB payload cap is enforced by calling toByteArray(UTF_8) on the entire raw JSON string first. A hostile or buggy web view can send a very large string and trigger a huge allocation (and possible OOM) before the message is dropped, even though the limit is meant to bound work.

 

^{Reviewed by Cursor Bugbot for commit cdc1156. Configure here.}