@instockng/api-client 1.0.0

package/src/hooks/public/carts.ts

@@ -0,0 +1,298 @@
+/**
+ * Type-safe RPC hooks for cart operations
+ *
+ * These hooks use Hono RPC client with types directly from the backend,
+ * providing end-to-end type safety without code generation.
+ */
+
+import { useMutation, useQueryClient, UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+import { useQueryUnwrapped } from '../use-query-unwrapped';
+import { queryKeys } from '../../utils/query-keys';
+import {
+  fetchCart,
+  updateCart,
+  createCart,
+  addCartItem,
+  updateCartItem,
+  removeCartItem,
+  applyDiscount,
+  removeDiscount,
+  checkoutCart,
+} from '../../fetchers/carts';
+
+/**
+ * Hook to get cart by ID using RPC
+ *
+ * @param cartId - Cart UUID
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * const { data: cart, isLoading } = useGetCart('cart-123');
+ * console.log(cart?.cart.brand.name); // Fully typed!
+ * ```
+ */
+export function useGetCart(
+  cartId: string,
+  options?: Omit<UseQueryOptions<Awaited<ReturnType<typeof fetchCart>>, Error>, 'queryKey' | 'queryFn'>
+) {
+  return useQueryUnwrapped({
+    queryKey: queryKeys.public.carts.detail(cartId),
+    queryFn: () => fetchCart(cartId),
+    ...options,
+  });
+}
+
+/**
+ * Hook to update cart using RPC
+ *
+ * @param cartId - Cart UUID
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const updateCart = useUpdateCart('cart-123');
+ * updateCart.mutate({
+ *   customerEmail: 'user@example.com',
+ *   deliveryZoneId: 'zone-123'
+ * });
+ * ```
+ */
+export function useUpdateCart(
+  cartId: string,
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof updateCart>>,
+    Error,
+    Parameters<typeof updateCart>[1]
+  >
+) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data) => updateCart(cartId, data),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.public.carts.detail(cartId) });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Hook to create a new cart using RPC
+ *
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const createCart = useCreateCart();
+ * createCart.mutate('my-brand');
+ * ```
+ */
+export function useCreateCart(
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof createCart>>,
+    Error,
+    string
+  >
+) {
+  return useMutation({
+    mutationFn: (brandSlug: string) => createCart(brandSlug),
+    ...options,
+  });
+}
+
+/**
+ * Hook to apply discount code to cart using RPC
+ *
+ * @param cartId - Cart UUID
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const applyDiscount = useApplyDiscount('cart-123');
+ * applyDiscount.mutate({ code: 'SAVE10' });
+ * ```
+ */
+export function useApplyDiscount(
+  cartId: string,
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof applyDiscount>>,
+    Error,
+    { code: string }
+  >
+) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data) => applyDiscount(cartId, data.code),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.public.carts.detail(cartId) });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Hook to remove discount code from cart using RPC
+ *
+ * @param cartId - Cart UUID
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const removeDiscount = useRemoveDiscount('cart-123');
+ * removeDiscount.mutate();
+ * ```
+ */
+export function useRemoveDiscount(
+  cartId: string,
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof removeDiscount>>,
+    Error,
+    void
+  >
+) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: () => removeDiscount(cartId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.public.carts.detail(cartId) });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Hook to add item to cart using RPC
+ *
+ * @param cartId - Cart UUID
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const addItem = useAddCartItem('cart-123');
+ * addItem.mutate({ sku: 'PROD-001', quantity: 2 });
+ * ```
+ */
+export function useAddCartItem(
+  cartId: string,
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof addCartItem>>,
+    Error,
+    { sku: string; quantity: number }
+  >
+) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data) => addCartItem(cartId, data.sku, data.quantity),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.public.carts.detail(cartId) });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Hook to update cart item quantity using RPC
+ *
+ * @param cartId - Cart UUID
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const updateItem = useUpdateCartItem('cart-123');
+ * updateItem.mutate({ itemId: 'item-456', quantity: 3 });
+ * ```
+ */
+export function useUpdateCartItem(
+  cartId: string,
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof updateCartItem>>,
+    Error,
+    { itemId: string; quantity: number }
+  >
+) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ itemId, quantity }) => updateCartItem(cartId, itemId, quantity),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.public.carts.detail(cartId) });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Hook to remove item from cart using RPC
+ *
+ * @param cartId - Cart UUID
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const removeItem = useRemoveCartItem('cart-123');
+ * removeItem.mutate('item-456'); // Pass itemId in mutate call
+ * ```
+ */
+export function useRemoveCartItem(
+  cartId: string,
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof removeCartItem>>,
+    Error,
+    string
+  >
+) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (itemId: string) => removeCartItem(cartId, itemId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.public.carts.detail(cartId) });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Hook to checkout a cart and create an order using RPC
+ *
+ * @param cartId - Cart UUID
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const checkout = useCheckoutCart('cart-123');
+ * checkout.mutate({
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   email: 'john@example.com',
+ *   phone: '+1234567890',
+ *   address: '123 Main St',
+ *   city: 'New York',
+ *   deliveryZoneId: 'zone-123',
+ *   paymentMethod: 'cod'
+ * });
+ * ```
+ */
+export function useCheckoutCart(
+  cartId: string,
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof checkoutCart>>,
+    Error,
+    Parameters<typeof checkoutCart>[1]
+  >
+) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data) => checkoutCart(cartId, data),
+    onSuccess: () => {
+      // Invalidate cart query since it's now converted to an order
+      queryClient.invalidateQueries({ queryKey: queryKeys.public.carts.detail(cartId) });
+    },
+    ...options,
+  });
+}

package/src/hooks/public/delivery-zones.ts

@@ -0,0 +1,34 @@
+/**
+ * Type-safe RPC hooks for delivery zone operations
+ *
+ * These hooks use Hono RPC client with types directly from the backend,
+ * providing end-to-end type safety without code generation.
+ */
+
+import { UseQueryOptions } from '@tanstack/react-query';
+import { useQueryUnwrapped } from '../use-query-unwrapped';
+import { queryKeys } from '../../utils/query-keys';
+import { fetchDeliveryZones } from '../../fetchers/delivery-zones';
+
+/**
+ * Hook to get delivery zones using RPC
+ *
+ * @param brandId - Optional brand UUID to filter brand-specific zones
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * const { data: zones, isLoading } = useGetDeliveryZones(undefined);
+ * console.log(zones?.data[0].name); // Fully typed!
+ * ```
+ */
+export function useGetDeliveryZones(
+  brandId: string | undefined,
+  options?: Omit<UseQueryOptions<Awaited<ReturnType<typeof fetchDeliveryZones>>, Error>, 'queryKey' | 'queryFn'>
+) {
+  return useQueryUnwrapped({
+    queryKey: queryKeys.public.deliveryZones.list(brandId),
+    queryFn: () => fetchDeliveryZones(brandId),
+    ...options,
+  });
+}

package/src/hooks/public/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Type-safe RPC hooks
+ *
+ * Export all RPC hooks for use in applications
+ */
+
+export * from './carts';
+export * from './orders';
+export * from './products';
+export * from './delivery-zones';

package/src/hooks/public/orders.ts

@@ -0,0 +1,66 @@
+/**
+ * Type-safe RPC hooks for order operations
+ *
+ * These hooks use Hono RPC client with types directly from the backend,
+ * providing end-to-end type safety without code generation.
+ */
+
+import { useMutation, UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+import { useQueryUnwrapped } from '../use-query-unwrapped';
+import { queryKeys } from '../../utils/query-keys';
+import { fetchOrder, confirmOrder } from '../../fetchers/orders';
+
+/**
+ * Hook to get order by ID and token using RPC
+ *
+ * @param orderId - Order UUID
+ * @param token - User action token
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * const { data: order, isLoading } = useGetOrder('order-123', 'token-456');
+ * console.log(order?.order.status); // Fully typed!
+ * ```
+ */
+export function useGetOrder(
+  orderId: string,
+  token: string,
+  options?: Omit<UseQueryOptions<Awaited<ReturnType<typeof fetchOrder>>, Error>, 'queryKey' | 'queryFn'>
+) {
+  return useQueryUnwrapped({
+    queryKey: queryKeys.public.orders.detail(orderId, token),
+    queryFn: () => fetchOrder(orderId, token),
+    ...options,
+  });
+}
+
+/**
+ * Hook to confirm a prospect order using RPC
+ *
+ * @param options - React Query mutation options
+ *
+ * @example
+ * ```tsx
+ * const confirmOrder = useConfirmOrder();
+ * confirmOrder.mutate({
+ *   orderId: 'order-123',
+ *   token: 'token-456'
+ * });
+ * ```
+ */
+export function useConfirmOrder(
+  options?: UseMutationOptions<
+    Awaited<ReturnType<typeof confirmOrder>>,
+    Error,
+    {
+      orderId: string;
+      token: string;
+    }
+  >
+) {
+  return useMutation({
+    mutationFn: (data) => confirmOrder(data.orderId, data.token),
+    ...options,
+  });
+}

package/src/hooks/public/products.ts

@@ -0,0 +1,57 @@
+/**
+ * Type-safe RPC hooks for product operations
+ *
+ * These hooks use Hono RPC client with types directly from the backend,
+ * providing end-to-end type safety without code generation.
+ */
+
+import { UseQueryOptions } from '@tanstack/react-query';
+import { useQueryUnwrapped } from '../use-query-unwrapped';
+import { queryKeys } from '../../utils/query-keys';
+import { fetchProductsByBrand, fetchProductBySlug } from '../../fetchers/products';
+
+/**
+ * Hook to get products by brand using RPC
+ *
+ * @param brandId - Brand UUID
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * const { data: products, isLoading } = useGetProducts('brand-123');
+ * console.log(products?.data[0].name); // Fully typed!
+ * ```
+ */
+export function useGetProducts(
+  brandId: string,
+  options?: Omit<UseQueryOptions<Awaited<ReturnType<typeof fetchProductsByBrand>>, Error>, 'queryKey' | 'queryFn'>
+) {
+  return useQueryUnwrapped({
+    queryKey: queryKeys.public.products.list(brandId),
+    queryFn: () => fetchProductsByBrand(brandId),
+    ...options,
+  });
+}
+
+/**
+ * Hook to get a single product by slug using RPC
+ *
+ * @param slug - Product slug
+ * @param options - React Query options
+ *
+ * @example
+ * ```tsx
+ * const { data: product, isLoading } = useGetProduct('cotton-t-shirt');
+ * console.log(product?.name); // Fully typed!
+ * ```
+ */
+export function useGetProduct(
+  slug: string,
+  options?: Omit<UseQueryOptions<Awaited<ReturnType<typeof fetchProductBySlug>>, Error>, 'queryKey' | 'queryFn'>
+) {
+  return useQueryUnwrapped({
+    queryKey: queryKeys.public.products.detail(slug),
+    queryFn: () => fetchProductBySlug(slug),
+    ...options,
+  });
+}

package/src/hooks/use-query-unwrapped.ts

@@ -0,0 +1,30 @@
+import { useQuery, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+
+/**
+ * Wrapper around useQuery that narrows the data type to exclude error responses
+ *
+ * Since our hooks throw on HTTP errors (via `if (!res.ok) throw new Error(...)`),
+ * the data will never actually be an error response at runtime. This wrapper
+ * tells TypeScript that truth.
+ *
+ * @example
+ * ```ts
+ * // Instead of:
+ * return useQuery({ ... })  // Returns UseQueryResult<Data | { error: ... }, Error>
+ *
+ * // Use:
+ * return useQueryUnwrapped({ ... })  // Returns UseQueryResult<Data, Error>
+ * ```
+ */
+export function useQueryUnwrapped<
+  TData,
+  TError = Error,
+  TQueryKey extends readonly unknown[] = readonly unknown[]
+>(
+  options: UseQueryOptions<TData, TError, TData, TQueryKey>
+): UseQueryResult<Exclude<TData, { error: any }>, TError> {
+  const result = useQuery(options);
+
+  // Cast the data to exclude error types since we throw on errors
+  return result as UseQueryResult<Exclude<TData, { error: any }>, TError>;
+}

package/src/hooks/useApiConfig.ts

@@ -0,0 +1,22 @@
+/**
+ * Hook to access API configuration from context
+ */
+
+import { useApiClientContext } from '../provider';
+
+export interface ApiConfig {
+  baseURL: string;
+  authToken: string;
+}
+
+/**
+ * Get API configuration from context
+ */
+export function useApiConfig(): ApiConfig {
+  const { baseURL, authToken } = useApiClientContext();
+
+  return {
+    baseURL,
+    authToken: authToken || '',
+  };
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @oms/api-client
+ *
+ * Type-safe React Query hooks for OMS API using Hono RPC
+ */
+
+// Export provider
+export { ApiClientProvider, useApiClientContext } from './provider';
+export type { ApiClientProviderProps } from './provider';
+
+// Export API config hook
+export { useApiConfig } from './hooks/useApiConfig';
+export type { ApiConfig } from './hooks/useApiConfig';
+
+// Export client utilities (legacy axios client - deprecated)
+export { getApiClient, initializeApiClient, resetApiClient } from './client';
+export type { ApiClientConfig } from './client';
+
+// Export RPC client utilities (type-safe Hono RPC)
+export { createRpcClients, createAdminRpcClients, authHeaders } from './rpc-client';
+export type { RpcClients, AdminRpcClients } from './rpc-client';
+
+// Export fetchers for Server Components (can be used without hooks)
+export * from './fetchers';
+
+// Export query keys for advanced usage
+export { queryKeys } from './utils/query-keys';
+
+// Export all public hooks directly from main package
+// These can be imported as: import { useGetCart } from '@oms/api-client'
+export * from './hooks/public';
+
+// Export namespaced versions for backward compatibility
+// These can be imported as: import { publicApi, adminApi } from '@oms/api-client'
+import * as publicHooks from './hooks/public';
+import * as adminHooks from './hooks/admin';
+
+export { publicHooks as publicApi, adminHooks as adminApi };
+
+// Export all type definitions
+// These can be imported as: import type { Brand, Product } from '@oms/api-client'
+export type * from './types';

package/src/provider.tsx

@@ -0,0 +1,89 @@
+/**
+ * React context provider for API client configuration
+ */
+
+import { createContext, useContext, useEffect, ReactNode, useMemo } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { AxiosError } from 'axios';
+import { initializeApiClient, ApiClientConfig } from './client';
+
+interface ApiClientContextValue {
+  baseURL: string;
+  authToken?: string;
+}
+
+const ApiClientContext = createContext<ApiClientContextValue | null>(null);
+
+export interface ApiClientProviderProps {
+  children: ReactNode;
+  baseURL?: string;
+  authToken?: string;
+  onError?: (error: AxiosError) => void;
+  queryClient?: QueryClient;
+}
+
+/**
+ * Provider component that initializes the API client and React Query
+ *
+ * @example
+ * ```tsx
+ * <ApiClientProvider>
+ *   <App />
+ * </ApiClientProvider>
+ * ```
+ */
+export function ApiClientProvider({
+  children,
+  baseURL = 'https://oms-api.instock.ng',
+  authToken,
+  onError,
+  queryClient: externalQueryClient
+}: ApiClientProviderProps) {
+  // Initialize client synchronously on first render
+  const config: ApiClientConfig = {
+    baseURL,
+    onError,
+  };
+
+  initializeApiClient(config);
+
+  // Update client when config changes
+  useEffect(() => {
+    initializeApiClient(config);
+  }, [baseURL, onError]);
+
+  // Create a default query client if one isn't provided
+  const queryClient = useMemo(
+    () =>
+      externalQueryClient ||
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            retry: 1,
+            refetchOnWindowFocus: false,
+            staleTime: 5000,
+          },
+        },
+      }),
+    [externalQueryClient]
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ApiClientContext.Provider value={{ baseURL, authToken }}>
+        {children}
+      </ApiClientContext.Provider>
+    </QueryClientProvider>
+  );
+}
+
+/**
+ * Hook to access API client context
+ */
+export function useApiClientContext() {
+  const context = useContext(ApiClientContext);
+  if (!context) {
+    throw new Error('useApiClientContext must be used within ApiClientProvider');
+  }
+  return context;
+}