@outerjoyn/react

React components for the OuterJoyn SDK. Thin bindings around the vanilla JS SDK, similar to @stripe/react-stripe-js.

Installation

npm install @outerjoyn/react @outerjoyn/js

Quick Start

1. Load the SDK

Add the OuterJoyn script tag or import @outerjoyn/js:

<script src="https://js.outerjoyn.com/v1/outerjoyn.js"></script>

2. Wrap with Provider

import { OuterJoynProvider } from '@outerjoyn/react';

function App() {
  return (
    <OuterJoynProvider
      sessionToken="ojsdk_live_..."
      onReady={(ctx) => console.log('SDK ready, member:', ctx.memberId)}
    >
      <CheckoutPage />
    </OuterJoynProvider>
  );
}

3. Use Widget Components

import { PayWithPoints } from '@outerjoyn/react';

function CheckoutPage() {
  const [remaining, setRemaining] = useState(4999);

  return (
    <PayWithPoints
      orderTotal={4999}
      onPointsChanged={(state) => setRemaining(state.remainingOrderCents)}
      onReady={({ programCount }) => {
        if (programCount === 0) console.log('No linked programs');
      }}
    />
  );
}

Available Components

Widgets

| Component | SDK Module | Description | |-----------|-----------|-------------| | <PayWidget /> | pay | Generic pay-with-points (pass-through props) | | <PayWithPoints /> | pay | Typed pay widget with orderTotal, onPointsChanged | | <ConnectWidget /> | connect | Link loyalty accounts (Plaid Link-style) | | <ExchangeWidget /> | exchange | Exchange points between programs | | <RedeemWidget /> | redeem | Redeem rewards from catalog | | <AccountWidget /> | account | Member account overview | | <WalletPassWidget /> | walletPass | Add to Apple/Google Wallet | | <PromotionsWidget /> | promotions | Display promotion arrays |

Provider

<OuterJoynProvider
  sessionToken="ojsdk_live_..."  // Required
  apiBaseUrl="https://api.outerjoyn.com"  // Optional override
  onReady={(ctx) => {}}  // Optional
  onError={(err) => {}}  // Optional
>
  {children}
</OuterJoynProvider>

Hook

import { useOuterJoyn } from '@outerjoyn/react';

function MyComponent() {
  const { sdk, loading, error } = useOuterJoyn();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  // Access SDK modules directly when needed
  const balance = await sdk.pay.getBalance?.();
}

How It Works

1. <OuterJoynProvider> finds window.OuterJoyn (set by @outerjoyn/js)
2. Calls OuterJoyn.init({ sessionToken }) to validate the session
3. Widget components use useOuterJoyn() to get the SDK instance
4. Each widget renders a container <div> and calls sdk.{module}.open({ container })
5. On unmount, calls close() to clean up the widget

All widgets render inline (not as modals) since they mount into a React-managed container div.