billos 0.1.0__tar.gz

billos-0.1.0/LICENSE

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

billos-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: billos
+Version: 0.1.0
+Summary: BillOS for Python: Israeli tax documents, expenses, webhooks and the regulatory outputs, over one small client.
+Author: BillOS
+License: MIT
+Project-URL: Documentation, https://docs.billos.co.il
+Project-URL: Homepage, https://billos.co.il
+Project-URL: Source, https://github.com/baraviz/pest-os/tree/main/packages/billos-python
+Keywords: billos,invoice,bookkeeping,israel,tax,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# billos (Python)
+
+BillOS from Python: legally valid Israeli tax documents (חשבונית מס, קבלה, זיכוי), the expense ledger, webhooks and the regulatory outputs, over one small client with no dependencies beyond the standard library (Python 3.9+).
+
+```bash
+pip install billos
+```
+
+```python
+from billos import BillOS, BillOSError
+
+billos = BillOS(api_key=os.environ["BILLOS_API_KEY"])
+bid = billos.businesses.list()["businesses"][0]["id"]
+
+created = billos.documents.create(bid, {
+    "docType": 320,
+    "priceMode": "gross",
+    "party": {"name": "דנה לוי", "phone": "0521111111"},
+    "lines": [{"description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000}],
+    "payments": [{"method": "card", "amount": 120000}],
+}, idempotency_key="order-8812")
+
+issued = billos.documents.issue(bid, created["document"]["id"])
+print(issued["document"]["docNumber"])
+
+pdf = billos.documents.print(bid, created["document"]["id"])   # Binary: .bytes, .content_type, .variant
+link = billos.documents.share(bid, created["document"]["id"])   # a public URL for the customer
+```
+
+Money is **integer agorot** everywhere, exactly like the API (₪354.00 is `35400`); a foreign-currency document (`"currency": "USD"`) is in that currency's cents. Nothing in the client converts.
+
+## What you get
+
+- Every operation in the spec as `namespace.method` (snake_case): `businesses`, `parties`, `documents`, `recurring`, `expenses`, `exports`, `files`, `webhooks`, `events`, `keys`, `usage`, `sandbox`. `OPERATIONS` (method and path per operation) is generated from the OpenAPI spec, and a test checks every operation has a method, so the client cannot lag behind the API.
+- The conventions handled: `X-Api-Key`, the `{ok, ...}` envelope returned as a dict (plus `request_id`), `Idempotency-Key` from `idempotency_key=`, `Retry-After` honoured.
+- Retries on 429 / 502 / 503 / 504 and network errors, up to `max_retries` (default 2), for GET/DELETE and for POSTs carrying an idempotency key; never for a POST without one.
+- `BillOSError` with `status`, `reason`, `request_id`, `body`, `retryable`. Branch on `reason`.
+- Binary answers (`documents.preview`, `documents.print`, `files.get`, a PDF report) come back as `Binary(bytes, content_type, variant, request_id)`.
+- `verify_webhook_signature(secret, header, raw_body)` for the `X-BillOS-Signature` header.
+- A `bk_test_` key answers from the sandbox with no change on your side (`billos.sandbox.seed()` fills it with demo data).
+
+Documentation and the OpenAPI spec: https://docs.billos.co.il. MIT.

billos-0.1.0/README.md

@@ -0,0 +1,42 @@
+# billos (Python)
+
+BillOS from Python: legally valid Israeli tax documents (חשבונית מס, קבלה, זיכוי), the expense ledger, webhooks and the regulatory outputs, over one small client with no dependencies beyond the standard library (Python 3.9+).
+
+```bash
+pip install billos
+```
+
+```python
+from billos import BillOS, BillOSError
+
+billos = BillOS(api_key=os.environ["BILLOS_API_KEY"])
+bid = billos.businesses.list()["businesses"][0]["id"]
+
+created = billos.documents.create(bid, {
+    "docType": 320,
+    "priceMode": "gross",
+    "party": {"name": "דנה לוי", "phone": "0521111111"},
+    "lines": [{"description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000}],
+    "payments": [{"method": "card", "amount": 120000}],
+}, idempotency_key="order-8812")
+
+issued = billos.documents.issue(bid, created["document"]["id"])
+print(issued["document"]["docNumber"])
+
+pdf = billos.documents.print(bid, created["document"]["id"])   # Binary: .bytes, .content_type, .variant
+link = billos.documents.share(bid, created["document"]["id"])   # a public URL for the customer
+```
+
+Money is **integer agorot** everywhere, exactly like the API (₪354.00 is `35400`); a foreign-currency document (`"currency": "USD"`) is in that currency's cents. Nothing in the client converts.
+
+## What you get
+
+- Every operation in the spec as `namespace.method` (snake_case): `businesses`, `parties`, `documents`, `recurring`, `expenses`, `exports`, `files`, `webhooks`, `events`, `keys`, `usage`, `sandbox`. `OPERATIONS` (method and path per operation) is generated from the OpenAPI spec, and a test checks every operation has a method, so the client cannot lag behind the API.
+- The conventions handled: `X-Api-Key`, the `{ok, ...}` envelope returned as a dict (plus `request_id`), `Idempotency-Key` from `idempotency_key=`, `Retry-After` honoured.
+- Retries on 429 / 502 / 503 / 504 and network errors, up to `max_retries` (default 2), for GET/DELETE and for POSTs carrying an idempotency key; never for a POST without one.
+- `BillOSError` with `status`, `reason`, `request_id`, `body`, `retryable`. Branch on `reason`.
+- Binary answers (`documents.preview`, `documents.print`, `files.get`, a PDF report) come back as `Binary(bytes, content_type, variant, request_id)`.
+- `verify_webhook_signature(secret, header, raw_body)` for the `X-BillOS-Signature` header.
+- A `bk_test_` key answers from the sandbox with no change on your side (`billos.sandbox.seed()` fills it with demo data).
+
+Documentation and the OpenAPI spec: https://docs.billos.co.il. MIT.

billos-0.1.0/billos/__init__.py

@@ -0,0 +1,4 @@
+"""BillOS for Python: a thin, dependency-free client over the ledger API (https://docs.billos.co.il)."""
+from .client import BillOS, BillOSError, OPERATIONS, SURFACE, DEFAULT_BASE_URL, VERSION, verify_webhook_signature
+
+__all__ = ["BillOS", "BillOSError", "OPERATIONS", "SURFACE", "DEFAULT_BASE_URL", "VERSION", "verify_webhook_signature"]

billos-0.1.0/billos/_operations.py

@@ -0,0 +1,62 @@
+# GENERATED from the BillOS OpenAPI spec by packages/billos-sdk/scripts/generate.mjs. Do not edit.
+# operationId -> (method, path template). The client's namespaces name these; a test in the Node
+# SDK regenerates this file and fails when the commit is stale.
+OPERATIONS = {
+    "createBusiness": ("POST", "/businesses"),
+    "listBusinesses": ("GET", "/businesses"),
+    "getBusiness": ("GET", "/businesses/{bid}"),
+    "updateBusiness": ("PATCH", "/businesses/{bid}"),
+    "deactivateBusiness": ("POST", "/businesses/{bid}/deactivate"),
+    "reactivateBusiness": ("POST", "/businesses/{bid}/reactivate"),
+    "createParty": ("POST", "/businesses/{bid}/parties"),
+    "listParties": ("GET", "/businesses/{bid}/parties"),
+    "updateParty": ("PATCH", "/businesses/{bid}/parties/{id}"),
+    "recordPartyConsent": ("POST", "/businesses/{bid}/parties/{id}/consent"),
+    "getFxRate": ("GET", "/businesses/{bid}/fx-rate"),
+    "createDocument": ("POST", "/businesses/{bid}/documents"),
+    "listDocuments": ("GET", "/businesses/{bid}/documents"),
+    "getDocument": ("GET", "/businesses/{bid}/documents/{id}"),
+    "updateDocument": ("PATCH", "/businesses/{bid}/documents/{id}"),
+    "deleteDocument": ("DELETE", "/businesses/{bid}/documents/{id}"),
+    "issueDocument": ("POST", "/businesses/{bid}/documents/{id}/issue"),
+    "issueCreditNote": ("POST", "/businesses/{bid}/documents/{id}/credit-note"),
+    "previewDocument": ("POST", "/businesses/{bid}/documents/{id}/preview"),
+    "printDocument": ("POST", "/businesses/{bid}/documents/{id}/prints"),
+    "createRecurring": ("POST", "/businesses/{bid}/recurring"),
+    "listRecurring": ("GET", "/businesses/{bid}/recurring"),
+    "getRecurring": ("GET", "/businesses/{bid}/recurring/{id}"),
+    "updateRecurring": ("PATCH", "/businesses/{bid}/recurring/{id}"),
+    "deleteRecurring": ("DELETE", "/businesses/{bid}/recurring/{id}"),
+    "runRecurring": ("POST", "/businesses/{bid}/recurring/{id}/run"),
+    "createExpense": ("POST", "/businesses/{bid}/expenses"),
+    "listExpenses": ("GET", "/businesses/{bid}/expenses"),
+    "shareDocument": ("POST", "/businesses/{bid}/documents/{id}/share"),
+    "emailDocument": ("POST", "/businesses/{bid}/documents/{id}/email"),
+    "findOrCreateParty": ("POST", "/businesses/{bid}/parties/find-or-create"),
+    "recordExpenseDirect": ("POST", "/businesses/{bid}/expenses/record"),
+    "deleteExpenseDraft": ("DELETE", "/businesses/{bid}/expenses/{id}"),
+    "getExpense": ("GET", "/businesses/{bid}/expenses/{id}"),
+    "updateExpense": ("PATCH", "/businesses/{bid}/expenses/{id}"),
+    "recordExpense": ("POST", "/businesses/{bid}/expenses/{id}/record"),
+    "correctExpense": ("POST", "/businesses/{bid}/expenses/{id}/correction"),
+    "ocrExpense": ("POST", "/businesses/{bid}/expenses/ocr"),
+    "exportOpenfrmt": ("POST", "/businesses/{bid}/exports/openfrmt"),
+    "continuityReport": ("GET", "/businesses/{bid}/reports/continuity"),
+    "managementReport": ("GET", "/businesses/{bid}/reports/{kind}"),
+    "createBackup": ("POST", "/businesses/{bid}/backup"),
+    "fileThumbnails": ("POST", "/businesses/{bid}/files/thumbs"),
+    "getFile": ("GET", "/businesses/{bid}/files/{id}"),
+    "listKeys": ("GET", "/keys"),
+    "updateKey": ("PATCH", "/keys/{id}"),
+    "getUsage": ("GET", "/usage"),
+    "createWebhook": ("POST", "/webhooks"),
+    "listWebhooks": ("GET", "/webhooks"),
+    "updateWebhook": ("PATCH", "/webhooks/{id}"),
+    "deleteWebhook": ("DELETE", "/webhooks/{id}"),
+    "listWebhookDeliveries": ("GET", "/webhooks/{id}/deliveries"),
+    "redeliverWebhook": ("POST", "/webhooks/{id}/deliveries/{did}/redeliver"),
+    "seedSandbox": ("POST", "/sandbox/seed"),
+    "listEvents": ("GET", "/events"),
+    "getEvent": ("GET", "/events/{id}"),
+    "testWebhook": ("POST", "/webhooks/{id}/test"),
+}

billos-0.1.0/billos/client.py

@@ -0,0 +1,320 @@
+"""billos: BillOS from Python.
+
+A thin wrapper over the ledger API with no dependencies beyond the standard library: one
+``request()`` that speaks the API's conventions (``X-Api-Key``, the ``{ok, ...}`` envelope,
+the ``{error, reason}`` failure shape, ``Idempotency-Key``, ``X-Request-Id``,
+``Retry-After``) and resource namespaces that name every operation in the OpenAPI spec.
+
+Money is integer agorot everywhere, exactly like the API. Amounts on a foreign-currency
+document are that currency's minor units. Nothing here converts.
+
+``_operations.py`` (method + path per operationId) is GENERATED from the OpenAPI spec by the
+Node SDK's generator and kept fresh by its test; ``SURFACE`` names where each operation lives
+on this client, and a test walks it, so a new endpoint without a Python method fails the suite.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from ._operations import OPERATIONS  # generated from the OpenAPI spec (see packages/billos-sdk/scripts/generate.mjs)
+
+DEFAULT_BASE_URL = "https://api.billos.co.il/v1"
+VERSION = "0.1.0"
+
+# operationId -> "namespace.method" on the client (what the drift test walks).
+SURFACE: Dict[str, str] = {
+    "createBusiness": "businesses.create", "listBusinesses": "businesses.list", "getBusiness": "businesses.get",
+    "updateBusiness": "businesses.update", "deactivateBusiness": "businesses.deactivate", "reactivateBusiness": "businesses.reactivate",
+    "listKeys": "keys.list", "updateKey": "keys.update", "getUsage": "usage.get",
+    "createParty": "parties.create", "listParties": "parties.list", "findOrCreateParty": "parties.find_or_create",
+    "updateParty": "parties.update", "recordPartyConsent": "parties.record_consent",
+    "getFxRate": "documents.fx_rate", "createDocument": "documents.create", "listDocuments": "documents.list",
+    "getDocument": "documents.get", "updateDocument": "documents.update", "deleteDocument": "documents.delete",
+    "issueDocument": "documents.issue", "issueCreditNote": "documents.credit_note", "previewDocument": "documents.preview",
+    "printDocument": "documents.print", "shareDocument": "documents.share", "emailDocument": "documents.email",
+    "createRecurring": "recurring.create", "listRecurring": "recurring.list", "getRecurring": "recurring.get",
+    "updateRecurring": "recurring.update", "deleteRecurring": "recurring.delete", "runRecurring": "recurring.run",
+    "createExpense": "expenses.create", "recordExpenseDirect": "expenses.record", "listExpenses": "expenses.list",
+    "getExpense": "expenses.get", "updateExpense": "expenses.update", "deleteExpenseDraft": "expenses.delete",
+    "recordExpense": "expenses.record_draft", "correctExpense": "expenses.correct", "ocrExpense": "expenses.ocr",
+    "exportOpenfrmt": "exports.openfrmt", "continuityReport": "exports.continuity", "managementReport": "exports.report",
+    "createBackup": "exports.backup", "fileThumbnails": "files.thumbnails", "getFile": "files.get",
+    "createWebhook": "webhooks.create", "listWebhooks": "webhooks.list", "updateWebhook": "webhooks.update",
+    "deleteWebhook": "webhooks.delete", "listWebhookDeliveries": "webhooks.deliveries", "redeliverWebhook": "webhooks.redeliver",
+    "testWebhook": "webhooks.test", "listEvents": "events.list", "getEvent": "events.get", "seedSandbox": "sandbox.seed",
+}
+
+TRANSIENT = {429, 502, 503, 504}
+
+
+class BillOSError(Exception):
+    """Every failure. ``reason`` is the API's stable code; ``request_id`` is what to quote to support."""
+
+    def __init__(self, status: int, reason: Optional[str], message: str, request_id: Optional[str] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.reason = reason or ("internal" if status >= 500 else "error")
+        self.request_id = request_id
+        self.body = body
+
+    @property
+    def retryable(self) -> bool:
+        """Transient: a 429/502/503/504 or a network failure. Re-send GET/DELETE freely; re-send a
+        POST only with the same idempotency key, or you may create the thing twice."""
+        return self.status in TRANSIENT or self.status == 0
+
+
+class Binary:
+    """A binary answer: PDF bytes, a stored file."""
+
+    def __init__(self, data: bytes, content_type: str, variant: Optional[str], request_id: Optional[str]):
+        self.bytes = data
+        self.content_type = content_type
+        self.variant = variant
+        self.request_id = request_id
+
+
+# The transport seam: (method, url, headers, body) -> (status, headers dict, body bytes).
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Tuple[int, Dict[str, str], bytes]]
+
+
+def _urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float):
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:  # noqa: S310 (https to our own API)
+            return res.status, {k.lower(): v for k, v in res.headers.items()}, res.read()
+    except urllib.error.HTTPError as e:
+        return e.code, {k.lower(): v for k, v in e.headers.items()}, e.read()
+
+
+def _fill(template: str, params: Dict[str, Any]) -> str:
+    def one(m: "re.Match[str]") -> str:
+        v = params.get(m.group(1))
+        if v is None or v == "":
+            raise TypeError(f'billos: missing path parameter "{m.group(1)}" for {template}')
+        return urllib.parse.quote(str(v), safe="")
+    return re.sub(r"\{(\w+)\}", one, template)
+
+
+def _query(query: Optional[Dict[str, Any]]) -> str:
+    if not query:
+        return ""
+    pairs = [(k, str(v).lower() if isinstance(v, bool) else str(v)) for k, v in query.items() if v is not None and v != ""]
+    return ("?" + urllib.parse.urlencode(pairs)) if pairs else ""
+
+
+class _NS:
+    def __init__(self, client: "BillOS"):
+        self._c = client
+
+
+class BillOS:
+    """``BillOS(api_key=...)``. Every method returns the API's JSON envelope as a dict (with
+    ``request_id`` added, non-standard but harmless) or a ``Binary`` for PDFs and files."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0, max_retries: int = 2,
+                 headers: Optional[Dict[str, str]] = None, transport: Optional[Transport] = None, sleep: Callable[[float], None] = time.sleep):
+        if not api_key or not isinstance(api_key, str):
+            raise TypeError("billos: api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.headers = dict(headers or {})
+        self._transport = transport or _urllib_transport
+        self._sleep = sleep
+        self.businesses = _Businesses(self)
+        self.keys = _Keys(self)
+        self.usage = _Usage(self)
+        self.parties = _Parties(self)
+        self.documents = _Documents(self)
+        self.recurring = _Recurring(self)
+        self.expenses = _Expenses(self)
+        self.exports = _Exports(self)
+        self.files = _Files(self)
+        self.webhooks = _Webhooks(self)
+        self.events = _Events(self)
+        self.sandbox = _Sandbox(self)
+
+    # ── the one call behind every method ────────────────────────────────────────────────
+    def request(self, op: str, path: Optional[Dict[str, Any]] = None, query: Optional[Dict[str, Any]] = None, body: Any = None,
+                idempotency_key: Optional[str] = None, headers: Optional[Dict[str, str]] = None, binary: bool = False,
+                raw: Optional[Tuple[bytes, str]] = None):
+        method, template = OPERATIONS[op]
+        url = self.base_url + _fill(template, path or {}) + _query(query)
+        can_retry = method in ("GET", "DELETE") or bool(idempotency_key)
+        h = {"X-Api-Key": self.api_key, "Accept": "*/*" if binary else "application/json", "User-Agent": f"billos-python/{VERSION}"}
+        h.update(self.headers)
+        h.update(headers or {})
+        if idempotency_key:
+            h["Idempotency-Key"] = str(idempotency_key)
+        payload: Optional[bytes] = None
+        if raw is not None:
+            payload, h["Content-Type"] = raw[0], raw[1]
+        elif body is not None:
+            payload = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            h["Content-Type"] = "application/json"
+
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                status, rh, data = self._transport(method, url, h, payload, self.timeout)
+            except Exception as e:  # network
+                if can_retry and attempt <= self.max_retries:
+                    self._sleep(0.25 * (2 ** (attempt - 1)))
+                    continue
+                raise BillOSError(0, "network", f"billos: {e}") from e
+            request_id = rh.get("x-request-id")
+            if 200 <= status < 300:
+                ctype = rh.get("content-type", "")
+                if binary or "json" not in ctype:
+                    return Binary(data, ctype or "application/octet-stream", rh.get("x-print-variant"), request_id)
+                out = json.loads(data.decode("utf-8")) if data else {}
+                if isinstance(out, dict):
+                    out.setdefault("request_id", request_id)
+                return out
+            try:
+                err_body = json.loads(data.decode("utf-8")) if data else None
+            except Exception:
+                err_body = None
+            if status in TRANSIENT and can_retry and attempt <= self.max_retries:
+                try:
+                    ra = float(rh.get("retry-after", ""))
+                except ValueError:
+                    ra = 0.0
+                self._sleep(min(ra, 30.0) if ra > 0 else 0.25 * (2 ** (attempt - 1)))
+                continue
+            ed = err_body if isinstance(err_body, dict) else {}
+            raise BillOSError(status, ed.get("reason"), ed.get("error") or f"HTTP {status}", request_id, err_body)
+
+
+class _Businesses(_NS):
+    def list(self, query=None, **o): return self._c.request("listBusinesses", query=query, **o)
+    def create(self, body, **o): return self._c.request("createBusiness", body=body, **o)
+    def get(self, bid, **o): return self._c.request("getBusiness", path={"bid": bid}, **o)
+    def update(self, bid, body, **o): return self._c.request("updateBusiness", path={"bid": bid}, body=body, **o)
+    def deactivate(self, bid, **o): return self._c.request("deactivateBusiness", path={"bid": bid}, **o)
+    def reactivate(self, bid, **o): return self._c.request("reactivateBusiness", path={"bid": bid}, **o)
+
+
+class _Keys(_NS):
+    def list(self, **o): return self._c.request("listKeys", **o)
+    def update(self, key_id, body, **o): return self._c.request("updateKey", path={"id": key_id}, body=body, **o)
+
+
+class _Usage(_NS):
+    def get(self, query=None, **o): return self._c.request("getUsage", query=query, **o)
+
+
+class _Parties(_NS):
+    def list(self, bid, query=None, **o): return self._c.request("listParties", path={"bid": bid}, query=query, **o)
+    def create(self, bid, body, **o): return self._c.request("createParty", path={"bid": bid}, body=body, **o)
+    def find_or_create(self, bid, body, **o): return self._c.request("findOrCreateParty", path={"bid": bid}, body=body, **o)
+    def update(self, bid, party_id, body, **o): return self._c.request("updateParty", path={"bid": bid, "id": party_id}, body=body, **o)
+    def record_consent(self, bid, party_id, body=None, **o): return self._c.request("recordPartyConsent", path={"bid": bid, "id": party_id}, body=body or {}, **o)
+
+
+class _Documents(_NS):
+    def fx_rate(self, bid, query, **o): return self._c.request("getFxRate", path={"bid": bid}, query=query, **o)
+    def create(self, bid, body, **o): return self._c.request("createDocument", path={"bid": bid}, body=body, **o)
+    def list(self, bid, query=None, **o): return self._c.request("listDocuments", path={"bid": bid}, query=query, **o)
+    def get(self, bid, doc_id, **o): return self._c.request("getDocument", path={"bid": bid, "id": doc_id}, **o)
+    def update(self, bid, doc_id, body, **o): return self._c.request("updateDocument", path={"bid": bid, "id": doc_id}, body=body, **o)
+    def delete(self, bid, doc_id, **o): return self._c.request("deleteDocument", path={"bid": bid, "id": doc_id}, **o)
+    def issue(self, bid, doc_id, body=None, **o): return self._c.request("issueDocument", path={"bid": bid, "id": doc_id}, body=body or {}, **o)
+    def credit_note(self, bid, doc_id, body=None, **o): return self._c.request("issueCreditNote", path={"bid": bid, "id": doc_id}, body=body or {}, **o)
+    def preview(self, bid, doc_id, body=None, **o): return self._c.request("previewDocument", path={"bid": bid, "id": doc_id}, body=body or {}, binary=True, **o)
+    def print(self, bid, doc_id, body=None, **o): return self._c.request("printDocument", path={"bid": bid, "id": doc_id}, body=body or {"kind": "auto"}, binary=True, **o)
+    def share(self, bid, doc_id, body=None, **o): return self._c.request("shareDocument", path={"bid": bid, "id": doc_id}, body=body or {"kind": "auto"}, **o)
+    def email(self, bid, doc_id, body, **o): return self._c.request("emailDocument", path={"bid": bid, "id": doc_id}, body=body, **o)
+
+
+class _Recurring(_NS):
+    def create(self, bid, body, **o): return self._c.request("createRecurring", path={"bid": bid}, body=body, **o)
+    def list(self, bid, query=None, **o): return self._c.request("listRecurring", path={"bid": bid}, query=query, **o)
+    def get(self, bid, plan_id, **o): return self._c.request("getRecurring", path={"bid": bid, "id": plan_id}, **o)
+    def update(self, bid, plan_id, body, **o): return self._c.request("updateRecurring", path={"bid": bid, "id": plan_id}, body=body, **o)
+    def delete(self, bid, plan_id, **o): return self._c.request("deleteRecurring", path={"bid": bid, "id": plan_id}, **o)
+    def run(self, bid, plan_id, **o): return self._c.request("runRecurring", path={"bid": bid, "id": plan_id}, **o)
+
+
+class _Expenses(_NS):
+    def create(self, bid, body, **o): return self._c.request("createExpense", path={"bid": bid}, body=body, **o)
+    def record(self, bid, body, **o): return self._c.request("recordExpenseDirect", path={"bid": bid}, body=body, **o)
+    def list(self, bid, query=None, **o): return self._c.request("listExpenses", path={"bid": bid}, query=query, **o)
+    def get(self, bid, expense_id, **o): return self._c.request("getExpense", path={"bid": bid, "id": expense_id}, **o)
+    def update(self, bid, expense_id, body, **o): return self._c.request("updateExpense", path={"bid": bid, "id": expense_id}, body=body, **o)
+    def delete(self, bid, expense_id, **o): return self._c.request("deleteExpenseDraft", path={"bid": bid, "id": expense_id}, **o)
+    def record_draft(self, bid, expense_id, **o): return self._c.request("recordExpense", path={"bid": bid, "id": expense_id}, **o)
+    def correct(self, bid, expense_id, body=None, **o): return self._c.request("correctExpense", path={"bid": bid, "id": expense_id}, body=body or {}, **o)
+
+    def ocr(self, bid, data: bytes, mime: str = "image/jpeg", **o):
+        """A receipt image or PDF -> a pre-filled draft. The bytes are the body with their own Content-Type."""
+        return self._c.request("ocrExpense", path={"bid": bid}, raw=(data, mime), **o)
+
+
+class _Exports(_NS):
+    def openfrmt(self, bid, body, **o): return self._c.request("exportOpenfrmt", path={"bid": bid}, body=body, **o)
+    def continuity(self, bid, query=None, **o): return self._c.request("continuityReport", path={"bid": bid}, query=query, **o)
+
+    def report(self, bid, kind, query=None, **o):
+        """``format='json'`` answers the report data; otherwise PDF bytes."""
+        return self._c.request("managementReport", path={"bid": bid, "kind": kind}, query=query, binary=(query or {}).get("format", "pdf") != "json", **o)
+
+    def backup(self, bid, **o): return self._c.request("createBackup", path={"bid": bid}, **o)
+
+
+class _Files(_NS):
+    def thumbnails(self, bid, body, **o): return self._c.request("fileThumbnails", path={"bid": bid}, body=body, **o)
+    def get(self, bid, file_id, **o): return self._c.request("getFile", path={"bid": bid, "id": file_id}, binary=True, **o)
+
+
+class _Webhooks(_NS):
+    def create(self, body, **o): return self._c.request("createWebhook", body=body, **o)
+    def list(self, **o): return self._c.request("listWebhooks", **o)
+    def update(self, webhook_id, body, **o): return self._c.request("updateWebhook", path={"id": webhook_id}, body=body, **o)
+    def delete(self, webhook_id, **o): return self._c.request("deleteWebhook", path={"id": webhook_id}, **o)
+    def deliveries(self, webhook_id, query=None, **o): return self._c.request("listWebhookDeliveries", path={"id": webhook_id}, query=query, **o)
+    def redeliver(self, webhook_id, delivery_id, **o): return self._c.request("redeliverWebhook", path={"id": webhook_id, "did": delivery_id}, **o)
+    def test(self, webhook_id, **o): return self._c.request("testWebhook", path={"id": webhook_id}, **o)
+
+
+class _Events(_NS):
+    def list(self, query=None, **o): return self._c.request("listEvents", query=query, **o)
+    def get(self, event_id, **o): return self._c.request("getEvent", path={"id": event_id}, **o)
+
+
+class _Sandbox(_NS):
+    def seed(self, **o):
+        """Test keys only: a demo business with customers, documents and expenses. Idempotent."""
+        return self._c.request("seedSandbox", **o)
+
+
+def verify_webhook_signature(secret: str, header: str, raw_body: bytes, tolerance_seconds: int = 300, now: Optional[float] = None) -> bool:
+    """Verify ``X-BillOS-Signature`` ("t=<unix>,v1=<hex>"): HMAC-SHA256 over the bytes ``t + "." + raw_body``.
+
+    ``raw_body`` must be the request's raw bytes, not a parsed or re-serialized body."""
+    if not isinstance(raw_body, (bytes, bytearray)):
+        raise TypeError("billos: raw_body must be the raw request bytes")
+    parts = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
+    try:
+        t = int(parts.get("t", ""))
+    except ValueError:
+        return False
+    v1 = parts.get("v1")
+    if not v1:
+        return False
+    if abs((now if now is not None else time.time()) - t) > tolerance_seconds:
+        return False
+    expected = hmac.new(secret.encode("utf-8"), f"{t}.".encode("utf-8") + bytes(raw_body), hashlib.sha256).hexdigest()
+    # Bytes, so a forged header with non-ASCII characters is a False, not a TypeError.
+    return hmac.compare_digest(expected.encode("ascii"), v1.encode("utf-8"))

billos-0.1.0/billos.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: billos
+Version: 0.1.0
+Summary: BillOS for Python: Israeli tax documents, expenses, webhooks and the regulatory outputs, over one small client.
+Author: BillOS
+License: MIT
+Project-URL: Documentation, https://docs.billos.co.il
+Project-URL: Homepage, https://billos.co.il
+Project-URL: Source, https://github.com/baraviz/pest-os/tree/main/packages/billos-python
+Keywords: billos,invoice,bookkeeping,israel,tax,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# billos (Python)
+
+BillOS from Python: legally valid Israeli tax documents (חשבונית מס, קבלה, זיכוי), the expense ledger, webhooks and the regulatory outputs, over one small client with no dependencies beyond the standard library (Python 3.9+).
+
+```bash
+pip install billos
+```
+
+```python
+from billos import BillOS, BillOSError
+
+billos = BillOS(api_key=os.environ["BILLOS_API_KEY"])
+bid = billos.businesses.list()["businesses"][0]["id"]
+
+created = billos.documents.create(bid, {
+    "docType": 320,
+    "priceMode": "gross",
+    "party": {"name": "דנה לוי", "phone": "0521111111"},
+    "lines": [{"description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000}],
+    "payments": [{"method": "card", "amount": 120000}],
+}, idempotency_key="order-8812")
+
+issued = billos.documents.issue(bid, created["document"]["id"])
+print(issued["document"]["docNumber"])
+
+pdf = billos.documents.print(bid, created["document"]["id"])   # Binary: .bytes, .content_type, .variant
+link = billos.documents.share(bid, created["document"]["id"])   # a public URL for the customer
+```
+
+Money is **integer agorot** everywhere, exactly like the API (₪354.00 is `35400`); a foreign-currency document (`"currency": "USD"`) is in that currency's cents. Nothing in the client converts.
+
+## What you get
+
+- Every operation in the spec as `namespace.method` (snake_case): `businesses`, `parties`, `documents`, `recurring`, `expenses`, `exports`, `files`, `webhooks`, `events`, `keys`, `usage`, `sandbox`. `OPERATIONS` (method and path per operation) is generated from the OpenAPI spec, and a test checks every operation has a method, so the client cannot lag behind the API.
+- The conventions handled: `X-Api-Key`, the `{ok, ...}` envelope returned as a dict (plus `request_id`), `Idempotency-Key` from `idempotency_key=`, `Retry-After` honoured.
+- Retries on 429 / 502 / 503 / 504 and network errors, up to `max_retries` (default 2), for GET/DELETE and for POSTs carrying an idempotency key; never for a POST without one.
+- `BillOSError` with `status`, `reason`, `request_id`, `body`, `retryable`. Branch on `reason`.
+- Binary answers (`documents.preview`, `documents.print`, `files.get`, a PDF report) come back as `Binary(bytes, content_type, variant, request_id)`.
+- `verify_webhook_signature(secret, header, raw_body)` for the `X-BillOS-Signature` header.
+- A `bk_test_` key answers from the sandbox with no change on your side (`billos.sandbox.seed()` fills it with demo data).
+
+Documentation and the OpenAPI spec: https://docs.billos.co.il. MIT.

billos-0.1.0/billos.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+billos/__init__.py
+billos/_operations.py
+billos/client.py
+billos.egg-info/PKG-INFO
+billos.egg-info/SOURCES.txt
+billos.egg-info/dependency_links.txt
+billos.egg-info/top_level.txt
+tests/test_client.py

billos-0.1.0/billos.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

billos-0.1.0/billos.egg-info/top_level.txt

@@ -0,0 +1 @@
+billos

billos-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "billos"
+version = "0.1.0"
+description = "BillOS for Python: Israeli tax documents, expenses, webhooks and the regulatory outputs, over one small client."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "BillOS" }]
+keywords = ["billos", "invoice", "bookkeeping", "israel", "tax", "api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Office/Business :: Financial :: Accounting",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://docs.billos.co.il"
+Homepage = "https://billos.co.il"
+Source = "https://github.com/baraviz/pest-os/tree/main/packages/billos-python"
+
+[tool.setuptools.packages.find]
+include = ["billos*"]

billos-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

billos-0.1.0/tests/test_client.py

@@ -0,0 +1,133 @@
+"""The client against a fake transport: headers, path filling, query encoding, envelope,
+errors with request ids, retries, binary answers, OCR raw upload, webhook signatures, and
+that SURFACE names a live method for every operation in the generated table.
+Run: python3 -m unittest discover -s packages/billos-python/tests"""
+import hashlib
+import hmac
+import json
+import os
+import sys
+import time
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from billos import BillOS, BillOSError, OPERATIONS, SURFACE, verify_webhook_signature  # noqa: E402
+
+
+class Fake:
+    def __init__(self, handler):
+        self.calls = []
+        self.handler = handler
+
+    def __call__(self, method, url, headers, body, timeout):
+        self.calls.append((method, url, headers, body))
+        status, hdrs, data = self.handler(method, url, headers, body, len(self.calls))
+        h = {"content-type": "application/json", "x-request-id": "req-1"}
+        h.update(hdrs)
+        return status, h, data if isinstance(data, bytes) else json.dumps(data).encode()
+
+
+class ClientTests(unittest.TestCase):
+    def test_call_shape(self):
+        fake = Fake(lambda *a: (200, {}, {"ok": True, "documents": []}))
+        c = BillOS("bk_test_abc", base_url="https://x.test/v1/", transport=fake)
+        out = c.documents.list("biz 1", {"status": "issued", "take": 5, "from": None})
+        method, url, headers, body = fake.calls[0]
+        self.assertEqual(url, "https://x.test/v1/businesses/biz%201/documents?status=issued&take=5")
+        self.assertEqual(method, "GET")
+        self.assertEqual(headers["X-Api-Key"], "bk_test_abc")
+        self.assertEqual(out["documents"], [])
+        self.assertEqual(out["request_id"], "req-1")
+
+    def test_create_sends_json_and_idempotency_key(self):
+        fake = Fake(lambda *a: (201, {}, {"ok": True, "document": {"id": "d1"}}))
+        c = BillOS("k", transport=fake)
+        c.documents.create("b1", {"docType": 400, "payments": [{"method": 1, "amount": 100}]}, idempotency_key="order-1")
+        _, _, headers, body = fake.calls[0]
+        self.assertEqual(headers["Idempotency-Key"], "order-1")
+        self.assertEqual(headers["Content-Type"], "application/json")
+        self.assertEqual(json.loads(body)["docType"], 400)
+        with self.assertRaisesRegex(TypeError, 'missing path parameter "bid"'):
+            c.documents.get("", "x")
+        self.assertEqual(len(fake.calls), 1)
+
+    def test_error_shape(self):
+        fake = Fake(lambda *a: (404, {"x-request-id": "req-404"}, {"error": "not found", "reason": "not_found"}))
+        c = BillOS("k", transport=fake)
+        with self.assertRaises(BillOSError) as cm:
+            c.businesses.get("nope")
+        e = cm.exception
+        self.assertEqual((e.status, e.reason, e.request_id, e.retryable), (404, "not_found", "req-404", False))
+        # a network failure is transient too
+        def boom(*a):
+            raise OSError("dns")
+        with self.assertRaises(BillOSError) as cm2:
+            BillOS("k", transport=boom, max_retries=0).documents.issue("b", "d")
+        self.assertTrue(cm2.exception.retryable and cm2.exception.status == 0)
+
+    def test_retries(self):
+        slept = []
+        state = {"n": 0}
+
+        def h(*a):
+            state["n"] += 1
+            return (429, {"retry-after": "0"}, {"error": "slow", "reason": "rate_limited"}) if state["n"] == 1 else (200, {}, {"ok": True, "businesses": []})
+        fake = Fake(h)
+        c = BillOS("k", transport=fake, sleep=slept.append)
+        self.assertTrue(c.businesses.list()["ok"])
+        self.assertEqual(len(fake.calls), 2)
+        # a POST without an idempotency key is never retried
+        fake2 = Fake(lambda *a: (502, {}, {"error": "x", "reason": "provider"}))
+        c2 = BillOS("k", transport=fake2, sleep=slept.append)
+        with self.assertRaises(BillOSError) as cm:
+            c2.documents.issue("b", "d")
+        self.assertTrue(cm.exception.retryable)
+        self.assertEqual(len(fake2.calls), 1)
+        # with one, it is
+        state["n"] = 0
+        fake3 = Fake(lambda m, u, hh, b, n: (502, {}, {"error": "x", "reason": "provider"}) if n == 1 else (201, {}, {"ok": True, "document": {}}))
+        c3 = BillOS("k", transport=fake3, sleep=slept.append)
+        c3.documents.create("b", {"docType": 400}, idempotency_key="k1")
+        self.assertEqual(len(fake3.calls), 2)
+
+    def test_binary_and_ocr(self):
+        pdf = b"%PDF-1.7"
+
+        def h(method, url, headers, body, n):
+            if url.endswith("/prints"):
+                return 200, {"content-type": "application/pdf", "x-print-variant": "origin"}, pdf
+            return 201, {}, {"ok": True, "expense": {"id": "e1"}}
+        fake = Fake(h)
+        c = BillOS("k", transport=fake)
+        out = c.documents.print("b", "d")
+        self.assertEqual((out.bytes, out.content_type, out.variant), (pdf, "application/pdf", "origin"))
+        self.assertEqual(json.loads(fake.calls[0][3])["kind"], "auto")
+        c.expenses.ocr("b", b"\x01\x02", mime="image/png")
+        _, url, headers, body = fake.calls[1]
+        self.assertEqual(headers["Content-Type"], "image/png")
+        self.assertEqual(body, b"\x01\x02")
+        self.assertTrue(url.endswith("/businesses/b/expenses/ocr"))
+
+    def test_surface_covers_every_generated_operation(self):
+        c = BillOS("k", transport=Fake(lambda *a: (200, {}, {"ok": True})))
+        for op, where in SURFACE.items():
+            ns, fn = where.split(".")
+            self.assertTrue(callable(getattr(getattr(c, ns), fn)), f"{op} -> {where}")
+        self.assertEqual(set(SURFACE), set(OPERATIONS))
+        self.assertEqual(len(set(SURFACE.values())), len(SURFACE))
+
+    def test_webhook_signature(self):
+        secret, body = "whsec_test", b'{"id":"del_1"}'
+        t = int(time.time())
+        v1 = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
+        self.assertTrue(verify_webhook_signature(secret, f"t={t},v1={v1}", body))
+        self.assertFalse(verify_webhook_signature(secret, f"t={t},v1={v1}", body + b" "))
+        self.assertFalse(verify_webhook_signature(secret, f"t={t - 1000},v1={v1}", body))
+        self.assertFalse(verify_webhook_signature(secret, "garbage", body))
+        self.assertFalse(verify_webhook_signature(secret, f"t={t},v1=abc\u05d0", body), "non-ASCII in the header is a False, not a crash")
+        with self.assertRaises(TypeError):
+            verify_webhook_signature(secret, f"t={t},v1={v1}", {"id": "del_1"})
+
+
+if __name__ == "__main__":
+    unittest.main()