@devx-commerce/loyaltyx-hooks

React Query hooks for the LoyaltyX loyalty engine. Wraps @devx-commerce/loyaltyx-api-client with TanStack Query v5 — caching, background refetch, optimistic mutations, and shared query keys for cross-component invalidation.

Use this when you're building a React-based admin dashboard or storefront experience that talks to LoyaltyX.

Install

pnpm add @devx-commerce/loyaltyx-hooks @devx-commerce/loyaltyx-api-client @devx-commerce/loyaltyx-core
# or
npm install @devx-commerce/loyaltyx-hooks @devx-commerce/loyaltyx-api-client @devx-commerce/loyaltyx-core

Peer dependencies your app must already have:

pnpm add react @tanstack/react-query

Requires react ≥ 18 and @tanstack/react-query ≥ 5.

Setup

Wrap your app once with both QueryClientProvider (from @tanstack/react-query) and LoyaltyProvider:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { LoyaltyClient } from '@devx-commerce/loyaltyx-api-client';
import { LoyaltyProvider } from '@devx-commerce/loyaltyx-hooks';

const queryClient = new QueryClient();
const loyaltyClient = new LoyaltyClient('https://loyalty.your-brand.com/api/v1');

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <LoyaltyProvider client={loyaltyClient}>
        <YourDashboard />
      </LoyaltyProvider>
    </QueryClientProvider>
  );
}

Usage

import { useCustomers, useAdjustPoints } from '@devx-commerce/loyaltyx-hooks';

function CustomersList() {
  const { data, isLoading, error } = useCustomers({ page: 1, limit: 20 });
  const adjust = useAdjustPoints();

  if (isLoading) return <Spinner />;
  if (error) return <ErrorBox err={error} />;

  return (
    <ul>
      {data.items.map((c) => (
        <li key={c.id}>
          {c.name} — {c.currentPoints} pts
          <button onClick={() => adjust.mutate({ id: c.id, points: 100, reason: 'Bonus' })}>
            +100
          </button>
        </li>
      ))}
    </ul>
  );
}

Mutation hooks auto-invalidate related queries on success — no manual cache-bust needed for the common case.

Available hooks

| Category | Hooks | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Auth | useMe, useLogin, useLogout, useChangePassword | | Tiers | useTiers, useTier, useCreateTier, useUpdateTier, useDeleteTier | | Earning Rules | useEarningRules, useCreateEarningRule, useUpdateEarningRule, useDeleteEarningRule | | Spending Rules | useSpendingRules, useCreateSpendingRule, useUpdateSpendingRule, useDeleteSpendingRule | | Customers | useCustomers, useCustomer, useOverrideTier, useAdjustPoints | | Ledger / Analytics | useLedger, useAnalytics | | Config | useConfig, useUpdateConfig | | Channel Mappings | useChannelMappings, useBulkSaveChannelMappings | | Users | useUsers, useCreateUser, useUpdateUser, useDeleteUser | | Connectors | useShopifyConfig, useUpdateShopifyConfig, useNectorConfig, useUpdateNectorConfig, useKwikengageConfig, useUpdateKwikengageConfig | | Import | useImports, useImport, useImportTemplate, useImportErrors, usePresignedUploadUrl, useCreateImport, useStartImport, useCancelImport | | Export | useExports, useExport, useCreateExport |

Query keys

For manual invalidation or selective prefetching:

import { useQueryClient } from '@tanstack/react-query';
import { loyaltyKeys } from '@devx-commerce/loyaltyx-hooks';

const qc = useQueryClient();
qc.invalidateQueries({ queryKey: loyaltyKeys.customers.all });
qc.invalidateQueries({ queryKey: loyaltyKeys.tiers.detail(tierId) });

Sibling packages

| Package | Purpose | | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | @devx-commerce/loyaltyx-core | Shared types + zod schemas | | @devx-commerce/loyaltyx-api-client | The HTTP client these hooks wrap | | @devx-commerce/loyaltyx-ui-kit | Pre-built React admin components that use these hooks |

License

Apache-2.0 — see LICENSE.