superartifacts 0.1.0__tar.gz

superartifacts-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+uv.lock
+__pycache__/
+.pytest_cache/
+.ruff_cache/

superartifacts-0.1.0/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.

superartifacts-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,216 @@
+# 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/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "superartifacts"
+version = "0.1.0"
+description = "Python SDK for the Super Artifacts REST API: publish artifacts and read their data from your own code."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Super Artifacts" }]
+keywords = ["super-artifacts", "artifacts", "publishing", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1", "pydantic>=2,<3"]
+
+[project.urls]
+Homepage = "https://superartifacts.app/docs/sdks/python"
+Repository = "https://github.com/Superbelt/sdk"
+Issues = "https://github.com/Superbelt/sdk/issues"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/superartifacts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["src/superartifacts/_generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

superartifacts-0.1.0/src/superartifacts/__init__.py

@@ -0,0 +1,39 @@
+"""Python SDK for the Super Artifacts REST API. https://superartifacts.app/docs/sdks/python"""
+
+from ._client import AsyncSuperArtifacts, SuperArtifacts, __version__
+from ._errors import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InternalError,
+    InvalidArgumentsError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionError,
+    PlanLimitError,
+    RateLimitError,
+    ScopeRequiredError,
+    SuperArtifactsError,
+)
+from ._generated import models
+
+__all__ = [
+    "APIConnectionError",
+    "APITimeoutError",
+    "AsyncSuperArtifacts",
+    "AuthenticationError",
+    "ConflictError",
+    "InternalError",
+    "InvalidArgumentsError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "PermissionError",
+    "PlanLimitError",
+    "RateLimitError",
+    "ScopeRequiredError",
+    "SuperArtifacts",
+    "SuperArtifactsError",
+    "__version__",
+    "models",
+]