plasgos-crm-sdk 2.0.0__tar.gz

plasgos_crm_sdk-2.0.0/.gitignore

@@ -0,0 +1,28 @@
+# Node
+node_modules/
+packages/node/dist/
+*.tsbuildinfo
+npm-debug.log*
+*.tgz
+
+# PHP
+packages/php/vendor/
+packages/php/composer.lock
+.phpunit.result.cache
+.phpunit.cache/
+.phpstan-cache/
+
+# Python
+packages/python/dist/
+packages/python/build/
+packages/python/.venv/
+packages/python/*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

plasgos_crm_sdk-2.0.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this package are documented here.
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [2.0.0] - 2026-10-27
+
+### API contract 3.0.0-rc.2
+- One `contact` object names "who" in `messages.send`, `leads.create` and `followups.enroll`: `{id}` | `{phone_number, …profile}` | `{channel, external_id}` | `{email}` (replaces `recipient` + `identity` + `create_contact`, and `contact_id` | `contact`). Profile fields only fill a NEW contact. `send-options` / `lookup` queries use the same keys (`send-options` also accepts `email`).
+- `meta.created` everywhere (contact upsert: replaces `meta.operation`; message send: `true`).
+- Malformed `contact` → `422 validation_failed` with field code `invalid_contact`. Error catalog: `components.x-error-codes` in `openapi/openapi-v3.json`.
+
+### Fixed
+- `409 idempotency_in_progress` is retried with the same Idempotency-Key (the first request is still running, e.g. after a client-side timeout); other 409s such as `identity_taken` are still raised.
+- Lint rules pinned explicitly (`[tool.ruff.lint] select`): newer ruff versions widened the default rule set and broke CI without any code change.
+
+### Added
+- `AsyncClient` for `asyncio` (`httpx.AsyncClient`): same resources, methods and parameters as `Client` (checked by a parity test), `AsyncPage` with `await next_page()` and `async for … in auto_paging()`, `async with` / `aclose()`. Signing, idempotency, retry policy and logging are shared with the sync client.
+- DEBUG logging on the `plasgos_crm` stdlib logger (docs/SDK_SPEC.md §1.2): one record per attempt with method, path (no query), status, duration, request id, error code and retry wait (also in `record.plasgos_crm`); never headers or bodies.
+- Per-call options (`options=RequestOptions`, docs/SDK_SPEC.md §1.1), keyword-only on every resource method and `client.request()`: `timeout`, `max_retries`, `headers`. Next pages of `auto_paging()` keep them. Headers the SDK owns (signing, `Idempotency-Key`, `Content-Type`, …) are rejected.
+- Types generated from `openapi/openapi-v3.json` (`scripts/generate-types.mjs`, checked in CI): `plasgos_crm.v3.types` (`TypedDict` per schema, plus `…Body`, `…Query`, `…Data`, `…Item`, `…Meta` per operation); `ApiResponse` is generic (`ApiResponse[Contact]`), every resource method is typed, and `Content.text()` / `media()` / `TemplateContent.to_dict()` return the matching `TypedDict`.
+- `Client` for **API Integrasi v3** (`/api/v3`), same contract as the PHP and Node SDK 2.0
+  (docs/SDK_SPEC.md):
+  - Resources: `me`, `channels`, `endpoints` (including templates), `template_variables`,
+    `messages` (omnichannel, `send_options`), `contacts` (including upsert and lookup),
+    `contact_groups`, `pipelines`, `leads`, `broadcasts`, `followups` (enrol and unenrol),
+    `webhooks` (including `rotate_secret`), plus `client.request()`.
+  - Request signing covers the method, path, query and body (`Plasgos-*` headers); exported as
+    `sign_v3`, `signature_headers_v3`, `string_to_sign`.
+  - An automatic `Idempotency-Key` on POST, reused across retries; retry policy of §6
+    (`max_retries`, `max_retry_wait`, injectable `sleeper`/`clock`).
+  - `ApiResponse`, `RateLimit` and `Page` (`auto_paging()` generator).
+  - `Content` / `TemplateContent` builders (`location()` for LOCATION-header templates).
+  - `Webhook.verify()` (HMAC, secret rotation with two signatures; any header mapping including
+    WSGI `environ`) and `WebhookEventType`.
+- `ChannelError` (502) and `ServiceUnavailableError` (503), both `ServerError`.
+- v3 error fields on every error: `error_code`, `error_type`, `details`, `fields`, `doc_url`,
+  `retry_after`; `error_from_v3()`.
+- Optional live test (`tests/test_v3_live.py`, `PLASGOS_LIVE_*`).
+
+### Changed (breaking)
+- The v1 client is now `LegacyClient` (`PlasgosCrmClient` stays as a deprecated alias until 3.0)
+  and emits a `DeprecationWarning` when constructed; its documentation moved to `LEGACY_V1.md`.
+- `SignatureExpiredError` now extends `AuthenticationError` (v3 reports clock skew as 401).
+- The legacy `x-hub-token` helper `verify_webhook` is v1-only; v3 deliveries use `Webhook.verify()`.
+
+## [1.0.0] - 2026-09-03
+
+### Added
+- Initial release: signed API client, credential-management client, webhook
+  verification, typed errors, normalised response envelope.

plasgos_crm_sdk-2.0.0/LEGACY_V1.md

@@ -0,0 +1,137 @@
+# plasgos-crm-sdk (Python) — LEGACY v1 client (`/api/v1`)
+
+> **Deprecated.** This documents the 1.x API (`PlasgosCrmClient`, now `LegacyClient`). New code should use
+> the API v3 `Client` — see [README.md](README.md). Removed in 3.0.
+
+
+Official Python SDK for the **Plasgos CRM — Api Integration** API.
+
+- One dependency (`httpx`).
+- Automatic HMAC request signing.
+- Normalised response envelope, typed exceptions.
+- Webhook verification helper.
+- Separate client for the credential-management endpoints.
+
+## Install
+
+```bash
+pip install plasgos-crm-sdk
+```
+
+## Quick start (signed API)
+
+```python
+from plasgos_crm import LegacyClient
+
+client = LegacyClient(
+    api_key="...",
+    secret_key="...",
+    base_url="production",  # "production" | "sandbox" | absolute URL
+)
+
+env = client.messages.send(
+    channel="whatsapp",
+    account_id="665f1c2e9a1b2c3d4e5f6a7b",
+    receiver={"phone_number": "628123456789", "name": "John Doe"},
+    content={"type": "text", "data": {"text": "Halo dari SDK"}},
+)
+print(env.metadata["message_id"], env.data)
+
+accounts = client.accounts.list()
+
+client.official.messages.send_template(
+    phone_number_id="123456789012345",
+    to="6281234567890",
+    template={
+        "id": "1234567890123456",
+        "name": "order_update_v1",
+        "category": "UTILITY",
+        "parameters": {"variables": [{"type": "custom", "name": "1", "value": "Budi"}]},
+    },
+)
+
+client.close()  # or: with LegacyClient(...) as client: ...
+```
+
+Every call returns an `Envelope`:
+
+```python
+@dataclass(frozen=True)
+class Envelope:
+    status: int | bool
+    message: str | None
+    data: Any
+    metadata: dict
+    raw: Any
+    http_status: int
+```
+
+## Errors
+
+```python
+from plasgos_crm import ValidationError, RateLimitError, SignatureExpiredError
+
+try:
+    client.messages.send(...)
+except ValidationError as e:
+    print(e.errors)
+except RateLimitError:
+    ...
+except SignatureExpiredError:
+    ...  # local clock skew vs. server
+```
+
+Hierarchy: `PlasgosApiError` → `AuthenticationError`, `PermissionError`
+(`PlanError`), `NotFoundError`, `SignatureExpiredError`, `ConflictError`,
+`ValidationError`, `BadRequestError`, `RateLimitError`, `ServerError`,
+`TransportError`.
+
+> An un-approved API key can surface as HTTP 500 (`ServerError`) with a message
+> containing `"You don't have permission"` — a known server quirk.
+
+## Credential management (`/v2/integration/*`)
+
+```python
+from plasgos_crm import PlasgosCrmCredentialsClient
+
+creds = PlasgosCrmCredentialsClient(access_token, fingerprint, base_url="production")
+creds.credentials.request()
+current = creds.credentials.get()
+creds.credentials.regenerate()
+creds.credentials.subscribe_webhook(
+    webhook_url="https://your.app/webhooks/plasgos",
+    verify_token="a-shared-secret",
+)
+```
+
+## Webhooks
+
+```python
+from plasgos_crm import verify_webhook, MESSAGE_RECEIVED
+
+event = verify_webhook(request.headers, raw_body, expected_token="a-shared-secret")
+if event["event"] == MESSAGE_RECEIVED:
+    ...
+```
+
+`verify_webhook` compares the `x-hub-token` header (constant-time) and parses
+the JSON body. There is no payload HMAC.
+
+## Configuration
+
+| Argument | Default | |
+|---|---|---|
+| `base_url` | `"production"` | `"production"`, `"sandbox"`, or an absolute URL |
+| `timeout` | `15.0` | seconds |
+| `max_retries` | `2` | idempotent GET only; network / 5xx / 429 |
+| `user_agent` | `plasgos-crm-sdk-python/<version>` | |
+| `transport` / `http_client` | — | inject `httpx.MockTransport` / `httpx.Client` for tests |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy src
+ruff check .
+```

plasgos_crm_sdk-2.0.0/LICENSE

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

plasgos_crm_sdk-2.0.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: plasgos-crm-sdk
+Version: 2.0.0
+Summary: Official Python SDK for the Plasgos CRM Api Integration API.
+Project-URL: Homepage, https://github.com/plasgos/plasgos-crm-sdk/tree/main/packages/python
+Project-URL: Source, https://github.com/plasgos/plasgos-crm-sdk
+Author: Plasgos
+License: MIT
+License-File: LICENSE
+Keywords: api,crm,plasgos,sdk,waba,whatsapp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# plasgos-crm-sdk (Python)
+
+Official Python SDK for **Plasgos CRM: API Integrasi v3**. The SDK covers:
+
+- omnichannel messages (WhatsApp official and unofficial, Instagram, Messenger)
+- contacts and leads
+- broadcasts
+- followups
+- signed webhooks
+
+Features:
+
+- Python 3.9+, one dependency (`httpx`), fully typed (`py.typed`, mypy strict).
+- Automatic request signing that covers the method, path, query and body.
+- An automatic `Idempotency-Key` on every POST, reused on retries.
+- Typed errors carrying the API `error_code`.
+- A `Page` type with `auto_paging()`.
+- Webhook HMAC verification.
+
+> Upgrading from 1.x? See [UPGRADING.md](../../UPGRADING.md). The v1 client lives on as the
+> deprecated `LegacyClient` (`PlasgosCrmClient` is an alias); its docs are in [LEGACY_V1.md](LEGACY_V1.md).
+
+## Install
+
+```bash
+pip install plasgos-crm-sdk
+```
+
+## Quick start
+
+```python
+import os
+
+from plasgos_crm import Client, Content, PlasgosApiError
+
+with Client(
+    os.environ["PLASGOS_API_KEY"],
+    os.environ["PLASGOS_SECRET_KEY"],
+    base_url="sandbox",  # "production" by default; or an absolute URL
+) as client:
+    me = client.me.get()
+    print(me.data["tenant"]["name"])
+
+    try:
+        sent = client.messages.send(
+            {
+                "endpoint_id": "6281100000001",
+                "contact": {"phone_number": "081234567890", "name": "Budi Santoso"},  # profile only for a NEW contact
+                "content": Content.template("66f1a2b3c4d5e6f708192a3b")
+                .dynamic("name", "{{full_name}}")
+                .custom("order", "INV-2026-0917"),
+            },
+            idempotency_key="wc-1234-processing",  # one per intent
+        )
+        print(sent.data["status"])  # pending | sent | failed (202)
+    except PlasgosApiError as error:
+        # Branch on the stable code; show error.message (Indonesian) to people.
+        if error.error_code == "requires_template":
+            ...
+        raise
+
+    for contact in client.contacts.list(per_page=100).auto_paging():
+        ...  # every page fetched lazily
+
+    client.contacts.upsert({"phone_number": "081234567890", "name": "Budi", "tags": ["woocommerce"]})
+    client.leads.create({"contact": {"phone_number": "081234567890"}, "pipeline_id": "pl_1"})
+    client.followups.enroll("fu_1", {"contact": {"id": "ct_1"}})
+```
+
+### asyncio
+
+`AsyncClient` has the same resources, methods and parameters (each method is `async`; lists return an
+`AsyncPage`):
+
+```python
+from plasgos_crm import AsyncClient
+
+async with AsyncClient(api_key, secret_key, base_url="sandbox") as client:
+    me = await client.me.get()
+    page = await client.contacts.list(per_page=100)
+    async for contact in page.auto_paging():
+        ...
+```
+
+It takes an `httpx.AsyncBaseTransport` / `httpx.AsyncClient` and an async `sleeper`; close it with
+`async with` or `await client.aclose()`.
+
+Resources:
+
+- `me`, `channels`
+- `endpoints` (including `templates`), `template_variables`
+- `messages` (`send_options`, `send`, `get`)
+- `contacts`, `contact_groups`
+- `pipelines`, `leads`
+- `broadcasts`, `followups`
+- `webhooks` (including `rotate_secret`)
+
+Query parameters may be a mapping, keyword arguments, or both:
+`client.contacts.list({"tag": "vip"}, per_page=100)`.
+`client.request(method, path, query=None, body=None, idempotency_key=None, *, options=None)` is an escape hatch for
+endpoints that do not have a method yet. The full surface is in
+[docs/SDK_SPEC.md](../../docs/SDK_SPEC.md) §3. Inputs and outputs use the API wire format
+(snake_case), described by [openapi/openapi-v3.json](../../openapi/openapi-v3.json).
+
+## Options
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `base_url` | `"production"` | `"production"`, `"sandbox"`, or an absolute URL (host only). |
+| `timeout` | `15.0` s | Timeout for each attempt. |
+| `max_retries` | `2` | Automatic retries (see below). |
+| `max_retry_wait` | `30.0` s | Longest `Retry-After` honoured automatically. |
+| `user_agent` | `plasgos-crm-sdk-python/<version> python/<version>` | Integrations append themselves. |
+| `transport` / `http_client` | — | Inject an `httpx` transport (e.g. `httpx.MockTransport`) or your own `httpx.Client`. |
+| `sleeper`, `clock` | real | Test hooks. |
+
+Logging: enable DEBUG on the `plasgos_crm` logger for one record per attempt (method, path without
+the query, status, duration, request id); headers and bodies are never logged.
+
+Every method also takes keyword-only per-call options (docs/SDK_SPEC.md §1.1):
+
+```python
+client.messages.send(body, "wc-1234-processing", options={"timeout": 5, "max_retries": 0})
+client.contacts.get(contact_id, options={"headers": {"X-Trace-Id": trace_id}})
+```
+
+## Responses
+
+```python
+r.http_status  # 200, 201, 202 …
+r.message      # user-facing text
+r.data         # payload
+r.meta         # e.g. {"created": True} (201) / {"created": False} (200)
+r.request_id   # quote it when contacting Plasgos
+r.rate_limit   # RateLimit(limit=120, remaining=119, reset=42)
+r.replayed     # True when the server replayed the first response for this Idempotency-Key
+```
+
+List methods return a `Page`: `items`, `pagination`, `has_next_page()`, `next_page()`,
+`auto_paging()` (generator); it is iterable over the current page and supports `len()`.
+
+Request bodies, query parameters and `data` are typed with `TypedDict`s generated from the OpenAPI spec
+(checked by mypy/pyright; plain dicts at runtime):
+
+```python
+from plasgos_crm.v3 import types as t
+
+sent = client.messages.send({"endpoint_id": "…", "contact": {"phone_number": "0812…"}, "content": Content.text("Halo")})
+status: t.MessageStatus = sent.data["status"]
+page = client.contacts.list({"tag": "vip"})  # Page[t.Contact]
+```
+
+## Errors
+
+```
+PlasgosApiError
+├─ AuthenticationError            401
+│  └─ SignatureExpiredError       401 signature_expired (check the server clock)
+├─ PermissionError                403 (scope_missing, api_key_revoked, …)
+│  └─ PlanError                   403 not_entitled
+├─ NotFoundError                  404
+├─ ConflictError                  409 (idempotency_in_progress, identity_taken, …)
+├─ BadRequestError                400
+├─ ValidationError                422 / 400 with fields → .fields
+├─ RateLimitError                 429 → .retry_after (rate_limited | daily_quota_exceeded)
+├─ ServerError                    5xx
+│  ├─ ChannelError                502 provider error
+│  └─ ServiceUnavailableError     503
+└─ TransportError                 no response
+```
+
+Every error exposes `error_code`, `error_type`, `details`, `fields`, `doc_url`, `request_id` and
+`retry_after` (plus the legacy `errors` view `[{message, path}]`). `PermissionError` deliberately
+shadows the builtin inside this package; import it as `from plasgos_crm import PermissionError as
+PlasgosPermissionError` if that bothers you.
+
+**Retries.** Transport errors, 502/503 and `rate_limited` (for any method) are retried
+automatically up to `max_retries`, reusing the same idempotency key. A plain 500 is retried only for
+GET. Other 4xx errors and `daily_quota_exceeded` are never retried.
+
+## Webhooks
+
+```python
+from plasgos_crm import Webhook, WebhookEventType, WebhookVerificationError
+
+# Flask
+@app.post("/webhooks/plasgos")
+def plasgos_webhook():
+    try:
+        event = Webhook.verify(request.get_data(), request.headers, signing_secret)
+        # during secret rotation: Webhook.verify(body, headers, [new_secret, previous_secret])
+    except WebhookVerificationError:
+        return "", 401
+    if event["type"] == WebhookEventType.MESSAGE_RECEIVED:
+        ...  # event["data"] is a Message
+    return "", 200
+```
+
+`headers` may be any mapping, including a WSGI `environ` or Django `request.META` (`HTTP_*` keys).
+Verify the **raw** body. Deliveries can repeat, so drop `event["id"]` values you have already
+processed.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest              # tests/test_v3_live.py runs only with PLASGOS_LIVE_BASE_URL/_API_KEY/_SECRET_KEY
+mypy src
+ruff check .
+```

plasgos_crm_sdk-2.0.0/README.md

@@ -0,0 +1,210 @@
+# plasgos-crm-sdk (Python)
+
+Official Python SDK for **Plasgos CRM: API Integrasi v3**. The SDK covers:
+
+- omnichannel messages (WhatsApp official and unofficial, Instagram, Messenger)
+- contacts and leads
+- broadcasts
+- followups
+- signed webhooks
+
+Features:
+
+- Python 3.9+, one dependency (`httpx`), fully typed (`py.typed`, mypy strict).
+- Automatic request signing that covers the method, path, query and body.
+- An automatic `Idempotency-Key` on every POST, reused on retries.
+- Typed errors carrying the API `error_code`.
+- A `Page` type with `auto_paging()`.
+- Webhook HMAC verification.
+
+> Upgrading from 1.x? See [UPGRADING.md](../../UPGRADING.md). The v1 client lives on as the
+> deprecated `LegacyClient` (`PlasgosCrmClient` is an alias); its docs are in [LEGACY_V1.md](LEGACY_V1.md).
+
+## Install
+
+```bash
+pip install plasgos-crm-sdk
+```
+
+## Quick start
+
+```python
+import os
+
+from plasgos_crm import Client, Content, PlasgosApiError
+
+with Client(
+    os.environ["PLASGOS_API_KEY"],
+    os.environ["PLASGOS_SECRET_KEY"],
+    base_url="sandbox",  # "production" by default; or an absolute URL
+) as client:
+    me = client.me.get()
+    print(me.data["tenant"]["name"])
+
+    try:
+        sent = client.messages.send(
+            {
+                "endpoint_id": "6281100000001",
+                "contact": {"phone_number": "081234567890", "name": "Budi Santoso"},  # profile only for a NEW contact
+                "content": Content.template("66f1a2b3c4d5e6f708192a3b")
+                .dynamic("name", "{{full_name}}")
+                .custom("order", "INV-2026-0917"),
+            },
+            idempotency_key="wc-1234-processing",  # one per intent
+        )
+        print(sent.data["status"])  # pending | sent | failed (202)
+    except PlasgosApiError as error:
+        # Branch on the stable code; show error.message (Indonesian) to people.
+        if error.error_code == "requires_template":
+            ...
+        raise
+
+    for contact in client.contacts.list(per_page=100).auto_paging():
+        ...  # every page fetched lazily
+
+    client.contacts.upsert({"phone_number": "081234567890", "name": "Budi", "tags": ["woocommerce"]})
+    client.leads.create({"contact": {"phone_number": "081234567890"}, "pipeline_id": "pl_1"})
+    client.followups.enroll("fu_1", {"contact": {"id": "ct_1"}})
+```
+
+### asyncio
+
+`AsyncClient` has the same resources, methods and parameters (each method is `async`; lists return an
+`AsyncPage`):
+
+```python
+from plasgos_crm import AsyncClient
+
+async with AsyncClient(api_key, secret_key, base_url="sandbox") as client:
+    me = await client.me.get()
+    page = await client.contacts.list(per_page=100)
+    async for contact in page.auto_paging():
+        ...
+```
+
+It takes an `httpx.AsyncBaseTransport` / `httpx.AsyncClient` and an async `sleeper`; close it with
+`async with` or `await client.aclose()`.
+
+Resources:
+
+- `me`, `channels`
+- `endpoints` (including `templates`), `template_variables`
+- `messages` (`send_options`, `send`, `get`)
+- `contacts`, `contact_groups`
+- `pipelines`, `leads`
+- `broadcasts`, `followups`
+- `webhooks` (including `rotate_secret`)
+
+Query parameters may be a mapping, keyword arguments, or both:
+`client.contacts.list({"tag": "vip"}, per_page=100)`.
+`client.request(method, path, query=None, body=None, idempotency_key=None, *, options=None)` is an escape hatch for
+endpoints that do not have a method yet. The full surface is in
+[docs/SDK_SPEC.md](../../docs/SDK_SPEC.md) §3. Inputs and outputs use the API wire format
+(snake_case), described by [openapi/openapi-v3.json](../../openapi/openapi-v3.json).
+
+## Options
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `base_url` | `"production"` | `"production"`, `"sandbox"`, or an absolute URL (host only). |
+| `timeout` | `15.0` s | Timeout for each attempt. |
+| `max_retries` | `2` | Automatic retries (see below). |
+| `max_retry_wait` | `30.0` s | Longest `Retry-After` honoured automatically. |
+| `user_agent` | `plasgos-crm-sdk-python/<version> python/<version>` | Integrations append themselves. |
+| `transport` / `http_client` | — | Inject an `httpx` transport (e.g. `httpx.MockTransport`) or your own `httpx.Client`. |
+| `sleeper`, `clock` | real | Test hooks. |
+
+Logging: enable DEBUG on the `plasgos_crm` logger for one record per attempt (method, path without
+the query, status, duration, request id); headers and bodies are never logged.
+
+Every method also takes keyword-only per-call options (docs/SDK_SPEC.md §1.1):
+
+```python
+client.messages.send(body, "wc-1234-processing", options={"timeout": 5, "max_retries": 0})
+client.contacts.get(contact_id, options={"headers": {"X-Trace-Id": trace_id}})
+```
+
+## Responses
+
+```python
+r.http_status  # 200, 201, 202 …
+r.message      # user-facing text
+r.data         # payload
+r.meta         # e.g. {"created": True} (201) / {"created": False} (200)
+r.request_id   # quote it when contacting Plasgos
+r.rate_limit   # RateLimit(limit=120, remaining=119, reset=42)
+r.replayed     # True when the server replayed the first response for this Idempotency-Key
+```
+
+List methods return a `Page`: `items`, `pagination`, `has_next_page()`, `next_page()`,
+`auto_paging()` (generator); it is iterable over the current page and supports `len()`.
+
+Request bodies, query parameters and `data` are typed with `TypedDict`s generated from the OpenAPI spec
+(checked by mypy/pyright; plain dicts at runtime):
+
+```python
+from plasgos_crm.v3 import types as t
+
+sent = client.messages.send({"endpoint_id": "…", "contact": {"phone_number": "0812…"}, "content": Content.text("Halo")})
+status: t.MessageStatus = sent.data["status"]
+page = client.contacts.list({"tag": "vip"})  # Page[t.Contact]
+```
+
+## Errors
+
+```
+PlasgosApiError
+├─ AuthenticationError            401
+│  └─ SignatureExpiredError       401 signature_expired (check the server clock)
+├─ PermissionError                403 (scope_missing, api_key_revoked, …)
+│  └─ PlanError                   403 not_entitled
+├─ NotFoundError                  404
+├─ ConflictError                  409 (idempotency_in_progress, identity_taken, …)
+├─ BadRequestError                400
+├─ ValidationError                422 / 400 with fields → .fields
+├─ RateLimitError                 429 → .retry_after (rate_limited | daily_quota_exceeded)
+├─ ServerError                    5xx
+│  ├─ ChannelError                502 provider error
+│  └─ ServiceUnavailableError     503
+└─ TransportError                 no response
+```
+
+Every error exposes `error_code`, `error_type`, `details`, `fields`, `doc_url`, `request_id` and
+`retry_after` (plus the legacy `errors` view `[{message, path}]`). `PermissionError` deliberately
+shadows the builtin inside this package; import it as `from plasgos_crm import PermissionError as
+PlasgosPermissionError` if that bothers you.
+
+**Retries.** Transport errors, 502/503 and `rate_limited` (for any method) are retried
+automatically up to `max_retries`, reusing the same idempotency key. A plain 500 is retried only for
+GET. Other 4xx errors and `daily_quota_exceeded` are never retried.
+
+## Webhooks
+
+```python
+from plasgos_crm import Webhook, WebhookEventType, WebhookVerificationError
+
+# Flask
+@app.post("/webhooks/plasgos")
+def plasgos_webhook():
+    try:
+        event = Webhook.verify(request.get_data(), request.headers, signing_secret)
+        # during secret rotation: Webhook.verify(body, headers, [new_secret, previous_secret])
+    except WebhookVerificationError:
+        return "", 401
+    if event["type"] == WebhookEventType.MESSAGE_RECEIVED:
+        ...  # event["data"] is a Message
+    return "", 200
+```
+
+`headers` may be any mapping, including a WSGI `environ` or Django `request.META` (`HTTP_*` keys).
+Verify the **raw** body. Deliveries can repeat, so drop `event["id"]` values you have already
+processed.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest              # tests/test_v3_live.py runs only with PLASGOS_LIVE_BASE_URL/_API_KEY/_SECRET_KEY
+mypy src
+ruff check .
+```