prophetx_sdk 0.5.0
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 #
OpenDepositOptionsandOpenWithdrawOptionstakesuccessButtonLabelandonSuccessAction(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 newPROPHETX_SUCCESS_ACTIONmessage, the SDK callsonSuccessActionand closes the sheet, andonCanceldoes not fire. Without either option nothing changes. The bus gains a matchingSuccessActionEvent.
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
_sessionSentand_readyReceivedafter the first load: the new page'sPROPHETX_EMBED_LOADEDwas 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'sGET /embed/v1/wallet(the endpoint the embed itself uses) and parses its decimal-stringbalance. It called the mothership/api/v1/wallet, which answers 401 to an ISV token, sobalancestayednullon every environment.- The injected bridge no longer replaces
window.postMessage; it forwardsPROPHETX_*messages from itswindow.parentproxy 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'sevent.source. PayNearMe's hosted widget page is such a frame, so itscompletewas 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.environmentto one with a differentapiBaseUrlnow replaces theWalletClient. The client was built once against the first environment's host, so after a switchrefetch()sent the new environment's token to the old gateway — a 401, or the wrong user's balance. Widgets that readProphetX.of(context).walletare rebuilt with the new client; arefetch()still in flight on the old one finishes without notifying.
0.4.0 - 2026-09-22 #
Added #
-
initialAmountonOpenDepositOptionsandOpenWithdrawOptions— 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 asappLink(BBPX-117). -
attributionVariantonProphetXProvider— asks the embed to draw its own footer attribution asPoweredByVariant.text, a single muted line, instead of the default lockup. Set once for the integration, the same way asthemeandlocale, rather than peropen()call — a host picks one treatment, not one per flow. Typed with the existingPoweredByVariantrather than a second enum, so the same value selects the treatment whether you renderPoweredByProphetXyourself or ask the embed to. Applied to every route whose footer carries the mark —deposit,withdraw,idUpload,kyc, andtandc— via the sharedisAttributionRoutepredicate.kycis included because it serves from/verified, which renders the same ID-upload screen/id-uploaddoes. Onlytextemits a query param;logoandnullare 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/tandcconsent screen, and a place in theisAttributionRouteallowlist so its footer respectsattributionVarianttoo. Deliberately incomplete otherwise: there is noTandcFlowcontroller, noOpenTandcOptions, and noProphetX.of(context).tandc. A host reaches the screen by composingProphetXWebView/ProphetXModalwithroute: EmbedRoute.tandcdirectly, not through a flow controller. -
PoweredByProphetXtakes avariant.PoweredByVariant.textrenders the attribution as a single muted line, "Powered by ProphetX", with no logo — for placements where the lockup is too loud.PoweredByVariant.logoremains the default, so existing usage is unchanged.
Changed #
PoweredByVariantmoved fromsrc/powered_by_prophetx.darttosrc/branding/powered_by_variant.dartso the URL builder can serialize it without importing a Flutter widget. Not a breaking change — the public name, members and export fromprophetx_sdk.dartare 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-feis 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 #
-
appLinkonOpenDepositOptionsandOpenWithdrawOptions— 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 throwonUnknownRoute 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
appLinkstill has OAuth bank linking broken. The SDK bump alone does not fix it. Three host-side obligations come with it: passappLinkon every deposit and withdraw open; register the scheme with the OS (CFBundleURLTypeson iOS, anintent-filteron 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. Seedocs/features/flutter-sdk.md→ AeroPay OAuth Bank Linking. -
ProphetXModal.appLinkandProphetXWebView.appLink, threading the same value down for a host driving either directly.ProphetXProviderreads it off whichever money flow is open; the identity flows never reach a bank widget, so they have nowhere to put it. -
An
appLinkparameter onbuildEmbedUri, emitted afterredirectUrland beforeextraParams. Absent, null and empty all emit no param — the embed reads a present-but-blankappLink=as a real return target and hands Aerosync something it cannot redirect to. This is one deliberate asymmetry with thesdk-coretwin the builder otherwise mirrors: only a native host needs a way back from the system browser, so the sharedurlCasescorpus carries noappLinkcase 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.openon the embed's main frame, so everywindow.openanywhere in the embed arrives on the same__OPEN_URL__channel, whatever flow it came from. AnythingUri.tryParseaccepted went tolaunchUrl, and a failure there surfaced asonError('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 — butUri.tryParseaccepts a scheme-less relative reference and returns a non-nullUri, so the null check never caught it. It reached the OS, failed, and the partner sawCould not open /api/auth/memberlogoutas a fatal error on a bank link that had already succeeded.Only an absolute
http/httpsURL is now treated as a hand-off, decided byisExternallyLaunchableinlib/src/webview/external_url.dart— a mirror ofsdk-react-native'sexternalUrl.ts. A relative path,about:blank,javascript:or an app scheme is dropped and logged throughdevtoolsatdebuglevel instead of raisingonError.Uri.hasAuthorityis checked alongsideUri.hasScheme, sohttps:notahostis 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, outsidedevtoolsand 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-usesessionKeyandenvironmentinstead 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.0means "back to your default".heightis 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 frompackages/ui/src/components/Icons/Icons.tsx: same0 0 108 12viewBox, same path data, same three gradients. -
Contract suites under
test/contract/, driven by the cross-SDK matrix atpackages/embed-contract/embed-route-contract.jsonrather than by locally restated expectations: the URL corpus, the Verified.inc return corpus, the flow → route map, and all 18PROPHETX_*message shapes. The URL semantics now live inlib/src/webview/embed_url.dart(buildEmbedUri), a mirror ofsdk-core'sbuildEmbedUrlthat the same corpus pins on both sides. -
ProphetXSheetLayout— the sheet chrome (barrier, dismiss target, slide-up sheet) split out ofProphetXModalbehind a plainchild, so it can be widget-tested.ProphetXModalcannot: it embeds awebview_flutterplatform view thatflutter testcannot instantiate. -
SheetGeometry, alongside the existingsheetMaxHeightFor— the sheet's geometry as pure functions over raw window metrics, unit-tested intest/sheet_geometry_test.dartincluding the degenerate cases (zero device pixel ratio, a keyboard taller than the window) that previously producedInfinity/NaNconstraints. -
EmbedRoute.dismissOnBackdropTapDefault, andProphetXModal.dismissOnBackdropTapas a per-modal override (bool?; null takes the per-flow default). -
A
modal tap ignoreddevtools log (categoryevent, leveldebug) with asourcetag, 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 requestedstill carries itssource(backdrop/close-button) unchanged.
Changed #
-
Breaking:
OpenKycOptionscallback 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 onretryable, never onreason. -
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 fromThemeData.colorScheme.surfacemeant the chrome followed one palette and the content another, and any difference read as a band of the wrong colour. Resolution iscolorOverrides['background']→backgroundColor→colorOverrides['surface']→ the ambient surface, shared withsdk-react-native. Only CSS hex forms parse; anything else falls back. -
PoweredByProphetXnow renders the real logo instead of plain text. It was a placeholder — a singleTextreading "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 aColorFilter, which would have flattened the gradient too.This follows the web component.
packages/sdk-react-nativestill draws a bold letter-spaced text wordmark, so RN is now the odd one out and should follow. -
Adds
flutter_svgas a dependency, to render that logo without hand-porting its Bezier paths to aCustomPainter— which would drift silently the next time branding changes. -
Breaking for two callers.
EmbedRoute.kyc.pathreturnsverifiedinstead ofkyc, andFlowOpenEvent/FlowCloseEventcarryflow: 'verified'instead offlow: 'kyc'for that flow. Both changes converge Flutter withsdk-js,sdk-reactandsdk-react-native, which all emitverifiedalready. Code that matched on the old string must be updated; theEmbedRoute.kycenum 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
depositorwithdraw; it still dismissesonboarding,kycandidUpload. 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 asmodal tap ignoredwithsource: 'backdrop-suppressed'atdebuglevel, so it is visible rather than merely inert. Override per modal withProphetXModal.dismissOnBackdropTap; the mapping lives onEmbedRoute.dismissOnBackdropTapDefaultand every route is pinned by a table intest/flows/dismiss_on_backdrop_tap_test.dart, so a new flow forces a decision. -
The active flow now renders in the root
Overlayinstead of aStackinsideProphetXProvider. 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 amodalBuilder; nothing needs re-providing. -
ProphetXProvidermust be mounted where anOverlayexists — i.e. insideMaterialApp(ashome:or below), which is what the test app and every realistic host already do. Mounted aboveMaterialAppthe SDK falls back to the old inlineStack, which no longer crashes on a missingDirectionalitybut cannot escape host chrome, and the real modal chrome will not render there at all because Flutter'sTooltipitself requires anOverlayancestor.
Fixed #
-
The sheet now closes on
PROPHETX_CANCEL. It handed the WebViewwidget.onCancelalone, 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. AScaffoldancestor stripsviewInsets.bottomfrom theMediaQueryit hands its body (removeViewInsets, gated onresizeToAvoidBottomInset, defaulttrue) and lays that body out smaller while leavingMediaQuery.sizeat 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, whichtest/sheet_layout_matrix_test.dartasserts 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
kycflow pointed at/kyc, which the embed does not register. With nonotFoundComponentthe SPA answered 200 with a blank shell, soPROPHETX_READYnever arrived and the modal's loading overlay hung forever instead of erroring.EmbedRoute.kyc.pathis nowverified— 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 ashttps://host///producedhttps://host///withdraw. Every trailing slash is now removed. Leading slashes on the route are stripped as well, sodepositand/depositbuild 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. Nowflutter-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:
eventsis aProphetXEventBus(subscribe via.stream), not aStream<ProphetXEvent>;authandwalletare nullable and only exist whenauth:is passed to the provider. Coding the old table literally was a compile error.idUploadand theonSessionExpired/devtoolsprovider parameters were missing entirely. - Built-in environment
embedUrls no longer carry a trailing slash, matchingsdk-core/src/env/env-config.ts. No behaviour change here —_fullEmbedUrlalready normalized — but the JS SDKs concatenate${embedUrl}/${route}and were emittinghttps://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).idUploadwithOpenIdUploadOptions(redirectUrl, onKycSuccess, onKycFailed, onKycPending, …). The vendor form cannot be framed, so it opens in the device browser;redirectUrlshould be a deep link registered with the OS, or the user has no route back into the app. url_launcherdependency, used to perform that handoff.
Fixed #
- The hosted form never opened.
webview_flutterproduces no navigation request forwindow.openand silently drops it, soonNavigationRequestcould not catch it either. The bridge JS now overrideswindow.openand forwards the URL as__OPEN_URL__over the existing channel; Dart opens it withLaunchMode.externalApplication. onCancelnever fired for ID Upload — a non-exhaustiveswitchin_onModalCancelomittedIdUploadFlowOptions. Adding a sealed-class variant breaks every exhaustive switch and the compiler reports them one at a time.sandboxpointed at a dead host.isv-sandbox-api.betprophet.coresolves but refuses connections; nowisv-api.sandbox.prophetx.dev, matchingsdk-core._fullEmbedUrldiscarded any query already present onembedUrland could emit a second?. Now parsed and merged viaUri.
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. ProphetXProviderroot widget with deposit, withdraw, onboarding, and KYC flow controllers.AuthManager(Unauthenticated/Authenticating/Authenticated/Expired/AuthError) with auto-refresh.WalletClient.refetch()againstGET /api/v1/wallet.ProphetXEventBusexposingReadyEvent,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, andsandbox.