satzet 1.0.0__tar.gz

satzet-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/

satzet-1.0.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: satzet
+Version: 1.0.0
+Summary: Python client for a wadeno-server WhatsApp gateway: sending, consent, broadcasts, schedules and the journal.
+Keywords: api-client,gateway,satzet,whatsapp
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# satzet (Python)
+
+Python client for a [wadeno-server](../..) WhatsApp gateway.
+
+Requires Python 3.10+. **No dependencies** — the standard library's `urllib` is enough for JSON over
+HTTP, and a client this small should not put `requests` in your lockfile.
+
+## Install
+
+While this lives in the gateway's own repository rather than on PyPI:
+
+```bash
+pip install ./wadeno-server/clients/python
+```
+
+Published, it would be the ordinary one line:
+
+```bash
+pip install satzet
+```
+
+## Send a message
+
+```python
+import os
+from satzet import Client
+
+wa = Client("http://localhost:8000", api_key=os.environ["WADENO_SESSION_API_KEY"])
+session = wa.session("default")
+
+sent = session.send_text("628123456789", "Halo, pesanan Anda sudah kami terima.")
+print(sent["id"])
+```
+
+## Per-session API keys
+
+Configure PostgreSQL with `DATABASE_URL` and apply the gateway's database schema. Creating a new
+session automatically issues its own `full` key:
+
+```python
+operator = Client("http://localhost:8000", os.environ["WADENO_API_KEY"])
+created = operator.create_session("orders")
+if "apiKey" not in created:
+    raise RuntimeError("Configure PostgreSQL to issue session keys")
+
+# Save this secret in your integration's secret store now. It is shown only once.
+integration = Client("http://localhost:8000", created["apiKey"]["secret"])
+orders = integration.session(created["session"]["id"])
+orders.status()
+```
+
+For an existing session, sign in before creating or managing keys:
+
+```python
+operator.login(os.environ["WADENO_USERNAME"], os.environ["WADENO_PASSWORD"])
+orders_admin = operator.session("orders")
+issued = orders_admin.create_api_key("Orders SDK")  # scope defaults to full
+integration = Client("http://localhost:8000", issued["secret"])
+integration.session("orders").status()
+
+metadata = orders_admin.api_keys()  # no secret or hash in this response
+orders_admin.revoke_api_key(issued["key"]["id"])  # this key stops working immediately
+```
+
+Save `issued["secret"]` securely; the database stores its SHA-256 hash and cannot reveal the secret
+again. Keys only access their own session, including WhatsApp and Telegram routes; another session
+raises `AuthError`. An integration key alone cannot manage keys. Use
+`create_api_key("MCP integration", "mcp")` for MCP access without sending; `full` permits sending
+subject to the usual consent and outbound rules. A session can have three live keys. Revoking one
+frees a slot.
+
+## Read this before your first send
+
+**This gateway will not message somebody who has never written to it.** That refusal is not a bug
+and not a configuration mistake — it is the whole reason the number does not get banned. Bans come
+from user reports, and reports come from unsolicited contact.
+
+For a recipient who agreed somewhere else — a signup form, an order, somebody who handed over their
+number — vouch for them first:
+
+```python
+session.consent("628123456789")          # records the agreement
+session.send_text("628123456789", "Halo!")
+```
+
+There is no bulk version of `consent()`, deliberately, and first contacts are held to roughly ten a
+day. Three hundred leads is a month of outreach. That is the feature working.
+
+## Handling refusals
+
+A send can fail in ways that are not errors in your code, and the right response differs by which:
+
+```python
+import time
+from satzet import GateError
+
+try:
+    session.send_text(phone, text)
+except GateError as error:
+    if error.deferred:
+        # 429. Temporary — your number is out of quota, parked, or being paced.
+        time.sleep(error.retry_after_ms / 1000)
+    elif error.about_recipient:
+        # 422 `no-consent`. This one person. The next recipient may be fine.
+        pass
+    else:
+        # 422 about the TEXT, or a refusal about the number. Retrying will not help.
+        raise
+```
+
+Looping over many recipients, `should_stop_batch` answers that in one attribute — it applies the
+same rule the gateway's own broadcast queue does:
+
+```python
+for phone in recipients:
+    try:
+        session.send_text(phone, text)
+    except GateError as error:
+        if error.should_stop_batch:
+            break        # about the number or the text: everybody left gets the same refusal
+        continue         # about this person: skip them
+```
+
+Better still, hand the list to the gateway and let it pace itself:
+
+```python
+job = session.broadcast(recipients, text)
+progress = session.broadcast_job(job["id"])
+```
+
+## The exceptions
+
+| Class                | When                                                                    |
+| -------------------- | ----------------------------------------------------------------------- |
+| `GateError`          | 422/429 — the safety policy refused. The one to write code against.     |
+| `AuthError`          | 401 (unrecognised key) / 403 (valid key, wrong place)                   |
+| `ConflictError`      | 409 — not connected, broadcast already running, schedule already sent   |
+| `NotConfiguredError` | 501 — the feature has no key or no database on this install             |
+| `SATZETError`        | everything else, including a gateway nobody could reach (`status` 0)    |
+
+All of them carry `status`, `code` and the decoded `body`. **Branch on `code`, never on the
+message** — the prose is written for a person and will be reworded.
+
+## Anything not wrapped
+
+The gateway has around a hundred routes; this library wraps the ones people actually call. The rest
+is one line away, with the same authentication and the same error translation:
+
+```python
+leads = wa.request("GET", "/v1/sessions/default/leads", query={"status": "new"})
+session.call("POST", "/status/text", {"text": "Buka sampai jam 9"})
+```
+
+See [`openapi.yaml`](../../openapi.yaml) for every route.
+
+## Autopilot needs a person
+
+Turning on automatic replies is refused for an API key however wide its scope, and switching it on
+means echoing back an acknowledgement version that only `autopilot()` hands out — so a client cannot
+agree to consequences it was never shown:
+
+```python
+wa.login("operator", password)
+
+state = session.autopilot()
+session.set_autopilot(
+    enabled=True,
+    persona="Admin toko, ramah, jawab singkat.",
+    dailyReplyCap=20,
+    acknowledge={"version": state["consent"]["version"]},
+)
+```
+
+Set the cap low on day one and read the first twenty replies before trusting it with a second
+number.
+
+## Tests
+
+Seventeen tests against a stub gateway, including key issuance, revocation, and session credentials:
+
+```bash
+python -m unittest discover -s tests -v
+```

satzet-1.0.0/README.md

@@ -0,0 +1,183 @@
+# satzet (Python)
+
+Python client for a [wadeno-server](../..) WhatsApp gateway.
+
+Requires Python 3.10+. **No dependencies** — the standard library's `urllib` is enough for JSON over
+HTTP, and a client this small should not put `requests` in your lockfile.
+
+## Install
+
+While this lives in the gateway's own repository rather than on PyPI:
+
+```bash
+pip install ./wadeno-server/clients/python
+```
+
+Published, it would be the ordinary one line:
+
+```bash
+pip install satzet
+```
+
+## Send a message
+
+```python
+import os
+from satzet import Client
+
+wa = Client("http://localhost:8000", api_key=os.environ["WADENO_SESSION_API_KEY"])
+session = wa.session("default")
+
+sent = session.send_text("628123456789", "Halo, pesanan Anda sudah kami terima.")
+print(sent["id"])
+```
+
+## Per-session API keys
+
+Configure PostgreSQL with `DATABASE_URL` and apply the gateway's database schema. Creating a new
+session automatically issues its own `full` key:
+
+```python
+operator = Client("http://localhost:8000", os.environ["WADENO_API_KEY"])
+created = operator.create_session("orders")
+if "apiKey" not in created:
+    raise RuntimeError("Configure PostgreSQL to issue session keys")
+
+# Save this secret in your integration's secret store now. It is shown only once.
+integration = Client("http://localhost:8000", created["apiKey"]["secret"])
+orders = integration.session(created["session"]["id"])
+orders.status()
+```
+
+For an existing session, sign in before creating or managing keys:
+
+```python
+operator.login(os.environ["WADENO_USERNAME"], os.environ["WADENO_PASSWORD"])
+orders_admin = operator.session("orders")
+issued = orders_admin.create_api_key("Orders SDK")  # scope defaults to full
+integration = Client("http://localhost:8000", issued["secret"])
+integration.session("orders").status()
+
+metadata = orders_admin.api_keys()  # no secret or hash in this response
+orders_admin.revoke_api_key(issued["key"]["id"])  # this key stops working immediately
+```
+
+Save `issued["secret"]` securely; the database stores its SHA-256 hash and cannot reveal the secret
+again. Keys only access their own session, including WhatsApp and Telegram routes; another session
+raises `AuthError`. An integration key alone cannot manage keys. Use
+`create_api_key("MCP integration", "mcp")` for MCP access without sending; `full` permits sending
+subject to the usual consent and outbound rules. A session can have three live keys. Revoking one
+frees a slot.
+
+## Read this before your first send
+
+**This gateway will not message somebody who has never written to it.** That refusal is not a bug
+and not a configuration mistake — it is the whole reason the number does not get banned. Bans come
+from user reports, and reports come from unsolicited contact.
+
+For a recipient who agreed somewhere else — a signup form, an order, somebody who handed over their
+number — vouch for them first:
+
+```python
+session.consent("628123456789")          # records the agreement
+session.send_text("628123456789", "Halo!")
+```
+
+There is no bulk version of `consent()`, deliberately, and first contacts are held to roughly ten a
+day. Three hundred leads is a month of outreach. That is the feature working.
+
+## Handling refusals
+
+A send can fail in ways that are not errors in your code, and the right response differs by which:
+
+```python
+import time
+from satzet import GateError
+
+try:
+    session.send_text(phone, text)
+except GateError as error:
+    if error.deferred:
+        # 429. Temporary — your number is out of quota, parked, or being paced.
+        time.sleep(error.retry_after_ms / 1000)
+    elif error.about_recipient:
+        # 422 `no-consent`. This one person. The next recipient may be fine.
+        pass
+    else:
+        # 422 about the TEXT, or a refusal about the number. Retrying will not help.
+        raise
+```
+
+Looping over many recipients, `should_stop_batch` answers that in one attribute — it applies the
+same rule the gateway's own broadcast queue does:
+
+```python
+for phone in recipients:
+    try:
+        session.send_text(phone, text)
+    except GateError as error:
+        if error.should_stop_batch:
+            break        # about the number or the text: everybody left gets the same refusal
+        continue         # about this person: skip them
+```
+
+Better still, hand the list to the gateway and let it pace itself:
+
+```python
+job = session.broadcast(recipients, text)
+progress = session.broadcast_job(job["id"])
+```
+
+## The exceptions
+
+| Class                | When                                                                    |
+| -------------------- | ----------------------------------------------------------------------- |
+| `GateError`          | 422/429 — the safety policy refused. The one to write code against.     |
+| `AuthError`          | 401 (unrecognised key) / 403 (valid key, wrong place)                   |
+| `ConflictError`      | 409 — not connected, broadcast already running, schedule already sent   |
+| `NotConfiguredError` | 501 — the feature has no key or no database on this install             |
+| `SATZETError`        | everything else, including a gateway nobody could reach (`status` 0)    |
+
+All of them carry `status`, `code` and the decoded `body`. **Branch on `code`, never on the
+message** — the prose is written for a person and will be reworded.
+
+## Anything not wrapped
+
+The gateway has around a hundred routes; this library wraps the ones people actually call. The rest
+is one line away, with the same authentication and the same error translation:
+
+```python
+leads = wa.request("GET", "/v1/sessions/default/leads", query={"status": "new"})
+session.call("POST", "/status/text", {"text": "Buka sampai jam 9"})
+```
+
+See [`openapi.yaml`](../../openapi.yaml) for every route.
+
+## Autopilot needs a person
+
+Turning on automatic replies is refused for an API key however wide its scope, and switching it on
+means echoing back an acknowledgement version that only `autopilot()` hands out — so a client cannot
+agree to consequences it was never shown:
+
+```python
+wa.login("operator", password)
+
+state = session.autopilot()
+session.set_autopilot(
+    enabled=True,
+    persona="Admin toko, ramah, jawab singkat.",
+    dailyReplyCap=20,
+    acknowledge={"version": state["consent"]["version"]},
+)
+```
+
+Set the cap low on day one and read the first twenty replies before trusting it with a second
+number.
+
+## Tests
+
+Seventeen tests against a stub gateway, including key issuance, revocation, and session credentials:
+
+```bash
+python -m unittest discover -s tests -v
+```

satzet-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "satzet"
+version = "1.0.0"
+description = "Python client for a wadeno-server WhatsApp gateway: sending, consent, broadcasts, schedules and the journal."
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["whatsapp", "satzet", "gateway", "api-client"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Communications :: Chat",
+]
+# No dependencies, deliberately: urllib is enough for JSON over HTTP, and a client this small
+# should not drag `requests` into somebody's lockfile.
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["satzet"]

satzet-1.0.0/satzet/__init__.py

@@ -0,0 +1,34 @@
+"""Python client for a wadeno-server WhatsApp gateway.
+
+    from satzet import Client
+
+    wa = Client("http://localhost:8000", api_key=os.environ["WADENO_API_KEY"])
+    wa.session("default").send_text("628123456789", "halo")
+
+READ THIS BEFORE YOUR FIRST SEND. This gateway will not message somebody who has never written to
+it — that refusal is the whole reason the number does not get banned. `Session.consent(to)` is how
+you vouch for a recipient who signed up elsewhere, and first contacts are held to roughly ten a
+day. See `GateError` for what to do about each kind of refusal.
+"""
+
+from .client import Client, Session
+from .errors import (
+    AuthError,
+    ConflictError,
+    GateError,
+    NotConfiguredError,
+    SATZETError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Client",
+    "Session",
+    "SATZETError",
+    "GateError",
+    "AuthError",
+    "ConflictError",
+    "NotConfiguredError",
+    "__version__",
+]