ts-our-groceries

Unofficial TypeScript/Node.js wrapper for the Our Groceries shopping list API.

Install

npm install ts-our-groceries
pnpm add ts-our-groceries
yarn add ts-our-groceries

Quick Start

import { OurGroceries } from 'ts-our-groceries'

const og = new OurGroceries()  // uses OUR_GROCERIES_USERNAME/PASSWORD env vars
await og.login()

const lists = await og.getMyLists()
const items = await og.getListItems(lists.shoppingLists[0].id)

Features

| Feature | Description | |---------|-------------| | List Management | Get, create, rename, and delete shopping lists | | Item Operations | Add, remove, update, and cross off items | | Batch Operations | Add/remove/toggle multiple items at once | | Categories | Manage item categories | | Search Helpers | Find lists and items by name | | Session Persistence | Save/restore sessions to avoid repeated logins | | Auto-Retry | Exponential backoff for transient failures | | Type-Safe | Full TypeScript support with runtime validation |

Documentation

• API Reference - Complete API documentation
• Features Guide - Detailed feature guides
• Architecture - Internal architecture overview
• Error Handling - Handling errors gracefully
• Contributing - How to contribute

Architecture

The library is organized into logical modules:

src/
├── http/        # HTTP client with retry support
├── auth/        # Authentication & session management
├── operations/  # API operations by domain (lists, items, categories)
└── helpers/     # Utility helpers (search)

• HttpClient - Handles all HTTP communication with auto-authentication
• Authenticator - Login flow and session extraction
• SessionManager - Session persistence for avoiding repeated logins
• Operations - Domain-specific API operations
• SearchHelpers - Convenient search utilities

Basic Usage

Authentication

// Via environment variables
const og = new OurGroceries()

// Or pass credentials directly
const og = new OurGroceries({
  username: '[email protected]',
  password: 'your-password',
})

await og.login()

Lists

// Get all lists
const { shoppingLists, recipes } = await og.getMyLists()

// Create a new list
await og.createList('Weekly Groceries')

// Rename a list
await og.renameList('list-id', 'New Name')

// Delete a list
await og.deleteList('list-id')

Items

// Get items
const { list } = await og.getListItems('list-id')

// Add item
await og.addItemToList('list-id', 'Milk', { note: '2% organic' })

// Add multiple items
await og.addItemsToList('list-id', [
  { value: 'Milk' },
  { value: 'Bread', categoryId: 'bakery-id' },
])

// Cross off
await og.toggleItemCrossedOff('list-id', 'item-id', true)

// Remove
await og.removeItemFromList('list-id', 'item-id')

Search

// Find a list by name
const list = await og.findListByName('shopping')

// Find items in a list
const items = await og.findItemsByName('list-id', 'milk')

Session Persistence

// Save session
const session = og.getSession()
// Store session somewhere (file, database, etc.)

// Restore later
og.restoreSession(savedSession)

License

MIT

Disclaimer

This is an unofficial wrapper. The Our Groceries API is not publicly documented and may change without notice.

Credits

Ported from py-our-groceries by ljmerza.