sage-messaging 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ .venv/
4
+ dist/
5
+ .pytest_cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Le Sage Code
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,181 @@
1
+ Metadata-Version: 2.5
2
+ Name: sage-messaging
3
+ Version: 0.1.0
4
+ Summary: SDK officiel de l'API Sage Messaging (WhatsApp & SMS).
5
+ Author-email: Le Sage Code <angezanou00@gmail.com>
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Keywords: messaging,sagecoders,sdk,sms,whatsapp
9
+ Classifier: Framework :: AsyncIO
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Typing :: Typed
12
+ Requires-Python: >=3.9
13
+ Requires-Dist: httpx<1,>=0.25
14
+ Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
15
+ Provides-Extra: dev
16
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
17
+ Requires-Dist: pytest>=8; extra == 'dev'
18
+ Description-Content-Type: text/markdown
19
+
20
+ # sage-messaging (Python)
21
+
22
+ SDK officiel de l'API [Sage Messaging](https://messaging.sagecoders.com) : envoi et lecture de messages WhatsApp et SMS, vérification des webhooks.
23
+
24
+ ```bash
25
+ pip install sage-messaging
26
+ ```
27
+
28
+ Python 3.9+. Client synchrone et asynchrone.
29
+
30
+ ## Démarrage
31
+
32
+ ```python
33
+ from sage_messaging import SageMessaging
34
+
35
+ client = SageMessaging(api_key="sk_...") # ou variable SAGE_MESSAGING_API_KEY
36
+
37
+ # WhatsApp (canal par défaut)
38
+ client.messages.send(phone="+22997000000", message="Bonjour !")
39
+
40
+ # SMS
41
+ client.sms.send(phone="+22997000000", message="Votre code : 4821")
42
+ ```
43
+
44
+ ### Asynchrone
45
+
46
+ ```python
47
+ from sage_messaging import AsyncSageMessaging
48
+
49
+ async with AsyncSageMessaging() as client:
50
+ await client.messages.send(phone="+22997000000", message="Bonjour !")
51
+ ```
52
+
53
+ Les méthodes sont identiques ; il suffit de les `await`.
54
+
55
+ ## Configuration
56
+
57
+ | Paramètre | Variable d'environnement | Défaut |
58
+ | ---------------- | ------------------------------- | --------------------------------- |
59
+ | `api_key` | `SAGE_MESSAGING_API_KEY` | — |
60
+ | `base_url` | `SAGE_MESSAGING_BASE_URL` | `https://messaging.sagecoders.com` |
61
+ | `webhook_secret` | `SAGE_MESSAGING_WEBHOOK_SECRET` | — |
62
+ | `timeout` | | `30` secondes |
63
+ | `max_retries` | | `2` (lectures uniquement) |
64
+
65
+ Les **lectures** (GET) sont rejouées en cas d'erreur réseau, de 429 ou de 5xx. Les **envois ne sont jamais rejoués** : un envoi dont la réponse s'est perdue a pu partir, et le rejouer enverrait le message en double.
66
+
67
+ ## Envoi
68
+
69
+ ```python
70
+ # Message texte, WhatsApp ou SMS
71
+ client.messages.send(phone="+229...", message="Salut", channel="sms")
72
+
73
+ # SMS différé, depuis un téléphone précis
74
+ from datetime import datetime, timedelta, timezone
75
+ client.sms.send(
76
+ phone="+229...",
77
+ message="Rappel : RDV demain",
78
+ from_="+229...", # voir client.sms.phones()
79
+ send_at=datetime.now(timezone.utc) + timedelta(hours=2), # 20 jours max
80
+ )
81
+
82
+ # Campagne SMS (1 à 100 destinataires)
83
+ client.sms.bulk_send(phones=["+229...", "+229..."], message="Promo -20 %")
84
+
85
+ # Médias WhatsApp (1 à 10, 16 Mo max chacun), envoyés dans l'ordre
86
+ res = client.messages.send_media(
87
+ phone="+229...",
88
+ caption="Votre facture",
89
+ media=[
90
+ {"path": "facture.pdf"}, # fichier local
91
+ {"url": "https://exemple.com/photo.jpg"}, # URL publique
92
+ {"data": image_bytes, "filename": "capture.png"}, # octets
93
+ ],
94
+ )
95
+ if res["failed"]: # succès partiel (HTTP 207)
96
+ print("Échecs :", res["failed"])
97
+ ```
98
+
99
+ Utilisez des `datetime` avec fuseau horaire pour `send_at` et `since`.
100
+
101
+ ## Lecture
102
+
103
+ ```python
104
+ client.conversations.list(unread_only=True, limit=20)
105
+ client.conversations.messages(42, direction="received")
106
+ client.conversations.mark_read(42)
107
+
108
+ client.messages.list(after_id=1000) # flux global, id croissant
109
+ ```
110
+
111
+ Les réponses paginées ont la forme `{"data": [...], "meta": {"current_page", "per_page", "total", "last_page"}}`.
112
+
113
+ ### Suivre les nouveaux messages sans webhook
114
+
115
+ ```python
116
+ for msg in client.messages.poll(direction="received", interval=5):
117
+ print(msg["contact_phone"], msg["body"])
118
+ ```
119
+
120
+ Sans `after_id`, seuls les messages arrivés après l'appel sont renvoyés. Pour reprendre après un redémarrage, conservez le dernier `msg["id"]` et passez-le en `after_id`.
121
+
122
+ ## Webhooks
123
+
124
+ Chaque webhook est signé en HMAC-SHA256 (`X-Signature`, `X-Timestamp`). Passez le **corps brut** de la requête, pas un JSON re-sérialisé.
125
+
126
+ ```python
127
+ from sage_messaging import verify_webhook, WebhookVerificationError
128
+
129
+ # FastAPI
130
+ @app.post("/webhooks/sage")
131
+ async def sage_webhook(request: Request):
132
+ try:
133
+ event = verify_webhook(await request.body(), request.headers, SECRET)
134
+ except WebhookVerificationError:
135
+ raise HTTPException(400)
136
+
137
+ if event["event"] == "message.received":
138
+ msg = event["data"]["message"]
139
+ contact = event["data"]["conversation"]
140
+ ...
141
+ return {"ok": True}
142
+ ```
143
+
144
+ Django : `verify_webhook(request.body, request.headers, SECRET)` ; Flask : `verify_webhook(request.get_data(), request.headers, SECRET)`.
145
+
146
+ Les requêtes de plus de 5 minutes sont refusées (`tolerance=300`) pour empêcher leur rejeu.
147
+
148
+ ## Erreurs
149
+
150
+ ```python
151
+ from sage_messaging import ValidationError, GatewayError, SageMessagingError
152
+
153
+ try:
154
+ client.sms.send(phone="+229...", message="...")
155
+ except ValidationError as e: # 422 : champ invalide, canal non provisionné…
156
+ print(e.errors, e.channel)
157
+ except GatewayError as e: # 502 : la passerelle a refusé l'envoi
158
+ print(e.detail)
159
+ except SageMessagingError as e: # toutes les autres erreurs du SDK
160
+ print(e)
161
+ ```
162
+
163
+ | Classe | Cas |
164
+ | ------------------------ | ------------------------------------------------------- |
165
+ | `AuthenticationError` | 401 : clé absente ou invalide |
166
+ | `PermissionDeniedError` | 403 : la clé n'a pas la permission requise |
167
+ | `NotFoundError` | 404 |
168
+ | `ValidationError` | 422 |
169
+ | `RateLimitError` | 429 |
170
+ | `GatewayError` | 502 : refus de WhatsApp ou de la passerelle SMS |
171
+ | `APIError` | classe mère des erreurs HTTP (`.status`, `.body`) |
172
+ | `APIConnectionError` | réseau, DNS, délai dépassé |
173
+ | `WebhookVerificationError` | signature absente, invalide ou expirée |
174
+
175
+ ## Permissions des clés API
176
+
177
+ | Permission | Méthodes |
178
+ | --------------- | ------------------------------------------------------------------------- |
179
+ | `messages:send` | `messages.send`, `messages.send_media` (WhatsApp) |
180
+ | `sms:send` | `sms.*` et `messages.send(channel="sms")` |
181
+ | `messages:read` | `messages.list`, `messages.poll`, `conversations.*`, `sms.phones` |
@@ -0,0 +1,162 @@
1
+ # sage-messaging (Python)
2
+
3
+ SDK officiel de l'API [Sage Messaging](https://messaging.sagecoders.com) : envoi et lecture de messages WhatsApp et SMS, vérification des webhooks.
4
+
5
+ ```bash
6
+ pip install sage-messaging
7
+ ```
8
+
9
+ Python 3.9+. Client synchrone et asynchrone.
10
+
11
+ ## Démarrage
12
+
13
+ ```python
14
+ from sage_messaging import SageMessaging
15
+
16
+ client = SageMessaging(api_key="sk_...") # ou variable SAGE_MESSAGING_API_KEY
17
+
18
+ # WhatsApp (canal par défaut)
19
+ client.messages.send(phone="+22997000000", message="Bonjour !")
20
+
21
+ # SMS
22
+ client.sms.send(phone="+22997000000", message="Votre code : 4821")
23
+ ```
24
+
25
+ ### Asynchrone
26
+
27
+ ```python
28
+ from sage_messaging import AsyncSageMessaging
29
+
30
+ async with AsyncSageMessaging() as client:
31
+ await client.messages.send(phone="+22997000000", message="Bonjour !")
32
+ ```
33
+
34
+ Les méthodes sont identiques ; il suffit de les `await`.
35
+
36
+ ## Configuration
37
+
38
+ | Paramètre | Variable d'environnement | Défaut |
39
+ | ---------------- | ------------------------------- | --------------------------------- |
40
+ | `api_key` | `SAGE_MESSAGING_API_KEY` | — |
41
+ | `base_url` | `SAGE_MESSAGING_BASE_URL` | `https://messaging.sagecoders.com` |
42
+ | `webhook_secret` | `SAGE_MESSAGING_WEBHOOK_SECRET` | — |
43
+ | `timeout` | | `30` secondes |
44
+ | `max_retries` | | `2` (lectures uniquement) |
45
+
46
+ Les **lectures** (GET) sont rejouées en cas d'erreur réseau, de 429 ou de 5xx. Les **envois ne sont jamais rejoués** : un envoi dont la réponse s'est perdue a pu partir, et le rejouer enverrait le message en double.
47
+
48
+ ## Envoi
49
+
50
+ ```python
51
+ # Message texte, WhatsApp ou SMS
52
+ client.messages.send(phone="+229...", message="Salut", channel="sms")
53
+
54
+ # SMS différé, depuis un téléphone précis
55
+ from datetime import datetime, timedelta, timezone
56
+ client.sms.send(
57
+ phone="+229...",
58
+ message="Rappel : RDV demain",
59
+ from_="+229...", # voir client.sms.phones()
60
+ send_at=datetime.now(timezone.utc) + timedelta(hours=2), # 20 jours max
61
+ )
62
+
63
+ # Campagne SMS (1 à 100 destinataires)
64
+ client.sms.bulk_send(phones=["+229...", "+229..."], message="Promo -20 %")
65
+
66
+ # Médias WhatsApp (1 à 10, 16 Mo max chacun), envoyés dans l'ordre
67
+ res = client.messages.send_media(
68
+ phone="+229...",
69
+ caption="Votre facture",
70
+ media=[
71
+ {"path": "facture.pdf"}, # fichier local
72
+ {"url": "https://exemple.com/photo.jpg"}, # URL publique
73
+ {"data": image_bytes, "filename": "capture.png"}, # octets
74
+ ],
75
+ )
76
+ if res["failed"]: # succès partiel (HTTP 207)
77
+ print("Échecs :", res["failed"])
78
+ ```
79
+
80
+ Utilisez des `datetime` avec fuseau horaire pour `send_at` et `since`.
81
+
82
+ ## Lecture
83
+
84
+ ```python
85
+ client.conversations.list(unread_only=True, limit=20)
86
+ client.conversations.messages(42, direction="received")
87
+ client.conversations.mark_read(42)
88
+
89
+ client.messages.list(after_id=1000) # flux global, id croissant
90
+ ```
91
+
92
+ Les réponses paginées ont la forme `{"data": [...], "meta": {"current_page", "per_page", "total", "last_page"}}`.
93
+
94
+ ### Suivre les nouveaux messages sans webhook
95
+
96
+ ```python
97
+ for msg in client.messages.poll(direction="received", interval=5):
98
+ print(msg["contact_phone"], msg["body"])
99
+ ```
100
+
101
+ Sans `after_id`, seuls les messages arrivés après l'appel sont renvoyés. Pour reprendre après un redémarrage, conservez le dernier `msg["id"]` et passez-le en `after_id`.
102
+
103
+ ## Webhooks
104
+
105
+ Chaque webhook est signé en HMAC-SHA256 (`X-Signature`, `X-Timestamp`). Passez le **corps brut** de la requête, pas un JSON re-sérialisé.
106
+
107
+ ```python
108
+ from sage_messaging import verify_webhook, WebhookVerificationError
109
+
110
+ # FastAPI
111
+ @app.post("/webhooks/sage")
112
+ async def sage_webhook(request: Request):
113
+ try:
114
+ event = verify_webhook(await request.body(), request.headers, SECRET)
115
+ except WebhookVerificationError:
116
+ raise HTTPException(400)
117
+
118
+ if event["event"] == "message.received":
119
+ msg = event["data"]["message"]
120
+ contact = event["data"]["conversation"]
121
+ ...
122
+ return {"ok": True}
123
+ ```
124
+
125
+ Django : `verify_webhook(request.body, request.headers, SECRET)` ; Flask : `verify_webhook(request.get_data(), request.headers, SECRET)`.
126
+
127
+ Les requêtes de plus de 5 minutes sont refusées (`tolerance=300`) pour empêcher leur rejeu.
128
+
129
+ ## Erreurs
130
+
131
+ ```python
132
+ from sage_messaging import ValidationError, GatewayError, SageMessagingError
133
+
134
+ try:
135
+ client.sms.send(phone="+229...", message="...")
136
+ except ValidationError as e: # 422 : champ invalide, canal non provisionné…
137
+ print(e.errors, e.channel)
138
+ except GatewayError as e: # 502 : la passerelle a refusé l'envoi
139
+ print(e.detail)
140
+ except SageMessagingError as e: # toutes les autres erreurs du SDK
141
+ print(e)
142
+ ```
143
+
144
+ | Classe | Cas |
145
+ | ------------------------ | ------------------------------------------------------- |
146
+ | `AuthenticationError` | 401 : clé absente ou invalide |
147
+ | `PermissionDeniedError` | 403 : la clé n'a pas la permission requise |
148
+ | `NotFoundError` | 404 |
149
+ | `ValidationError` | 422 |
150
+ | `RateLimitError` | 429 |
151
+ | `GatewayError` | 502 : refus de WhatsApp ou de la passerelle SMS |
152
+ | `APIError` | classe mère des erreurs HTTP (`.status`, `.body`) |
153
+ | `APIConnectionError` | réseau, DNS, délai dépassé |
154
+ | `WebhookVerificationError` | signature absente, invalide ou expirée |
155
+
156
+ ## Permissions des clés API
157
+
158
+ | Permission | Méthodes |
159
+ | --------------- | ------------------------------------------------------------------------- |
160
+ | `messages:send` | `messages.send`, `messages.send_media` (WhatsApp) |
161
+ | `sms:send` | `sms.*` et `messages.send(channel="sms")` |
162
+ | `messages:read` | `messages.list`, `messages.poll`, `conversations.*`, `sms.phones` |
@@ -0,0 +1,32 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.24"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "sage-messaging"
7
+ version = "0.1.0"
8
+ description = "SDK officiel de l'API Sage Messaging (WhatsApp & SMS)."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ authors = [{ name = "Le Sage Code", email = "angezanou00@gmail.com" }]
12
+ requires-python = ">=3.9"
13
+ keywords = ["sms", "whatsapp", "messaging", "sagecoders", "sdk"]
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "Typing :: Typed",
17
+ "Framework :: AsyncIO",
18
+ ]
19
+ dependencies = [
20
+ "httpx>=0.25,<1",
21
+ "typing_extensions>=4.7; python_version<'3.11'",
22
+ ]
23
+
24
+ [project.optional-dependencies]
25
+ dev = ["pytest>=8", "pytest-asyncio>=0.23"]
26
+
27
+ [tool.hatch.build.targets.wheel]
28
+ packages = ["src/sage_messaging"]
29
+
30
+ [tool.pytest.ini_options]
31
+ asyncio_mode = "auto"
32
+ testpaths = ["tests"]
@@ -0,0 +1,37 @@
1
+ """SDK officiel de l'API Sage Messaging (WhatsApp & SMS)."""
2
+
3
+ from ._async_client import AsyncSageMessaging
4
+ from ._base import DEFAULT_BASE_URL, VERSION
5
+ from ._client import SageMessaging
6
+ from ._errors import (
7
+ APIConnectionError,
8
+ APIError,
9
+ AuthenticationError,
10
+ GatewayError,
11
+ NotFoundError,
12
+ PermissionDeniedError,
13
+ RateLimitError,
14
+ SageMessagingError,
15
+ ValidationError,
16
+ WebhookVerificationError,
17
+ )
18
+ from ._webhooks import verify_webhook
19
+
20
+ __version__ = VERSION
21
+
22
+ __all__ = [
23
+ "SageMessaging",
24
+ "AsyncSageMessaging",
25
+ "verify_webhook",
26
+ "DEFAULT_BASE_URL",
27
+ "SageMessagingError",
28
+ "APIError",
29
+ "AuthenticationError",
30
+ "PermissionDeniedError",
31
+ "NotFoundError",
32
+ "ValidationError",
33
+ "RateLimitError",
34
+ "GatewayError",
35
+ "APIConnectionError",
36
+ "WebhookVerificationError",
37
+ ]