Full SDK rewrite with native-first WebView #MOBI-297

.gitignore

@@ -23,7 +23,10 @@ migrate_working_dir/
 
 # Flutter/Dart/Pub related
 # Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+# The example app lockfile (example/pubspec.lock) is kept for reproducible demos.
 /pubspec.lock
 **/doc/api/
 .dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
 build/

.metadata

@@ -7,27 +7,4 @@ version:
   revision: "46787ee49c1fd80ab603f0702733edab54653aef"
   channel: "stable"
 
-project_type: plugin
-
-# Tracks metadata for the flutter migrate command
-migration:
-  platforms:
-    - platform: root
-      create_revision: 46787ee49c1fd80ab603f0702733edab54653aef
-      base_revision: 46787ee49c1fd80ab603f0702733edab54653aef
-    - platform: android
-      create_revision: 46787ee49c1fd80ab603f0702733edab54653aef
-      base_revision: 46787ee49c1fd80ab603f0702733edab54653aef
-    - platform: ios
-      create_revision: 46787ee49c1fd80ab603f0702733edab54653aef
-      base_revision: 46787ee49c1fd80ab603f0702733edab54653aef
-
-  # User provided section
-
-  # List of Local paths (relative to this file) that should be
-  # ignored by the migrate tool.
-  #
-  # Files that are not part of the templates will be ignored by default.
-  unmanaged_files:
-    - 'lib/main.dart'
-    - 'ios/Runner.xcodeproj/project.pbxproj'
+project_type: package

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 5.0.0
+
+* Rewrite the SDK to load the Ramp widget in a Flutter WebView instead of the
+  native iOS/Android Ramp SDKs. Published as a Dart Flutter package (no
+  Android/iOS plugin shells).
+* Breaking: host owns presentation (`ramp.view`); use sealed `WidgetEvent` /
+  `HostEvent` instead of the old callbacks; `Configuration` is immutable and
+  uses widget-2 params. See [MIGRATION.md](MIGRATION.md).
+* Default base URL is now `https://app.rampnetwork.com`.
+* Raise minimums: Flutter 3.44 / Dart 3.12, Android API 24, iOS 13.
+* Off-widget / `target=_blank` navigations open in the system browser; Android
+  file inputs use `file_picker` / `image_picker`.
+
 ## 4.0.1
 
 * Updated package documentation
@@ -10,7 +23,7 @@
 
 ## 3.0.0
 
-* Regenerated plugin to fix platform specific dependencies 
+* Regenerated plugin to fix platform specific dependencies
 
 ## 2.0.2
 

MIGRATION.md

@@ -0,0 +1,114 @@
+# Migrating from 4.x to 5.x
+
+Version 5.0.0 replaces the native iOS/Android Ramp SDKs with a Flutter WebView
+that loads the Ramp widget. The package is a Dart Flutter package (no Android
+or iOS plugin shells).
+
+## Platform requirements
+
+| | 4.x | 5.x |
+| --- | --- | --- |
+| Flutter / Dart | Flutter `>=3.3.0` / Dart `>=3.2.3 <4.0.0` | Flutter 3.44+ / Dart 3.12+ |
+| Android | `minSdkVersion` 21 | `minSdkVersion` 24+ |
+| iOS | deployment target 11.0 | deployment target 13+ |
+
+Declare `android.permission.CAMERA`, `NSCameraUsageDescription`, and photo
+library usage descriptions for identity verification and document upload.
+
+## Presentation
+
+**4.x:** the SDK presented its own UI (`showRamp` / similar).
+
+**5.x:** create `RampFlutter(Configuration)` or `RampFlutter.signed(url)`,
+embed `ramp.view` in your own route / sheet / dialog, and call `dispose` when
+dismissed.
+
+```dart
+final ramp = RampFlutter(Configuration(/* ... */))
+  ..onWidgetEvent = (event) { /* ... */ };
+
+await showModalBottomSheet<void>(
+  context: context,
+  isScrollControlled: true,
+  builder: (_) => SizedBox(
+    height: MediaQuery.sizeOf(context).height * 0.92,
+    child: ramp.view,
+  ),
+);
+
+ramp.dispose();
+```
+
+## Events
+
+**4.x:** separate callbacks (`onOnrampPurchaseCreated`, `onSendCryptoRequested`,
+`onOfframpSaleCreated`, `onRampClosed`, …).
+
+**5.x:** one `onWidgetEvent` handler with sealed `WidgetEvent` subtypes, and
+`postHostEvent` with sealed `HostEvent` subtypes (`SendCryptoResult`,
+`RequestCryptoAccountResult`). Host events are queued until the widget page
+has finished loading.
+
+```dart
+ramp.onWidgetEvent = (event) {
+  switch (event) {
+    case AppVersion():
+      break;
+    case PurchaseCreated(:final payload):
+      break;
+    case OfframpSaleCreated(:final payload):
+      break;
+    case SendCryptoRequested(:final payload):
+      ramp.postHostEvent(SendCryptoResult.txHash(txHash));
+    case RequestCryptoAccount(:final payload):
+      ramp.postHostEvent(
+        RequestCryptoAccountResult.account(address: userAddress, type: payload.type),
+      );
+    case WidgetClose():
+      Navigator.of(context).pop();
+    case WidgetCloseRequest():
+      break;
+    case WidgetConfigDone():
+    case WidgetConfigFailed():
+      break;
+  }
+};
+```
+
+## Configuration
+
+`Configuration` is an immutable helper used only for the config-built entry
+point. It builds widget URLs with widget-2 params and always appends
+`sdkType` / `sdkVersion`.
+
+### Param mapping
+
+| 4.x (removed) | 5.x |
+| --- | --- |
+| `defaultAsset` / `fiatCurrency` / `fiatValue` / `swapAsset` / `offrampAsset` / `swapAmount` | `inAsset` / `outAsset` / `inAssetValue` / `outAssetValue` / `enabledCryptoAssets` |
+| `enabledFlows` / `defaultFlow` as strings | `TransactionFlow` enum |
+| — | `paymentMethodType` (`PaymentMethodType` enum) |
+| `hostLogoUrl`, `hostAppName`, `containerNode`, `deepLinkScheme`, `variant` | removed — partner name and logo are set by Ramp Network on the integration (`PARTNER_NAME` / `PARTNER_LOGO_URL`) |
+| `finalUrl` | removed — hosted-mode redirect only; not used by the Flutter WebView SDK |
+
+Default base URL is `https://app.rampnetwork.com`.
+
+Both `Configuration.buildWidgetUrl()` and `RampFlutter.signed` require an
+`https` Ramp Network host (`*.ramp.network`, `*.rampnetwork.com`,
+`*.ramp-network.org`).
+
+## Signed URLs
+
+Use `RampFlutter.signed(url)` for server-signed widget URLs (loaded verbatim).
+Do not put a signed URL in `Configuration.url` — `buildWidgetUrl()` rejects
+bases that already include a `signature` query parameter.
+
+## Public API surface
+
+Import only `package:ramp_flutter/ramp_flutter.dart`. Implementation lives under
+`lib/src/`.
+
+## Further reading
+
+See [README.md](README.md) for host setup and usage examples, and the
+[Flutter SDK docs](https://docs.ramp.network/mobile/flutter-sdk/).

Makefile

@@ -0,0 +1,24 @@
+.PHONY: get format analyze test ios
+.DEFAULT_GOAL := test
+
+get:
+	flutter pub get
+
+format:
+	dart format lib test example/lib
+
+analyze:
+	dart analyze
+
+test: get format analyze
+	flutter test
+
+build: get
+	cd example && flutter build ios --debug --no-codesign
+	cd example && flutter build apk --debug
+
+ios:
+	@id=$$(flutter devices --device-connection attached | grep SimRuntime.iOS \
+	| head -n1 | cut -d'•' -f2 | xargs); \
+	[ -n "$$id" ] || (echo "No iOS device found" && exit 1); \
+	cd example && flutter run -d $$id

README.md

@@ -1,7 +1,107 @@
 # Ramp Network Flutter
 
-Official Flutter wrapper for Ramp Network
+Official Flutter package for Ramp Network. \
+Loads the Ramp widget in a Flutter
+WebView on iOS and Android.
 
 ## Getting Started
 
-For installation & usage follow [Ramp Network Flutter documentation](https://docs.ramp.network/mobile/flutter-sdk/)
+Add the dependency:
+
+```yaml
+dependencies:
+  ramp_flutter: ^5.0.0
+```
+
+Upgrading from 4.x? See [MIGRATION.md](MIGRATION.md).
+
+### Host setup
+
+- **Android:** `minSdkVersion` 24+. Declare `android.permission.CAMERA` for
+  identity verification camera capture.
+- **iOS:** deployment target 13+. Add `NSCameraUsageDescription` and photo
+  library usage descriptions for identity verification and document upload.
+- Requires Flutter 3.44+ / Dart 3.12+.
+
+### Usage
+
+The SDK provides the Ramp WebView; your app owns presentation (route, bottom
+sheet, dialog, etc.) and must call `dispose` when it is dismissed.
+
+**Configuration** (SDK builds the widget URL, including `sdkType` / `sdkVersion`):
+
+```dart
+import 'package:ramp_flutter/ramp_flutter.dart';
+
+final ramp = RampFlutter(
+  Configuration(
+    hostApiKey: 'YOUR_API_KEY',
+    enabledFlows: [TransactionFlow.ONRAMP, TransactionFlow.OFFRAMP],
+    outAsset: 'BTC_BTC',
+  ),
+)
+  ..onWidgetEvent = (event) {
+    switch (event) {
+      case AppVersion():
+        break;
+      case PurchaseCreated(:final payload):
+        break;
+      case OfframpSaleCreated(:final payload):
+        break;
+      case SendCryptoRequested(:final payload):
+        ramp.postHostEvent(SendCryptoResult.txHash(txHash));
+      case RequestCryptoAccount(:final payload):
+        ramp.postHostEvent(
+          RequestCryptoAccountResult.account(address: userAddress, type: payload.type),
+        );
+      case WidgetClose():
+        Navigator.of(context).pop();
+      case WidgetCloseRequest():
+        break;
+      case WidgetConfigDone():
+      case WidgetConfigFailed():
+        break;
+    }
+  };
+
+await showModalBottomSheet<void>(
+  context: context,
+  isScrollControlled: true,
+  builder: (_) => SizedBox(
+    height: MediaQuery.sizeOf(context).height * 0.92,
+    child: ramp.view,
+  ),
+);
+
+ramp.dispose();
+```
+
+**Server-signed URL** (loaded verbatim — do not put this in `Configuration.url`):
+
+```dart
+final ramp = RampFlutter.signed(signedWidgetUrlFromYourBackend)
+  ..onWidgetEvent = (event) { /* same switch as above */ };
+```
+
+Generate the signed URL on your backend (`hostApiKey`, `timestamp`, `signature`).
+Keep signing keys out of the app.
+
+Partner **name** and **logo** are not SDK configuration fields. Ask Ramp
+Network to set host features `PARTNER_NAME` / `PARTNER_LOGO_URL` for your
+integration (for example via integrations@rampnetwork.com).
+
+For more configuration parameters see
+[Ramp Network Flutter documentation](https://docs.ramp.network/mobile/flutter-sdk/).
+
+### Notes
+
+- Off-widget navigations (other https hosts, custom schemes, `intent:`) and
+  `target=_blank` / `window.open` open in the system browser via
+  `NavigationDelegate` and a forked `webview_flutter`
+  ([mateusz-ramp/flutter_packages](https://github.com/mateusz-ramp/flutter_packages/tree/webview-target-blank)
+  / commit `a37d157`), declared as a direct dependency of this package so hosts
+  pick it up transitively (no host `dependency_overrides` required unless
+  another package pins pub.dev `webview_flutter`).
+- Android WebView `<input type="file">` uses `file_picker` (and the camera via
+  `image_picker` for capture). Host apps must declare camera / photo library
+  usage (see Getting Started). iOS WKWebView handles file inputs natively.

analysis_options.yaml

@@ -1,4 +1,4 @@
 include: package:flutter_lints/flutter.yaml
 
-# Additional information about this file can be found at
-# https://dart.dev/guides/language/analysis-options
+formatter:
+  page_width: 120