smartbill-rest-sdk 1.0.0__tar.gz

smartbill_rest_sdk-1.0.0/.gitignore

@@ -0,0 +1,289 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python,jetbrains
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,jetbrains
+
+### JetBrains ###
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### JetBrains Patch ###
+# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
+
+# *.iml
+# modules.xml
+# .idea/misc.xml
+# *.ipr
+
+# Sonarlint plugin
+# https://plugins.jetbrains.com/plugin/7973-sonarlint
+.idea/**/sonarlint/
+
+# SonarQube Plugin
+# https://plugins.jetbrains.com/plugin/7238-sonarqube-community-plugin
+.idea/**/sonarIssues.xml
+
+# Markdown Navigator plugin
+# https://plugins.jetbrains.com/plugin/7896-markdown-navigator-enhanced
+.idea/**/markdown-navigator.xml
+.idea/**/markdown-navigator-enh.xml
+.idea/**/markdown-navigator/
+
+# Cache file creation bug
+# See https://youtrack.jetbrains.com/issue/JBR-2257
+.idea/$CACHE_FILE$
+
+# CodeStream plugin
+# https://plugins.jetbrains.com/plugin/12206-codestream
+.idea/codestream.xml
+
+# Azure Toolkit for IntelliJ plugin
+# https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij
+.idea/**/azureSettings.xml
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+# End of https://www.toptal.com/developers/gitignore/api/python,jetbrains

smartbill_rest_sdk-1.0.0/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

smartbill_rest_sdk-1.0.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

smartbill_rest_sdk-1.0.0/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv (smartbill-sdk)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="uv (smartbill-sdk)" project-jdk-type="Python SDK" />
+</project>

smartbill_rest_sdk-1.0.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/smartbill-sdk.iml" filepath="$PROJECT_DIR$/.idea/smartbill-sdk.iml" />
+    </modules>
+  </component>
+</project>

smartbill_rest_sdk-1.0.0/.idea/smartbill-sdk.iml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="uv (smartbill-sdk)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

smartbill_rest_sdk-1.0.0/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

smartbill_rest_sdk-1.0.0/AGENTS.md

@@ -0,0 +1,99 @@
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** 2026-06-21
+
+## OVERVIEW
+Project: **smartbill-sdk**
+Stack: Python ≥ 3.11, `httpx>=0.27`, `pydantic>=2.6`; build backend `hatchling`; dependency/
+dev env managed with `uv`; tests with `pytest` + `pytest-asyncio` + `respx`.
+
+A Python SDK for the [SmartBill Cloud REST API](https://www.facturionline.ro/api-program-facturare/)
+offering both **synchronous** (`SmartBillClient`) and **asynchronous**
+(`AsyncSmartBillClient`) interfaces, with typed pydantic v2 request/response
+models covering every endpoint in the official `docs/openapi.json` spec.
+
+## STRUCTURE
+```
+src/smartbill_sdk/      # the package (src-layout)
+  __init__.py           # public API + __all__ re-exports
+  client.py             # SmartBillClient (sync)
+  async_client.py       # AsyncSmartBillClient (async)
+  _transport.py         # shared request build / auth / envelope unwrap / errors / RateLimiter
+  exceptions.py         # SmartBillError hierarchy
+  models/               # pydantic v2 models per resource (alias camelCase <-> snake_case)
+  services/             # per-resource endpoint logic, shared by sync + async clients
+tests/                  # pytest suite, mocked via respx (63 tests)
+examples/               # standalone runnable example scripts
+docs/openapi.json       # official SmartBill OpenAPI spec (source of truth)
+pyproject.toml          # project + hatch build + pytest config
+uv.lock                 # lockfile
+```
+*   `src/smartbill_sdk/services/__init__.py`: All endpoint logic. Each service builds
+    `httpx.Request` objects and defines both sync (`create`, `delete`, ...) and async
+    (`acreate`, `adelete`, ...) methods that delegate to an injected `_Executor`
+    (`execute` / `aexecute`). Defined once, used by both clients.
+*   `src/smartbill_sdk/_transport.py`: Auth (HTTP Basic `username:token`), request
+    construction, SmartBill response-envelope unwrapping, error mapping, and the
+    optional client-side `RateLimiter` (SmartBill enforces 30 calls / 10s, then 403
+    for 10 minutes).
+*   `src/smartbill_sdk/models/`: snake_case attrs aliased to camelCase JSON; models
+    are permissive (`extra="allow"`) so new API fields don't break parsing.
+
+## COMMANDS
+| Action              | Command                          |
+|---------------------|----------------------------------|
+| Install (dev)       | `uv sync --extra dev`            |
+| Run tests           | `uv run pytest` (or `uv run pytest -q`) |
+| Run a single test   | `uv run pytest tests/test_invoices.py` |
+| Build wheel         | `uv build`                       |
+| Run an example      | `uv run python examples/create_invoice_sync.py` |
+
+Note: `pytest-asyncio` runs in `asyncio_mode = "auto"` (see `pyproject.toml`), so
+async test functions need no `@pytest.mark.asyncio` decorator.
+
+## CODING STANDARDS
+*   **Language**: Python 3.11+ (`from __future__ import annotations` is used throughout).
+*   **Style**: 4-space indent, double-quote strings, module-level docstrings, full
+    type hints, `Optional[...]` over `| None`. No formatter/linter is currently
+    configured (no ruff/black/mypy in `pyproject.toml`) — match the existing style.
+*   **Models**: pydantic v2, subclass the `ModelConfig` base in `models/common.py`
+    (`populate_by_name=True`, `extra="allow"`). Use `Field(..., alias="camelCase")`
+    and `AliasChoices` for snake_case ⇄ camelCase mapping. Serialize with
+    `model_dump(by_alias=True, exclude_none=True)`.
+*   **Services**: keep sync + async methods paired in the same service class; sync
+    method `foo` → async `afoo`. Build the `httpx.Request` once in a private
+    `_foo_request(...)` helper, then both `foo` and `afoo` reuse it.
+*   **Errors**: raise `SmartBillError` subclasses from `exceptions.py`; never bare
+    `Exception`. `handle_response()` in `_transport.py` is the single place that
+    maps HTTP status / envelopes to exceptions.
+*   **Responses**: the SmartBill API wraps payloads in envelopes (`sbcResponse`,
+    `Response`, `sbcTaxes`, `sbcSeries`, `sbcInvoicePaymentStatusResponse`,
+    `stocks`, `Fault`). `parse_envelope()` unwraps them — don't unwrap manually.
+
+## WHERE TO LOOK
+*   **Source**: `src/smartbill_sdk/`
+*   **Tests**: `tests/` (mocked HTTP via `respx`; `tests/conftest.py` has shared
+    fixtures/helpers like `make_sync_client`, `make_async_client`, `envelope()`)
+*   **Docs**: `README.md`, `docs/openapi.json` (official spec), `examples/`
+*   **Public API surface**: `src/smartbill_sdk/__init__.py` (`__all__`)
+
+## NOTES
+*   **Auth**: SmartBill uses HTTP Basic Auth with `username:token` where `username`
+    is the login e-mail and `token` comes from SmartBill Cloud → *Contul Meu →
+    Integrari → API*.
+*   **JSON only**: the SDK sends JSON (`format="json"`); XML is not supported.
+*   **Rate limit**: 30 calls / 10 seconds — exceeding it triggers a server-side 403
+    that blocks access for 10 minutes. Opt into a client-side preemptive limiter with
+    `SmartBillClient(..., enforce_rate_limit=True)`.
+*   **Dates**: all date fields are `YYYY-MM-DD` strings, matching the API.
+*   **Sync vs async**: `SmartBillClient` exposes sync service methods (`client.invoices.create`)
+    and `AsyncSmartBillClient` exposes async ones (`await client.invoices.acreate`).
+    Calling the wrong one raises a clear `SmartBillError`.
+*   **`taxes` / `series` alias**: on both clients, `client.taxes` and `client.series`
+    are the *same* `ConfigurationService` instance (taxes + series share one service).
+*   **Tests are mocked**: no network calls; `respx` intercepts `httpx`. The full suite
+    (63 tests) passes offline.
+*   **Disclaimer (from README)**: the SDK was AI-generated from `openapi.json` and
+    verified with 63 mocked tests — please have a human review before issuing real
+    invoices.
+*   No other context files (`.cursorrules`, `CLAUDE.md`, etc.) were found in the repo.

smartbill_rest_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] — 2026-06-21
+
+First stable release of the Python SDK for the SmartBill Cloud REST API.
+
+### Added
+- Synchronous `SmartBillClient` and asynchronous `AsyncSmartBillClient` with
+  HTTP Basic (`username:token`) authentication.
+- Typed pydantic v2 request/response models for every endpoint in the official
+  `docs/openapi.json` spec, using snake_case attributes aliased to the
+  camelCase JSON field names.
+- Per-resource services covering invoices, proformas (estimates), payments
+  (incl. `chitanta` and `bon fiscal`), e-mail, taxes, series and stocks.
+- Exception hierarchy (`SmartBillError`, `SmartBillAuthError`,
+  `SmartBillRateLimitError`, `SmartBillAPIError`, `SmartBillTransportError`)
+  that surfaces the API `errorText`.
+- SmartBill response-envelope unwrapping (`sbcResponse`, `Response`,
+  `sbcTaxes`, `sbcSeries`, `sbcInvoicePaymentStatusResponse`, `stocks`,
+  `Fault`) centralized in `_transport.parse_envelope`.
+- Optional client-side `RateLimiter` (`enforce_rate_limit=True`) to preempt
+  the server's 403 (SmartBill blocks access for 10 minutes after >30 calls
+  in 10 seconds).
+- Binary PDF retrieval for invoices, proformas and fiscal receipts.
+- Draft (ciornă) support via `is_draft=True` on `Invoice`, `Estimate` and
+  `Payment`.
+- Runnable example scripts under `examples/` and copy-pasteable pi agent
+  skills under `skills/` (`smartbill-invoices`, `smartbill-payments`,
+  `smartbill-email`).
+- Test suite of 63 mocked tests using `respx` (no network calls).
+
+### Fixed
+- **Critical:** request bodies were incorrectly wrapped in XML-style
+  envelopes (`{"invoice": {...}}`, `{"estimate": {...}}`, `{"payment": {...}}`,
+  `{"sendDocumentRequest": {...}}`). The JSON endpoints reject these with
+  `400 Unrecognized property: <envelope>.` Envelope wrapping has been removed
+  from all POST request builders in `services/__init__.py`; the request body
+  is now the bare model. Verified against the live SmartBill API by emitting
+  a draft invoice.
+- `InvoiceRef.series_name` now accepts both `seriesName` (requests) and
+  `series` (the `GET /estimate/invoices` response) via `AliasChoices`, while
+  still serializing as `seriesName`.
+- `PaymentsService.create` / `acreate` now return `FiscalReceiptResponse`
+  (exposes the generated receipt `id`) instead of `BaseResponse`.
+- README quick-start example used the non-existent `client.taxes.list(...)`;
+  corrected to `client.taxes.ataxes(...)`.
+
+### Notes
+- The SDK sends JSON only (`format="json"`); XML is not supported.
+- Date fields use `YYYY-MM-DD` strings, matching the API.
+- This SDK was AI-generated from the official `openapi.json` spec and
+  verified with a suite of mocked tests, then refined against live API
+  calls. Please have a human review before issuing real invoices.

smartbill_rest_sdk-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

smartbill_rest_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: smartbill-rest-sdk
+Version: 1.0.0
+Summary: Python SDK (sync + async) for the SmartBill Cloud REST API.
+Author: smartbill-sdk contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# smartbill-sdk
+
+A Python SDK for the [SmartBill Cloud REST API](https://www.facturionline.ro/api-program-facturare/),
+offering both **synchronous** and **asynchronous** interfaces and typed
+request/response models generated from the official `openapi.json` spec.
+
+## Features
+
+- Sync (`SmartBillClient`) and async (`AsyncSmartBillClient`) clients.
+- Typed pydantic v2 models for invoices, proformas, payments, emails,
+  taxes, series and stocks.
+- Covers every endpoint from the SmartBill OpenAPI definition.
+- Helper exceptions with the API `errorText` surfaced.
+
+## Installation
+
+```bash
+pip install smartbill-sdk
+```
+
+From source (development):
+
+```bash
+uv sync --extra dev
+```
+
+## Authentication
+
+SmartBill uses HTTP Basic Auth with `username:token`:
+
+- `username` — the e-mail you log in with in SmartBill Cloud.
+- `token` — found in SmartBill Cloud > **Contul Meu** > **Integrari** > **API**.
+
+```python
+from smartbill_sdk import SmartBillClient
+
+client = SmartBillClient(username="you@example.com", token="abc123...")
+```
+
+## Quick start (sync)
+
+```python
+from smartbill_sdk import SmartBillClient
+from smartbill_sdk.models import Invoice, Client, Product
+
+client = SmartBillClient(username="you@example.com", token="...")
+
+invoice = Invoice(
+    company_vat_code="RO12345678",
+    client=Client(name="Intelligent IT", vat_code="RO12345678", city="Sibiu", country="Romania"),
+    series_name="FCT",
+    is_draft=False,
+    products=[
+        Product(name="Produs 1", measuring_unit_name="buc", currency="RON",
+                quantity=2, price=10, is_tax_included=True,
+                tax_name="Redusa", tax_percentage=9),
+    ],
+)
+
+resp = client.invoices.create(invoice)
+print(resp.series, resp.number)
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from smartbill_sdk import AsyncSmartBillClient
+
+async def main():
+    client = AsyncSmartBillClient(username="you@example.com", token="...")
+    taxes = await client.taxes.ataxes("RO12345678")
+    print(taxes)
+    await client.aclose()
+
+asyncio.run(main())
+```
+
+## Endpoints covered
+
+Invoices, Proformas, Payments (incl. chitanta & bon fiscal), E-mail,
+Taxes, Series, Stocks. See `smartbill_sdk/services/` for the full list.
+
+## Agent skills
+
+This repo ships ready-to-import [pi](https://github.com/earendil-works/pi-coding-agent)
+**skills** under [`skills/`](skills/) that teach coding agents how to use the
+SDK. Each `SKILL.md` is a self-contained, copy-pasteable guide for one area of
+the API:
+
+| Skill                | Covers                                                                  |
+|----------------------|-------------------------------------------------------------------------|
+| `smartbill-invoices` | Invoices & proformas/estimates: create, storno, cancel, restore, PDF, payment status |
+| `smartbill-payments` | Payments & fiscal receipts (`bon fiscal`): `POST /payment`, payment types, mixed cash/card, fiscal-printer text, delete |
+| `smartbill-email`    | Emailing a document (`POST /document/send`): base64 subject/body, invoice/proforma |
+
+See [`skills/README.md`](skills/README.md) for how to import them into a pi
+agent. The runnable scripts in [`examples/`](examples/) accompany these skills.
+
+## Notes
+
+- The SDK talks JSON by default (`format="json"`); XML is not yet supported.
+- Rate limit: the SmartBill API allows 30 calls / 10 seconds. A client-side
+  limiter can be enabled with `enforce_rate_limit=True`.
+- Date fields use `YYYY-MM-DD` strings, matching the API.
+
+See [`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+## Disclaimer
+
+This SDK was written by an AI agent (pi) which, to its credit.
+The code was generated from the official
+`openapi.json` spec, verified with a suite of 63 mocked tests, and refined
+until everything passed.
+
+That said, please have a human review it before issuing real invoices —
+accountants work hard enough as it is, and the last thing they need is an
+enthusiastic model quietly deciding that the 9% reduced rate applies to
+shampoo.