archerprotocol-sdk 0.1.0__tar.gz

archerprotocol_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: archerprotocol-sdk
+Version: 0.1.0
+Summary: Build and monetize an Archer intent from Python: typed envelope builders, embeds, caller context, effect inference, and a one-call FastAPI handler.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Archer-Laboratories/archer-sdk
+Project-URL: Repository, https://github.com/Archer-Laboratories/archer-sdk
+Project-URL: Issues, https://github.com/Archer-Laboratories/archer-sdk/issues
+Keywords: archer,archer-protocol,intent,partner-sdk,fastapi,ed25519
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: archer-verify>=0.1.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Requires-Dist: starlette>=0.36; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+
+# archerprotocol-sdk
+
+Build, monetize, and publish an Archer intent from Python. This package
+mirrors the Node `@archerprotocol/sdk` builder surface; both are held to the
+same shared test vectors, so an envelope built here is byte-identical to one
+built in TypeScript.
+
+```bash
+pip install "archerprotocol-sdk[fastapi]"
+```
+
+## One-call handler (FastAPI)
+
+```python
+from fastapi import FastAPI
+from archer_sdk import archer, require_archer_caller, BadInputError
+from archer_sdk.fastapi import mount_archer_tools
+
+app = FastAPI()
+
+async def deposit(ctx):
+    caller = require_archer_caller(ctx.args)
+    amount = ctx.args.get("amount")
+    if not amount:
+        raise BadInputError('amount is required (e.g. "1.5")')
+    return archer.envelope(
+        cost=archer.cost(model="embedded", archer_fee_micro=200),
+        authorizations=[
+            archer.authorization(
+                type="tx",
+                namespace="evm",
+                label=f"Deposit {amount} USDC",
+                payload={"chainId": 8453, "to": "0x...", "data": "0x...", "value": "0x0"},
+            )
+        ],
+        record=archer.record(
+            record_kind="position",
+            basis_micro=1_000_000,
+            disclosure={"custody": "SELF", "exitModel": "PERMISSIONLESS"},
+        ),
+    )
+
+mount_archer_tools(app, {"/deposit": deposit})
+```
+
+The handler verifies the signed Archer envelope (via `archer-verify`),
+hands you `ctx.args / ctx.caller / ctx.request_id / ctx.intent_definition_id /
+ctx.user_id`, and wraps your return in the partner response envelope.
+Raise `BadInputError` (400) or `UpstreamError` (503) for clean failures.
+
+## Reads
+
+Return the flat render payload instead of an envelope:
+
+```python
+from archer_sdk import archer
+
+async def price_chart(ctx):
+    return archer.render(
+        text="ETH, last 30 days",
+        embed=archer.embed.chart(chart_type="line", data=[{"x": "2026-01", "y": 3000}]),
+    )
+```
+
+## Effect inference (pre-flight)
+
+`infer_effects` is the same function the platform runs server-side to decode
+a `sign` authorization into a verified, bounded confirmation. Run it locally
+against your descriptors to see exactly what the user's confirmation screen
+will derive; the platform always re-derives its own report.
+
+```python
+from archer_sdk import infer_effects
+
+report = await infer_effects(auth, descriptors=my_descriptors, price=my_price_fn)
+assert report["verdict"] == "DECODED_BOUNDED"
+```
+
+## Publishing
+
+Publishing and lifecycle management use the Node CLI, which works without a
+Node project: `npx @archerprotocol/sdk` gives you `archer init / publish /
+activate / stats`.

archerprotocol_sdk-0.1.0/README.md

@@ -0,0 +1,83 @@
+# archerprotocol-sdk
+
+Build, monetize, and publish an Archer intent from Python. This package
+mirrors the Node `@archerprotocol/sdk` builder surface; both are held to the
+same shared test vectors, so an envelope built here is byte-identical to one
+built in TypeScript.
+
+```bash
+pip install "archerprotocol-sdk[fastapi]"
+```
+
+## One-call handler (FastAPI)
+
+```python
+from fastapi import FastAPI
+from archer_sdk import archer, require_archer_caller, BadInputError
+from archer_sdk.fastapi import mount_archer_tools
+
+app = FastAPI()
+
+async def deposit(ctx):
+    caller = require_archer_caller(ctx.args)
+    amount = ctx.args.get("amount")
+    if not amount:
+        raise BadInputError('amount is required (e.g. "1.5")')
+    return archer.envelope(
+        cost=archer.cost(model="embedded", archer_fee_micro=200),
+        authorizations=[
+            archer.authorization(
+                type="tx",
+                namespace="evm",
+                label=f"Deposit {amount} USDC",
+                payload={"chainId": 8453, "to": "0x...", "data": "0x...", "value": "0x0"},
+            )
+        ],
+        record=archer.record(
+            record_kind="position",
+            basis_micro=1_000_000,
+            disclosure={"custody": "SELF", "exitModel": "PERMISSIONLESS"},
+        ),
+    )
+
+mount_archer_tools(app, {"/deposit": deposit})
+```
+
+The handler verifies the signed Archer envelope (via `archer-verify`),
+hands you `ctx.args / ctx.caller / ctx.request_id / ctx.intent_definition_id /
+ctx.user_id`, and wraps your return in the partner response envelope.
+Raise `BadInputError` (400) or `UpstreamError` (503) for clean failures.
+
+## Reads
+
+Return the flat render payload instead of an envelope:
+
+```python
+from archer_sdk import archer
+
+async def price_chart(ctx):
+    return archer.render(
+        text="ETH, last 30 days",
+        embed=archer.embed.chart(chart_type="line", data=[{"x": "2026-01", "y": 3000}]),
+    )
+```
+
+## Effect inference (pre-flight)
+
+`infer_effects` is the same function the platform runs server-side to decode
+a `sign` authorization into a verified, bounded confirmation. Run it locally
+against your descriptors to see exactly what the user's confirmation screen
+will derive; the platform always re-derives its own report.
+
+```python
+from archer_sdk import infer_effects
+
+report = await infer_effects(auth, descriptors=my_descriptors, price=my_price_fn)
+assert report["verdict"] == "DECODED_BOUNDED"
+```
+
+## Publishing
+
+Publishing and lifecycle management use the Node CLI, which works without a
+Node project: `npx @archerprotocol/sdk` gives you `archer init / publish /
+activate / stats`.

archerprotocol_sdk-0.1.0/archer_sdk/__init__.py

@@ -0,0 +1,55 @@
+"""Archer contribution SDK for Python: build, monetize, and publish an
+Archer intent. Envelope builders, GUI embeds, caller context, effect
+inference, and a one-call FastAPI handler (archer_sdk.fastapi). Mirrors the
+Node @archerprotocol/sdk; the shared test-vectors enforce parity."""
+
+from types import SimpleNamespace
+
+from . import embed as _embed
+from .builders import (
+    authorization,
+    cost,
+    data,
+    envelope,
+    is_invocation_envelope,
+    record,
+)
+from .caller import ArcherCaller, get_archer_caller, require_archer_caller
+from .effects import infer_effects
+from .errors import BadInputError, UpstreamError
+from .handler import ArcherHandler, HandlerContext, run_invocation
+from .money import to_micro, to_micro_optional
+
+__version__ = "0.1.0"
+
+# The one-object surface most handlers want: archer.envelope(...), archer.render(...).
+archer = SimpleNamespace(
+    data=data,
+    cost=cost,
+    authorization=authorization,
+    record=record,
+    envelope=envelope,
+    embed=_embed,
+    render=_embed.render,
+)
+
+__all__ = [
+    "archer",
+    "authorization",
+    "cost",
+    "data",
+    "envelope",
+    "record",
+    "is_invocation_envelope",
+    "get_archer_caller",
+    "require_archer_caller",
+    "ArcherCaller",
+    "infer_effects",
+    "BadInputError",
+    "UpstreamError",
+    "ArcherHandler",
+    "HandlerContext",
+    "run_invocation",
+    "to_micro",
+    "to_micro_optional",
+]

archerprotocol_sdk-0.1.0/archer_sdk/builders.py

@@ -0,0 +1,149 @@
+"""Envelope builders for the generic Archer invocation contract. Inputs take
+pythonic snake_case keywords; outputs are plain dicts whose keys and shapes
+are byte-identical to the Node SDK's JSON (the shared test-vectors enforce
+this). Optional fields are omitted when absent, never set to null."""
+
+from typing import Any, Dict, List, Optional
+
+from .money import Money, to_micro, to_micro_optional
+
+_COST_MODELS = {"flat", "percent", "x402", "embedded", "none"}
+
+
+def _prune(obj: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in obj.items() if v is not None}
+
+
+def data(value: Any) -> Dict[str, Any]:
+    """The Render arm."""
+    return {"data": value}
+
+
+def cost(
+    *,
+    model: str,
+    amount_micro: Optional[Money] = None,
+    value_micro: Optional[Money] = None,
+    bps: Optional[int] = None,
+    bob_fee_micro: Optional[Money] = None,
+    archer_fee_micro: Optional[Money] = None,
+) -> Dict[str, Any]:
+    """The Settle arm: a declared fee model plus its parameters."""
+    if model in ("flat", "x402"):
+        params = _prune(
+            {
+                "amountMicro": to_micro(amount_micro) if amount_micro is not None else None,
+                "archerFeeMicro": to_micro_optional(archer_fee_micro),
+            }
+        )
+    elif model == "percent":
+        params = _prune(
+            {
+                "valueMicro": to_micro(value_micro) if value_micro is not None else None,
+                "bps": bps,
+                "archerFeeMicro": to_micro_optional(archer_fee_micro),
+            }
+        )
+    elif model == "embedded":
+        params = _prune(
+            {
+                "bobFeeMicro": to_micro_optional(bob_fee_micro),
+                "archerFeeMicro": to_micro_optional(archer_fee_micro),
+            }
+        )
+    elif model == "none":
+        params = {}
+    else:
+        raise ValueError(f'unknown fee model "{model}" (expected one of {sorted(_COST_MODELS)})')
+    return {"model": model, "params": params}
+
+
+def authorization(
+    *,
+    type: str,
+    label: str,
+    payload: Dict[str, Any],
+    namespace: Optional[str] = None,
+) -> Dict[str, Any]:
+    """One entry of the Authorize arm. The label is the human disclosure."""
+    if not label or not isinstance(label, str):
+        raise ValueError("authorization label is required (human-readable disclosure)")
+    return _prune(
+        {
+            "type": type,
+            "namespace": namespace,
+            "label": label,
+            "payload": payload if payload is not None else {},
+        }
+    )
+
+
+def record(
+    *,
+    record_kind: str,
+    basis_micro: Optional[Money] = None,
+    value_micro: Optional[Money] = None,
+    bob_fee_micro: Optional[Money] = None,
+    archer_fee_micro: Optional[Money] = None,
+    value_read: Optional[Dict[str, Any]] = None,
+    exit_instructions: Optional[Dict[str, Any]] = None,
+    ref: Optional[str] = None,
+    group_key: Optional[str] = None,
+    view_url: Optional[str] = None,
+    disclosure: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """The Record arm: a durable, user-owned outcome (opaque to the engine)."""
+    if not record_kind or not isinstance(record_kind, str):
+        raise ValueError("record_kind is required")
+    return _prune(
+        {
+            "recordKind": record_kind,
+            "basisMicro": to_micro_optional(basis_micro),
+            "valueMicro": to_micro_optional(value_micro),
+            "bobFeeMicro": to_micro_optional(bob_fee_micro),
+            "archerFeeMicro": to_micro_optional(archer_fee_micro),
+            "valueRead": value_read,
+            "exitInstructions": exit_instructions,
+            "ref": ref,
+            "groupKey": group_key,
+            "viewUrl": view_url,
+            "disclosure": disclosure,
+        }
+    )
+
+
+def envelope(
+    *,
+    data: Any = None,
+    cost: Optional[Dict[str, Any]] = None,
+    authorizations: Optional[List[Dict[str, Any]]] = None,
+    record: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Assemble the arms into one invocation envelope, validated structurally."""
+    env = _prune(
+        {"data": data, "cost": cost, "authorizations": authorizations, "record": record}
+    )
+    if not is_invocation_envelope(env):
+        raise ValueError(
+            "envelope arms are malformed (cost needs a model, record needs a recordKind, "
+            "authorizations must be a list)"
+        )
+    return env
+
+
+def is_invocation_envelope(value: Any) -> bool:
+    """Structural check mirroring the engine's isInvocationEnvelope."""
+    if value is None or not isinstance(value, dict):
+        return False
+    if "authorizations" in value and value["authorizations"] is not None:
+        if not isinstance(value["authorizations"], list):
+            return False
+    if "cost" in value and value["cost"] is not None:
+        c = value["cost"]
+        if not isinstance(c, dict) or not isinstance(c.get("model"), str):
+            return False
+    if "record" in value and value["record"] is not None:
+        r = value["record"]
+        if not isinstance(r, dict) or not isinstance(r.get("recordKind"), str):
+            return False
+    return True

archerprotocol_sdk-0.1.0/archer_sdk/caller.py

@@ -0,0 +1,39 @@
+"""Caller context. Archer injects the invoking user's context inside the
+signed args as args["archerCaller"], so it is verified as part of the
+envelope. Read it here."""
+
+from typing import Any, Dict, Optional, TypedDict
+
+
+class ArcherCaller(TypedDict):
+    evmAddress: Optional[str]
+    svmAddress: Optional[str]
+    archerFeeRate: Optional[float]
+
+
+def get_archer_caller(args: Dict[str, Any]) -> Optional[ArcherCaller]:
+    raw = args.get("archerCaller") if isinstance(args, dict) else None
+    if raw is None or not isinstance(raw, dict):
+        return None
+    evm = raw.get("evmAddress")
+    svm = raw.get("svmAddress")
+    rate = raw.get("archerFeeRate")
+    return {
+        "evmAddress": evm if isinstance(evm, str) else None,
+        "svmAddress": svm if isinstance(svm, str) else None,
+        "archerFeeRate": float(rate)
+        if isinstance(rate, (int, float)) and not isinstance(rate, bool)
+        else None,
+    }
+
+
+def require_archer_caller(args: Dict[str, Any]) -> ArcherCaller:
+    """For intents that move user funds or cause side effects, caller context
+    is mandatory. A missing caller almost always means the intent was
+    published without requiresCaller: true."""
+    caller = get_archer_caller(args)
+    if caller is None:
+        raise ValueError(
+            "caller context is missing; declare requiresCaller: true when publishing this intent"
+        )
+    return caller