flutter_hylid_bridge

A Flutter wrapper for the Hylid Bridge JavaScript SDK, providing seamless integration with Hylid's payment, authentication, and UI services on web platforms.

Features

• Payment Integration: Process payments using Hylid's trade pay system
• Authentication: Get auth codes with customizable scopes
• UI Components: Display native-style alerts
• Automatic Script Loading: Zero configuration - the Hylid Bridge script is automatically injected on web
• Cross-Platform: Works on web with graceful no-op on mobile/desktop
• Type-Safe: Full Dart type safety with proper result types

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_hylid_bridge: ^0.0.1

Then run:

flutter pub get

Usage

Basic Setup

No setup required! Just import and use:

import 'package:flutter_hylid_bridge/hylid_bridge.dart';

The Hylid Bridge JavaScript library will be automatically loaded when you use any API method on web platforms.

Payment

Process a payment using the tradePay function:

import 'package:flutter_hylid_bridge/hylid_bridge.dart';

await tradePay(
  paymentUrl: 'https://your-payment-url.com/pay?params=...',
  success: (TradePayResult result) {
    print('Payment successful: ${result.resultCode?.toDart}');
  },
  fail: (TradePayResult result) {
    print('Payment failed: ${result.resultCode?.toDart}');
  },
  complete: (TradePayResult result) {
    print('Payment completed');
  },
);

Authentication

Get an authorization code:

import 'package:flutter_hylid_bridge/hylid_bridge.dart';

await getAuthCode(
  scopes: ['auth_user', 'auth_profile'],
  success: (AuthCodeResult result) {
    final authCode = result.authCode?.toDart;
    print('Auth code: $authCode');
  },
  fail: () {
    print('Authentication failed');
  },
  complete: () {
    print('Authentication flow completed');
  },
);

UI - Alert Dialog

Display a native-style alert:

import 'package:flutter_hylid_bridge/hylid_bridge.dart';

await alert(
  title: 'Success',
  content: 'Your operation was successful!',
  buttonText: 'OK',
  success: () {
    print('User clicked OK');
  },
);

Organized Imports

You can import specific categories instead of everything:

// Import only payment APIs
import 'package:flutter_hylid_bridge/payment.dart';

// Import only authentication APIs
import 'package:flutter_hylid_bridge/auth.dart';

// Import only UI APIs
import 'package:flutter_hylid_bridge/ui.dart';

Platform Support

Platform	Support
Web	✓
Android	-
iOS	-
macOS	-
Windows	-
Linux	-

The package is designed for web platforms where the Hylid Bridge JavaScript SDK operates. On non-web platforms, all methods will execute without errors but won't perform any actions.

How It Works

Automatic Script Injection

When you use any API method on web:

1. The package automatically checks if the Hylid Bridge script is loaded
2. If not loaded, it injects the script tag into the DOM
3. Waits for the script to load completely
4. Executes your API call
5. Subsequent calls use the already-loaded script (no re-loading)

No manual script tags in index.html required!

Web vs Mobile

The package uses conditional imports to provide:

• Web: Full implementation with automatic script loading
• Mobile/Desktop: Stub implementation (no-op)

This ensures your app compiles and runs on all platforms without platform-specific code.

API Reference

Payment

tradePay

Future<void> tradePay({
  String? paymentUrl,
  void Function(TradePayResult result)? success,
  void Function(TradePayResult result)? fail,
  void Function(TradePayResult result)? complete,
})

Process a payment transaction.

Parameters:

• paymentUrl: The payment URL provided by your backend
• success: Called when payment succeeds
• fail: Called when payment fails
• complete: Called when payment flow completes (success or fail)

Authentication

getAuthCode

Future<void> getAuthCode({
  required List<String> scopes,
  void Function(AuthCodeResult result)? success,
  void Function()? fail,
  void Function()? complete,
})

Request an authorization code with specified scopes.

Parameters:

• scopes: List of authorization scopes to request
• success: Called with the auth code on success
• fail: Called when authorization fails
• complete: Called when authorization flow completes

UI

alert

Future<void> alert({
  String? title,
  String? content,
  String? buttonText,
  void Function()? success,
  void Function()? fail,
  void Function()? complete,
})

Display a native-style alert dialog.

Parameters:

• title: Alert title
• content: Alert message
• buttonText: Text for the button (default: "OK")
• success: Called when user dismisses the alert
• fail: Called if alert fails to display
• complete: Called when alert flow completes

Example

See the example directory for a complete sample app demonstrating all features.

Important Notes

• All API methods are asynchronous and return Future<void>
• Make sure to await the calls or handle the Future properly
• On web, the Hylid Bridge script is loaded from: https://cdn.marmot-cloud.com/npm/hylid-bridge/2.10.0/index.js
• Callbacks receive JavaScript interop types - use .toDart to convert to Dart types

License

MIT License - see the LICENSE file for details.

Issues and Feedback

Please file issues, bugs, or feature requests in our issue tracker.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.