superartifacts 0.1.0__py3-none-any.whl

superartifacts/_helpers.py

@@ -0,0 +1,195 @@
+"""The hand-written parts of the resources: paging, the upload round trip and publishing a file."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+from ._errors import SuperArtifactsError
+
+OMIT: Any = object()
+"""Leave a field out, where None would send a null that means something."""
+
+Files = Mapping[str, "bytes | str | os.PathLike[str]"]
+
+
+def _items(page: dict[str, Any], key: str) -> list[Any]:
+    items = page.get(key)
+    if items is None:
+        raise SuperArtifactsError(f"This read answered no {key!r} to page through.")
+    return items
+
+
+def _next_cursor(page: dict[str, Any]) -> str | None:
+    # Data reads answer `cursor.next`, mentions answer `cursorNext`.
+    cursor = page.get("cursor")
+    return cursor.get("next") if isinstance(cursor, dict) else page.get("cursorNext")
+
+
+def _last_page(page: dict[str, Any], number: int, items: list[Any]) -> bool:
+    return not items or (number + 1) * page.get("pageSize", len(items)) >= page.get("total", 0)
+
+
+def walk_cursor(fetch: Callable[..., Any], key: str, args: dict[str, Any]) -> Iterator[Any]:
+    args = dict(args)
+    while True:
+        page = fetch(**args)
+        yield from _items(page, key)
+        args["cursor"] = _next_cursor(page)
+        if not args["cursor"]:
+            return
+
+
+async def awalk_cursor(
+    fetch: Callable[..., Any], key: str, args: dict[str, Any]
+) -> AsyncIterator[Any]:
+    args = dict(args)
+    while True:
+        page = await fetch(**args)
+        for item in _items(page, key):
+            yield item
+        args["cursor"] = _next_cursor(page)
+        if not args["cursor"]:
+            return
+
+
+def walk_pages(fetch: Callable[..., Any], key: str, args: dict[str, Any]) -> Iterator[Any]:
+    args = dict(args)
+    args.setdefault("page", 0)
+    while True:
+        page = fetch(**args)
+        items = _items(page, key)
+        yield from items
+        if _last_page(page, args["page"], items):
+            return
+        args["page"] += 1
+
+
+async def awalk_pages(
+    fetch: Callable[..., Any], key: str, args: dict[str, Any]
+) -> AsyncIterator[Any]:
+    args = dict(args)
+    args.setdefault("page", 0)
+    while True:
+        page = await fetch(**args)
+        items = _items(page, key)
+        for item in items:
+            yield item
+        if _last_page(page, args["page"], items):
+            return
+        args["page"] += 1
+
+
+def _read(files: Files) -> dict[str, bytes]:
+    return {
+        path: bytes(source) if isinstance(source, (bytes, bytearray)) else Path(source).read_bytes()
+        for path, source in files.items()
+    }
+
+
+def _declare(blobs: dict[str, bytes]) -> list[dict[str, Any]]:
+    return [{"path": path, "bytes": len(blob)} for path, blob in blobs.items()]
+
+
+class UploadHelper:
+    def upload(self, files: Files, *, timeout: float | None = None) -> dict[str, Any]:
+        """Stage `{path in the artifact: bytes or local file}` and PUT each file.
+
+        Returns what `stage` answered; pass its `uploadId` to
+        `artifacts.publish(uploads=...)`. The URLs are the credential, so the
+        API key is not sent with the bytes.
+        """
+        blobs = _read(files)
+        staged = self.stage(files=_declare(blobs), timeout=timeout)  # type: ignore[attr-defined]
+        # The answer lists the files in the order they were declared.
+        for upload, blob in zip(staged["uploads"], blobs.values(), strict=True):
+            self._client._request("PUT", upload["url"], timeout, {"content": blob})  # type: ignore[attr-defined]
+        return staged
+
+
+class AsyncUploadHelper:
+    async def upload(self, files: Files, *, timeout: float | None = None) -> dict[str, Any]:
+        """Stage `{path in the artifact: bytes or local file}` and PUT each file.
+
+        Returns what `stage` answered; pass its `uploadId` to
+        `artifacts.publish(uploads=...)`. The URLs are the credential, so the
+        API key is not sent with the bytes.
+        """
+        blobs = _read(files)
+        staged = await self.stage(files=_declare(blobs), timeout=timeout)  # type: ignore[attr-defined]
+        for upload, blob in zip(staged["uploads"], blobs.values(), strict=True):
+            await self._client._request("PUT", upload["url"], timeout, {"content": blob})  # type: ignore[attr-defined]
+        return staged
+
+
+def _slug_of(path: Path) -> str:
+    name = path.parent.name if path.name == "index.html" else path.stem if path.is_file() else path.name
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def _gather(path: str | os.PathLike[str], slug: str | None) -> tuple[str, str, dict[str, Path]]:
+    """Resolve `path` to (slug, index.html text, every other file by its path in the artifact)."""
+    root = Path(path).resolve()
+    slug = slug or _slug_of(root)
+    if not slug:
+        raise SuperArtifactsError(f"Cannot name an artifact after {str(root)!r}: pass slug=.")
+    if root.is_file():
+        return slug, root.read_text(encoding="utf-8"), {}
+    if not (root / "index.html").is_file():
+        raise SuperArtifactsError(f"{str(root)!r} is not a file, or a folder with an index.html.")
+    beside = {
+        file.relative_to(root).as_posix(): file
+        for file in sorted(root.rglob("*"))
+        if file.is_file() and not any(part.startswith(".") for part in file.relative_to(root).parts)
+    }
+    html = beside.pop("index.html").read_text(encoding="utf-8")
+    return slug, html, beside
+
+
+class ArtifactHelper:
+    def publish_file(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        slug: str | None = None,
+        timeout: float | None = None,
+        **fields: Any,
+    ) -> dict[str, Any]:
+        """Publish a page you already made: an HTML file, or a folder with an `index.html`.
+
+        The page comes from your own model, your own tools, your own build; this
+        hosts it. A folder's other files go up beside it, uploaded for you. `slug`
+        defaults to the file's name (the folder's name for a folder or an
+        `index.html`); every other field is what `publish` takes.
+        """
+        slug, html, beside = _gather(path, slug)
+        if beside:
+            staged = self._client.uploads.upload(beside, timeout=timeout)  # type: ignore[attr-defined]
+            fields["uploads"] = staged["uploadId"]
+        return self.publish(slug=slug, html=html, timeout=timeout, **fields)  # type: ignore[attr-defined]
+
+
+class AsyncArtifactHelper:
+    async def publish_file(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        slug: str | None = None,
+        timeout: float | None = None,
+        **fields: Any,
+    ) -> dict[str, Any]:
+        """Publish a page you already made: an HTML file, or a folder with an `index.html`.
+
+        The page comes from your own model, your own tools, your own build; this
+        hosts it. A folder's other files go up beside it, uploaded for you. `slug`
+        defaults to the file's name (the folder's name for a folder or an
+        `index.html`); every other field is what `publish` takes.
+        """
+        slug, html, beside = _gather(path, slug)
+        if beside:
+            staged = await self._client.uploads.upload(beside, timeout=timeout)  # type: ignore[attr-defined]
+            fields["uploads"] = staged["uploadId"]
+        return await self.publish(slug=slug, html=html, timeout=timeout, **fields)  # type: ignore[attr-defined]

superartifacts-0.1.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.5
+Name: superartifacts
+Version: 0.1.0
+Summary: Python SDK for the Super Artifacts REST API: publish artifacts and read their data from your own code.
+Project-URL: Homepage, https://superartifacts.app/docs/sdks/python
+Project-URL: Repository, https://github.com/Superbelt/sdk
+Project-URL: Issues, https://github.com/Superbelt/sdk/issues
+Author: Super Artifacts
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,artifacts,publishing,sdk,super-artifacts
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2
+Description-Content-Type: text/markdown
+
+# Super Artifacts for Python
+
+Needs a Solo plan or higher. MCP and skills are unaffected.
+
+The official Python SDK for the [Super Artifacts](https://superartifacts.app) REST API: publish
+artifacts, read what visitors submitted, manage projects and templates, from your own code.
+
+Full docs: <https://superartifacts.app/docs/sdks/python>
+
+## Install
+
+```bash
+pip install superartifacts
+```
+
+Python 3.10 or newer. Create a key in
+[Settings → API keys](https://superartifacts.app/settings/api-keys).
+
+## Quickstart
+
+```python
+import os
+
+from superartifacts import SuperArtifacts
+
+sa = SuperArtifacts(api_key=os.environ["SUPERARTIFACTS_API_KEY"])
+
+print(sa.account.whoami()["handle"])
+
+sa.artifacts.publish(
+    slug="hello",
+    html="<!doctype html><h1>Hello</h1>",
+)
+
+for artifact in sa.artifacts.list()["artifacts"]:
+    print(artifact["slug"])
+
+for row in sa.data.iter_artifact_rows(artifact="hello"):
+    print(row)
+```
+
+`api_key` falls back to `SUPERARTIFACTS_API_KEY`, so `SuperArtifacts()` is enough.
+
+Keyword arguments hold path, query and body fields together, in snake_case: the SDK splits them
+as the API expects, so `values_file=` goes out as `valuesFile`. Values nested inside a dict keep
+the API's spelling. Answers are plain dicts, as the
+[API reference](https://superartifacts.app/docs/reference/api-endpoints) describes them.
+
+**Server-side only.** The API refuses any request carrying an `Origin` header, which every browser
+adds. Keep the key on a server.
+
+## Async
+
+`AsyncSuperArtifacts` is the same surface, awaited:
+
+```python
+import asyncio
+
+from superartifacts import AsyncSuperArtifacts
+
+
+async def main():
+    async with AsyncSuperArtifacts() as sa:
+        print(await sa.account.whoami())
+        async for row in sa.data.iter_artifact_rows(artifact="hello"):
+            print(row)
+
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+SuperArtifacts(
+    api_key=None,  # or SUPERARTIFACTS_API_KEY
+    base_url="https://superartifacts.app",
+    timeout=60.0,  # seconds
+    max_retries=2,
+    http_client=None,  # your own httpx.Client; yours to close
+)
+```
+
+Every method also takes `timeout=` for that call, and every `POST` takes `idempotency_key=`.
+Use the client as a context manager, or call `close()`.
+
+## Errors
+
+Everything raised is a `SuperArtifactsError`, with `.status`, `.code`, `.message`, `.retry_after`
+and the full error object in `.details`.
+A client-side failure has `.status` 0 and its own `.code`: a missing key is an `AuthenticationError`
+with `missing_api_key`.
+
+| Status | Exception |
+| --- | --- |
+| 400 | `InvalidArgumentsError` |
+| 401 | `AuthenticationError` (also raised when there is no key) |
+| 402 | `PlanLimitError` |
+| 403 | `PermissionError`, or `ScopeRequiredError` when a read key tried a write |
+| 404 | `NotFoundError` |
+| 409 | `ConflictError` |
+| 413 | `PayloadTooLargeError` |
+| 429 | `RateLimitError` |
+| 5xx | `InternalError` |
+| none | `APIConnectionError`, `APITimeoutError` |
+
+```python
+from superartifacts import NotFoundError
+
+try:
+    sa.artifacts.get(artifact="missing")
+except NotFoundError as error:
+    print(error.code, error.message)
+```
+
+`superartifacts.PermissionError` is not the builtin of that name: import it by name when you
+catch it.
+
+## Retries
+
+Up to `max_retries` more tries, two by default:
+
+- A `429` is retried after its `Retry-After`. Past 60 seconds it is not waited out: the
+  `RateLimitError` comes straight back with `retry_after` set.
+- `502`, `503`, `504` and network errors are retried with exponential backoff and jitter, for
+  `GET`, `DELETE` and `POST`.
+- `PATCH` and `PUT` are retried on `429` only. `500` and every other `4xx` are never retried.
+
+Every `POST` sends an `Idempotency-Key`, one per call and the same across its retries, so a retried
+publish happens once. Pass `idempotency_key=` to choose your own, which also makes a retry of your
+own code safe.
+
+## Pagination
+
+`iter_*` methods walk every page and yield one item at a time, taking the same arguments as the
+list they wrap:
+
+| Method | Wraps |
+| --- | --- |
+| `sa.data.iter_rows(...)` | `sa.data.list_rows(...)`, with `dataset=` or `collection=` |
+| `sa.data.iter_artifact_rows(...)` | `sa.data.list_artifact_rows(...)` |
+| `sa.entries.iter(...)` | `sa.entries.list(...)` |
+| `sa.mentions.iter(...)` | `sa.mentions.list(...)` |
+
+## Publish a page you made
+
+Super Artifacts runs no model: you bring the inference. Make the page with your own model, write it
+to a file, publish the file.
+
+```python
+from pathlib import Path
+
+from anthropic import Anthropic
+from superartifacts import SuperArtifacts
+
+# Your model, your key. We run no inference.
+msg = Anthropic().messages.create(
+    model="claude-haiku-5-5",
+    max_tokens=4000,
+    messages=[{
+        "role": "user",
+        "content": "A launch checklist. HTML only.",
+    }],
+)
+Path("checklist.html").write_text(
+    msg.content[0].text
+)
+
+# We host the file. Reads SUPERARTIFACTS_API_KEY
+sa = SuperArtifacts()
+page = sa.artifacts.publish_file(
+    "checklist.html"
+)
+print(page["url"])
+```
+
+`publish_file` takes an HTML file, or a folder with an `index.html` (its other files are uploaded
+beside it). The slug defaults to the file's or folder's name. `prompt` is optional: send it only if
+you want the request shown on the artifact's card; nothing is generated from it.
+
+## Uploads
+
+A JSON body stops at 1 MiB. Bigger files go through `uploads.upload`, which stages them and sends
+the bytes straight to their upload URLs. It takes a mapping of path in the artifact to bytes or a
+local file, within the limits of 5 MiB a file and 10 MiB a set:
+
+```python
+staged = sa.uploads.upload({"images/hero.png": "./hero.png", "notes.txt": b"hello"})
+
+sa.artifacts.publish(
+    slug="hello",
+    html='<!doctype html><img src="images/hero.png">',
+    uploads=staged["uploadId"],
+)
+```
+
+## License
+
+MIT
+
+## Webhook endpoints for an agent
+
+Create an endpoint filtered to the agent that owns the calling key. Store the returned
+signing secret in the receiver’s secret store; it is returned only by create and rotate.
+The listener must be publicly reachable. Mutations require a key with write scope.
+
+```python
+endpoint = sa.webhooks.create(
+    url="https://agent.example/webhook",
+    agent="me",
+    event_types=["trigger.fired"],
+)
+# Save endpoint["secret"] securely; never log it.
+sa.webhooks.test(id=endpoint["id"])
+messages = sa.webhooks.messages(id=endpoint["id"], since_minutes=60)
+```

superartifacts-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+superartifacts/__init__.py,sha256=WVslkhjAbGv8Bc1oKVO9M9gjavnR6bLLNpRIiizW6H0,925
+superartifacts/_client.py,sha256=nd7TVKKlBfPh4zYMQW-JiyocPz5KCcjLI5nRWneGdZo,10107
+superartifacts/_errors.py,sha256=HYhnW9rutgRQg14z4kSSj0sBQKYVmbDg91kp6Ef2p1Y,3390
+superartifacts/_helpers.py,sha256=rJgf0TIev09r7wlA1B4Gr0PTQc68qoW5njtVHwULbRg,7454
+superartifacts/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+superartifacts/_generated/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+superartifacts/_generated/models.py,sha256=97YStbCFbreDoUmpvvXRHCgnkTS2w3nC4Eql6gTnX0k,36997
+superartifacts/_generated/resources.py,sha256=8fl-tSYWGPimX31iT_1IHSYsTZTVRmh9ZqutHbE6c04,149762
+superartifacts-0.1.0.dist-info/METADATA,sha256=Vts_BkvZwlMyXxq0PCQwxh7pWBYMBcFeoK-iuubkfHU,7439
+superartifacts-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+superartifacts-0.1.0.dist-info/licenses/LICENSE,sha256=JUpWclesPd7rcrwHwG5xYoXMXPUqDDhh_HXkdHKPnNs,1072
+superartifacts-0.1.0.dist-info/RECORD,,

superartifacts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

superartifacts-0.1.0.dist-info/licenses/LICENSE

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