Node-Bring-Shopping

A zero dependency Node.js wrapper for the Bring! shopping list API, entirely written in TypeScript with full feature parity to the Python bring-api package.

✨ Features

🎯 Complete API Coverage - All Bring! API endpoints implemented
🔄 Modern Batch Operations - Efficient item management with batchUpdateList()
🍽️ Recipe Inspirations - Browse and import seasonal recipes
📱 Activity Tracking - Monitor list changes and notifications
🔒 Type-Safe - Full TypeScript definitions included
⚡ Zero Dependencies - Uses native Node.js fetch API
🛠️ CLI Tools - Includes bring-recipes command-line tool

Requirements

Node.js 18.0.0 or higher

Installation

npm install bring-shopping

Quick Start

const Bring = require('bring-shopping');

async function main() {
    // Initialize with credentials
    const bring = new Bring({
        mail: 'your@email.com',
        password: 'yourpassword'
    });

    // Login
    await bring.login();
    console.log(`Logged in as ${bring.name}`);

    // Get all lists
    const lists = await bring.loadLists();
    const listUuid = lists.lists[0].listUuid;

    // Get items from a list
    const items = await bring.getItems(listUuid);
    console.log('Shopping list:', items.purchase);

    // Add item using modern batch API
    await bring.batchUpdateList(listUuid, [{
        itemId: 'Milk',
        spec: '2 liters',
        operation: 'TO_PURCHASE'
    }]);
}

main();

API Reference

Authentication

`login()`

Authenticate with Bring! and obtain access tokens.

await bring.login();

`getUserAccount()`

Get current user profile information.

const user = await bring.getUserAccount();
console.log(user.email, user.publicUserUuid);

List Management

`loadLists()`

Get all shopping lists.

const lists = await bring.loadLists();
// { lists: [{ listUuid, name, theme }] }

`getItems(listUuid)`

Get all items from a specific list.

const items = await bring.getItems(listUuid);
// { purchase: [...], recently: [...] }

`getItemsDetails(listUuid)`

Get detailed information about list items.

const details = await bring.getItemsDetails(listUuid);

Item Operations (Legacy)

`saveItem(listUuid, itemName, specification)`

Add an item to a list.

await bring.saveItem(listUuid, 'Milk', '2 liters');

`removeItem(listUuid, itemName)`

Remove an item from a list.

await bring.removeItem(listUuid, 'Milk');

`moveToRecentList(listUuid, itemName)`

Move item to recently purchased.

await bring.moveToRecentList(listUuid, 'Milk');

Item Operations (Modern Batch API) 🆕

`batchUpdateList(listUuid, items, options?)`

Perform batch operations on multiple items atomically.

await bring.batchUpdateList(listUuid, [
    { itemId: 'Milk', spec: '2L', operation: 'TO_PURCHASE' },
    { itemId: 'Bread', spec: '', operation: 'TO_PURCHASE' },
    { itemId: 'Eggs', spec: '', operation: 'TO_RECENTLY' }
]);

Operations:

TO_PURCHASE - Add to shopping list
TO_RECENTLY - Mark as purchased
REMOVE - Delete from list

`updateItem(listUuid, itemId, spec, uuid?)` 🆕

Update an existing item's specification.

await bring.updateItem(listUuid, 'Milk', '3 liters');

`completeItem(listUuid, itemId, spec, uuid?)` 🆕

Mark an item as purchased.

await bring.completeItem(listUuid, 'Milk', '2 liters');

User & Settings 🆕

`getAllUsersFromList(listUuid)`

Get all users with access to a list.

const users = await bring.getAllUsersFromList(listUuid);

`getUserSettings()`

Get user settings and preferences.

const settings = await bring.getUserSettings();

`setListArticleLanguage(listUuid, language)` 🆕

Set language preference for a list.

await bring.setListArticleLanguage(listUuid, 'de-DE');

Activity & Notifications 🆕

`getActivity(listUuid)` 🆕

Get activity timeline for a list.

const activity = await bring.getActivity(listUuid);
// { timeline: [...], totalEvents: 42 }

`notify(listUuid, notificationType, args?)` 🆕

Send notifications to list members.

await bring.notify(listUuid, 'GOING_SHOPPING', ['store name']);

Notification Types:

GOING_SHOPPING
CHANGED_LIST
SHOPPING_DONE
URGENT_MESSAGE

Recipe Inspirations 🆕

`getInspirations(filterTags?, offset?, limit?)` 🆕

Get recipe and meal suggestions.

const recipes = await bring.getInspirations(['seasonal'], 0, 10);
// { entries: [...], count: 10, total: 100 }

`getInspirationFilters()` 🆕

Get available filter categories for recipes.

const filters = await bring.getInspirationFilters();
// { filters: [{ id, name, tags, ... }] }

Translations & Catalog

`loadTranslations(locale)`

Get item name translations.

const translations = await bring.loadTranslations('de-DE');
// { "Milk": "Milch", ... }

`loadCatalog(locale)`

Get complete item catalog with categories.

const catalog = await bring.loadCatalog('de-DE');

Images

`saveItemImage(itemUuid, image)`

Add an image to an item.

await bring.saveItemImage(itemUuid, { imageData: base64String });

`removeItemImage(itemUuid)`

Remove an item's image.

await bring.removeItemImage(itemUuid);

Other

`getPendingInvitations()`

Get pending list invitations.

const invites = await bring.getPendingInvitations();

CLI Tools

bring-recipes

CLI for browsing Bring! recipe inspirations. Browse-only - recipe ingredients are not available via the Bring! Inspirations API.

Installation:

cd skills/bring-recipes
npm install

Usage:

# Set credentials
export BRING_EMAIL="your@email.com"
export BRING_PASSWORD="yourpassword"

# Browse recipes
node index.js list

# Filter recipes
node index.js list --filter mine

# Show available filters
node index.js filters

# JSON output for scripting
node index.js list --json

Features:

Browse recipe inspirations (TEMPLATE, RECIPE, POST types)
Filter by tags (all, mine)
View recipe metadata (name, author, images, links, likes)
JSON mode for automation
⚠️ Note: Cannot import ingredients (API limitation)

API Limitation: The Bring! getInspirations() API returns only recipe metadata, not ingredient lists. This CLI is designed for recipe discovery and browsing only.

See skills/bring-recipes/README.md for full documentation.

bring-add

CLI for adding items to Bring! shopping lists. Supports quick mode, batch mode, stdin, and interactive mode.

Installation:

cd skills/bring-add
npm install

Usage:

# Set credentials
export BRING_EMAIL="your@email.com"
export BRING_PASSWORD="yourpassword"
export BRING_DEFAULT_LIST="Shopping"  # optional

# Quick mode - single item
node index.js "Tomatoes" "500g"

# Batch mode - multiple items
node index.js --batch "Tomatoes 500g, Onions, Cheese 200g"

# Stdin mode - pipe items
echo -e "Milk 1L\nBread" | node index.js -

# Dry-run - preview without adding
node index.js --dry-run --batch "Apples, Pears"

# JSON output for scripting
node index.js --json lists

# Interactive mode
node index.js

Features:

Quick, batch, stdin, and interactive input modes
--dry-run for previewing changes
--json for machine-readable output
--quiet for scripts
Smart parsing: Tomatoes 500g → item: "Tomatoes", spec: "500g"
Follows CLI Guidelines

See skills/bring-add/README.md for full documentation.

TypeScript Support

Full TypeScript definitions included:

import Bring = require('bring-shopping');

const bring = new Bring({
    mail: 'your@email.com',
    password: 'yourpassword'
});

// Full type inference
const lists: LoadListsResponse = await bring.loadLists();
const items: GetItemsResponse = await bring.getItems(lists.lists[0].listUuid);

Error Handling

All methods throw errors with descriptive messages:

try {
    await bring.login();
} catch (error) {
    if (error.message.includes('Cannot Login')) {
        console.error('Invalid credentials');
    }
}

Development

Building

npm install
npm run build

Testing

npm test

Project Structure

node-bring-api/
├── src/
│   └── bring.ts          # Main implementation
├── build/
│   ├── bring.js          # Compiled JavaScript
│   └── bring.d.ts        # TypeScript definitions
├── test/
│   ├── testMinimal.js
│   └── testNewApis.js    # Tests for new features
├── skills/
│   └── bring-recipes/    # CLI tool
└── docs/
    └── plans/            # Design documents

Comparison with Python Package

This package provides complete feature parity with bring-api (Python):

Feature	Node Package	Python Package	Status
Authentication	✅	✅	Complete
User account info	✅	✅	Complete
List management	✅	✅	Complete
Item operations	✅	✅	Complete
Batch operations	✅	✅	Complete
Activity tracking	✅	✅	Complete
Notifications	✅	✅	Complete
Recipe inspirations	✅	✅	Complete
Image management	✅	✅	Complete

Contributing

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

Disclaimer

The developers of this module are in no way endorsed by or affiliated with Bring! Labs AG, or any associated subsidiaries, logos or trademarks.

License

MIT

Changelog

2.0.2 (2026-01-27) 🎉

🆕 New API Methods - Complete feature parity with Python package
- getUserAccount() - Get user profile information
- batchUpdateList() - Modern batch item operations
- updateItem() - Update item specification
- completeItem() - Mark item as purchased
- getActivity() - Get list activity timeline
- notify() - Send notifications to list members
- getInspirations() - Get recipe suggestions
- getInspirationFilters() - Get recipe filter categories
- setListArticleLanguage() - Set list language preference
🔧 Improvements
- Added HTTP status checks to all new methods
- Proper TypeScript interfaces for all request/response types
- Fixed double response body read bug
- Comprehensive test suite for new features
🛠️ New CLI Tool
- bring-recipes - Interactive seasonal recipe CLI
- Auto-detects seasons, batch-adds ingredients
- Supports JSON output for scripting

2.0.1 (2025-01-21)

(@foxriver76) also throw on http errors

2.0.0 (2024-11-27)

(@foxriver76) ported to native fetch module (BREAKING: Requires Node.js 18 or above)

1.5.1 (2022-10-31)

(foxriver76) updated types
(foxriver76) fixed removeItemImage as headers were missing

1.5.0 (2022-10-31)

(Aliyss) added methods to link an image to an item (PR #221)

1.4.3 (2022-05-01)

(foxriver76) fixed typos in types (thanks to @Squawnchy)

1.4.2 (2021-08-12)

(foxriver76) restructure to typescript

1.3.1 (2021-04-29)

(foxriver76) fixed issue where error was used instead of the message on getPendingInvitations

1.3.0 (2020-10-05)

(mdhom) added getItemsDetails method
(foxriver76) now reject with real errors instead of strings

1.2.3 (2019-09-22)

(foxriver76) on new call of login overwrite bearer header to allow reauth

1.2.0

(foxriver76) new functionalities -> getTranslations, getCatalog and getPendingInvitations

1.1.0

(foxriver76) use API version v2

1.0.0

(foxriver76) official release

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
.github		.github
build		build
docs/plans		docs/plans
skills		skills
src		src
test		test
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierrc.json		.prettierrc.json
CODE_REVIEW_FIXES.md		CODE_REVIEW_FIXES.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Node-Bring-Shopping

✨ Features

Requirements

Installation

Quick Start

API Reference

Authentication

login()

getUserAccount()

List Management

loadLists()

getItems(listUuid)

getItemsDetails(listUuid)

Item Operations (Legacy)

saveItem(listUuid, itemName, specification)

removeItem(listUuid, itemName)

moveToRecentList(listUuid, itemName)

Item Operations (Modern Batch API) 🆕

batchUpdateList(listUuid, items, options?)

updateItem(listUuid, itemId, spec, uuid?) 🆕

completeItem(listUuid, itemId, spec, uuid?) 🆕

User & Settings 🆕

getAllUsersFromList(listUuid)

getUserSettings()

setListArticleLanguage(listUuid, language) 🆕

Activity & Notifications 🆕

getActivity(listUuid) 🆕

notify(listUuid, notificationType, args?) 🆕

Recipe Inspirations 🆕

getInspirations(filterTags?, offset?, limit?) 🆕

getInspirationFilters() 🆕

Translations & Catalog

loadTranslations(locale)

loadCatalog(locale)

Images

saveItemImage(itemUuid, image)

removeItemImage(itemUuid)

Other

getPendingInvitations()

CLI Tools

bring-recipes

bring-add

TypeScript Support

Error Handling

Development

Building

Testing

Project Structure

Comparison with Python Package

Contributing

Disclaimer

License

Changelog

2.0.2 (2026-01-27) 🎉

2.0.1 (2025-01-21)

2.0.0 (2024-11-27)

1.5.1 (2022-10-31)

1.5.0 (2022-10-31)

1.4.3 (2022-05-01)

1.4.2 (2021-08-12)

1.3.1 (2021-04-29)

1.3.0 (2020-10-05)

1.2.3 (2019-09-22)

1.2.0

1.1.0

1.0.0

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

`login()`

`getUserAccount()`

`loadLists()`

`getItems(listUuid)`

`getItemsDetails(listUuid)`

`saveItem(listUuid, itemName, specification)`

`removeItem(listUuid, itemName)`

`moveToRecentList(listUuid, itemName)`

`batchUpdateList(listUuid, items, options?)`

`updateItem(listUuid, itemId, spec, uuid?)` 🆕

`completeItem(listUuid, itemId, spec, uuid?)` 🆕

`getAllUsersFromList(listUuid)`

`getUserSettings()`

`setListArticleLanguage(listUuid, language)` 🆕

`getActivity(listUuid)` 🆕

`notify(listUuid, notificationType, args?)` 🆕

`getInspirations(filterTags?, offset?, limit?)` 🆕

`getInspirationFilters()` 🆕

`loadTranslations(locale)`

`loadCatalog(locale)`

`saveItemImage(itemUuid, image)`

`removeItemImage(itemUuid)`

`getPendingInvitations()`

Packages