### Setup Development Environment

Source: https://github.com/miaucl/bring-api/blob/main/README.md

Instructions for setting up the Python development environment using a virtual environment and installing dependencies.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_dev.txt
```

--------------------------------

### Complete Shopping Workflow Example

Source: https://context7.com/miaucl/bring-api/llms.txt

This example demonstrates a full shopping workflow, including authentication, loading lists, adding items, notifying members, marking items as complete, and handling potential API errors. Ensure you have the necessary libraries installed (`aiohttp`, `bring_api`).

```python
import aiohttp
import asyncio
import uuid
from bring_api import (
    Bring,
    BringItemOperation,
    BringNotificationType,
    BringAuthException,
    BringRequestException,
    BringParseException,
)

async def shopping_workflow():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")

        try:
            # Authenticate
            await bring.login()
            print("Logged in successfully")

            # Get lists
            lists = await bring.load_lists()
            if not lists.lists:
                print("No shopping lists found")
                return

            shopping_list = lists.lists[0]
            print(f"Using list: {shopping_list.name}")

            # Add items with UUIDs for tracking
            items_to_add = [
                {"itemId": "Milk", "spec": "2% low fat", "uuid": str(uuid.uuid4())},
                {"itemId": "Bread", "spec": "sourdough", "uuid": str(uuid.uuid4())},
                {"itemId": "Eggs", "spec": "free range, dozen", "uuid": str(uuid.uuid4())},
            ]

            await bring.batch_update_list(
                shopping_list.listUuid,
                items_to_add,
                BringItemOperation.ADD
            )
            print(f"Added {len(items_to_add)} items")

            # Notify household
            await bring.notify(
                shopping_list.listUuid,
                BringNotificationType.CHANGED_LIST
            )
            print("Notified list members")

            # View current list
            items = await bring.get_list(shopping_list.listUuid)
            print(f"\nCurrent shopping list ({len(items.items.purchase)} items):")
            for item in items.items.purchase:
                print(f"  [ ] {item.itemId}: {item.specification}")

            # Mark items as complete
            for item in items.items.purchase[:2]:
                await bring.complete_item(
                    shopping_list.listUuid,
                    item.itemId,
                    item_uuid=item.uuid
                )
                print(f"  [x] Completed: {item.itemId}")

            # Notify shopping done
            await bring.notify(
                shopping_list.listUuid,
                BringNotificationType.SHOPPING_DONE
            )
            print("\nShopping complete!")

        except BringAuthException as e:
            print(f"Authentication error: {e}")
        except BringRequestException as e:
            print(f"Request failed: {e}")
        except BringParseException as e:
            print(f"Parse error: {e}")

# Handle Windows event loop issue
import sys
if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

asyncio.run(shopping_workflow())

```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://github.com/miaucl/bring-api/blob/main/README.md

Steps to install pre-commit for code quality checks and to run the hooks manually across all files.

```bash
pre-commit install

# Run the commit hooks manually
pre-commit run --all-files
```

--------------------------------

### Python Bring! API Usage Example

Source: https://github.com/miaucl/bring-api/blob/main/README.md

This example demonstrates the core functionalities of the bring-api Python package. It requires aiohttp for asynchronous operations and shows how to log in, manage shopping lists, add, retrieve, complete, and remove items. Ensure you replace 'MAIL' and 'PASSWORD' with your actual credentials.

```python
import aiohttp
import asyncio
import logging
import sys

from bring_api import Bring

logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)

async def main():
  async with aiohttp.ClientSession() as session:
    # Create Bring instance with email and password
    bring = Bring(session, "MAIL", "PASSWORD")
    # Login
    await bring.login()

    # Get information about all available shopping lists
    lists = (await bring.load_lists())["lists"]

    # Save an item with specifications to a certain shopping list
    await bring.save_item(lists[0]['listUuid'], 'Milk', 'low fat')

    # Save another item
    await bring.save_item(lists[0]['listUuid'], 'Carrots')

    # Get all the items of a list
    items = await bring.get_list(lists[0]['listUuid'])
    print(items)

    # Check off an item
    await bring.complete_item(lists[0]['listUuid'], 'Carrots')

    # Remove an item from a list
    await bring.remove_item(lists[0]['listUuid'], 'Milk')

asyncio.run(main())
```

--------------------------------

### Get All User Settings

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves user preferences and per-list settings including language configurations.

```APIDOC
## Get All User Settings

### Description
Retrieves user preferences and per-list settings including language configurations.

### Method
GET

### Endpoint
/settings

### Response
#### Success Response (200)
- **usersettings** (array) - An array of general user settings.
  - **key** (string) - The setting key.
  - **value** (string) - The setting value.
- **userlistsettings** (array) - An array of per-list settings.
  - **listUuid** (string) - The unique identifier of the shopping list.
  - **usersettings** (array) - An array of settings specific to the list.
    - **key** (string) - The setting key.
    - **value** (string) - The setting value.

### Response Example
```json
{
  "usersettings": [
    {
      "key": "defaultListUuid",
      "value": "list-uuid-1234"
    }
  ],
  "userlistsettings": [
    {
      "listUuid": "list-uuid-1234",
      "usersettings": [
        {
          "key": "listArticleLanguage",
          "value": "en-US"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Get Inspirations API

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves recipe suggestions and templates from Bring's inspiration stream. It supports fetching user-specific inspirations or trending recipes.

```APIDOC
## Get Inspirations

### Description
Retrieves recipe suggestions and templates from Bring's inspiration stream. It supports fetching user-specific inspirations or trending recipes.

### Method
GET

### Endpoint
/inspirations

### Parameters
#### Query Parameters
- **type** (string) - Required - Specifies the type of inspirations to retrieve. Use 'mine' for user's own templates/recipes or 'bring_trending_recipes' for trending recipes.

### Response
#### Success Response (200)
- **count** (integer) - The number of inspirations returned.
- **total** (integer) - The total number of available inspirations.
- **entries** (array) - A list of inspiration objects.
  - **content** (object) - The content of the inspiration.
    - **name** (string) - The name of the recipe or template.
    - **author** (string) - The author of the recipe or template (if available).
    - **likeCount** (integer) - The number of likes for the recipe (if available).
  - **template_type** (string) - The type of the inspiration (e.g., TEMPLATE, RECIPE).

### Request Example
```python
# This is a Python example demonstrating how to call the API
# Replace with actual API call structure if different from SDK
import aiohttp
import asyncio
from bring_api import Bring

async def get_inspirations_example():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()
        my_inspirations = await bring.get_inspirations("mine")
        print(f"My inspirations: {my_inspirations.count} of {my_inspirations.total}")

asyncio.run(get_inspirations_example())
```

### Response Example
```json
{
  "count": 5,
  "total": 5,
  "entries": [
    {
      "content": {
        "name": "Weekly Breakfast",
        "author": null,
        "likeCount": null
      },
      "template_type": "TEMPLATE"
    }
  ]
}
```
```

--------------------------------

### Get All User Settings with Python

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves user preferences and per-list settings, including language configurations. Requires authentication. Displays general user settings and specific settings for each list.

```python
import aiohttp
import asyncio
from bring_api import Bring

async def get_user_settings():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        settings = await bring.get_all_user_settings()

        print("User Settings:")
        for setting in settings.usersettings:
            print(f"  {setting.key}: {setting.value}")

        print("\nList Settings:")
        for list_setting in settings.userlistsettings:
            print(f"  List UUID: {list_setting.listUuid}")
            for setting in list_setting.usersettings:
                print(f"    {setting.key}: {setting.value}")

asyncio.run(get_user_settings())
```

--------------------------------

### Authenticate with Bring! API

Source: https://context7.com/miaucl/bring-api/llms.txt

Authenticates with the Bring! service using email and password. Requires `aiohttp` and `bring_api` to be installed. Handles `BringAuthException` and `BringRequestException`.

```python
import aiohttp
import asyncio
from bring_api import Bring, BringAuthException, BringRequestException

async def authenticate():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "your_password")

        try:
            auth_response = await bring.login()
            print(f"Logged in as: {auth_response.name}")
            print(f"User UUID: {auth_response.uuid}")
            print(f"Public UUID: {auth_response.publicUuid}")
            print(f"Token expires in: {auth_response.expires_in} seconds")
        except BringAuthException as e:
            print(f"Authentication failed: {e}")
        except BringRequestException as e:
            print(f"Request failed: {e}")

asyncio.run(authenticate())
```

--------------------------------

### Get Inspiration Filters from Bring API

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves available categories and filters for browsing inspirations. Use this to understand the available filtering options. Requires aiohttp and asyncio.

```python
import aiohttp
import asyncio
from bring_api import Bring

async def get_filters():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        filters_response = await bring.get_inspiration_filters()

        print("Available inspiration filters:")
        for filter in filters_response.filters:
            special = " (special)" if filter.isSpecial else ""
            promoted = " [promoted]" if filter.isPromoted else ""
            print(f"  {filter.name}{special}{promoted}")
            print(f"    ID: {filter.id}")
            print(f"    Tags: {', '.join(filter.tags)}")
        # Output:
        # Available inspiration filters:
        #   My Recipes
        #     ID: mine
        #     Tags: mine
        #   Trending (special) [promoted]
        #     ID: bring_trending_recipes
        #     Tags: bring_trending_recipes

asyncio.run(get_filters())
```

--------------------------------

### Get Inspirations from Bring API

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves recipe suggestions and templates from Bring's inspiration stream. Use this to fetch user's own templates/recipes or trending recipes. Requires aiohttp and asyncio.

```python
import aiohttp
import asyncio
from bring_api import Bring

async def get_inspirations():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        # Get user's own templates/recipes
        my_inspirations = await bring.get_inspirations("mine")
        print(f"My inspirations: {my_inspirations.count} of {my_inspirations.total}")

        for inspiration in my_inspirations.entries[:5]:
            content = inspiration.content
            print(f"  - {content.name} ({inspiration.template_type})")

        # Get trending recipes
        trending = await bring.get_inspirations("bring_trending_recipes")
        print(f"\nTrending recipes: {trending.count}")

        for inspiration in trending.entries[:3]:
            content = inspiration.content
            print(f"  - {content.name}")
            print(f"    Author: {content.author}")
            print(f"    Likes: {inspiration.content.likeCount}")
        # Output:
        # My inspirations: 5 of 5
        #   - Weekly Breakfast (TEMPLATE)
        #   - Quick Pasta (RECIPE)
        # Trending recipes: 50
        #   - Summer Salad
        #     Author: Bring Kitchen
        #     Likes: 1234

asyncio.run(get_inspirations())
```

--------------------------------

### Get List Activity

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves the activity timeline for a shopping list, showing recent changes and actions.

```APIDOC
## Get List Activity

### Description
Retrieves the activity timeline for a shopping list, showing recent changes and actions.

### Method
GET

### Endpoint
/lists/{list_uuid}/activity

### Parameters
#### Path Parameters
- **list_uuid** (string) - Required - The unique identifier of the shopping list.

### Response
#### Success Response (200)
- **totalEvents** (integer) - The total number of events in the activity timeline.
- **timestamp** (string) - The timestamp of the last activity.
- **timeline** (array) - An array of activity events.
  - **type** (string) - The type of activity (e.g., LIST_ITEMS_ADDED).
  - **content** (object) - The content of the activity.
    - **sessionDate** (string) - The date of the session.
    - **publicUserUuid** (string) - The public UUID of the user who performed the action.
    - **items** (array) - An array of items that were changed.
      - **itemId** (string) - The ID of the item.
      - **specification** (string) - The specification of the item.

### Response Example
```json
{
  "totalEvents": 15,
  "timestamp": "2024-01-15 10:30:00",
  "timeline": [
    {
      "type": "LIST_ITEMS_ADDED",
      "content": {
        "sessionDate": "2024-01-15 10:25:00",
        "publicUserUuid": "pub-uuid-1234",
        "items": [
          {
            "itemId": "Milk",
            "specification": "2%"
          }
        ]
      }
    }
  ]
}
```
```

--------------------------------

### Get Inspiration Filters API

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves available categories and filters for browsing inspirations.

```APIDOC
## Get Inspiration Filters

### Description
Retrieves available categories and filters for browsing inspirations.

### Method
GET

### Endpoint
/inspiration-filters

### Parameters
This endpoint does not require any parameters.

### Response
#### Success Response (200)
- **filters** (array) - A list of available filter objects.
  - **name** (string) - The name of the filter (e.g., 'My Recipes', 'Trending').
  - **id** (string) - The unique identifier for the filter (e.g., 'mine', 'bring_trending_recipes').
  - **tags** (array of strings) - Associated tags for the filter.
  - **isSpecial** (boolean) - Indicates if the filter is special.
  - **isPromoted** (boolean) - Indicates if the filter is promoted.

### Request Example
```python
# This is a Python example demonstrating how to call the API
# Replace with actual API call structure if different from SDK
import aiohttp
import asyncio
from bring_api import Bring

async def get_filters_example():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()
        filters_response = await bring.get_inspiration_filters()
        print("Available inspiration filters:")
        for filter in filters_response.filters:
            print(f"  {filter.name}")

asyncio.run(get_filters_example())
```

### Response Example
```json
{
  "filters": [
    {
      "name": "My Recipes",
      "id": "mine",
      "tags": ["mine"],
      "isSpecial": false,
      "isPromoted": false
    },
    {
      "name": "Trending",
      "id": "bring_trending_recipes",
      "tags": ["bring_trending_recipes"],
      "isSpecial": true,
      "isPromoted": true
    }
  ]
}
```
```

--------------------------------

### Get Item Details

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves detailed information about items that have been customized with icons, categories, or images.

```APIDOC
## Get Item Details

### Description
Retrieves detailed information about items that have been customized with icons, categories, or images.

### Method
GET

### Endpoint
`/lists/{list_uuid}/items/details`

### Parameters
#### Path Parameters
- **list_uuid** (string) - Required - The unique identifier of the list.

### Response
#### Success Response (200)
- **items** (array) - An array of item detail objects.
  - **itemId** (string) - The ID of the item.
  - **uuid** (string) - The unique identifier of the item.
  - **userIconItemId** (string) - The ID of the custom icon, if any.
  - **userSectionId** (string) - The ID of the custom section, if any.
  - **assignedTo** (string) - The user assigned to the item, if any.
  - **imageUrl** (string) - The URL of the custom image, if any.

### Response Example
```json
{
  "items": [
    {
      "itemId": "Organic Milk",
      "uuid": "item-uuid-1234",
      "userIconItemId": "milk",
      "userSectionId": "dairy",
      "assignedTo": "user-uuid-5678",
      "imageUrl": "https://..."
    }
  ]
}
```
```

--------------------------------

### Get User Account Information with Python

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves the current user's account details, including email, verification status, name, UUIDs, locale, and premium status. Requires authentication.

```python
import aiohttp
import asyncio
from bring_api import Bring

async def get_account_info():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        account = await bring.get_user_account()

        print(f"Email: {account.email}")
        print(f"Email Verified: {account.emailVerified}")
        print(f"Name: {account.name}")
        print(f"User UUID: {account.userUuid}")
        print(f"Public UUID: {account.publicUserUuid}")
        print(f"Locale: {account.userLocale.language}-{account.userLocale.country}")
        print(f"Premium Config: {account.premiumConfiguration}")

asyncio.run(get_account_info())
```

--------------------------------

### Get User Account Information

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves the current user's account details including locale and premium status.

```APIDOC
## Get User Account Information

### Description
Retrieves the current user's account details including locale and premium status.

### Method
GET

### Endpoint
/account

### Response
#### Success Response (200)
- **email** (string) - The email address of the user.
- **emailVerified** (boolean) - Indicates if the user's email has been verified.
- **name** (string) - The name of the user.
- **userUuid** (string) - The unique user identifier.
- **publicUserUuid** (string) - The public user identifier.
- **userLocale** (object) - The user's locale settings.
  - **language** (string) - The language code.
  - **country** (string) - The country code.
- **premiumConfiguration** (object) - The user's premium subscription details.

### Response Example
```json
{
  "email": "user@example.com",
  "emailVerified": true,
  "name": "John Doe",
  "userUuid": "user-uuid-1234",
  "publicUserUuid": "pub-uuid-5678",
  "userLocale": {
    "language": "en",
    "country": "US"
  },
  "premiumConfiguration": {
    "hasPremium": false,
    "hideSponsoredProducts": false
  }
}
```
```

--------------------------------

### Load All Shopping Lists

Source: https://github.com/miaucl/bring-api/wiki/Raw-API-Requests

This GET request retrieves all shopping lists associated with a user. It requires the user's UUID and appropriate authorization headers. The response includes a list of lists, each with its UUID, name, and theme.

```http
GET https://api.getbring.com/rest/bringusers/{list_uuid}/lists HTTP/2.0
accept: application/json
x-bring-api-key: cof4Nc6D8saplXjE3h3HXqHH8m7VU2i1Gs0g85Sp
x-bring-version: 303480400
x-bring-client: android
x-bring-application: bring
x-bring-client-instance-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
x-bring-client-timezone: Europe/Berlin
user-agent: Bring!/4.58.3 (ch.publisheria.bring; versionCode:303480400; build:200; android 33) okhttp/4.9.1
x-bring-user-uuid: {user_uuid}
x-bring-user-ad-tracking-enabled: true
x-bring-user-ad-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
x-bring-country: DE
accept-language: de-DE
authorization: Bearer 
accept-encoding: gzip
content-length: 0



HTTP/2.0 200 
date: 
content-type: application/json
server: Apache/2.4.58 () OpenSSL/1.0.2k-fips
vary: Origin,Accept-Encoding
x-amzn-trace-id: Root=xxx;
etag: 
cache-control: no-transform
content-length: 468

{
  "lists": [
    {
      "listUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      "name": "Einkaufsliste",
      "theme": "ch.publisheria.bring.theme.home"
    },
    {
      "listUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      "name": "IKEA",
      "theme": "ch.publisheria.bring.theme.office"
    },
    {
      "listUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      "name": "Baumarkt",
      "theme": "ch.publisheria.bring.theme.hardware"
    }
  ]
}
```

--------------------------------

### Get List Activity with Python

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves the activity timeline for a shopping list. Requires authentication and list UUID. Displays total events, timestamp, and details of each timeline event including item changes.

```python
import aiohttp
import asyncio
from bring_api import Bring

async def get_list_activity():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        lists = await bring.load_lists()
        list_uuid = lists.lists[0].listUuid

        activity = await bring.get_activity(list_uuid)

        print(f"Total events: {activity.totalEvents}")
        print(f"Timestamp: {activity.timestamp}")

        for event in activity.timeline:
            print(f"\nActivity Type: {event.type}")
            print(f"  Session Date: {event.content.sessionDate}")
            print(f"  User: {event.content.publicUserUuid}")

            if event.content.items:
                print("  Items changed:")
                for item in event.content.items:
                    print(f"    - {item.itemId}: {item.specification}")

asyncio.run(get_list_activity())
```

--------------------------------

### Get User Account Details

Source: https://github.com/miaucl/bring-api/wiki/Raw-API-Requests

Use this endpoint to retrieve specific user account information. Ensure you include the necessary API key and user UUID in the headers.

```http
GET https://api.getbring.com/rest/v2/bringusers/{user_uuid}3 HTTP/2.0
accept: application/json
x-bring-api-key: cof4Nc6D8saplXjE3h3HXqHH8m7VU2i1Gs0g85Sp
x-bring-version: 303480402
x-bring-client: android
x-bring-application: bring
x-bring-client-instance-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
x-bring-client-timezone: Europe/Berlin
user-agent: Bring!/4.58.4 (ch.publisheria.bring; versionCode:303480402; build:201; android 33) okhttp/4.9.1
x-bring-user-uuid: {user_uuid}
x-bring-user-ad-tracking-enabled: true
x-bring-user-ad-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
x-bring-country: DE
accept-language: de-DE
authorization: Bearer
accept-encoding: gzip
content-length: 0



HTTP/2.0 200 
date: 
content-type: application/json
server: Apache/2.4.58 () OpenSSL/1.0.2k-fips
vary: Origin,Accept-Encoding
x-amzn-trace-id: Root=xxx;
etag: "xxx"
cache-control: no-transform
strict-transport-security: max-age=31536000 ; includeSubDomains
x-xss-protection: 1; mode=block
x-frame-options: DENY
x-content-type-options: nosniff
content-length: 489

{
  "userUuid": "{user_uuid}",
  "publicUserUuid": "{public_uuid}",
  "email": "{email}",
  "emailVerified": true,
  "name": "{user_name}",
  "photoPath": "bring/user/portrait/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
  "userLocale": { "language": "de", "country": "DE" },
  "premiumConfiguration": {
    "hasPremium": false,
    "hideSponsoredProducts": false,
    "hideSponsoredTemplates": false,
    "hideSponsoredPosts": false,
    "hideSponsoredCategories": false,
    "hideOffersOnMain": false
  }
}
```

--------------------------------

### Get List Users with Python

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves all members who have access to a shared shopping list. Requires authentication and list UUID. Displays user details such as name, email, country, language, and push notification status.

```python
import aiohttp
import asyncio
from bring_api import Bring

async def get_shared_list_users():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        lists = await bring.load_lists()
        list_uuid = lists.lists[0].listUuid

        users_response = await bring.get_list_users(list_uuid)

        print("List members:")
        for user in users_response.users:
            print(f"  Name: {user.name or 'Unknown'}")
            print(f"  Email: {user.email or 'Hidden'}")
            print(f"  Country: {user.country}")
            print(f"  Language: {user.language}")
            print(f"  Push Enabled: {user.pushEnabled}")
            print()

asyncio.run(get_shared_list_users())
```

--------------------------------

### GET /rest/bringlists/{list_uuid}/invitations

Source: https://github.com/miaucl/bring-api/wiki/Raw-API-Requests

Retrieves a list of pending or accepted invitations for a specific Bring! list. This endpoint is useful for displaying the invitation status associated with a particular shopping list.

```APIDOC
## GET /rest/bringlists/{list_uuid}/invitations

### Description
Retrieves a list of pending or accepted invitations for a specific Bring! list.

### Method
GET

### Endpoint
https://api.getbring.com/rest/bringlists/{list_uuid}/invitations

### Parameters
#### Path Parameters
- **list_uuid** (string) - Required - The unique identifier for the Bring! list.

#### Headers
- **x-bring-api-key** (string) - Required - API key for authentication.
- **x-bring-version** (string) - Required - The version of the Bring! API.
- **x-bring-client** (string) - Required - The client application type (e.g., 'android').
- **x-bring-application** (string) - Required - The name of the application (e.g., 'bring').
- **x-bring-client-instance-id** (string) - Required - Unique identifier for the client instance.
- **x-bring-client-timezone** (string) - Required - The client's timezone (e.g., 'Europe/Berlin').
- **user-agent** (string) - Required - User-agent string of the client.
- **x-bring-user-ad-tracking-enabled** (boolean) - Required - Indicates if ad tracking is enabled for the user.
- **x-bring-user-ad-id** (string) - Required - The user's advertising identifier.
- **x-bring-user-uuid** (string) - Required - The unique identifier for the user.
- **x-bring-country** (string) - Required - The user's country code (e.g., 'DE').
- **accept-language** (string) - Required - Preferred language for the response (e.g., 'de-DE').
- **authorization** (string) - Required - Bearer token for authentication.
- **accept-encoding** (string) - Required - Encoding type accepted for the response (e.g., 'gzip').

### Response
#### Success Response (200)
- **invitations** (array) - A list of invitation objects.
  - **bringListUuid** (string) - The UUID of the Bring! list.
  - **fromEmail** (string) - The email address of the sender.
  - **listName** (string) - The name of the list.
  - **listTheme** (string) - The theme of the list.
  - **state** (string) - The current state of the invitation ('PENDING' or 'ACCEPTED').
  - **toEmail** (string) - The email address of the recipient.
  - **uuid** (string) - The unique identifier for the invitation.

#### Response Example
```json
{
    "invitations": [
        {
            "bringListUuid": "{list_uuid}",
            "fromEmail": "{sender_mail}",
            "listName": "{list_name}",
            "listTheme": "ch.publisheria.bring.theme.home",
            "state": "PENDING",
            "toEmail": "{recipient_mail}",
            "uuid": "{invitation_uuid}"
        },
        {
            "bringListUuid": "{list_uuid}",
            "fromEmail": "{sender_mail}",
            "listName": "{list_name}",
            "listTheme": "ch.publisheria.bring.theme.office",
            "state": "ACCEPTED",
            "toEmail": "{recipient_mail}",
            "uuid": "{invitation_uuid}"
        }
    ]
}
```
```

--------------------------------

### Create Template or Recipe with Python

Source: https://context7.com/miaucl/bring-api/llms.txt

Saves a new template or recipe to your Bring account. Supports creating both general templates and specific recipes with details like author and cooking time. Requires aiohttp.

```python
import aiohttp
import asyncio
from bring_api import Bring, BringTemplate, TemplateType
from bring_api.types import Ingredient

async def create_recipe_template():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        # Create a custom template
        template = BringTemplate(
            name="Weekly Breakfast",
            tagline="Quick and healthy breakfast items",
            items=[
                Ingredient(itemId="Eggs", spec="1 dozen", stock=False),
                Ingredient(itemId="Bread", spec="whole wheat", stock=False),
                Ingredient(itemId="Butter", spec="unsalted", stock=True),
                Ingredient(itemId="Orange Juice", spec="1 liter", stock=False),
            ]
        )

        created = await bring.create_template(template, TemplateType.TEMPLATE)
        print(f"Created template: {created.name}")
        print(f"Template UUID: {created.uuid}")

        # Create a recipe
        recipe = BringTemplate(
            name="Quick Pasta",
            author="Home Chef",
            requestQuantity="2 servings",
            time="20 min",
            linkOutUrl="https://myrecipes.com/quick-pasta",
            items=[
                Ingredient(itemId="Pasta", spec="200g", stock=False),
                Ingredient(itemId="Olive Oil", spec="2 tbsp", stock=True),
                Ingredient(itemId="Garlic", spec="3 cloves", stock=False),
            ]
        )

        created_recipe = await bring.create_template(recipe, TemplateType.RECIPE)
        print(f"Created recipe: {created_recipe.name}")
        print(f"Recipe UUID: {created_recipe.uuid}")

asyncio.run(create_recipe_template())
```

--------------------------------

### Get List Users

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves all members who have access to a shared shopping list.

```APIDOC
## Get List Users

### Description
Retrieves all members who have access to a shared shopping list.

### Method
GET

### Endpoint
/lists/{list_uuid}/users

### Parameters
#### Path Parameters
- **list_uuid** (string) - Required - The unique identifier of the shopping list.

### Response
#### Success Response (200)
- **users** (array) - An array of users who are members of the list.
  - **name** (string) - The name of the user.
  - **email** (string) - The email address of the user.
  - **country** (string) - The country of the user.
  - **language** (string) - The language preference of the user.
  - **pushEnabled** (boolean) - Indicates if push notifications are enabled for the user.

### Response Example
```json
{
  "users": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "country": "US",
      "language": "en",
      "pushEnabled": true
    }
  ]
}
```
```

--------------------------------

### User Signup API

Source: https://github.com/miaucl/bring-api/wiki/Raw-API-Requests

Allows for the creation of a new Bring! account.

```APIDOC
## POST /api/v2/bringauth/signup

### Description
Create a Bring account.

### Method
POST

### Endpoint
https://api.getbring.com/rest/v2/bringauth/signup

### Parameters
#### Request Body
- **email** (string) - Required - The email address for the new account.

### Request Example
```json
{
  "email": "{user_mail}"
}
```

### Response
#### Success Response (201)
- **uuid** (string) - The unique identifier for the user.
- **publicUuid** (string) - A public-facing identifier for the user.
- **email** (string) - The email address of the user.
- **access_token** (string) - The authentication token for accessing protected resources.
- **refresh_token** (string) - The token used to obtain a new access token.
- **token_type** (string) - The type of token, typically 'Bearer'.
- **expires_in** (integer) - The time in seconds until the access token expires.

#### Response Example
```json
{
  "uuid": "{user_uuid}",
  "publicUuid": "{public_uuid}",
  "email": "{user_mail}",
  "access_token": "xxxxxxxxxxxxxxxx",
  "refresh_token": "xxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 604799
}
```
```

--------------------------------

### Authentication and Login

Source: https://context7.com/miaucl/bring-api/llms.txt

Authenticates with Bring! using email and password credentials to establish a session for subsequent API calls. It also loads user settings, locale preferences, and article translations.

```APIDOC
## Authentication and Login

### Description
Authenticates with Bring! using email and password credentials, returning user information and establishing the session for subsequent API calls. It automatically loads user settings, locale preferences, and article translations.

### Method
POST (Implicit, as `login()` is called)

### Endpoint
Not explicitly defined, handled by the `bring_api.Bring.login()` method.

### Parameters
#### Request Body (Implicit within `Bring` object initialization)
- **session** (aiohttp.ClientSession) - Required - The aiohttp client session.
- **email** (str) - Required - The user's email address.
- **password** (str) - Required - The user's password.

### Request Example
```python
import aiohttp
import asyncio
from bring_api import Bring, BringAuthException, BringRequestException

async def authenticate():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "your_password")
        try:
            auth_response = await bring.login()
            print(f"Logged in as: {auth_response.name}")
            print(f"User UUID: {auth_response.uuid}")
            print(f"Public UUID: {auth_response.publicUuid}")
            print(f"Token expires in: {auth_response.expires_in} seconds")
        except BringAuthException as e:
            print(f"Authentication failed: {e}")
        except BringRequestException as e:
            print(f"Request failed: {e}")

asyncio.run(authenticate())
```

### Response
#### Success Response (200)
- **name** (str) - The name of the authenticated user.
- **uuid** (str) - The unique identifier for the user.
- **publicUuid** (str) - The public unique identifier for the user.
- **expires_in** (int) - The time in seconds until the authentication token expires.

#### Response Example
```json
{
  "name": "John Doe",
  "uuid": "abc12345-1234-5678-9abc-def012345678",
  "publicUuid": "pub12345-1234-5678-9abc-def012345678",
  "expires_in": 604800
}
```
```

--------------------------------

### Get Users of a Shared List

Source: https://github.com/miaucl/bring-api/wiki/Raw-API-Requests

Retrieves a list of all users associated with a specific shared Bring! list.

```APIDOC
## GET /rest/v2/bringlists/{list_uuid}/users

### Description
Get Details of all users of a shared list.

### Method
GET

### Endpoint
https://api.getbring.com/rest/v2/bringlists/{list_uuid}/users

### Parameters
#### Path Parameters
- **list_uuid** (string) - Required - The unique identifier of the bring list.

#### Request Headers
- **accept**: application/json
- **x-bring-api-key**: string - Your Bring! API key.
- **x-bring-version**: string - The API version.
- **x-bring-client**: string - The client type (e.g., 'android').
- **x-bring-application**: string - The application name (e.g., 'bring').
- **x-bring-client-instance-id**: string - Unique ID for the client instance.
- **x-bring-client-timezone**: string - The client's timezone (e.g., 'Europe/Berlin').
- **user-agent**: string - User agent string.
- **x-bring-user-uuid**: string - The unique identifier of the user.
- **x-bring-user-ad-tracking-enabled**: boolean - Whether ad tracking is enabled.
- **x-bring-user-ad-id**: string - The user's ad ID.
- **x-bring-country**: string - The user's country code (e.g., 'DE').
- **accept-language**: string - Preferred language for the response (e.g., 'de-DE').
- **authorization**: Bearer
- **accept-encoding**: gzip

### Response
#### Success Response (200)
- **users** (array) - An array of user objects.
  - **publicUuid** (string) - The public unique identifier of the user.
  - **name** (string) - The name of the user.
  - **email** (string) - The email address of the user.
  - **photoPath** (string) - Path to the user's photo.
  - **pushEnabled** (boolean) - Indicates if push notifications are enabled for the user.
  - **plusTryOut** (boolean) - Indicates if the user is in a trial for plus features.
  - **country** (string) - The user's country code.
  - **language** (string) - The user's language code.

#### Response Example
```json
{
  "users": [
    {
      "publicUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      "name": "xxxx",
      "email": "xxxx",
      "photoPath": "bring/user/portrait/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
      "pushEnabled": true,
      "plusTryOut": false,
      "country": "DE",
      "language": "de"
    }
  ]
}
```
```

--------------------------------

### Get List Items

Source: https://context7.com/miaucl/bring-api/llms.txt

Retrieves all items from a specific shopping list, including items to purchase and recently completed items.

```APIDOC
## Get List Items

### Description
Retrieves all items from a specific shopping list, including items to purchase and recently completed items.

### Method
GET (Implicit, as `get_list()` is called)

### Endpoint
Not explicitly defined, handled by the `bring_api.Bring.get_list(list_uuid)` method.

### Parameters
#### Path Parameters
- **list_uuid** (str) - Required - The unique identifier of the shopping list.

### Request Example
```python
import aiohttp
import asyncio
from bring_api import Bring

async def get_list_items():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        lists = await bring.load_lists()
        if not lists.lists:
            print("No lists found.")
            return
        list_uuid = lists.lists[0].listUuid

        items_response = await bring.get_list(list_uuid)

        print(f"List Status: {items_response.status}")
        print("\nItems to purchase:")
        for item in items_response.items.purchase:
            print(f"  - {item.itemId}: {item.specification or 'no spec'} (uuid: {item.uuid})")

        print("\nRecently completed:")
        for item in items_response.items.recently:
            print(f"  - {item.itemId}: {item.specification or 'no spec'})

asyncio.run(get_list_items())
```

### Response
#### Success Response (200)
- **status** (str) - The status of the list (e.g., "REGISTERED").
- **items** (object) - An object containing different categories of items.
  - **purchase** (list) - A list of items that need to be purchased.
    - **itemId** (str) - The ID of the item.
    - **specification** (str) - Additional details about the item.
    - **uuid** (str) - The unique identifier for the item.
  - **recently** (list) - A list of recently completed items.
    - **itemId** (str) - The ID of the item.
    - **specification** (str) - Additional details about the item.

#### Response Example
```json
{
  "status": "REGISTERED",
  "items": {
    "purchase": [
      {
        "itemId": "Milk",
        "specification": "low fat",
        "uuid": "item-uuid-1234"
      },
      {
        "itemId": "Bread",
        "specification": "whole wheat",
        "uuid": "item-uuid-5678"
      }
    ],
    "recently": [
      {
        "itemId": "Eggs",
        "specification": "organic",
        "uuid": "item-uuid-9abc"
      }
    ]
  }
}
```
```

--------------------------------

### Parse Recipe from URL with Python

Source: https://context7.com/miaucl/bring-api/llms.txt

Use this method to extract recipe ingredients from a URL and convert them into a Bring template format. Requires aiohttp for asynchronous HTTP requests.

```python
import aiohttp
import asyncio
from bring_api import Bring

async def parse_recipe():
    async with aiohttp.ClientSession() as session:
        bring = Bring(session, "user@example.com", "password")
        await bring.login()

        recipe_url = "https://www.example-recipe-site.com/recipes/pasta-bolognese"

        template = await bring.parse_recipe(recipe_url)

        print(f"Recipe: {template.name}")
        print(f"Author: {template.author}")
        print(f"Servings: {template.requestQuantity}")
        print(f"Time: {template.time}")
        print("\nIngredients:")
        for ingredient in template.items:
            spec = f" ({ingredient.spec})" if ingredient.spec else ""
            print(f"  - {ingredient.itemId}{spec}")
        # Output:
        # Recipe: Pasta Bolognese
        # Author: Chef John
        # Servings: 4
        # Time: 45 min
        # Ingredients:
        #   - Ground Beef (500g)
        #   - Tomatoes (canned, 400g)
        #   - Pasta (spaghetti)

asyncio.run(parse_recipe())
```

--------------------------------

### Get User Profile Picture

Source: https://github.com/miaucl/bring-api/wiki/Raw-API-Requests

Retrieves the URL for a user's profile picture using their public UUID. This endpoint does not require authentication.

```APIDOC
## GET /v2/bringusers/profilepictures/{public_uuid}

### Description
Fetches the URL of a user's profile picture. This endpoint is publicly accessible and does not require authentication.

### Method
GET

### Endpoint
https://api.getbring.com/rest/v2/bringusers/profilepictures/{public_uuid}

### Parameters
#### Path Parameters
- **public_uuid** (string) - Required - The public unique identifier of the user whose profile picture URL is requested.

### Response
#### Success Response (200)
- **URL** (string) - The URL of the user's profile picture.

#### Response Example
(Example response body not provided in source text)
```