norbix 1.1.0__tar.gz

norbix-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main, next, beta]
+
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --all-groups
+      - name: Lint
+        run: uv run ruff check .
+      - name: Typecheck
+        run: uv run mypy src
+      - name: Test
+        run: uv run pytest

norbix-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  push:
+    branches: [main, next, beta]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Test before release
+        run: |
+          uv run pytest
+
+      - name: Bootstrap initial semantic-release tag
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if ! git tag -l "v*" | grep -q .; then
+            echo "No semantic-release tags found. Bootstrapping v0.0.0"
+            git tag v0.0.0
+            git push origin v0.0.0
+          else
+            echo "Existing semantic-release tags found. Skipping bootstrap."
+          fi
+
+      - name: Semantic release version
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run semantic-release version
+
+      - name: Publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if ls dist/*.whl >/dev/null 2>&1; then
+            uv publish --token "$PYPI_TOKEN" dist/*
+          else
+            echo "No new release artifacts produced; skipping PyPI publish."
+          fi

norbix-1.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.pyc
+scripts/sync_types.py

norbix-1.1.0/ArchitectOverview.md

@@ -0,0 +1,142 @@
+# Architect Overview — norbix-python SDK
+
+> Author role: Python Architect (20+ years).
+> Scope: developer UX of the Python SDK — how config is initiated, how the library feels when imported and used in real scripts.
+> Reviewed paths: `src/norbix_python/__init__.py`, `src/norbix_python/client.py`, `src/norbix_python/transport.py`, `src/norbix_python/errors.py`, `src/norbix_python/api/*.py`, `src/norbix_python/hub/*.py`, `tests/*.py`, `pyproject.toml`, `README.md`.
+
+---
+
+## Suggestions list (sorted by impact)
+
+### Naming and Python idioms
+
+1. **Method names are camelCase, not snake_case.** `findOne`, `getDatabaseSchemas`, `deleteMany` look like JavaScript / C#. Python community uses `find_one`, `get_database_schemas`, `delete_many`. PyMongo, boto3, requests, stripe, openai — all use snake_case. This is the single biggest UX issue.
+2. **`LoginCredentials` fields use camelCase (`userName`).** Should be `user_name` with a serialization alias for the wire format.
+3. **Module class names like `DatabaseModule` are noisy.** `Database`, `Files`, `Ai` is enough. Users do not write these names anyway.
+
+### API ergonomics — the "import and use" feeling
+
+4. **Every method takes one big `dict[str, Any]`.** No autocomplete, no type hints, no IDE help. User cannot tell which keys are path parameters, which are query, which are body.
+   - Now: `db.findOne({"collectionName": "orders", "id": "123"})`
+   - Better: `db.find_one("orders", id="123")` or `db.collection("orders").find_one("123")`
+5. **No fluent / resource-oriented API.** Best Python SDKs feel like: `s3.objects("bucket").list()`, `db["orders"].find_one(id)`. Norbix forces you to build a dict every call.
+6. **Return type is always `Any`.** README itself shows the pain:
+   ```python
+   items = response.get("results", []) if isinstance(response, dict) else []
+   ```
+   This is a code smell. Return Pydantic models or at minimum `TypedDict`.
+7. **No `download()` / `upload()` / `execute()` style methods.** The `db.FindAll()`, `files.Download()`, `code.Execute()` style is missing. `hub/files.py` only has trigger and integration management (`enableFiles`, `saveFilesIntegration`). There is no real file upload / download / list. There is no `code.execute()` module at all.
+
+### Configuration / initialization UX
+
+8. **Env variables are supported (good).** `NORBIX_PROJECT_ID`, `NORBIX_API_KEY`, etc. are read in `src/norbix_python/client.py` lines 42–54. This part is solid.
+9. **No `.env` auto-loading.** Most modern SDKs (or their docs) suggest `python-dotenv`. The README does not mention it.
+10. **No global / default client pattern.** OpenAI and stripe let you do `stripe.api_key = "..."` then `stripe.Customer.list()`. Norbix forces explicit `Norbix(...)` every time. For scripts, a module-level client is friendlier.
+11. **`project_id` always required.** Even for endpoints that don't need it (`/auth`). This forces users to set it before login is even possible, which is strange.
+12. **API key and bearer token are mixed under one `Authorization: Bearer` header** (`transport.py` line 74). Most APIs use `Authorization: ApiKey ...` or a separate header for API keys. Mixing them is unclear and risky.
+
+### Architecture / safety
+
+13. **Path parameters are extracted from the request dict by string matching** (`_build_url_and_body`, `transport.py` lines 115–144). This is "magic" — caller does not know which keys vanish from the body. Case-insensitive lookup (`_lookup_case_insensitive`, lines 147–154) makes it worse: `id` and `Id` collide silently.
+14. **Private attribute mutation.** `client.py` line 81 does `self._transport._cfg.bearer_token = str(...)` — touching a private field. The `set_bearer_token()` method already exists (line 87) but `login()` does not use it. Inconsistent.
+15. **`NorbixError` is a `@dataclass` AND an `Exception`.** This works in Python 3.10+ but is fragile — `Exception.__init__` is bypassed. A normal class with `__init__` calling `super().__init__(message)` is safer.
+16. **No `__enter__` / `__exit__`** on `Norbix`. Should support `with Norbix(...) as client:` so the underlying `httpx.Client` is closed automatically.
+17. **No async client.** `httpx` already gives you `AsyncClient`. Modern Python SDKs ship `AsyncNorbix` for free.
+18. **No retries, no backoff, no rate-limit handling.** Stripe's SDK retries idempotent calls automatically.
+19. **No pagination helper.** `find()` returns `{"results": [...]}` but the user has to handle `skip`/`take` themselves. An iterator (`for order in db.orders.iter_all()`) is the standard.
+
+### Tests / docs
+
+20. **Only 3 tests in `tests/test_client.py`.** Coverage of modules (`database`, `files`, `ai`) is zero. The boilerplate of every method is identical — one parametrized test would cover all of them.
+21. **README example uses `getCurrentUser({})`** but this method is not in `src/norbix_python/api/membership.py`. Either the doc is stale or the method is missing.
+22. **`per-file-ignores` in `pyproject.toml`** (lines 47–50) disables `E501` and `I001` for all generated modules. This hides real issues. Generated code should still be linted.
+
+---
+
+## Summary
+
+The SDK is a thin, generated wrapper over the HTTP API. The transport layer (`src/norbix_python/transport.py`) is clean and the env-variable support in `src/norbix_python/client.py` (lines 42–54) is well done. The **biggest weakness is developer UX** — the SDK feels like a TypeScript library translated to Python rather than a Python library. A senior Python developer using this for the first time will not feel "at home".
+
+### Where it hurts most — config initiation
+
+The env-variable story is fine, but the constructor surface in `src/norbix_python/client.py` (lines 27–65) is wide (10+ parameters). A user who only wants `Norbix()` from `.env` is fine, but a user who wants explicit credentials has to pass several keyword arguments. Splitting into `Norbix.from_env()` and `Norbix(api_key=..., project_id=...)` would clarify intent. Adding a top-level helper like:
+
+```python
+import norbix
+norbix.configure(api_key="sk_live_...", project_id="proj_123")
+norbix.db.find_all("orders")
+```
+
+would match the OpenAI / stripe style users expect.
+
+### Where it hurts most — calling style
+
+The request style `db.FindAll()`, `files.Download()`, `code.Execute()` is not possible today.
+
+Today (from `README.md` lines 46–53):
+
+```python
+response = norbix.api.database.find(
+    {"collectionName": "orders", "take": 20, "skip": 0,
+     "orderBy": [{"field": "createdAt", "direction": "desc"}]}
+)
+items = response.get("results", []) if isinstance(response, dict) else []
+```
+
+What it should look like (PyMongo / stripe style):
+
+```python
+orders = norbix.db("orders").find_all(take=20, order_by="-createdAt")
+for order in orders:
+    print(order.id)
+```
+
+The current style is caused by `src/norbix_python/api/database.py` lines 143–153 where `find` accepts only a dict and returns `Any`. The dict-only signature comes from the code generator. To fix this without rewriting the generator, add a thin **hand-written facade layer** on top of the generated modules — for example `src/norbix_python/db.py` exposing `Collection.find_all()`, `find_one()`, `insert_one()` with typed kwargs, calling the generated `database.find(...)` underneath.
+
+### File operations are missing
+
+`src/norbix_python/hub/files.py` only manages triggers and integrations (`enableFiles`, `saveFilesIntegration`, lines 23–177). There is no `upload()`, `download()`, `list()`, `delete_object()`. If the backend supports file storage, the SDK is not exposing it. If it does not, then the module name `files` is misleading.
+
+### Path parameter handling is magical
+
+`transport.py` lines 121–134 walks the URL template and pulls keys from the request dict — case-insensitive (`_lookup_case_insensitive`, lines 147–154). The user has no way to tell from the method signature `database.findOne(request)` which dict keys are path parameters (`collectionName`, `id`) and which are body. Promote them to explicit positional arguments in the generated code:
+
+```python
+def find_one(self, collection_name: str, id: str, *, timeout: float | None = None) -> Any:
+    ...
+```
+
+### Auth state is leaky
+
+`client.py` line 81 writes directly to `self._transport._cfg.bearer_token` — bypassing `set_bearer_token()` (line 87) which exists for exactly this. Replace with `self.set_bearer_token(str(result["bearerToken"]))`. Also, `transport.py` line 74 sends `api_key` as `Authorization: Bearer ...` together with JWT tokens — most APIs separate these. Add a clear header strategy.
+
+### Errors swallow detail
+
+`NorbixError` (`src/norbix_python/errors.py`) is a `@dataclass(Exception)`. It works but is fragile. Convert to a normal exception class with `super().__init__(message)`, keep `code`, `status`, `details` as attributes, and add subclasses (`AuthenticationError`, `RateLimitError`, `NotFoundError`, `ValidationError`) so users can write:
+
+```python
+try:
+    norbix.db.find_one("orders", id="123")
+except NotFoundError:
+    ...
+except RateLimitError:
+    ...
+```
+
+like in stripe and openai SDKs.
+
+### Quality of the plan / generation pipeline
+
+The architecture (one `Transport` + one module per resource + namespaces `api` / `hub`) is reasonable and extendable. The `pyproject.toml` is professional — `ruff`, `mypy --strict`, `pytest`, semantic-release. But `tool.ruff.lint.per-file-ignores` (lines 47–50) silences linting for the generated modules — that hides bugs in the very code most users will read.
+
+---
+
+## Top 5 actions, in order
+
+1. **Rename methods to snake_case in the generator.** This alone removes 80% of the "this feels foreign" feeling.
+2. **Promote path parameters to explicit function arguments.** Stop reading them out of the request dict.
+3. **Add a hand-written facade** for the most-used resources: `db.collection("orders").find_all()`, `files.upload(path)`, etc. — backed by the generated code.
+4. **Return typed objects (Pydantic v2 models)**, since you already require Python 3.10+. Stop returning `Any`.
+5. **Add `__enter__`/`__exit__`, an `AsyncNorbix`, and basic retries on idempotent verbs.**
+
+If you do these five, the SDK will feel like a first-class Python library and not a generated transport.

norbix-1.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.1.0 (2026-04-28)
+
+### Features
+
+- **pypi**: Rename distribution package to norbix
+  ([`2ab5e75`](https://github.com/norbix-code/sdk-python/commit/2ab5e7508f5b465f1b81add49191213c9440a252))
+
+
+## v1.0.2 (2026-04-28)
+
+### Bug Fixes
+
+- **ci**: Publish python package to pypi via uv
+  ([`3ec7ba5`](https://github.com/norbix-code/sdk-python/commit/3ec7ba58c5c0e2ee27330696f022cc251e2068cd))
+
+
+## v1.0.1 (2026-04-28)
+
+### Bug Fixes
+
+- **ci**: Run semantic-release publish after version
+  ([`6deb16d`](https://github.com/norbix-code/sdk-python/commit/6deb16dec02d2c739e216c5a82b72078acdebf7a))
+
+
+## v1.0.0 (2026-04-28)
+
+### Bug Fixes
+
+- Normalize generated python imports for ruff
+  ([`3bb658a`](https://github.com/norbix-code/sdk-python/commit/3bb658a47c96df81825e0cd38cbd418adbcab3e3))
+
+- Trigger initial pypi publish
+  ([`9d32ddc`](https://github.com/norbix-code/sdk-python/commit/9d32ddcf604920b2ecac84d59f5b5d574071f7c6))
+
+- **ci**: Use semantic-release version for pypi publishing
+  ([`d2a4a81`](https://github.com/norbix-code/sdk-python/commit/d2a4a816b33ad0c0144fdeacee556a74f35efece))
+
+### Continuous Integration
+
+- Normalize generated python modules before drift check
+  ([`4e8d920`](https://github.com/norbix-code/sdk-python/commit/4e8d9200d8792b6c5569f71bb18b18267b41e071))
+
+- Remove endpoint generation from python pipeline
+  ([`aae4e66`](https://github.com/norbix-code/sdk-python/commit/aae4e66d47380c476f79f139f78658642bd8257e))
+
+### Features
+
+- Split python clients into api and hub surfaces
+  ([`3864f46`](https://github.com/norbix-code/sdk-python/commit/3864f4623ed33c959785cf757c0588eac305ddf1))
+
+
+## v0.0.0 (2026-04-28)
+
+- Initial Release

norbix-1.1.0/LICENSE

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

norbix-1.1.0/Makefile

@@ -0,0 +1,37 @@
+PYTHON := python
+UV := uv
+
+.PHONY: help sync install lint typecheck test check build release-dry
+
+help:
+	@echo "Available targets:"
+	@echo "  make install           - install all dependencies with uv"
+	@echo "  make sync              - alias for install"
+	@echo "  make lint              - run ruff"
+	@echo "  make typecheck         - run mypy"
+	@echo "  make test              - run pytest"
+	@echo "  make check             - run lint + typecheck + tests"
+	@echo "  make build             - build wheel/sdist"
+	@echo "  make release-dry       - semantic-release dry run (no publish)"
+
+install:
+	$(UV) sync --all-groups
+
+sync: install
+
+lint:
+	$(UV) run ruff check .
+
+typecheck:
+	$(UV) run mypy src
+
+test:
+	$(UV) run pytest
+
+check: lint typecheck test
+
+build:
+	$(UV) build
+
+release-dry:
+	$(UV) run semantic-release --noop version

norbix-1.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: norbix
+Version: 1.1.0
+Summary: Official Python SDK for Norbix — split API and Hub clients with flat module access.
+Project-URL: Homepage, https://norbix.dev
+Project-URL: Repository, https://github.com/norbix-dev/norbix-python
+Project-URL: Issues, https://github.com/norbix-dev/norbix-python/issues
+Author: UAB Isidos
+License: MIT
+License-File: LICENSE
+Keywords: api,baas,hub,norbix,python,sdk
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# norbix-python
+
+[![CI](https://github.com/norbix-dev/norbix-python/actions/workflows/ci.yml/badge.svg)](https://github.com/norbix-dev/norbix-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/norbix.svg)](https://pypi.org/project/norbix/)
+[![Python](https://img.shields.io/badge/python-%3E=3.10-blue)](https://python.org)
+[![License](https://img.shields.io/pypi/l/norbix.svg)](./LICENSE)
+
+Official Python SDK for [Norbix](https://norbix.dev).
+Use split clients with flat module access:
+
+- `NorbixApi` for API scope (`client.database`, `client.membership`, ...)
+- `NorbixHub` for Hub scope (`client.database`, `client.account`, ...)
+
+## Install
+
+```bash
+uv add norbix
+```
+
+Optional: load `.env` in apps with `python-dotenv` (`load_dotenv()` before constructing `Norbix()`).
+
+## Quickstart
+
+```python
+from norbix_python import NorbixApi
+
+# Service mode
+norbix = NorbixApi(api_key="<api_key>", project_id="proj_123")
+
+norbix.database.find("orders", take=20, skip=0, orderBy=[{"field": "createdAt", "direction": "desc"}])
+```
+
+```python
+# User mode
+from norbix_python import LoginCredentials, NorbixApi
+
+norbix = NorbixApi(project_id="proj_123")
+norbix.login(LoginCredentials(user_name="alice@team.io", password="secret"))
+norbix.database.find("orders", take=10)
+```
+
+### Async client
+
+```python
+from norbix_python import AsyncNorbix
+
+async def main() -> None:
+    async with AsyncNorbix(api_key="...", project_id="proj_123") as client:
+        await client.api.echo.echo()
+
+# asyncio.run(main())
+```
+
+## Real-world examples
+
+### 1) List recent orders (API scope)
+
+```python
+from norbix_python import DatabaseFindResult, NorbixApi, NorbixError
+
+norbix = NorbixApi(api_key="sk_live_xxx", project_id="proj_123")
+
+try:
+    raw = norbix.database.find("orders", take=20, skip=0, orderBy=[{"field": "createdAt", "direction": "desc"}])
+    typed = DatabaseFindResult.model_validate(raw) if isinstance(raw, dict) else DatabaseFindResult()
+    items = typed.results
+    print(f"Fetched {len(items)} orders")
+except NorbixError as exc:
+    print(exc.code, exc.status, exc.message)
+```
+
+### 2) Login as user and load profile
+
+```python
+from norbix_python import LoginCredentials, NorbixApi
+
+norbix = NorbixApi(project_id="proj_123")
+
+auth = norbix.login(LoginCredentials(user_name="alice@team.io", password="secret"))
+print("Logged in, token prefix:", str(auth.get("bearerToken", ""))[:16])
+
+users = norbix.membership.get_users()
+print("Users response:", users)
+```
+
+### 3) Account-scoped Hub call (requires account_id)
+
+```python
+from norbix_python import NorbixHub
+
+norbix = NorbixHub(
+    api_key="sk_live_xxx",
+    project_id="proj_123",
+    account_id="acc_456",  # required for account-scoped endpoints
+)
+
+account = norbix.hub.account.get_account_profile()
+print(account)
+```
+
+## Breaking changes (recent major-style refresh)
+
+- Methods use **snake_case** (`find_one`, `get_database_schemas`) instead of camelCase.
+- Path parameters are **positional or keyword** arguments (for example `find("orders", ...)`,
+  `find_one("orders", id)`). Remaining query/body fields are passed as keyword args.
+- Use **typed errors** where helpful: `AuthenticationError`, `NotFoundError`, `RateLimitError`,
+  `ValidationError` (all subclass `NorbixError`).
+
+## Authentication
+
+- API key: set `api_key` or `NORBIX_API_KEY`
+- JWT bearer: set `bearer_token`, `NORBIX_BEARER_TOKEN`, or call `norbix.login(...)`
+- If both are configured, bearer token wins
+- If neither is configured, SDK raises `NORBIX_NOT_AUTHENTICATED`
+
+API keys and JWTs are sent as `Authorization: Bearer ...` (document your backend expectations).
+
+## Configuration from environment
+
+```bash
+NORBIX_API_KEY=sk_live_...
+NORBIX_PROJECT_ID=proj_123
+NORBIX_ACCOUNT_ID=acc_456
+NORBIX_API_URL=https://api.norbix.ai
+NORBIX_HUB_URL=https://hub.norbix.ai
+```
+
+```python
+norbix = NorbixApi()  # reads from environment when values omitted
+```
+
+## Project vs account scope
+
+- `project_id` is required (set explicitly or via env).
+- `account_id` is optional
+- Account-scoped Hub methods raise `NORBIX_ACCOUNT_SCOPE_REQUIRED` if `account_id` is not configured
+
+## SDK maintenance
+
+Regenerate API and Hub modules from DTO stubs:
+
+```bash
+uv run python scripts/generate_endpoints.py
+```
+
+This refreshes `src/norbix_python/api/`, `hub/`, matching tests under `tests/api` and `tests/hub`, and docs under `docs/`.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```
+
+## Releases
+
+Pushes to `main`, `next`, and `beta` run
+[python-semantic-release](https://python-semantic-release.readthedocs.io/)
+and publish to PyPI.
+
+## License
+
+MIT