@instockng/api-client 1.0.0

package/README.md

@@ -0,0 +1,263 @@
+# @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
+
+```bash
+npm install @oms/api-client
+# or
+pnpm add @oms/api-client
+```
+
+## Usage
+
+### 1. Setup Provider
+
+Wrap your app with `ApiClientProvider`:
+
+```tsx
+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
+
+```tsx
+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
+
+```tsx
+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
+
+```tsx
+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)
+
+```tsx
+// Coming soon - admin hooks will be added here
+// import { useGetOrders, useUpdateOrder } from '@oms/api-client/admin';
+```
+
+### 3. Custom Error Handling
+
+```tsx
+<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:
+
+```tsx
+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:
+
+```tsx
+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:
+
+```bash
+# From the monorepo root
+cd packages/types
+pnpm run generate
+```
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@instockng/api-client",
+  "version": "1.0.0",
+  "description": "React Query hooks for OMS API",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./fetchers": "./src/fetchers/index.ts",
+    "./public": "./src/hooks/public/index.ts",
+    "./admin": "./src/hooks/admin/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "api",
+    "react-query",
+    "hooks",
+    "oms"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@trpc/client": "^11.6.0",
+    "hono": "^4.9.10"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "axios": "^1.6.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.17.19",
+    "@types/react": "npm:types-react@^19.0.0-rc.1",
+    "axios": "^1.6.5",
+    "react": "^19.0.0",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "build": "tsc --build"
+  }
+}

package/src/client.ts

@@ -0,0 +1,57 @@
+/**
+ * Axios client configuration for OMS API
+ */
+
+import axios, { AxiosInstance, AxiosError } from 'axios';
+
+export interface ApiClientConfig {
+  baseURL: string;
+  onError?: (error: AxiosError) => void;
+}
+
+let apiClient: AxiosInstance | null = null;
+
+/**
+ * Initialize the API client with configuration
+ */
+export function initializeApiClient(config: ApiClientConfig): AxiosInstance {
+  apiClient = axios.create({
+    baseURL: config.baseURL,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  });
+
+  // Response interceptor for error handling
+  apiClient.interceptors.response.use(
+    (response) => response,
+    (error: AxiosError) => {
+      // Call custom error handler if provided
+      if (config.onError) {
+        config.onError(error);
+      }
+      return Promise.reject(error);
+    }
+  );
+
+  return apiClient;
+}
+
+/**
+ * Get the current API client instance
+ */
+export function getApiClient(): AxiosInstance {
+  if (!apiClient) {
+    throw new Error(
+      'API client not initialized. Make sure to wrap your app with ApiClientProvider.'
+    );
+  }
+  return apiClient;
+}
+
+/**
+ * Reset the API client (mainly for testing)
+ */
+export function resetApiClient(): void {
+  apiClient = null;
+}

package/src/fetchers/carts.ts

@@ -0,0 +1,202 @@
+/**
+ * Cart fetcher functions
+ *
+ * These are the actual data-fetching functions used by hooks.
+ * They can also be imported directly in Server Components.
+ *
+ * API URL is hardcoded to https://oms-api.instock.ng
+ */
+
+import { createRpcClients } from '../rpc-client';
+
+const API_URL = 'https://oms-api.instock.ng';
+
+/**
+ * Fetch a cart by ID
+ *
+ * @param cartId - Cart UUID
+ * @returns Cart with items, brand, and delivery zone
+ */
+export async function fetchCart(cartId: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts[':id'].$get({
+    param: { id: cartId },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch cart: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Create a new cart
+ *
+ * @param brandSlug - Brand slug
+ * @returns Newly created cart
+ */
+export async function createCart(brandSlug: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts.index.$post({
+    json: { brandSlug },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to create cart: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Update a cart
+ *
+ * @param cartId - Cart UUID
+ * @param data - Cart update data (customer info, deliveryZoneId, etc.)
+ * @returns Updated cart
+ */
+export async function updateCart(
+  cartId: string,
+  data: {
+    customerPhone?: string | null;
+    customerEmail?: string | null;
+    customerFirstName?: string | null;
+    customerLastName?: string | null;
+    deliveryZoneId?: string | null;
+    ifUnmodifiedSince?: string;
+  }
+) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts[':id'].$patch({
+    param: { id: cartId },
+    json: data,
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to update cart: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Add an item to cart
+ *
+ * @param cartId - Cart UUID
+ * @param sku - Product variant SKU
+ * @param quantity - Quantity to add
+ * @returns Updated cart
+ */
+export async function addCartItem(cartId: string, sku: string, quantity: number) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts[':id'].items.$post({
+    param: { id: cartId },
+    json: { sku, quantity },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to add item to cart: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Update a cart item quantity
+ *
+ * @param cartId - Cart UUID
+ * @param itemId - Cart item UUID
+ * @param quantity - New quantity
+ * @returns Updated cart
+ */
+export async function updateCartItem(cartId: string, itemId: string, quantity: number) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts[':id'].items[':itemId'].$patch({
+    param: { id: cartId, itemId },
+    json: { quantity },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to update cart item: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Remove an item from cart
+ *
+ * @param cartId - Cart UUID
+ * @param itemId - Cart item UUID
+ * @returns Updated cart
+ */
+export async function removeCartItem(cartId: string, itemId: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts[':id'].items[':itemId'].$delete({
+    param: { id: cartId, itemId },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to remove cart item: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Apply a discount code to cart
+ *
+ * @param cartId - Cart UUID
+ * @param code - Discount code
+ * @returns Updated cart
+ */
+export async function applyDiscount(cartId: string, code: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts[':id']['apply-discount'].$post({
+    param: { id: cartId },
+    json: { code },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to apply discount: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Remove discount from cart
+ *
+ * @param cartId - Cart UUID
+ * @returns Updated cart
+ */
+export async function removeDiscount(cartId: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts[':id']['remove-discount'].$post({
+    param: { id: cartId },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to remove discount: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Checkout a cart
+ *
+ * @param cartId - Cart UUID
+ * @param checkoutData - Checkout information (customer details, delivery, payment)
+ * @returns Created order
+ */
+export async function checkoutCart(
+  cartId: string,
+  checkoutData: {
+    firstName: string;
+    lastName: string;
+    phone?: string;
+    email?: string;
+    address: string;
+    city: string;
+    deliveryZoneId: string;
+    paymentMethod: 'cod' | 'online';
+    paystackReference?: string;
+    ifUnmodifiedSince?: string;
+  }
+) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.carts[':id'].checkout.$post({
+    param: { id: cartId },
+    json: checkoutData,
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to checkout cart: ${res.statusText}`);
+  }
+  return res.json();
+}

package/src/fetchers/delivery-zones.ts

@@ -0,0 +1,29 @@
+/**
+ * Delivery zone fetcher functions
+ *
+ * These are the actual data-fetching functions used by hooks.
+ * They can also be imported directly in Server Components.
+ *
+ * API URL is hardcoded to https://oms-api.instock.ng
+ */
+
+import { createRpcClients } from '../rpc-client';
+
+const API_URL = 'https://oms-api.instock.ng';
+
+/**
+ * Fetch delivery zones
+ *
+ * @param brandId - Optional brand UUID to filter brand-specific zones
+ * @returns List of delivery zones with states
+ */
+export async function fetchDeliveryZones(brandId?: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.deliveryZones.index.$get({
+    query: brandId ? { brandId } : {},
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch delivery zones: ${res.statusText}`);
+  }
+  return res.json();
+}

package/src/fetchers/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Data fetcher functions for Server Components
+ *
+ * These functions can be used directly in Next.js Server Components
+ * without needing React hooks. They use the same underlying logic
+ * as the client-side hooks, ensuring no code duplication.
+ *
+ * @example Server Component
+ * ```tsx
+ * import { fetchProductBySlug, fetchCart } from '@oms/api-client/fetchers';
+ *
+ * export default async function ProductPage({ params }) {
+ *   const product = await fetchProductBySlug(params.slug);
+ *   return <div>{product.name}</div>;
+ * }
+ * ```
+ */
+
+export * from './products';
+export * from './carts';
+export * from './orders';
+export * from './delivery-zones';

package/src/fetchers/orders.ts

@@ -0,0 +1,48 @@
+/**
+ * Order fetcher functions
+ *
+ * These are the actual data-fetching functions used by hooks.
+ * They can also be imported directly in Server Components.
+ *
+ * API URL is hardcoded to https://oms-api.instock.ng
+ */
+
+import { createRpcClients } from '../rpc-client';
+
+const API_URL = 'https://oms-api.instock.ng';
+
+/**
+ * Fetch an order by ID and token
+ *
+ * @param orderId - Order UUID
+ * @param token - User action token
+ * @returns Order with items, delivery zone, and brand
+ */
+export async function fetchOrder(orderId: string, token: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.orders[':id'][':token'].$get({
+    param: { id: orderId, token },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch order: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Confirm a prospect order
+ *
+ * @param orderId - Order UUID
+ * @param token - User action token
+ * @returns Confirmed order
+ */
+export async function confirmOrder(orderId: string, token: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.orders.confirm.$post({
+    json: { orderId, token },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to confirm order: ${res.statusText}`);
+  }
+  return res.json();
+}

package/src/fetchers/products.ts

@@ -0,0 +1,46 @@
+/**
+ * Product fetcher functions
+ *
+ * These are the actual data-fetching functions used by hooks.
+ * They can also be imported directly in Server Components.
+ *
+ * API URL is hardcoded to https://oms-api.instock.ng
+ */
+
+import { createRpcClients } from '../rpc-client';
+
+const API_URL = 'https://oms-api.instock.ng';
+
+/**
+ * Fetch products by brand ID
+ *
+ * @param brandId - Brand UUID
+ * @returns Products for the brand with variants and availability
+ */
+export async function fetchProductsByBrand(brandId: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.products[':brandId'].$get({
+    param: { brandId },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch products: ${res.statusText}`);
+  }
+  return res.json();
+}
+
+/**
+ * Fetch a single product by slug
+ *
+ * @param slug - Product slug (e.g., 'cotton-t-shirt')
+ * @returns Product with variants and availability
+ */
+export async function fetchProductBySlug(slug: string) {
+  const clients = createRpcClients(API_URL);
+  const res = await clients.products.product[':slug'].$get({
+    param: { slug },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch product: ${res.statusText}`);
+  }
+  return res.json();
+}