apisim 0.1.0__py3-none-any.whl

apisim/__init__.py

@@ -0,0 +1,15 @@
+"""ApiSIM Python SDK: your business phone, connected to software.
+
+from apisim import ApiSim
+
+apisim = ApiSim(api_key=os.environ["APISIM_API_KEY"])
+line = apisim.lines.list()[0]
+op = apisim.messages.send(line["id"], "+15555550101", "Hi Alex, can I help?", idempotency_key="welcome-1042")
+print(apisim.operations.wait_for(op["id"])["state"])  # sent | delivered | failed | uncertain
+"""
+
+from .client import ApiSim, ApiSimError
+from .webhooks import parse_webhook, verify_webhook
+
+__all__ = ["ApiSim", "ApiSimError", "parse_webhook", "verify_webhook"]
+__version__ = "0.1.0"

apisim/client.py

@@ -0,0 +1,236 @@
+"""Synchronous client over httpx. Every write takes an idempotency key: one key, one real action."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from typing import Any, Self
+
+import httpx
+
+TERMINAL = ("sent", "delivered", "failed", "uncertain", "completed")
+
+
+class ApiSimError(Exception):
+    """An error answer from the API: `status`, the API's `detail`, and `retry_after` seconds on 429."""
+
+    def __init__(self, status: int, detail: Any, retry_after: float | None = None):
+        super().__init__(detail if isinstance(detail, str) else repr(detail))
+        self.status = status
+        self.detail = detail
+        self.retry_after = retry_after
+
+
+class ApiSim:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.apisim.app",
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required (create one in the dashboard)")
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers={"Authorization": f"Bearer {api_key}", "User-Agent": "apisim-sdk-python/0.1"},
+        )
+        self.lines = _Lines(self)
+        self.devices = _Devices(self)
+        self.messages = _Messages(self)
+        self.operations = _Operations(self)
+        self.calls = _Calls(self)
+        self.recordings = _Recordings(self)
+        self.events = _Events(self)
+        self.webhooks = _Webhooks(self)
+        self.keys = _Keys(self)
+        self.billing = _Billing(self)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        response = self._http.request(method, path, json=json, params=params, headers=headers)
+        try:
+            data = response.json() if response.content else {}
+        except ValueError:
+            data = response.text
+        if response.is_error:
+            detail = data.get("detail", data) if isinstance(data, dict) else data
+            retry = response.headers.get("retry-after")
+            raise ApiSimError(
+                response.status_code, detail or response.reason_phrase, float(retry) if retry else None
+            )
+        return data
+
+    def me(self) -> dict[str, Any]:
+        """Workspace identity, e-mail verification and the capabilities this deployment enables."""
+        return self.request("GET", "/v1/me")
+
+
+class _Resource:
+    def __init__(self, client: ApiSim):
+        self._c = client
+
+
+class _Lines(_Resource):
+    def list(self) -> list[dict[str, Any]]:
+        return self._c.request("GET", "/v1/lines")
+
+    def set_calling(self, line_id: str, enabled: bool, conference_confirmed: bool = False) -> dict[str, Any]:
+        """Enable calling after confirming the carrier's conference calling works on this SIM."""
+        body = {"enabled": enabled, "conference_confirmed": conference_confirmed}
+        return self._c.request("POST", f"/v1/lines/{line_id}/calling", json=body)
+
+
+class _Devices(_Resource):
+    def list(self) -> list[dict[str, Any]]:
+        return self._c.request("GET", "/v1/devices")
+
+    def disconnect(self, device_id: str) -> Any:
+        return self._c.request("DELETE", f"/v1/devices/{device_id}")
+
+
+class _Messages(_Resource):
+    def send(self, line_id: str, to: str, body: str, idempotency_key: str) -> dict[str, Any]:
+        """Queue an SMS on a line; `idempotency_key` identifies this one message and makes retries safe."""
+        payload = {"line_id": line_id, "to": to, "body": body}
+        return self._c.request("POST", "/v1/messages", json=payload, idempotency_key=idempotency_key)
+
+    def list(self) -> list[dict[str, Any]]:
+        """Scoped business conversations: replies and manual messages to numbers you have contacted."""
+        return self._c.request("GET", "/v1/messages")
+
+
+class _Operations(_Resource):
+    def list(self) -> list[dict[str, Any]]:
+        return self._c.request("GET", "/v1/operations")
+
+    def get(self, operation_id: str) -> dict[str, Any]:
+        return self._c.request("GET", f"/v1/operations/{operation_id}")
+
+    def wait_for(
+        self,
+        operation_id: str,
+        until: tuple[str, ...] = TERMINAL,
+        timeout: float = 60.0,
+        interval: float = 1.5,
+    ) -> dict[str, Any]:
+        """Poll until the operation reaches one of `until`; raises ApiSimError(408) on timeout."""
+        deadline = time.monotonic() + timeout
+        while True:
+            op = self.get(operation_id)
+            if op["state"] in until:
+                return op
+            if time.monotonic() >= deadline:
+                raise ApiSimError(408, f"operation {operation_id} still {op['state']} after timeout")
+            time.sleep(interval)
+
+
+class _Calls(_Resource):
+    def start(
+        self,
+        line_id: str,
+        to: str,
+        idempotency_key: str,
+        record: bool = False,
+        recording_notice_acknowledged: bool = False,
+    ) -> dict[str, Any]:
+        """Dial from the line through the bridge; the recipient sees the SIM's number."""
+        payload = {
+            "line_id": line_id,
+            "to": to,
+            "record": record,
+            "recording_notice_acknowledged": recording_notice_acknowledged,
+        }
+        return self._c.request("POST", "/v1/calls", json=payload, idempotency_key=idempotency_key)
+
+    def answer(self, call_id: str, record: bool = False, recording_notice_acknowledged: bool = False) -> dict:
+        body = {"record": record, "recording_notice_acknowledged": recording_notice_acknowledged}
+        return self._c.request("POST", f"/v1/calls/{call_id}/answer", json=body)
+
+    def end(self, call_id: str) -> dict[str, Any]:
+        return self._c.request("POST", f"/v1/calls/{call_id}/end", json={})
+
+    def session(self, call_id: str) -> dict[str, Any]:
+        """Short-lived WebRTC credentials (`url`, `token`, `room`) for an agent to join the call."""
+        return self._c.request("POST", f"/v1/calls/{call_id}/session", json={})
+
+    def start_recording(self, call_id: str) -> dict[str, Any]:
+        """Record at the bridge; needs record + notice acknowledgement on the call, and credit."""
+        return self._c.request("POST", f"/v1/calls/{call_id}/recording", json={})
+
+
+class _Recordings(_Resource):
+    def list(self) -> list[dict[str, Any]]:
+        return self._c.request("GET", "/v1/recordings")
+
+    def playback(self, recording_id: str) -> dict[str, Any]:
+        """Two-minute private URL (`url`, `expires_in`)."""
+        return self._c.request("GET", f"/v1/recordings/{recording_id}/playback")
+
+    def delete(self, recording_id: str) -> Any:
+        return self._c.request("DELETE", f"/v1/recordings/{recording_id}")
+
+
+class _Events(_Resource):
+    def list(self, after: int = 0) -> list[dict[str, Any]]:
+        """Up to 200 events with seq greater than `after`, in order. Persist the last seq you processed."""
+        return self._c.request("GET", "/v1/events", params={"after": after})
+
+    def stream(self, after: int = 0, interval: float = 2.0) -> Iterator[dict[str, Any]]:
+        """Yield events as they appear, resuming from `after`. Runs until the caller stops iterating."""
+        while True:
+            batch = self.list(after)
+            for event in batch:
+                after = event["seq"]
+                yield event
+            if not batch:
+                time.sleep(interval)
+
+
+class _Webhooks(_Resource):
+    def create(self, url: str) -> dict[str, Any]:
+        """The signing `secret` is returned once; keep it for verify_webhook()."""
+        return self._c.request("POST", "/v1/webhooks", json={"url": url})
+
+    def list(self) -> list[dict[str, Any]]:
+        return self._c.request("GET", "/v1/webhooks")
+
+    def delete(self, webhook_id: str) -> Any:
+        return self._c.request("DELETE", f"/v1/webhooks/{webhook_id}")
+
+
+class _Keys(_Resource):
+    def list(self) -> list[dict[str, Any]]:
+        return self._c.request("GET", "/v1/keys")
+
+    def create(self, label: str) -> dict[str, Any]:
+        return self._c.request("POST", "/v1/keys", json={"label": label})
+
+    def revoke(self, key_id: str) -> Any:
+        return self._c.request("DELETE", f"/v1/keys/{key_id}")
+
+
+class _Billing(_Resource):
+    def status(self) -> dict[str, Any]:
+        return self._c.request("GET", "/v1/billing")
+
+    def ledger(self) -> list[dict[str, Any]]:
+        return self._c.request("GET", "/v1/billing/ledger")

apisim/webhooks.py

@@ -0,0 +1,43 @@
+"""Verify ApiSIM webhook deliveries.
+
+Header `X-Apisim-Signature: t=<unix seconds>,v1=<hex>` where
+v1 = HMAC-SHA256(secret, f"{t}.{raw_body}"). Always verify against the raw request body as received,
+never re-serialised JSON. Delivery is at least once: deduplicate on the `X-Apisim-Event` header.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any
+
+from .client import ApiSimError
+
+
+def verify_webhook(
+    secret: str,
+    signature: str | None,
+    raw_body: bytes | str,
+    tolerance_seconds: int = 300,
+    now: float | None = None,
+) -> bool:
+    parts = dict(p.split("=", 1) for p in (signature or "").split(",") if "=" in p)
+    timestamp, given = parts.get("t"), parts.get("v1")
+    if not timestamp or not given or not timestamp.isdigit():
+        return False
+    if abs((now if now is not None else time.time()) - int(timestamp)) > tolerance_seconds:
+        return False
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, given.lower())
+
+
+def parse_webhook(
+    secret: str, signature: str | None, raw_body: bytes | str, tolerance_seconds: int = 300
+) -> dict[str, Any]:
+    """Verify and parse in one step; raises ApiSimError(401) when the signature is invalid or stale."""
+    if not verify_webhook(secret, signature, raw_body, tolerance_seconds):
+        raise ApiSimError(401, "invalid webhook signature")
+    return json.loads(raw_body)

apisim-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: apisim
+Version: 0.1.0
+Summary: Python client for the ApiSIM API: send SMS, place calls and read conversations through a phone you own.
+Project-URL: Homepage, https://apisim.app/docs
+Project-URL: Repository, https://github.com/ronnybru/apisim
+Project-URL: Issues, https://github.com/ronnybru/apisim/issues
+Author-email: Digital Trend AS <support@apisim.app>
+License-Expression: MIT
+Keywords: ai-agents,api,apisim,phone,sms,voice,webhooks
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Telephony
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# apisim
+
+Python client for the [ApiSIM](https://apisim.app) API: send SMS, place calls with browser or AI
+audio, read conversations and recordings, all through an Android phone and SIM you own.
+Python 3.11+, one dependency (`httpx`).
+
+```sh
+pip install apisim
+```
+
+```python
+import os
+from apisim import ApiSim
+
+apisim = ApiSim(api_key=os.environ["APISIM_API_KEY"])
+
+line = apisim.lines.list()[0]
+op = apisim.messages.send(
+    line["id"],
+    "+15555550101",
+    "Hi Alex, can I help?",
+    idempotency_key="welcome-1042",  # one real-world message; retries with the same key never send twice
+)
+print(apisim.operations.wait_for(op["id"])["state"])  # sent | delivered | failed | uncertain
+```
+
+Outcomes are honest: `sent` is carrier acceptance, `delivered` is handset confirmation, and
+`uncertain` means the phone went quiet mid-action; reconcile before retrying with a new key.
+
+## Events and webhooks
+
+```python
+for event in apisim.events.stream(after=last_seq):
+    if event["type"] == "messages.incoming":
+        handle(event["data"])
+    last_seq = event["seq"]  # persist it
+```
+
+Or register a webhook and verify each delivery against the raw request body:
+
+```python
+from apisim import parse_webhook
+
+event = parse_webhook(
+    os.environ["APISIM_WEBHOOK_SECRET"], request.headers.get("X-Apisim-Signature"), request.body
+)
+```
+
+Delivery is at least once; deduplicate on the `X-Apisim-Event` header.
+
+## Calls
+
+```python
+call = apisim.calls.start(line["id"], "+15555550101", idempotency_key="callback-77")
+session = apisim.calls.session(call["id"])  # {"url", "token", "room"}: WebRTC credentials for your agent
+apisim.calls.end(call["id"])
+```
+
+Calling is enabled per line after a conference-capability check; recording needs `record=True`,
+`recording_notice_acknowledged=True` and credit.
+
+Full reference: https://apisim.app/docs and the OpenAPI document at https://api.apisim.app/docs.

apisim-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+apisim/__init__.py,sha256=RmBdtmzx0Sfp7ASJxUVWTcGSWfHSvh_RNMEGbpZs72Y,573
+apisim/client.py,sha256=KDIfKBoKpmKyN3eAD3rk76DUi33Yxf2uF16SEtbyQsQ,8872
+apisim/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+apisim/webhooks.py,sha256=j--NxYip5JTd7UAOh-A9D5yuzos4y2cyCDcIxlQn2gc,1584
+apisim-0.1.0.dist-info/METADATA,sha256=ASAaTRXkXJjLg97th9GdIGSGDRVV4G-MHzqKz1Z1HPc,2580
+apisim-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+apisim-0.1.0.dist-info/RECORD,,

apisim-0.1.0.dist-info/WHEEL

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