node-mealie

A Node.js wrapper for the Mealie API with TypeScript support, Deno compatibility, and ESM module support.

Features

• 🚀 TypeScript support
• 📦 ESM and CommonJS compatible
• 🦕 Deno compatible
• 🔒 Authentication handling (Username/Password, OAuth/OIDC)
• 🧪 100% test coverage
• 🛠️ Extensible architecture

Installation

npm install node-mealie

Usage

Basic Usage

import { AboutService } from 'node-mealie';

const client = new AboutService({
  baseUrl: 'https://demo.mealie.io', // optional, defaults to demo instance
});

// Get app info
const appInfo = await client.getAppInfo();
console.log(appInfo.version);

// Get startup info
const startupInfo = await client.getStartupInfo();
console.log(startupInfo.isDemo);

// Get app theme
const theme = await client.getAppTheme();
console.log(theme);

Groups Management

import { MealieClient, GroupsService } from 'node-mealie';

const client = new MealieClient({
  baseUrl: 'https://your-mealie-instance.com',
  token: 'your-auth-token'
});

const groups = new GroupsService(client);

// Get current group
const currentGroup = await groups.getSelf();

// Get all households
const households = await groups.getAllHouseholds({
  page: 1,
  perPage: 10,
  orderBy: 'name',
  orderDirection: 'asc'
});

// Get group members
const members = await groups.getGroupMembers();

// Check storage usage
const storage = await groups.getStorage();
console.log(`Using ${storage.usedStorageStr} of ${storage.totalStorageStr}`);

// Manage labels
const label = await groups.createLabel({ name: 'Vegetarian' });
const labels = await groups.getAllLabels({ search: 'veg' });

// Start data migration
const migrationFile = new File(['...data...'], 'migration.zip');
const report = await groups.startDataMigration({
  migration_type: 'chowdown',
  archive: migrationFile
});

Households Management

import { MealieClient, HouseholdsService } from 'node-mealie';

const client = new MealieClient({
  baseUrl: 'https://your-mealie-instance.com',
  username: 'your-username',
  password: 'your-password'
});

const households = new HouseholdsService(client);

// Create a cookbook
const cookbook = await households.createCookbook({
  name: 'Italian Recipes',
  description: 'A collection of Italian dishes',
  public: true
});

// Create a shopping list
const shoppingList = await households.createShoppingList({
  name: 'Weekly Groceries'
});

// Add items to shopping list
const item = await households.createShoppingListItem({
  shoppingListId: shoppingList.id,
  note: 'Milk',
  quantity: 1
});

// Create a meal plan
const mealPlan = await households.createMealplan({
  date: '2025-04-25',
  entryType: 'dinner',
  title: 'Pasta Night'
});

// Get household statistics
const stats = await households.getStatistics();
console.log(`Total recipes: ${stats.totalRecipes}`);

Authentication

import { AuthService } from 'node-mealie';

const auth = new AuthService({
  baseUrl: 'https://your-mealie-instance.com'
});

// Standard login
const token = await auth.login('username', 'password');

// OAuth/OIDC login
const { redirectUrl } = await auth.oauthLogin();
// Redirect user to OAuth provider...

// Handle OAuth callback
const callbackToken = await auth.oauthCallback({ code: 'auth-code' });

// Refresh token
const newToken = await auth.refreshToken();

// Logout
await auth.logout();

With Existing Token

import { AboutService } from 'node-mealie';

// Use existing token
const client = new AboutService();
client.setToken('your-auth-token');

Deno Usage

import { AboutService } from "https://deno.land/x/node_mealie/mod.ts";

const client = new AboutService();
const appInfo = await client.getAppInfo();
console.log(appInfo.version);

API Reference

AboutService

• getAppInfo(): Get general application information
• getStartupInfo(): Get startup information
• getAppTheme(): Get current theme settings

AuthService

• login(username: string, password: string): Authenticate with credentials
• oauthLogin(): Initiate OAuth login flow
• oauthCallback(params: OAuthCallbackParams): Handle OAuth callback
• refreshToken(): Refresh authentication token
• logout(): Log out the current user
• setToken(token: string): Set authentication token manually
• clearToken(): Clear authentication token

HouseholdsService

The HouseholdsService provides comprehensive functionality for managing household-related features:

Cookbooks

• getCookbooks(params?): Get all cookbooks
• createCookbook(data): Create a new cookbook
• updateCookbook(id, data): Update a cookbook
• deleteCookbook(id): Delete a cookbook

Shopping Lists

• getShoppingLists(params?): Get all shopping lists
• createShoppingList(data): Create a new shopping list
• createShoppingListItem(data): Add item to a list
• updateShoppingListItem(id, data): Update an item
• addRecipeIngredientsToList(id, data): Add recipe ingredients to list

Meal Plans

• getMealplans(params?): Get meal plans
• createMealplan(data): Create a meal plan
• getTodaysMeals(): Get today's meal plans
• createRandomMeal(data): Create a random meal plan
• createMealplanRule(data): Create meal plan rules

Household Management

• getSelf(): Get current household information
• getHouseholdPreferences(): Get household preferences
• updateHouseholdPreferences(data): Update preferences
• setMemberPermissions(data): Set member permissions
• getStatistics(): Get household statistics

Invitations

• getInviteTokens(): Get all invite tokens
• createInviteToken(data): Create new invite token
• emailInvitation(data): Send email invitation

Full API documentation

GroupsService

The GroupsService provides functionality for managing groups, households, migrations, reports, and more:

Group Information

• getSelf(): Get current group information
• getGroupMembers(params?): Get members in the group
• getGroupMember(usernameOrId): Get specific member details
• getGroupPreferences(): Get group preferences
• updateGroupPreferences(data): Update group preferences
• getStorage(): Get storage usage information

Households

• getAllHouseholds(params?): Get all households within a group
• getOneHousehold(householdSlug): Get specific household details

Migrations

• startDataMigration(params): Import data from other platforms (Nextcloud, Chowdown, etc.)

Reports

• getAllReports(reportType?): Get all reports or filter by type
• getOneReport(itemId): Get specific report details
• deleteOneReport(itemId): Delete a report

Multi-Purpose Labels

• createLabel(data): Create a new label
• getAllLabels(params?): Get all labels with optional search
• getOneLabel(itemId): Get specific label
• updateLabel(itemId, data): Update a label
• deleteLabel(itemId): Delete a label

Seeders

• seedFoods(config): Initialize food data
• seedLabels(config): Initialize label data
• seedUnits(config): Initialize unit data

Full Groups API documentation

OrganizerService

The OrganizerService provides functionality for managing recipe organization features including categories, tags, and tools:

Categories

• getAllCategories(params?): Get all categories with optional pagination and filtering
• createCategory(data): Create a new category
• getAllEmptyCategories(): Get all categories without recipes
• getCategoryById(id): Get specific category by ID
• updateCategory(id, data): Update a category
• deleteCategory(id): Delete a category
• getCategoryBySlug(slug): Get category by slug

Tags

• getAllTags(params?): Get all tags with optional pagination and filtering
• createTag(data): Create a new tag
• getEmptyTags(): Get all tags without recipes
• getTagById(id): Get specific tag by ID
• updateTag(id, data): Update a tag
• deleteTag(id): Delete a tag
• getTagBySlug(slug): Get tag by slug

Tools

• getAllTools(params?): Get all tools with optional pagination and filtering
• createTool(data): Create a new tool
• getToolById(id): Get specific tool by ID
• updateTool(id, data): Update a tool
• deleteTool(id): Delete a tool
• getToolBySlug(slug): Get tool by slug

import { OrganizerService } from 'node-mealie';

const organizers = new OrganizerService({
  baseUrl: 'https://your-mealie-instance.com',
  token: 'your-auth-token'
});

// Work with categories
const categories = await organizers.getAllCategories({ search: 'breakfast' });
const newCategory = await organizers.createCategory({ name: 'Desserts' });

// Work with tags
const tags = await organizers.getAllTags({ orderBy: 'name' });
const newTag = await organizers.createTag({ name: 'Vegetarian' });

// Work with tools
const tools = await organizers.getAllTools({ page: 1, perPage: 10 });
const newTool = await organizers.createTool({ name: 'Food Processor' });

Full Organizers API documentation

CommentsService

The CommentsService provides functionality for managing recipe comments, including CRUD operations and filtering:

Comment Operations

• getAllComments(params?): Get all comments with optional filtering and pagination
• createComment(data): Create a new comment for a recipe
• getComment(commentId): Get specific comment by ID
• updateComment(commentId, data): Update an existing comment
• deleteComment(commentId): Delete a comment

import { CommentsService } from 'node-mealie';

const comments = new CommentsService({
  baseUrl: 'https://your-mealie-instance.com',
  token: 'your-auth-token'
});

// Get all comments with filtering
const allComments = await comments.getAllComments({
  page: 1,
  perPage: 20,
  orderBy: 'createdAt',
  orderDirection: 'desc',
  queryFilter: 'delicious'
});

// Create a new comment
const newComment = await comments.createComment({
  recipeId: 'recipe-uuid',
  text: 'This recipe is amazing!'
});

// Update a comment
const updatedComment = await comments.updateComment(newComment.id, {
  id: newComment.id,
  text: 'Updated: This recipe is even better with extra cheese!'
});

// Delete a comment
await comments.deleteComment(newComment.id);

Full Comments API documentation

IngredientParserService

The IngredientParserService provides functionality for parsing natural language ingredient descriptions into structured data components:

Parser Operations

• parseIngredient(ingredient, acceptLanguage?): Parse a single ingredient string
• parseIngredients(ingredients, acceptLanguage?): Parse multiple ingredient strings in bulk

import { IngredientParserService } from 'node-mealie';

const parser = new IngredientParserService({
  baseUrl: 'https://your-mealie-instance.com',
  token: 'your-auth-token'
});

// Parse a single ingredient
const result = await parser.parseIngredient('2 cups all-purpose flour');
console.log(result.quantity); // 2
console.log(result.unit); // "cups"
console.log(result.food); // "all-purpose flour"

// Parse multiple ingredients
const results = await parser.parseIngredients([
  '2 cups all-purpose flour',
  '1 tsp vanilla extract',
  '3 large eggs, room temperature'
]);

// Parse with localization
const frenchResult = await parser.parseIngredient('2 tasses de farine', 'fr-FR');

Full Ingredient Parser API documentation

FoodsService

The FoodsService provides functionality for managing food items, including CRUD operations, merging, and filtering:

Food Operations

• getAllFoods(params?): Get all foods with optional filtering and pagination
• createFood(data): Create a new food item
• getOne(itemId): Get specific food by ID
• updateFood(itemId, data): Update an existing food item
• deleteFood(itemId): Delete a food item
• mergeFoods(data): Merge two food items into one

import { FoodsService } from 'node-mealie';

const foods = new FoodsService({
  baseUrl: 'https://your-mealie-instance.com',
  token: 'your-auth-token'
});

// Get all foods with filtering
const allFoods = await foods.getAllFoods({
  search: 'tomato',
  orderBy: 'name',
  orderDirection: 'asc',
  page: 1,
  perPage: 50
});

// Create a new food
const newFood = await foods.createFood({ name: 'Cherry Tomatoes' });

// Update a food
const updatedFood = await foods.updateFood(newFood.id, {
  name: 'Roma Tomatoes'
});

// Merge foods
await foods.mergeFoods({
  fromFood: 'food-123',
  toFood: 'food-456'
});

// Delete a food
await foods.deleteFood(newFood.id);

Full Foods API documentation

AdminService

The AdminService provides functionality for system administration tasks, requiring administrator privileges:

Application Management

• getAppInfo(acceptLanguage?): Get detailed application information
• getAppStatistics(acceptLanguage?): Get usage statistics
• checkAppConfig(acceptLanguage?): Check configuration status

User Management

• getAllUsers(options?): Get paginated list of users
• createUser(data, acceptLanguage?): Create new user account
• getUser(userId, acceptLanguage?): Get specific user details
• updateUser(userId, data, acceptLanguage?): Update user
• deleteUser(userId, acceptLanguage?): Delete user
• unlockUsers(force?, acceptLanguage?): Unlock user accounts
• generatePasswordResetToken(data, acceptLanguage?): Generate password reset

Household Management

• getAllHouseholds(options?): Get paginated list of households
• createHousehold(data, acceptLanguage?): Create new household
• getHousehold(householdId, acceptLanguage?): Get specific household
• updateHousehold(householdId, data, acceptLanguage?): Update household
• deleteHousehold(householdId, acceptLanguage?): Delete household

Group Management

• getAllGroups(options?): Get paginated list of groups
• createGroup(data, acceptLanguage?): Create new group
• getGroup(groupId, acceptLanguage?): Get specific group
• updateGroup(groupId, data, acceptLanguage?): Update group
• deleteGroup(groupId, acceptLanguage?): Delete group

Backup Management

• getAllBackups(acceptLanguage?): List all backups
• createBackup(acceptLanguage?): Create system backup
• getBackupToken(fileName, acceptLanguage?): Get backup download token
• deleteBackup(fileName, acceptLanguage?): Delete backup
• uploadBackup(file, acceptLanguage?): Upload backup file
• restoreBackup(fileName, acceptLanguage?): Restore from backup

System Maintenance

• getMaintenanceSummary(acceptLanguage?): Get maintenance summary
• getStorageDetails(acceptLanguage?): Get storage details
• cleanImages(acceptLanguage?): Clean unused images
• cleanTemp(acceptLanguage?): Clean temporary files
• cleanRecipeFolders(acceptLanguage?): Clean recipe folders

Email & Debug

• checkEmailConfig(acceptLanguage?): Check email configuration
• sendTestEmail(data, acceptLanguage?): Send test email
• debugOpenAI(file?, acceptLanguage?): Debug OpenAI integration

import { AdminService } from 'node-mealie';

const admin = new AdminService({
  baseUrl: 'https://your-mealie-instance.com',
  token: 'your-admin-token'
});

// Get application statistics
const stats = await admin.getAppStatistics();
console.log(`Total recipes: ${stats.totalRecipes}`);

// User management
const users = await admin.getAllUsers({ page: 1, perPage: 10 });
const newUser = await admin.createUser({
  username: 'newuser',
  fullName: 'New User',
  email: 'user@example.com',
  password: 'password123'
});

// Create backup
const backup = await admin.createBackup();
console.log('Backup created:', backup.message);

Full Admin API documentation

UtilsService

The UtilsService provides utility functions for file downloads and other utility operations within Mealie:

File Downloads

• downloadFile(params?): Download a file from the server, optionally with a specific token

import { UtilsService } from 'node-mealie';

const utils = new UtilsService({
  baseUrl: 'https://your-mealie-instance.com',
  token: 'your-auth-token'
});

// Download a file
const fileBlob = await utils.downloadFile();

// Download with a specific token
const fileBlob = await utils.downloadFile({ token: 'special-token' });

// Save in browser
const url = URL.createObjectURL(fileBlob);
const link = document.createElement('a');
link.href = url;
link.download = 'downloaded-file';
link.click();
URL.revokeObjectURL(url);

// Save in Node.js
import { writeFile } from 'fs/promises';
const buffer = await fileBlob.arrayBuffer();
await writeFile('downloaded-file', Buffer.from(buffer));

Full Utils API documentation

ExploreService

The ExploreService provides functionality for browsing and discovering public content within Mealie groups. This service is designed for unauthenticated access to public content or can be used with authentication for private groups:

Foods & Ingredients

• getFoods(groupSlug, params?): Browse available foods in a group
• getFood(groupSlug, itemId, acceptLanguage?): Get specific food details

Households

• getHouseholds(groupSlug, params?): Browse households in a group
• getHousehold(groupSlug, householdSlug, acceptLanguage?): Get household details

Organization

• getCategories(groupSlug, params?): Browse recipe categories
• getCategory(groupSlug, itemId, acceptLanguage?): Get category details
• getTags(groupSlug, params?): Browse recipe tags
• getTag(groupSlug, itemId, acceptLanguage?): Get tag details
• getTools(groupSlug, params?): Browse cooking tools
• getTool(groupSlug, itemId, acceptLanguage?): Get tool details

Cookbooks & Recipes

• getCookbooks(groupSlug, params?): Browse cookbooks
• getCookbook(groupSlug, itemId, acceptLanguage?): Get cookbook details
• getRecipes(groupSlug, params?): Search recipes with complex filters
• getRecipe(groupSlug, recipeSlug, acceptLanguage?): Get recipe details
• getRecipeSuggestions(groupSlug, params?): Get recipe suggestions based on available ingredients

import { ExploreService } from 'node-mealie';

const explore = new ExploreService({
  baseUrl: 'https://your-mealie-instance.com'
  // Authentication optional for public content
});

// Browse recipes with filters
const recipes = await explore.getRecipes('public-recipes', {
  categories: ['desserts', 'quick-meals'],
  tags: ['vegetarian'],
  search: 'pasta',
  page: 1,
  perPage: 20
});

// Get recipe suggestions based on what you have
const suggestions = await explore.getRecipeSuggestions('public-recipes', {
  foods: ['tomatoes', 'basil', 'garlic', 'pasta'],
  tools: ['pot', 'knife'],
  limit: 5,
  maxMissingFoods: 2
});

// Browse content in different languages
const frenchCategories = await explore.getCategories('cuisine-francaise', {
  acceptLanguage: 'fr-FR'
});

Full Explore API documentation

Configuration Options

interface MealieClientOptions {
  baseUrl?: string;      // Base URL for the Mealie API
  token?: string;        // Authentication token
  username?: string;     // Username for authentication
  password?: string;     // Password for authentication
  debug?: boolean;       // Enable debug logging
}

Error Handling

The library throws MealieError for all API errors:

try {
  await client.getAppInfo();
} catch (error) {
  if (error instanceof MealieError) {
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Response:', error.response);
  }
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

License

MIT