helprange 0.1.0__tar.gz

helprange-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv*/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

helprange-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] – unreleased
+
+First release, generated from HelpRange API spec version 2026-11-15 (not published yet; this entry describes
+everything that will ship in it).
+
+### Added
+
+- Client with every REST API v2 endpoint, grouped by tag: account, folders, documents, links, triggers, data rooms,
+  NDAs, e-signature, offers, store, lead forms, activity, webhook endpoints.
+- Data rooms end to end: `data_rooms.create` (with folders and NDA settings), `update`, `delete(confirm=True)`;
+  sub-resources `data_rooms.guests` (`list`, `invite`, `remove`), `data_rooms.documents` (`list`, `add`, `remove`,
+  `move`), `data_rooms.folders`, `data_rooms.questions`, `data_rooms.request_items`, `data_rooms.access_requests`,
+  `data_rooms.signature_requests`; `ndas.list`.
+- `links.list` (every share link of the team, with filters and pagination) and `links.views` (the views of one link).
+- `webhook_endpoints`: `list`, `create`, `get`, `update`, `delete`, `rotate_secret`, `send_test`, `deliveries`,
+  `redeliver`.
+- Typed request and response models for every endpoint.
+- `share()` – upload a file and create a share link in one call.
+- Automatic `Idempotency-Key` (UUID v4) on every POST / PATCH, reused across retries; `idempotency_key=` on every
+  POST / PATCH method (or `request_options={"idempotency_key": …}`) to set your own.
+- Retries with backoff on 429 (any method, honouring Retry-After), on 408/5xx/connection errors/timeouts (GET and
+  keyed POST / PATCH) and on 409 `idempotency_key_in_progress` (up to 5 extra attempts).
+- Typed errors with status, code and body (incl. `IdempotencyKeyInProgressError`, `UnprocessableEntityError`,
+  `IdempotencyKeyReusedError`); test-mode (`hr_test_`) detection; rate-limit headers after each response.
+- Webhook signature verification (`HelpRange-Signature`, v1 scheme, rotation-aware) and a signing helper for tests.
+- Sync (`HelpRange`) and async (`AsyncHelpRange`) clients.
+- `helprange` command-line tool: login, whoami, share, documents, `links` (all links, filters `--document`
+  `--folder` `--room` `--status` `--label`), `views --link LINK_ID` / `views DOCUMENT_ID`, `rooms create NAME
+  [--folder …] [--nda] [--invite EMAIL …]`, `rooms delete ID --yes`, rooms list/show/index/documents/guests/add/
+  invite/questions; `--json` output everywhere.

helprange-0.1.0/LICENSE

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

helprange-0.1.0/PKG-INFO

@@ -0,0 +1,435 @@
+Metadata-Version: 2.5
+Name: helprange
+Version: 0.1.0
+Summary: Official HelpRange API client: upload documents, create tracked share links, run data rooms, e-signature, offers and analytics.
+Project-URL: Homepage, https://www.helprange.com/developers
+Project-URL: Documentation, https://www.helprange.com/developers/api
+Project-URL: Repository, https://github.com/HelpRange/helprange-python
+Project-URL: Issues, https://github.com/HelpRange/helprange-python/issues
+Project-URL: Changelog, https://github.com/HelpRange/helprange-python/blob/main/CHANGELOG.md
+Author-email: HelpRange <hello@helprange.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,data room,document sharing,e-signature,helprange,sdk,virtual data room,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.23
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# HelpRange Python SDK
+
+Official Python client and CLI for the [HelpRange API](https://www.helprange.com/developers): upload documents, create
+tracked share links, see who viewed what (page by page, link by link), create and run data rooms (folders, NDA,
+guests, Q&A, request lists), send documents for e-signature, create offers and manage your webhook endpoint.
+
+- Sync (`HelpRange`) and asyncio (`AsyncHelpRange`) clients with the same methods
+- Typed responses (`TypedDict`s generated from the [OpenAPI spec](https://www.helprange.com/developers/openapi.json) –
+  plain dicts at runtime, full completion in your editor and mypy/pyright checks)
+- Automatic `Idempotency-Key` on every POST / PATCH, so retries on 429 / 5xx / network errors are safe for writes too
+- Typed exceptions, test-mode detection
+- Webhook signature verification
+- A `helprange` command-line tool with `--json` output for scripts and agents
+
+Python 3.9+. One dependency: [httpx](https://www.python-httpx.org/).
+
+## Install
+
+```sh
+pip install helprange
+```
+
+## Quickstart
+
+```python
+from helprange import HelpRange
+
+hr = HelpRange()  # reads HELPRANGE_API_KEY; or HelpRange("hr_live_…")
+
+# Upload a PDF and create a tracked share link in one call
+result = hr.share("proposal.pdf", label="ACME - Anna", expires_on="2026-12-31", allow_download=False, watermark=True)
+print(result["link"]["url"])  # https://www.helprange.com/view/…/proposal.pdf
+
+# Who opened it, when and for how long
+stats = hr.documents.get(result["document"]["id"], recent_views=20)
+for view in stats["recent_views"]:
+    print(view["viewer"], view["opened_at"], view["seconds_read"])
+```
+
+Async:
+
+```python
+import asyncio
+from helprange import AsyncHelpRange
+
+async def main():
+    async with AsyncHelpRange() as hr:
+        rooms = await hr.data_rooms.list()
+        print([r["name"] for r in rooms["data_rooms"]])
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Create a team API key in HelpRange → **Settings → API keys**. It acts as the administrator who created it, limited to
+its **scopes** (`documents:read`, `documents:write`, `links:read`, `links:write`, `rooms:read`, `rooms:write`,
+`analytics:read`, `team:read`). Every method's docstring names the scope it needs.
+
+The key is taken from the `api_key` argument, else `HELPRANGE_API_KEY`. The SDK sends `Authorization: Bearer <key>`.
+The REST API is part of the Max and Unlimited plans, the Deal Room Pass and the trial; other plans get
+`PaymentRequiredError` (402).
+
+## Sandbox (test mode)
+
+Keys starting with `hr_test_` work on a separate sandbox of your team with sample data – never on live data:
+
+- no e-mail is sent (only addresses at reserved test domains such as `example.com` are accepted; others raise
+  `BadRequestError` with `code == "sandbox_email_domain"`), nothing reaches Stripe, sandbox activity sends no webhooks;
+- every JSON response carries `"livemode": False`;
+- sandbox data is deleted 30 days after the sandbox was created or reset (Settings → API keys → Reset sandbox).
+
+```python
+hr = HelpRange("hr_test_…")
+hr.test_mode               # True
+hr.account.me()["livemode"]  # False
+```
+
+## Resources
+
+| Attribute | What |
+| --- | --- |
+| `hr.account` | Who is connected, the plan and its limits |
+| `hr.folders` | Folders and subfolders |
+| `hr.documents` | Uploads, documents, statistics and share links |
+| `hr.links` | Every share link of the team (filters, pagination) and the views of one link |
+| `hr.triggers` | Newest views and uploads (polling) |
+| `hr.data_rooms` | Create, change and delete data rooms; the index. Sub-resources: `.guests`, `.documents`, `.folders`, `.questions`, `.request_items`, `.access_requests`, `.signature_requests` |
+| `hr.ndas` | The team's NDAs (for a data room's `nda_id`) and whether the plan has NDAs |
+| `hr.signature_requests` | E-signature requests and signed PDFs |
+| `hr.offers` | Offers with their own link |
+| `hr.store` | Store sales and buyer access |
+| `hr.lead_forms` | Lead-magnet / landing-page templates |
+| `hr.activity` | The team activity feed |
+| `hr.webhook_endpoints` | The team's webhook endpoint: create, change, delete, rotate the secret, test, delivery log, redeliver |
+
+Path parameters are positional, everything else is a keyword argument named as in the API reference:
+`hr.documents.create_link(250, label="ACME", passcode="oak-41")`. Arguments you leave out are not sent. For the few
+fields where `null` means something (e.g. `subfolder_id=None` takes documents out of their subfolder), pass `None`
+explicitly. Every method also takes `request_options={"timeout": …, "max_retries": …, "headers": {…}}`; every
+POST / PATCH method also takes `idempotency_key=` (see [Retries](#retries-and-limits)).
+
+Uploads accept a path, `bytes` or a binary file object: `hr.documents.upload(file="deck.pdf", folder_id=31)`, or a
+public URL: `hr.documents.upload(file_url="https://example.com/deck.pdf")`.
+
+Types live in `helprange.types` (`from helprange.types import ShareLink, GetDocumentResponse`). For an endpoint this
+version does not wrap yet: `hr.request("GET", "/api/v2/…")`.
+
+### All endpoints
+
+<!-- BEGIN GENERATED ENDPOINTS -->
+| Method | Endpoint | Scope |
+| --- | --- | --- |
+| `hr.account.me()` | `GET /api/v2/me` | `team:read` |
+| `hr.account.plan()` | `GET /api/v2/plan` | `team:read` |
+| `hr.folders.list()` | `GET /api/v2/folders` | `documents:read` |
+| `hr.folders.get(folder_id)` | `GET /api/v2/folders/{folder_id}` | `documents:read` |
+| `hr.folders.set_subfolders_enabled(folder_id, ...)` | `POST /api/v2/folders/{folder_id}` | `documents:write` |
+| `hr.folders.list_subfolders(folder_id)` | `GET /api/v2/folders/{folder_id}/subfolders` | `documents:read` |
+| `hr.folders.create_subfolder(folder_id, ...)` | `POST /api/v2/folders/{folder_id}/subfolders` | `documents:write` |
+| `hr.folders.move_documents(folder_id, ...)` | `POST /api/v2/folders/{folder_id}/subfolders/move` | `documents:write` |
+| `hr.folders.rename_subfolder(subfolder_id, ...)` | `POST /api/v2/subfolders/{subfolder_id}` | `documents:write` |
+| `hr.folders.delete_subfolder(subfolder_id)` | `POST /api/v2/subfolders/{subfolder_id}/delete` | `documents:write` |
+| `hr.documents.list(...)` | `GET /api/v2/documents` | `documents:read` |
+| `hr.documents.upload(...)` | `POST /api/v2/files` | `documents:write` |
+| `hr.documents.create_link(file_id, ...)` | `POST /api/v2/files/{file_id}/links` | `links:write` |
+| `hr.documents.get(file_id, ...)` | `GET /api/v2/documents/{file_id}` | `documents:read` |
+| `hr.documents.list_links(file_id)` | `GET /api/v2/documents/{file_id}/links` | `links:read` |
+| `hr.links.list(...)` | `GET /api/v2/links` | `links:read` |
+| `hr.links.views(link_id, ...)` | `GET /api/v2/links/{link_id}/views` | `analytics:read` |
+| `hr.triggers.recent_views()` | `GET /api/v2/views` | `analytics:read` |
+| `hr.triggers.recent_uploads()` | `GET /api/v2/uploads` | `documents:read` |
+| `hr.store.grant_buyer_access(folder_id, ...)` | `POST /api/v2/folders/{folder_id}/buyers` | `links:write` |
+| `hr.store.revoke_buyer_access(folder_id, ...)` | `POST /api/v2/folders/{folder_id}/buyers/remove` | `links:write` |
+| `hr.store.list_sales(...)` | `GET /api/v2/store/sales` | `analytics:read` |
+| `hr.lead_forms.list_templates()` | `GET /api/v2/landing-templates` | `links:read` |
+| `hr.activity.list(...)` | `GET /api/v2/activity` | `analytics:read` |
+| `hr.signature_requests.list(...)` | `GET /api/v2/signature-requests` | `documents:read` |
+| `hr.signature_requests.create(...)` | `POST /api/v2/signature-requests` | `documents:write` |
+| `hr.signature_requests.get(envelope_id)` | `GET /api/v2/signature-requests/{envelope_id}` | `documents:read` |
+| `hr.signature_requests.remind(envelope_id)` | `POST /api/v2/signature-requests/{envelope_id}/remind` | `documents:write` |
+| `hr.signature_requests.void(envelope_id, ...)` | `POST /api/v2/signature-requests/{envelope_id}/void` | `documents:write` |
+| `hr.signature_requests.get_signed_pdf(envelope_id)` | `GET /api/v2/signature-requests/{envelope_id}/signed-pdf` | `documents:read` |
+| `hr.data_rooms.list()` | `GET /api/v2/data-rooms` | `rooms:read` |
+| `hr.data_rooms.create(...)` | `POST /api/v2/data-rooms` | `rooms:write` |
+| `hr.data_rooms.get(data_room_id)` | `GET /api/v2/data-rooms/{data_room_id}` | `rooms:read` |
+| `hr.data_rooms.update(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}` | `rooms:write` |
+| `hr.data_rooms.delete(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/delete` | `rooms:write` |
+| `hr.ndas.list()` | `GET /api/v2/ndas` | `rooms:read` |
+| `hr.data_rooms.get_index(data_room_id)` | `GET /api/v2/data-rooms/{data_room_id}/index` | `rooms:read` |
+| `hr.data_rooms.guests.list(data_room_id)` | `GET /api/v2/data-rooms/{data_room_id}/guests` | `rooms:read` |
+| `hr.data_rooms.guests.invite(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/guests` | `rooms:write` |
+| `hr.data_rooms.guests.remove(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/guests/remove` | `rooms:write` |
+| `hr.data_rooms.access_requests.list(data_room_id, ...)` | `GET /api/v2/data-rooms/{data_room_id}/access-requests` | `rooms:read` |
+| `hr.data_rooms.signature_requests.list(data_room_id)` | `GET /api/v2/data-rooms/{data_room_id}/signature-requests` | `rooms:read` |
+| `hr.data_rooms.questions.list(data_room_id, ...)` | `GET /api/v2/data-rooms/{data_room_id}/questions` | `rooms:read` |
+| `hr.data_rooms.questions.add(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/questions` | `rooms:write` |
+| `hr.data_rooms.request_items.list(data_room_id, ...)` | `GET /api/v2/data-rooms/{data_room_id}/requests` | `rooms:read` |
+| `hr.data_rooms.request_items.add(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/requests` | `rooms:write` |
+| `hr.data_rooms.folders.list(data_room_id)` | `GET /api/v2/data-rooms/{data_room_id}/folders` | `rooms:read` |
+| `hr.data_rooms.folders.create(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/folders` | `rooms:write` |
+| `hr.data_rooms.documents.move(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/folders/move` | `rooms:write` |
+| `hr.data_rooms.folders.rename(data_room_id, folder_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/folders/{folder_id}` | `rooms:write` |
+| `hr.data_rooms.folders.delete(data_room_id, folder_id)` | `POST /api/v2/data-rooms/{data_room_id}/folders/{folder_id}/delete` | `rooms:write` |
+| `hr.data_rooms.documents.list(data_room_id)` | `GET /api/v2/data-rooms/{data_room_id}/documents` | `rooms:read` |
+| `hr.data_rooms.documents.add(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/documents` | `rooms:write` |
+| `hr.data_rooms.documents.remove(data_room_id, ...)` | `POST /api/v2/data-rooms/{data_room_id}/documents/remove` | `rooms:write` |
+| `hr.offers.list(...)` | `GET /api/v2/offers` | `links:read` |
+| `hr.offers.create(...)` | `POST /api/v2/offers` | `links:write` |
+| `hr.offers.get(offer_id)` | `GET /api/v2/offers/{offer_id}` | `links:read` |
+| `hr.offers.update(offer_id, ...)` | `PATCH /api/v2/offers/{offer_id}` | `links:write` |
+| `hr.offers.add_files(offer_id, ...)` | `POST /api/v2/offers/{offer_id}/files` | `links:write` |
+| `hr.offers.remove_files(offer_id, ...)` | `POST /api/v2/offers/{offer_id}/files/remove` | `links:write` |
+| `hr.offers.list_responses(offer_id, ...)` | `GET /api/v2/offers/{offer_id}/responses` | `analytics:read` |
+| `hr.offers.list_all_responses(...)` | `GET /api/v2/offer-responses` | `analytics:read` |
+| `hr.webhook_endpoints.list()` | `GET /api/v2/webhook-endpoints` | `webhooks:manage` |
+| `hr.webhook_endpoints.create(...)` | `POST /api/v2/webhook-endpoints` | `webhooks:manage` |
+| `hr.webhook_endpoints.get(endpoint_id)` | `GET /api/v2/webhook-endpoints/{endpoint_id}` | `webhooks:manage` |
+| `hr.webhook_endpoints.update(endpoint_id, ...)` | `POST /api/v2/webhook-endpoints/{endpoint_id}` | `webhooks:manage` |
+| `hr.webhook_endpoints.delete(endpoint_id)` | `POST /api/v2/webhook-endpoints/{endpoint_id}/delete` | `webhooks:manage` |
+| `hr.webhook_endpoints.rotate_secret(endpoint_id)` | `POST /api/v2/webhook-endpoints/{endpoint_id}/rotate-secret` | `webhooks:manage` |
+| `hr.webhook_endpoints.send_test(endpoint_id)` | `POST /api/v2/webhook-endpoints/{endpoint_id}/test` | `webhooks:manage` |
+| `hr.webhook_endpoints.deliveries(endpoint_id, ...)` | `GET /api/v2/webhook-endpoints/{endpoint_id}/deliveries` | `webhooks:manage` |
+| `hr.webhook_endpoints.redeliver(endpoint_id, delivery_id)` | `POST /api/v2/webhook-endpoints/{endpoint_id}/deliveries/{delivery_id}/redeliver` | `webhooks:manage` |
+<!-- END GENERATED ENDPOINTS -->
+
+## Data rooms
+
+```python
+# NDAs need the Max plan (or the Deal Room Pass / trial)
+nda_available = hr.ndas.list()["nda_available"]
+
+room = hr.data_rooms.create(
+    name="Project Falcon",
+    folders=["1. Corporate", "2. Financials", "3. Legal"],
+    settings={"download": False, "watermark": True, "nda": nda_available, "nda_template": "investor", "nda_mode": "click"},
+)
+print(room["links"]["guest_link"])  # the room's shareable link
+
+hr.data_rooms.documents.add(room["id"], document_ids=[250, 251], folder_id=room["folders"][1]["id"])
+
+guest = hr.data_rooms.guests.invite(room["id"], email="jane@example.com")
+print(guest["link"])  # Jane's own link – also e-mailed to her unless send_invite=False
+
+hr.data_rooms.guests.list(room["id"])
+hr.data_rooms.guests.remove(room["id"], email="jane@example.com")
+hr.data_rooms.update(room["id"], settings={"expires_on": "2026-12-31"})
+
+# Deleting a room (and its guest access) needs an explicit confirmation
+hr.data_rooms.delete(room["id"], confirm=True)
+```
+
+## Links and views
+
+```python
+# Every share link of the team – filter by document_id, folder_id, room_id, label, status, created_after/_before
+page = 1
+while page:
+    res = hr.links.list(document_id=250, status="active", page=page, limit=200)
+    for link in res["links"]:
+        print(link["id"], link["label"], link["views"], link["url"])
+    page = res["next_page"]
+
+# Who opened one link, when, for how long
+for v in hr.links.views(264, limit=100)["views"]:
+    print(v["viewer"], v["opened_at"], v["seconds_read"], v["pages_read"])
+```
+
+## Errors
+
+Every exception is a `helprange.HelpRangeError` with `status`, `code` (the API's machine-readable reason, when it
+sends one), `message` and the parsed `body`:
+
+| Exception | When |
+| --- | --- |
+| `BadRequestError` | 400 – e.g. a duplicate link label, `sandbox_email_domain` |
+| `AuthenticationError` | 401 – `invalid_key`, `key_revoked`, `key_expired`, `key_owner_removed` |
+| `PaymentRequiredError` | 402 – the plan does not include the API / feature |
+| `PermissionDeniedError` | 403 – `insufficient_scope` (see `.required_scope`) |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 – e.g. a frozen room, the team already has a webhook endpoint |
+| `IdempotencyKeyInProgressError` | 409 `idempotency_key_in_progress` (a `ConflictError`) – still running after the in-progress retries |
+| `UnprocessableEntityError` | 422 |
+| `IdempotencyKeyReusedError` | 422 `idempotency_key_reused` (an `UnprocessableEntityError`) – the key was used for a different request |
+| `PayloadTooLargeError` | 413 – `FILE_TOO_LARGE`, `REQUEST_TOO_LARGE` |
+| `LockedError` | 423 – e.g. `ROOM_FROZEN` |
+| `RateLimitError` | 429 – `RATE_LIMITED`, `DAILY_LIMIT`, `PAUSED`, `UPLOAD_LIMIT` (see `.retry_after`) |
+| `InternalServerError` | 5xx |
+| `APIConnectionError` / `APITimeoutError` | no HTTP answer / timed out |
+| `WebhookVerificationError` | `verify_webhook()` rejected a delivery |
+
+```python
+from helprange import PermissionDeniedError, RateLimitError
+
+try:
+    hr.data_rooms.guests.invite(10, email="jane@example.com")
+except PermissionDeniedError as e:
+    print("missing scope:", e.required_scope)
+except RateLimitError as e:
+    print(f"over a limit ({e.code}); retry in {e.retry_after}s")
+```
+
+## Retries and limits
+
+Every `POST` and `PATCH` carries an `Idempotency-Key` header – a new UUID v4 per call, **the same one for every retry
+of that call**. The API runs a keyed request once and answers a repeat with the stored response (header
+`Idempotent-Replayed: true`), so a retried write never creates a second data room, share link or invitation.
+
+- **429** (any method) – the API did not carry out the request. The client waits `Retry-After` and retries, unless the
+  wait is longer than `max_retry_after` (default 60 s – e.g. a daily cap or a paused API); then it raises
+  `RateLimitError` at once.
+- **408 / 5xx, connection errors and timeouts** – retried for `GET` and for keyed `POST` / `PATCH`, with exponential
+  backoff (0.5 s, 1 s, 2 s … up to 8 s, with jitter; a short `Retry-After` is respected).
+- **409 `idempotency_key_in_progress`** – the first attempt is still running on the server (typically after a
+  timeout). The client waits with backoff (~1, 2, 4, 8, 8 s) and asks again, up to 5 times, without using up
+  `max_retries`; then it raises `IdempotencyKeyInProgressError`.
+- **422 `idempotency_key_reused`** – never retried; raises `IdempotencyKeyReusedError`. It means the key was used in the
+  last 24 hours for a different method, path or body.
+
+Pass your own key to make a write safe to repeat across processes or restarts (e.g. a job id):
+
+```python
+hr.data_rooms.create(name="Project Falcon", idempotency_key=f"deal-{deal.id}-room")
+# or, on any method: request_options={"idempotency_key": "…"}
+```
+
+Keys are kept for 24 hours, per API key. `hr.share(..., request_options={"idempotency_key": k})` uses `k` for the
+upload and `k:link` for the share link.
+
+`max_retries` (default 2) and `timeout` (default 60 s per attempt) can be set on the client or per request.
+After each response `hr.rate_limit` holds `limit`, `remaining`, `reset` and `livemode` from the response headers.
+Team limits: 3,600 requests an hour, 120 a minute, 300 writes an hour, 2,000 share links and 1,000 guests a day.
+
+## Webhooks
+
+HelpRange POSTs signed JSON events (`document.opened`, `file_request.uploaded`, `room.access_requested`,
+`nda.accepted`, `document.acknowledged`, `offer.accepted`, `offer.declined`, `offer.contact_requested`) to the endpoint
+you set in Settings → Integrations or through `hr.webhook_endpoints`. Verify each delivery with the **raw** body:
+
+```python
+# Flask
+import os
+
+from flask import Flask, request
+from helprange import verify_webhook, WebhookVerificationError
+
+app = Flask(__name__)
+
+@app.post("/webhooks/helprange")
+def helprange_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers, os.environ["HELPRANGE_WEBHOOK_SECRET"])
+    except WebhookVerificationError:
+        return "", 400
+    # deduplicate on event["id"] – retries carry the same id
+    if event["event"] == "document.opened":
+        print(event["data"])
+    return "", 200  # answer 2xx within 10 seconds
+```
+
+Django: `verify_webhook(request.body, request.headers, secret)`; FastAPI: `verify_webhook(await request.body(),
+request.headers, secret)`.
+
+The scheme: `HelpRange-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`. `verify_webhook` accepts
+a timestamp within 5 minutes (`tolerance=` to change it) and any `v1` that matches – during the 24 hours after a secret
+rotation HelpRange sends two. Pass a list of secrets if you rotate on your side. `sign_webhook_payload()` builds a valid
+header for your tests. See the [webhooks guide](https://www.helprange.com/developers/webhooks).
+
+Manage the endpoint from code:
+
+```python
+ep = hr.webhook_endpoints.create(url="https://example.com/webhooks/helprange")
+print(ep["secret"])                                    # shown once – store it
+hr.webhook_endpoints.send_test(ep["id"])               # a test event, delivered right away
+failed = hr.webhook_endpoints.deliveries(ep["id"], status="failed")["deliveries"]
+if failed:
+    hr.webhook_endpoints.redeliver(ep["id"], failed[0]["id"])
+secret = hr.webhook_endpoints.rotate_secret(ep["id"])["secret"]  # the old secret keeps signing for 24 hours
+hr.webhook_endpoints.update(ep["id"], enabled=True)    # turn it back on after 410 Gone / repeated failures
+hr.webhook_endpoints.delete(ep["id"])
+```
+
+## Command line
+
+```sh
+helprange login                                  # prompts for the key, checks it, saves ~/.config/helprange/config (0600)
+helprange whoami
+helprange share proposal.pdf --to anna@acme.com --to bob@acme.com --expires 2026-12-31 --no-download --watermark
+helprange share https://example.com/deck.pdf     # a public URL works too
+helprange documents
+helprange links                                  # every active share link of the team
+helprange links --document 250 --status all      # filters: --document --folder --room --status --label (+ --page --limit)
+helprange views --link 264                       # who opened link 264, when, how long
+helprange views 250                              # a document's totals and latest views
+helprange rooms create "Project Falcon" --folder Corporate --folder Financials --nda \
+    --invite jane@example.com --invite max@example.com   # prints the guest link and each guest's own link
+helprange rooms list
+helprange rooms show 10 | index 10 | documents 10 | guests 10 | questions 10 --status open
+helprange rooms add 10 250 251                   # add documents 250 and 251 to room 10
+helprange rooms invite 10 jane@example.com       # HelpRange e-mails the invitation
+helprange rooms delete 10 --yes                  # without --yes nothing is deleted
+```
+
+- `--json` on any command prints JSON (errors go to stderr as JSON too) – meant for scripts and AI agents.
+- The key: `--api-key`, else `HELPRANGE_API_KEY`, else the saved one. `helprange logout` forgets it.
+- `share --to` creates **one link per recipient**, labelled with their e-mail, so the statistics show who opened what.
+  HelpRange does not e-mail links created through the API – send them yourself.
+- Exit codes: 0 ok, 1 API error, 2 usage / configuration error.
+
+`python -m helprange …` works the same.
+
+## Examples
+
+[`examples/`](examples): [`share_pdf.py`](examples/share_pdf.py) (share a PDF and get a link),
+[`who_viewed.py`](examples/who_viewed.py) (who viewed a document, through which link, time per page),
+[`data_room.py`](examples/data_room.py) (async: create a room with folders and an NDA, add documents, invite guests
+and print their links, index, Q&A),
+[`webhook_endpoints.py`](examples/webhook_endpoints.py) (create / update the endpoint, test event, redeliver, rotate
+the secret),
+[`webhook_server.py`](examples/webhook_server.py) (stdlib webhook receiver).
+
+## Why httpx
+
+httpx is the one dependency: it gives the sync and the async client the same request model, real connect/read
+timeouts, connection pooling, correct multipart uploads and `MockTransport` for tests, and is already installed in
+most modern Python stacks (it is pure Python). The stdlib (`urllib`) has no async client, so an async SDK on top of it
+would need threads, and it lacks pooling and multipart.
+
+## Development
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest -q          # fake transport, no network
+.venv/bin/ruff check src tests examples && .venv/bin/mypy src examples
+```
+
+`src/helprange/_generated/` is generated from the OpenAPI spec – don't edit it by hand; see the generator in the
+`helprange-sdks` workspace.
+
+## License
+
+MIT © HelpRange