send21-haystack 0.1.0__py3-none-any.whl

send21_haystack/__init__.py

@@ -0,0 +1,8 @@
+"""send21 for Haystack. Not an official deepset integration."""
+from .client import MockSend21Client, Send21MCPClient, build_create_args, pay_link
+from .component import Send21PaymentRequest
+from .webhook import verify_send21_signature
+
+__all__ = ["Send21PaymentRequest", "verify_send21_signature", "Send21MCPClient",
+           "MockSend21Client", "build_create_args", "pay_link"]
+__version__ = "0.1.0"

send21_haystack/client.py

@@ -0,0 +1,126 @@
+"""send21 MCP client (live) and a deterministic mock with the same interface.
+
+Verified against github.com/send21io/send21-examples (mcp-payment-request):
+- endpoint https://send21.io/mcp, Streamable HTTP, Authorization: Bearer <key>
+- tool create_payment_request with fiatCurrency, fiatAmount, options[{currency,network,address,method?}],
+  orderId, memo, expiryHours, idempotencyKey (all keys sent, null for optional ones)
+- result content[0].text is JSON with id and payPath; pay link = https://send21.io + payPath
+
+Only create_payment_request is used. Arguments are also validated against the live
+inputSchema at call time.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from decimal import Decimal
+from typing import Any
+from urllib.parse import urljoin
+
+SITE_URL = "https://send21.io"
+TOOLS = ("create_payment_request",)
+
+
+def pay_link(pay_path: str) -> str:
+    return urljoin(SITE_URL, pay_path)
+
+
+def build_create_args(*, amount: Decimal, fiat_currency: str, currency: str, network: str, address: str,
+                      order_id: str, memo: str, idempotency_key: str, expiry_hours: int | None = None) -> dict:
+    return {
+        "fiatCurrency": fiat_currency.upper(),
+        "fiatAmount": float(amount),
+        "options": [{"currency": currency, "network": network, "address": address}],
+        "orderId": order_id,
+        "memo": memo,
+        "expiryHours": expiry_hours,
+        "idempotencyKey": idempotency_key,
+    }
+
+
+def _type_of(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "boolean"
+    if isinstance(v, int):
+        return "integer"
+    if isinstance(v, float):
+        return "number"
+    if isinstance(v, str):
+        return "string"
+    if isinstance(v, list):
+        return "array"
+    return "object"
+
+
+def validate(value: Any, schema: dict, path: str = "arguments") -> list[str]:
+    """Minimal JSON Schema check (type, required, properties, items), ported from the TS example."""
+    errors: list[str] = []
+    t = schema.get("type")
+    if t:
+        allowed = t if isinstance(t, list) else [t]
+        actual = _type_of(value)
+        if not (actual in allowed or (actual == "integer" and "number" in allowed)):
+            return [f"{path}: expected {' or '.join(allowed)}, got {actual}"]
+    if isinstance(value, dict):
+        for key in schema.get("required", []):
+            if key not in value:
+                errors.append(f"{path}.{key}: required")
+        for key, sub in (schema.get("properties") or {}).items():
+            if key in value:
+                errors += validate(value[key], sub, f"{path}.{key}")
+    if isinstance(value, list) and schema.get("items"):
+        for i, item in enumerate(value):
+            errors += validate(item, schema["items"], f"{path}[{i}]")
+    return errors
+
+
+class MockSend21Client:
+    """No network. Deterministic ids so demo output is identical every run."""
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, dict]] = []
+        self._by_key: dict[str, dict] = {}
+
+    def call(self, tool: str, args: dict) -> dict:
+        if tool not in TOOLS:
+            raise ValueError(f"unknown tool {tool}")
+        self.calls.append((tool, args))
+        if tool == "create_payment_request":
+            key = args["idempotencyKey"]
+            if key not in self._by_key:  # same key returns the same request, like the real API
+                n = len(self._by_key) + 1
+                self._by_key[key] = {"id": f"demo-{n:04d}", "payPath": f"/p/demo-{n:04d}", "status": "mock"}
+            return dict(self._by_key[key])
+        raise ValueError(tool)
+
+
+class Send21MCPClient:
+    """Live client over the send21 MCP server. Sync wrapper around the async MCP SDK."""
+
+    def __init__(self, url: str, api_key: str) -> None:
+        self.url, self.api_key = url, api_key
+
+    async def _call(self, tool: str, args: dict) -> dict:
+        from mcp import ClientSession
+        from mcp.client.streamable_http import streamablehttp_client
+
+        headers = {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+        async with streamablehttp_client(self.url, headers=headers) as (read, write, _):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                tools = {t.name: t for t in (await session.list_tools()).tools}
+                if tool not in tools:
+                    raise RuntimeError(f"The server does not offer {tool}")
+                problems = validate(args, tools[tool].inputSchema or {})
+                if problems:
+                    raise RuntimeError(f"Arguments do not match the live {tool} schema: {problems}")
+                result = await session.call_tool(tool, args)
+                text = "\n".join(c.text for c in result.content if getattr(c, "type", "") == "text")
+                if result.isError:
+                    raise RuntimeError(text or f"{tool} failed")
+                return json.loads(text)
+
+    def call(self, tool: str, args: dict) -> dict:
+        return asyncio.run(self._call(tool, args))

send21_haystack/component.py

@@ -0,0 +1,67 @@
+"""Haystack component: ask send21 to prepare a payment request and return the pay link.
+
+send21 prepares payment instructions. It never holds keys or funds, never signs and never
+broadcasts. Use an API key with the drafts:write scope only; such a key cannot move funds.
+"""
+from __future__ import annotations
+
+import os
+import uuid
+from decimal import Decimal
+from typing import Any, Optional
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+from .client import Send21MCPClient, build_create_args, pay_link
+
+MCP_URL = "https://send21.io/mcp"
+
+
+@component
+class Send21PaymentRequest:
+    """Creates a send21 payment request and returns its id and pay link.
+
+    Usage:
+        pr = Send21PaymentRequest(currency="USDC", network="base", address="0x...")
+        pr.run(amount=1.5, fiat_currency="USD", order_id="run-42", memo="agent top-up")
+        # {"id": "...", "pay_link": "https://send21.io/p/...", "raw": {...}}
+    """
+
+    def __init__(self, currency: str, network: str, address: str,
+                 api_key: Secret = Secret.from_env_var("SEND21_API_KEY"),
+                 mcp_url: str = MCP_URL, expiry_hours: Optional[int] = None,
+                 client: Any = None) -> None:
+        self.currency, self.network, self.address = currency, network, address
+        self.api_key, self.mcp_url, self.expiry_hours = api_key, mcp_url, expiry_hours
+        self._client = client
+
+    def _get_client(self):
+        if self._client is None:
+            self._client = Send21MCPClient(self.mcp_url, self.api_key.resolve_value() or "")
+        return self._client
+
+    @component.output_types(id=str, pay_link=str, raw=dict)
+    def run(self, amount: float, fiat_currency: str, order_id: str, memo: str = "",
+            idempotency_key: Optional[str] = None) -> dict:
+        if Decimal(str(amount)) <= 0:
+            raise ValueError("amount must be positive")
+        args = build_create_args(amount=Decimal(str(amount)), fiat_currency=fiat_currency,
+                                 currency=self.currency, network=self.network, address=self.address,
+                                 order_id=order_id, memo=memo,
+                                 idempotency_key=idempotency_key or f"{order_id}-{uuid.uuid4()}",
+                                 expiry_hours=self.expiry_hours)
+        res = self._get_client().call("create_payment_request", args)
+        if "id" not in res or "payPath" not in res:
+            raise RuntimeError(f"unexpected send21 response: {res}")
+        return {"id": str(res["id"]), "pay_link": pay_link(res["payPath"]), "raw": res}
+
+    def to_dict(self) -> dict:
+        return default_to_dict(self, currency=self.currency, network=self.network, address=self.address,
+                               api_key=self.api_key.to_dict(), mcp_url=self.mcp_url,
+                               expiry_hours=self.expiry_hours)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Send21PaymentRequest":
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)

send21_haystack/webhook.py

@@ -0,0 +1,26 @@
+"""Webhook signature check.
+
+Header X-Send21-Signature: sha256=<lowercase hex HMAC-SHA256 of the raw body>, keyed with the
+endpoint signing secret. Check the raw bytes before parsing. X-Send21-Delivery is reused on
+retries, so store it and ignore repeats. No timestamp header is documented.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import Optional
+
+SIGNATURE_HEADER = "X-Send21-Signature"
+DELIVERY_HEADER = "X-Send21-Delivery"
+EVENT_HEADER = "X-Send21-Event"
+
+
+def sign(raw: bytes, secret: str) -> str:
+    return "sha256=" + hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()
+
+
+def verify_send21_signature(raw_body: bytes, signature_header: Optional[str], secret: str) -> bool:
+    """True only if the header matches the HMAC of the raw body. Constant-time compare."""
+    if not secret or not isinstance(signature_header, str) or not isinstance(raw_body, (bytes, bytearray)):
+        return False
+    return hmac.compare_digest(sign(bytes(raw_body), secret).encode(), signature_header.encode())

send21_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: send21-haystack
+Version: 0.1.0
+Summary: Haystack component that asks send21 to prepare a non-custodial payment request (pay link). Not an official deepset integration.
+Project-URL: Repository, https://github.com/send21io/send21-haystack
+Project-URL: Issues, https://github.com/send21io/send21-haystack/issues
+Author-email: send21 <info@send21.io>
+License: MIT
+License-File: LICENSE
+Keywords: agents,haystack,mcp,payments,send21
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=2.0
+Requires-Dist: mcp>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# send21-haystack
+
+A Haystack 2.x component that asks send21 to prepare a payment request and returns a pay link, plus a webhook signature helper.
+
+This is a community package. It is **not an official deepset integration**.
+
+send21 prepares payment instructions. A person opens the pay link and signs in their own wallet; funds go straight from the payer's wallet to the receiver's wallet. send21 never holds keys or funds, never signs and never broadcasts. Use an API key with the `drafts:write` scope only. That key can prepare a payment request but cannot move funds.
+
+## Install
+
+Not on PyPI yet. Install from git:
+
+```sh
+pip install git+https://github.com/send21io/send21-haystack
+```
+
+## Usage in a pipeline
+
+```python
+from haystack import Pipeline
+from send21_haystack import Send21PaymentRequest
+
+# reads SEND21_API_KEY from the environment (scope: drafts:write)
+payment = Send21PaymentRequest(currency="USDC", network="base", address="0xYourReceivingAddress")
+
+p = Pipeline()
+p.add_component("payment", payment)
+out = p.run({"payment": {"amount": 1.50, "fiat_currency": "USD",
+                         "order_id": "run-42", "memo": "agent top-up"}})
+print(out["payment"]["pay_link"])   # https://send21.io/p/...
+```
+
+Outputs: `id`, `pay_link`, `raw` (the full tool result).
+
+Offline: pass `client=MockSend21Client()` to get deterministic fake ids with no network. See `examples/pipeline.py`.
+
+## What it sends
+
+The component calls the send21 MCP server at `https://send21.io/mcp` (Streamable HTTP, `Authorization: Bearer <key>`), tool `create_payment_request`, with these fields only:
+
+`fiatCurrency`, `fiatAmount`, `options: [{currency, network, address}]`, `orderId`, `memo`, `expiryHours` (null if unset), `idempotencyKey`.
+
+It reads `id` and `payPath` from the result; the pay link is `https://send21.io` + `payPath`. Arguments are checked against the server's live `inputSchema` before the call.
+
+## Webhooks
+
+```python
+from send21_haystack import verify_send21_signature
+
+ok = verify_send21_signature(raw_body_bytes, headers.get("X-Send21-Signature"), signing_secret)
+```
+
+`X-Send21-Signature` is `sha256=<lowercase hex HMAC-SHA256 of the raw body>` keyed with the endpoint signing secret. Check the raw bytes before parsing. Store `X-Send21-Delivery` and ignore repeats; deliveries can be retried and arrive out of order. A stdlib receiver is in `examples/webhook_receiver.py`.
+
+## Tests
+
+```sh
+pip install -e ".[dev]" && pytest
+```
+
+Tests run fully offline (the MCP client is mocked).
+
+## Unverified
+
+Not confirmed against the live API yet; check https://send21.io/docs and the live MCP `tools/list` first.
+
+- The `status` and `expiresAt` values in the `create_payment_request` response, and the exact `payPath` format. Only `id` and `payPath` are relied on.
+- Exact accepted `currency` and `network` names for `options`; the examples use `USDC` / `base`.
+- Whether API keys can target testnet. Assume mainnet; use small amounts.
+- Webhook payload fields beyond `event` and `data.orderId` (for example `paymentRequestId`, `fiatAmount`).
+- Whether a key's scopes can be read through the API. Create the key with `drafts:write` only.
+
+## Related
+
+- Agent spend-cap handoff example: https://github.com/send21io/send21-over-budget-handoff
+- More examples: https://github.com/send21io/send21-examples
+- Docs: https://send21.io/docs
+
+## License and contact
+
+MIT. Questions: info@send21.io

send21_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+send21_haystack/__init__.py,sha256=4KukQgGASF_fY_mRI-taPkU_rw7kvLNJVqvgX8Dcf04,404
+send21_haystack/client.py,sha256=7TY4vJxw-GMxsfANDvN9k4HWOvvz1gFXHFgWWcNFj2A,5101
+send21_haystack/component.py,sha256=Wq44p1A1cma71wrBzkmdGv5gRH6p8FRsKXfBI9P0qQ4,3134
+send21_haystack/webhook.py,sha256=SaibRu5aXQZHvG5srUXZaqzpaSzuR2MxgZQv9z5ZQo4,1043
+send21_haystack-0.1.0.dist-info/METADATA,sha256=rPHaysQxZZN4tL91LZtad8EplsiqIxujvtvavlYhkQ4,4038
+send21_haystack-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+send21_haystack-0.1.0.dist-info/licenses/LICENSE,sha256=_sIkanGpKqb_AgEqV25-w5X9loAc_g6r7DYjJc4lKWI,1063
+send21_haystack-0.1.0.dist-info/RECORD,,

send21_haystack-0.1.0.dist-info/WHEEL

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

send21_haystack-0.1.0.dist-info/licenses/LICENSE

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