rd_catalogue 0.1.0-beta.1

A Flutter package for the Redeemly Catalogue API

rd_catalogue

Official Redeemly Flutter package for browsing, purchasing, and managing digital vouchers.

Features

• Browse vouchers from Redeemly catalogue API
• View voucher details
• Select quantity and confirm purchase
• Integrate custom payment logic
• Automatic voucher pull via Redeemly API
• Voucher success screen
• Customer logs (My Vouchers)
• HTML-based "How to Use" rendering
• Clean and customizable UI
• Fully self-contained navigation flow

Installation

Add rd_catalogue to your pubspec.yaml:

dependencies:
  rd_catalogue: ^0.1.0

Then run:

flutter pub get

Usage

Basic Setup

1. Initialize the package configuration:

import 'package:rd_catalogue/rd_catalogue.dart';

void main() {
  // Initialize the package before using any pages
  RdCatalogueConfig.initialize(
    RdCatalogueOptions(
      baseUrl: 'https://api.redeemly.com/api/v1',
      language: RdLanguage.en, // or RdLanguage.ar
      debugToken: 'your-jwt-token', // Optional, for testing
      enableLogs: true, // Optional, defaults to true
    ),
  );
  
  runApp(MyApp());
}

2. Use the vouchers page:

import 'package:flutter/material.dart';
import 'package:rd_catalogue/rd_catalogue.dart';

class MyVouchersPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return RdVouchersPage(
      options: RdCatalogueOptions(
        baseUrl: 'https://api.redeemly.com/api/v1',
        language: RdLanguage.en,
        enableLogs: true,
      ),
      onConfirmPurchase: (context, voucher, quantity, totalPrice) async {
        // Implement your payment logic here
        // This callback is called when user confirms purchase
        
        // Example: Process payment
        final paymentResult = await processPayment(totalPrice);
        
        if (paymentResult.success) {
          // Return success with order references
          return RdPurchaseAuthSuccess(
            orderRef: paymentResult.orderRef,
            customerRef: paymentResult.customerRef,
            tranRef: paymentResult.tranRef,
          );
        } else {
          // Return cancelled if payment failed
          return const RdPurchaseAuthCancelled();
        }
      },
    );
  }
}

Custom Payment Integration

The onConfirmPurchase callback allows you to integrate your own payment system:

onConfirmPurchase: (context, voucher, quantity, totalPrice) async {
  // Show your payment UI
  final result = await Navigator.push(
    context,
    MaterialPageRoute(
      builder: (context) => YourPaymentPage(
        amount: totalPrice,
        voucher: voucher,
      ),
    ),
  );
  
  if (result is PaymentSuccess) {
    return RdPurchaseAuthSuccess(
      orderRef: result.orderId,
      customerRef: result.customerId,
      tranRef: result.transactionId,
    );
  }
  
  return const RdPurchaseAuthCancelled();
}

Customer Logs (My Vouchers)

Navigate to the customer logs page:

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => RdCatalogueLogsPage(
      language: RdLanguage.en,
    ),
  ),
);

Configuration Options

RdCatalogueOptions

• baseUrl (required): The base URL for the Redeemly API
• language (required): Language preference (RdLanguage.en or RdLanguage.ar)
• debugToken (optional): JWT token for testing/development
• timeout (optional): HTTP request timeout (default: 30 seconds)
• enableLogs (optional): Enable debug logging (default: true)
• headersBuilder (optional): Custom headers builder function
• onConfirmPurchase (optional): Callback for purchase confirmation

Models

RdCatalogueVoucher

Represents a voucher in the catalogue:

final voucher = RdCatalogueVoucher(
  id: 1,
  name: 'Premium Dining Voucher',
  sellPrice: 100.0,
  availableCount: 10,
  // ... other fields
);

RdPurchaseAuthResult

Result of purchase authorization:

• RdPurchaseAuthSuccess: Contains orderRef, customerRef, tranRef
• RdPurchaseAuthCancelled: Indicates purchase was cancelled

RdPulledVoucherItem

Represents a voucher item returned from the pull API:

final item = RdPulledVoucherItem(
  serialCode: 'VCH-123456',
  serialNumber: 'SN-789',
  voucherName: 'Premium Dining Voucher',
  // ... other fields
);

Pages

RdVouchersPage

Main page displaying the list of available vouchers.

RdCatalogueLogsPage

Page displaying customer's issued vouchers (My Vouchers).

Error Handling

The package provides custom exceptions:

• RdCatalogueApiException: API-related errors
• RdCatalogueNetworkException: Network connectivity errors
• RdCatalogueParsingException: Data parsing errors

Handle errors appropriately in your application:

try {
  // Use package features
} on RdCatalogueApiException catch (e) {
  // Handle API errors
} on RdCatalogueNetworkException catch (e) {
  // Handle network errors
} catch (e) {
  // Handle other errors
}

Internationalization

The package supports English and Arabic:

RdCatalogueOptions(
  language: RdLanguage.en, // English
  // or
  language: RdLanguage.ar, // Arabic
)

Requirements

• Flutter SDK: >=1.17.0
• Dart SDK: ^3.9.2

Example

See the example directory for a complete working example.

License

This package is licensed under the MIT License. See the LICENSE file for details.

Support

For issues, questions, or contributions, please visit:

• Homepage
• GitHub Issues

Additional Information

This package is part of the Redeemly ecosystem and integrates seamlessly with Redeemly's voucher management platform.