Buymeua API Frontend

TypeScript/JavaScript client for BuyMeUA API with RTK Query integration.


🚀 Installation

``bash
npm install buymeua-api-fe @reduxjs/toolkit react-redux


or

`typescript
import { configureStore } from '@reduxjs/toolkit';
import { configureBuymeuaApi, Session } from 'buymeua-api-fe';

// Configure API before store setup
const buymeuaApi = configureBuymeuaApi({
baseUrl: 'https://api.buymeua.com/',
pusher: {
appKey: 'your-pusher-app-key',
cluster: 'eu',
},
prepareHeaders: (headers) => {
headers.set('Accept', 'application/json');
headers.set('Content-Type', 'application/json');

headers.set('X-SESSION', Session.Dropshipper);

const token = localStorage.getItem('auth-token');
if (token) {
headers.set('Authorization', Bearer ${token});
}
},
onUnauthorized: (args, api, extraOptions) => {
// Handle 401 errors with full request context
console.log('Unauthorized request:', args);
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),
});
`

$3

`typescript
import React from 'react';
import { productApi } from 'buymeua-api-fe';

function ProductList() {
const { data, isLoading, error, fetchNextPage, hasNextPage } = productApi.useGetProductsInfiniteQuery({
per_page: 20,
core_filter: 'phone'
});

if (isLoading) return

#### configureBuymeuaApi(config: ApiConfig)

Configures the global API client.

#### getPusher(): Promise

Returns a shared Pusher instance for real-time subscriptions. Uses lazy initialization and automatically handles authentication for private channels.

`typescript
import { getPusher } from 'buymeua-api-fe';

// Subscribe to a channel
const pusher = await getPusher();
const channel = pusher.subscribe('my-channel');
channel.bind('my-event', (data) => {
console.log('Received:', data);
});
`

Parameters:

- config.baseUrl - Base API URL
- config.prepareHeaders - Function to prepare headers (receives Headers object and API context)
- config.onUnauthorized - Optional callback for handling 401 errors (receives args, api, extraOptions for context)

Returns: Configured API instance ready for Redux store setup

$3

`typescript
import { productApi } from 'buymeua-api-fe';

// Get products list with infinite scroll
const { data, fetchNextPage, hasNextPage } = productApi.useGetProductsInfiniteQuery({
per_page?: number;
core_filter?: string;
filter_has_special?: boolean | null;
order_by?: string | string[];
category_filter?: number[];
option_value_filter?: {
option_value_ids: number[];
warehouse_ids: number[];
};
attribute_filter?: {
attribute_ids: number[];
attribute_values: ${number}:$${number}[];
};
filter_customer_id?: number;
filter_has_customer_id?: boolean;
filter_advertised?: boolean;
filter_product_ids?: number[];
filter_exclude_product_ids?: number[];
filter_bestseller?: boolean;
price_from?: number;
price_to?: number;
retail_price_from?: number;
retail_price_to?: number;
margin_from?: number;
margin_to?: number;
only_in_root_category?: boolean;
price_type?: string;
});

// Get products with standard pagination
const { data } = productApi.useGetPaginatedProductsQuery({
page?: number;
per_page?: number;
core_filter?: string;
filter_has_special?: boolean | null;
order_by?: string | string[];
category_filter?: number[];
option_value_filter?: {
option_value_ids?: number[];
warehouse_ids?: number[];
};
attribute_filter?: {
attribute_ids: number[];
attribute_values: ${number}:$${number}[];
};
filter_customer_id?: number;
filter_has_customer_id?: boolean;
filter_advertised?: boolean;
filter_product_ids?: number[];
filter_exclude_product_ids?: number[];
filter_bestseller?: boolean;
price_from?: number;
price_to?: number;
retail_price_from?: number;
retail_price_to?: number;
margin_from?: number;
margin_to?: number;
only_in_root_category?: boolean;
price_type?: string;
});

// Get products by QR code
const { data, fetchNextPage, hasNextPage } = productApi.useGetProductsByQrInfiniteQuery({
'filter[barcode]'?: string;
'filter[product_id]'?: number;
core_filter?: string;
per_page?: number;
});

// Get single product by ID
const { data } = productApi.useGetProductQuery({ product: number });

// Get product statistics
const { data } = productApi.useGetProductStatisticsQuery({ product: number });

// Get product details
const { data } = productApi.useGetProductDetailsQuery({ product: number });

// Get product attributes for filtering
const { data } = productApi.useGetProductAttributesQuery({
search?: string;
product_id?: number;
category_id?: number;
attribute_ids?: number[];
option_value_filter?: {
option_value_ids?: number[];
warehouse_ids?: number[];
};
attribute_filter?: {
attribute_ids?: number[];
attribute_values?: ${number}:${string}[];
};
});

// Get product options for filtering
const { data } = productApi.useGetProductOptionsQuery({
search?: string;
product_id?: number;
category_id?: number;
option_id?: number;
option_value_ids?: number[];
warehouse_ids?: number[];
attribute_filter?: {
attribute_ids?: number[];
attribute_values?: ${number}:${string}[];
};
});

// Get supplier products with infinite scroll
const { data, fetchNextPage, hasNextPage } = productApi.useGetSupplierProductsInfiniteQuery({
core_filter?: string;
category_filter?: number[];
buyme_category_filter?: number[];
filter_buyme_category_set_main_category?: boolean;
filter_customer_id?: number;
filter_exclude_supplier_ids?: number[];
filter_advertised?: boolean;
only_in_root_category?: boolean;
option_value_filter?: {
option_value_ids?: number[];
warehouse_ids?: number[];
};
price_from?: number;
price_to?: number;
per_page?: number;
price_type?: 'price' | 'price_drop';
});

// Get supplier products with standard pagination
const { data } = productApi.useGetPaginatedSupplierProductsQuery({
page?: number;
core_filter?: string;
category_filter?: number[];
buyme_category_filter?: number[];
filter_buyme_category_set_main_category?: boolean;
filter_customer_id?: number;
filter_exclude_supplier_ids?: number[];
filter_advertised?: boolean;
only_in_root_category?: boolean;
option_value_filter?: {
option_value_ids?: number[];
warehouse_ids?: number[];
};
price_from?: number;
price_to?: number;
per_page?: number;
price_type?: 'price' | 'price_drop';
});

// Get supplier product details
const { data } = productApi.useGetSupplierProductDetailsQuery({ id: number });

// Generate product description using AI
const { data } = productApi.useGenerateProductDescriptionQuery({ product: number });
// data.description - AI-generated product description
`

$3

`typescript
import { cartApi } from 'buymeua-api-fe';

// Get cart count
const { data } = cartApi.useGetCartCountQuery();

// Get cart merchants
const { data, fetchNextPage, hasNextPage } = cartApi.useGetCartMerchantsInfiniteQuery({
per_page?: number;
});

// Get cart merchant items
const { data, fetchNextPage, hasNextPage } = cartApi.useGetCartMerchantItemsInfiniteQuery({
merchant_id: number;
per_page?: number;
});

// Add item to cart
const [addToCart] = cartApi.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] = cartApi.useRemoveItemFromCartMutation();
await removeFromCart({
cart_item_id: number;
merchantId: number;
quantity: number;
});

// Remove entire merchant from cart
const [removeMerchant] = cartApi.useRemoveMerchantFromCartMutation();
await removeMerchant({ merchant_id: number });

// Update cart item quantity
const [updateQuantity] = cartApi.useUpdateCartItemQuantityMutation();
await updateQuantity({
cart_item_option_value_id: number;
quantity: number;
type: 'increase' | 'decrease';
merchantId: number;
optionIndex: number;
});

// Toggle gift package
const [toggleGift] = cartApi.useToggleGiftPackageMutation();
await toggleGift({
gift_package: boolean;
});
`

$3

`typescript
import { authApi } from 'buymeua-api-fe';

// Sign in with phone number
const [signIn] = authApi.useSignInMutation();
await signIn({
telephone: string;
});

// Confirm verification code
const [confirmCode] = authApi.useConfirmCodeMutation();
await confirmCode({
telephone: string;
code: string;
});

// Sign up
const [signUp] = authApi.useSignUpMutation();
await signUp({
telephone: string;
firstname: string;
lastname: string;
term: 1;
});

// Register as guest
const [registerGuest] = authApi.useRegisterGuestMutation();
const { data } = await registerGuest(); // Returns Customer with token

// Logout
const [logout] = authApi.useLogoutMutation();
await logout();
`

$3

`typescript
import { customerApi } from 'buymeua-api-fe';

// Save customer settings
const [saveSettings] = customerApi.useSaveCustomerSettingsMutation();
await saveSettings({
firstname: string;
lastname: string;
middlename: string;
iban: string;
card_fio: string;
ederpou: string;
avatar: string;
email?: string;
});

// Delete customer account
const [deleteAccount] = customerApi.useDeleteCustomerAccountMutation();
await deleteAccount();
`

$3

`typescript
import { categoryApi, useCategoryBreadcrumbs } from 'buymeua-api-fe';

// Get categories tree (full hierarchy)
const { data } = categoryApi.useGetCategoriesQuery({
search?: string;
filter_parent_id?: number;
filter_with_products?: boolean;
filter_with_supplier_products?: boolean;
filter_prepared_for_site?: boolean;
});

// Build category breadcrumbs
// For regular categories
const { breadcrumbs, isLoading } = useCategoryBreadcrumbs(categoryId);

// For supplier categories
const { breadcrumbs, isLoading } = useCategoryBreadcrumbs(categoryId, supplierId);
// Returns array of categories from root to current

// Get supplier categories
const { data } = categoryApi.useGetSupplierCategoriesQuery({
search?: string;
filter_parent_id?: number;
filter_customer_id?: number;
filter_has_products?: boolean;
filter_status?: boolean;
});
`

$3

`typescript
import { favoriteApi } from 'buymeua-api-fe';

// Get favorite count
const { data } = favoriteApi.useGetFavoriteCountQuery();

// Get favorite merchants
const { data, fetchNextPage, hasNextPage } = favoriteApi.useGetFavoriteMerchantsInfiniteQuery({
per_page?: number;
});

// Get favorite merchant items
const { data, fetchNextPage, hasNextPage } = favoriteApi.useGetFavoriteMerchantItemsInfiniteQuery({
merchant_id: number;
});

// Add to favorites
const [addToFavorite] = favoriteApi.useAddFavoriteMerchantItemMutation();
await addToFavorite({
product_type: string;
product_id: number;
optimisticUpdate?: {
product: BaseProduct; // For optimistic UI updates
};
});

// Remove from favorites
const [removeFromFavorite] = favoriteApi.useDeleteFavoriteMerchantItemMutation();
await removeFromFavorite({
product_type: string;
product_id: number;
optimisticUpdate?: {
product: BaseProduct; // For optimistic UI updates
};
});
`

$3

`typescript
import { chatApi } from 'buymeua-api-fe';

// Get chat list
const { data, fetchNextPage, hasNextPage } = chatApi.useGetChatsInfiniteQuery({
per_page?: number;
});

// Get chat info
const { data } = chatApi.useGetChatInfoQuery({
customerChatThread: number;
});

// Get chat messages
const { data, fetchNextPage, hasNextPage } = chatApi.useGetChatInfiniteQuery({
customerChatThreadId: number;
per_page?: number;
});

// Get single chat message
const { data } = chatApi.useGetChatMessageQuery({
customerChatThreadId: number;
customerChatId: number;
});

// Create chat
const [createChat] = chatApi.useCreateChatMutation();
await createChat({
customer_id: number;
supplier_id?: number; // Required if admin_id not provided
admin_id?: number; // Required if supplier_id not provided
});

// Send message
const [sendMessage] = chatApi.useSendChatMessageMutation();
await sendMessage({
customerChatThreadId: number;
message: string;
medias?: File[];
});

// Update message
const [updateMessage] = chatApi.useUpdateChatMessageMutation();
await updateMessage({
customerChatThreadId: number;
customerChatId: number;
message: string;
medias?: File[];
});

// Mark messages as read
const [markAsRead] = chatApi.useMarkChatMessagesAsReadMutation();
await markAsRead({
customerChatThreadId: number;
chats: number[]; // Message IDs
});

// Mark all messages as read
const [markAllAsRead] = chatApi.useMarkAllChatMessagesAsReadMutation();
await markAllAsRead({
customerChatThreadId: number;
});

// Delete chat
const [deleteChat] = chatApi.useDeleteChatMutation();
await deleteChat({
customerChatThread: number;
customer_id: number;
});

// Delete message
const [deleteMessage] = chatApi.useDeleteChatMessageMutation();
await deleteMessage({
customerChatThread: number;
chat: number; // Message ID
});

// Resend message
const [resendMessage] = chatApi.useResendChatMessageMutation();
await resendMessage({
customerChatThreadId: number;
customerChatId: number;
message: string;
medias?: File[];
});
`

$3

`typescript
import { notificationApi } from 'buymeua-api-fe';

// Get notifications
const { data, fetchNextPage, hasNextPage } = notificationApi.useGetNotificationsInfiniteQuery({
per_page?: number;
'filter[type]'?: string;
'filter[event]'?: string;
'filter[date_from]'?: string;
'filter[date_to]'?: string;
});

// Get single notification
const { data } = notificationApi.useGetNotificationQuery({
notification: number;
});

// Get notifications count
const { data } = notificationApi.useGetNotificationsCountQuery();

// Get new suppliers count
const { data } = notificationApi.useGetNewSuppliersCountQuery();

// Mark all as read
const [markAllAsRead] = notificationApi.useMarkAllNotificationsAsReadMutation();
await markAllAsRead();

// Mark single notification as read
const [markAsRead] = notificationApi.useMarkNotificationAsReadMutation();
await markAsRead({ notification: number });

// Delete all notifications
const [deleteAll] = notificationApi.useDeleteAllNotificationsMutation();
await deleteAll();

// Delete single notification
const [deleteNotification] = notificationApi.useDeleteNotificationMutation();
await deleteNotification({ notification: number });
`

$3

`typescript
import { storiesApi } from 'buymeua-api-fe';

// Get stories
const { data, fetchNextPage, hasNextPage } = storiesApi.useGetStoriesInfiniteQuery({
sort_type?: 'created_at' | 'views_count' | 'sort_order' | 'viewed_order';
sort_direction?: 'asc' | 'desc';
per_page?: number;
});

// Increase story views
const [increaseViews] = storiesApi.useIncreaseStoryViewsMutation();
await increaseViews({ story: number });

// Get suppliers with stories (infinite scroll)
const { data, fetchNextPage, hasNextPage } = storiesApi.useGetSuppliersWithStoriesInfiniteQuery();

// Get suppliers with stories (pagination)
const { data } = storiesApi.useGetPaginatedSuppliersWithStoriesQuery({
page?: number;
});

// Get supplier story groups
const { data } = storiesApi.useGetSupplierStoryGroupsQuery({
customer: number;
});

// Get stories in a group
const { data } = storiesApi.useGetSupplierStoryGroupStoriesQuery({
customer: number;
supplierStoryGroup: number;
});

// Save story statistics
const [saveStats] = storiesApi.useSaveSupplierStoryStatisticsMutation();
await saveStats({
supplierStory: number;
type: 'view' | 'like' | 'unlike' | 'share' | 'reply';
});
`

$3

`typescript
import { supplierApi } from 'buymeua-api-fe';

// Get suppliers list
const { data, fetchNextPage, hasNextPage } = supplierApi.useGetSuppliersInfiniteQuery({
per_page?: number;
search?: string;
filter_buyme_category_ids?: number[];
});

// Get supplier info
const { data } = supplierApi.useGetSupplierInfoQuery({
customer: number;
});

// Get supplier articles
const { data, fetchNextPage, hasNextPage } = supplierApi.useGetSupplierArticlesInfiniteQuery({
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 } = supplierApi.useGetSupplierReviewsInfiniteQuery({
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';
});

// Add supplier review
const [addReview] = supplierApi.useAddSupplierReviewMutation();
await addReview({
supplier_id: number;
rating: number;
text: string;
});

// Reply to supplier review
const [replyToReview] = supplierApi.useReplyToSupplierReviewMutation();
await replyToReview({
review_id: number;
reply_text: string;
});

// Mark supplier as old
const [markAsOld] = supplierApi.useMarkSupplierAsOldMutation();
await markAsOld({ supplier: number });
`

$3

`typescript
import { novaposhtaApi } from 'buymeua-api-fe';

// Get Nova Poshta cities
const { data, fetchNextPage, hasNextPage } = novaposhtaApi.useGetNovaposhtaCitiesInfiniteQuery({
search?: string;
area?: string;
settlement_type?: string;
is_branch?: boolean;
per_page?: number;
});

// Get Nova Poshta streets
const { data, fetchNextPage, hasNextPage } = novaposhtaApi.useGetNovaposhtaStreetsInfiniteQuery({
search?: string;
city_ref: string;
streets_type?: string;
per_page?: number;
});

// Get Nova Poshta warehouses
const { data, fetchNextPage, hasNextPage } = novaposhtaApi.useGetNovaposhtaWarehousesInfiniteQuery({
search?: string;
city_ref: string;
type?: string;
per_page?: number;
});
`

$3

`typescript
import { orderApi } from 'buymeua-api-fe';

// Get orders list with infinite scroll
const { data, fetchNextPage, hasNextPage } = orderApi.useGetOrdersInfiniteQuery({
search?: string;
filter_order_id?: number;
filter_customer_id?: number;
filter_is_ttn_custom?: boolean;
filter_drop_name?: string;
filter_date_added?: string;
filter_drop_email?: string;
filter_customer_telephone?: string;
filter_customer_name?: string;
filter_drop_telephone?: string;
filter_email?: string;
filter_old_novaposhta_cn_number?: string;
filter_novaposhta_cn_number?: string;
filter_order_status_id?: number[];
filter_products_model?: string;
filter_products_name?: string;
filter_with_store?: boolean;
filter_without_store?: boolean;
});

// Check telephone number (blacklist, duplicates)
const { data } = orderApi.useCheckTelephoneQuery({
telephone: string;
});

// Get delivery methods for merchant
const { data } = orderApi.useGetDeliveryMethodsQuery({
merchant_id: number;
});

// Get payment methods for merchant
const { data } = orderApi.useGetPaymentMethodsQuery({
merchant_id: number;
custom_ttn?: string;
delivery_method_code?: string;
});

// Create order
const [createOrder] = orderApi.useCreateOrderMutation();
await createOrder({
merchant_id: number;
payment_method_code: string;
delivery_method_code?: string;
custom_ttn?: string;
firstname?: string;
lastname?: string;
middlename?: string;
telephone?: string;
email?: string;
comment?: string;
city_ref?: string;
warehouse_ref?: string;
shipping_street_id?: number;
shipping_house?: string;
shipping_flat?: string;
country_id?: number;
city?: string;
address?: string;
total_pay?: number;
custom_customer_id?: number;
category_order_id?: number;
ad_platform_page_id?: number;
ad_new_client?: boolean;
});
`

$3

`typescript
import { referralApi } from 'buymeua-api-fe';

// Get referral statistics
const { data, fetchNextPage, hasNextPage } = referralApi.useGetReferralStatisticsInfiniteQuery({
date_from?: string;
date_to?: string;
per_page?: number;
});

// Get referral transactions
const { data, fetchNextPage, hasNextPage } = referralApi.useGetReferralTransactionsInfiniteQuery({
referral_id: number;
date_from?: string;
date_to?: string;
per_page?: number;
});

// Track referral visit
const [trackVisit] = referralApi.useTrackReferralVisitMutation();
await trackVisit({
referral_id: number;
});
`

$3

`typescript
import { adApi } from 'buymeua-api-fe';

// Get ad pages
const { data } = adApi.useGetAdPagesQuery({
platform_id: number;
});

// Get ad platforms
const { data, fetchNextPage, hasNextPage } = adApi.useGetAdPlatformsInfiniteQuery({
per_page?: number;
});
`

$3

`typescript
import { countryApi } from 'buymeua-api-fe';

// Get countries list
const { data, fetchNextPage, hasNextPage } = countryApi.useGetCountriesInfiniteQuery({
search?: string;
per_page?: number;
});
`

$3

`typescript
import { storeApi } from 'buymeua-api-fe';

// Get store information
const { data } = storeApi.useGetStoreInfoQuery({
store: number;
});

// Get store articles/informations
const { data } = storeApi.useGetStoreArticlesQuery({
store: number;
});
`

$3

`typescript
import { systemApi } from 'buymeua-api-fe';

// Get maintenance status (with real-time Pusher updates)
const { data } = systemApi.useGetMaintenanceStatusQuery();
// data.enable: boolean - true if system is available

// Get version check for mobile apps (with real-time Pusher updates)
const { data } = systemApi.useGetVersionCheckQuery();
// data.ios.minimumVersion, data.ios.lastUpdatedVersion
// data.android.minimumVersion, data.android.lastUpdatedVersion

// Check if Telegram user exists
const { data } = systemApi.useCheckTelegramUserQuery({
telegram_user_name: 'username', // without @
});
// data.success: boolean
`

📋 TypeScript Types

The library is fully typed with TypeScript. Main types:

`typescript
interface ApiConfig {
baseUrl: string;
prepareHeaders?: (
headers: Headers,
api: {
getState: () => unknown;
extra: unknown;
endpoint: string;
type: 'query' | 'mutation';
forced?: boolean;
} & {
arg: unknown;
extraOptions: unknown;
},
) => Headers | void | Promise;
onUnauthorized?: (
args: string | FetchArgs,
api: BaseQueryApi,
extraOptions: unknown,
) => void;
}

enum Session {
Dropshipper = 'dropshipper',
Supplier = 'supplier',
Retail = 'retail',
}

interface PaginatedResponse {
meta: {
current_page: number;
last_page: number;
per_page: number;
total: number;
from: number;
to: number;
};
links: {
first: string;
last: string;
prev: string | null;
next: string | null;
};
}
``

📄 License

ISC License - see the LICENSE file for details.