shepherd-sdk 0.2.0__tar.gz

shepherd_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: shepherd-sdk
+Version: 0.2.0
+Summary: Python client for the Shepherd API: connect wallets, classify transactions, and pull financial statements.
+Project-URL: Homepage, https://getshepherd.co/developers.html
+Author-email: Shepherd <alan@getshepherd.co>
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Description-Content-Type: text/markdown
+
+# shepherd-sdk (Python)
+
+Python client for the [Shepherd API](https://getshepherd.co/developers.html): connect wallets, classify every transaction, and pull audit-ready financial statements.
+
+```bash
+pip install shepherd-sdk
+```
+
+```python
+from shepherd import Shepherd
+
+shep = Shepherd("shep_live_...")          # or Shepherd.create_sandbox() for an instant test key
+
+wallet = shep.wallets.connect("0x...", "base", end_user_id="cust_4821")
+pnl = shep.statements.income(start_date="2026-09-01", end_date="2026-09-30", end_user_id="cust_4821")
+print(pnl["net_income"])
+```
+
+## Sandbox
+
+```python
+shep = Shepherd.create_sandbox(email="you@company.com")
+print(shep.sandbox_info)    # seeded wallet + customer
+```
+
+Sandbox keys start with `shep_test_`. Data is synthetic; connecting any address returns generated activity.
+
+## Webhooks
+
+```python
+from shepherd import construct_event, SignatureVerificationError
+
+# Flask example
+@app.post("/shepherd/webhook")
+def hook():
+    try:
+        event = construct_event(request.get_data(), request.headers["Shepherd-Signature"], WEBHOOK_SECRET)
+    except SignatureVerificationError:
+        return "", 400
+    if event["type"] == "wallet.scan_completed":
+        ...
+    return "", 200
+```
+
+## Push your own transactions
+
+```python
+acct = shep.accounts.create("acct_123", type="bank", currency="USD", end_user_id="cust_4821")
+r = shep.accounts.push_transactions(acct["id"], [
+    {"external_id": "tx_1", "date": "2026-09-03", "amount": 1250.00, "direction": "inflow", "counterparty": "Acme Corp"},
+])
+print(r["created"], r["duplicates"], r["rejected"])
+shep.jobs.wait(r["classification"]["job_id"])      # classification runs in the background
+```
+
+Sending the same `external_id` again changes nothing, so it is safe to retry.
+
+## Pagination
+
+```python
+for tx in shep.transactions.iterate(status="unclassified"):   # follows pages for you
+    ...
+changed = shep.transactions.iterate(updated_since="2026-10-01T00:00:00Z")   # keep a copy in sync
+```
+
+## One set of books per customer (platform accounts)
+
+```python
+shep.workspaces.create("cust_4821", "Acme Corp")
+acme = shep.with_workspace("cust_4821")        # every call on `acme` reads and writes that customer only
+acme.statements.income(start_date="2026-09-01")
+```
+
+## Keys and safe retries
+
+```python
+key = shep.api_keys.create(label="reporting", scope="read", expires_in_days=90)   # admin key needed
+shep.api_keys.rotate(key["id"], grace_hours=24)
+shep.accounts.create("acct_123", idempotency_key="create-acct_123")   # POSTs with a key retry safely
+```
+
+## Errors
+
+Every failure raises a `ShepherdError` subclass with `.status`, `.message`, `.code`, `.request_id`, `.body`:
+`InvalidRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `.retry_after`), `ServerError` (5xx).
+GET requests, and POSTs sent with an `idempotency_key`, retry automatically on 429/502/503 and honour `Retry-After`.
+
+## Resources
+
+`wallets`, `transactions`, `accounts`, `jobs`, `statements`, `entities`, `opening_balances`, `accruals`, `classification_rules`, `chart_of_accounts`, `periods`, `reconciliation`, `audit_log`, `api_keys`, `workspaces`, `webhooks`, `sandbox`. See the [API reference](https://getshepherd.co/developers-docs.html#reference).

shepherd_sdk-0.2.0/README.md

@@ -0,0 +1,90 @@
+# shepherd-sdk (Python)
+
+Python client for the [Shepherd API](https://getshepherd.co/developers.html): connect wallets, classify every transaction, and pull audit-ready financial statements.
+
+```bash
+pip install shepherd-sdk
+```
+
+```python
+from shepherd import Shepherd
+
+shep = Shepherd("shep_live_...")          # or Shepherd.create_sandbox() for an instant test key
+
+wallet = shep.wallets.connect("0x...", "base", end_user_id="cust_4821")
+pnl = shep.statements.income(start_date="2026-09-01", end_date="2026-09-30", end_user_id="cust_4821")
+print(pnl["net_income"])
+```
+
+## Sandbox
+
+```python
+shep = Shepherd.create_sandbox(email="you@company.com")
+print(shep.sandbox_info)    # seeded wallet + customer
+```
+
+Sandbox keys start with `shep_test_`. Data is synthetic; connecting any address returns generated activity.
+
+## Webhooks
+
+```python
+from shepherd import construct_event, SignatureVerificationError
+
+# Flask example
+@app.post("/shepherd/webhook")
+def hook():
+    try:
+        event = construct_event(request.get_data(), request.headers["Shepherd-Signature"], WEBHOOK_SECRET)
+    except SignatureVerificationError:
+        return "", 400
+    if event["type"] == "wallet.scan_completed":
+        ...
+    return "", 200
+```
+
+## Push your own transactions
+
+```python
+acct = shep.accounts.create("acct_123", type="bank", currency="USD", end_user_id="cust_4821")
+r = shep.accounts.push_transactions(acct["id"], [
+    {"external_id": "tx_1", "date": "2026-09-03", "amount": 1250.00, "direction": "inflow", "counterparty": "Acme Corp"},
+])
+print(r["created"], r["duplicates"], r["rejected"])
+shep.jobs.wait(r["classification"]["job_id"])      # classification runs in the background
+```
+
+Sending the same `external_id` again changes nothing, so it is safe to retry.
+
+## Pagination
+
+```python
+for tx in shep.transactions.iterate(status="unclassified"):   # follows pages for you
+    ...
+changed = shep.transactions.iterate(updated_since="2026-10-01T00:00:00Z")   # keep a copy in sync
+```
+
+## One set of books per customer (platform accounts)
+
+```python
+shep.workspaces.create("cust_4821", "Acme Corp")
+acme = shep.with_workspace("cust_4821")        # every call on `acme` reads and writes that customer only
+acme.statements.income(start_date="2026-09-01")
+```
+
+## Keys and safe retries
+
+```python
+key = shep.api_keys.create(label="reporting", scope="read", expires_in_days=90)   # admin key needed
+shep.api_keys.rotate(key["id"], grace_hours=24)
+shep.accounts.create("acct_123", idempotency_key="create-acct_123")   # POSTs with a key retry safely
+```
+
+## Errors
+
+Every failure raises a `ShepherdError` subclass with `.status`, `.message`, `.code`, `.request_id`, `.body`:
+`InvalidRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `.retry_after`), `ServerError` (5xx).
+GET requests, and POSTs sent with an `idempotency_key`, retry automatically on 429/502/503 and honour `Retry-After`.
+
+## Resources
+
+`wallets`, `transactions`, `accounts`, `jobs`, `statements`, `entities`, `opening_balances`, `accruals`, `classification_rules`, `chart_of_accounts`, `periods`, `reconciliation`, `audit_log`, `api_keys`, `workspaces`, `webhooks`, `sandbox`. See the [API reference](https://getshepherd.co/developers-docs.html#reference).

shepherd_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shepherd-sdk"
+version = "0.2.0"
+description = "Python client for the Shepherd API: connect wallets, classify transactions, and pull financial statements."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Shepherd", email = "alan@getshepherd.co" }]
+dependencies = ["requests>=2.25"]
+classifiers = ["Programming Language :: Python :: 3", "Typing :: Typed", "License :: OSI Approved :: MIT License"]
+
+[project.urls]
+Homepage = "https://getshepherd.co/developers.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["shepherd"]

shepherd_sdk-0.2.0/shepherd/__init__.py

@@ -0,0 +1,8 @@
+from .client import Shepherd, DEFAULT_BASE_URL
+from .errors import (AuthenticationError, ConflictError, InvalidRequestError, NotFoundError, PermissionDeniedError,
+                     RateLimitError, ServerError, ShepherdError, SignatureVerificationError)
+from .webhooks import construct_event
+
+__all__ = ["Shepherd", "DEFAULT_BASE_URL", "ShepherdError", "AuthenticationError", "InvalidRequestError", "NotFoundError", "PermissionDeniedError", "ConflictError",
+           "RateLimitError", "ServerError", "SignatureVerificationError", "construct_event"]
+__version__ = "0.2.0"

shepherd_sdk-0.2.0/shepherd/client.py

@@ -0,0 +1,405 @@
+import time
+
+import requests
+
+from . import webhooks as _wh
+from .errors import (AuthenticationError, ConflictError, InvalidRequestError, NotFoundError, PermissionDeniedError,
+                     RateLimitError, ServerError, ShepherdError)
+
+DEFAULT_BASE_URL = "https://app.getshepherd.co/api/v1"
+
+
+def _clean(d):
+    return {k: v for k, v in d.items() if v is not None}
+
+
+class _Resource:
+    def __init__(self, client):
+        self._c = client
+
+
+class Wallets(_Resource):
+    def list(self, end_user_id=None):
+        return self._c._get("/wallets", end_user_id=end_user_id)["wallets"]
+
+    def connect(self, address, chain, end_user_id=None, end_user_name=None, name=None, lookback_blocks=None):
+        """Connect a wallet, pull its history, and auto-classify. chain: base, ethereum, polygon, arbitrum, tempo, solana."""
+        return self._c._post("/wallets", _clean(dict(address=address, chain=chain, end_user_id=end_user_id,
+                                                      end_user_name=end_user_name, name=name, lookback_blocks=lookback_blocks)))
+
+    def scan(self, wallet_id, background=False):
+        """Rescan a wallet. With background=True returns a job right away (see `jobs.wait`)."""
+        return self._c._post(f"/wallets/{wallet_id}/scan", {"async": True} if background else None)
+
+
+class Transactions(_Resource):
+    def list(self, wallet_id=None, end_user_id=None, gl_code=None, **filters):
+        """One page (up to `limit`, default 500). Use `iterate` to read everything, or `page` for the cursor.
+        filters: status, date_from, date_to, updated_since, limit, cursor, order."""
+        return self.page(wallet_id=wallet_id, end_user_id=end_user_id, gl_code=gl_code, **filters)["transactions"]
+
+    def page(self, **filters):
+        """One page as {transactions, has_more, next_cursor}."""
+        return self._c._get("/transactions", **filters)
+
+    def iterate(self, **filters):
+        """Yields every matching transaction, following next_cursor until the end."""
+        return self._c._iterate("/transactions", "transactions", filters)
+
+    def get(self, transaction_id):
+        return self._c._get(f"/transactions/{transaction_id}")
+
+    def classify(self, transaction_id, gl_code, counterparty=None, reason=None):
+        return self._c._post(f"/transactions/{transaction_id}/classify", _clean(dict(gl_code=gl_code, counterparty=counterparty, reason=reason)))
+
+    def link_suggestions(self):
+        return self._c._get("/transactions/link-suggestions")["suggestions"]
+
+    def link(self, tx_id_a, tx_id_b, note=None):
+        return self._c._post("/transactions/link", _clean(dict(tx_id_a=tx_id_a, tx_id_b=tx_id_b, note=note)))
+
+    def links(self):
+        return self._c._get("/transactions/links")["links"]
+
+    def unlink(self, link_id):
+        return self._c._post(f"/transactions/links/{link_id}/unlink")
+
+    def dismiss_link_suggestion(self, tx_id_a, tx_id_b):
+        return self._c._post("/transactions/link-suggestions/dismiss", dict(tx_id_a=tx_id_a, tx_id_b=tx_id_b))
+
+
+class Statements(_Resource):
+    def income(self, start_date=None, end_date=None, entity_id=None, wallet_id=None, end_user_id=None):
+        return self._c._get("/financial-statements", start_date=start_date, end_date=end_date, entity_id=entity_id,
+                            wallet_id=wallet_id, end_user_id=end_user_id)
+
+    def income_consolidated(self, start_date=None, end_date=None):
+        return self._c._get("/financial-statements/consolidated", start_date=start_date, end_date=end_date)
+
+    def balance_sheet(self, entity_id=None, as_of_date=None):
+        return self._c._get("/balance-sheet", entity_id=entity_id, as_of_date=as_of_date)
+
+    def balance_sheet_consolidated(self, as_of_date=None, period_start_date=None):
+        return self._c._get("/balance-sheet/consolidated", as_of_date=as_of_date, period_start_date=period_start_date)
+
+
+class Entities(_Resource):
+    def list(self):
+        return self._c._get("/entities")["entities"]
+
+    def create(self, name, legal_name=None, entity_type=None, functional_currency=None):
+        return self._c._post("/entities", _clean(dict(name=name, legal_name=legal_name, entity_type=entity_type, functional_currency=functional_currency)))
+
+    def update(self, entity_id, name, legal_name=None, entity_type=None, functional_currency=None, clear_functional_currency=None):
+        return self._c._post(f"/entities/{entity_id}/update", _clean(dict(name=name, legal_name=legal_name, entity_type=entity_type,
+                                                                          functional_currency=functional_currency,
+                                                                          clear_functional_currency=clear_functional_currency)))
+
+    def delete(self, entity_id):
+        return self._c._post(f"/entities/{entity_id}/delete")
+
+
+class OpeningBalances(_Resource):
+    def list(self):
+        return self._c._get("/opening-balances")["opening_balances"]
+
+    def create(self, account_name, account_type, amount, as_of_date, currency=None, gl_code=None):
+        return self._c._post("/opening-balances", _clean(dict(account_name=account_name, account_type=account_type, amount=amount,
+                                                              as_of_date=as_of_date, currency=currency, gl_code=gl_code)))
+
+    def delete(self, balance_id):
+        return self._c._post(f"/opening-balances/{balance_id}/delete")
+
+
+class Accruals(_Resource):
+    def list(self):
+        return self._c._get("/accruals")["accruals"]
+
+    def create(self, entry_type, amount, issue_date, **fields):
+        """fields: gl_code, counterparty, description, due_date, recognition_start_date, recognition_months, external_source, external_id"""
+        return self._c._post("/accruals", _clean(dict(entry_type=entry_type, amount=amount, issue_date=issue_date, **fields)))
+
+    def match(self, accrual_id, tx_hash, wallet_address, chain, matched_date):
+        return self._c._post(f"/accruals/{accrual_id}/match", dict(tx_hash=tx_hash, wallet_address=wallet_address, chain=chain, matched_date=matched_date))
+
+    def delete(self, accrual_id):
+        return self._c._post(f"/accruals/{accrual_id}/delete")
+
+
+class ClassificationRules(_Resource):
+    def list(self):
+        return self._c._get("/classification-rules")["classification_rules"]
+
+    def create(self, gl_code, direction=None, chain=None, counterparty=None, amount_min=None, amount_max=None, entity_id=None):
+        return self._c._post("/classification-rules", _clean(dict(gl_code=gl_code, direction=direction, chain=chain, counterparty=counterparty,
+                                                                  amount_min=amount_min, amount_max=amount_max, entity_id=entity_id)))
+
+    def delete(self, rule_id):
+        return self._c._post(f"/classification-rules/{rule_id}/delete")
+
+
+class Reconciliation(_Resource):
+    def get(self, wallet_id):
+        return self._c._get("/reconciliation", wallet_id=wallet_id)
+
+    def set_baseline(self, wallet_id, balance):
+        return self._c._post("/reconciliation/baseline", dict(wallet_id=wallet_id, balance=balance))
+
+
+class Accounts(_Resource):
+    """Accounts you push transactions to: bank, credit_card, stablecoin or ledger."""
+
+    def list(self, end_user_id=None):
+        return self._c._get("/accounts", end_user_id=end_user_id)["accounts"]
+
+    def create(self, external_id, name=None, type=None, currency=None, end_user_id=None, end_user_name=None, entity_id=None,
+               idempotency_key=None):
+        """Creates the account, or returns the existing one with the same external_id."""
+        return self._c._post("/accounts", _clean(dict(external_id=external_id, name=name, type=type, currency=currency,
+                                                      end_user_id=end_user_id, end_user_name=end_user_name, entity_id=entity_id)),
+                             idempotency_key=idempotency_key)
+
+    def get(self, account_id):
+        return self._c._get(f"/accounts/{account_id}")
+
+    def push_transactions(self, account_id, transactions, classify=True, idempotency_key=None):
+        """Send up to 1000 transactions: dicts with external_id, date, amount, and optionally direction, counterparty,
+        currency, category. Returns {created, duplicates, rejected, ids, classification}. Safe to resend."""
+        return self._c._post(f"/accounts/{account_id}/transactions", dict(transactions=transactions, classify=classify),
+                             idempotency_key=idempotency_key)
+
+    def transactions(self, account_id, **filters):
+        """Every transaction of one account, following pages."""
+        return self._c._iterate(f"/accounts/{account_id}/transactions", "transactions", filters)
+
+    def classify(self, account_id):
+        """Classify the account's unclassified transactions in the background. Returns a job."""
+        return self._c._post(f"/accounts/{account_id}/classify")
+
+
+class Jobs(_Resource):
+    def list(self):
+        return self._c._get("/jobs")["jobs"]
+
+    def get(self, job_id):
+        return self._c._get(f"/jobs/{job_id}")
+
+    def wait(self, job_id, timeout=300, interval=2):
+        """Polls until the job succeeds (returns it) or fails (raises ShepherdError)."""
+        deadline = time.time() + timeout
+        while True:
+            job = self.get(job_id)
+            if job["status"] == "succeeded":
+                return job
+            if job["status"] == "failed":
+                raise ShepherdError(0, job.get("error") or "job failed", job)
+            if time.time() > deadline:
+                raise ShepherdError(0, f"job {job_id} still {job['status']} after {timeout}s", job)
+            time.sleep(interval)
+
+
+class ApiKeys(_Resource):
+    """Needs an admin key."""
+
+    def list(self):
+        return self._c._get("/api-keys")["api_keys"]
+
+    def create(self, label=None, scope=None, expires_in_days=None, rate_limit_per_min=None):
+        """scope: read, write or admin. The secret in `api_key` is shown once."""
+        return self._c._post("/api-keys", _clean(dict(label=label, scope=scope, expires_in_days=expires_in_days,
+                                                      rate_limit_per_min=rate_limit_per_min)))
+
+    def rotate(self, key_id, grace_hours=None):
+        """Issues a replacement; the old key keeps working for grace_hours (default 24)."""
+        return self._c._post(f"/api-keys/{key_id}/rotate", _clean(dict(grace_hours=grace_hours)))
+
+    def revoke(self, key_id):
+        return self._c._post(f"/api-keys/{key_id}/revoke")
+
+
+class Workspaces(_Resource):
+    """One separate set of books per customer. Use `shep.with_workspace(external_id)` to work inside one."""
+
+    def list(self):
+        return list(self._c._iterate("/workspaces", "workspaces", {}))
+
+    def create(self, external_id, name, contact_email=None, idempotency_key=None):
+        return self._c._post("/workspaces", _clean(dict(external_id=external_id, name=name, contact_email=contact_email)),
+                             idempotency_key=idempotency_key)
+
+    def get(self, workspace_id):
+        return self._c._get(f"/workspaces/{workspace_id}")
+
+    def update(self, workspace_id, name):
+        return self._c._post(f"/workspaces/{workspace_id}/update", dict(name=name))
+
+    def delete(self, workspace_id, confirm):
+        """Permanently deletes the workspace and its data. `confirm` must equal its external_id."""
+        return self._c._post(f"/workspaces/{workspace_id}/delete", dict(confirm=confirm))
+
+
+class ChartOfAccounts(_Resource):
+    def list(self):
+        return self._c._get("/chart-of-accounts")["accounts"]
+
+    def add(self, accounts, replace=False):
+        """accounts: dicts with code, name, account_type, description, parent_code. replace=True needs an admin key."""
+        return self._c._post("/chart-of-accounts", dict(accounts=accounts, replace=replace))
+
+
+class Periods(_Resource):
+    def get(self):
+        return self._c._get("/periods")
+
+    def close(self, through, note=None):
+        return self._c._post("/periods/close", _clean(dict(through=through, note=note)))
+
+    def reopen(self, to, note):
+        return self._c._post("/periods/reopen", dict(to=to, note=note))
+
+
+class AuditLog(_Resource):
+    def iterate(self, limit=None):
+        return self._c._iterate("/audit-log", "entries", _clean(dict(limit=limit)))
+
+
+class Webhooks(_Resource):
+    def list(self):
+        return self._c._get("/webhooks")["webhooks"]
+
+    def create(self, url, events=None, description=None):
+        """Returns the endpoint including its signing `secret`. The secret is shown once."""
+        return self._c._post("/webhooks", _clean(dict(url=url, events=events, description=description)))
+
+    def delete(self, webhook_id):
+        return self._c._post(f"/webhooks/{webhook_id}/delete")
+
+    def test(self, webhook_id):
+        """Queue a `ping` event to this endpoint."""
+        return self._c._post(f"/webhooks/{webhook_id}/test")
+
+    def deliveries(self, webhook_id):
+        return self._c._get(f"/webhooks/{webhook_id}/deliveries")["deliveries"]
+
+    construct_event = staticmethod(_wh.construct_event)
+
+
+class Sandbox(_Resource):
+    def reset(self):
+        """Wipe this sandbox back to its seed data. Sandbox keys only."""
+        return self._c._post("/sandbox/reset")
+
+
+class Shepherd:
+    def __init__(self, api_key, base_url=DEFAULT_BASE_URL, timeout=60, max_retries=2, workspace=None):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.workspace = workspace
+        self.livemode = not api_key.startswith("shep_test_")
+        self._s = requests.Session()
+        self._s.headers.update({"Authorization": f"Bearer {api_key}", "User-Agent": "shepherd-python/0.2.0"})
+        if workspace:
+            self._s.headers["Shepherd-Workspace"] = str(workspace)
+        self.wallets = Wallets(self)
+        self.transactions = Transactions(self)
+        self.statements = Statements(self)
+        self.entities = Entities(self)
+        self.opening_balances = OpeningBalances(self)
+        self.accruals = Accruals(self)
+        self.classification_rules = ClassificationRules(self)
+        self.reconciliation = Reconciliation(self)
+        self.webhooks = Webhooks(self)
+        self.sandbox = Sandbox(self)
+        self.accounts = Accounts(self)
+        self.jobs = Jobs(self)
+        self.api_keys = ApiKeys(self)
+        self.workspaces = Workspaces(self)
+        self.chart_of_accounts = ChartOfAccounts(self)
+        self.periods = Periods(self)
+        self.audit_log = AuditLog(self)
+
+    def with_workspace(self, external_id):
+        """A client that works inside one customer's workspace (platform accounts)."""
+        return Shepherd(self.api_key, base_url=self.base_url, timeout=self.timeout, max_retries=self.max_retries, workspace=external_id)
+
+    def _iterate(self, path, key, params):
+        params = dict(params or {})
+        while True:
+            page = self._get(path, **params)
+            for item in page[key]:
+                yield item
+            if not page.get("has_more"):
+                return
+            params["cursor"] = page["next_cursor"]
+
+    @classmethod
+    def create_sandbox(cls, email=None, name=None, base_url=DEFAULT_BASE_URL):
+        """Mint an instant sandbox key (no signup form) and return a client for it. The seed details are on `.sandbox_info`."""
+        r = requests.post(base_url.rstrip("/") + "/sandbox/signup", json=_clean(dict(email=email, name=name)), timeout=30)
+        body = _json(r)
+        if not r.ok:
+            raise _error(r.status_code, body)
+        client = cls(body["api_key"], base_url=base_url)
+        client.sandbox_info = body
+        return client
+
+    def _request(self, method, path, params=None, json_body=None, idempotency_key=None):
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        retriable = method == "GET" or bool(idempotency_key)   # a POST is only retried when it is safe to repeat
+        attempt = 0
+        while True:
+            try:
+                r = self._s.request(method, self.base_url + path, params=_clean(params or {}) or None, json=json_body,
+                                    headers=headers, timeout=self.timeout)
+            except requests.RequestException as e:
+                if retriable and attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(0.5 * 2 ** attempt)
+                    continue
+                raise ShepherdError(0, f"network error: {e}")
+            body = _json(r)
+            if r.ok:
+                return body
+            if retriable and r.status_code in (429, 502, 503) and attempt < self.max_retries:
+                attempt += 1
+                try:
+                    wait = min(30.0, float(r.headers.get("Retry-After")))
+                except (TypeError, ValueError):
+                    wait = 0.5 * 2 ** attempt
+                time.sleep(wait)
+                continue
+            raise _error(r.status_code, body, r.headers)
+
+    def _get(self, path, **params):
+        return self._request("GET", path, params=params)
+
+    def _post(self, path, body=None, idempotency_key=None):
+        return self._request("POST", path, json_body=body if body is not None else {}, idempotency_key=idempotency_key)
+
+
+def _json(r):
+    try:
+        return r.json()
+    except ValueError:
+        return {"error": r.text[:200]}
+
+
+def _error(status, body, headers=None):
+    body = body or {}
+    msg = body.get("message") or body.get("error") or "request failed"
+    cls = {400: InvalidRequestError, 401: AuthenticationError, 403: PermissionDeniedError, 404: NotFoundError,
+           409: ConflictError, 413: InvalidRequestError, 422: InvalidRequestError, 429: RateLimitError}.get(status)
+    if cls is None:
+        cls = ServerError if status >= 500 else ShepherdError
+    err = cls(status, msg, body)
+    err.code = body.get("code")
+    err.request_id = body.get("request_id")
+    try:
+        err.retry_after = float((headers or {}).get("Retry-After"))
+    except (TypeError, ValueError):
+        err.retry_after = None
+    return err

shepherd_sdk-0.2.0/shepherd/errors.py

@@ -0,0 +1,43 @@
+class ShepherdError(Exception):
+    """Raised for any non-2xx response. `status` is the HTTP status, `message` is the API's `error` text."""
+
+    def __init__(self, status, message, body=None):
+        super().__init__(f"{status}: {message}")
+        self.status = status
+        self.message = message
+        self.body = body or {}
+        self.code = self.body.get("code")            # stable, safe to branch on, e.g. "period_closed"
+        self.request_id = self.body.get("request_id")  # quote this when contacting Shepherd
+        self.retry_after = None                       # seconds, set on 429 and 503
+
+
+class AuthenticationError(ShepherdError):
+    """401: missing, malformed, expired or revoked API key."""
+
+
+class PermissionDeniedError(ShepherdError):
+    """403: the key's scope is too low, or the account can't use this feature."""
+
+
+class ConflictError(ShepherdError):
+    """409: for example the period is closed, or the same Idempotency-Key is still running."""
+
+
+class NotFoundError(ShepherdError):
+    """404: the object doesn't exist in your organization."""
+
+
+class InvalidRequestError(ShepherdError):
+    """400: a field is missing or invalid."""
+
+
+class RateLimitError(ShepherdError):
+    """429: slow down."""
+
+
+class ServerError(ShepherdError):
+    """5xx: Shepherd (or a chain data source) failed. Safe to retry."""
+
+
+class SignatureVerificationError(Exception):
+    """A webhook payload failed signature verification."""

shepherd_sdk-0.2.0/shepherd/webhooks.py

@@ -0,0 +1,29 @@
+import hashlib
+import hmac
+import json
+import time
+
+from .errors import SignatureVerificationError
+
+
+def construct_event(payload, signature_header, secret, tolerance=300):
+    """Verify a webhook and return the parsed event.
+
+    payload          the raw request body, exactly as received (bytes or str), not re-serialized JSON
+    signature_header the value of the `Shepherd-Signature` header
+    secret           your endpoint's signing secret (whsec_...)
+    tolerance        seconds a timestamp may differ from now; guards against replays (default 5 minutes)
+    """
+    if isinstance(payload, bytes):
+        payload = payload.decode("utf-8")
+    try:
+        parts = dict(p.split("=", 1) for p in signature_header.split(","))
+        ts, sig = int(parts["t"]), parts["v1"]
+    except Exception:
+        raise SignatureVerificationError("Malformed Shepherd-Signature header")
+    expected = hmac.new(secret.encode(), f"{ts}.{payload}".encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, sig):
+        raise SignatureVerificationError("Signature does not match")
+    if tolerance and abs(time.time() - ts) > tolerance:
+        raise SignatureVerificationError("Timestamp outside the tolerance window")
+    return json.loads(payload)

shepherd_sdk-0.2.0/tests/test_integration.py

@@ -0,0 +1,140 @@
+"""Runs against a live server: SHEPHERD_TEST_BASE=http://localhost:8191/api/v1 python -m pytest tests"""
+import os, time, hmac, hashlib, json
+import pytest
+from shepherd import Shepherd, NotFoundError, InvalidRequestError, AuthenticationError, SignatureVerificationError, construct_event
+
+BASE = os.environ.get("SHEPHERD_TEST_BASE")
+pytestmark = pytest.mark.skipif(not BASE, reason="set SHEPHERD_TEST_BASE")
+
+
+@pytest.fixture(scope="module")
+def shep():
+    return Shepherd.create_sandbox(email="sdk-test@example.com", base_url=BASE)
+
+
+def test_sandbox_seed(shep):
+    assert shep.livemode is False
+    ws = shep.wallets.list()
+    assert len(ws) == 1 and shep.sandbox_info["seeded"]["end_user_id"] == "cust_demo"
+
+
+def test_statements_and_filters(shep):
+    txs = shep.transactions.list(end_user_id="cust_demo")
+    assert len(txs) == 40
+    pnl = shep.statements.income(start_date="2020-01-01", end_user_id="cust_demo")
+    assert pnl["total_revenue"] > 0
+    assert shep.statements.balance_sheet() is not None
+
+
+def test_connect_scan_classify(shep):
+    w = shep.wallets.connect("0xdef4560000000000000000000000000000000def", "polygon", end_user_id="cust_x", end_user_name="X")
+    assert w["transactions_saved"] == 40
+    assert shep.wallets.scan(w["wallet_id"])["success"]
+    unc = shep.transactions.list(wallet_id=w["wallet_id"], gl_code="Unclassified") or [t for t in shep.transactions.list(wallet_id=w["wallet_id"]) if not t.get("gl_code")]
+    assert shep.transactions.classify(unc[0]["id"], "6600 - Office & Operations")["success"]
+
+
+def test_errors(shep):
+    with pytest.raises(InvalidRequestError):
+        shep.wallets.connect("0x1", "dogechain")
+    with pytest.raises(NotFoundError):
+        shep.wallets.scan(999999)
+    with pytest.raises(AuthenticationError):
+        Shepherd("shep_test_nope", base_url=BASE).wallets.list()
+
+
+def test_entities_rules(shep):
+    e = shep.entities.create("Customer A", functional_currency="USD")
+    assert any(x["name"] == "Customer A" for x in shep.entities.list())
+    shep.classification_rules.create("6200 - Software & SaaS", counterparty="Vercel")
+    assert len(shep.classification_rules.list()) == 1
+    shep.opening_balances.create("Cash", "asset", 1000, "2026-01-01")
+    assert len(shep.opening_balances.list()) == 1
+
+
+def test_webhook_signature():
+    body = json.dumps({"id": "evt_1", "type": "ping"})
+    ts = int(time.time())
+    sig = hmac.new(b"whsec_x", f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
+    assert construct_event(body, f"t={ts},v1={sig}", "whsec_x")["id"] == "evt_1"
+    with pytest.raises(SignatureVerificationError):
+        construct_event(body, f"t={ts},v1=deadbeef", "whsec_x")
+    old = ts - 1000
+    sig_old = hmac.new(b"whsec_x", f"{old}.{body}".encode(), hashlib.sha256).hexdigest()
+    with pytest.raises(SignatureVerificationError):
+        construct_event(body, f"t={old},v1={sig_old}", "whsec_x")
+
+
+def test_reset(shep):
+    shep.sandbox.reset()
+    assert len(shep.wallets.list()) == 1
+
+
+# ---- 0.2.0: accounts, pagination, jobs, keys, workspaces
+from shepherd import PermissionDeniedError, ConflictError
+
+
+def test_push_and_paginate(shep):
+    acct = shep.accounts.create("sdk_acct", name="SDK bank", type="bank", currency="USD", end_user_id="cust_sdk", idempotency_key="sdk-acct-1")
+    again = shep.accounts.create("sdk_acct", name="SDK bank", type="bank", currency="USD", end_user_id="cust_sdk", idempotency_key="sdk-acct-1")
+    assert again["id"] == acct["id"]
+    txs = [dict(external_id=f"s{i}", date="2026-08-%02d" % (1 + i % 28), amount=10 + i, direction="outflow", counterparty="Vendor %d" % (i % 5)) for i in range(250)]
+    r = shep.accounts.push_transactions(acct["id"], txs, classify=False)
+    assert r["created"] == 250 and r["rejected"] == []
+    r2 = shep.accounts.push_transactions(acct["id"], txs[:10], classify=False)
+    assert r2["created"] == 0 and r2["duplicates"] == 10
+    bad = shep.accounts.push_transactions(acct["id"], [dict(external_id="bad", date="nope", amount=1)], classify=False)
+    assert len(bad["rejected"]) == 1
+    seen = list(shep.accounts.transactions(acct["id"], limit=100))
+    assert len(seen) == 250 and len({t["id"] for t in seen}) == 250
+    assert len(list(shep.transactions.iterate(wallet_id=acct["id"], limit=60))) == 250
+    assert shep.transactions.page(wallet_id=acct["id"], limit=10)["has_more"] is True
+    assert shep.transactions.get(seen[0]["id"])["id"] == seen[0]["id"]
+
+
+def test_jobs(shep):
+    acct = shep.accounts.create("sdk_acct2", type="stablecoin")
+    shep.accounts.push_transactions(acct["id"], [dict(external_id="j1", date="2026-08-03", amount=5, counterparty="Acme")], classify=False)
+    job = shep.accounts.classify(acct["id"])
+    done = shep.jobs.wait(job["job_id"], timeout=60, interval=1)
+    assert done["status"] == "succeeded"
+    assert any(j["id"] == job["job_id"] for j in shep.jobs.list())
+
+
+def test_keys_scopes_errors(shep):
+    ro = shep.api_keys.create(label="ro", scope="read")
+    reader = Shepherd(ro["api_key"], base_url=BASE)
+    assert reader.transactions.list(limit=1) is not None
+    with pytest.raises(PermissionDeniedError) as ei:
+        reader.accounts.create("nope")
+    assert ei.value.code == "insufficient_scope" and ei.value.request_id
+    rot = shep.api_keys.rotate(ro["id"], grace_hours=1)
+    assert rot["replaces"] == ro["id"]
+    shep.api_keys.revoke(rot["id"])
+    with pytest.raises(AuthenticationError) as ei:
+        Shepherd(rot["api_key"], base_url=BASE).wallets.list()
+    assert ei.value.code == "invalid_api_key"
+    assert any(k["id"] == ro["id"] for k in shep.api_keys.list())
+
+
+def test_workspaces(shep):
+    ws = shep.workspaces.create("sdk_cust_1", "SDK Customer 1")
+    inside = shep.with_workspace("sdk_cust_1")
+    assert inside.accounts.list() == []
+    a = inside.accounts.create("w1", type="bank")
+    inside.accounts.push_transactions(a["id"], [dict(external_id="w", date="2026-08-02", amount=7, counterparty="Z")], classify=False)
+    assert len(list(inside.transactions.iterate())) == 1
+    assert all(x["id"] != a["id"] for x in shep.accounts.list())
+    assert any(w["external_id"] == "sdk_cust_1" for w in shep.workspaces.list())
+    with pytest.raises(InvalidRequestError):
+        shep.workspaces.delete("sdk_cust_1", confirm="wrong")
+    assert shep.workspaces.delete("sdk_cust_1", confirm="sdk_cust_1")["success"]
+    with pytest.raises(NotFoundError):
+        shep.workspaces.get("sdk_cust_1")
+
+
+def test_chart_periods_audit(shep):
+    assert len(shep.chart_of_accounts.list()) > 5
+    assert shep.chart_of_accounts.add([dict(code="6901 - SDK Test", name="SDK Test", account_type="expense")])["received"] == 1
+    assert "closed_through" in shep.periods.get()
+    assert len(list(zip(range(5), shep.audit_log.iterate(limit=2)))) == 5