inqud-recurring-api

Recurring Data Provider

This repository provides a recurring data provider for integrating subscription-based payment systems into your React application. It is a React context-based solution that helps manage wallet connection, subscription plan selection, network and currency settings, and the payment process for recurring subscriptions.

Features

• Wallet Connection: Allows users to connect their wallets (e.g., MetaMask).
• Network and Currency Management: Select different blockchains and currencies for payments.
• Subscription Management: Handle different subscription states, such as active, pending, failed, and cancelled.
• Recurring Payment Integration: Easily integrate recurring payment functionality with necessary hooks and contexts.

Installation

You can install the package from npm:

npm install inqud-recurring-api

RecurringDataProvider API Description

This library provides a context-based solution for managing subscriptions, wallet connections, network selection, and recurring payments. It leverages wagmi for Ethereum wallet connection management and offers hooks for interacting with recurring subscription states and transactions.

---

Key Components and Hooks

1. RecurringDataProvider

A React provider that wraps the application and provides recurring subscription data context.

Props:

• planId: ID of the subscription plan to be managed.
• clientOrderId: Unique identifier for the client's order.
• projectId: Your project ID for tracking.
• baseUrl: The base URL for API calls (not provided in the example code but should be configured in a real application).

Usage:

Wrap the root component of your application with RecurringDataProvider to provide subscription data throughout the app.

<RecurringDataProvider planId="12345" clientOrderId="abc123" projectId="project_id" baseUrl="https://api.example.com">
  <YourApp />
</RecurringDataProvider>

2. useRecurringData

A custom hook to access the context provided by RecurringDataProvider. This hook provides various states and methods to manage subscription data.

Returned Value:

• account: User's account information.
• address: Wallet address of the user.
• plan: The current subscription plan.
• isConnected: Whether the wallet is connected.
• state: Current subscription state (e.g., active, pending, failed).
• currency: The selected currency for payment.
• selectedNetwork: The selected blockchain network for payment.
• handlePayClick: Function to trigger payment.
• loading: Boolean indicating loading state.
• error: Error message if any operation fails.

Usage:

const { plan, state, loading, error } = useRecurringData();

if (loading) {
  return <LoadingSpinner />;
}

return (
  <div>
    {state === RecurringState.notConnected && <PlanDetailsCard />}
    {state === RecurringState.connected && <SubscriptionCard />}
    {state === RecurringState.active && <SuccessCard />}
    {state === RecurringState.failed && <FailedCard />}
    {/* Additional UI logic */}
  </div>
);

Returned Value:

• account: User's account information.
• address: Wallet address of the user.
• plan: The current subscription plan.
• isConnected: Whether the wallet is connected.
• state: Current subscription state (e.g., active, pending, failed).
• currency: The selected currency for payment.
• selectedNetwork: The selected blockchain network for payment.
• handlePayClick: Function to trigger payment.
• loading: Boolean indicating loading state.
• error: Error message if any operation fails.
• setCurrency: Method to set the selected currency.
• setSelectedNetwork: Method to set the selected blockchain network for payment.
• noNetwork: Boolean indicating if no network is selected or supported.
• disconnect: Function to disconnect the current wallet.
• setLimit: Method to set a spending limit.
• isSubscription: Boolean indicating whether the user has an active subscription.
• duration: The duration for which the user is subscribing.
• setDuration: Method to set the subscription duration.
• networks: Available networks for the subscription.
• balanceData: Data about the user's balance.
• limitFormatted: Formatted display of the user's spending limit.
• noBalance: Boolean indicating if the user has insufficient balance.

Usage:

const {
  setCurrency,
  setSelectedNetwork,
  noNetwork,
  selectedNetwork,
  currency,
  plan,
  address,
  disconnect,
  error,
  loading,
  setLimit,
  handlePayClick,
  isSubscription,
  duration,
  setDuration,
  networks,
  balanceData,
  limit,
  limitFormatted,
  noBalance,
} = useRecurringData();

return (
  <div className="h-full flex flex-col">
    {/* Select Network */}
    <div className="mb-4">
      <p className="text-xs font-bold text-independent-grey">Select network</p>
      <CheckboxGroup
        networks={values(networks)}
        radio
        selectedNetwork={selectedNetwork}
        onChange={setSelectedNetwork}
      />
    </div>

    {/* Select Currency */}
    {selectedNetwork && (
      <div className="mb-4">
        <p className="text-xs font-bold text-independent-grey">Select currency</p>
        <Select
          className="w-full"
          currencies={selectedNetwork.currencies}
          selectedCurrency={currency}
          onSelect={setCurrency}
          disabled={!!error}
        />
      </div>
    )}
    
    {/* Connect Button */}
    <div className="mt-auto">
      <ConnectButtonComponent.Custom>
        {({ openConnectModal }: any) => (
          <Button
            className="w-full"
            onClick={openConnectModal}
            loading={loading}
          >
            Connect wallet
          </Button>
        )}
      </ConnectButtonComponent.Custom>
    </div>
    
    {/* Wallet Address */}
    {address && (
      <div className="flex flex-col mb-4">
        <div className="color-main-black text-[12px]">Wallet address</div>
        <div className="flex justify-between border-independent-grey border-[1px] rounded-[8px] p-2">
          <p>{shortenWithDotsBetween(address, 20)}</p>
          <button onClick={() => disconnect()}>Disconnect</button>
        </div>
      </div>
    )}

    {/* Balance Display */}
    {currency && balanceData && (
      <div className="flex justify-between">
        <p>Your wallet balance</p>
        <p>{balanceData.formatted ? `${balanceData.formatted} ${currency.currency}` : ''}</p>
      </div>
    )}

    {/* Limit and Duration Controls */}
    {isSubscription && (
      <div className="flex gap-1 justify-center">
        <Input value={isSubscription ? limitFormatted : '∞'} label={`Spending limit to this service`} />
        <CountSelector value={duration} disabled={!isSubscription} onChange={setDuration} />
      </div>
    )}

    {/* Pay Button */}
    <Button
      onClick={handlePayClick}
      loading={loading}
      disabled={!currency || !selectedNetwork || noBalance}
    >
      {isSubscription ? 'Pay and subscribe' : 'Allow spending'}
    </Button>
  </div>
);