@oms/api-client

React Query hooks for the OMS API. This package provides type-safe API client with hooks for both public (e-commerce) and admin (internal) endpoints.

Installation

npm install @oms/api-client
# or
pnpm add @oms/api-client

Usage

1. Setup Provider

Wrap your app with ApiClientProvider:

import { ApiClientProvider } from '@oms/api-client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ApiClientProvider baseURL="https://api.yoursite.com">
        <YourApp />
      </ApiClientProvider>
    </QueryClientProvider>
  );
}

2. Use Hooks

Orders Example

import { useGetOrder, useConfirmOrder } from '@oms/api-client';

function OrderConfirmation() {
  const { orderId, token } = useParams();

  // Get order details
  const { data, isLoading } = useGetOrder(orderId, token);

  // Confirm order
  const confirmMutation = useConfirmOrder({
    onSuccess: () => {
      console.log('Order confirmed!');
    }
  });

  return (
    <div>
      <h1>Order #{data?.order.orderNumber}</h1>
      <button onClick={() => confirmMutation.mutate({ orderId, token })}>
        Confirm Order
      </button>
    </div>
  );
}

Products Example

import { useGetProducts } from '@oms/api-client';

function ProductList({ brandId }) {
  const { data, isLoading } = useGetProducts(brandId);

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {data?.products.map(product => (
        <div key={product.id}>
          <h3>{product.name}</h3>
          <p>{product.description}</p>
        </div>
      ))}
    </div>
  );
}

Cart & Checkout Example

import {
  useGetCart,
  useCreateCart,
  useAddToCart,
  useRemoveCartItem,
  useCheckout
} from '@oms/api-client';

function ShoppingCart() {
  const [cartId, setCartId] = useState<string | null>(null);
  const { data: cart } = useGetCart(cartId!, { enabled: !!cartId });

  const createCart = useCreateCart({
    onSuccess: (data) => setCartId(data.cart.id)
  });

  const addToCart = useAddToCart(cartId!, {
    onSuccess: () => {
      // Cart is automatically updated via React Query
    }
  });

  const removeItem = useRemoveCartItem(cartId!, '');

  const checkout = useCheckout(cartId!, {
    onSuccess: (data) => {
      console.log('Order created:', data.order.id);
    }
  });

  const handleAddToCart = (sku: string, quantity: number) => {
    if (!cartId) {
      createCart.mutate({
        brandId: 'your-brand-id',
        expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
      });
    } else {
      addToCart.mutate({ sku, quantity });
    }
  };

  const handleCheckout = (customerInfo) => {
    checkout.mutate({
      ...customerInfo,
      paymentMethod: 'cod'
    });
  };

  return (
    <div>
      {cart?.items.map(item => (
        <div key={item.id}>
          <span>{item.variant.product.name} x {item.quantity}</span>
          <button onClick={() => removeItem.mutate()}>Remove</button>
        </div>
      ))}
      <button onClick={() => handleCheckout(formData)}>
        Checkout
      </button>
    </div>
  );
}

Admin Hooks (Internal OMS)

// Coming soon - admin hooks will be added here
// import { useGetOrders, useUpdateOrder } from '@oms/api-client/admin';

3. Custom Error Handling

<ApiClientProvider
  baseURL="https://api.yoursite.com"
  onError={(error) => {
    console.error('API Error:', error.message);
    // Show toast notification, etc.
  }}
>
  <App />
</ApiClientProvider>

Available Hooks

Public Hooks

Orders

• useGetOrder(orderId, token, options?) - Get order details by ID and token
• useConfirmOrder(options?) - Confirm a prospect order

Products

• useGetProducts(brandId, options?) - Get all products for a brand

Carts

• useGetCart(cartId, options?) - Get cart details by ID
• useCreateCart(options?) - Create a new cart
• useAddToCart(cartId, options?) - Add item to cart by SKU
• useRemoveCartItem(cartId, itemId, options?) - Remove item from cart
• useApplyDiscount(cartId, options?) - Apply discount code to cart
• useRemoveDiscount(cartId, options?) - Remove discount from cart
• useCheckout(cartId, options?) - Checkout cart and create order

Delivery Zones

• useGetDeliveryZones(params?, options?) - Get delivery zones with optional filters

Admin Hooks

Coming soon! Will include hooks for:

• Orders management
• Inventory management
• Products management
• Brands management

Type Safety

All hooks are fully typed using OpenAPI-generated types from @oms/types. TypeScript will autocomplete and validate all API requests and responses.

Advanced Usage

Query Keys

Access query keys for manual cache invalidation:

import { queryKeys } from '@oms/api-client';
import { useQueryClient } from '@tanstack/react-query';

function MyComponent() {
  const queryClient = useQueryClient();

  // Invalidate specific order
  queryClient.invalidateQueries({
    queryKey: queryKeys.public.orders.detail(orderId, token)
  });

  // Invalidate all orders
  queryClient.invalidateQueries({
    queryKey: queryKeys.public.orders.all
  });
}

Direct API Client Access

For advanced use cases, access the axios client directly:

import { getApiClient } from '@oms/api-client';

const client = getApiClient();
const response = await client.get('/custom-endpoint');

Development

Updating Types

When the backend API changes, regenerate types:

# From the monorepo root
cd packages/types
pnpm run generate

License

ISC