alloy-cx 0.1.0__tar.gz

alloy_cx-0.1.0/LICENSE

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

alloy_cx-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: alloy-cx
+Version: 0.1.0
+Summary: Client for the Alloy private API: organization storage and databases
+Author: Alloy Systems
+License: MIT
+Project-URL: Homepage, https://alloy.cx
+Project-URL: Repository, https://github.com/Alloy-Systems/backend
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# alloy-cx
+
+Python client for the Alloy private API: organization storage and storage databases. No dependencies beyond the
+standard library; Python 3.9+.
+
+```bash
+pip install alloy-cx
+```
+
+## Authentication
+
+Code that Alloy runs for a user (the `run_code` workflow step, the `programming.run_code` tool, and commands in an
+AI teammate's sandbox) gets `ALLOY_API_URL` and a temporary `ALLOY_API_TOKEN` with that user's rights in its
+environment, so the client needs no arguments there:
+
+```python
+from alloy_cx import AlloyClient
+
+client = AlloyClient()
+```
+
+Elsewhere, pass a personal access token from Organization Settings → API Tokens:
+
+```python
+client = AlloyClient(token="alloy_pat_...", base_url="https://api.alloy.cx/api/private")
+```
+
+Never print the token or write it to a file.
+
+## Storage
+
+Paths are relative to the storage root.
+
+```python
+client.storage.list("reports")                          # direct children of a folder
+client.storage.upload("summary.csv", "a,b\n1,2\n", folder="reports")
+client.storage.meta("reports/summary.csv")              # size, hash, timestamps, MIME type
+client.storage.download("reports/summary.csv")          # bytes
+client.storage.download_text("reports/summary.csv")     # str
+client.storage.create_folder("2026", parent="reports")  # returns the new folder's path
+client.storage.rename("reports/summary.csv", "q1.csv")  # returns the new path
+client.storage.move("reports/q1.csv", "archive")        # moves into the folder, returns the new path
+client.storage.delete("archive/q1.csv")
+```
+
+## Databases
+
+```python
+client.databases.list()
+client.databases.tables("crm")
+client.databases.table("crm", "deals")                  # schema
+
+page = client.databases.rows(
+    "crm", "deals",
+    limit=50, order_by="amount", direction="DESC",
+    filters=[{"column": "stage", "operator": "equals", "value": "won"}],
+)
+page["rows"], page["total"]                             # rows: [{"id", "version", "values"}]
+
+ids = client.databases.insert("crm", "deals", [{"title": "Acme", "amount": 1200}])
+row = client.databases.row("crm", "deals", ids[0])
+client.databases.update("crm", "deals", row["id"], {"amount": 1500}, expected_version=row["version"])
+client.databases.update_many("crm", "deals", [{"id": ids[0], "values": {"stage": "won"}}])
+client.databases.delete("crm", "deals", ids)
+
+client.databases.query("crm", "SELECT stage, SUM(amount) FROM deals WHERE amount > ? GROUP BY stage", [100])
+```
+
+Filter operators: `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`, `greater_than`, `greater_or_equal`,
+`less_than`, `less_or_equal`, `is_empty`, `is_not_empty`. `match="any"` returns rows matching any filter instead of
+all of them. `query` accepts only `SELECT` and `WITH ... SELECT`.
+
+## Errors
+
+A failed request raises `AlloyApiError` with `status`, `message`, and the response `body`. With `expected_version`,
+an update of a row changed since that version fails with status `409`.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```

alloy_cx-0.1.0/README.md

@@ -0,0 +1,82 @@
+# alloy-cx
+
+Python client for the Alloy private API: organization storage and storage databases. No dependencies beyond the
+standard library; Python 3.9+.
+
+```bash
+pip install alloy-cx
+```
+
+## Authentication
+
+Code that Alloy runs for a user (the `run_code` workflow step, the `programming.run_code` tool, and commands in an
+AI teammate's sandbox) gets `ALLOY_API_URL` and a temporary `ALLOY_API_TOKEN` with that user's rights in its
+environment, so the client needs no arguments there:
+
+```python
+from alloy_cx import AlloyClient
+
+client = AlloyClient()
+```
+
+Elsewhere, pass a personal access token from Organization Settings → API Tokens:
+
+```python
+client = AlloyClient(token="alloy_pat_...", base_url="https://api.alloy.cx/api/private")
+```
+
+Never print the token or write it to a file.
+
+## Storage
+
+Paths are relative to the storage root.
+
+```python
+client.storage.list("reports")                          # direct children of a folder
+client.storage.upload("summary.csv", "a,b\n1,2\n", folder="reports")
+client.storage.meta("reports/summary.csv")              # size, hash, timestamps, MIME type
+client.storage.download("reports/summary.csv")          # bytes
+client.storage.download_text("reports/summary.csv")     # str
+client.storage.create_folder("2026", parent="reports")  # returns the new folder's path
+client.storage.rename("reports/summary.csv", "q1.csv")  # returns the new path
+client.storage.move("reports/q1.csv", "archive")        # moves into the folder, returns the new path
+client.storage.delete("archive/q1.csv")
+```
+
+## Databases
+
+```python
+client.databases.list()
+client.databases.tables("crm")
+client.databases.table("crm", "deals")                  # schema
+
+page = client.databases.rows(
+    "crm", "deals",
+    limit=50, order_by="amount", direction="DESC",
+    filters=[{"column": "stage", "operator": "equals", "value": "won"}],
+)
+page["rows"], page["total"]                             # rows: [{"id", "version", "values"}]
+
+ids = client.databases.insert("crm", "deals", [{"title": "Acme", "amount": 1200}])
+row = client.databases.row("crm", "deals", ids[0])
+client.databases.update("crm", "deals", row["id"], {"amount": 1500}, expected_version=row["version"])
+client.databases.update_many("crm", "deals", [{"id": ids[0], "values": {"stage": "won"}}])
+client.databases.delete("crm", "deals", ids)
+
+client.databases.query("crm", "SELECT stage, SUM(amount) FROM deals WHERE amount > ? GROUP BY stage", [100])
+```
+
+Filter operators: `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`, `greater_than`, `greater_or_equal`,
+`less_than`, `less_or_equal`, `is_empty`, `is_not_empty`. `match="any"` returns rows matching any filter instead of
+all of them. `query` accepts only `SELECT` and `WITH ... SELECT`.
+
+## Errors
+
+A failed request raises `AlloyApiError` with `status`, `message`, and the response `body`. With `expected_version`,
+an update of a row changed since that version fails with status `409`.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```

alloy_cx-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "alloy-cx"
+version = "0.1.0"
+description = "Client for the Alloy private API: organization storage and databases"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Alloy Systems" }]
+requires-python = ">=3.9"
+dependencies = []
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://alloy.cx"
+Repository = "https://github.com/Alloy-Systems/backend"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+alloy_cx = ["py.typed"]

alloy_cx-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

alloy_cx-0.1.0/src/alloy_cx/__init__.py

@@ -0,0 +1,35 @@
+"""Client for the Alloy private API: organization storage and databases."""
+
+import os
+from typing import Optional
+
+from ._http import DEFAULT_TIMEOUT_SECONDS, AlloyApiError, HttpClient
+from .databases import DatabasesApi
+from .storage import StorageApi
+
+__all__ = ["AlloyApiError", "AlloyClient", "DatabasesApi", "StorageApi"]
+
+
+class AlloyClient:
+    """Client for the Alloy private API.
+
+    Inside an Alloy sandbox it needs no arguments: the token and URL come from ``ALLOY_API_TOKEN``
+    and ``ALLOY_API_URL``, and every call runs with the rights of the user the code runs for.
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        token = token or os.environ.get("ALLOY_API_TOKEN")
+        base_url = base_url or os.environ.get("ALLOY_API_URL")
+        if not token or not base_url:
+            raise ValueError(
+                "Alloy API token and URL are required: pass token and base_url, or set ALLOY_API_TOKEN and ALLOY_API_URL"
+            )
+
+        http = HttpClient(base_url, token, timeout)
+        self.storage = StorageApi(http)
+        self.databases = DatabasesApi(http)

alloy_cx-0.1.0/src/alloy_cx/_http.py

@@ -0,0 +1,120 @@
+import json
+import uuid
+from typing import Any, Dict, Mapping, Optional, Tuple, Union
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+QueryValue = Union[str, int, bool, None]
+
+DEFAULT_TIMEOUT_SECONDS = 60
+
+
+class AlloyApiError(Exception):
+    """A non-2xx answer from the API. ``body`` is the parsed response, or its text when it is not JSON."""
+
+    def __init__(self, status: int, message: str, body: Any) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+def _parse(raw: bytes) -> Any:
+    text = raw.decode("utf-8", errors="replace")
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _error_message(body: Any, status: int) -> str:
+    """Reads the message out of either error shape the API answers with."""
+    if isinstance(body, dict):
+        if isinstance(body.get("message"), str):
+            return body["message"]
+        error = body.get("error")
+        if isinstance(error, str):
+            return error
+        if isinstance(error, dict) and isinstance(error.get("message"), str):
+            return error["message"]
+    if isinstance(body, str) and body:
+        return body
+    return f"Request failed with status {status}"
+
+
+def _multipart(fields: Mapping[str, str], file_field: str, file_name: str, content: bytes) -> Tuple[bytes, str]:
+    boundary = uuid.uuid4().hex
+    # Quotes and line breaks would end the header value early; browsers percent-encode them the same way.
+    file_name = file_name.replace('"', "%22").replace("\r", "%0D").replace("\n", "%0A")
+    parts = []
+    for name, value in fields.items():
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'.encode("utf-8")
+        )
+    parts.append(
+        f'--{boundary}\r\nContent-Disposition: form-data; name="{file_field}"; filename="{file_name}"\r\n'
+        "Content-Type: application/octet-stream\r\n\r\n".encode("utf-8")
+        + content
+        + b"\r\n"
+    )
+    parts.append(f"--{boundary}--\r\n".encode("utf-8"))
+    return b"".join(parts), f"multipart/form-data; boundary={boundary}"
+
+
+class HttpClient:
+    def __init__(self, base_url: str, token: str, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Mapping[str, QueryValue]] = None,
+        json_body: Any = None,
+        upload: Optional[Tuple[Mapping[str, str], str, bytes]] = None,
+    ) -> Any:
+        """Sends a request and returns the ``data`` of the JSON envelope."""
+        body = _parse(self._send(method, path, query, json_body, upload))
+        return body.get("data") if isinstance(body, dict) else None
+
+    def request_bytes(self, method: str, path: str, query: Optional[Mapping[str, QueryValue]] = None) -> bytes:
+        """Sends a request and returns the raw response body."""
+        return self._send(method, path, query, None, None)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Mapping[str, QueryValue]],
+        json_body: Any,
+        upload: Optional[Tuple[Mapping[str, str], str, bytes]],
+    ) -> bytes:
+        url = self._base_url + path
+        params = {name: _query_value(value) for name, value in (query or {}).items() if value is not None}
+        if params:
+            url += "?" + urlencode(params)
+
+        headers: Dict[str, str] = {"Authorization": f"Bearer {self._token}"}
+        data: Optional[bytes] = None
+        if upload is not None:
+            fields, file_name, content = upload
+            data, headers["Content-Type"] = _multipart(fields, "file", file_name, content)
+        elif json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        try:
+            with urlopen(Request(url, data=data, headers=headers, method=method), timeout=self._timeout) as response:
+                return response.read()
+        except HTTPError as error:
+            body = _parse(error.read())
+            raise AlloyApiError(error.code, _error_message(body, error.code), body) from None
+
+
+def _query_value(value: Union[str, int, bool]) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)

alloy_cx-0.1.0/src/alloy_cx/databases.py

@@ -0,0 +1,102 @@
+import json
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+from urllib.parse import quote
+
+from ._http import HttpClient
+
+CellValue = Union[str, int, float, bool, None]
+
+
+def _segment(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _table_path(database: str, table: str) -> str:
+    return f"/databases/{_segment(database)}/tables/{_segment(table)}"
+
+
+class DatabasesApi:
+    """The organization's storage databases: tables, rows, and read-only SQL."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> List[Dict[str, Any]]:
+        return self._http.request("GET", "/databases")["databases"]
+
+    def tables(self, database: str) -> List[Dict[str, Any]]:
+        return self._http.request("GET", f"/databases/{_segment(database)}/tables")["tables"]
+
+    def table(self, database: str, table: str) -> Dict[str, Any]:
+        return self._http.request("GET", _table_path(database, table))["table"]
+
+    def rows(
+        self,
+        database: str,
+        table: str,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        order_by: Optional[str] = None,
+        direction: Optional[str] = None,
+        match: Optional[str] = None,
+        filters: Optional[Sequence[Mapping[str, CellValue]]] = None,
+    ) -> Dict[str, Any]:
+        """Returns ``{"rows": [...], "total": n}``; ``total`` counts every row matching the filters.
+
+        Each filter is ``{"column": ..., "operator": ..., "value": ...}`` with an operator such as
+        ``equals``, ``contains`` or ``greater_than``; ``match`` is ``"all"`` (the default) or ``"any"``.
+        """
+        return self._http.request(
+            "GET",
+            f"{_table_path(database, table)}/rows",
+            query={
+                "limit": limit,
+                "offset": offset,
+                "order_by": order_by,
+                "direction": direction,
+                "match": match,
+                "filters": None if filters is None else json.dumps(list(filters)),
+            },
+        )
+
+    def row(self, database: str, table: str, row_id: int) -> Dict[str, Any]:
+        return self._http.request("GET", f"{_table_path(database, table)}/rows/{row_id}")["row"]
+
+    def insert(self, database: str, table: str, rows: Sequence[Mapping[str, CellValue]]) -> List[int]:
+        """Inserts rows and returns their ids, in order."""
+        body = {"rows": [dict(row) for row in rows]}
+        return self._http.request("POST", f"{_table_path(database, table)}/rows", json_body=body)["ids"]
+
+    def update(
+        self,
+        database: str,
+        table: str,
+        row_id: int,
+        values: Mapping[str, CellValue],
+        expected_version: Optional[int] = None,
+    ) -> bool:
+        """Updates one row. With ``expected_version`` it fails with a 409 when the row changed since; otherwise the last write wins."""
+        body: Dict[str, Any] = {"values": dict(values)}
+        if expected_version is not None:
+            body["expected_version"] = expected_version
+        return self._http.request("PATCH", f"{_table_path(database, table)}/rows/{row_id}", json_body=body)["updated"]
+
+    def update_many(self, database: str, table: str, updates: Sequence[Mapping[str, Any]]) -> int:
+        """Updates several rows, all or none, and returns how many changed.
+
+        Each update is ``{"id": ..., "values": {...}}``, optionally with ``"expected_version"``.
+        """
+        body = {"updates": [dict(update) for update in updates]}
+        return self._http.request("PATCH", f"{_table_path(database, table)}/rows", json_body=body)["updated"]
+
+    def delete(self, database: str, table: str, ids: Sequence[int]) -> int:
+        """Deletes rows by id and returns how many were deleted."""
+        return self._http.request("DELETE", f"{_table_path(database, table)}/rows", json_body={"ids": list(ids)})["deleted"]
+
+    def query(self, database: str, sql: str, params: Sequence[CellValue] = ()) -> Dict[str, Any]:
+        """Runs a read-only ``SELECT`` (or ``WITH ... SELECT``) with ``?`` placeholders bound to ``params``.
+
+        Returns ``{"columns": [...], "rows": [[...]], "truncated": bool}``.
+        """
+        body = {"sql": sql, "params": list(params)}
+        return self._http.request("POST", f"/databases/{_segment(database)}/query", json_body=body)

alloy_cx-0.1.0/src/alloy_cx/storage.py

@@ -0,0 +1,47 @@
+from typing import Any, Dict, List, Optional, Union
+
+from ._http import HttpClient
+
+
+class StorageApi:
+    """Organization storage, with the rights of the token's user. Paths are relative to the storage root."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, path: str = "/") -> List[Dict[str, Any]]:
+        """Lists the direct children of a folder; the root by default."""
+        return self._http.request("GET", "/storage", query={"path": path})
+
+    def upload(self, name: str, content: Union[bytes, str], folder: Optional[str] = None) -> Dict[str, Any]:
+        """Uploads a file named ``name`` into ``folder`` (the root by default), overwriting a file of the same name."""
+        data = content.encode("utf-8") if isinstance(content, str) else content
+        fields = {} if folder is None else {"path": folder}
+        return self._http.request("POST", "/storage/upload", upload=(fields, name, data))
+
+    def meta(self, path: str) -> Dict[str, Any]:
+        return self._http.request("GET", "/storage/meta", query={"path": path})
+
+    def download(self, path: str) -> bytes:
+        return self._http.request_bytes("GET", "/storage/download", query={"path": path})
+
+    def download_text(self, path: str, encoding: str = "utf-8") -> str:
+        return self.download(path).decode(encoding)
+
+    def delete(self, path: str) -> None:
+        """Deletes a file or a folder with everything in it."""
+        self._http.request("DELETE", "/storage/file", query={"path": path})
+
+    def create_folder(self, name: str, parent: Optional[str] = None) -> str:
+        """Creates folder ``name`` inside ``parent`` (the root by default) and returns its path."""
+        body = {"name": name} if parent is None else {"name": name, "path": parent}
+        return self._http.request("POST", "/storage/folder", json_body=body)["path"]
+
+    def rename(self, path: str, new_name: str) -> str:
+        """Renames a file or folder in place and returns its new path."""
+        return self._http.request("POST", "/storage/rename", json_body={"path": path, "new_name": new_name})["path"]
+
+    def move(self, path: str, destination: str) -> str:
+        """Moves a file or folder into the folder ``destination`` and returns its new path."""
+        body = {"source_path": path, "dest_path": destination}
+        return self._http.request("POST", "/storage/move", json_body=body)["path"]

alloy_cx-0.1.0/src/alloy_cx.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: alloy-cx
+Version: 0.1.0
+Summary: Client for the Alloy private API: organization storage and databases
+Author: Alloy Systems
+License: MIT
+Project-URL: Homepage, https://alloy.cx
+Project-URL: Repository, https://github.com/Alloy-Systems/backend
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# alloy-cx
+
+Python client for the Alloy private API: organization storage and storage databases. No dependencies beyond the
+standard library; Python 3.9+.
+
+```bash
+pip install alloy-cx
+```
+
+## Authentication
+
+Code that Alloy runs for a user (the `run_code` workflow step, the `programming.run_code` tool, and commands in an
+AI teammate's sandbox) gets `ALLOY_API_URL` and a temporary `ALLOY_API_TOKEN` with that user's rights in its
+environment, so the client needs no arguments there:
+
+```python
+from alloy_cx import AlloyClient
+
+client = AlloyClient()
+```
+
+Elsewhere, pass a personal access token from Organization Settings → API Tokens:
+
+```python
+client = AlloyClient(token="alloy_pat_...", base_url="https://api.alloy.cx/api/private")
+```
+
+Never print the token or write it to a file.
+
+## Storage
+
+Paths are relative to the storage root.
+
+```python
+client.storage.list("reports")                          # direct children of a folder
+client.storage.upload("summary.csv", "a,b\n1,2\n", folder="reports")
+client.storage.meta("reports/summary.csv")              # size, hash, timestamps, MIME type
+client.storage.download("reports/summary.csv")          # bytes
+client.storage.download_text("reports/summary.csv")     # str
+client.storage.create_folder("2026", parent="reports")  # returns the new folder's path
+client.storage.rename("reports/summary.csv", "q1.csv")  # returns the new path
+client.storage.move("reports/q1.csv", "archive")        # moves into the folder, returns the new path
+client.storage.delete("archive/q1.csv")
+```
+
+## Databases
+
+```python
+client.databases.list()
+client.databases.tables("crm")
+client.databases.table("crm", "deals")                  # schema
+
+page = client.databases.rows(
+    "crm", "deals",
+    limit=50, order_by="amount", direction="DESC",
+    filters=[{"column": "stage", "operator": "equals", "value": "won"}],
+)
+page["rows"], page["total"]                             # rows: [{"id", "version", "values"}]
+
+ids = client.databases.insert("crm", "deals", [{"title": "Acme", "amount": 1200}])
+row = client.databases.row("crm", "deals", ids[0])
+client.databases.update("crm", "deals", row["id"], {"amount": 1500}, expected_version=row["version"])
+client.databases.update_many("crm", "deals", [{"id": ids[0], "values": {"stage": "won"}}])
+client.databases.delete("crm", "deals", ids)
+
+client.databases.query("crm", "SELECT stage, SUM(amount) FROM deals WHERE amount > ? GROUP BY stage", [100])
+```
+
+Filter operators: `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`, `greater_than`, `greater_or_equal`,
+`less_than`, `less_or_equal`, `is_empty`, `is_not_empty`. `match="any"` returns rows matching any filter instead of
+all of them. `query` accepts only `SELECT` and `WITH ... SELECT`.
+
+## Errors
+
+A failed request raises `AlloyApiError` with `status`, `message`, and the response `body`. With `expected_version`,
+an update of a row changed since that version fails with status `409`.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```

alloy_cx-0.1.0/src/alloy_cx.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/alloy_cx/__init__.py
+src/alloy_cx/_http.py
+src/alloy_cx/databases.py
+src/alloy_cx/py.typed
+src/alloy_cx/storage.py
+src/alloy_cx.egg-info/PKG-INFO
+src/alloy_cx.egg-info/SOURCES.txt
+src/alloy_cx.egg-info/dependency_links.txt
+src/alloy_cx.egg-info/top_level.txt
+tests/test_client.py

alloy_cx-0.1.0/src/alloy_cx.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

alloy_cx-0.1.0/src/alloy_cx.egg-info/top_level.txt

@@ -0,0 +1 @@
+alloy_cx

alloy_cx-0.1.0/tests/test_client.py

@@ -0,0 +1,130 @@
+import json
+import os
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Callable, Dict, List
+from unittest import mock
+from urllib.parse import parse_qsl, urlsplit
+
+from alloy_cx import AlloyApiError, AlloyClient
+
+Respond = Callable[[Dict[str, Any]], Dict[str, Any]]
+
+
+def ok(data: Any) -> Dict[str, Any]:
+    return {"json": {"success": True, "data": data}}
+
+
+class StubApi:
+    """A stand-in for the private API: records each request and answers with what ``respond`` returns."""
+
+    def __init__(self, respond: Respond) -> None:
+        self.requests: List[Dict[str, Any]] = []
+        api = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def handle_one(self) -> None:
+                url = urlsplit(self.path)
+                length = int(self.headers.get("Content-Length") or 0)
+                request = {
+                    "method": self.command,
+                    "path": url.path,
+                    "query": dict(parse_qsl(url.query)),
+                    "headers": {name.lower(): value for name, value in self.headers.items()},
+                    "body": self.rfile.read(length),
+                }
+                api.requests.append(request)
+                answer = respond(request)
+                raw = answer["raw"] if "raw" in answer else json.dumps(answer["json"]).encode("utf-8")
+                self.send_response(answer.get("status", 200))
+                self.send_header("Content-Length", str(len(raw)))
+                self.end_headers()
+                self.wfile.write(raw)
+
+            do_GET = do_POST = do_PATCH = do_DELETE = handle_one
+
+            def log_message(self, *args: Any) -> None:
+                pass
+
+        self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=self._server.serve_forever, daemon=True).start()
+        self.base_url = f"http://127.0.0.1:{self._server.server_address[1]}/api/private/"
+
+    def close(self) -> None:
+        self._server.shutdown()
+        self._server.server_close()
+
+
+class AlloyClientTest(unittest.TestCase):
+    def start(self, respond: Respond) -> StubApi:
+        api = StubApi(respond)
+        self.addCleanup(api.close)
+        return api
+
+    def client(self, api: StubApi) -> AlloyClient:
+        return AlloyClient(token="alloy_tmp_secret", base_url=api.base_url)
+
+    def test_takes_the_token_and_url_from_the_environment_and_sends_a_bearer_token(self) -> None:
+        api = self.start(lambda request: ok([]))
+
+        with mock.patch.dict(os.environ, {}, clear=True):
+            with self.assertRaisesRegex(ValueError, "ALLOY_API_TOKEN and ALLOY_API_URL"):
+                AlloyClient()
+
+        with mock.patch.dict(os.environ, {"ALLOY_API_TOKEN": "alloy_tmp_secret", "ALLOY_API_URL": api.base_url}):
+            AlloyClient().storage.list("reports")
+
+        request = api.requests[0]
+        self.assertEqual(request["headers"]["authorization"], "Bearer alloy_tmp_secret")
+        self.assertEqual(request["path"], "/api/private/storage")
+        self.assertEqual(request["query"], {"path": "reports"})
+
+    def test_storage_uploads_a_file_as_multipart_and_downloads_it_back(self) -> None:
+        uploaded = {"path": "reports/data.csv", "name": "data.csv", "size": 8, "mimetype": "text/csv"}
+        api = self.start(lambda request: {"raw": b"a,b\n1,2\n"} if request["path"].endswith("/download") else ok(uploaded))
+        client = self.client(api)
+
+        self.assertEqual(client.storage.upload("data.csv", "a,b\n1,2\n", folder="reports"), uploaded)
+        self.assertEqual(client.storage.download_text("reports/data.csv"), "a,b\n1,2\n")
+
+        upload = api.requests[0]
+        self.assertRegex(upload["headers"]["content-type"], r"^multipart/form-data; boundary=")
+        self.assertIn(b'name="path"\r\n\r\nreports\r\n', upload["body"])
+        self.assertRegex(upload["body"], rb'name="file"; filename="data.csv"\r\n[^\r]*\r\n\r\na,b\n1,2\n\r\n')
+        self.assertEqual(api.requests[1]["query"], {"path": "reports/data.csv"})
+
+    def test_databases_send_filters_as_json_and_the_expected_version(self) -> None:
+        page = {"rows": [{"id": 2, "version": 1, "values": {"title": "Beta", "amount": 20}}], "total": 1}
+        api = self.start(lambda request: ok(page) if request["method"] == "GET" else ok({"updated": True}))
+        client = self.client(api)
+        filters = [{"column": "amount", "operator": "greater_than", "value": 15}]
+
+        self.assertEqual(client.databases.rows("crm", "deals", limit=10, order_by="amount", direction="DESC", filters=filters), page)
+        self.assertTrue(client.databases.update("crm", "deals", 2, {"title": "Beta 2"}, expected_version=1))
+
+        listing, update = api.requests
+        self.assertEqual(listing["path"], "/api/private/databases/crm/tables/deals/rows")
+        self.assertEqual(listing["query"], {"limit": "10", "order_by": "amount", "direction": "DESC", "filters": json.dumps(filters)})
+        self.assertEqual((update["method"], update["path"]), ("PATCH", "/api/private/databases/crm/tables/deals/rows/2"))
+        self.assertEqual(json.loads(update["body"]), {"values": {"title": "Beta 2"}, "expected_version": 1})
+
+    def test_an_error_answer_raises_alloy_api_error_with_the_status_and_message(self) -> None:
+        def respond(request: Dict[str, Any]) -> Dict[str, Any]:
+            if request["path"].endswith("/rows/1"):
+                return {"status": 409, "json": {"success": False, "error": {"message": "Rows changed since they were read: 1"}}}
+            return {"status": 401, "json": {"error": "Unauthorized access"}}
+
+        client = self.client(self.start(respond))
+
+        with self.assertRaises(AlloyApiError) as conflict:
+            client.databases.update("crm", "deals", 1, {"title": "Stale"}, expected_version=1)
+        self.assertEqual((conflict.exception.status, conflict.exception.message), (409, "Rows changed since they were read: 1"))
+
+        with self.assertRaises(AlloyApiError) as unauthorized:
+            client.databases.list()
+        self.assertEqual((unauthorized.exception.status, unauthorized.exception.message), (401, "Unauthorized access"))
+
+
+if __name__ == "__main__":
+    unittest.main()