Wolt API

A production-ready TypeScript library for interacting with the Wolt API. This library provides type-safe access to Wolt's consumer and restaurant APIs.

Installation

npm install wolt-api

Features

• ✅ Type-safe: Full TypeScript support with comprehensive type definitions
• ✅ Production-ready: Error handling, timeouts, and robust request handling
• ✅ Flexible: Customizable fetch implementation and timeout settings
• ✅ Complete: All documented Wolt API endpoints supported
• ✅ Modern: ES modules with CommonJS compatibility

Quick Start

import { WoltClient } from "wolt-api";

const client = new WoltClient();

// List venues near a location
const venues = await client.listVenues({
  lat: "32.081171",
  lon: "34.780663",
});

console.log(`Found ${venues.length} venues`);

API Reference

WoltClient

The main client class for interacting with the Wolt API.

Constructor

new WoltClient(options?: WoltClientOptions)

Options:

• fetch?: typeof fetch - Custom fetch implementation (useful for testing)
• timeout?: number - Request timeout in milliseconds (default: 30000)

Example:

import { WoltClient } from "wolt-api";

// Default configuration
const client = new WoltClient();

// Custom timeout
const clientWithTimeout = new WoltClient({
  timeout: 10000, // 10 seconds
});

Methods

listVenues(params: LocationParams): Promise<VenueData[]>

Lists available venues (restaurants) near a location.

Parameters:

• lat: string - Latitude
• lon: string - Longitude

Example:

const venues = await client.listVenues({
  lat: "32.081171",
  lon: "34.780663",
});

venues.forEach((venue) => {
  console.log(`${venue.venue.name} - ${venue.venue.estimate} min`);
});

getVenueMenu(params: MenuParams): Promise<MenuItem[]>

Gets the menu for a specific venue.

Parameters:

• venue_id: string - Venue ID (required, can be obtained from listVenues())
• unit_prices?: boolean - Show unit prices (default: true)
• show_weighted_items?: boolean - Show weighted items (default: true)
• show_subcategories?: boolean - Show subcategories (default: true)

Example:

// First get venues to obtain venue IDs
const venues = await client.listVenues({
  lat: "32.081171",
  lon: "34.780663",
});

// Then get the menu using the venue ID
const menu = await client.getVenueMenu({
  venue_id: venues[0].venue.id,
});

menu.forEach((item) => {
  console.log(`${item.name}: ${item.baseprice / 100} ${item.category}`);
});

searchVenues(params: SearchVenuesParams): Promise<SearchVenueResult[]>

Searches for venues by query string.

Note: Search results return partial venue data (id, name, slug at minimum). For complete venue information, use listVenues or fetch individual venue details.

Parameters:

• q: string - Search query
• lat: string - Latitude
• lon: string - Longitude

Example:

const results = await client.searchVenues({
  q: "pizza",
  lat: "32.081171",
  lon: "34.780663",
});

console.log(`Found ${results.length} pizza places`);
results.forEach((result) => {
  console.log(`${result.venue.name} (${result.venue.slug})`);
});

searchItems(params: SearchItemsParams): Promise<ItemSearchResult[]>

Searches for menu items across venues.

Parameters:

• q: string - Search query
• lat: string - Latitude
• lon: string - Longitude

Example:

const items = await client.searchItems({
  q: "pizza",
  lat: "32.081171",
  lon: "34.780663",
});

items.forEach((item) => {
  console.log(`${item.name} at ${item.venue_name} - ${item.price / 100}`);
});

listCities(): Promise<City[]>

Lists all available cities.

Example:

const cities = await client.listCities();

cities.forEach((city) => {
  console.log(`${city.name}, ${city.country_code_alpha2}`);
});

refreshToken(params: RefreshTokenParams): Promise<TokenResponse>

Refreshes an access token using a refresh token.

Parameters:

• refresh_token: string - Refresh token
• grant_type: 'refresh_token' - Grant type (must be 'refresh_token')

Example:

const tokens = await client.refreshToken({
  refresh_token: "your-refresh-token",
  grant_type: "refresh_token",
});

console.log("New access token:", tokens.access_token);

Error Handling

The library throws WoltAPIError for API-related errors:

import { WoltClient, WoltAPIError } from "wolt-api";

const client = new WoltClient();

try {
  const venues = await client.listVenues({
    lat: "32.081171",
    lon: "34.780663",
  });
} catch (error) {
  if (error instanceof WoltAPIError) {
    console.error("API Error:", error.message);
    console.error("Status Code:", error.statusCode);
    console.error("Response:", error.response);
  } else {
    console.error("Unexpected error:", error);
  }
}

Type Definitions

The library exports comprehensive TypeScript types for all API responses:

import type {
  Venue,
  VenueData,
  MenuItem,
  ItemSearchResult,
  City,
  LocationParams,
  MenuParams,
} from "wolt-api";

function processVenue(venue: Venue) {
  // Type-safe access to venue properties
  console.log(venue.name, venue.online, venue.estimate);
}

Examples

Find nearby restaurants

import { WoltClient } from "wolt-api";

const client = new WoltClient();

async function findNearbyRestaurants(lat: string, lon: string) {
  const venues = await client.listVenues({ lat, lon });

  return venues
    .filter((v) => v.venue.online)
    .map((v) => ({
      name: v.venue.name,
      estimate: v.venue.estimate,
      rating: v.venue.rating?.score,
      priceRange: v.venue.price_range,
    }));
}

Search for a specific dish

import { WoltClient } from "wolt-api";

const client = new WoltClient();

async function findDish(dishName: string, lat: string, lon: string) {
  const items = await client.searchItems({
    q: dishName,
    lat,
    lon,
  });

  return items
    .filter((item) => item.is_available)
    .map((item) => ({
      name: item.name,
      venue: item.venue_name,
      price: item.price / 100,
      currency: item.currency,
    }));
}

Get menu with custom options

import { WoltClient } from "wolt-api";

const client = new WoltClient();

async function getMenu(venueId: string) {
  const menu = await client.getVenueMenu({
    venue_id: venueId,
    unit_prices: true,
    show_weighted_items: false,
    show_subcategories: true,
  });

  // Group by category
  const byCategory = menu.reduce((acc, item) => {
    if (!acc[item.category]) {
      acc[item.category] = [];
    }
    acc[item.category].push(item);
    return acc;
  }, {} as Record<string, typeof menu>);

  return byCategory;
}

Development

# Install dependencies
npm install

# Build the library
npm run build

# Type check
npm run typecheck

# Run tests
npm test

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

# Development mode with watch
npm run dev

Testing

The library includes comprehensive test coverage using Vitest. Tests cover:

• All API endpoints (listVenues, getVenueMenu, searchVenues, searchItems, listCities, refreshToken)
• Error handling (HTTP errors, network errors, timeouts)
• Edge cases (empty responses, missing data, malformed responses)
• Request/response validation

Unit Tests

Run unit tests (with mocks):

npm test

Integration Tests

Integration tests call the real Wolt API to ensure:

• API contract hasn't changed
• Response shapes match our type definitions
• The library works correctly with real API responses

Note: Integration tests are skipped by default to avoid unnecessary API calls. To run them:

npm run test:integration

Or set the environment variable:

INTEGRATION=true npm test -- src/client.integration.test.ts

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.