W-List API Client

TypeScript API client for W-List wine management system with authentication, wine lists, and inventory management.

Installation

npm install w-list-api

Features

• 🔐 Authentication - Login, registration, token refresh
• 🍷 Wine Management - CRUD operations for wines and vintages
• 📋 Wine Lists - Create and manage wine lists
• 🏪 Shop Management - Shop configuration and settings
• 🌍 Geographic Data - Countries and regions management
• 🍇 Grape Varieties - Grape types management
• 💳 Purchase Orders - Payment and subscription management
• 📧 Invitations - User invitation system

Quick Start

Initialize the API Client

import { initializeAuth, api } from 'w-list-api';

// Initialize with your API configuration
initializeAuth({
  apiUrl: 'https://api.w-list.ru',
  router: {
    replace: (path: string) => {
      // Handle navigation (optional)
      console.log('Navigate to:', path);
    },
  },
});

Authentication

import { AuthService } from 'w-list-api';

// Login
const authResponse = await AuthService.login({
  email: '[email protected]',
  password: 'password',
});

// Register
const registerResponse = await AuthService.register({
  email: '[email protected]',
  password: 'password',
  name: 'John Doe',
});

// Get current user
const user = await AuthService.me();

// Logout
await AuthService.logout({});

Wine Management

import { WineManagmentService } from 'w-list-api';

// Get all wines
const wines = await WineManagmentService.getAll({
  page: 0,
  size: 20,
});

// Get wine by ID
const wine = await WineManagmentService.getById(123);

// Create new wine
const newWine = await WineManagmentService.create(
  {
    name: 'Château Margaux',
    category: 'RED',
    colour: 'RED',
    // ... other wine properties
  },
  wineImageFile // File object
);

Wine Lists

import { WineListService, WineListItemService, ActiveWineListService } from 'w-list-api';

// Create wine list
const wineList = await WineListService.create({
  name: 'Premium Wines',
  description: 'Our finest selection',
});

// Add wine to list
const wineItem = await WineListItemService.create({
  wineListId: wineList.id,
  wineId: 123,
  pricePerBottle: 1500,
  pricePerGlass: 200,
  glassVolume: 150,
});

// Get all items in list
const items = await WineListItemService.getAll(wineList.id, {
  page: 0,
  size: 50,
});

// Set active wine list
const activeList = await ActiveWineListService.setActiveList(wineList.id);

// Get glass list for shop
const glassList = await ActiveWineListService.getActiveListGlass(shopId);
console.log(glassList.categories.RED?.data.length); // количество красных вин

// Get bottle list for shop
const bottleList = await ActiveWineListService.getActiveListBottle(shopId);
console.log(bottleList.categories.WHITE?.data.length); // количество белых вин

Geographic Data

import { CountryService, RegionService } from 'w-list-api';

// Get all countries
const countries = await CountryService.getAll();

// Get regions by country
const regions = await RegionService.getAll(countryId);

API Reference

Services

AuthService

• login(request: LoginRequest): Promise<AuthResponse>
• register(request: RegistrationRequest): Promise<AuthResponse>
• me(): Promise<Me>
• logout(request: LogoutRequest): Promise<any>
• refresh(payload: any): Promise<AuthResponse>
• refreshIfNeeded(): Promise<boolean>

WineManagmentService

• getAll(params: WineManagmentRequest): Promise<WineManagmentResponse>
• getById(id: number): Promise<WineManagment>
• create(request: WineManagmentCreateRequest, image: File): Promise<WineManagment>
• update(id: number, data: WineManagmentUpdateRequest): Promise<WineManagment>
• delete(id: number): Promise<any>
• search(params: WineManagmentSearch): Promise<WineManagmentResponse>

WineListService

• getAll(): Promise<ActiveWineListWine[]>
• getById(id: number): Promise<ActiveWineListWine>
• create(data: CreateOrUpdateWineListRequest): Promise<ActiveWineListWine>
• update(id: number, data: CreateOrUpdateWineListRequest): Promise<ActiveWineListWine>
• delete(id: number): Promise<any>
• uploadImage(id: number, image: File): Promise<ActiveWineListWine>
• clone(body: { wineListId: number; name: string }): Promise<ActiveWineListWine>

ActiveWineListService

• setActiveList(id: number): Promise<ActiveWineListResponse>
• getActiveListGlass(shopId: number): Promise<ActiveWineListGlassCategories>
• getActiveListBottle(shopId: number): Promise<ActiveWineListBottle>
• getInfo(shopId: number): Promise<GetInfoResponse>

WineListItemService

• getAll(listId: number, params: WineListItemRequest): Promise<WineListItemResponses>
• getById(listId: number, itemId: number): Promise<WineListItem>
• create(data: CreateWineList): Promise<WineListItem>
• update(listId: number, itemId: number, data: UpdateWineListItem): Promise<WineListItem>
• delete(listId: number, itemId: number): Promise<any>
• searchByName(listId: number, params: SearchByNameRequest): Promise<WineListItem[]>

Core API

HTTP Client

import { api, initializeAuth } from 'w-list-api';

// Direct API calls
const response = await api.get('/wines');
const wines = response.data;

Token Management

import { getToken, setToken, clearTokens, hasValidToken } from 'w-list-api';

// Check if user is authenticated
if (hasValidToken()) {
  // User is logged in
}

// Get access token
const token = getToken('accessToken');

Error Handling

All services use consistent error handling with ApiError:

import { ApiError } from 'w-list-api';

try {
  const wines = await WineManagmentService.getAll({ page: 0, size: 20 });
} catch (error) {
  if (error instanceof ApiError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Details:', error.details);
  }
}

Configuration

Environment Variables

The client automatically detects the API URL from environment variables:

• VITE_API_URL (for Vite projects)
• API_URL (fallback)

Environment Detection

The package automatically detects the environment based on:

1. Environment Variable: VITE_API_URL (highest priority)
2. Hostname:
   • stage, dev, localhost → Staging API (https://stage-api.w-list.ru)
   • Everything else → Production API (https://api.w-list.ru)

API URLs

import { API_URLS, getApiUrl, isProduction, isStaging } from 'w-list-api';

// Get current API URL
const currentUrl = getApiUrl();

// Check environment
if (isProduction()) {
  console.log('Using production API');
}

if (isStaging()) {
  console.log('Using staging API');
}

// Access URLs directly
console.log(API_URLS.PRODUCTION); // 'https://api.w-list.ru'
console.log(API_URLS.STAGING); // 'https://stage-api.w-list.ru'

Manual Configuration

You can override the API URL by setting the VITE_API_URL environment variable:

# .env
VITE_API_URL=https://stage-api.w-list.ru

Authentication Configuration

initializeAuth({
  apiUrl: 'https://api.w-list.ru',
  router: {
    replace: (path: string) => {
      // Handle navigation on auth events
    },
  },
  maxRetries: 3, // Token refresh retry attempts
  retryDelay: 1000, // Delay between retries (ms)
  refreshThreshold: 5 * 60 * 1000, // Refresh token 5 minutes before expiry
});

Development

Building

npm run build

Type Checking

npm run check:types

Publishing

npm run total

License

ISC

Support

• Issues: GitHub Issues
• Repository: GitHub Repository