Wheelhouse Embed Library

Installation

npm i @wheelhouse/embed

Peer dependencies

Outside of the library's api and types exports, peer dependencies are required.

The host application must install compatible versions of several packages alongside @wheelhouse/embed. They are declared as peers (not bundled inside this package) so you get one shared instance of React, TanStack Query, and i18next. If the library shipped its own copies, you could end up with multiple React trees, separate QueryClient instances (broken cache and hooks), or separate i18n instances (wrong translations).

Exact semver ranges live in package.json under peerDependencies. Some peers are also marked optional there so non-React or types-only installs are not forced to pull them in; when you need a package for your integration is separate from that npm flag—use the table below.

| Package | When you need it | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | react | Any React usage: DataProvider, ListingProvider, UIProvider, hooks, or @wheelhouse/embed/react or @wheelhouse/embed/react/ui. | | @tanstack/react-query | DataProvider, exported TanStack query/mutation hooks, or anything under ListingProvider (it assumes DataProvider above it). Not required for types-only or non-React consumers. | | react-dom | Only when using UIProvider and components from @wheelhouse/embed/react/ui (DOM/CSS UI). Not required for DataProvider, ListingProvider, or headless hooks alone—those only need react. | | i18next | Only when using UIProvider from @wheelhouse/embed/react/ui. Not required for DataProvider or ListingProvider alone. | | react-i18next | Only when using UIProvider. Pairs with i18next for the UI bundle. |

Typical React app with data + UI:

npm i @wheelhouse/embed react react-dom @tanstack/react-query i18next react-i18next

Use version ranges from peerDependencies. If you use Query or i18n in your host app, use the same packages and wire QueryClientProvider / I18nextProvider (or equivalent) so the app and the embed resolve one client and one i18n instance.

Basic Usage

| Exports | Import Path | Includes CSS? | Use Case | Dependencies | | ------------------- | ---------------------------- | ------------- | ------------------------------------------------- | ------------------------------- | | TypeScript types | @wheelhouse/embed/types | ❌ | Type declarations only | None | | API fetches | @wheelhouse/embed/api | ❌ | API helpers | types | | React logic (no UI) | @wheelhouse/embed/react | ❌ | Data, hooks, state mgmt, logic, bring your own UI | types, api (core in the future) | | React Components | @wheelhouse/embed/react/ui | ✅ | UI Components | types, api, react | | Web Components | @wheelhouse/embed/wc | ✅ | Native web component wrappers (future) | types, api, react, react/ui |

Authentication & Data

To make secure authenticated calls to the Wheelhouse API, three things are needed:

• Integrations API key (server)
• User API key (server, per user)
• Access token (client)

Only the access token should be sent down to the client, which gets used to make calls directly to the WH API from the browser.

To exchange the two server keys for an auth token, a secure server-to-server call needs to be made. This looks something like the following. The nonce is a random string that needs to be generated in the browser and utilized on subsequent requests with the access token.

// on your server behind an endpoint that the browser library can reach
const getAccessToken = async (nonce: string): Promise<AccessTokenResponse> => {
    const response = await fetch('https://app.usewheelhouse.com/api/v1/edge_embed/token', {
        method: 'POST',
        headers: {
            Accept: 'application/json',
            'X-Integration-Api-Key': process.env.WHEELHOUSE_INTEGRATION_API_KEY,
            'X-User-Api-Key': userApiKey,
            'X-Embed-Api-Nonce': nonce,
        },
    });

    if (!response.ok) {
        throw new Error('Failed to get access token');
    }

    return response.json() as unknown as AccessTokenResponse;
};

With React, it looks like the following. The DataProvider will generate the nonce, and it will utilize the returned access token to make subsequent API calls.

// fetchAccessToken is a call to your server that ends up calling something like getAccessToken above
<DataProvider getAccessToken={fetchAccessToken}>{children}</DataProvider>

Expiration / Invalidated Tokens

If the token is expired or invalidated, a new one must be obtained. The library will automatically call the function provided to the getAccessToken prop in an attempt to obtain a new token.

@wheelhouse/embed/react

These components can be used to manage data access and listing state management alongside your own React components.

DataProvider

Provides access to and management of Wheelhouse API data and caching. Required for usage with React components in @wheelhouse/embed/react/ui, or your own custom components using this library's React query and mutation hooks.

The context value can be obtained importing the useDataContext hook from @wheelhouse/embed/react.

React Query and Mutation Hooks

Exports of query hooks and mutations (Tanstack Query) are made available (must be used with a DataProvider).

This library's UI components have a dependency on these, but they can also be used directly for implementing custom UI.

ListingProvider

Utilities for fetching and updating listing settings, as well as previewing changes on the pricing chart. Required for listing specific React components in @wheelhouse/embed/react/ui.

The useListingProvider hook can be used when implementing your own React UI.

See Storybook for more information and usage.

@wheelhouse/embed/react/ui

The React UI components. See Storybook for complete information and usage.

Running Example Apps

export WHEELHOUSE_ACCESS_TOKEN="your_access_token_here" WHEELHOUSE_LISTING_ID="123"
npm run examples # development build
npm run examples:preview # production build
# OR
WHEELHOUSE_ACCESS_TOKEN="your_access_token" WHEELHOUSE_LISTING_ID="123" npm run examples

Note that these example apps do not hot-reload changes to the embed package, they must be rebuilt.

LLMs

For LLM context, see llms.txt.