React Hooks

The SDK provides React hooks powered by TanStack Query for data fetching, caching, and mutations.

Setup

npm install @tanqory/sdk @tanstack/react-query

Wrap your app with TanqoryProvider:

import { createClient } from '@tanqory/sdk'
import { TanqoryProvider } from '@tanqory/sdk/react'

const tanqory = createClient({ apiKey: 'pk_live_...' })

function App() {
  return (
    <TanqoryProvider client={tanqory}>
      <MyApp />
    </TanqoryProvider>
  )
}

TanqoryProvider sets up both the Tanqory client context and a QueryClientProvider internally.

Available Hooks

Products

import { useProducts, useProduct } from '@tanqory/sdk/react'

function ProductList({ storeId }: { storeId: string }) {
  const { data, isLoading, error } = useProducts(storeId, {
    status: 'ACTIVE',
    limit: 50,
  })

  if (isLoading) return <Spinner />
  if (error) return <ErrorMessage error={error} />

  return data.data.map(product => (
    <ProductCard key={product.id} product={product} />
  ))
}

function ProductDetail({ storeId, productId }: { storeId: string; productId: string }) {
  const { data: product } = useProduct(storeId, productId)
  return <h1>{product?.title}</h1>
}

Orders

import { useOrders, useOrder } from '@tanqory/sdk/react'

const { data } = useOrders(storeId, { status: 'UNFULFILLED' })
const { data: order } = useOrder(storeId, orderId)

Customers

import { useCustomers, useCustomer } from '@tanqory/sdk/react'

const { data } = useCustomers(storeId, { search: 'john' })
const { data: customer } = useCustomer(storeId, customerId)

Inventory

import { useInventory } from '@tanqory/sdk/react'

const { data } = useInventory(storeId, { stockStatus: 'low_stock' })

Auth

import { useAuth, useCurrentUser } from '@tanqory/sdk/react'

const { login, logout, isAuthenticated } = useAuth()
const { data: user } = useCurrentUser()

Mutations

Hooks for write operations return TanStack Query mutations:

import { useCreateProduct, useUpdateProduct, useDeleteProduct } from '@tanqory/sdk/react'

function CreateProductButton({ storeId }: { storeId: string }) {
  const { mutate, isPending } = useCreateProduct(storeId)

  const handleCreate = () => {
    mutate(
      { title: 'New Product', price: 2999, status: 'DRAFT' },
      {
        onSuccess: (product) => {
          console.log('Created:', product.id)
        },
        onError: (error) => {
          console.error(error.message)
        },
      }
    )
  }

  return <button onClick={handleCreate} disabled={isPending}>Create Product</button>
}

Invalidation

Mutations automatically invalidate related queries. After creating a product, the useProducts query refetches:

const { mutate: createProduct } = useCreateProduct(storeId)
// After success, useProducts(storeId) automatically refetches

Custom Query Options

All hooks accept TanStack Query options as the last parameter:

const { data } = useProducts(storeId, { status: 'ACTIVE' }, {
  staleTime: 60_000,       // Cache for 1 minute
  refetchInterval: 30_000, // Poll every 30 seconds
  enabled: !!storeId,      // Only fetch when storeId is available
})

Hook Reference

Hook	Description
useProducts / useProduct	List / retrieve products
useOrders / useOrder	List / retrieve orders
useCustomers / useCustomer	List / retrieve customers
useInventory	List inventory levels
useDiscounts / useDiscount	List / retrieve discounts
useAnalytics	Run analytics queries
useAuth	Login, logout, auth state
useCurrentUser	Get current user
useCreateProduct	Create product mutation
useUpdateProduct	Update product mutation
useDeleteProduct	Delete product mutation