efact 1.0.0__tar.gz

efact-1.0.0/LICENSE

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

efact-1.0.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: efact
+Version: 1.0.0
+Summary: SDK Python officiel EFact pour l'e-facturation (DGI Maroc)
+Author-email: Itzenata <contact@itzenata.com>
+License: MIT
+Project-URL: Homepage, https://github.com/itzenata/sdk/tree/main/python-sdk#readme
+Project-URL: Repository, https://github.com/itzenata/sdk
+Keywords: efact,e-facturation,invoice,invoicing,dgi,morocco,maroc,itzenata,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urllib3<3,>=1.25.3
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4.7.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# efact
+
+SDK Python officiel **EFact** pour l'e-facturation au Maroc (mandat DGI).
+
+EFact est une API de conformité (« le Stripe de la facturation électronique »).
+Ce SDK est une fine couche typée au-dessus de l'API REST EFact :
+authentification par clé, nouveaux essais, délais, et erreurs typées.
+
+- ✅ Typé (Pydantic v2)
+- ✅ Timeouts, retries avec back-off, erreurs typées
+- ✅ Généré depuis le contrat OpenAPI — toujours aligné sur l'API
+
+## Installation
+
+```bash
+pip install efact
+```
+
+Prérequis : **Python ≥ 3.9**.
+
+## Démarrage rapide
+
+```python
+import os
+from efact import EFact
+
+# La clé secrète identifie ET authentifie votre organisation (modèle Stripe).
+# Ne la committez jamais : chargez-la depuis l'environnement.
+efact = EFact(os.environ["EFACT_SECRET_KEY"])
+
+invoice = efact.invoices.create({
+    "invoiceNumber": "INV-2026-001",
+    "invoiceDate": "2026-06-24",
+    "currency": "MAD",
+    "paymentMethod": "BANK_TRANSFER",
+    # Acheteur (optionnel) — format plat, aligné sur l'API.
+    "buyerIce": "001234567890123",  # 15 chiffres si fourni
+    "buyerName": "Client SARL",
+    "buyerAddress": "Casablanca",
+    "lines": [
+        {
+            "lineNumber": 1,
+            "description": "Prestation de service",
+            "quantity": 1,
+            "unitPrice": 1000,
+            "vatRate": 20,
+        },
+    ],
+})
+
+print(invoice.id, invoice.status)
+```
+
+## Configuration
+
+**Aucune configuration n'est requise.** `EFact(secret_key)` cible la production
+et gère l'authentification, l'URL, les délais et les nouveaux essais pour vous.
+
+Deux options facultatives permettent d'ajuster le comportement réseau (valeurs
+par défaut sûres) :
+
+```python
+EFact(
+    secret_key,
+    timeout=30.0,     # délai max par requête (s) — défaut 30
+    max_retries=2,    # rejeux sur erreurs transitoires (méthodes sûres) — défaut 2
+)
+```
+
+## Opérations sur les factures
+
+| Méthode | Description |
+| --- | --- |
+| `efact.invoices.create(data)` | Crée une facture |
+| `efact.invoices.list(...)` | Liste paginée (filtre par statut optionnel) |
+| `efact.invoices.retrieve(id)` | Récupère une facture |
+| `efact.invoices.retrieve_status(id)` | Statut de clairance DGI |
+| `efact.invoices.update(id, patch)` | Met à jour une facture (PENDING uniquement) |
+| `efact.invoices.cancel(id)` | Annule une facture (PENDING uniquement) |
+
+L'organisation est résolue côté serveur à partir de la clé API : aucun
+`organization_id` n'est transmis. La modification et l'annulation ne sont
+possibles que tant que la facture est au statut `PENDING`.
+
+```python
+# Lister (pagination + filtre optionnels)
+page = efact.invoices.list(page=0, size=20, status="ACCEPTED")
+for inv in page.content:
+    print(inv.invoice_number, inv.status)
+
+# Suivre la clairance DGI
+status = efact.invoices.retrieve_status(invoice.id)
+print(status.status, status.dgi_reference)
+```
+
+## Gestion des erreurs
+
+Toutes les erreurs héritent de `EFactError`. Les réponses non-OK de l'API
+sont converties en erreurs typées portant `code`, `http_status` et `errors`.
+
+```python
+from efact import (
+    EFactApiError,
+    EFactAuthError,
+    EFactValidationError,
+    EFactNotFoundError,
+    EFactConflictError,
+    EFactConnectionError,
+    EFactTimeoutError,
+)
+
+try:
+    efact.invoices.create(data)
+except EFactValidationError as e:
+    print("Champs invalides :", e.errors)
+except EFactAuthError:
+    print("Clé API manquante ou invalide.")
+except EFactConflictError:
+    print("Facture non modifiable (statut ≠ PENDING).")
+except EFactApiError as e:
+    print(e.code, e.http_status, e)
+except EFactTimeoutError:
+    print("Délai dépassé.")
+except EFactConnectionError:
+    print("Échec réseau.")
+```
+
+| Erreur | Cas |
+| --- | --- |
+| `EFactConfigError` | Mauvaise configuration (avant tout appel réseau) |
+| `EFactAuthError` | 401/403 — clé manquante/invalide |
+| `EFactValidationError` | 400/422 — champs invalides (`errors`) |
+| `EFactNotFoundError` | 404 — introuvable (inclut cross-tenant) |
+| `EFactConflictError` | 409 — facture non modifiable/annulable |
+| `EFactApiError` | autre erreur API |
+| `EFactTimeoutError` | délai dépassé |
+| `EFactConnectionError` | échec réseau |
+
+Les méthodes sûres (`GET`/`PUT`/`DELETE`) sont automatiquement rejouées sur
+les erreurs transitoires (408, 425, 429, 5xx, coupures réseau) avec back-off
+exponentiel et respect de `Retry-After`. `POST` (création) n'est jamais rejoué.
+
+## Sécurité
+
+- La clé n'est attachée qu'en `Authorization: Bearer <clé>`, jamais dans l'URL.
+- `efact.get_config()` ne renvoie qu'une version masquée de la clé.
+- Les messages d'erreur n'incluent jamais la clé ni le corps brut de la réponse.
+
+## Licence
+
+[MIT](./LICENSE)

efact-1.0.0/README.md

@@ -0,0 +1,151 @@
+# efact
+
+SDK Python officiel **EFact** pour l'e-facturation au Maroc (mandat DGI).
+
+EFact est une API de conformité (« le Stripe de la facturation électronique »).
+Ce SDK est une fine couche typée au-dessus de l'API REST EFact :
+authentification par clé, nouveaux essais, délais, et erreurs typées.
+
+- ✅ Typé (Pydantic v2)
+- ✅ Timeouts, retries avec back-off, erreurs typées
+- ✅ Généré depuis le contrat OpenAPI — toujours aligné sur l'API
+
+## Installation
+
+```bash
+pip install efact
+```
+
+Prérequis : **Python ≥ 3.9**.
+
+## Démarrage rapide
+
+```python
+import os
+from efact import EFact
+
+# La clé secrète identifie ET authentifie votre organisation (modèle Stripe).
+# Ne la committez jamais : chargez-la depuis l'environnement.
+efact = EFact(os.environ["EFACT_SECRET_KEY"])
+
+invoice = efact.invoices.create({
+    "invoiceNumber": "INV-2026-001",
+    "invoiceDate": "2026-06-24",
+    "currency": "MAD",
+    "paymentMethod": "BANK_TRANSFER",
+    # Acheteur (optionnel) — format plat, aligné sur l'API.
+    "buyerIce": "001234567890123",  # 15 chiffres si fourni
+    "buyerName": "Client SARL",
+    "buyerAddress": "Casablanca",
+    "lines": [
+        {
+            "lineNumber": 1,
+            "description": "Prestation de service",
+            "quantity": 1,
+            "unitPrice": 1000,
+            "vatRate": 20,
+        },
+    ],
+})
+
+print(invoice.id, invoice.status)
+```
+
+## Configuration
+
+**Aucune configuration n'est requise.** `EFact(secret_key)` cible la production
+et gère l'authentification, l'URL, les délais et les nouveaux essais pour vous.
+
+Deux options facultatives permettent d'ajuster le comportement réseau (valeurs
+par défaut sûres) :
+
+```python
+EFact(
+    secret_key,
+    timeout=30.0,     # délai max par requête (s) — défaut 30
+    max_retries=2,    # rejeux sur erreurs transitoires (méthodes sûres) — défaut 2
+)
+```
+
+## Opérations sur les factures
+
+| Méthode | Description |
+| --- | --- |
+| `efact.invoices.create(data)` | Crée une facture |
+| `efact.invoices.list(...)` | Liste paginée (filtre par statut optionnel) |
+| `efact.invoices.retrieve(id)` | Récupère une facture |
+| `efact.invoices.retrieve_status(id)` | Statut de clairance DGI |
+| `efact.invoices.update(id, patch)` | Met à jour une facture (PENDING uniquement) |
+| `efact.invoices.cancel(id)` | Annule une facture (PENDING uniquement) |
+
+L'organisation est résolue côté serveur à partir de la clé API : aucun
+`organization_id` n'est transmis. La modification et l'annulation ne sont
+possibles que tant que la facture est au statut `PENDING`.
+
+```python
+# Lister (pagination + filtre optionnels)
+page = efact.invoices.list(page=0, size=20, status="ACCEPTED")
+for inv in page.content:
+    print(inv.invoice_number, inv.status)
+
+# Suivre la clairance DGI
+status = efact.invoices.retrieve_status(invoice.id)
+print(status.status, status.dgi_reference)
+```
+
+## Gestion des erreurs
+
+Toutes les erreurs héritent de `EFactError`. Les réponses non-OK de l'API
+sont converties en erreurs typées portant `code`, `http_status` et `errors`.
+
+```python
+from efact import (
+    EFactApiError,
+    EFactAuthError,
+    EFactValidationError,
+    EFactNotFoundError,
+    EFactConflictError,
+    EFactConnectionError,
+    EFactTimeoutError,
+)
+
+try:
+    efact.invoices.create(data)
+except EFactValidationError as e:
+    print("Champs invalides :", e.errors)
+except EFactAuthError:
+    print("Clé API manquante ou invalide.")
+except EFactConflictError:
+    print("Facture non modifiable (statut ≠ PENDING).")
+except EFactApiError as e:
+    print(e.code, e.http_status, e)
+except EFactTimeoutError:
+    print("Délai dépassé.")
+except EFactConnectionError:
+    print("Échec réseau.")
+```
+
+| Erreur | Cas |
+| --- | --- |
+| `EFactConfigError` | Mauvaise configuration (avant tout appel réseau) |
+| `EFactAuthError` | 401/403 — clé manquante/invalide |
+| `EFactValidationError` | 400/422 — champs invalides (`errors`) |
+| `EFactNotFoundError` | 404 — introuvable (inclut cross-tenant) |
+| `EFactConflictError` | 409 — facture non modifiable/annulable |
+| `EFactApiError` | autre erreur API |
+| `EFactTimeoutError` | délai dépassé |
+| `EFactConnectionError` | échec réseau |
+
+Les méthodes sûres (`GET`/`PUT`/`DELETE`) sont automatiquement rejouées sur
+les erreurs transitoires (408, 425, 429, 5xx, coupures réseau) avec back-off
+exponentiel et respect de `Retry-After`. `POST` (création) n'est jamais rejoué.
+
+## Sécurité
+
+- La clé n'est attachée qu'en `Authorization: Bearer <clé>`, jamais dans l'URL.
+- `efact.get_config()` ne renvoie qu'une version masquée de la clé.
+- Les messages d'erreur n'incluent jamais la clé ni le corps brut de la réponse.
+
+## Licence
+
+[MIT](./LICENSE)

efact-1.0.0/efact/__init__.py

@@ -0,0 +1,61 @@
+"""SDK Python officiel EFact — e-facturation (DGI Maroc).
+
+Surface publique du SDK. Les types du contrat sont réexportés depuis
+`efact._generated` (régénérés depuis l'OpenAPI) : un changement de champ côté
+API se propage ici automatiquement.
+"""
+
+from efact.client import ENVIRONMENTS, EFact
+from efact.errors import (
+    AUTH_ERROR_CODES,
+    CONFLICT_ERROR_CODES,
+    VALIDATION_ERROR_CODES,
+    EFactApiError,
+    EFactAuthError,
+    EFactConfigError,
+    EFactConflictError,
+    EFactConnectionError,
+    EFactError,
+    EFactNotFoundError,
+    EFactTimeoutError,
+    EFactValidationError,
+    create_api_error,
+)
+from efact.invoices import InvoicesResource
+
+# Types du contrat (générés).
+from efact._generated.models.create_invoice_line_request import CreateInvoiceLineRequest
+from efact._generated.models.create_invoice_request import CreateInvoiceRequest
+from efact._generated.models.field_error import FieldError
+from efact._generated.models.invoice_response import InvoiceResponse
+from efact._generated.models.invoice_status_response import InvoiceStatusResponse
+from efact._generated.models.page_response_invoice_response import PageResponseInvoiceResponse
+from efact._generated.models.update_invoice_request import UpdateInvoiceRequest
+
+__all__ = [
+    "EFact",
+    "ENVIRONMENTS",
+    "InvoicesResource",
+    # Erreurs
+    "EFactError",
+    "EFactConfigError",
+    "EFactConnectionError",
+    "EFactTimeoutError",
+    "EFactApiError",
+    "EFactAuthError",
+    "EFactValidationError",
+    "EFactNotFoundError",
+    "EFactConflictError",
+    "create_api_error",
+    "AUTH_ERROR_CODES",
+    "CONFLICT_ERROR_CODES",
+    "VALIDATION_ERROR_CODES",
+    # Types générés
+    "CreateInvoiceRequest",
+    "CreateInvoiceLineRequest",
+    "UpdateInvoiceRequest",
+    "InvoiceResponse",
+    "InvoiceStatusResponse",
+    "PageResponseInvoiceResponse",
+    "FieldError",
+]

efact-1.0.0/efact/_generated/__init__.py

@@ -0,0 +1,44 @@
+# coding: utf-8
+
+# flake8: noqa
+
+"""
+    EFact API
+
+    Compliance-as-a-service backend for Moroccan DGI electronic invoicing
+
+    The version of the OpenAPI document: v0.0.1-SNAPSHOT
+    Contact: contact@itzenata.com
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+__version__ = "1.0.0"
+
+# import apis into sdk package
+from efact._generated.api.invoices_api import InvoicesApi
+
+# import ApiClient
+from efact._generated.api_response import ApiResponse
+from efact._generated.api_client import ApiClient
+from efact._generated.configuration import Configuration
+from efact._generated.exceptions import OpenApiException
+from efact._generated.exceptions import ApiTypeError
+from efact._generated.exceptions import ApiValueError
+from efact._generated.exceptions import ApiKeyError
+from efact._generated.exceptions import ApiAttributeError
+from efact._generated.exceptions import ApiException
+
+# import models into sdk package
+from efact._generated.models.api_response_invoice_response import ApiResponseInvoiceResponse
+from efact._generated.models.api_response_invoice_status_response import ApiResponseInvoiceStatusResponse
+from efact._generated.models.api_response_page_response_invoice_response import ApiResponsePageResponseInvoiceResponse
+from efact._generated.models.create_invoice_line_request import CreateInvoiceLineRequest
+from efact._generated.models.create_invoice_request import CreateInvoiceRequest
+from efact._generated.models.field_error import FieldError
+from efact._generated.models.invoice_response import InvoiceResponse
+from efact._generated.models.invoice_status_response import InvoiceStatusResponse
+from efact._generated.models.page_response_invoice_response import PageResponseInvoiceResponse
+from efact._generated.models.update_invoice_request import UpdateInvoiceRequest

efact-1.0.0/efact/_generated/api/__init__.py

@@ -0,0 +1,5 @@
+# flake8: noqa
+
+# import apis into api package
+from efact._generated.api.invoices_api import InvoicesApi
+