pennylane-sdk 0.1.0__tar.gz

pennylane_sdk-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary

pennylane_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - name: Ruff
+        run: uv run ruff check src tests scripts
+      - name: Mypy (strict)
+        run: uv run mypy --strict src
+
+  coverage-audit:
+    name: API coverage audit (213 operations)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Every spec operation implemented (sync + async)
+        run: uv run python scripts/check_coverage.py
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --frozen
+      - name: Tests
+        run: uv run pytest -q
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - name: Build docs (strict)
+        run: uv run mkdocs build --strict
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

pennylane_sdk-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - name: Build site
+        run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

pennylane_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - name: Run tests
+        run: uv run pytest -q
+      - name: Coverage audit
+        run: uv run python scripts/check_coverage.py
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pennylane-sdk/
+    permissions:
+      id-token: write  # OIDC trusted publishing — no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pennylane_sdk-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Docs build
+site/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Local secrets (never commit API tokens)
+.env
+.env.*
+
+# Local tooling configuration
+.claude/

pennylane_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-08
+
+Initial release.
+
+### Added
+
+- Full coverage of the Pennylane **Company API v2**: 165 operations across 24 resource modules (customer and supplier invoicing, quotes, customers, products, billing subscriptions, banking, ledger, lettering, trial balance, analytics, FEC/GL/AGL exports, SEPA/GoCardless/Pro Account mandates, e-invoicing, changelogs, webhook subscriptions).
+- Full coverage of the Pennylane **Firm API v1**: 48 operations (companies portfolio, accounting, DMS, exports, invoicing, banking, categories, changelogs).
+- Sync (`Pennylane`, `PennylaneFirm`) and async (`AsyncPennylane`, `AsyncPennylaneFirm`) clients with identical surfaces.
+- Typed Pydantic response models; monetary values as `Decimal` serialized to API-compliant strings.
+- Auto-paginating cursor and page-number pages, re-sending filters across pages.
+- Client-side throttling to the official rate limits, on by default.
+- Conservative retry policy safe for a non-idempotent accounting API (POST never retried on 5xx).
+- Defensive error parsing with a full exception hierarchy.
+- Typed filter builders (`pennylane_sdk.filters`).
+- OAuth 2.0 helpers with serialized refresh (Refresh Token Rotation safe).
+- Webhook signature verification (constant-time HMAC) and payload parsing.
+- Coverage audit script validating the SDK against the vendored official OpenAPI specs.

pennylane_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for helping make pennylane-sdk better! Contributions of every size are welcome: bug reports, docs fixes, new endpoint coverage, ideas.
+
+## Development setup
+
+Requirements: Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/GoatAndCow7/pennylane-sdk
+cd pennylane-sdk
+uv sync
+```
+
+Run the checks the CI runs:
+
+```bash
+uv run pytest                              # tests (all mocked, no token needed)
+uv run mypy --strict src                   # type checking
+uv run ruff check src tests scripts       # lint
+uv run python scripts/check_coverage.py    # every API operation implemented?
+uv run mkdocs serve                        # docs live preview
+```
+
+## Project layout
+
+```
+specs/                     vendored official OpenAPI specs (source of truth)
+scripts/update_specs.py    refresh the specs from pennylane.readme.io
+scripts/check_coverage.py  audits that every spec operation exists in sync + async
+scripts/show_endpoint.py   inspect one endpoint's schema from the specs
+src/pennylane_sdk/
+  _base_client.py          HTTP engine: auth, retries, throttle, errors
+  _pagination.py           cursor and page-number auto-paginating pages
+  resources/company|firm/  one module per URL namespace, sync + Async classes
+  types/company|firm/      Pydantic response models
+tests/                     mirrors resources/, respx-mocked
+docs/                      mkdocs-material site
+```
+
+## Adding or fixing an endpoint
+
+1. Find the operation in the spec: `uv run python scripts/show_endpoint.py company "customer_invoices/{id}/finalize" put`
+2. Follow the conventions in `docs/design/resource-map.md` (method naming, models, docstrings). `src/pennylane_sdk/resources/company/products.py` is the reference style.
+3. Write the resource method (sync and async), the models, and tests.
+4. Make the four checks above pass. `check_coverage.py` must report full coverage.
+
+## Style rules
+
+- English everywhere in code and docs.
+- No em dashes or en dashes in text; use plain punctuation.
+- Docstrings state the required scope and link the official reference page.
+- Response model fields are optional (`| None = None`) except `id`; monetary strings use the `Money` type.
+
+## Releasing (maintainers)
+
+1. Update `CHANGELOG.md` and bump the version in `pyproject.toml` and `src/pennylane_sdk/_version.py`.
+2. Tag: `git tag v0.x.y && git push --tags`.
+3. The `release.yml` workflow tests, builds and publishes to PyPI via trusted publishing.
+
+## When the API changes
+
+Refresh the vendored specs and see what the coverage audit says:
+
+```bash
+uv run python scripts/update_specs.py
+uv run python scripts/check_coverage.py
+```
+
+New operations show up as MISSING; removed ones as UNKNOWN CALL. Please open an issue even if you cannot fix it yourself.

pennylane_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pennylane SDK Contributors
+
+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.

pennylane_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: pennylane-sdk
+Version: 0.1.0
+Summary: Unofficial Python SDK for the Pennylane API — the French accounting and invoicing platform
+Project-URL: Homepage, https://github.com/pennylane-sdk/pennylane-sdk
+Project-URL: Documentation, https://github.com/pennylane-sdk/pennylane-sdk#readme
+Project-URL: Repository, https://github.com/pennylane-sdk/pennylane-sdk
+Project-URL: Changelog, https://github.com/pennylane-sdk/pennylane-sdk/blob/main/CHANGELOG.md
+Author: Pennylane SDK Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accounting,api,comptabilite,e-invoicing,factur-x,facturation,france,invoicing,pennylane,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Natural Language :: French
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio<5,>=4.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: typing-extensions>=4.10
+Description-Content-Type: text/markdown
+
+# pennylane-sdk
+
+> The unofficial Python SDK for the [Pennylane](https://www.pennylane.com) API, the French accounting and invoicing platform.
+
+🇫🇷 [Version française](README.fr.md)
+
+[![CI](https://github.com/GoatAndCow7/pennylane-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/GoatAndCow7/pennylane-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pennylane-sdk)](https://pypi.org/project/pennylane-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/pennylane-sdk)](https://pypi.org/project/pennylane-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE)
+
+**[Documentation](https://goatandcow7.github.io/pennylane-sdk/)** | [API coverage: 213/213 operations](#complete-api-coverage)
+
+- **Complete**: every operation of the Company API v2 (165) and the Firm API v1 (48), in sync and async, audited against the official OpenAPI specs in CI.
+- **Typed**: Pydantic models everywhere; monetary amounts are `Decimal`, never floats.
+- **Safe for accounting**: the API has no idempotency, so POST is never retried after a server error. No duplicate invoices from a network hiccup.
+- **Rate-limit proof**: built-in client-side throttling to the official limits, plus `retry-after` aware retries on 429.
+- **Effortless pagination**: iterate a list call, the SDK fetches the pages.
+
+> Not affiliated with Pennylane SAS. Unrelated to the PennyLane quantum computing framework (which owns `pennylane` on PyPI; this package is `pennylane-sdk`).
+
+## Install
+
+```bash
+pip install pennylane-sdk
+```
+
+Python 3.10+.
+
+## Quickstart
+
+Create an API token in Pennylane (**Settings > Connectivity > Developers**), then:
+
+```python
+from pennylane_sdk import Pennylane, filters
+
+client = Pennylane()  # reads PENNYLANE_API_TOKEN
+
+# List and filter, with transparent pagination
+for invoice in client.customer_invoices.list(
+    filter=[filters.gte("date", "2026-01-01")],
+    sort="-date",
+):
+    print(invoice.invoice_number, invoice.currency_amount)
+
+# Create, finalize, send
+invoice = client.customer_invoices.create(
+    customer_id=123,
+    date="2026-07-08",
+    deadline="2026-08-07",
+    invoice_lines=[{"product_id": 45, "quantity": "2"}],
+)
+client.customer_invoices.finalize(invoice.id)
+client.customer_invoices.send_by_email(invoice.id)
+```
+
+Async, same surface:
+
+```python
+from pennylane_sdk import AsyncPennylane
+
+async with AsyncPennylane() as client:
+    page = await client.customer_invoices.list(limit=100)
+    async for invoice in page:
+        ...
+```
+
+Accounting firms, across the whole portfolio:
+
+```python
+from pennylane_sdk import PennylaneFirm
+
+firm = PennylaneFirm()  # reads PENNYLANE_FIRM_API_TOKEN
+for company in firm.companies.list():
+    for row in firm.trial_balance.list(
+        company.id, period_start="2026-01-01", period_end="2026-06-30"
+    ):
+        ...
+```
+
+French e-invoicing (2026 reform), Pennylane being an accredited Plateforme Agréée:
+
+```python
+client.customer_invoices.send_to_pa(invoice.id)                  # emit through the PA
+client.supplier_invoices.import_e_invoice(file="factur-x.pdf")   # ingest Factur-X/UBL/CII
+```
+
+## Complete API coverage
+
+| API | Operations | Resources |
+|---|---|---|
+| Company v2 | 165/165 | customer and supplier invoices, quotes, customers, products, billing subscriptions, banking and reconciliation, journals, ledger entries, lettering, trial balance, analytics, FEC/GL/AGL exports, SEPA/GoCardless/Pro mandates, e-invoicing, changelogs, webhooks |
+| Firm v1 | 48/48 | client portfolio, accounting, DMS, exports, invoicing (read), banking, analytics, changelogs |
+
+Coverage is not a promise: `scripts/check_coverage.py` verifies in CI that every operation in the vendored official OpenAPI specs exists in both the sync and async clients.
+
+## Learn more
+
+- [Getting started](https://goatandcow7.github.io/pennylane-sdk/getting-started/)
+- [Guides](https://goatandcow7.github.io/pennylane-sdk/guides/authentication/): authentication, pagination and filtering, errors and retries, invoicing lifecycle, e-invoicing 2026, accounting, Firm API, webhooks, OAuth apps
+- [API reference](https://goatandcow7.github.io/pennylane-sdk/api/clients/)
+- [Examples](examples/)
+- [Contributing](CONTRIBUTING.md)
+
+## License
+
+[MIT](LICENSE). Build whatever you want with it.

pennylane_sdk-0.1.0/README.fr.md

@@ -0,0 +1,128 @@
+# pennylane-sdk
+
+> Le SDK Python non officiel pour l'API de [Pennylane](https://www.pennylane.com), la plateforme française de comptabilité et de facturation.
+
+🇬🇧 [English version](README.md)
+
+**[Documentation complète](https://goatandcow7.github.io/pennylane-sdk/)** (en anglais)
+
+## Pourquoi ce SDK
+
+- **Complet** : la totalité des opérations de l'API Entreprise v2 (165) et de l'API Cabinet v1 (48), en synchrone et en asynchrone. La couverture est vérifiée automatiquement en CI contre les spécifications OpenAPI officielles de Pennylane.
+- **Typé** : chaque réponse est un modèle Pydantic. Les montants sont des `Decimal`, jamais des floats, exactement comme l'API le demande (les montants circulent en chaînes pour éviter les erreurs d'arrondi).
+- **Sûr pour la compta** : l'API Pennylane n'a pas d'idempotence côté serveur. Le SDK ne réessaie donc jamais un POST après une erreur serveur : impossible de créer une facture en double à cause d'un souci réseau.
+- **Anti rate-limit** : les requêtes sont cadencées côté client aux limites officielles (25 requêtes / 5 s pour les entreprises, 5/s pour les cabinets), et les 429 sont réessayés en respectant `retry-after`. Vos exports de masse passent sans effort.
+- **Pagination invisible** : itérez sur un `list()` et le SDK va chercher les pages suivantes tout seul, en renvoyant vos filtres comme l'API l'exige.
+
+> Projet communautaire, non affilié à Pennylane SAS. Sans rapport avec le framework de calcul quantique PennyLane (qui possède le nom `pennylane` sur PyPI ; ce paquet s'appelle `pennylane-sdk`).
+
+## Installation
+
+```bash
+pip install pennylane-sdk
+```
+
+Python 3.10 ou plus récent.
+
+## Démarrage rapide
+
+Créez un jeton API dans Pennylane (**Paramètres > Connectivité > Développeurs**), copiez-le immédiatement (il n'est affiché qu'une fois), puis :
+
+```bash
+export PENNYLANE_API_TOKEN="votre-jeton"
+```
+
+```python
+from pennylane_sdk import Pennylane, filters
+
+client = Pennylane()
+
+# Lister et filtrer, pagination transparente
+for facture in client.customer_invoices.list(
+    filter=[filters.gte("date", "2026-01-01")],
+    sort="-date",
+):
+    print(facture.invoice_number, facture.currency_amount)
+
+# Créer un brouillon, le finaliser, l'envoyer
+facture = client.customer_invoices.create(
+    customer_id=123,
+    date="2026-07-08",
+    deadline="2026-08-07",
+    invoice_lines=[{"product_id": 45, "quantity": "2"}],
+)
+client.customer_invoices.finalize(facture.id)
+client.customer_invoices.send_by_email(facture.id)
+```
+
+La version asynchrone offre exactement la même surface :
+
+```python
+from pennylane_sdk import AsyncPennylane
+
+async with AsyncPennylane() as client:
+    page = await client.customer_invoices.list(limit=100)
+    async for facture in page:
+        ...
+```
+
+## Cabinets d'expertise comptable
+
+L'API Cabinet permet de travailler sur tout le portefeuille de dossiers clients :
+
+```python
+from pennylane_sdk import PennylaneFirm
+
+cabinet = PennylaneFirm()  # lit PENNYLANE_FIRM_API_TOKEN
+
+for dossier in cabinet.companies.list():
+    # Balance générale du dossier sur la période
+    for ligne in cabinet.trial_balance.list(
+        dossier.id, period_start="2026-01-01", period_end="2026-06-30"
+    ):
+        print(ligne.number, ligne.debits, ligne.credits)
+
+    # Export FEC
+    export = cabinet.exports.fecs.create(
+        dossier.id, period_start="2026-01-01", period_end="2026-12-31"
+    )
+```
+
+## Facturation électronique (réforme 2026)
+
+Pennylane est Plateforme Agréée (PA) : l'API couvre l'émission et la réception des factures électroniques, et le SDK aussi.
+
+```python
+# Émettre une facture via la plateforme agréée
+client.customer_invoices.send_to_pa(facture.id)
+
+# Importer une facture fournisseur Factur-X / UBL / CII
+client.supplier_invoices.import_e_invoice(file="facture.xml")
+
+# Suivre vos immatriculations PA
+client.pa_registrations.list()
+```
+
+## Ce que couvre le SDK
+
+| Domaine | Ressources |
+|---|---|
+| Ventes | factures clients, avoirs, devis, abonnements récurrents, clients, produits, envoi par email ou par PA |
+| Achats | fournisseurs, factures fournisseurs, bons de commande, statuts de paiement |
+| Banque | comptes, transactions, rapprochement avec les factures |
+| Comptabilité | journaux, plan comptable, écritures, lettrage, balance, exercices |
+| Analytique | catégories et axes analytiques sur factures, transactions, écritures |
+| Exports | FEC, grand livre, grand livre analytique |
+| Mandats | SEPA, GoCardless, compte pro |
+| Synchronisation | changelogs par ressource, webhooks (bêta), OAuth 2.0 pour les apps partenaires |
+| Cabinet | dossiers clients, comptabilité, GED, exports, lecture des factures |
+
+Gestion des erreurs : une hiérarchie d'exceptions claire (`AuthenticationError`, `ValidationError` avec les détails métier, `RateLimitError` avec `retry_after`...). Voir le [guide des erreurs](https://goatandcow7.github.io/pennylane-sdk/guides/errors-and-retries/).
+
+## Contribuer
+
+Les contributions sont bienvenues, en anglais de préférence pour le code et les issues. Voir [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Licence
+
+[MIT](LICENSE). Utilisez-le librement, y compris commercialement.

pennylane_sdk-0.1.0/README.md

@@ -0,0 +1,107 @@
+# pennylane-sdk
+
+> The unofficial Python SDK for the [Pennylane](https://www.pennylane.com) API, the French accounting and invoicing platform.
+
+🇫🇷 [Version française](README.fr.md)
+
+[![CI](https://github.com/GoatAndCow7/pennylane-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/GoatAndCow7/pennylane-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pennylane-sdk)](https://pypi.org/project/pennylane-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/pennylane-sdk)](https://pypi.org/project/pennylane-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE)
+
+**[Documentation](https://goatandcow7.github.io/pennylane-sdk/)** | [API coverage: 213/213 operations](#complete-api-coverage)
+
+- **Complete**: every operation of the Company API v2 (165) and the Firm API v1 (48), in sync and async, audited against the official OpenAPI specs in CI.
+- **Typed**: Pydantic models everywhere; monetary amounts are `Decimal`, never floats.
+- **Safe for accounting**: the API has no idempotency, so POST is never retried after a server error. No duplicate invoices from a network hiccup.
+- **Rate-limit proof**: built-in client-side throttling to the official limits, plus `retry-after` aware retries on 429.
+- **Effortless pagination**: iterate a list call, the SDK fetches the pages.
+
+> Not affiliated with Pennylane SAS. Unrelated to the PennyLane quantum computing framework (which owns `pennylane` on PyPI; this package is `pennylane-sdk`).
+
+## Install
+
+```bash
+pip install pennylane-sdk
+```
+
+Python 3.10+.
+
+## Quickstart
+
+Create an API token in Pennylane (**Settings > Connectivity > Developers**), then:
+
+```python
+from pennylane_sdk import Pennylane, filters
+
+client = Pennylane()  # reads PENNYLANE_API_TOKEN
+
+# List and filter, with transparent pagination
+for invoice in client.customer_invoices.list(
+    filter=[filters.gte("date", "2026-01-01")],
+    sort="-date",
+):
+    print(invoice.invoice_number, invoice.currency_amount)
+
+# Create, finalize, send
+invoice = client.customer_invoices.create(
+    customer_id=123,
+    date="2026-07-08",
+    deadline="2026-08-07",
+    invoice_lines=[{"product_id": 45, "quantity": "2"}],
+)
+client.customer_invoices.finalize(invoice.id)
+client.customer_invoices.send_by_email(invoice.id)
+```
+
+Async, same surface:
+
+```python
+from pennylane_sdk import AsyncPennylane
+
+async with AsyncPennylane() as client:
+    page = await client.customer_invoices.list(limit=100)
+    async for invoice in page:
+        ...
+```
+
+Accounting firms, across the whole portfolio:
+
+```python
+from pennylane_sdk import PennylaneFirm
+
+firm = PennylaneFirm()  # reads PENNYLANE_FIRM_API_TOKEN
+for company in firm.companies.list():
+    for row in firm.trial_balance.list(
+        company.id, period_start="2026-01-01", period_end="2026-06-30"
+    ):
+        ...
+```
+
+French e-invoicing (2026 reform), Pennylane being an accredited Plateforme Agréée:
+
+```python
+client.customer_invoices.send_to_pa(invoice.id)                  # emit through the PA
+client.supplier_invoices.import_e_invoice(file="factur-x.pdf")   # ingest Factur-X/UBL/CII
+```
+
+## Complete API coverage
+
+| API | Operations | Resources |
+|---|---|---|
+| Company v2 | 165/165 | customer and supplier invoices, quotes, customers, products, billing subscriptions, banking and reconciliation, journals, ledger entries, lettering, trial balance, analytics, FEC/GL/AGL exports, SEPA/GoCardless/Pro mandates, e-invoicing, changelogs, webhooks |
+| Firm v1 | 48/48 | client portfolio, accounting, DMS, exports, invoicing (read), banking, analytics, changelogs |
+
+Coverage is not a promise: `scripts/check_coverage.py` verifies in CI that every operation in the vendored official OpenAPI specs exists in both the sync and async clients.
+
+## Learn more
+
+- [Getting started](https://goatandcow7.github.io/pennylane-sdk/getting-started/)
+- [Guides](https://goatandcow7.github.io/pennylane-sdk/guides/authentication/): authentication, pagination and filtering, errors and retries, invoicing lifecycle, e-invoicing 2026, accounting, Firm API, webhooks, OAuth apps
+- [API reference](https://goatandcow7.github.io/pennylane-sdk/api/clients/)
+- [Examples](examples/)
+- [Contributing](CONTRIBUTING.md)
+
+## License
+
+[MIT](LICENSE). Build whatever you want with it.