shoply 0.1.0__tar.gz

shoply-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+/build/
+/dist/
+/.mypy_cache/
+/.venv/

shoply-0.1.0/LICENSE

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

shoply-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: shoply
+Version: 0.1.0
+Summary: Shoply's API from your own server: every route as a method, safe retries, pages, and checking webhooks.
+Project-URL: Documentation, https://docs.shoply.gg/api-reference/python
+Project-URL: Source, https://github.com/shoplygg/shoply-python
+Project-URL: Issues, https://github.com/shoplygg/shoply-python/issues
+Project-URL: Changelog, https://docs.shoply.gg/changelog
+Author: Shoply
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,digital-goods,ecommerce,sdk,shoply,webhooks
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# shoply
+
+Shoply's API from your own server. Every route of the [API reference](https://docs.shoply.gg/api-reference/introduction) is a method, with types your editor and mypy read, safe retries, lists a page at a time or all at once, and checking that a webhook came from Shoply.
+
+```sh
+pip install shoply
+```
+
+Python 3.9 or later. No dependencies.
+
+```python
+import shoply
+
+client = shoply.Client()  # SHOPLY_API_KEY from the environment
+
+order = client.orders.show("ORDER_ID")
+
+for customer in client.customers.list(search="gmail.com"):
+    print(customer["emailAddress"])
+
+coupon = client.coupons.create(code="SPRING10", value=10)
+```
+
+Make the key under **Developers**, **API Keys** in the dashboard, with the permissions your code needs. Keep it on your server.
+
+A route's method is its id: **Get an order** is `orders.show`, so `client.orders.show(order_id)`. The address's IDs come first, in order, then the fields as keyword arguments, by the names the reference gives them, then options. A field whose name is a Python keyword takes an underscore: `from_`.
+
+## Errors
+
+A refusal is a `shoply.ShoplyError`, with `status`, `code` (`not_found`, `missing_scope`, `validation_failed`...), `errors` for each field that is wrong, and `request_id`.
+
+```python
+try:
+    client.coupons.create(code="SPRING10", value=10)
+except shoply.ShoplyError as error:
+    if error.code == "validation_failed":
+        print(error.errors)
+```
+
+A change is sent with an `Idempotency-Key`, the same on every try, so a try whose answer was lost is never carried out twice. Pass `idempotency_key=...` to use your own.
+
+## Webhooks
+
+```python
+import os
+
+import shoply
+from flask import Flask, request
+
+app = Flask(__name__)
+
+
+@app.post("/webhooks/shoply")
+def shoply_webhook() -> tuple[str, int]:
+    try:
+        event = shoply.webhooks.verify(request.get_data(), request.headers, os.environ["SHOPLY_WEBHOOK_SECRET"])
+    except shoply.ShoplyError:
+        return "", 401
+
+    if event["event"] == "order.paid":
+        ...  # event["data"] is the order
+
+    return "", 200
+```
+
+## The Customer API
+
+`shoply.Customer` signs a buyer in with a code emailed to them, and reads their own orders, keys and subscriptions. It holds the buyer's token and no key.
+
+```python
+buyer = shoply.Customer("YOUR_STORE_ID")
+
+buyer.login(email=email)
+buyer.verify(email=email, code=code)
+me = buyer.show()
+```
+
+The whole guide: https://docs.shoply.gg/api-reference/python

shoply-0.1.0/README.md

@@ -0,0 +1,78 @@
+# shoply
+
+Shoply's API from your own server. Every route of the [API reference](https://docs.shoply.gg/api-reference/introduction) is a method, with types your editor and mypy read, safe retries, lists a page at a time or all at once, and checking that a webhook came from Shoply.
+
+```sh
+pip install shoply
+```
+
+Python 3.9 or later. No dependencies.
+
+```python
+import shoply
+
+client = shoply.Client()  # SHOPLY_API_KEY from the environment
+
+order = client.orders.show("ORDER_ID")
+
+for customer in client.customers.list(search="gmail.com"):
+    print(customer["emailAddress"])
+
+coupon = client.coupons.create(code="SPRING10", value=10)
+```
+
+Make the key under **Developers**, **API Keys** in the dashboard, with the permissions your code needs. Keep it on your server.
+
+A route's method is its id: **Get an order** is `orders.show`, so `client.orders.show(order_id)`. The address's IDs come first, in order, then the fields as keyword arguments, by the names the reference gives them, then options. A field whose name is a Python keyword takes an underscore: `from_`.
+
+## Errors
+
+A refusal is a `shoply.ShoplyError`, with `status`, `code` (`not_found`, `missing_scope`, `validation_failed`...), `errors` for each field that is wrong, and `request_id`.
+
+```python
+try:
+    client.coupons.create(code="SPRING10", value=10)
+except shoply.ShoplyError as error:
+    if error.code == "validation_failed":
+        print(error.errors)
+```
+
+A change is sent with an `Idempotency-Key`, the same on every try, so a try whose answer was lost is never carried out twice. Pass `idempotency_key=...` to use your own.
+
+## Webhooks
+
+```python
+import os
+
+import shoply
+from flask import Flask, request
+
+app = Flask(__name__)
+
+
+@app.post("/webhooks/shoply")
+def shoply_webhook() -> tuple[str, int]:
+    try:
+        event = shoply.webhooks.verify(request.get_data(), request.headers, os.environ["SHOPLY_WEBHOOK_SECRET"])
+    except shoply.ShoplyError:
+        return "", 401
+
+    if event["event"] == "order.paid":
+        ...  # event["data"] is the order
+
+    return "", 200
+```
+
+## The Customer API
+
+`shoply.Customer` signs a buyer in with a code emailed to them, and reads their own orders, keys and subscriptions. It holds the buyer's token and no key.
+
+```python
+buyer = shoply.Customer("YOUR_STORE_ID")
+
+buyer.login(email=email)
+buyer.verify(email=email, code=code)
+me = buyer.show()
+```
+
+The whole guide: https://docs.shoply.gg/api-reference/python

shoply-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shoply"
+version = "0.1.0"
+description = "Shoply's API from your own server: every route as a method, safe retries, pages, and checking webhooks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Shoply" }]
+keywords = ["shoply", "api", "sdk", "ecommerce", "webhooks", "digital-goods"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Office/Business :: Financial :: Point-Of-Sale",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://docs.shoply.gg/api-reference/python"
+Source = "https://github.com/shoplygg/shoply-python"
+Issues = "https://github.com/shoplygg/shoply-python/issues"
+Changelog = "https://docs.shoply.gg/changelog"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shoply"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/shoply", "tests", "README.md", "LICENSE", "pyproject.toml"]

shoply-0.1.0/src/shoply/__init__.py

@@ -0,0 +1,20 @@
+"""Shoply's API from your own server: every route as a method, safe retries, pages, and checking
+webhooks. Docs: https://docs.shoply.gg/api-reference/python
+
+    import shoply
+
+    client = shoply.Client()  # SHOPLY_API_KEY from the environment
+    order = client.orders.show("8f2c...")
+"""
+
+from . import _webhooks as webhooks
+from ._client import Client
+from ._customer import Customer
+from ._errors import ShoplyError
+from ._files import File
+from ._generated.routes import EVENTS
+from ._generated.types import WebhookEvent, WebhookEventName
+from ._page import Page
+from ._version import VERSION
+
+__all__ = ["Client", "Customer", "ShoplyError", "File", "Page", "webhooks", "WebhookEvent", "WebhookEventName", "EVENTS", "VERSION"]

shoply-0.1.0/src/shoply/_calls.py

@@ -0,0 +1,42 @@
+"""What a call of a route is made of: its address, and where its fields go."""
+
+import urllib.parse
+from typing import Any, Dict, List, Optional, Tuple
+
+from ._generated.routes import ROUTES
+
+
+def prepare(id: str, path: List[str], fields: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, str], Optional[Dict[str, Any]], Any, Optional[Tuple[str, Any, Optional[str], Optional[str]]]]:
+    """The route, the address's IDs by name, and the fields: as the query, the JSON body, or a file."""
+    route = ROUTES[id]
+    values: Dict[str, str] = {}
+
+    for index, name in enumerate(route["params"]):
+        value = path[index] if index < len(path) else ""
+        if not isinstance(value, str) or value == "":
+            raise ValueError(f"{id} needs {name}.")
+        values[name] = value
+
+    given = {name: value for name, value in fields.items() if value is not None}
+    query: Optional[Dict[str, Any]] = None
+    body: Any = None
+    form = None
+
+    if route["upload"]:
+        form = (route["upload"], given.get("file"), given.get("filename"), given.get("content_type"))
+        # What the route takes beside the file (a dispute's file says its `kind`) is in the address.
+        query = {name: value for name, value in given.items() if name in route["query"]}
+    elif route["body"]:
+        query = {name: value for name, value in given.items() if name in route["query"]}
+        body = {name: value for name, value in given.items() if name not in route["query"]}
+    else:
+        query = given
+
+    return route, values, query, body, form
+
+
+def fill(template: str, values: Dict[str, str]) -> str:
+    """The route's address with its IDs in it, each escaped."""
+    for name, value in values.items():
+        template = template.replace("{" + name + "}", urllib.parse.quote(value, safe=""))
+    return template

shoply-0.1.0/src/shoply/_client.py

@@ -0,0 +1,114 @@
+import os
+from typing import Any, Dict, List, Optional, Union
+
+from ._calls import fill, prepare
+from ._errors import ShoplyError
+from ._files import File
+from ._generated.resources import ClientResources
+from ._page import Page
+from ._transport import Transport
+
+
+class Client(ClientResources):
+    """Shoply's API from your own server, with a store's secret API key. Every route of the API
+    reference is a method named by its id: `orders.show` is `client.orders.show(order_id)`.
+
+        client = shoply.Client(api_key=os.environ["SHOPLY_API_KEY"])
+        order = client.orders.show("8f2c...")
+
+    A call takes the IDs in the route's address, in order, then its fields as keyword
+    arguments, then options (`idempotency_key`, `timeout`, `max_retries`, `headers`). It answers
+    the route's `data`, as dicts; a list that is paged answers a Page, and a file a File.
+
+    Docs: https://docs.shoply.gg/api-reference/python
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        store_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ) -> None:
+        """
+        api_key:     `shoply_sk_...`. Left out, SHOPLY_API_KEY from the environment.
+        store_id:    the store's ID. Left out, it is asked of the key the first time it is needed.
+        timeout:     how long one try waits for an answer, in seconds. 60.
+        max_retries: how many more tries a request that is safe to repeat is given. 2.
+        """
+        key = api_key if api_key is not None else os.environ.get("SHOPLY_API_KEY")
+
+        if not isinstance(key, str) or not key.startswith("shoply_sk_"):
+            raise ShoplyError("Pass the store's secret API key as `api_key` (shoply_sk_...), or set SHOPLY_API_KEY.", code="api_key_required")
+
+        self._store_id = store_id
+        self._transport = Transport(base_url, timeout, max_retries, lambda: key)
+        self._resources()
+
+    def store_id(self) -> str:
+        """The store the key belongs to, asked once and remembered."""
+        if self._store_id is None:
+            answer = self._transport.send("GET", "/key")
+            assert isinstance(answer, dict)
+            self._store_id = str(answer["data"]["store"]["id"])
+        return self._store_id
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Any route, by its method and its address after /v1, for one newer than this package:
+        `{storeId}` in the path is filled in. Answers the whole envelope: `data`, and `meta`,
+        `pages` and `total` where the route has them."""
+        method = method.upper()
+        if "{storeId}" in path:
+            path = fill(path, {"storeId": self.store_id()})
+        answer = self._transport.send(
+            method, path, query=query, body=body, idempotent=method != "GET",
+            options={"idempotency_key": idempotency_key, "timeout": timeout, "max_retries": max_retries, "headers": headers},
+        )
+        assert isinstance(answer, dict)
+        return answer
+
+    def _call(self, id: str, path: List[str], fields: Dict[str, Any], options: Dict[str, Any]) -> Any:
+        route, values, query, body, form = prepare(id, path, fields)
+
+        def fetch(page: int) -> Union[Dict[str, Any], File]:
+            filled = dict(values)
+            if "{storeId}" in route["path"]:
+                filled["storeId"] = self.store_id()
+            asked = dict(query or {}, page=page) if route["paged"] else query
+            return self._transport.send(
+                route["method"], fill(route["path"], filled), query=asked, body=body, form=form,
+                idempotent=route["idempotent"], file=route["file"], options=options,
+            )
+
+        if route["paged"]:
+            given = fields.get("page")
+            return _page(fetch, given if isinstance(given, int) and given > 0 else 1)
+
+        answer = fetch(1)
+        return answer if isinstance(answer, File) else answer.get("data")
+
+
+def _page(fetch: Any, number: int) -> Page[Any]:
+    answer = fetch(number)
+    data = answer.get("data")
+    return Page(
+        list(data) if isinstance(data, list) else [],
+        number,
+        int(answer["pages"]) if isinstance(answer.get("pages"), int) else None,
+        int(answer["total"]) if isinstance(answer.get("total"), int) else None,
+        answer.get("meta") if isinstance(answer.get("meta"), dict) else None,
+        lambda next: _page(fetch, next),
+    )

shoply-0.1.0/src/shoply/_customer.py

@@ -0,0 +1,61 @@
+from typing import Any, Dict, List, Optional
+
+from ._calls import fill, prepare
+from ._errors import ShoplyError
+from ._generated.resources import CustomerResources
+from ._transport import Transport
+
+
+class Customer(CustomerResources):
+    """The Customer API: a buyer signed in on your own site or app with a code emailed to them,
+    reading their own orders, keys, subscriptions and affiliate page. It holds the buyer's token
+    and no key.
+
+        buyer = shoply.Customer(store_id="YOUR_STORE_ID")
+        buyer.login(email=email)
+        buyer.verify(email=email, code=code)  # keeps the token
+        me = buyer.show()
+    """
+
+    def __init__(
+        self,
+        store_id: str,
+        *,
+        token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ) -> None:
+        """
+        store_id: the store's ID, from Settings, General. It is not a secret.
+        token:    a token from an earlier sign-in (`shoply_ct_...`), if you kept one.
+        """
+        if not isinstance(store_id, str) or store_id == "":
+            raise ShoplyError("Pass the store's ID as `store_id`. It is in Settings, General, in the store's dashboard.", code="store_id_required")
+
+        self.store_id = store_id
+        self.token = token
+        self._transport = Transport(base_url, timeout, max_retries, lambda: self.token)
+        self._resources()
+
+    def _call(self, id: str, path: List[str], fields: Dict[str, Any], options: Dict[str, Any]) -> Any:
+        route, values, query, body, _ = prepare(id, path, fields)
+
+        if route["signed_in"] and not self.token:
+            raise ShoplyError("Sign the buyer in first: login, then verify with the code they were emailed.", code="customer_token_required")
+
+        answer = self._transport.send(
+            route["method"], fill(route["path"], dict(values, storeId=self.store_id)),
+            query=query, body=body, idempotent=False, options=options,
+        )
+        assert isinstance(answer, dict)
+        data = answer.get("data")
+
+        # Signing in hands out the token; signing out ends it.
+        if id == "customer.verify" and isinstance(data, dict) and isinstance(data.get("token"), str):
+            self.token = data["token"]
+
+        if id in ("customer.logout", "customer.logoutEverywhere"):
+            self.token = None
+
+        return data

shoply-0.1.0/src/shoply/_errors.py

@@ -0,0 +1,32 @@
+from typing import Any, Dict, Optional
+
+
+class ShoplyError(Exception):
+    """A request Shoply refused, or one that never got an answer.
+
+    `status` is the HTTP status (0 when nothing answered), `code` the word that does not change
+    (`not_found`, `missing_scope`, `validation_failed`, `rate_limited`... and `connection_error`
+    or `timeout` when nothing answered), `errors` what is wrong with each field for
+    `validation_failed`, `request_id` what to quote to Shoply about it, `retry_after` the seconds
+    to wait when told to slow down, and `body` the whole answer.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: Optional[str] = None,
+        errors: Optional[Dict[str, str]] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[int] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.errors = errors
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body

shoply-0.1.0/src/shoply/_files.py

@@ -0,0 +1,26 @@
+import os
+from typing import Dict, Optional, Union
+
+
+class File:
+    """A route's answer that is a file, a CSV or a PDF, as it came: `body` its bytes, `headers` by
+    lowercase name."""
+
+    def __init__(self, body: bytes, headers: Dict[str, str]) -> None:
+        self.body = body
+        self.headers = headers
+
+    @property
+    def content_type(self) -> Optional[str]:
+        """Its type, "text/csv"."""
+        return self.headers.get("content-type")
+
+    def text(self, encoding: str = "utf-8-sig") -> str:
+        """Its body as text. A CSV from Shoply starts with a byte order mark, for spreadsheets,
+        which this leaves out."""
+        return self.body.decode(encoding)
+
+    def save(self, path: Union[str, "os.PathLike[str]"]) -> None:
+        """Written to a file."""
+        with open(path, "wb") as handle:
+            handle.write(self.body)

shoply-0.1.0/src/shoply/_generated/__init__.py

@@ -0,0 +1 @@
+# Written by scripts/generate.py from the API reference. Do not edit by hand.