buymeua-api-fe 0.0.1

package/README.md

@@ -0,0 +1,592 @@
+# Buymeua API Frontend
+
+## 🚀 Installation
+
+```bash
+npm install buymeua-api-fe @reduxjs/toolkit react-redux
+```
+
+## 📖 Quick Start
+
+### 1. Configure API and Setup Redux Store
+
+```typescript
+import { configureStore } from '@reduxjs/toolkit';
+import { configureBuymeuaApi, getBuymeuaApi, Session } from 'buymeua-api-fe';
+
+// Configure API before store setup
+const buymeuaApi = configureBuymeuaApi({
+  baseUrl: 'https://api.buymeua.com/',
+  prepareHeaders: (headers) => {
+    headers.set('Accept', 'application/json');
+    headers.set('X-SESSION', Session.Dropshipper);
+
+    const token = localStorage.getItem('auth-token');
+    if (token) {
+      headers.set('Authorization', `Bearer ${token}`);
+    }
+  },
+  onUnauthorized: () => {
+    // Handle 401 errors
+    localStorage.removeItem('auth-token');
+    window.location.href = '/login';
+  },
+});
+
+// Setup Redux store
+export const store = configureStore({
+  reducer: {
+    [buymeuaApi.reducerPath]: buymeuaApi.reducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().concat(buymeuaApi.middleware),
+});
+```
+
+### 2. Usage in React Components
+
+```typescript
+import React from 'react';
+import { useGetProductsQuery } from 'buymeua-api-fe';
+
+function ProductList() {
+  const { data: products, isLoading, error } = useGetProductsQuery({
+    page: 1,
+    per_page: 20,
+    search: 'phone'
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error loading products</div>;
+
+  return (
+    <div>
+      {products?.data.map(product => (
+        <div key={product.id}>{product.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+## 📚 API Reference
+
+### Configuration
+
+#### `configureBuymeuaApi(config: ApiConfig)`
+
+Configures the global API client.
+
+**Parameters:**
+
+- `config.baseUrl` - Base API URL
+- `config.prepareHeaders` - Function to prepare headers
+- `config.onUnauthorized` - Callback for handling 401 errors
+
+#### `getBuymeuaApi()`
+
+Returns the configured API instance.
+
+### Products
+
+```typescript
+// Get products list with infinite scroll
+const { data, fetchNextPage, hasNextPage } = useGetProductsInfiniteQuery({
+  queryArg: {
+    per_page?: number;
+    core_filter?: string;
+    filter_has_special?: boolean | null;
+    order_by?: string;
+    category_filter?: number[];
+    option_value_filter?: {
+      option_value_ids: number[];
+      warehouse_ids: number[];
+    };
+    filter_customer_id?: number;
+    filter_has_customer_id?: boolean;
+    filter_advertised?: boolean;
+    price_from?: number;
+    price_to?: number;
+    only_in_root_category?: boolean;
+    price_type?: string;
+  }
+});
+
+// Get products by QR code
+const { data, fetchNextPage, hasNextPage } = useGetProductsByQrInfiniteQuery({
+  queryArg: {
+    'filter[barcode]'?: string;
+    'filter[product_id]'?: number;
+    core_filter?: string;
+    per_page?: number;
+  }
+});
+
+// Get single product by ID
+const { data } = useGetProductByIdQuery({ product: number });
+
+// Get product (alternative endpoint)
+const { data } = useGetProductQuery({ product: number });
+
+// Get product statistics
+const { data } = useGetProductStatisticsQuery({ product: number });
+
+// Get bestsellers
+const { data } = useGetBestSellersQuery({
+  best_seller_days_filter?: number;
+  filter_customer_id?: number;
+  filter_has_suppliers?: boolean;
+  category_filter?: number[];
+});
+
+// Get product details
+const { data } = useGetProductDetailsQuery({ product: number });
+```
+
+### Cart
+
+```typescript
+// Get cart count
+const { data } = useGetCartCountQuery();
+
+// Get cart merchants
+const { data, fetchNextPage, hasNextPage } = useGetCartMerchantsInfiniteQuery({
+  queryArg: {
+    per_page?: number;
+  }
+});
+
+// Get cart merchant items
+const { data, fetchNextPage, hasNextPage } = useGetCartMerchantItemsInfiniteQuery({
+  queryArg: {
+    merchant_id: number;
+    per_page?: number;
+  }
+});
+
+// Add item to cart
+const [addToCart] = useAddToCartMutation();
+await addToCart({
+  product_type: string;
+  product_id: number;
+  product_option_value_id: number;
+  quantity: number;
+  warehouse_id: number | null; // only for buyme products
+});
+
+// Remove item from cart
+const [removeFromCart] = useRemoveItemFromCartMutation();
+await removeFromCart({
+  cart_item_id: number;
+  merchantId: number;
+  quantity: number;
+});
+
+// Remove entire merchant from cart
+const [removeMerchant] = useRemoveMerchantFromCartMutation();
+await removeMerchant({ merchant_id: number });
+
+// Update cart item quantity
+const [updateQuantity] = useUpdateCartItemQuantityMutation();
+await updateQuantity({
+  cart_item_option_value_id: number;
+  quantity: number;
+  type: 'increase' | 'decrease';
+  merchantId: number;
+  optionIndex: number;
+});
+
+// Toggle gift package
+const [toggleGift] = useToggleGiftPackageMutation();
+await toggleGift({
+  gift_package: boolean;
+  merchantId: number;
+});
+```
+
+### Authentication
+
+```typescript
+// Sign in with phone number
+const [signIn] = useSignInMutation();
+await signIn({
+  telephone: string;
+});
+
+// Confirm verification code
+const [confirmCode] = useConfirmCodeMutation();
+await confirmCode({
+  telephone: string;
+  code: string;
+});
+
+// Sign up
+const [signUp] = useSignUpMutation();
+await signUp({
+  telephone: string;
+  firstname: string;
+  lastname: string;
+  term: 1;
+});
+```
+
+### Categories
+
+```typescript
+// Get categories
+const { data, fetchNextPage, hasNextPage } = useGetCategoriesInfiniteQuery({
+  queryArg: {
+    search: string;
+    filter_parent_id?: number;
+    filter_with_products?: boolean;
+    per_page?: number;
+  }
+});
+
+// Get supplier categories
+const { data, fetchNextPage, hasNextPage } = useGetSupplierCategoriesInfiniteQuery({
+  queryArg: {
+    customer: number;
+    parent_id?: number;
+    per_page?: number;
+  }
+});
+
+// Get Buyme categories
+const { data, fetchNextPage, hasNextPage } = useGetBuymeCategoriesInfiniteQuery({
+  queryArg: {
+    search?: string;
+    parent_id?: number;
+    customer_id?: number;
+    per_page?: number;
+  }
+});
+```
+
+### Favorites
+
+```typescript
+// Get favorite count
+const { data } = useGetFavoriteCountQuery();
+
+// Get favorite merchants
+const { data, fetchNextPage, hasNextPage } = useGetFavoriteMerchantsInfiniteQuery({
+  queryArg: {
+    per_page?: number;
+  }
+});
+
+// Get favorite merchant items
+const { data, fetchNextPage, hasNextPage } = useGetFavoriteMerchantItemsInfiniteQuery({
+  queryArg: {
+    merchant_id: number;
+  }
+});
+
+// Add to favorites
+const [addToFavorite] = useAddFavoriteMerchantItemMutation();
+await addToFavorite({
+  product_type: string;
+  product_id: number;
+});
+
+// Remove from favorites
+const [removeFromFavorite] = useDeleteFavoriteMerchantItemMutation();
+await removeFromFavorite({
+  product_type: string;
+  product_id: number;
+});
+```
+
+### Chat
+
+```typescript
+// Get chat list
+const { data, fetchNextPage, hasNextPage } = useGetChatsInfiniteQuery({
+  queryArg: {
+    per_page?: number;
+  }
+});
+
+// Get chat info
+const { data } = useGetChatInfoQuery({
+  customerChatThread: number;
+});
+
+// Get chat messages
+const { data, fetchNextPage, hasNextPage } = useGetChatInfiniteQuery({
+  queryArg: {
+    customerChatThreadId: number;
+    per_page?: number;
+  }
+});
+
+// Get single chat message
+const { data } = useGetChatMessageQuery({
+  customerChatThreadId: number;
+  customerChatId: number;
+});
+
+// Create chat
+const [createChat] = useCreateChatMutation();
+await createChat({
+  customer_id: number;
+  supplier_id: number | null;
+  admin_id: number | null;
+});
+
+// Send message
+const [sendMessage] = useSendChatMessageMutation();
+await sendMessage({
+  customerChatThreadId: number;
+  message: string;
+  medias: File[];
+});
+
+// Update message
+const [updateMessage] = useUpdateChatMessageMutation();
+await updateMessage({
+  customerChatThreadId: number;
+  customerChatId: number;
+  message: string;
+  medias: File[];
+});
+
+// Mark messages as read
+const [markAsRead] = useMarkChatMessagesAsReadMutation();
+await markAsRead({
+  customerChatThreadId: number;
+  chats: number[]; // Message IDs
+});
+
+// Delete chat
+const [deleteChat] = useDeleteChatMutation();
+await deleteChat({
+  customerChatThread: number;
+  customer_id: number;
+});
+
+// Delete message
+const [deleteMessage] = useDeleteChatMessageMutation();
+await deleteMessage({
+  customerChatThread: number;
+  chat: number; // Message ID
+});
+
+// Resend message
+const [resendMessage] = useResendChatMessageMutation();
+await resendMessage({
+  customerChatThreadId: number;
+  customerChatId: number;
+  message: string;
+  medias: File[];
+});
+```
+
+### Notifications
+
+```typescript
+// Get notifications
+const { data, fetchNextPage, hasNextPage } = useGetNotificationsInfiniteQuery({
+  queryArg: {
+    per_page?: number;
+    'filter[type]'?: string;
+    'filter[event]'?: string;
+    'filter[date_from]'?: string;
+    'filter[date_to]'?: string;
+  }
+});
+
+// Get single notification
+const { data } = useGetNotificationQuery({
+  notification: number;
+});
+
+// Get notifications count
+const { data } = useGetNotificationsCountQuery();
+
+// Get new suppliers count
+const { data } = useGetNewSuppliersCountQuery();
+
+// Mark all as read
+const [markAllAsRead] = useMarkAllNotificationsAsReadMutation();
+await markAllAsRead();
+
+// Mark single notification as read
+const [markAsRead] = useMarkNotificationAsReadMutation();
+await markAsRead({ notification: number });
+
+// Delete all notifications
+const [deleteAll] = useDeleteAllNotificationsMutation();
+await deleteAll();
+
+// Delete single notification
+const [deleteNotification] = useDeleteNotificationMutation();
+await deleteNotification({ notification: number });
+```
+
+### Stories
+
+```typescript
+// Get stories
+const { data, fetchNextPage, hasNextPage } = useGetStoriesInfiniteQuery({
+  queryArg?: {
+    sort_type?: 'created_at' | 'views_count' | 'sort_order' | 'viewed_order';
+    sort_direction?: 'asc' | 'desc';
+    per_page?: number;
+  }
+});
+
+// Increase story views
+const [increaseViews] = useIncreaseStoryViewsMutation();
+await increaseViews({ story: number });
+```
+
+### Suppliers
+
+```typescript
+// Get suppliers list
+const { data, fetchNextPage, hasNextPage } = useGetSuppliersInfiniteQuery({
+  queryArg: {
+    per_page?: number;
+    search?: string;
+    filter_buyme_category_ids?: number[];
+  }
+});
+
+// Get supplier info
+const { data } = useGetSupplierInfoQuery({
+  customer: number;
+});
+
+// Get supplier articles
+const { data, fetchNextPage, hasNextPage } = useGetSupplierArticlesInfiniteQuery({
+  queryArg: {
+    customer: number;
+    per_page?: number;
+    'filter[id]'?: number;
+    'filter[translations.title]'?: string;
+    'filter[translations.content]'?: string;
+    'filter[date_from]'?: string;
+    'filter[date_to]'?: string;
+  }
+});
+
+// Get supplier reviews
+const { data, fetchNextPage, hasNextPage } = useGetSupplierReviewsInfiniteQuery({
+  queryArg: {
+    supplier_id: number;
+    per_page?: number;
+    rating?: number;
+    has_reply?: boolean;
+    date_from?: string;
+    date_to?: string;
+    sort_by?: 'rating' | 'created_at';
+    sort_direction?: 'asc' | 'desc';
+  }
+});
+
+// Get supplier rating
+const { data } = useGetSupplierRatingQuery({
+  supplier_id: number;
+});
+
+// Add supplier review
+const [addReview] = useAddSupplierReviewMutation();
+await addReview({
+  supplier_id: number;
+  rating: number;
+  text: string;
+});
+
+// Reply to supplier review
+const [replyToReview] = useReplyToSupplierReviewMutation();
+await replyToReview({
+  review_id: number;
+  reply_text: string;
+});
+
+// Mark supplier as old
+const [markAsOld] = useMarkSupplierAsOldMutation();
+await markAsOld({ supplier: number });
+```
+
+### Nova Poshta
+
+```typescript
+// Get Nova Poshta cities
+const { data, fetchNextPage, hasNextPage } = useGetNovaposhtaCitiesInfiniteQuery({
+  queryArg: {
+    search?: string;
+    area?: string;
+    settlement_type?: string;
+    is_branch?: boolean;
+    per_page?: number;
+  }
+});
+
+// Get Nova Poshta streets
+const { data, fetchNextPage, hasNextPage } = useGetNovaposhtaStreetsInfiniteQuery({
+  queryArg: {
+    search?: string;
+    city_ref: string;
+    streets_type?: string;
+    per_page?: number;
+  }
+});
+
+// Get Nova Poshta warehouses
+const { data, fetchNextPage, hasNextPage } = useGetNovaposhtaWarehousesInfiniteQuery({
+  queryArg: {
+    search?: string;
+    city_ref: string;
+    type?: string;
+    per_page?: number;
+  }
+});
+```
+
+### Referrals
+
+```typescript
+// Get referral statistics
+const { data, fetchNextPage, hasNextPage } = useGetReferralStatisticsInfiniteQuery({
+  queryArg?: {
+    date_from?: string;
+    date_to?: string;
+    per_page?: number;
+  }
+});
+
+// Get referral transactions
+const { data, fetchNextPage, hasNextPage } = useGetReferralTransactionsInfiniteQuery({
+  queryArg: {
+    referral_id: number;
+    date_from?: string;
+    date_to?: string;
+    per_page?: number;
+  }
+});
+
+// Track referral visit
+const [trackVisit] = useTrackReferralVisitMutation();
+await trackVisit({
+  referral_id: number;
+});
+```
+
+### Ads
+
+```typescript
+// Get ad pages
+const { data } = useGetAdPagesQuery({
+  platform_id: number;
+});
+
+// Get ad platforms
+const { data, fetchNextPage, hasNextPage } = useGetAdPlatformsInfiniteQuery({
+  queryArg?: {
+    per_page?: number;
+  }
+});
+```