postcept 0.1.0__py3-none-any.whl

postcept/__init__.py

@@ -0,0 +1,6 @@
+"""Python SDK for Postcept: Proof-of-Completion for AI agents."""
+
+from postcept._client import DEFAULT_BASE_URL, Postcept, PostceptError
+
+__all__ = ["DEFAULT_BASE_URL", "Postcept", "PostceptError"]
+__version__ = "0.1.0"

postcept/_client.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.postcept.com"
+
+
+class PostceptError(Exception):
+    """Raised when the Postcept API returns an error response."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(f"Postcept API error {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+class Postcept:
+    """Submit Proof-of-Completion verifications for your agents' actions.
+
+    Authenticate with an organization API key (``pcpt_sk_...``):
+
+        from postcept import Postcept
+
+        pc = Postcept(api_key="pcpt_sk_...")
+        result = pc.verify_refund(
+            operation_id="refund_8F31",
+            agent_id="SupportAgent-04",
+            refund_id="re_4md82k",
+            amount_cents=12000,
+            currency="usd",
+            customer="mara.ellis@example.com",
+            idempotency_key="refund_8F31",
+        )
+        print(result["result"])  # "verified" | "incomplete" | "mismatched" | ...
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # --- verifications ---
+
+    def verify_refund(
+        self,
+        *,
+        operation_id: str,
+        agent_id: str,
+        customer: str,
+        amount_cents: int,
+        currency: str = "usd",
+        refund_id: str | None = None,
+        charge_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Verify that a refund actually completed in the system of record."""
+        claim: dict[str, Any] = {
+            "customer": customer,
+            "amount_cents": amount_cents,
+            "currency": currency,
+        }
+        if refund_id is not None:
+            claim["refund_id"] = refund_id
+        if charge_id is not None:
+            claim["charge_id"] = charge_id
+        return self._create_verification(operation_id, agent_id, claim, idempotency_key)
+
+    def verify_cancellation(
+        self,
+        *,
+        operation_id: str,
+        agent_id: str,
+        subscription_id: str,
+        customer: str,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Verify that a subscription was actually cancelled in the system of record."""
+        claim = {"subscription_id": subscription_id, "customer": customer}
+        return self._create_verification(operation_id, agent_id, claim, idempotency_key)
+
+    def get_verification(self, verification_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/verifications/{verification_id}")
+
+    def verified_completion_rate(self) -> dict[str, Any]:
+        """The org's Verified Completion Rate (verified / claimed)."""
+        return self._request("GET", "/v1/metrics/vcr")
+
+    # --- internals ---
+
+    def _create_verification(
+        self,
+        operation_id: str,
+        agent_id: str,
+        claim: dict[str, Any],
+        idempotency_key: str | None,
+    ) -> dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        body = {"operation_id": operation_id, "agent_id": agent_id, "claim": claim}
+        return self._request("POST", "/v1/verifications", json=body, headers=headers)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        response = self._client.request(method, path, json=json, headers=headers)
+        if response.is_error:
+            raise PostceptError(response.status_code, _detail(response))
+        return response.json()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Postcept:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+
+def _detail(response: httpx.Response) -> str:
+    try:
+        return response.json().get("detail", response.text)
+    except Exception:
+        return response.text

postcept-0.1.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: postcept
+Version: 0.1.0
+Summary: Python SDK for Postcept: Proof-of-Completion for AI agents.
+Project-URL: Homepage, https://postcept.com
+Project-URL: Documentation, https://postcept.com/docs
+Project-URL: Repository, https://github.com/Postcept/postcept-python
+Project-URL: Issues, https://github.com/Postcept/postcept-python/issues
+Author: Postcept
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,postcept,proof-of-completion,receipt,stripe,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Postcept Python SDK
+
+Submit Proof-of-Completion verifications for your AI agents' high-risk actions.
+
+```bash
+pip install postcept
+```
+
+## Usage
+
+```python
+from postcept import Postcept
+
+pc = Postcept(api_key="pcpt_sk_...")  # create a key in the dashboard
+
+# After your agent issues a refund, prove it actually completed:
+result = pc.verify_refund(
+    operation_id="refund_8F31",        # stable across retries
+    agent_id="SupportAgent-04",
+    refund_id="re_4md82k",
+    amount_cents=12000,
+    currency="usd",
+    customer="mara.ellis@example.com",
+    idempotency_key="refund_8F31",     # safe to retry
+)
+
+print(result["result"])                # "verified" | "incomplete" | "duplicated" | "mismatched" | "policy_failed"
+print(result["receipt"]["id"])         # signed completion receipt
+```
+
+Cancellations work the same way:
+
+```python
+pc.verify_cancellation(
+    operation_id="cancel_2240",
+    agent_id="SupportAgent-04",
+    subscription_id="sub_9Kd21",
+    customer="mara.ellis@example.com",
+)
+```
+
+Read your Verified Completion Rate:
+
+```python
+pc.verified_completion_rate()  # {"claimed": 1240, "verified": 1167, "verified_completion_rate": 0.9411, ...}
+```
+
+## Notes
+
+- **Auth**: pass an organization API key (`pcpt_sk_...`). All data is scoped to that org.
+- **Idempotency**: pass `idempotency_key` so retried submissions return the original verification instead of creating a duplicate.
+- **Errors**: non-2xx responses raise `PostceptError` (`.status_code`, `.detail`).
+- **Base URL**: defaults to `https://api.postcept.com`. Override with `Postcept(api_key=..., base_url=...)` for staging.
+- Use as a context manager (`with Postcept(...) as pc:`) to close the HTTP client.

postcept-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+postcept/__init__.py,sha256=V8IZ1og2DPwlOqbEDLXhicSwDiVENz8-_CzhLc4tYiU,221
+postcept/_client.py,sha256=BmWY5S4Dm6Cz3PRcB32Mzwm4qyX65pkKwHNdf3wwsF8,4368
+postcept-0.1.0.dist-info/METADATA,sha256=vmIbPyLyGjpW-ycEW1DEUJhBpI1QWCZzDpF2v3SpvvY,2520
+postcept-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+postcept-0.1.0.dist-info/licenses/LICENSE,sha256=u_Poz2GlsmRFjANw0D4d45KYNbZBUvKOR-FLxBYckfc,1071
+postcept-0.1.0.dist-info/RECORD,,

postcept-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

postcept-0.1.0.dist-info/licenses/LICENSE

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