smklog-sdk 0.1.0__py3-none-any.whl

smklog/__init__.py

@@ -0,0 +1,50 @@
+"""Official Python client for the SMKlog Quote API: https://smklog.com/developers/
+
+    from smklog import SmklogClient
+    quote = SmklogClient().get_parcel_quote(product="paperback books",
+                                             from_postal_code="07030", to_postal_code="33101")
+"""
+
+from ._version import __version__
+from .client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, SmklogClient
+from .errors import (
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitedError,
+    SessionFailedError,
+    SmklogError,
+)
+from .models import (
+    Checkout,
+    CheckoutSession,
+    CheckoutSessionRequest,
+    CheckoutStatus,
+    Liveness,
+    Package,
+    Problem,
+    QuoteRequest,
+    QuoteResponse,
+    Rate,
+)
+
+__all__ = [
+    "__version__",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "SmklogClient",
+    "SmklogError",
+    "RateLimitedError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "SessionFailedError",
+    "QuoteRequest",
+    "QuoteResponse",
+    "Rate",
+    "Package",
+    "CheckoutSessionRequest",
+    "CheckoutSession",
+    "Checkout",
+    "CheckoutStatus",
+    "Liveness",
+    "Problem",
+]

smklog/__main__.py

@@ -0,0 +1,7 @@
+"""Lets ``python -m smklog`` behave like the ``smklog`` console script."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

smklog/_version.py

@@ -0,0 +1,3 @@
+# Kept in its own module so both the package root and the client's User-Agent
+# can read it without importing each other.
+__version__ = "0.1.0"

smklog/cli.py

@@ -0,0 +1,283 @@
+"""The ``smklog`` command line: one subcommand per API operation.
+
+    smklog quote "Yamaha FG800 acoustic guitar in a hard case" 07102 30303 [--country US] [--qty 1]
+                 [--dims 112x48x20 --kg 6.4] [--json]
+    smklog session --quote-id q_... [--service "USPS Ground Advantage"] [--json]
+    smklog session-status as_... [--json]
+    smklog status [--json]
+
+Human output is a small table; ``--json`` prints the raw answer. A priced quote also
+prints its quote_id on its own line, ready for ``smklog session --quote-id``.
+
+Exit codes: 0 for a priced answer or a successful read, 2 when the API refuses (the
+Problem is printed) or answers a quote without a price, 3 on a rate limit, 1 when the
+host could not be reached.
+"""
+
+import argparse
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+from ._version import __version__
+from .client import DEFAULT_BASE_URL, SmklogClient
+from .errors import RateLimitedError, SmklogError
+from .models import CheckoutSession, CheckoutStatus, Liveness, QuoteResponse
+
+Number = Union[int, float]
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    client = SmklogClient(base_url=args.base_url, token=args.token or None)
+    try:
+        return args.run(client, args)
+    except RateLimitedError as exc:
+        _print_problem(exc, args.json)
+        return 3
+    except SmklogError as exc:
+        _print_problem(exc, args.json)
+        return 1 if exc.error == "network_error" else 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="smklog",
+        description="Live parcel rates from the SMKlog Quote API. No key needed; every quote spends a carrier rating, so quote once per shipment.",
+    )
+    parser.add_argument("--version", action="version", version="smklog-sdk " + __version__)
+    # Shared flags live on each subcommand so they can follow it, as the usage lines show.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="print the raw JSON answer instead of a table")
+    common.add_argument("--base-url", default=os.environ.get("SMKLOG_BASE_URL", DEFAULT_BASE_URL),
+                        help="API host (default %(default)s; env SMKLOG_BASE_URL)")
+    common.add_argument("--token", default=os.environ.get("SMKLOG_TOKEN", ""),
+                        help="optional OAuth bearer for a dedicated rate-limit bucket (env SMKLOG_TOKEN)")
+
+    commands = parser.add_subparsers(dest="command", metavar="command", required=True)
+
+    quote = commands.add_parser("quote", parents=[common], help="price one parcel")
+    quote.add_argument("product", help='the item in plain words, e.g. "paperback books"')
+    quote.add_argument("from_zip", help="5-digit US origin ZIP")
+    quote.add_argument("to_zip", help="destination ZIP or postal code")
+    quote.add_argument("--country", default="US", help="destination country: US, CA, GB, DE or AU (default US)")
+    quote.add_argument("--qty", type=int, default=1, help="units shipping together (default 1)")
+    quote.add_argument("--dims", type=_dims, metavar="LxWxH", help="packed box in cm, e.g. 30x22x12 (needs --kg)")
+    quote.add_argument("--kg", type=_number, help="packed weight in kg (needs --dims)")
+    quote.set_defaults(run=_cmd_quote)
+
+    session = commands.add_parser("session", parents=[common], help="open a checkout for a human from a quote")
+    session.add_argument("--quote-id", required=True, help="quote_id printed by `smklog quote`, valid 15 minutes")
+    session.add_argument("--service", help='anchor the amount to a service, e.g. "USPS Ground Advantage"')
+    session.set_defaults(run=_cmd_session)
+
+    session_status = commands.add_parser("session-status", parents=[common], help="where a checkout stands")
+    session_status.add_argument("session_id", help="session_id from `smklog session`")
+    session_status.set_defaults(run=_cmd_session_status)
+
+    status = commands.add_parser("status", parents=[common], help="liveness and the serving version")
+    status.set_defaults(run=_cmd_status)
+    return parser
+
+
+def _cmd_quote(client: SmklogClient, args: argparse.Namespace) -> int:
+    if (args.dims is None) != (args.kg is None):
+        raise SmklogError(0, "invalid_request", "--dims and --kg go together.")
+    fields: Dict[str, Any] = {
+        "product": args.product,
+        "from_postal_code": args.from_zip,
+        "to_postal_code": args.to_zip,
+        "quantity": args.qty,
+    }
+    # US is the API's default, so it is only sent when the caller asked for elsewhere.
+    if args.country.upper() != "US":
+        fields["to_country_code"] = args.country.upper()
+    if args.dims is not None:
+        fields.update(zip(("length_cm", "width_cm", "height_cm"), args.dims))
+        fields["weight_kg"] = args.kg
+    quote = client.get_parcel_quote(**fields)
+    if args.json:
+        _print_json(quote.raw)
+    else:
+        _print_quote(quote)
+    return 0 if quote.is_priced() else 2
+
+
+def _cmd_session(client: SmklogClient, args: argparse.Namespace) -> int:
+    fields: Dict[str, Any] = {"quote_id": args.quote_id}
+    if args.service:
+        fields["service"] = args.service
+    session = client.create_payment_session(**fields)
+    if args.json:
+        _print_json(session.raw)
+    else:
+        _print_session(session)
+    return 0
+
+
+def _cmd_session_status(client: SmklogClient, args: argparse.Namespace) -> int:
+    status = client.get_checkout_status(args.session_id)
+    if args.json:
+        _print_json(status.raw)
+    else:
+        _print_session_status(status)
+    return 0
+
+
+def _cmd_status(client: SmklogClient, args: argparse.Namespace) -> int:
+    liveness = client.status()
+    if args.json:
+        _print_json(liveness.raw)
+    else:
+        _print_rows([
+            ("ok", _yes_no(liveness.ok)),
+            ("service", liveness.service),
+            ("version", liveness.version),
+            ("time", liveness.time),
+        ])
+    return 0
+
+
+def _print_quote(quote: QuoteResponse) -> None:
+    if quote.identified_product_title:
+        print(quote.identified_product_title)
+    box = quote.package
+    if box is not None and box.length_cm is not None:
+        origin = "exact" if box.confidence == "manual" else "estimate, %s confidence" % (box.confidence or "unknown")
+        print("Box: %s x %s x %s cm, %s kg (%s)" % (
+            _num(box.length_cm), _num(box.width_cm), _num(box.height_cm), _num(box.weight_kg), origin))
+    if not quote.is_priced():
+        print("No price: %s. %s" % (quote.mode, quote.notice or "The service did not price this shipment."))
+    else:
+        rows = [("Carrier", "Service", "Checkout", "Counter", "Delivery")]
+        for rate in quote.rates:
+            rows.append((rate.carrier or "", rate.service or "", _money(rate.amount), _money(rate.retail_amount), _delivery(rate)))
+        _print_table(rows)
+    if quote.quote_id:
+        # On its own line so it can be copied straight into `smklog session --quote-id`.
+        print("quote_id  %s" % quote.quote_id)
+
+
+def _print_session(session: CheckoutSession) -> None:
+    _print_rows([
+        ("session_id", session.session_id),
+        ("amount", _money(session.amount, session.currency)),
+        ("service", session.service),
+        ("quote_reused", _yes_no(session.quote_reused)),
+        ("handoff_url", session.handoff_url),
+        ("note", session.note),
+    ])
+
+
+def _print_session_status(status: CheckoutStatus) -> None:
+    checkout = status.checkout
+    rows: List[Tuple[str, Any]] = [
+        ("session_id", status.session_id),
+        ("status", status.status),
+        ("amount", _money(status.amount, status.currency)),
+        ("service", status.service),
+        ("expires_at", status.expires_at),
+    ]
+    if checkout is not None:
+        carrier = " ".join(part for part in (checkout.carrier, checkout.service) if part)
+        rows += [
+            ("order_id", checkout.order_id),
+            ("paid", _yes_no(checkout.paid)),
+            ("label_ready", _yes_no(checkout.label_ready)),
+            ("refunded", _yes_no(checkout.refunded)),
+            ("carrier", carrier or None),
+            ("tracking_number", checkout.tracking_number),
+            ("tracking_status", checkout.tracking_status),
+            ("estimated_delivery", checkout.estimated_delivery),
+            ("delivered_at", checkout.delivered_at),
+        ]
+    rows.append(("next", status.next))
+    _print_rows(rows)
+
+
+def _print_problem(exc: SmklogError, as_json: bool) -> None:
+    if as_json:
+        _print_json(exc.problem())
+        return
+    line = "error: %s" % exc.error
+    if exc.status:
+        line += " (HTTP %d)" % exc.status
+    if exc.message:
+        line += ": " + exc.message
+    print(line, file=sys.stderr)
+    if exc.missing:
+        print("missing: " + ", ".join(exc.missing), file=sys.stderr)
+
+
+def _print_json(data: Any) -> None:
+    print(json.dumps(data, indent=2))
+
+
+def _print_rows(rows: Sequence[Tuple[str, Any]]) -> None:
+    present = [(key, value) for key, value in rows if value is not None and value != ""]
+    width = max(len(key) for key, _ in present) if present else 0
+    for key, value in present:
+        print("%-*s  %s" % (width, key, value))
+
+
+def _print_table(rows: Sequence[Sequence[str]]) -> None:
+    widths = [max(len(row[i]) for row in rows) for i in range(len(rows[0]))]
+    for row in rows:
+        print("  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip())
+
+
+def _delivery(rate: Any) -> str:
+    parts = []
+    if rate.delivery_window:
+        parts.append(str(rate.delivery_window))
+    elif rate.delivery_days is not None:
+        parts.append("%s day%s" % (rate.delivery_days, "" if rate.delivery_days == 1 else "s"))
+    if rate.delivery_estimated_date:
+        parts.append("by %s" % rate.delivery_estimated_date)
+    return ", ".join(parts)
+
+
+def _money(amount: Optional[Number], currency: Optional[str] = None) -> str:
+    if amount is None:
+        return ""
+    text = "$%.2f" % amount
+    return text + " " + currency if currency and currency != "USD" else text
+
+
+def _num(value: Optional[Number]) -> str:
+    if value is None:
+        return "?"
+    return str(int(value)) if float(value).is_integer() else str(value)
+
+
+def _yes_no(value: Optional[bool]) -> Optional[str]:
+    return None if value is None else ("yes" if value else "no")
+
+
+def _number(text: str) -> Number:
+    value: Number
+    try:
+        # Whole numbers stay integers so the wire shows 30, not 30.0.
+        value = int(text)
+    except ValueError:
+        try:
+            value = float(text)
+        except ValueError:
+            raise argparse.ArgumentTypeError("%r is not a number" % text)
+    if value <= 0:
+        raise argparse.ArgumentTypeError("%r must be above zero" % text)
+    return value
+
+
+def _dims(text: str) -> Tuple[Number, Number, Number]:
+    parts = text.lower().split("x")
+    if len(parts) != 3:
+        raise argparse.ArgumentTypeError("--dims wants LxWxH in cm, e.g. 30x22x12")
+    length, width, height = (_number(part) for part in parts)
+    return length, width, height
+
+
+if __name__ == "__main__":
+    sys.exit(main())

smklog/client.py

@@ -0,0 +1,205 @@
+"""The client: four operations over urllib, nothing else."""
+
+import json
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from http.client import HTTPException
+from typing import Any, Dict, Mapping, Optional, Union
+
+from ._version import __version__
+from .errors import InvalidRequestError, SmklogError, error_for
+from .models import CheckoutSession, CheckoutStatus, Liveness, Model, QuoteResponse
+
+DEFAULT_BASE_URL = "https://quote-api.smklog.com"
+# A quote can take 10-20 s while carriers answer, so the default is generous.
+DEFAULT_TIMEOUT = 30.0
+COUNTRIES = ("US", "CA", "GB", "DE", "AU")
+MEASUREMENTS = ("length_cm", "width_cm", "height_cm", "weight_kg")
+# One pause per retry, GETs only. POST /quote spends a live carrier rating and
+# POST /agent/checkout-session opens a session, so neither is ever repeated by the SDK.
+RETRY_BACKOFF_SECONDS = (0.5, 1.0)
+
+_ZIP = re.compile(r"^[0-9]{5}$")
+RequestLike = Union[Model, Mapping[str, Any], None]
+
+
+class SmklogClient:
+    """Talks to the SMKlog Quote API. No key needed; ``token`` is the optional OAuth
+    bearer that buys a client its own rate-limit bucket."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        token: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.token = token
+        self.user_agent = "smklog-sdk-python/" + __version__
+        if user_agent:
+            self.user_agent += " " + user_agent
+
+    def get_parcel_quote(self, request: RequestLike = None, **fields: Any) -> QuoteResponse:
+        """POST /quote. Pass a QuoteRequest, a dict, or the fields as keywords.
+
+        Costs a live carrier rating on the server: one call per shipment, never a poll.
+        """
+        body = _prepare_quote(_merge(request, fields))
+        return QuoteResponse.from_dict(self._request("POST", "/quote", body))
+
+    def create_payment_session(self, request: RequestLike = None, **fields: Any) -> CheckoutSession:
+        """POST /agent/checkout-session. Give a ``quote_id`` (preferred: the quote is
+        reused, no second carrier call) or the shipment itself; the SDK does not turn
+        one into the other. A ``quote_id`` older than 15 minutes makes the API price
+        the shipment fields live, so send them along when the quote may have aged."""
+        body = _prepare_session(_merge(request, fields))
+        return CheckoutSession.from_dict(self._request("POST", "/agent/checkout-session", body))
+
+    def get_checkout_status(self, session_id: str) -> CheckoutStatus:
+        """GET /agent/checkout-session/{session_id}."""
+        if not isinstance(session_id, str) or not session_id.strip():
+            raise InvalidRequestError(0, "invalid_request", "session_id must be a non-empty string.")
+        path = "/agent/checkout-session/" + urllib.parse.quote(session_id, safe="")
+        return CheckoutStatus.from_dict(self._request("GET", path, retry=True))
+
+    def status(self) -> Liveness:
+        """GET /status: liveness and the serving version."""
+        return Liveness.from_dict(self._request("GET", "/status", retry=True))
+
+    def _request(
+        self, method: str, path: str, body: Optional[Dict[str, Any]] = None, retry: bool = False
+    ) -> Dict[str, Any]:
+        attempts = 1 + (len(RETRY_BACKOFF_SECONDS) if retry else 0)
+        for attempt in range(attempts):
+            try:
+                return self._send(method, path, body)
+            except SmklogError as exc:
+                # Only a dropped connection or a server-side failure is worth a second
+                # try; a 429 is deliberately excluded (retrying burns the bucket faster).
+                transient = exc.status == 0 or exc.status >= 500
+                if not transient or attempt + 1 == attempts:
+                    raise
+                time.sleep(RETRY_BACKOFF_SECONDS[attempt])
+        raise AssertionError("unreachable")
+
+    def _send(self, method: str, path: str, body: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        url = self.base_url + path
+        headers = {"Accept": "application/json", "User-Agent": self.user_agent}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if self.token:
+            headers["Authorization"] = "Bearer " + self.token
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                status, raw = response.status, response.read()
+        except urllib.error.HTTPError as exc:
+            status, raw = exc.code, exc.read()
+        except (OSError, HTTPException) as exc:
+            # URLError, socket timeouts and connection resets are all OSError.
+            raise SmklogError(0, "network_error", "%s %s: %s" % (method, url, exc)) from exc
+        parsed = _parse_json(raw)
+        if 200 <= status < 300:
+            if not isinstance(parsed, dict):
+                raise SmklogError(status, "unexpected_response", "HTTP %d with a non-JSON body" % status, body=_text(raw))
+            return parsed
+        raise error_for(status, parsed if parsed is not None else _text(raw))
+
+
+def _parse_json(raw: bytes) -> Any:
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError):
+        return None
+
+
+def _text(raw: bytes) -> str:
+    return raw.decode("utf-8", "replace")[:500]
+
+
+def _merge(request: RequestLike, fields: Dict[str, Any]) -> Dict[str, Any]:
+    if request is None:
+        body: Dict[str, Any] = {}
+    elif isinstance(request, Model):
+        body = request.to_dict()
+    elif isinstance(request, Mapping):
+        body = dict(request)
+    else:
+        raise TypeError("request must be a model, a dict or None, got %s" % type(request).__name__)
+    body.update(fields)
+    # A None means "not given", so it never reaches the wire as null.
+    return {name: value for name, value in body.items() if value is not None}
+
+
+def _reject(message: str, code: str = "invalid_request", missing: Optional[list] = None) -> InvalidRequestError:
+    return InvalidRequestError(0, code, message, missing)
+
+
+def _prepare_quote(body: Dict[str, Any]) -> Dict[str, Any]:
+    """Local checks that save a request the server would refuse anyway."""
+    missing = [name for name in ("from_postal_code", "to_postal_code") if not body.get(name)]
+    if not body.get("product") and not body.get("product_url"):
+        missing.append("product")
+    if missing:
+        raise _reject("Required: " + ", ".join(missing) + ".", "missing_required_fields", missing)
+    if not _is_zip(body["from_postal_code"]):
+        raise _reject("from_postal_code must be a 5-digit US ZIP, got %r." % (body["from_postal_code"],))
+    country = body.get("to_country_code", "US")
+    if country not in COUNTRIES:
+        raise _reject("to_country_code must be one of %s, got %r." % (", ".join(COUNTRIES), country))
+    if country == "US" and not _is_zip(body["to_postal_code"]):
+        raise _reject("to_postal_code must be a 5-digit US ZIP for a US destination, got %r." % (body["to_postal_code"],))
+    body.setdefault("quantity", 1)
+    _check_quantity(body["quantity"])
+    given = [name for name in MEASUREMENTS if name in body]
+    if given and len(given) != len(MEASUREMENTS):
+        absent = [name for name in MEASUREMENTS if name not in body]
+        raise _reject("length_cm, width_cm, height_cm and weight_kg go together; missing " + ", ".join(absent) + ".")
+    if given:
+        for name in MEASUREMENTS:
+            if not _is_positive_number(body[name]):
+                raise _reject("%s must be a positive number, got %r." % (name, body[name]))
+        # Exact measurements are only honored when the request says so.
+        body.setdefault("package_source", "manual")
+    return body
+
+
+def _prepare_session(body: Dict[str, Any]) -> Dict[str, Any]:
+    if body.get("quote_id"):
+        if not isinstance(body["quote_id"], str):
+            raise _reject("quote_id must be a string, got %r." % (body["quote_id"],))
+    else:
+        missing = [name for name in ("product", "from_zip", "to_zip") if not body.get(name)]
+        if missing:
+            raise _reject("Without quote_id the shipment itself is required: " + ", ".join(missing) + ".",
+                          "missing_required_fields", missing)
+        if not _is_zip(body["from_zip"]):
+            raise _reject("from_zip must be a 5-digit US ZIP, got %r." % (body["from_zip"],))
+        country = body.get("to_country", "US")
+        if country not in COUNTRIES:
+            raise _reject("to_country must be one of %s, got %r." % (", ".join(COUNTRIES), country))
+        if country == "US" and not _is_zip(body["to_zip"]):
+            raise _reject("to_zip must be a 5-digit US ZIP for a US destination, got %r." % (body["to_zip"],))
+    if "quantity" in body:
+        _check_quantity(body["quantity"])
+    return body
+
+
+def _check_quantity(value: Any) -> None:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise _reject("quantity must be a whole number of 1 or more, got %r." % (value,))
+
+
+def _is_zip(value: Any) -> bool:
+    return isinstance(value, str) and bool(_ZIP.match(value))
+
+
+def _is_positive_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0

smklog/errors.py

@@ -0,0 +1,112 @@
+"""The error taxonomy: one base exception and four subclasses picked by the Problem code."""
+
+from typing import Any, Dict, Optional, Sequence, Type
+
+
+class SmklogError(Exception):
+    """Any failure the client raises.
+
+    ``status`` is the HTTP status, or 0 when no HTTP exchange happened: a network
+    failure or timeout (``error == "network_error"``) or a request the client refused
+    locally before spending a call. ``error`` is the stable code from the Problem body,
+    ``message`` its sentence, ``missing`` the field names it asked for (often empty)
+    and ``body`` the response body as received (a dict when it was JSON).
+    """
+
+    def __init__(
+        self,
+        status: int,
+        error: str,
+        message: str = "",
+        missing: Optional[Sequence[str]] = None,
+        body: Any = None,
+    ) -> None:
+        self.status = status
+        self.error = error
+        self.message = message or ""
+        self.missing = [str(name) for name in (missing or [])]
+        self.body = body
+        super().__init__(str(self))
+
+    def __reduce__(self):
+        # Exception's default pickling replays ``args`` (the rendered text) into
+        # __init__, which wants the five fields; rebuild from them instead so an
+        # error crosses a multiprocessing boundary intact.
+        return (type(self), (self.status, self.error, self.message, self.missing, self.body))
+
+    def __str__(self) -> str:
+        text = self.error
+        if self.status:
+            text += " (HTTP %d)" % self.status
+        if self.message:
+            text += ": " + self.message
+        if self.missing:
+            text += " [missing: " + ", ".join(self.missing) + "]"
+        return text
+
+    def problem(self) -> Dict[str, Any]:
+        """The Problem shape for this error, rebuilt when the server sent none."""
+        if isinstance(self.body, dict) and "error" in self.body:
+            return dict(self.body)
+        out: Dict[str, Any] = {"error": self.error, "message": self.message}
+        if self.missing:
+            out["missing"] = list(self.missing)
+        return out
+
+
+class RateLimitedError(SmklogError):
+    """429: the hourly bucket is spent. The SDK never retries this; wait, then decide."""
+
+
+class InvalidRequestError(SmklogError):
+    """The request cannot be served as written: missing fields, bad JSON, an item or
+    URL the estimator could not recognize, or a value this client rejected locally."""
+
+
+class NotFoundError(SmklogError):
+    """404: no payment session with that id (sessions answer for 30 days)."""
+
+
+class SessionFailedError(SmklogError):
+    """422: the shipment cannot become a checkout (past parcel limits, restricted,
+    more than one box, or unpriceable)."""
+
+
+ERROR_TYPES: Dict[str, Type[SmklogError]] = {
+    "rate_limited": RateLimitedError,
+    "slow_down": RateLimitedError,
+    "product_not_recognized": InvalidRequestError,
+    "product_url_not_detected": InvalidRequestError,
+    "missing_required_fields": InvalidRequestError,
+    "invalid_request": InvalidRequestError,
+    "invalid_json": InvalidRequestError,
+    "session_not_found": NotFoundError,
+    "session_failed": SessionFailedError,
+}
+
+
+def error_for(status: int, body: Any) -> SmklogError:
+    """Builds the error for a non-2xx answer; the Problem's code picks the type.
+
+    A 429 without a Problem body (an edge rate limit answers in HTML) still becomes a
+    RateLimitedError, because the caller's reaction is the same either way. A Problem
+    may carry no sentence (missing_required_fields lists fields instead), so the
+    message is then the code plus the missing fields and a log line still says what
+    went wrong.
+    """
+    problem = body if isinstance(body, dict) else {}
+    code = problem.get("error")
+    if not isinstance(code, str) or not code:
+        code = "rate_limited" if status == 429 else "unexpected_response"
+    missing = problem.get("missing")
+    if not isinstance(missing, list):
+        missing = None
+    message = problem.get("message")
+    if not isinstance(message, str) or not message:
+        if not problem:
+            message = "HTTP %d with a non-JSON body" % status
+        elif missing:
+            message = "%s: missing %s" % (code, ", ".join(str(name) for name in missing))
+        else:
+            message = code
+    return ERROR_TYPES.get(code, SmklogError)(status, code, message, missing, body)

smklog/models.py

@@ -0,0 +1,257 @@
+"""Typed views of the API's JSON shapes, one dataclass per schema in testdata/schemas.
+
+Field names are the wire names (snake_case) so a model reads like the JSON it came
+from. The API adds fields without a version bump, so ``from_dict`` never drops
+anything: names this SDK does not know land in ``extra``, and ``raw`` keeps the body
+exactly as received.
+"""
+
+from dataclasses import dataclass, field, fields
+from typing import Any, Callable, ClassVar, Dict, List, Optional, Type, TypeVar
+
+M = TypeVar("M", bound="Model")
+
+
+@dataclass
+class Model:
+    """Shared behavior: build from a dict, serialize back, keep unknown fields."""
+
+    # init=False keeps these off the constructor so subclasses may still declare
+    # ordinary fields after them (dataclasses only order the init parameters).
+    extra: Dict[str, Any] = field(default_factory=dict, init=False, compare=False)
+    raw: Dict[str, Any] = field(default_factory=dict, init=False, repr=False, compare=False)
+
+    # Field name -> converter for nested shapes; subclasses override.
+    _nested: ClassVar[Dict[str, Callable[[Any], Any]]] = {}
+
+    @classmethod
+    def from_dict(cls: Type[M], data: Dict[str, Any]) -> M:
+        if not isinstance(data, dict):
+            raise TypeError("%s.from_dict expects a dict, got %s" % (cls.__name__, type(data).__name__))
+        known = {f.name for f in fields(cls) if f.init}
+        values = {}
+        for name, value in data.items():
+            if name not in known:
+                continue
+            convert = cls._nested.get(name)
+            values[name] = convert(value) if convert and value is not None else value
+        model = cls(**values)
+        model.extra = {name: value for name, value in data.items() if name not in known}
+        model.raw = dict(data)
+        return model
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-ready dict: the fields that are set, nested models flattened, extra merged."""
+        out: Dict[str, Any] = {}
+        for f in fields(self):
+            if not f.init:
+                continue
+            value = getattr(self, f.name)
+            if value is not None:
+                out[f.name] = _plain(value)
+        out.update(self.extra)
+        return out
+
+
+def _plain(value: Any) -> Any:
+    if isinstance(value, Model):
+        return value.to_dict()
+    if isinstance(value, list):
+        return [_plain(item) for item in value]
+    return value
+
+
+def _list_of(model: Type[M]) -> Callable[[Any], Any]:
+    # A list item that is not an object is passed through untouched rather than
+    # failing the whole response: the typed view is a convenience, not a validator.
+    def convert(items: Any) -> Any:
+        if not isinstance(items, list):
+            return items
+        return [model.from_dict(item) if isinstance(item, dict) else item for item in items]
+
+    return convert
+
+
+def _one(model: Type[M]) -> Callable[[Any], Any]:
+    def convert(item: Any) -> Any:
+        return model.from_dict(item) if isinstance(item, dict) else item
+
+    return convert
+
+
+@dataclass
+class QuoteRequest(Model):
+    """One shipment to price (quote-request.schema.json)."""
+
+    product: Optional[str] = None
+    from_postal_code: Optional[str] = None
+    to_postal_code: Optional[str] = None
+    quantity: int = 1
+    to_country_code: Optional[str] = None
+    product_url: Optional[str] = None
+    length_cm: Optional[float] = None
+    width_cm: Optional[float] = None
+    height_cm: Optional[float] = None
+    weight_kg: Optional[float] = None
+    package_source: Optional[str] = None
+
+
+@dataclass
+class Package(Model):
+    """The packed box used for pricing (package.schema.json)."""
+
+    quantity: Optional[int] = None
+    length_cm: Optional[float] = None
+    width_cm: Optional[float] = None
+    height_cm: Optional[float] = None
+    weight_kg: Optional[float] = None
+    description: Optional[str] = None
+    confidence: Optional[str] = None
+    assumptions: Optional[List[str]] = None
+
+
+@dataclass
+class Rate(Model):
+    """One purchasable service (rate.schema.json).
+
+    ``amount`` is the checkout total the customer pays, SMKlog fee inside;
+    ``retail_amount`` is the carrier's own counter price (0 when not published).
+    """
+
+    carrier: Optional[str] = None
+    service: Optional[str] = None
+    service_code: Optional[str] = None
+    amount: Optional[float] = None
+    retail_amount: Optional[float] = None
+    delivery_days: Optional[int] = None
+    delivery_window: Optional[str] = None
+    delivery_estimated_date: Optional[str] = None
+    currency: Optional[str] = None
+
+
+@dataclass
+class QuoteResponse(Model):
+    """A priced parcel, or the reason it was not priced (quote-response.schema.json).
+
+    ``quote_id`` is the handle the API keeps for 15 minutes: pass it to
+    ``create_payment_session`` and the checkout reuses these rates instead of
+    spending a second carrier call. It is None when nothing was priced, when the
+    handle could not be stored, or when the answer carried no rates.
+    """
+
+    mode: Optional[str] = None
+    identified_product_title: Optional[str] = None
+    quote_id: Optional[str] = None
+    package: Optional[Package] = None
+    packages: Optional[List[Package]] = None
+    rates: List[Rate] = field(default_factory=list)
+    dangerous_goods: Optional[Dict[str, Any]] = None
+    sources: Optional[List[Dict[str, Any]]] = None
+    notice: Optional[str] = None
+    source: Optional[Dict[str, Any]] = None
+
+    _nested: ClassVar[Dict[str, Callable[[Any], Any]]] = {
+        "package": _one(Package),
+        "packages": _list_of(Package),
+        "rates": _list_of(Rate),
+    }
+
+    def __post_init__(self) -> None:
+        # A body with "rates": null is an unpriced answer, so the typed view reads
+        # as an empty list; ``raw`` still shows the null the API sent.
+        if self.rates is None:
+            self.rates = []
+
+    def is_priced(self) -> bool:
+        """True only when the shipment can be bought: a label-ready mode with a rate."""
+        return self.mode == "parcel_label_ready" and bool(self.rates)
+
+    def cheapest(self) -> Optional[Rate]:
+        """The rate with the lowest checkout total; None when nothing was priced."""
+        priced = [rate for rate in self.rates or [] if isinstance(rate, Rate) and rate.amount is not None]
+        return min(priced, key=lambda rate: rate.amount) if priced else None
+
+
+@dataclass
+class CheckoutSessionRequest(Model):
+    """What to open a checkout for: a quote_id, or the shipment itself
+    (checkout-session-request.schema.json)."""
+
+    quote_id: Optional[str] = None
+    service: Optional[str] = None
+    product: Optional[str] = None
+    from_zip: Optional[str] = None
+    to_zip: Optional[str] = None
+    to_country: Optional[str] = None
+    quantity: Optional[int] = None
+
+
+@dataclass
+class CheckoutSession(Model):
+    """A payment session, not a charge (checkout-session.schema.json)."""
+
+    intent: Optional[str] = None
+    session_id: Optional[str] = None
+    method: Optional[List[str]] = None
+    amount: Optional[float] = None
+    currency: Optional[str] = None
+    service: Optional[str] = None
+    handoff_url: Optional[str] = None
+    identified_product_title: Optional[str] = None
+    quote_reused: Optional[bool] = None
+    note: Optional[str] = None
+
+
+@dataclass
+class Checkout(Model):
+    """The checkout a human started, nested in CheckoutStatus."""
+
+    order_id: Optional[str] = None
+    started_at: Optional[str] = None
+    paid: Optional[bool] = None
+    label_ready: Optional[bool] = None
+    refunded: Optional[bool] = None
+    carrier: Optional[str] = None
+    service: Optional[str] = None
+    tracking_number: Optional[str] = None
+    tracking_status: Optional[str] = None
+    estimated_delivery: Optional[str] = None
+    delivered_at: Optional[str] = None
+
+
+@dataclass
+class CheckoutStatus(Model):
+    """Where a checkout stands (checkout-status.schema.json)."""
+
+    session_id: Optional[str] = None
+    status: Optional[str] = None
+    created_at: Optional[str] = None
+    expires_at: Optional[str] = None
+    amount: Optional[float] = None
+    currency: Optional[str] = None
+    service: Optional[str] = None
+    quote_reused: Optional[bool] = None
+    checkout: Optional[Checkout] = None
+    next: Optional[str] = None
+
+    _nested: ClassVar[Dict[str, Callable[[Any], Any]]] = {"checkout": _one(Checkout)}
+
+
+@dataclass
+class Liveness(Model):
+    """The liveness answer (liveness.schema.json)."""
+
+    ok: Optional[bool] = None
+    service: Optional[str] = None
+    version: Optional[str] = None
+    time: Optional[str] = None
+    last_estimate_race: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Problem(Model):
+    """Every error body on the host (problem.schema.json)."""
+
+    error: Optional[str] = None
+    message: Optional[str] = None
+    missing: List[str] = field(default_factory=list)

smklog_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: smklog-sdk
+Version: 0.1.0
+Summary: Official Python client and command line for the SMKlog Quote API: live USPS, UPS, FedEx and DHL parcel rates from a US origin, a checkout handed to a human, and where it stands.
+Author-email: SMKlog <info@smklog.com>
+License-Expression: MIT
+Project-URL: Homepage, https://smklog.com/developers/
+Project-URL: Documentation, https://smklog.com/developers/
+Project-URL: Repository, https://github.com/smklog/smklog-sdk
+Project-URL: Changelog, https://github.com/smklog/smklog-sdk/releases
+Project-URL: OpenAPI, https://quote-api.smklog.com/openapi.json
+Project-URL: Status page, https://smklog.com/developers/status
+Keywords: smklog,shipping,parcel,rates,usps,ups,fedex,dhl,labels
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# smklog-sdk (Python)
+
+Official Python client and command line for the [SMKlog Quote API](https://smklog.com/developers/):
+live USPS, UPS, FedEx and DHL Express parcel rates from a US origin, a checkout handed
+to a human, and where that checkout stands. No API key, no account, no dependencies
+beyond the standard library. Python 3.9 or newer.
+
+```
+pip install smklog-sdk
+```
+
+The distribution is `smklog-sdk`; the import package is `smklog`.
+
+## Quickstart
+
+```python
+from smklog import SmklogClient
+
+client = SmklogClient()
+quote = client.get_parcel_quote(product="Yamaha FG800 acoustic guitar in a hard case",
+                                from_postal_code="07102", to_postal_code="30303")
+for rate in quote.rates:                       # best value first, as the API returns them
+    print(rate.carrier, rate.service, rate.amount, "counter", rate.retail_amount)
+if quote.is_priced() and quote.quote_id:       # the handle is good for 15 minutes
+    best = quote.cheapest()
+    session = client.create_payment_session(quote_id=quote.quote_id, service=best.service)
+    print(session.handoff_url)                 # the human confirms and pays here
+    if session.session_id:                     # None only when the record was not stored
+        print(client.get_checkout_status(session.session_id).status)
+```
+
+The pair costs one carrier call: the quote answer carries `quote_id`, and a checkout
+opened with it reuses those rates (`session.quote_reused` is true) instead of pricing
+the shipment again.
+
+Exact measurements skip the box estimate: pass all four of `length_cm`, `width_cm`,
+`height_cm`, `weight_kg` (the client marks the package `manual`). A request can also be a
+`QuoteRequest` / `CheckoutSessionRequest` model or a plain dict; fields keep the wire names.
+
+Every `get_parcel_quote` call spends a live carrier rating on the server: one call per
+shipment, cache on your side, never poll. `create_payment_session` takes one of two forms:
+
+- `create_payment_session(quote_id=..., service=...)`: the quote is reused and no second
+  carrier call is spent. `quote_id` is the handle every priced quote answer carries; it is
+  `None` when nothing was priced or the handle could not be stored. The API ignores any
+  shipment fields sent next to a valid `quote_id`.
+- `create_payment_session(product=..., from_zip=..., to_zip=..., to_country=..., quantity=...,
+  service=...)`: the API prices the shipment live and opens the checkout in one call.
+
+A `quote_id` older than 15 minutes makes the API price the shipment fields live, so send
+them along when the quote may have aged. The client never turns one form into the other.
+
+## Client options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `base_url` | `https://quote-api.smklog.com` | The API host. |
+| `timeout` | `30.0` | Seconds per request; a quote can take 10-20 s while carriers answer. |
+| `token` | `None` | Optional OAuth bearer for a dedicated rate-limit bucket ([auth.md](https://smklog.com/auth.md)); sent as `Authorization: Bearer ...` only when set. |
+| `user_agent` | `None` | Suffix appended after `smklog-sdk-python/0.1.0`. |
+
+Operations: `get_parcel_quote(...)` -> `QuoteResponse` (with `quote_id`, `rates`,
+`cheapest()`, `is_priced()`), `create_payment_session(...)` -> `CheckoutSession`,
+`get_checkout_status(session_id)` -> `CheckoutStatus`, `status()` -> `Liveness`.
+
+Every model is a dataclass whose fields are the wire names. Fields this version does
+not know about land in `.extra`; `.raw` is the body exactly as received; `.to_dict()`
+serializes back. Only the idempotent GETs (`get_checkout_status`, `status`) are retried,
+at most twice, on network failures and 5xx. POSTs are never retried, and a 429 is never
+retried anywhere: the buckets are hourly (about 80 quotes, 60 status reads, 20 token
+requests per client), so a retry loop only burns them faster.
+
+## Errors
+
+Every failure raises `SmklogError` or one of its subclasses, carrying `status` (HTTP
+status, 0 when nothing was sent), `error` (the stable code), `message`, `missing`
+(field names, often empty) and `body` (the response body as received). When the Problem
+carries no `message`, the error's message is the code plus the missing fields
+(`missing_required_fields: missing to_postal_code`). Errors pickle, so they cross a
+`multiprocessing` boundary intact.
+
+| Code | Exception |
+| --- | --- |
+| `rate_limited`, `slow_down` | `RateLimitedError` |
+| `product_not_recognized`, `product_url_not_detected`, `missing_required_fields`, `invalid_request`, `invalid_json` | `InvalidRequestError` |
+| `session_not_found` | `NotFoundError` |
+| `session_failed` | `SessionFailedError` |
+| anything else | `SmklogError` |
+
+A network failure or timeout is `SmklogError` with `status == 0` and
+`error == "network_error"`; the native exception is its `__cause__`. Requests the client
+refuses before sending (a 4-digit ZIP, a country outside US/CA/GB/DE/AU, a quantity
+below 1, measurements that do not come as a set of four) raise `InvalidRequestError`
+with `status == 0`.
+
+## Command line
+
+```
+smklog quote "Yamaha FG800 acoustic guitar in a hard case" 07102 30303 [--country US] [--qty 1] [--dims 112x48x20 --kg 6.4] [--json]
+smklog session --quote-id q_... [--service "USPS Ground Advantage"] [--json]
+smklog session-status as_... [--json]
+smklog status [--json]
+```
+
+Human output is a small table; `--json` prints the raw answer. A priced `smklog quote`
+also prints the `quote_id` on its own line, ready to pass to `smklog session --quote-id`
+within 15 minutes (`--json` carries it in the body):
+
+```
+$ smklog quote "Yamaha FG800 acoustic guitar in a hard case" 07102 30303
+Yamaha FG800 acoustic guitar in a hard case
+Box: 112 x 48 x 20 cm, 6.4 kg (estimate, medium confidence)
+Carrier  Service           Checkout  Counter  Delivery
+USPS     Ground Advantage  $38.42    $46.95   2-5 business days
+UPS      Ground            $41.10    $67.35   3 days, by 2026-10-16
+quote_id  q_8f3c2e1a4b7d
+$ smklog session --quote-id q_8f3c2e1a4b7d --service "USPS Ground Advantage"
+```
+
+Exit code 0 on a priced answer or a successful read, 2 when the API refuses (the Problem
+is printed) or answers a quote without a price, 3 on a rate limit, 1 when the host could
+not be reached.
+`--base-url` and `--token` (or `SMKLOG_BASE_URL` / `SMKLOG_TOKEN`) are accepted by every
+command. `python -m smklog` runs the same program.
+
+## Development
+
+```
+cd python
+python3 -m unittest discover -s tests
+```
+
+The tests replay the vendored examples in `../testdata/` over a local HTTP server and
+never reach the network. `SMKLOG_LIVE=1` adds one live test that calls `status()` on
+production; nothing in the suite ever requests a quote.
+
+Docs, schemas, playground and status page: [smklog.com/developers](https://smklog.com/developers/).
+The contract is the OpenAPI 3.1 document at
+[quote-api.smklog.com/openapi.json](https://quote-api.smklog.com/openapi.json).
+
+MIT license; see [LICENSE](LICENSE).

smklog_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+smklog/__init__.py,sha256=b1G6Ushsrj3A4IROMXFdB9Y6ZNd-_b3HcWNJD_njYW4,1126
+smklog/__main__.py,sha256=_hb4IAc3u3TNm1eNR-sW26IweOj6eWXkVjw0IlaPgxc,128
+smklog/_version.py,sha256=zq64KsfLwETMEhjUgMB5D0Ogktyq2x2zaxRFl-Vqcks,144
+smklog/cli.py,sha256=3vN--XASlVcjIbCB6EpmSbgLFN0mGm0ymFKOZoDAkSE,11205
+smklog/client.py,sha256=OnYR03k1-gqZ32C4YL_6FpSEKIFx2TYem_SRKRlENRk,9554
+smklog/errors.py,sha256=sNCwgaY2MYMVbuGwVBYB1Qu1rVvgwCddQfHPZu1sCK8,4375
+smklog/models.py,sha256=UF2Y7rAOYA2ws4dTkiWzbe_ViHcRt1sSHFTq057sJVU,8816
+smklog/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+smklog_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=06AdKTrykLR7O2TaVXFNXotCvj9YGEiE0ENwr2uBobk,1066
+smklog_sdk-0.1.0.dist-info/METADATA,sha256=Drk-GeX_0iAJ6s9A0nZCTRYjG_ahROTqJBvFQ2uHEW0,8402
+smklog_sdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+smklog_sdk-0.1.0.dist-info/entry_points.txt,sha256=M2LGx69lkPbSMKJuRCb1LZ6kB0C3x1jO3rH4yKvRQD8,43
+smklog_sdk-0.1.0.dist-info/top_level.txt,sha256=wMOWK-ql0NobhHjITZnt-_FIJzfANnwPgpe1fd4b98Q,7
+smklog_sdk-0.1.0.dist-info/RECORD,,

smklog_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

smklog_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+smklog = smklog.cli:main

smklog_sdk-0.1.0.dist-info/licenses/LICENSE

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

smklog_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+smklog