elastly 0.1.0__tar.gz → 0.2.0__tar.gz

{elastly-0.1.0 → elastly-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: elastly
-Version: 0.1.0
+Version: 0.2.0
 Summary: Elastly API
 Home-page: https://elastly.io/docs/sdk
 Author: Elastly
@@ -82,6 +82,53 @@ Every response line is either a priced result (`ok` is true) or a per-line error
 
 `POST /v1/prices` requires an `Idempotency-Key` header. Use a fresh key for each logical request and reuse the same key on retries. A replay returns the stored response, so a retried call never prices twice.
 
+## Price with a deadline and a fallback
+
+If you price inside a checkout or quote flow, use the serving layer instead of calling the API directly. It puts a hard deadline on the call (800ms by default), retries transient failures with backoff, trips a circuit breaker when Elastly is down (5 failures, 30 second cooldown), and falls back to a price you supply instead of blocking your flow.
+
+```python
+import elastly
+from elastly.serving import FallbackPrice, PricesNamespace, static_fallback
+from elastly.transport import ElastlyTransport
+
+configuration = elastly.Configuration(access_token="elastly_live_...")
+client = elastly.ApiClient(configuration)
+prices = PricesNamespace(ElastlyTransport(client))
+
+result = prices.get(
+    elastly.PricesRequestLinesInner(product_sku="SKU-1042", quantity=25),
+    fail_open=static_fallback(lambda line, cause: FallbackPrice(price_cents=1500)),
+)
+
+if result.source == "elastly":
+    print(result.price_cents, result.reason_summary)
+elif result.source == "fallback":
+    print(result.price_cents, "fallback because", result.cause.reason)
+else:
+    print("no price available:", result.cause.reason)
+```
+
+Every result carries a `source`: `"elastly"` (a real price), `"fallback"` (your resolver's price), or `"unavailable"` (your resolver returned `None`). Mistakes on your side, like an invalid request or a bad key, always raise a typed error from `elastly.errors` instead of falling back. Prefer an exception over a fallback price? Pass `fail_open=throw_on_failure()`.
+
+The transport handles retries and idempotency keys for you, so you do not need to manage the `Idempotency-Key` header yourself on this path.
+
+## Verify webhooks
+
+Verify the `elastly-signature` header on every webhook before trusting the payload:
+
+```python
+from elastly.webhooks import SignatureVerificationError, WebhooksNamespace
+
+webhooks = WebhooksNamespace()
+try:
+    event = webhooks.verify(raw_body, signature_header, "whsec_...")
+except SignatureVerificationError:
+    ...  # reject with a 400
+print(event.event, event.data)
+```
+
+`verify` checks the HMAC signature in constant time, rejects replays older than 5 minutes, and returns a typed event.
+
 ## Close the loop
 
 Elastly learns from the difference between the price it recommended and the price your team actually charged. When you ingest quotes, echo the `pricingDecisionId` you received from the prices call on the matching quote line. Skip that and the engine has nothing to learn from.

{elastly-0.1.0 → elastly-0.2.0}/README.md

@@ -61,6 +61,53 @@ Every response line is either a priced result (`ok` is true) or a per-line error
 
 `POST /v1/prices` requires an `Idempotency-Key` header. Use a fresh key for each logical request and reuse the same key on retries. A replay returns the stored response, so a retried call never prices twice.
 
+## Price with a deadline and a fallback
+
+If you price inside a checkout or quote flow, use the serving layer instead of calling the API directly. It puts a hard deadline on the call (800ms by default), retries transient failures with backoff, trips a circuit breaker when Elastly is down (5 failures, 30 second cooldown), and falls back to a price you supply instead of blocking your flow.
+
+```python
+import elastly
+from elastly.serving import FallbackPrice, PricesNamespace, static_fallback
+from elastly.transport import ElastlyTransport
+
+configuration = elastly.Configuration(access_token="elastly_live_...")
+client = elastly.ApiClient(configuration)
+prices = PricesNamespace(ElastlyTransport(client))
+
+result = prices.get(
+    elastly.PricesRequestLinesInner(product_sku="SKU-1042", quantity=25),
+    fail_open=static_fallback(lambda line, cause: FallbackPrice(price_cents=1500)),
+)
+
+if result.source == "elastly":
+    print(result.price_cents, result.reason_summary)
+elif result.source == "fallback":
+    print(result.price_cents, "fallback because", result.cause.reason)
+else:
+    print("no price available:", result.cause.reason)
+```
+
+Every result carries a `source`: `"elastly"` (a real price), `"fallback"` (your resolver's price), or `"unavailable"` (your resolver returned `None`). Mistakes on your side, like an invalid request or a bad key, always raise a typed error from `elastly.errors` instead of falling back. Prefer an exception over a fallback price? Pass `fail_open=throw_on_failure()`.
+
+The transport handles retries and idempotency keys for you, so you do not need to manage the `Idempotency-Key` header yourself on this path.
+
+## Verify webhooks
+
+Verify the `elastly-signature` header on every webhook before trusting the payload:
+
+```python
+from elastly.webhooks import SignatureVerificationError, WebhooksNamespace
+
+webhooks = WebhooksNamespace()
+try:
+    event = webhooks.verify(raw_body, signature_header, "whsec_...")
+except SignatureVerificationError:
+    ...  # reject with a 400
+print(event.event, event.data)
+```
+
+`verify` checks the HMAC signature in constant time, rejects replays older than 5 minutes, and returns a typed event.
+
 ## Close the loop
 
 Elastly learns from the difference between the price it recommended and the price your team actually charged. When you ingest quotes, echo the `pricingDecisionId` you received from the prices call on the matching quote line. Skip that and the engine has nothing to learn from.

{elastly-0.1.0 → elastly-0.2.0}/elastly/__init__.py

@@ -15,7 +15,7 @@
 """  # noqa: E501
 
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 # Define package exports
 __all__ = [

{elastly-0.1.0 → elastly-0.2.0}/elastly/api_client.py

@@ -92,7 +92,7 @@ class ApiClient:
             self.default_headers[header_name] = header_value
         self.cookie = cookie
         # Set default User-Agent.
-        self.user_agent = 'OpenAPI-Generator/0.1.0/python'
+        self.user_agent = 'OpenAPI-Generator/0.2.0/python'
         self.client_side_validation = configuration.client_side_validation
 
     def __enter__(self):

{elastly-0.1.0 → elastly-0.2.0}/elastly/configuration.py

@@ -534,7 +534,7 @@ class Configuration:
                "OS: {env}\n"\
                "Python Version: {pyversion}\n"\
                "Version of the API: 1.0.0\n"\
-               "SDK Package Version: 0.1.0".\
+               "SDK Package Version: 0.2.0".\
                format(env=sys.platform, pyversion=sys.version)
 
     def get_host_settings(self) -> List[HostSetting]:

elastly-0.2.0/elastly/connector/__init__.py

@@ -0,0 +1,84 @@
+"""Connector framework: define a connector once, get resumable sync and lease-safe write-backs."""
+
+from elastly.connector.checkpoints import FileCheckpointStore, InMemoryCheckpointStore
+from elastly.connector.client import (
+    DEFAULT_DRAIN_TIMEOUT_MS,
+    DEFAULT_POLL_INTERVAL_MS,
+    MAX_RECORDS_PER_CALL,
+    DrainTimeoutError,
+    ElastlyConnectorClient,
+    IngestClient,
+    WritebacksClient,
+    connector_client,
+)
+from elastly.connector.ports import (
+    INGEST_ENTITIES,
+    AckOutcome,
+    BatchCreated,
+    BatchStatus,
+    CheckpointStore,
+    CommitResult,
+    ConnectorClient,
+    ConnectorIngestClient,
+    ConnectorWritebacksClient,
+    ElastlyConnector,
+    IngestEntity,
+    Page,
+    Record,
+    StageResult,
+    WritebackResult,
+    WritebackTask,
+)
+from elastly.connector.runtime import (
+    BATCH_CHECKPOINT_KEY,
+    DEFAULT_FETCH_RETRY_POLICY,
+    DEFAULT_LEASE_SAFETY_MS,
+    ConnectorDefinition,
+    ConnectorRuntimeEvent,
+    ConnectorSyncError,
+    ConnectorWarning,
+    DrainReport,
+    FetchRetryPolicy,
+    SyncReport,
+    define_connector,
+)
+
+__all__ = [
+    "AckOutcome",
+    "BATCH_CHECKPOINT_KEY",
+    "BatchCreated",
+    "BatchStatus",
+    "CheckpointStore",
+    "CommitResult",
+    "ConnectorClient",
+    "ConnectorDefinition",
+    "ConnectorIngestClient",
+    "ConnectorRuntimeEvent",
+    "ConnectorSyncError",
+    "ConnectorWarning",
+    "ConnectorWritebacksClient",
+    "DEFAULT_DRAIN_TIMEOUT_MS",
+    "DEFAULT_FETCH_RETRY_POLICY",
+    "DEFAULT_LEASE_SAFETY_MS",
+    "DEFAULT_POLL_INTERVAL_MS",
+    "DrainReport",
+    "DrainTimeoutError",
+    "ElastlyConnector",
+    "ElastlyConnectorClient",
+    "FetchRetryPolicy",
+    "FileCheckpointStore",
+    "INGEST_ENTITIES",
+    "IngestClient",
+    "IngestEntity",
+    "InMemoryCheckpointStore",
+    "MAX_RECORDS_PER_CALL",
+    "Page",
+    "Record",
+    "StageResult",
+    "SyncReport",
+    "WritebackResult",
+    "WritebackTask",
+    "WritebacksClient",
+    "connector_client",
+    "define_connector",
+]

elastly-0.2.0/elastly/connector/checkpoints.py

@@ -0,0 +1,53 @@
+"""Checkpoint stores: cursor persistence so an interrupted sync resumes, not restarts."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, Optional, Union
+
+
+class InMemoryCheckpointStore:
+    def __init__(self) -> None:
+        self._cursors: Dict[str, str] = {}
+
+    def get(self, key: str) -> Optional[str]:
+        return self._cursors.get(key)
+
+    def set(self, key: str, cursor: Optional[str]) -> None:
+        if cursor is None:
+            self._cursors.pop(key, None)
+        else:
+            self._cursors[key] = cursor
+
+
+class FileCheckpointStore:
+    """JSON-file store; writes go to a temp file then an atomic rename."""
+
+    def __init__(self, file_path: Union[str, "os.PathLike[str]"]) -> None:
+        self._path = Path(file_path)
+
+    def get(self, key: str) -> Optional[str]:
+        return self._read().get(key)
+
+    def set(self, key: str, cursor: Optional[str]) -> None:
+        cursors = self._read()
+        if cursor is None:
+            cursors.pop(key, None)
+        else:
+            cursors[key] = cursor
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        temporary_path = self._path.with_name(f"{self._path.name}.tmp")
+        temporary_path.write_text(json.dumps(cursors, indent=2) + "\n", encoding="utf-8")
+        os.replace(temporary_path, self._path)
+
+    def _read(self) -> Dict[str, str]:
+        try:
+            raw = self._path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return {}
+        parsed = json.loads(raw)
+        if not isinstance(parsed, dict):
+            return {}
+        return {key: value for key, value in parsed.items() if isinstance(value, str)}

elastly-0.2.0/elastly/connector/client.py

@@ -0,0 +1,183 @@
+"""Concrete connector client composed over the generated ingest and write-back APIs."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, List, Optional, Sequence, TypeVar
+from uuid import UUID
+
+from elastly.api.ingest_api import IngestApi
+from elastly.api.writebacks_api import WritebacksApi
+from elastly.connector.ports import (
+    AckOutcome,
+    BatchCreated,
+    BatchStatus,
+    CommitResult,
+    IngestEntity,
+    Record,
+    StageResult,
+    WritebackResult,
+    WritebackTask,
+)
+from elastly.errors import ElastlyError
+from elastly.exceptions import ApiException
+from elastly.models.claim_writebacks_request import ClaimWritebacksRequest
+from elastly.models.stage_records_request import StageRecordsRequest
+from elastly.models.writeback_ack_request import WritebackAckRequest
+from elastly.models.writeback_ack_request_results_inner import WritebackAckRequestResultsInner
+from elastly.transport import error_from_api_exception
+
+MAX_RECORDS_PER_CALL = 1000
+DEFAULT_POLL_INTERVAL_MS = 2_000.0
+DEFAULT_DRAIN_TIMEOUT_MS = 600_000.0
+
+R = TypeVar("R")
+
+
+class DrainTimeoutError(ElastlyError):
+    def __init__(self, batch_id: str, timeout_ms: float) -> None:
+        super().__init__(f"Batch {batch_id} did not drain within {timeout_ms:g}ms.", None)
+        self.batch_id = batch_id
+        self.timeout_ms = timeout_ms
+
+
+def _monotonic_ms() -> float:
+    return time.monotonic() * 1000.0
+
+
+def _default_sleep(ms: float) -> None:
+    if ms > 0:
+        time.sleep(ms / 1000.0)
+
+
+def _call(operation: Callable[[], R]) -> R:
+    try:
+        return operation()
+    except ApiException as exc:
+        error, _ = error_from_api_exception(exc)
+        raise error from exc
+
+
+class IngestClient:
+    def __init__(
+        self,
+        api: IngestApi,
+        *,
+        clock: Optional[Callable[[], float]] = None,
+        sleep: Optional[Callable[[float], None]] = None,
+    ) -> None:
+        self._api = api
+        self._clock = clock if clock is not None else _monotonic_ms
+        self._sleep = sleep if sleep is not None else _default_sleep
+
+    def open_batch(self) -> BatchCreated:
+        response = _call(self._api.create_ingest_batch)
+        return BatchCreated(batch_id=response.batch_id, connector_id=response.connector_id)
+
+    def stage(
+        self, batch_id: str, entity: IngestEntity, records: Sequence[Record]
+    ) -> StageResult:
+        staged = 0
+        for offset in range(0, len(records), MAX_RECORDS_PER_CALL):
+            chunk = records[offset:offset + MAX_RECORDS_PER_CALL]
+            # model_construct skips client-side validation on purpose: the generated
+            # date-time regex validators run after pydantic coerces the string to a
+            # datetime, so every valid RFC3339 quote/order timestamp is rejected.
+            # The server validates the payload; this matches the TypeScript SDK.
+            request = StageRecordsRequest.model_construct(
+                actual_instance={"entity": entity, "records": [dict(record) for record in chunk]}
+            )
+            response = _call(lambda: self._api.stage_ingest_records(UUID(batch_id), request))
+            staged += response.staged
+        return StageResult(staged=staged)
+
+    def commit(self, batch_id: str) -> CommitResult:
+        response = _call(lambda: self._api.commit_ingest_batch(UUID(batch_id)))
+        return CommitResult(job_id=response.job_id)
+
+    def status(self, batch_id: str) -> BatchStatus:
+        response = _call(lambda: self._api.get_ingest_batch_status(UUID(batch_id)))
+        return BatchStatus(
+            status=response.status,
+            entities=tuple(response.entities),
+            record_count=response.record_count,
+            skipped_over_cap=response.skipped_over_cap,
+            error=response.error,
+        )
+
+    def wait_for_drain(
+        self,
+        batch_id: str,
+        *,
+        poll_interval_ms: Optional[float] = None,
+        timeout_ms: Optional[float] = None,
+        sleep: Optional[Callable[[float], None]] = None,
+    ) -> BatchStatus:
+        poll = max(
+            1.0, poll_interval_ms if poll_interval_ms is not None else DEFAULT_POLL_INTERVAL_MS
+        )
+        timeout = max(0.0, timeout_ms if timeout_ms is not None else DEFAULT_DRAIN_TIMEOUT_MS)
+        sleep_fn = sleep if sleep is not None else self._sleep
+        started = self._clock()
+        while True:
+            status = self.status(batch_id)
+            if status.status in ("drained", "failed"):
+                return status
+            remaining = timeout - (self._clock() - started)
+            if remaining <= 0:
+                raise DrainTimeoutError(batch_id, timeout)
+            sleep_fn(min(poll, remaining))
+
+
+class WritebacksClient:
+    def __init__(self, api: WritebacksApi) -> None:
+        self._api = api
+
+    def claim(self, limit: Optional[int] = None) -> Sequence[WritebackTask]:
+        request = ClaimWritebacksRequest() if limit is None else ClaimWritebacksRequest(limit=limit)
+        response = _call(lambda: self._api.claim_writebacks(request))
+        return [
+            WritebackTask(
+                id=task.id,
+                product_sku=task.product_sku,
+                product_external_id=task.product_external_id,
+                price_cents=task.price_cents,
+                currency=task.currency,
+                lease_until=task.lease_until,
+                exchange_rate_to_base=task.exchange_rate_to_base,
+                reason_summary=task.reason_summary,
+                pricing_decision_id=task.pricing_decision_id,
+                target=task.target,
+            )
+            for task in response.tasks
+        ]
+
+    def ack(self, results: Sequence[WritebackResult]) -> AckOutcome:
+        if not results:
+            return AckOutcome(applied=0, failed=0, expired=0)
+        inner: List[WritebackAckRequestResultsInner] = [
+            WritebackAckRequestResultsInner(id=result.id, ok=result.ok, error=result.error)
+            for result in results
+        ]
+        response = _call(lambda: self._api.ack_writebacks(WritebackAckRequest(results=inner)))
+        return AckOutcome(
+            applied=response.applied, failed=response.failed, expired=response.expired
+        )
+
+
+class ElastlyConnectorClient:
+    def __init__(
+        self,
+        api_client: Any,
+        *,
+        ingest: Optional[IngestClient] = None,
+        writebacks: Optional[WritebacksClient] = None,
+    ) -> None:
+        self.ingest = ingest if ingest is not None else IngestClient(IngestApi(api_client))
+        self.writebacks = (
+            writebacks if writebacks is not None else WritebacksClient(WritebacksApi(api_client))
+        )
+
+
+def connector_client(api_client: Any) -> ElastlyConnectorClient:
+    return ElastlyConnectorClient(api_client)

elastly-0.2.0/elastly/connector/ports.py

@@ -0,0 +1,138 @@
+"""Narrow ports the connector runtime depends on, mirroring the TypeScript SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Literal,
+    Mapping,
+    Optional,
+    Protocol,
+    Sequence,
+    Tuple,
+    TypeVar,
+)
+
+IngestEntity = Literal["product", "customer", "quote", "order"]
+
+INGEST_ENTITIES: Tuple[IngestEntity, ...] = ("product", "customer", "quote", "order")
+
+Record = Mapping[str, Any]
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    records: Sequence[T]
+    next_cursor: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class BatchCreated:
+    batch_id: str
+    connector_id: str
+
+
+@dataclass(frozen=True)
+class StageResult:
+    staged: int
+
+
+@dataclass(frozen=True)
+class CommitResult:
+    job_id: str
+
+
+@dataclass(frozen=True)
+class BatchStatus:
+    status: str
+    entities: Sequence[str] = ()
+    record_count: int = 0
+    skipped_over_cap: int = 0
+    error: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class WritebackTask:
+    id: str
+    product_sku: str
+    product_external_id: str
+    price_cents: float
+    currency: str
+    lease_until: str
+    exchange_rate_to_base: Optional[float] = None
+    reason_summary: Optional[str] = None
+    pricing_decision_id: Optional[str] = None
+    target: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class WritebackResult:
+    id: str
+    ok: bool
+    error: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class AckOutcome:
+    applied: int
+    failed: int
+    expired: int
+
+
+class ElastlyConnector(Protocol):
+    """The user-implemented connector port.
+
+    ``fetch_quotes``, ``fetch_orders``, and ``apply_price`` are optional
+    capabilities: the runtime discovers them with ``getattr`` so a connector
+    only implements what its source system supports.
+    """
+
+    def fetch_products(self, cursor: Optional[str]) -> Page[Record]: ...
+
+    def fetch_customers(self, cursor: Optional[str]) -> Page[Record]: ...
+
+
+class CheckpointStore(Protocol):
+    def get(self, key: str) -> Optional[str]: ...
+
+    def set(self, key: str, cursor: Optional[str]) -> None: ...
+
+
+class ConnectorIngestClient(Protocol):
+    def open_batch(self) -> BatchCreated: ...
+
+    def stage(
+        self, batch_id: str, entity: IngestEntity, records: Sequence[Record]
+    ) -> StageResult: ...
+
+    def commit(self, batch_id: str) -> CommitResult: ...
+
+    def status(self, batch_id: str) -> BatchStatus: ...
+
+    def wait_for_drain(
+        self,
+        batch_id: str,
+        *,
+        poll_interval_ms: Optional[float] = None,
+        timeout_ms: Optional[float] = None,
+        sleep: Optional[Callable[[float], None]] = None,
+    ) -> BatchStatus: ...
+
+
+class ConnectorWritebacksClient(Protocol):
+    def claim(self, limit: Optional[int] = None) -> Sequence[WritebackTask]: ...
+
+    def ack(self, results: Sequence[WritebackResult]) -> AckOutcome: ...
+
+
+class ConnectorClient(Protocol):
+    @property
+    def ingest(self) -> ConnectorIngestClient: ...
+
+    @property
+    def writebacks(self) -> ConnectorWritebacksClient: ...