augstash 0.2.0__tar.gz

augstash-0.2.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Augmentrait Private Limited
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

augstash-0.2.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: augstash
+Version: 0.2.0
+Summary: Python client for the Augstash messaging API
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urllib3<3,>=2.1
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: typing-extensions>=4.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# augstash (Python)
+
+Python client for the Augstash API. Not published yet - see [`../README.md`](../README.md).
+
+```bash
+python -m pip install -e .[dev]
+python ../tools/refresh.py --base-url http://localhost:8086 python   # generate the client
+python -m pytest tests
+```
+
+## Using it
+
+```python
+import os
+from augstash import AugstashClient, AugstashError
+from augstash.generated.api import SmsApi, WalletApi
+from augstash.generated.models import SendSmsRequest
+
+client = AugstashClient(
+    base_url=os.environ["AUGSTASH_BASE_URL"],   # required - there is no default host
+    api_key=os.environ["AUGSTASH_API_KEY"],     # ask_live_<keyId>.<secret>
+)
+
+wallet = client.api(WalletApi).balance()
+
+try:
+    client.api(SmsApi).send_sms(SendSmsRequest(to="+919000000000", body="hello"))
+except AugstashError as error:
+    if error.code == "WALLET_INSUFFICIENT_FUNDS":   # branch on code, never on message
+        print(error.detail, error.trace_id)
+```
+
+`client.api(X)` takes any of the 154 generated API classes and hands back a cached, configured
+instance. There is no hand-written list of accessors: one would drift the moment an endpoint is
+added.
+
+### Paging
+
+```python
+from augstash import paginate_cursor, paginate_pages
+from augstash.generated.api import ContactApi
+
+contacts = client.api(ContactApi)
+for contact in paginate_pages(lambda page: contacts.list_contacts(page=page, limit=100)):
+    ...
+```
+
+Use `paginate_cursor` for message, conversation and event history - those endpoints are
+cursor-paged because an offset page over a table that grows at the top repeats and skips rows
+mid-scroll.
+
+### Webhooks
+
+```python
+from augstash import verify_webhook_signature, SIGNATURE_HEADER
+
+@app.post("/hooks/augstash")
+def receive():
+    # request.get_data(), not request.get_json(): the signature covers the bytes as sent, and a
+    # parsed-then-reserialized body no longer matches.
+    if not verify_webhook_signature(secret, request.get_data(), request.headers.get(SIGNATURE_HEADER)):
+        return "", 401
+    return "", 204
+```
+
+## Options
+
+| Argument | Default | |
+|---|---|---|
+| `base_url` | - | required |
+| `api_key` / `bearer_token` | - | one is required; a bearer token reaches endpoints a key cannot |
+| `timeout` | 30.0 | seconds, per attempt |
+| `retry` | `RetryPolicy(3, 0.5, 8.0)` | `RetryPolicy(max_attempts=1)` disables |
+| `idempotency` | `True` | off also stops mutating calls being retried |
+| `headers` | - | extra headers on every request |
+
+The client is a context manager (`with AugstashClient(...) as client:`) and holds a connection
+pool; call `close()` when you are done with it.
+
+## Layout
+
+`augstash/generated/` is machine-written and gitignored; `augstash/*.py` beside it is the
+hand-written core and is protected from the generator by `.openapi-generator-ignore`.

augstash-0.2.0/README.md

@@ -0,0 +1,83 @@
+# augstash (Python)
+
+Python client for the Augstash API. Not published yet - see [`../README.md`](../README.md).
+
+```bash
+python -m pip install -e .[dev]
+python ../tools/refresh.py --base-url http://localhost:8086 python   # generate the client
+python -m pytest tests
+```
+
+## Using it
+
+```python
+import os
+from augstash import AugstashClient, AugstashError
+from augstash.generated.api import SmsApi, WalletApi
+from augstash.generated.models import SendSmsRequest
+
+client = AugstashClient(
+    base_url=os.environ["AUGSTASH_BASE_URL"],   # required - there is no default host
+    api_key=os.environ["AUGSTASH_API_KEY"],     # ask_live_<keyId>.<secret>
+)
+
+wallet = client.api(WalletApi).balance()
+
+try:
+    client.api(SmsApi).send_sms(SendSmsRequest(to="+919000000000", body="hello"))
+except AugstashError as error:
+    if error.code == "WALLET_INSUFFICIENT_FUNDS":   # branch on code, never on message
+        print(error.detail, error.trace_id)
+```
+
+`client.api(X)` takes any of the 154 generated API classes and hands back a cached, configured
+instance. There is no hand-written list of accessors: one would drift the moment an endpoint is
+added.
+
+### Paging
+
+```python
+from augstash import paginate_cursor, paginate_pages
+from augstash.generated.api import ContactApi
+
+contacts = client.api(ContactApi)
+for contact in paginate_pages(lambda page: contacts.list_contacts(page=page, limit=100)):
+    ...
+```
+
+Use `paginate_cursor` for message, conversation and event history - those endpoints are
+cursor-paged because an offset page over a table that grows at the top repeats and skips rows
+mid-scroll.
+
+### Webhooks
+
+```python
+from augstash import verify_webhook_signature, SIGNATURE_HEADER
+
+@app.post("/hooks/augstash")
+def receive():
+    # request.get_data(), not request.get_json(): the signature covers the bytes as sent, and a
+    # parsed-then-reserialized body no longer matches.
+    if not verify_webhook_signature(secret, request.get_data(), request.headers.get(SIGNATURE_HEADER)):
+        return "", 401
+    return "", 204
+```
+
+## Options
+
+| Argument | Default | |
+|---|---|---|
+| `base_url` | - | required |
+| `api_key` / `bearer_token` | - | one is required; a bearer token reaches endpoints a key cannot |
+| `timeout` | 30.0 | seconds, per attempt |
+| `retry` | `RetryPolicy(3, 0.5, 8.0)` | `RetryPolicy(max_attempts=1)` disables |
+| `idempotency` | `True` | off also stops mutating calls being retried |
+| `headers` | - | extra headers on every request |
+
+The client is a context manager (`with AugstashClient(...) as client:`) and holds a connection
+pool; call `close()` when you are done with it.
+
+## Layout
+
+`augstash/generated/` is machine-written and gitignored; `augstash/*.py` beside it is the
+hand-written core and is protected from the generator by `.openapi-generator-ignore`.

augstash-0.2.0/augstash/__init__.py

@@ -0,0 +1,39 @@
+"""augstash - the Python client for the Augstash API.
+
+The hand-written entry points live here; the generated client (154 API classes and their models)
+lives under ``augstash.generated`` and is regenerated by ``python sdk/tools/refresh.py``.
+
+    from augstash import AugstashClient, AugstashError
+    from augstash.generated.api import ContactApi
+"""
+from augstash.client import AugstashClient
+from augstash.errors import AugstashConfigError, AugstashConnectionError, AugstashError
+from augstash.pagination import paginate_cursor, paginate_pages
+from augstash.transport import AugstashApiClient, RetryPolicy, parse_retry_after
+from augstash.webhooks import (
+    EVENT_HEADER,
+    EVENT_ID_HEADER,
+    SIGNATURE_HEADER,
+    sign_webhook,
+    verify_webhook_signature,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AugstashClient",
+    "AugstashApiClient",
+    "AugstashError",
+    "AugstashConnectionError",
+    "AugstashConfigError",
+    "RetryPolicy",
+    "parse_retry_after",
+    "paginate_pages",
+    "paginate_cursor",
+    "verify_webhook_signature",
+    "sign_webhook",
+    "SIGNATURE_HEADER",
+    "EVENT_HEADER",
+    "EVENT_ID_HEADER",
+    "__version__",
+]

augstash-0.2.0/augstash/client.py

@@ -0,0 +1,95 @@
+"""The entry point: one configured client, from which every API surface is taken.
+
+::
+
+    from augstash import AugstashClient
+    from augstash.generated.api import WalletApi, SmsApi
+
+    client = AugstashClient(
+        base_url=os.environ["AUGSTASH_BASE_URL"],   # no default beyond localhost - pass your own
+        api_key=os.environ["AUGSTASH_API_KEY"],     # ask_live_<keyId>.<secret>
+    )
+
+    balance = client.api(WalletApi).balance()
+    client.api(SmsApi).send_sms(send_sms_request=SendSmsRequest(to="+919000000000", body="hi"))
+
+There are 154 API classes, one per controller, and ``client.api(X)`` reaches any of them: it hands
+back a cached, fully configured instance. No hand-written list of accessors exists on purpose - one
+would drift the moment an endpoint is added.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Type, TypeVar
+
+from augstash.errors import AugstashConfigError
+from augstash.generated.configuration import Configuration
+from augstash.transport import AugstashApiClient, RetryPolicy
+
+T = TypeVar("T")
+
+
+class AugstashClient:
+    """A configured Augstash API client."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        timeout: Optional[float] = 30.0,
+        retry: Optional[RetryPolicy] = None,
+        idempotency: bool = True,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """
+        :param base_url: origin of the Augstash API for your environment. Required.
+        :param api_key: an ``ask_live_*`` key, sent as ``X-Api-Key``
+        :param bearer_token: an Augstash-issued user JWT; reaches endpoints a key cannot
+        :param timeout: per-request timeout in seconds
+        :param retry: retry policy for 429/502/503/504 and transport failures
+        :param idempotency: send ``X-Idempotency-Key`` on mutating calls. Turning it off also stops
+            mutating calls being retried, because a retry would then risk executing twice.
+        :param headers: extra headers on every request
+        """
+        if not base_url:
+            raise AugstashConfigError("base_url is required - there is no default Augstash host")
+        if not api_key and not bearer_token:
+            raise AugstashConfigError("pass either api_key (ask_live_*) or bearer_token")
+
+        configuration = Configuration(host=base_url.rstrip("/"))
+        if api_key:
+            configuration.api_key["ApiKeyAuth"] = api_key
+        if bearer_token:
+            configuration.access_token = bearer_token
+
+        self.configuration = configuration
+        self.api_client = AugstashApiClient(configuration, retry=retry, idempotency=idempotency)
+        self.api_client.user_agent = "augstash-python/0.1.0"
+        for name, value in (headers or {}).items():
+            self.api_client.set_default_header(name, value)
+        self._timeout = timeout
+        self._instances: Dict[type, Any] = {}
+
+    @property
+    def timeout(self) -> Optional[float]:
+        """Per-request timeout in seconds. Pass ``_request_timeout=`` on a call to override it."""
+        return self._timeout
+
+    def api(self, api_class: Type[T]) -> T:
+        """A configured instance of any generated API class, created once and reused."""
+        existing = self._instances.get(api_class)
+        if existing is not None:
+            return existing  # type: ignore[return-value]
+        created = api_class(self.api_client)  # type: ignore[call-arg]
+        self._instances[api_class] = created
+        return created
+
+    def close(self) -> None:
+        """Release the underlying connection pool."""
+        self.api_client.close()
+
+    def __enter__(self) -> "AugstashClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

augstash-0.2.0/augstash/errors.py

@@ -0,0 +1,73 @@
+"""Errors the Augstash API raises, in the shape it actually sends them.
+
+A failure arrives as ``{"success": false, "code": ..., "data": {"code", "fieldErrors", "detail"},
+"message": ..., "traceId": ...}``. ``code`` is the stable name to branch on; ``message`` is
+localized text that changes with the caller's language and must never be matched against.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class AugstashError(Exception):
+    """Every error raised for a call the server answered.
+
+    Branch on :attr:`code`. Quote :attr:`trace_id` in a support request - it is the correlation id
+    the backend logged the failure under.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        trace_id: Optional[str] = None,
+        detail: Optional[str] = None,
+        field_errors: Optional[List[Dict[str, Any]]] = None,
+        method: Optional[str] = None,
+        url: Optional[str] = None,
+        retry_after_seconds: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.trace_id = trace_id
+        self.detail = detail
+        self.field_errors = field_errors or []
+        self.method = method
+        self.url = url
+        self.retry_after_seconds = retry_after_seconds
+
+    @property
+    def is_authentication_error(self) -> bool:
+        """No key, an unknown key, or an expired token."""
+        return self.status == 401
+
+    @property
+    def is_permission_error(self) -> bool:
+        """Authenticated, but this key lacks the scope - or the endpoint needs a signed-in user."""
+        return self.status == 403
+
+    @property
+    def is_rate_limit_error(self) -> bool:
+        """The key's per-minute budget is spent; wait :attr:`retry_after_seconds`."""
+        return self.status == 429
+
+    def __str__(self) -> str:
+        detail = f" ({self.detail})" if self.detail else ""
+        trace = f" traceId={self.trace_id}" if self.trace_id else ""
+        return f"[{self.status} {self.code}] {self.message}{detail}{trace}"
+
+
+class AugstashConnectionError(AugstashError):
+    """The request never reached Augstash, or the answer never came back."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None,
+                 method: Optional[str] = None, url: Optional[str] = None) -> None:
+        super().__init__(status=0, code="CONNECTION_ERROR", message=message, method=method, url=url)
+        self.cause = cause
+
+
+class AugstashConfigError(ValueError):
+    """Configuration this SDK refuses to start with - a missing base URL or missing credentials."""