npm package: @meaple-com/react-query
Description: React Query hooks for Meaple SDK
Latest version: 1.1.1

# @meaple-com/react-query

React Query (TanStack Query) hooks for the [Meaple](https://meaple.com) ticketing platform. Fetch and mutate Meaple data in React with caching, loading and error states.

## Installation

```bash
npm install @meaple-com/react-query @meaple-com/core @meaple-com/types
# or
pnpm add @meaple-com/react-query @meaple-com/core @meaple-com/types
# or
bun add @meaple-com/react-query @meaple-com/core @meaple-com/types
```

**Peer dependencies:**

- `react` ^19.0.0  
- `@tanstack/react-query` ^5.90.7  
- `axios` ^1.12.2  
- `date-fns` ^4.0.0  

Install them if not already in your project.

## Setup

Wrap your app with `QueryClientProvider` (from TanStack Query) and `MeapleSDKProvider`:

```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { MeapleSDKProvider } from '@meaple-com/react-query';
import { MeapleSDK } from '@meaple-com/core';

const queryClient = new QueryClient();
const sdk = new MeapleSDK({
  publicKey: 'YOUR_CHANNEL_ID',
  baseURL: 'https://api.meaple.com',
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MeapleSDKProvider sdk={sdk}>
        {/* Your app */}
      </MeapleSDKProvider>
    </QueryClientProvider>
  );
}
```

Optional: set the user token when they log in:

```tsx
sdk.setGlobalToken('user-jwt-token');
```

## Hooks

All hooks use the SDK from `MeapleSDKProvider` and return standard TanStack Query results (`data`, `isPending`, `error`, `refetch`, etc.). You can pass the same options as `useQuery` / `useMutation` (e.g. `enabled`, `staleTime`).

### Events

- **`useEvents(params?, options?)`** – List events  
- **`useEvent(eventId, slug, options?)`** – Single event  
- **`useEventTickets(eventId, slug, options?)`** – Event tickets  
- **`useEventProducts(eventId, slug, options?)`** – Event products  

### Categories

- **`useCategories(options?)`** – List categories  

### Coupon

- **`useCheckCoupon()`** – Mutation to validate a coupon (code + eventId)  

### Orders

- **`useOrder(orderId, options?)`** – Single order  
- **`useUserOrders(params?, options?)`** – Current user orders  
- **`useCreateOrder()`** – Mutation to create an order  

### Payments

- **`usePlatformFee(eventId, amount?, options?)`** – Platform fee for an amount  

### Tickets (user)

- **`useUserEvents(params?, options?)`** – Current user events  
- **`useUserEventTickets(eventId, options?)`** – Current user tickets for an event  
- **`useTransferTicket()`** – Mutation to transfer a ticket  
- **`useEditUserTicket()`** – Mutation to edit user ticket  
- **`useCreateTicketFile()`** – Mutation to create ticket file  
- **`useRefundUserOrder()`** – Mutation to refund user order  

### Context

- **`useMeapleSDK()`** – Access the Meaple SDK instance (throws if used outside `MeapleSDKProvider`)  

## Example

```tsx
import { useEvents, useEvent } from '@meaple-com/react-query';

function EventList() {
  const { data, isPending, error } = useEvents({ limit: 20 });

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

  return (
    <ul>
      {data?.events.map((event) => (
        <li key={event.id}>{event.name}</li>
      ))}
    </ul>
  );
}

function EventDetail({ eventId, slug }: { eventId: string; slug: string }) {
  const { data: event } = useEvent(eventId, slug);
  // ...
}
```

## With headless components

Use `@meaple-com/react-headless-components` for render-props components that call these hooks and expose `data`, `isPending`, `error` (and mutations where relevant), so you can focus on styling and layout.

## Documentation

[https://docs.meaple.com.br/](https://docs.meaple.com.br/)