restless-stream 0.1.1__py3-none-any.whl

restless_stream/__init__.py

@@ -0,0 +1,65 @@
+"""Python SDK for Restless Stream."""
+
+from ._client import AsyncRestlessStreamClient, RestlessStreamClient
+from ._errors import RestlessStreamAPIError, RestlessStreamError, RestlessStreamParseError
+from ._hmac import compute_hmac_signature, verify_hmac_signature
+from ._models import (
+  BaseActionResponse,
+  ConnectionSnippetsResponse,
+  CreditUsageChargeTypeBreakdown,
+  DailyCreditUsage,
+  DirectSessionResponse,
+  DirectSetupResponse,
+  HttpMethod,
+  PayloadMode,
+  PollingStrategy,
+  RestlessModel,
+  Stream,
+  StreamCreditUsageStats,
+  StreamErrorDetail,
+  StreamEvent,
+  StreamEventMeta,
+  StreamsResponse,
+  StreamStatus,
+)
+from ._urls import (
+  DEFAULT_STREAM_BASE_URL,
+  build_direct_sse_url,
+  build_direct_websocket_url,
+  build_sse_url,
+  build_websocket_url,
+  to_websocket_url,
+)
+
+__all__ = [
+  "AsyncRestlessStreamClient",
+  "BaseActionResponse",
+  "ConnectionSnippetsResponse",
+  "CreditUsageChargeTypeBreakdown",
+  "DEFAULT_STREAM_BASE_URL",
+  "DailyCreditUsage",
+  "DirectSessionResponse",
+  "DirectSetupResponse",
+  "HttpMethod",
+  "PayloadMode",
+  "PollingStrategy",
+  "RestlessModel",
+  "RestlessStreamAPIError",
+  "RestlessStreamClient",
+  "RestlessStreamError",
+  "RestlessStreamParseError",
+  "Stream",
+  "StreamCreditUsageStats",
+  "StreamErrorDetail",
+  "StreamEvent",
+  "StreamEventMeta",
+  "StreamStatus",
+  "StreamsResponse",
+  "compute_hmac_signature",
+  "verify_hmac_signature",
+  "build_direct_sse_url",
+  "build_direct_websocket_url",
+  "build_sse_url",
+  "build_websocket_url",
+  "to_websocket_url",
+]

restless_stream/_async_client.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping
+from typing import Any
+
+import httpx
+
+from ._constants import DEFAULT_API_BASE_URL
+from ._models import (
+  BaseActionResponse,
+  ConnectionSnippetsResponse,
+  DirectSessionResponse,
+  DirectSetupResponse,
+  Stream,
+  StreamCreditUsageStats,
+  StreamEvent,
+  StreamsResponse,
+)
+from ._resources import AsyncStreams
+from ._streaming import async_sse_events, websocket_events
+from ._urls import DEFAULT_STREAM_BASE_URL, build_direct_sse_url, build_direct_websocket_url
+from ._utils import dump_body, pop_stream_runtime_options, raise_for_status, with_api_key
+
+
+class AsyncRestlessStreamClient:
+  """Asynchronous REST, SSE, and WebSocket client."""
+
+  def __init__(
+    self,
+    api_key: str | None = None,
+    *,
+    base_url: str = DEFAULT_API_BASE_URL,
+    stream_base_url: str = DEFAULT_STREAM_BASE_URL,
+    timeout: float = 30.0,
+    http_client: httpx.AsyncClient | None = None,
+  ) -> None:
+    self.api_key = api_key
+    self.stream_base_url = stream_base_url.rstrip("/")
+    self._owns_client = http_client is None
+    self._client = http_client or httpx.AsyncClient(
+      base_url=base_url.rstrip("/"),
+      timeout=timeout,
+    )
+    if api_key:
+      self._client.headers.setdefault("x-api-key", api_key)
+    self.streams = AsyncStreams(self)
+
+  async def aclose(self) -> None:
+    if self._owns_client:
+      await self._client.aclose()
+
+  async def __aenter__(self) -> AsyncRestlessStreamClient:
+    return self
+
+  async def __aexit__(self, *_: object) -> None:
+    await self.aclose()
+
+  async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+    response = await self._client.request(method, path, **kwargs)
+    raise_for_status(response)
+    if response.status_code == 204 or not response.content:
+      return None
+    return response.json()
+
+  async def list_streams(self, *, limit: int = 20, offset: int = 0) -> StreamsResponse:
+    return StreamsResponse.model_validate(
+      await self._request("GET", "/streams", params={"limit": limit, "offset": offset})
+    )
+
+  async def get_stream(self, stream_id: str) -> Stream:
+    return Stream.model_validate(await self._request("GET", f"/streams/{stream_id}"))
+
+  async def create_stream(self, data: Mapping[str, Any] | None = None, **kwargs: Any) -> Stream:
+    body = with_api_key(dump_body(data, kwargs), self.api_key)
+    return Stream.model_validate(await self._request("POST", "/streams", json=body))
+
+  async def update_stream(
+    self, stream_id: str, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> Stream:
+    body = with_api_key(dump_body(data, kwargs), self.api_key)
+    return Stream.model_validate(await self._request("PATCH", f"/streams/{stream_id}", json=body))
+
+  async def start_stream(self, stream_id: str) -> Stream:
+    return Stream.model_validate(await self._request("POST", f"/streams/{stream_id}/start"))
+
+  async def stop_stream(self, stream_id: str) -> Stream:
+    return Stream.model_validate(await self._request("POST", f"/streams/{stream_id}/stop"))
+
+  async def delete_stream(self, stream_id: str) -> BaseActionResponse:
+    return BaseActionResponse.model_validate(await self._request("DELETE", f"/streams/{stream_id}"))
+
+  async def validate_stream_api_key(self, api_key: str | None = None) -> BaseActionResponse:
+    return BaseActionResponse.model_validate(
+      await self._request(
+        "POST", "/streams/validate-api-key", json={"apiKey": api_key or self.api_key}
+      )
+    )
+
+  async def credit_usage_stats(self, stream_id: str) -> StreamCreditUsageStats:
+    return StreamCreditUsageStats.model_validate(
+      await self._request("GET", f"/streams/{stream_id}/credit-usage-stats")
+    )
+
+  async def connection_snippets(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> ConnectionSnippetsResponse:
+    return ConnectionSnippetsResponse.model_validate(
+      await self._request("POST", "/streams/connection-snippets", json=dump_body(data, kwargs))
+    )
+
+  async def direct_setup(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> DirectSetupResponse:
+    return DirectSetupResponse.model_validate(
+      await self._request("POST", "/streams/direct/setup", json=dump_body(data, kwargs))
+    )
+
+  async def direct_session(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> DirectSessionResponse:
+    return DirectSessionResponse.model_validate(
+      await self._request("POST", "/streams/direct/sessions", json=dump_body(data, kwargs))
+    )
+
+  def subscribe_sse(self, url: str, **kwargs: Any) -> AsyncIterator[StreamEvent]:
+    return async_sse_events(self._client, url, api_key=self.api_key, **kwargs)
+
+  def subscribe_websocket(self, url: str, **kwargs: Any) -> AsyncIterator[StreamEvent]:
+    return websocket_events(url, api_key=self.api_key, **kwargs)
+
+  def subscribe_direct_sse(self, **kwargs: Any) -> AsyncIterator[StreamEvent]:
+    stream_base_url = kwargs.pop("stream_base_url", self.stream_base_url)
+    stream_options = pop_stream_runtime_options(kwargs)
+    return self.subscribe_sse(
+      build_direct_sse_url(stream_base_url=stream_base_url, **kwargs),
+      **stream_options,
+    )
+
+  def subscribe_direct_websocket(self, **kwargs: Any) -> AsyncIterator[StreamEvent]:
+    stream_base_url = kwargs.pop("stream_base_url", self.stream_base_url)
+    stream_options = pop_stream_runtime_options(kwargs, websocket=True)
+    return self.subscribe_websocket(
+      build_direct_websocket_url(stream_base_url=stream_base_url, **kwargs),
+      **stream_options,
+    )

restless_stream/_client.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from ._async_client import AsyncRestlessStreamClient
+from ._constants import DEFAULT_API_BASE_URL
+from ._sync_client import RestlessStreamClient
+
+__all__ = ["AsyncRestlessStreamClient", "DEFAULT_API_BASE_URL", "RestlessStreamClient"]

restless_stream/_constants.py

@@ -0,0 +1 @@
+DEFAULT_API_BASE_URL = "https://api.restlessapi.stream"

restless_stream/_errors.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+
+class RestlessStreamError(Exception):
+  """Base SDK exception."""
+
+
+class RestlessStreamAPIError(RestlessStreamError):
+  """Raised when the REST API returns a non-successful response."""
+
+  def __init__(self, status_code: int, message: str) -> None:
+    super().__init__(f"Restless Stream API error {status_code}: {message}")
+    self.status_code = status_code
+    self.message = message
+
+
+class RestlessStreamParseError(RestlessStreamError):
+  """Raised when a runtime event cannot be parsed."""

restless_stream/_hmac.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import hmac
+import json
+from hashlib import sha256
+from typing import Any
+
+
+def _canonical_json_bytes(value: Any) -> bytes:
+  return json.dumps(
+    value,
+    ensure_ascii=False,
+    separators=(",", ":"),
+    sort_keys=True,
+  ).encode("utf-8")
+
+
+def compute_hmac_signature(secret: str, payload: Any) -> str:
+  """Return the Restless Stream HMAC-SHA256 signature for a JSON payload."""
+
+  return hmac.new(secret.encode("utf-8"), _canonical_json_bytes(payload), sha256).hexdigest()
+
+
+def verify_hmac_signature(secret: str, payload: Any, signature: str) -> bool:
+  """Constant-time verification for a runtime event `signature` value."""
+
+  expected = compute_hmac_signature(secret, payload)
+  return hmac.compare_digest(expected, signature)

restless_stream/_models.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def to_camel(value: str) -> str:
+  head, *tail = value.split("_")
+  return head + "".join(part[:1].upper() + part[1:] for part in tail)
+
+
+class RestlessModel(BaseModel):
+  model_config = ConfigDict(
+    alias_generator=to_camel,
+    extra="allow",
+    populate_by_name=True,
+    use_enum_values=True,
+  )
+
+
+class HttpMethod(str, Enum):
+  GET = "GET"
+  POST = "POST"
+  PUT = "PUT"
+  PATCH = "PATCH"
+  DELETE = "DELETE"
+  OPTIONS = "OPTIONS"
+
+
+class StreamStatus(str, Enum):
+  ACTIVE = "ACTIVE"
+  INACTIVE = "INACTIVE"
+
+
+class PayloadMode(str, Enum):
+  FULL_DATA = "FULL_DATA"
+  JSON_PATCH = "JSON_PATCH"
+
+
+class PollingStrategy(RestlessModel):
+  start_time: str
+  end_time: str
+  interval_seconds: int
+
+
+class Stream(RestlessModel):
+  id: str
+  business_id: str | None = None
+  name: str
+  description: str | None = None
+  status: StreamStatus
+  method: HttpMethod
+  url: str
+  headers: dict[str, Any] | None = None
+  body: dict[str, Any] | None = None
+  payload_mode: PayloadMode
+  jq_filter: str | None = None
+  hmac_signature_enabled: bool = False
+  polling_interval: int
+  polling_strategies: list[PollingStrategy] | None = None
+  created_at: str | None = None
+  updated_at: str | None = None
+  ws_url: str | None = None
+  sse_url: str | None = None
+
+
+class PaginationInfo(RestlessModel):
+  has_next_page: bool = False
+
+
+class StreamsResponse(RestlessModel):
+  streams: list[Stream]
+  pagination_info: PaginationInfo = Field(default_factory=PaginationInfo)
+
+
+class BaseActionResponse(RestlessModel):
+  id: str
+  affected: bool
+
+
+class CreditUsageChargeTypeBreakdown(RestlessModel):
+  charge_type: str
+  credits_used: int
+
+
+class DailyCreditUsage(RestlessModel):
+  date: str
+  credits_used: int
+  charge_type_breakdown: list[CreditUsageChargeTypeBreakdown]
+
+
+class StreamCreditUsageStats(RestlessModel):
+  total_burned_last_week: int
+  total_burned_last_month: int
+  daily_usage: list[DailyCreditUsage]
+
+
+class SnippetSet(RestlessModel):
+  curl: str
+  wget: str
+  sse: str
+  websocket: str
+
+
+class SnippetLanguageOption(RestlessModel):
+  label: str
+  value: str
+
+
+class SnippetPayload(RestlessModel):
+  available_languages: list[SnippetLanguageOption]
+  selected_language: str
+  selected_snippets: SnippetSet
+  snippets_by_language: dict[str, SnippetSet] | None = None
+
+
+class RuntimeUrls(RestlessModel):
+  sse_url: str
+  websocket_url: str
+
+
+class ConnectionSnippetsResponse(RestlessModel):
+  runtime: RuntimeUrls
+  snippets: SnippetPayload
+
+
+class DirectCommandSet(RestlessModel):
+  curl: str
+  wget: str
+
+
+class DirectCommands(RestlessModel):
+  header: DirectCommandSet
+  url_param: DirectCommandSet
+
+
+class DirectSetupRuntimeAuth(RestlessModel):
+  api_key_location: str
+  header_example: str
+
+
+class DirectSetupRuntime(RestlessModel):
+  auth: DirectSetupRuntimeAuth
+  direct_sse_url: str
+  direct_websocket_url: str
+
+
+class DirectSetupStreamConfig(RestlessModel):
+  target_url: str
+  method: HttpMethod
+  headers: dict[str, Any] | None = None
+  body: dict[str, Any] | None = None
+  jq_filter: str | None = None
+  payload_mode: PayloadMode | None = None
+  polling_interval: int | None = None
+  polling_strategies: list[PollingStrategy] | None = None
+
+
+class DirectSetupResponse(RestlessModel):
+  commands: DirectCommands
+  runtime: DirectSetupRuntime
+  snippets: SnippetPayload
+  stream_config: DirectSetupStreamConfig
+
+
+class DirectSessionResponse(RestlessModel):
+  session_id: str
+  ws_url: str
+  sse_url: str
+  expires_at: str
+  created: bool
+  dedupe_key: str
+
+
+class StreamEventMeta(RestlessModel):
+  timestamp: str
+  attempt_id: str | None = None
+  status: int | None = None
+  latency_ms: int | None = None
+  payload_mode_fallback: str | None = None
+
+
+class StreamErrorDetail(RestlessModel):
+  code: str
+  message: str
+
+
+class StreamEvent(RestlessModel):
+  type: str
+  meta: StreamEventMeta
+  data: Any | None = None
+  error: StreamErrorDetail | None = None
+  signature: str | None = None
+  event_id: str | None = None

restless_stream/_resources.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import TYPE_CHECKING, Any
+
+from ._models import (
+  BaseActionResponse,
+  ConnectionSnippetsResponse,
+  DirectSessionResponse,
+  DirectSetupResponse,
+  Stream,
+  StreamCreditUsageStats,
+  StreamEvent,
+  StreamsResponse,
+)
+
+if TYPE_CHECKING:
+  from ._async_client import AsyncRestlessStreamClient
+  from ._sync_client import RestlessStreamClient
+
+
+class SyncStreams:
+  def __init__(self, client: RestlessStreamClient) -> None:
+    self._client = client
+
+  def list(self, **kwargs: Any) -> StreamsResponse:
+    return self._client.list_streams(**kwargs)
+
+  def get(self, stream_id: str) -> Stream:
+    return self._client.get_stream(stream_id)
+
+  def create(self, data: Mapping[str, Any] | None = None, **kwargs: Any) -> Stream:
+    return self._client.create_stream(data, **kwargs)
+
+  def update(self, stream_id: str, data: Mapping[str, Any] | None = None, **kwargs: Any) -> Stream:
+    return self._client.update_stream(stream_id, data, **kwargs)
+
+  def start(self, stream_id: str) -> Stream:
+    return self._client.start_stream(stream_id)
+
+  def stop(self, stream_id: str) -> Stream:
+    return self._client.stop_stream(stream_id)
+
+  def delete(self, stream_id: str) -> BaseActionResponse:
+    return self._client.delete_stream(stream_id)
+
+  def validate_api_key(self, api_key: str | None = None) -> BaseActionResponse:
+    return self._client.validate_stream_api_key(api_key)
+
+  def credit_usage_stats(self, stream_id: str) -> StreamCreditUsageStats:
+    return self._client.credit_usage_stats(stream_id)
+
+  def connection_snippets(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> ConnectionSnippetsResponse:
+    return self._client.connection_snippets(data, **kwargs)
+
+  def direct_setup(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> DirectSetupResponse:
+    return self._client.direct_setup(data, **kwargs)
+
+  def direct_session(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> DirectSessionResponse:
+    return self._client.direct_session(data, **kwargs)
+
+  def subscribe_sse(self, url: str, **kwargs: Any) -> Iterator[StreamEvent]:
+    return self._client.subscribe_sse(url, **kwargs)
+
+  def subscribe_direct_sse(self, **kwargs: Any) -> Iterator[StreamEvent]:
+    return self._client.subscribe_direct_sse(**kwargs)
+
+
+class AsyncStreams:
+  def __init__(self, client: AsyncRestlessStreamClient) -> None:
+    self._client = client
+
+  async def list(self, **kwargs: Any) -> StreamsResponse:
+    return await self._client.list_streams(**kwargs)
+
+  async def get(self, stream_id: str) -> Stream:
+    return await self._client.get_stream(stream_id)
+
+  async def create(self, data: Mapping[str, Any] | None = None, **kwargs: Any) -> Stream:
+    return await self._client.create_stream(data, **kwargs)
+
+  async def update(
+    self, stream_id: str, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> Stream:
+    return await self._client.update_stream(stream_id, data, **kwargs)
+
+  async def start(self, stream_id: str) -> Stream:
+    return await self._client.start_stream(stream_id)
+
+  async def stop(self, stream_id: str) -> Stream:
+    return await self._client.stop_stream(stream_id)
+
+  async def delete(self, stream_id: str) -> BaseActionResponse:
+    return await self._client.delete_stream(stream_id)
+
+  async def validate_api_key(self, api_key: str | None = None) -> BaseActionResponse:
+    return await self._client.validate_stream_api_key(api_key)
+
+  async def credit_usage_stats(self, stream_id: str) -> StreamCreditUsageStats:
+    return await self._client.credit_usage_stats(stream_id)
+
+  async def connection_snippets(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> ConnectionSnippetsResponse:
+    return await self._client.connection_snippets(data, **kwargs)
+
+  async def direct_setup(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> DirectSetupResponse:
+    return await self._client.direct_setup(data, **kwargs)
+
+  async def direct_session(
+    self, data: Mapping[str, Any] | None = None, **kwargs: Any
+  ) -> DirectSessionResponse:
+    return await self._client.direct_session(data, **kwargs)
+
+  def subscribe_sse(self, url: str, **kwargs: Any) -> AsyncIterator[StreamEvent]:
+    return self._client.subscribe_sse(url, **kwargs)
+
+  def subscribe_websocket(self, url: str, **kwargs: Any) -> AsyncIterator[StreamEvent]:
+    return self._client.subscribe_websocket(url, **kwargs)
+
+  def subscribe_direct_sse(self, **kwargs: Any) -> AsyncIterator[StreamEvent]:
+    return self._client.subscribe_direct_sse(**kwargs)
+
+  def subscribe_direct_websocket(self, **kwargs: Any) -> AsyncIterator[StreamEvent]:
+    return self._client.subscribe_direct_websocket(**kwargs)