aranova-tracking 0.1.0__tar.gz

aranova_tracking-0.1.0/LICENSE

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

aranova_tracking-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: aranova-tracking
+Version: 0.1.0
+Summary: Typed Python client for the Aranova tracking API (sales, customers, calendar, config).
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aranova,tracking,sales,analytics,sdk
+Author: Aranova
+Author-email: ritesh@aranova.io
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Intended Audience :: Developers
+Requires-Dist: httpx (>=0.27,<1)
+Requires-Dist: pydantic[email] (>=2.7,<3)
+Requires-Dist: tenacity (>=8,<10)
+Project-URL: Homepage, https://aranova.io
+Description-Content-Type: text/markdown
+
+# aranova-tracking
+
+Typed Python client for the Aranova tracking API — record sales, read the ledger and
+customer roster, manage calendar bookings, and fetch a business's tracking config from
+your own backend.
+
+```bash
+pip install aranova-tracking
+```
+
+## Quick start
+
+```python
+import os
+from aranova_tracking import AranovaTracking
+from aranova_tracking.models import SaleCreateSchema
+
+with AranovaTracking(os.environ["ARANOVA_TRACKING_SECRET_KEY"]) as aranova:
+    sale = aranova.tracking_sales.record_sale(
+        SaleCreateSchema(
+            external_id="order-1042",      # your id — makes this call idempotent
+            currency="CAD",
+            amount_total_cents=12_000,     # minor units: $120.00
+            occurred_at="2026-09-09T14:03:00Z",
+            customer_phone="+14165550123",
+        )
+    )
+    print(sale.id)
+```
+
+Async is the same surface:
+
+```python
+from aranova_tracking import AsyncAranovaTracking
+
+async with AsyncAranovaTracking(secret_key) as aranova:
+    page = await aranova.tracking_sales.query_sales(...)
+```
+
+## Your API key
+
+Use a **secret** key (`aranv_sk_…`), issued per business in the Aranova dashboard, and
+keep it in server-side env only. A public key (`aranv_pk_…`) authenticates but may only
+*create* sales — every read returns 403. Never ship either key in a browser bundle.
+
+## Idempotency
+
+`external_id` is your dedup handle. Send the same one twice and the second call returns
+the **existing** sale with HTTP 200 instead of creating a duplicate (a fresh create is
+201). Omit it and there is no dedup at all — a retried request writes a second sale.
+
+## Errors
+
+Every failure raises a subclass of `AranovaAPIError` carrying a stable `code`, the
+`request_id` to quote when reporting a problem, and any extra `context`:
+
+```python
+from aranova_tracking import AranovaAPIError, RateLimitError, ValidationError
+
+try:
+    aranova.tracking_sales.record_sale(payload)
+except ValidationError as exc:
+    print(exc.errors)          # per-field failures
+except RateLimitError as exc:
+    print(exc.retry_after)     # seconds, from the server
+except AranovaAPIError as exc:
+    print(exc.code, exc.request_id)
+```
+
+Branch on `exc.code`, never on the message text — prose is free to change, codes are
+contract. Transport failures, 429s and 5xx are retried automatically with exponential
+backoff; 4xx you must fix are raised immediately.
+
+## Models are real Pydantic
+
+`aranova_tracking.models` is generated from the API's own schemas, so the models are
+genuine `pydantic.BaseModel` classes — usable directly as a FastAPI `response_model`,
+and they validate. They also tolerate unknown fields, so a client pinned to an older
+release keeps working when the API adds one.
+
+## Versioning
+
+Semantic versioning on the wire contract: a new optional field is a patch, a new
+endpoint a minor, and anything removed or retyped a major. Pin a major
+(`aranova-tracking = "^1.0"`) and upgrade on your own schedule.
+
+---
+
+Generated from `apps/api/openapi.json`; `models.py` and `_endpoints.py` are build
+artifacts — see `docs/runbooks/python-sdk.md` in the monorepo.
+

aranova_tracking-0.1.0/README.md

@@ -0,0 +1,90 @@
+# aranova-tracking
+
+Typed Python client for the Aranova tracking API — record sales, read the ledger and
+customer roster, manage calendar bookings, and fetch a business's tracking config from
+your own backend.
+
+```bash
+pip install aranova-tracking
+```
+
+## Quick start
+
+```python
+import os
+from aranova_tracking import AranovaTracking
+from aranova_tracking.models import SaleCreateSchema
+
+with AranovaTracking(os.environ["ARANOVA_TRACKING_SECRET_KEY"]) as aranova:
+    sale = aranova.tracking_sales.record_sale(
+        SaleCreateSchema(
+            external_id="order-1042",      # your id — makes this call idempotent
+            currency="CAD",
+            amount_total_cents=12_000,     # minor units: $120.00
+            occurred_at="2026-09-09T14:03:00Z",
+            customer_phone="+14165550123",
+        )
+    )
+    print(sale.id)
+```
+
+Async is the same surface:
+
+```python
+from aranova_tracking import AsyncAranovaTracking
+
+async with AsyncAranovaTracking(secret_key) as aranova:
+    page = await aranova.tracking_sales.query_sales(...)
+```
+
+## Your API key
+
+Use a **secret** key (`aranv_sk_…`), issued per business in the Aranova dashboard, and
+keep it in server-side env only. A public key (`aranv_pk_…`) authenticates but may only
+*create* sales — every read returns 403. Never ship either key in a browser bundle.
+
+## Idempotency
+
+`external_id` is your dedup handle. Send the same one twice and the second call returns
+the **existing** sale with HTTP 200 instead of creating a duplicate (a fresh create is
+201). Omit it and there is no dedup at all — a retried request writes a second sale.
+
+## Errors
+
+Every failure raises a subclass of `AranovaAPIError` carrying a stable `code`, the
+`request_id` to quote when reporting a problem, and any extra `context`:
+
+```python
+from aranova_tracking import AranovaAPIError, RateLimitError, ValidationError
+
+try:
+    aranova.tracking_sales.record_sale(payload)
+except ValidationError as exc:
+    print(exc.errors)          # per-field failures
+except RateLimitError as exc:
+    print(exc.retry_after)     # seconds, from the server
+except AranovaAPIError as exc:
+    print(exc.code, exc.request_id)
+```
+
+Branch on `exc.code`, never on the message text — prose is free to change, codes are
+contract. Transport failures, 429s and 5xx are retried automatically with exponential
+backoff; 4xx you must fix are raised immediately.
+
+## Models are real Pydantic
+
+`aranova_tracking.models` is generated from the API's own schemas, so the models are
+genuine `pydantic.BaseModel` classes — usable directly as a FastAPI `response_model`,
+and they validate. They also tolerate unknown fields, so a client pinned to an older
+release keeps working when the API adds one.
+
+## Versioning
+
+Semantic versioning on the wire contract: a new optional field is a patch, a new
+endpoint a minor, and anything removed or retyped a major. Pin a major
+(`aranova-tracking = "^1.0"`) and upgrade on your own schedule.
+
+---
+
+Generated from `apps/api/openapi.json`; `models.py` and `_endpoints.py` are build
+artifacts — see `docs/runbooks/python-sdk.md` in the monorepo.

aranova_tracking-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "aranova-tracking"
+version = "0.1.0"
+description = "Typed Python client for the Aranova tracking API (sales, customers, calendar, config)."
+readme = "README.md"
+requires-python = ">=3.11"  # http.HTTPMethod needs 3.11; 3.10 hits EOL Oct 2026 anyway
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Aranova", email = "ritesh@aranova.io" }]
+keywords = ["aranova", "tracking", "sales", "analytics", "sdk"]
+classifiers = [
+  # No "License ::" classifier: PEP 639 deprecates them, and `license` above is
+  # the authoritative SPDX expression.
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Intended Audience :: Developers",
+]
+dependencies = [
+  "httpx (>=0.27,<1)",
+  # `email` extra: generated models use EmailStr, which needs it at import time.
+  "pydantic[email] (>=2.7,<3)",
+  "tenacity (>=8,<10)",
+]
+
+[project.urls]
+# The repository is private; point the public listing at the company site.
+Homepage = "https://aranova.io"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "aranova_tracking", from = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.4"
+pytest-asyncio = "^0.25.3"
+respx = "^0.22.0"
+ruff = "^0.15.5"
+mypy = "^1.15.0"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+# Generated: names and unions are the generator's, not ours to restyle.
+"src/aranova_tracking/models.py" = ["E501", "UP", "RUF"]
+"src/aranova_tracking/_endpoints.py" = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+# The two generated modules, each suppressing exactly one code with a reason.
+# `models`: datamodel-code-generator emits defaults mypy reads as incompatible.
+# `_endpoints`: the transport returns Any, but `_parse` validates to the declared
+# model at runtime, so the annotation is true even though mypy cannot infer it.
+[[tool.mypy.overrides]]
+module = "aranova_tracking.models"
+disable_error_code = ["assignment"]
+
+[[tool.mypy.overrides]]
+module = "aranova_tracking._endpoints"
+disable_error_code = ["no-any-return"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "integration: needs a live API (ARANOVA_TEST_BASE_URL/SECRET_KEY); skipped by default",
+]
+# `test_transport.py` (respx-mocked) always runs. Integration tests are opt-in
+# so a bare `poetry run pytest` never needs a running server: CI passes `-m integration`.
+addopts = "-m 'not integration'"

aranova_tracking-0.1.0/src/aranova_tracking/__init__.py

@@ -0,0 +1,34 @@
+"""Typed Python client for the Aranova tracking API.
+
+Import models from `aranova_tracking.models` — they are real Pydantic v2 models
+generated from the API's own schemas, so a FastAPI service can reuse them directly
+as a `response_model`.
+"""
+
+from aranova_tracking.client import AranovaTracking, AsyncAranovaTracking
+from aranova_tracking.errors import (
+    AranovaAPIError,
+    AranovaError,
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AranovaAPIError",
+    "AranovaError",
+    "AranovaTracking",
+    "AsyncAranovaTracking",
+    "AuthenticationError",
+    "ConflictError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ValidationError",
+    "__version__",
+]