Metadata-Version: 2.4
Name: loyverse-sdk
Version: 0.4.3
Summary: Asynchronous Python SDK for the Loyverse API
Project-URL: Homepage, https://github.com/dagsdags212/loyverse_sdk
Project-URL: Repository, https://github.com/dagsdags212/loyverse_sdk
Project-URL: Issues, https://github.com/dagsdags212/loyverse_sdk/issues
Author-email: dagsdags212 <jegsamson.dev@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,async,loyverse,pos,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: duckdb>=1.1.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: polars>=1.0.0
Requires-Dist: pyarrow>=15.0.0
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: pydantic>=2.12.4
Requires-Dist: pytz>=2025.2
Requires-Dist: rich>=14.2.0
Requires-Dist: typer>=0.15.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Loyverse SDK

Asynchronous Python SDK, CLI, and MCP server for the
[Loyverse API](https://developer.loyverse.com/docs/) — a point-of-sale (POS)
platform for managing sales, inventory, and customers.

## Features

- **Async/await** client built on `httpx` for non-blocking API calls
- **Type-safe** request/response models powered by Pydantic
- **Automatic pagination** with cursor-based `iter_all()` iteration
- **Full CRUD** across 16 endpoints
- **`loyverse` CLI** — list, create, update, delete, export, and analyze from the terminal
- **`loyverse-mcp` server** — 18 read-only tools exposing your POS data to LLM clients (Claude Desktop, etc.)
- **DuckDB export** — a local relational warehouse for SQL analytics
- **Flat-file export** — write any query straight to CSV or Parquet
- **Analytics engine** — revenue, products, customers, profitability, inventory, and more

## Install

```bash
uv add loyverse_sdk          # core SDK
uv add "loyverse_sdk[mcp]"   # with the MCP server
```

See [Installation](docs/Installation.md) for pip, GitHub, and extras.

## Quickstart

```python
import asyncio
from loyverse_sdk import LoyverseClient

async def main():
    client = LoyverseClient()                 # reads your token from ~/.loyverse
    response = await client.customers.list()
    print(f"Found {len(response.items)} customers")
    await client.close()

asyncio.run(main())
```

Run `loyverse init` once to store your API token. See
[Configuration](docs/Configuration.md) and [Quickstart](docs/Quickstart.md) to
get going.

## Documentation

Full documentation lives in the [**`docs/`** wiki](docs/Home.md) — start at
[Home](docs/Home.md). Highlights:

- **Getting started:** [Installation](docs/Installation.md) · [Configuration](docs/Configuration.md) · [Quickstart](docs/Quickstart.md)
- **Python SDK:** [Client](docs/Client.md) · [Endpoints](docs/Endpoints.md) · [Query Models](docs/Query-Models.md) · [Models](docs/Models.md) · [Helpers](docs/Helpers.md) · [Error Handling](docs/Error-Handling.md)
- **Export & analytics:** [DuckDB Export](docs/DuckDB-Export.md) · [Flat-File Export](docs/Flat-File-Export.md) · [Analytics](docs/Analytics.md)
- **Tools:** [CLI](docs/CLI.md) · [MCP Server](docs/MCP-Server.md)
- **Project:** [Development](docs/Development.md)

> The pages under `docs/` use `[[wikilink]]` syntax so they render as a connected
> [GitHub Wiki](https://docs.github.com/en/communities/documenting-your-project-with-wikis).
> When browsing them in the repo, use the relative links above.

## License

MIT — see [LICENSE](LICENSE).
