Skip to main content

prophetx_sdk 0.5.0 copy "prophetx_sdk: ^0.5.0" to clipboard
prophetx_sdk: ^0.5.0 copied to clipboard

ProphetX Flutter SDK — embed deposit, withdraw, KYC and onboarding flows in Flutter apps.

Changelog #

All notable changes to the ProphetX Flutter SDK are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased] #

0.5.0 - 2026-10-28 #

Added #

  • OpenDepositOptions and OpenWithdrawOptions take successButtonLabel and onSuccessAction (BBPX-178). The label replaces the success screen's "Make Another Deposit" / "Make Another Withdrawal" text, shown as given (trimmed, at most 40 characters, not translated). Once either is set the button no longer reloads the flow: the embed sends the new PROPHETX_SUCCESS_ACTION message, the SDK calls onSuccessAction and closes the sheet, and onCancel does not fire. Without either option nothing changes. The bus gains a matching SuccessActionEvent.

Fixed #

  • A page reload no longer leaves the embed spinning forever. The deposit and withdraw success screens' "Make Another Deposit" / "Make Another Withdrawal" reloads the page inside the WebView, and the SDK had latched _sessionSent and _readyReceived after the first load: the new page's PROPHETX_EMBED_LOADED was ignored and the retry loop that backs it up stood down on its first tick, so no session ever reached the embed. Each page load now starts a fresh handshake, as React Native already did.
  • WalletClient.refetch() now reads the ISV gateway's GET /embed/v1/wallet (the endpoint the embed itself uses) and parses its decimal-string balance. It called the mothership /api/v1/wallet, which answers 401 to an ISV token, so balance stayed null on every environment.
  • The injected bridge no longer replaces window.postMessage; it forwards PROPHETX_* messages from its window.parent proxy instead. The replacement ran whenever a same-origin frame inside the embed posted to it, which made the browser report the embed's own window as that message's event.source. PayNearMe's hosted widget page is such a frame, so its complete was dropped by payment-web's source check: the deposit went through, but the flow stayed on a blank widget and never reported success.
  • Changing ProphetXProvider.environment to one with a different apiBaseUrl now replaces the WalletClient. The client was built once against the first environment's host, so after a switch refetch() sent the new environment's token to the old gateway — a 401, or the wrong user's balance. Widgets that read ProphetX.of(context).wallet are rebuilt with the new client; a refetch() still in flight on the old one finishes without notifying.

0.4.0 - 2026-09-22 #

Added #

  • initialAmount on OpenDepositOptions and OpenWithdrawOptions — pre-fills the amount field on load; the user can still edit it before submitting. A value that is not a finite positive number emits no query param, the same discipline as appLink (BBPX-117).

  • attributionVariant on ProphetXProvider — asks the embed to draw its own footer attribution as PoweredByVariant.text, a single muted line, instead of the default lockup. Set once for the integration, the same way as theme and locale, rather than per open() call — a host picks one treatment, not one per flow. Typed with the existing PoweredByVariant rather than a second enum, so the same value selects the treatment whether you render PoweredByProphetX yourself or ask the embed to. Applied to every route whose footer carries the mark — deposit, withdraw, idUpload, kyc, and tandc — via the shared isAttributionRoute predicate. kyc is included because it serves from /verified, which renders the same ID-upload screen /id-upload does. Only text emits a query param; logo and null are the same URL (BBPX-112).

    Currently a no-op against a deployed embed. The embed honours the underlying ?attribution= param only in a dev build; production always renders the lockup, whatever the SDK sends. The option lands now so the four SDKs stay in step and so the variant is exercisable in development.

  • EmbedRoute.tandc — a route token for the standalone /tandc consent screen, and a place in the isAttributionRoute allowlist so its footer respects attributionVariant too. Deliberately incomplete otherwise: there is no TandcFlow controller, no OpenTandcOptions, and no ProphetX.of(context).tandc. A host reaches the screen by composing ProphetXWebView/ProphetXModal with route: EmbedRoute.tandc directly, not through a flow controller.

  • PoweredByProphetX takes a variant. PoweredByVariant.text renders the attribution as a single muted line, "Powered by ProphetX", with no logo — for placements where the lockup is too loud. PoweredByVariant.logo remains the default, so existing usage is unchanged.

Changed #

  • PoweredByVariant moved from src/powered_by_prophetx.dart to src/branding/powered_by_variant.dart so the URL builder can serialize it without importing a Flutter widget. Not a breaking change — the public name, members and export from prophetx_sdk.dart are unchanged.

0.3.1 - 2026-08-29 #

Changed #

  • Removed the git-dependency install instructions from the package README. The README is the public pub.dev page, and it was telling readers that betprophet1/isv-embed-fe is private and that they needed read access granted — to people who had just installed the package from a public registry. The install section is now the pub.dev dependency and nothing else. Partners who pin an exact commit still can; that route is documented in the integration guide rather than on the listing.

No code changes. Identical to 0.3.0.

0.3.0 - 2026-08-28 #

Added #

  • appLink on OpenDepositOptions and OpenWithdrawOptions — your app's bare URL scheme, e.g. myapp://.

    ProphetX.of(context).deposit.open(
      OpenDepositOptions(appLink: 'myapp://', onSuccess: (id, amount) { … }),
    );
    

    When a user links an AeroPay bank that uses OAuth, the bank login cannot run inside the WebView — it has to run in the system browser, and this is the link Aerosync redirects to on the way back. Without it the widget sits on "Almost there! Bank authenticated, returning to Aerosync." forever, even though the bank link itself succeeded.

    Bare, not a path. Aerosync's guidance is that "you want to open the app in the same state that it exists in memory and not trigger any specific navigation". This is deliberately not OpenIdUploadOptions.redirectUrl, which carries a path on purpose so the host can route on it. A path here made Flutter's default router throw onUnknownRoute was not set.

    ⚠️ Additive, but not optional in practice. Named optional parameters, so nothing renames and existing code compiles untouched — but an integration that upgrades and does not adopt appLink still has OAuth bank linking broken. The SDK bump alone does not fix it. Three host-side obligations come with it: pass appLink on every deposit and withdraw open; register the scheme with the OS (CFBundleURLTypes on iOS, an intent-filter on Android); and consume the incoming link without navigating, because the link exists only to foreground the app and routing on it takes the user off the screen the widget is waiting on. Only deposit and withdraw are affected, only on a device, and only for banks that use OAuth. See docs/features/flutter-sdk.md → AeroPay OAuth Bank Linking.

  • ProphetXModal.appLink and ProphetXWebView.appLink, threading the same value down for a host driving either directly. ProphetXProvider reads it off whichever money flow is open; the identity flows never reach a bank widget, so they have nowhere to put it.

  • An appLink parameter on buildEmbedUri, emitted after redirectUrl and before extraParams. Absent, null and empty all emit no param — the embed reads a present-but-blank appLink= as a real return target and hands Aerosync something it cannot redirect to. This is one deliberate asymmetry with the sdk-core twin the builder otherwise mirrors: only a native host needs a way back from the system browser, so the shared urlCases corpus carries no appLink case and both sides still agree everywhere it is asserted.

Fixed #

  • A URL the embed cannot launch is no longer reported as a fatal error. The SDK overrides window.open on the embed's main frame, so every window.open anywhere in the embed arrives on the same __OPEN_URL__ channel, whatever flow it came from. Anything Uri.tryParse accepted went to launchUrl, and a failure there surfaced as onError('ID_UPLOAD_OPEN_FAILED', …).

    Navy Federal ends its OAuth bank login on a relative /api/auth/memberlogout. That is the embed navigating itself, not a hand-off — but Uri.tryParse accepts a scheme-less relative reference and returns a non-null Uri, so the null check never caught it. It reached the OS, failed, and the partner saw Could not open /api/auth/memberlogout as a fatal error on a bank link that had already succeeded.

    Only an absolute http/https URL is now treated as a hand-off, decided by isExternallyLaunchable in lib/src/webview/external_url.dart — a mirror of sdk-react-native's externalUrl.ts. A relative path, about:blank, javascript: or an app scheme is dropped and logged through devtools at debug level instead of raising onError. Uri.hasAuthority is checked alongside Uri.hasScheme, so https:notahost is rejected too. Genuine hand-offs — the IDComply verification form, an OAuth bank login — are unaffected.

  • The two debugPrint('[ProphetX:handoff] …') lines left on the __OPEN_URL__ path are gone. They printed to the host app's console on every hand-off, outside devtools and with no way to switch them off.

0.2.0 - 2026-08-27 #

Added #

  • Verified Inc 1-Click Signup — ProphetX.of(context).oneClickSignup.open(...). Runs before a ProphetX user exists, so it takes a single-use sessionKey and environment instead of an embed token, and ends on its own dismissible screen.

  • ResizeMessage.width. The model could not represent a width at all, so 1-Click stayed at Verified's 396px cap for its terminal screens, which are ours and belong at the house width. 0 means "back to your default".

    height is deliberately still ignored. A bottom sheet is anchored to the bottom edge, so sizing it to a short screen drags the flow into the corner — worse than the empty surface it removes. Content taller than the sheet scrolls inside the embed.

  • ProphetXLogo — the ProphetX wordmark, exported so a host can place the mark on its own. Ported from packages/ui/src/components/Icons/Icons.tsx: same 0 0 108 12 viewBox, same path data, same three gradients.

  • Contract suites under test/contract/, driven by the cross-SDK matrix at packages/embed-contract/embed-route-contract.json rather than by locally restated expectations: the URL corpus, the Verified.inc return corpus, the flow → route map, and all 18 PROPHETX_* message shapes. The URL semantics now live in lib/src/webview/embed_url.dart (buildEmbedUri), a mirror of sdk-core's buildEmbedUrl that the same corpus pins on both sides.

  • ProphetXSheetLayout — the sheet chrome (barrier, dismiss target, slide-up sheet) split out of ProphetXModal behind a plain child, so it can be widget-tested. ProphetXModal cannot: it embeds a webview_flutter platform view that flutter test cannot instantiate.

  • SheetGeometry, alongside the existing sheetMaxHeightFor — the sheet's geometry as pure functions over raw window metrics, unit-tested in test/sheet_geometry_test.dart including the degenerate cases (zero device pixel ratio, a keyboard taller than the window) that previously produced Infinity/NaN constraints.

  • EmbedRoute.dismissOnBackdropTapDefault, and ProphetXModal.dismissOnBackdropTap as a per-modal override (bool?; null takes the per-flow default).

  • A modal tap ignored devtools log (category event, level debug) with a source tag, emitted whenever a tap lands on the modal but on nothing actionable. The original bug was invisible precisely because a suppressed or mis-routed tap left no trace; modal close requested still carries its source (backdrop / close-button) unchanged.

Changed #

  • Breaking: OpenKycOptions callback signatures changed. Dart is strict about closure arity, so both break existing code:

    // before
    onKycSuccess: (String uuid) { … }
    onKycFailed:  (String reason) { … }
    
    // after
    onKycSuccess: (String? uuid) { … }        // no identifier at runtime
    onKycFailed:  (String reason, bool? retryable) { … }
    

    openKyc() resolves to /verified, which now serves the ID Upload flow — our Verified Inc account is not approved for the API integration the old phone/OTP screens ran on. The IDPV API behind it returns no applicant id, and failures carry whether a retry could help. Branch on retryable, never on reason.

  • The sheet paints its surface from the embed theme, not the host app's. The embed paints background: transparent, so the sheet shows through wherever the content does not — most visibly under a vendor screen that caps its own height. Taking it from ThemeData.colorScheme.surface meant the chrome followed one palette and the content another, and any difference read as a band of the wrong colour. Resolution is colorOverrides['background'] → backgroundColor → colorOverrides['surface'] → the ambient surface, shared with sdk-react-native. Only CSS hex forms parse; anything else falls back.

  • PoweredByProphetX now renders the real logo instead of plain text. It was a placeholder — a single Text reading "Powered by PROPHETX" — where the embed's own footer shows the wordmark with its teal gradient. It now matches, so the mark a host places in their chrome is the same one the flow shows inside the WebView.

    Defaults are unchanged (12px, ThemeData.hintColor), so existing call sites keep their sizing and colour; only the rendering differs. The colour applies to the label and the wordmark glyphs, while the X keeps its gradient — it is interpolated into the markup rather than applied as a ColorFilter, which would have flattened the gradient too.

    This follows the web component. packages/sdk-react-native still draws a bold letter-spaced text wordmark, so RN is now the odd one out and should follow.

  • Adds flutter_svg as a dependency, to render that logo without hand-porting its Bezier paths to a CustomPainter — which would drift silently the next time branding changes.

  • Breaking for two callers. EmbedRoute.kyc.path returns verified instead of kyc, and FlowOpenEvent / FlowCloseEvent carry flow: 'verified' instead of flow: 'kyc' for that flow. Both changes converge Flutter with sdk-js, sdk-react and sdk-react-native, which all emit verified already. Code that matched on the old string must be updated; the EmbedRoute.kyc enum member is unchanged. Release this as a minor bump (0.2.0), not a patch.

  • Backdrop-tap dismissal is now per flow, and off for money flows. Tapping the gap above the sheet no longer dismisses deposit or withdraw; it still dismisses onboarding, kyc and idUpload. The asymmetry is about the cost of being wrong rather than how often it happens: losing a half-entered deposit costs the user real effort and risks a duplicate transaction, while abandoning onboarding costs almost nothing and is usually what the user meant. Nobody is trapped — the close button and the system back gesture always work. A suppressed tap is logged as modal tap ignored with source: 'backdrop-suppressed' at debug level, so it is visible rather than merely inert. Override per modal with ProphetXModal.dismissOnBackdropTap; the mapping lives on EmbedRoute.dismissOnBackdropTapDefault and every route is pinned by a table in test/flows/dismiss_on_backdrop_tap_test.dart, so a new flow forces a decision.

  • The active flow now renders in the root Overlay instead of a Stack inside ProphetXProvider. Two consequences worth knowing before upgrading: the sheet paints above all host chrome (that is the fix), and because the portal's element stays inside the host's route, host navigation suspends the flow — pushing a route takes the sheet offstage without disposing it, and popping restores it with the flow still open. ProphetX.of(context) keeps working inside a modalBuilder; nothing needs re-providing.

  • ProphetXProvider must be mounted where an Overlay exists — i.e. inside MaterialApp (as home: or below), which is what the test app and every realistic host already do. Mounted above MaterialApp the SDK falls back to the old inline Stack, which no longer crashes on a missing Directionality but cannot escape host chrome, and the real modal chrome will not render there at all because Flutter's Tooltip itself requires an Overlay ancestor.

Fixed #

  • The sheet now closes on PROPHETX_CANCEL. It handed the WebView widget.onCancel alone, so an embed reporting it was finished — a terminal screen's Close button, ID Upload's final action — fired the host callback and left the sheet sitting there. Every other SDK closes on this message.

  • The session context is re-sent after the verified return-navigation. That navigation is a real page load and the send was latched once-only, so the reloaded embed got no theme or locale.

  • The modal dismissed itself when the soft keyboard opened, and the host's app bar covered its close button. Both came from the same root cause: the sheet was laid out inline in the host's widget tree and sized from the ambient MediaQuery. A Scaffold ancestor strips viewInsets.bottom from the MediaQuery it hands its body (removeViewInsets, gated on resizeToAvoidBottomInset, default true) and lays that body out smaller while leaving MediaQuery.size at the full screen — so the sheet read a keyboard inset of 0 and a screen taller than the box it was in, overflowed, and got clipped. Taps aimed at the sheet then landed on the full-screen backdrop, which dismissed the flow silently: nothing threw, so no error reporting could see it. Being inline also put the sheet below the host's chrome in paint order. The sheet now derives its geometry from raw window metrics (immune to ancestor rewriting) and renders in the root overlay, above all host scaffolds. Geometry is now identical in every host layout, which test/sheet_layout_matrix_test.dart asserts across a matrix of host shapes × keyboard states × screen sizes.

  • A mis-aimed tap can no longer cancel a payment. The dismiss target used to be a full-screen backdrop, so any tap the sheet did not claim dismissed the flow. It is now laid out as the sheet's exact complement — only the visible gap above the sheet — so a stray tap during a layout shift is structurally incapable of cancelling a transaction, whatever future geometry bugs appear. Everything else is absorbed and logged rather than acted on, which also stops taps falling through to the host app behind the sheet.

  • The kyc flow pointed at /kyc, which the embed does not register. With no notFoundComponent the SPA answered 200 with a blank shell, so PROPHETX_READY never arrived and the modal's loading overlay hung forever instead of erroring. EmbedRoute.kyc.path is now verified — the route that actually serves the flow, and the one the three JavaScript SDKs already used.

  • The embed URL builder stripped only one trailing slash off a configured embedUrl, so a self-hosted base written as https://host/// produced https://host///withdraw. Every trailing slash is now removed. Leading slashes on the route are stripped as well, so deposit and /deposit build the same URL.

0.1.1 - 2026-08-05 #

Fixed #

  • Install instructions pointed at flutter-sdk-v0.0.1, a tag that never existed, so a partner copy-pasting the README block got a resolution failure. Now flutter-sdk-v0.1.0, with the HTTPS clone URL as the documented default — the README previously showed only the SSH URL while claiming a credential helper would work, which it cannot without an SSH key.
  • Public API table corrected: events is a ProphetXEventBus (subscribe via .stream), not a Stream<ProphetXEvent>; auth and wallet are nullable and only exist when auth: is passed to the provider. Coding the old table literally was a compile error. idUpload and the onSessionExpired / devtools provider parameters were missing entirely.
  • Built-in environment embedUrls no longer carry a trailing slash, matching sdk-core/src/env/env-config.ts. No behaviour change here — _fullEmbedUrl already normalized — but the JS SDKs concatenate ${embedUrl}/${route} and were emitting https://host//deposit.

Note #

Released to separate main from the flutter-sdk-v0.1.0 tag, which shipped different content under the same 0.1.0 version.

0.1.0 - 2026-08-04 #

Added #

  • ID Upload (IDComply document verification) — ProphetX.of(context).idUpload with OpenIdUploadOptions(redirectUrl, onKycSuccess, onKycFailed, onKycPending, …). The vendor form cannot be framed, so it opens in the device browser; redirectUrl should be a deep link registered with the OS, or the user has no route back into the app.
  • url_launcher dependency, used to perform that handoff.

Fixed #

  • The hosted form never opened. webview_flutter produces no navigation request for window.open and silently drops it, so onNavigationRequest could not catch it either. The bridge JS now overrides window.open and forwards the URL as __OPEN_URL__ over the existing channel; Dart opens it with LaunchMode.externalApplication.
  • onCancel never fired for ID Upload — a non-exhaustive switch in _onModalCancel omitted IdUploadFlowOptions. Adding a sealed-class variant breaks every exhaustive switch and the compiler reports them one at a time.
  • sandbox pointed at a dead host. isv-sandbox-api.betprophet.co resolves but refuses connections; now isv-api.sandbox.prophetx.dev, matching sdk-core.
  • _fullEmbedUrl discarded any query already present on embedUrl and could emit a second ?. Now parsed and merged via Uri.

Notes #

onKycFailed carries retryable — branch on it, never on reason. A retryable document rejection emits nothing at all; anything reaching the callback is terminal. reason is for logging and routing only.

0.0.2 - 2026-06-26 #

0.0.1 #

Added #

  • Initial private-beta release of prophetx_sdk.
  • ProphetXProvider root widget with deposit, withdraw, onboarding, and KYC flow controllers.
  • AuthManager (Unauthenticated / Authenticating / Authenticated / Expired / AuthError) with auto-refresh.
  • WalletClient.refetch() against GET /api/v1/wallet.
  • ProphetXEventBus exposing ReadyEvent, SuccessEvent, ErrorEvent, CancelEvent, KycSuccessEvent, KycFailedEvent, KycPendingEvent, GeofenceBlockedEvent, SessionExpiredEvent, SessionRefreshedEvent, FlowOpenEvent, FlowCloseEvent.
  • WebView bridge with Verified.inc redirect handling (lib/src/webview/injected_js.dart).
  • Environment resolution for production, staging, and sandbox.
0
likes
130
points
583
downloads

Documentation

Documentation
API reference

Publisher

unverified uploader

Weekly Downloads

ProphetX Flutter SDK — embed deposit, withdraw, KYC and onboarding flows in Flutter apps.

Homepage

License

unknown (license)

Dependencies

flutter, flutter_secure_storage, flutter_svg, http, url_launcher, uuid, webview_flutter

More

Packages that depend on prophetx_sdk