b1sl-python 0.3.0__tar.gz → 0.4.0__tar.gz

b1sl_python-0.4.0/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`b1sl-python` — an async-first, metadata-driven Python SDK for the SAP Business One Service Layer (OData v4). Published to PyPI. Optional `saphdb` subpackage wraps SAP HANA via `hdbcli`.
+
+## Tooling and commands
+
+- **Package manager: `uv` exclusively.** `uv sync` (or `uv sync --all-extras --dev`) for installs. The venv lives at `.venv/`.
+- **Python: 3.11–3.12** (`requires-python = ">=3.11,<3.13"`).
+- Common targets (see `Makefile`):
+  - `make test` — unit tests only, no network (`pytest -m "not (integration or vcr)"`).
+  - `make test-vcr` — replay recorded cassettes offline (`--record-mode=none`). Requires the `vcr` marker.
+  - `make test-record` — re-record cassettes against a real SAP server. Requires `.env`.
+  - `make test-demo` — live integration tests, `APP_ENV=demo`, requires `.env`.
+  - `make test-ci` — full CI suite with coverage XML.
+  - `make lint` — `ruff check .` + `mypy .` (CI parity).
+- **Single test**: `PYTHONPATH=src:. .venv/bin/pytest tests/unit/test_odata_builder.py::test_name -xvs`. The `PYTHONPATH=src:.` prefix matters — the package lives at `src/b1sl/` and tests import via `b1sl.b1sl.…`.
+- CI (`.github/workflows/ci.yml`) runs only `uv run ruff check .` + `uv run pytest tests/unit/`. `mypy` is enforced locally via `make lint`, not in CI.
+- Release: `make release v=X.Y.Z` commits, tags, pushes; `publish.yml` then publishes to PyPI on tag.
+
+## Architecture
+
+### Three-layer model code: generated / overrides / entities
+
+The SDK is **metadata-driven**. Most of `src/b1sl/b1sl/models/` and `src/b1sl/b1sl/resources/` is autogenerated from SAP's OData `$metadata` XML, service document JSON, and API reference HTML (sources versioned under `metadata/<version>/`).
+
+- `models/_generated/`, `resources/_generated/` — **NEVER edit**. Wiped on every regeneration. Any structural fix belongs in the generator at `scripts/b1sl_metadata_generator/` (run via `./scripts/generate_models.sh <version>`).
+- `models/_overrides/` — hand-written extensions, calculated properties, `model_rebuild()` calls, metadata quirk fixes.
+- `entities/__init__.py` — the public facade. Blends generated + overridden models. **All public consumption goes through `from b1sl.b1sl import entities as en`**, never from `_generated/` directly.
+
+Production metadata should not be committed: place it as `metadata/<version>/metadata_document.real.xml` / `service_document.real.json`. The generator prioritizes `.real.*` over the public files; `.real.*` is gitignored.
+
+### `B1Model` base class
+
+Every entity inherits from `B1Model` (`models/base.py`), which provides:
+- Boolean coercion (SAP `"tYES"`/`"tNO"` ↔ Python `bool`).
+- Date handling (`/Date(ms)/` ↔ `date`).
+- `.to_api_payload()` uses `exclude_unset=True` — this is the foundation of the **Surgical Delta** pattern. PATCH payloads must contain only the fields the caller explicitly set; never `GET` an entity and resend it.
+- `.udfs` proxy: mapping-like accessor for User-Defined Fields. **Enforces the `U_` prefix** to prevent overwriting SAP core fields.
+
+### Elite vs Generic resource access
+
+The client exposes ~16 "Elite" aliases as direct properties (`client.items`, `client.business_partners`, `client.orders`, …) — these are the entities with verified ETag concurrency support. Everything else (~1000 endpoints) requires explicit binding:
+
+```python
+res = client.get_resource(en.User, "Users")
+```
+
+The explicit `get_resource` call is a deliberate safety signal: ETag protection is **not guaranteed** for these endpoints. When adding a new alias, only promote to Elite if SAP supports ETag for that endpoint.
+
+### Async/Sync symmetry
+
+`B1Client` / `AsyncB1Client`, `RestAdapter` / `AsyncRestAdapter`, `GenericResource` / `AsyncGenericResource`, `QueryBuilder` / `AsyncQueryBuilder` — every sync class has an async counterpart. Both surfaces must support the same parameters and methods. When changing one, change the other.
+
+### ETag concurrency — proactive invalidation
+
+SAP returns `204 No Content` on PATCH/DELETE without a fresh `ETag` header. The adapter's contract is:
+
+1. GET caches `ETag`.
+2. PATCH/DELETE sends it as `If-Match`.
+3. **On success, the adapter immediately clears the cached ETag** (proactive invalidation). Skipping this step makes a subsequent DELETE-after-UPDATE use a stale ETag and silently break under load.
+4. 412 → `SAPConcurrencyError`.
+
+Adapters map HTTP status to semantic exceptions via a standardized dict: 400 → `B1ValidationError`, 401 → `B1AuthError`, 404 → `B1NotFoundError`, 412 → `SAPConcurrencyError`, else `B1Exception`.
+
+### Batch / changesets
+
+`src/b1sl/b1sl/batch/` implements `$batch` via a `RecordingAdapter` proxy pattern: `batch.items.create(...)` reuses the exact same resource API but enqueues into `_pending` instead of executing.
+
+- `changeset()` blocks → atomic (all-or-nothing).
+- Top-level batch ops → independent (partial success allowed).
+- **`batch.execute()` must NOT raise on individual op failures.** Callers inspect `results.all_ok` / `results.failed`. Each result preserves `r.index` for traceability.
+
+### Pagination
+
+`.execute()` returns one page. `.stream()` follows `odata.nextLink` via generators (async generators for the async client). `.top(N)` is a global hard cap; `page_size` and `max_pages` are independent safety knobs. Filters survive page boundaries.
+
+### Configuration
+
+`B1Environment.load()` loads with precedence: env vars > `.env` > `configs/<env>.json`. JSON profiles hold non-sensitive test data only — credentials must come from env/`.env`. `B1SL_ENV` controls `dev` (human logs) vs `test` vs `prod` (structured JSON logs). `B1SL_DRY_RUN=1` (or `with b1.dry_run():` — `ContextVar`-scoped, task-safe) intercepts all writes and returns a fake 204.
+
+## Rules and gotchas
+
+- **English only** in code, comments, commits, docs.
+- **Never `pip install`** — use `uv add` / `uv sync`.
+- **Never edit `_generated/`**. Fix the generator or add a `_overrides/` file.
+- **Run `make lint` before proposing changes** — it covers the whole repo (CI only runs ruff, so mypy regressions slip past unless you run it locally).
+- **Surgical deltas only**: write `client.items.update("A001", en.Item(item_name="New"))`, never round-trip a fetched object.
+- **Don't promote endpoints to Elite without verifying ETag support** — Elite aliases imply concurrency safety.
+- **VCR cassette hygiene**: `tests/conftest.py` redacts hosts, sessions, credentials, and OData context URLs. Before pushing recorded cassettes, sanity-check with `grep -r "B1SESSION" tests/integration/cassettes/`.
+- **`hdbcli` is mocked at top-level in `tests/conftest.py`** so HANA tests don't require the SAP driver. Don't import `hdbcli` outside the `saphdb` subpackage.
+- Pytest markers: `integration` (live SAP), `vcr` (cassette playback). Default `make test` excludes both.
+
+## Where things live
+
+- `src/b1sl/b1sl/` — Service Layer SDK (the main product).
+- `src/b1sl/saphdb/` — optional HANA direct-SQL adapter (gated by `hana` extra).
+- `src/b1sl/contrib/` — framework integrations (Django, etc.).
+- `src/b1sl/contrib/mcp/` — MCP helper toolkit (framework-agnostic, no MCP SDK import).
+  Seven modules: `discovery.py` (Elite resource catalog + field introspection),
+  `grammar.py` / `odata_grammar.py` (SQL and OData grammar constraints + system prompts),
+  `schemas.py` / `odata_schemas.py` (tool-definition builders for SQL and OData CRUD),
+  `formatters.py` / `odata_formatters.py` (result/error formatters).
+  Guide: `docs/16-mcp-helpers.md`. Example: `examples/23_mcp_odata_server.py`.
+- `scripts/b1sl_metadata_generator/` — the generator engine.
+- `scripts/generate_models.sh <version>` — regen entry point.
+- `docs/` — long-form architecture/API guides (excluded from the wheel).
+- `docs/reference/sl/` — verbatim SAP Service Layer reference extracts (e.g. `sql-queries.md`). Read these before guessing endpoint semantics.
+- `examples/`, `skills/`, `agents.md`, `metadata/` — also excluded from the wheel (see `pyproject.toml [tool.hatch.build]`).
+- `src/b1sl/b1sl/resources/sql_queries.py` — specialized resource with bounded function (`/List`) support; the reference implementation for resources that go beyond generic CRUD.
+- `src/b1sl/b1sl/pagination.py` — contains `extract_next_link()` which handles both OData v3 (`odata.nextLink`) and v4 (`@odata.nextLink`) response formats.

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: b1sl-python
-Version: 0.3.0
+Version: 0.4.0
 Summary: A framework-agnostic Python SDK for SAP Business One Service Layer and SAP HANA. (Unofficial)
 Project-URL: Homepage, https://github.com/operator-ita/b1sl-python
 Project-URL: Repository, https://github.com/operator-ita/b1sl-python

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "b1sl-python"
-version = "0.3.0"
+version = "0.4.0"
 description = "A framework-agnostic Python SDK for SAP Business One Service Layer and SAP HANA. (Unofficial)"
 readme = "README.md"
 requires-python = ">=3.11,<3.13"

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/__init__.py

@@ -13,9 +13,20 @@ from b1sl.b1sl.client import B1Client
 from b1sl.b1sl.config import B1Config
 from b1sl.b1sl.config_manager import B1Environment
 from b1sl.b1sl.environment import B1Env
-from b1sl.b1sl.exceptions.exceptions import SAPConcurrencyError
+from b1sl.b1sl.exceptions.exceptions import (
+    B1SqlNotAllowedError,
+    B1SqlParamError,
+    B1SqlSyntaxError,
+    SAPConcurrencyError,
+)
 from b1sl.b1sl.resources.async_base import AsyncGenericResource
 from b1sl.b1sl.resources.base import GenericResource, ODataQuery
+from b1sl.b1sl.resources.sql_queries import (
+    DEFAULT_ACCESSIBLE_TABLES,
+    KNOWN_INACCESSIBLE_PATTERNS,
+    SQLQueryInfo,
+    SQLRunResult,
+)
 from b1sl.b1sl.rest_adapter import RestAdapter
 
 try:
@@ -42,9 +53,16 @@ __all__ = [
     "RestAdapter",
     "B1Env",
     "SAPConcurrencyError",
+    "B1SqlSyntaxError",
+    "B1SqlNotAllowedError",
+    "B1SqlParamError",
     "AsyncGenericResource",
     "GenericResource",
     "ODataQuery",
+    "DEFAULT_ACCESSIBLE_TABLES",
+    "KNOWN_INACCESSIBLE_PATTERNS",
+    "SQLQueryInfo",
+    "SQLRunResult",
     "entities",
     "fields",
     "HookContext",

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/async_client.py

@@ -17,6 +17,11 @@ if TYPE_CHECKING:
     from b1sl.b1sl.models._generated.entities.inventory import Item
     from b1sl.b1sl.models.base import B1Model
     from b1sl.b1sl.resources.async_base import AsyncGenericResource
+    from b1sl.b1sl.resources.crossjoin import (
+        AsyncCrossJoinQueryBuilder,
+        AsyncQueryServiceBuilder,
+    )
+    from b1sl.b1sl.resources.sql_queries import AsyncSQLQueriesResource
     from b1sl.b1sl.resources.udo import AsyncUDOResource
 
 
@@ -351,6 +356,15 @@ class AsyncB1Client:
         from b1sl.b1sl.models._generated.entities.general import Document
         return self.get_resource(Document, "CorrectionPurchaseInvoiceReversal")
 
+    # --- SQL Queries ---
+
+    @property
+    def sql_queries(self) -> "AsyncSQLQueriesResource":
+        """Access the 'SQLQueries' endpoint (supports ETags, run() / run_stream())."""
+        from b1sl.b1sl.resources.sql_queries import AsyncSQLQueriesResource
+        resource = AsyncSQLQueriesResource(self._adapter)
+        return resource
+
     def udo(self, table_name: str) -> "AsyncUDOResource":
         """
         Asynchronously access a User Defined Object (UDO) or User Table.
@@ -360,4 +374,45 @@ class AsyncB1Client:
         from b1sl.b1sl.resources.udo import AsyncUDOResource
         return AsyncUDOResource(adapter=self._adapter, table_name=table_name)
 
+    def crossjoin(self, *entities: str) -> "AsyncCrossJoinQueryBuilder":
+        """Build an async ``$crossjoin`` query (SAP HANA only, B1 9.2 patch 07+).
+
+        At least 2 entity names are required.  A bare crossjoin without
+        ``$expand`` or ``$apply`` will raise ``ValueError`` before the request.
+
+        Example::
+
+            rows = await (
+                client.crossjoin("Orders", "BusinessPartners")
+                .expand({"Orders": ["DocEntry", "DocNum"], "BusinessPartners": ["CardCode"]})
+                .filter("Orders/CardCode eq BusinessPartners/CardCode")
+                .execute()
+            )
+        """
+        from b1sl.b1sl.resources.crossjoin import AsyncCrossJoinQueryBuilder
+
+        return AsyncCrossJoinQueryBuilder(self._adapter, *entities)
+
+    def query_service(self, query_path: str) -> "AsyncQueryServiceBuilder":
+        """Async ``QueryService_PostQuery`` row-level filter (SAP HANA only, B1 9.2 PL11+).
+
+        Example::
+
+            rows = await (
+                client.query_service("$crossjoin(Orders,Orders/DocumentLines)")
+                .expand({
+                    "Orders": ["DocEntry", "DocNum"],
+                    "Orders/DocumentLines": ["ItemCode", "LineNum"],
+                })
+                .filter(
+                    "Orders/DocEntry eq Orders/DocumentLines/DocEntry"
+                    " and Orders/DocumentLines/ItemCode eq 'WIDGET'"
+                )
+                .execute()
+            )
+        """
+        from b1sl.b1sl.resources.crossjoin import AsyncQueryServiceBuilder
+
+        return AsyncQueryServiceBuilder(self._adapter, query_path)
+
 

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/async_rest_adapter.py

@@ -16,6 +16,7 @@ from b1sl.b1sl.exceptions.exceptions import (
     B1ValidationError,
 )
 from b1sl.b1sl.models.result import Result
+from b1sl.b1sl.pagination import extract_next_link
 
 _HTTP_STATUS_TO_EXC: dict[int, type] = {
     400: B1ValidationError,
@@ -278,7 +279,10 @@ class AsyncRestAdapter(BaseRestAdapter):
             self._raise_if_concurrency_error(
                 e.response.status_code, sap_code, sap_msg, endpoint_path, body
             )
-            
+            self._raise_if_sql_error(
+                e.response.status_code, sap_code, sap_msg, body
+            )
+
             # Use specialized exception based on status code if available
             exc_cls = _HTTP_STATUS_TO_EXC.get(e.response.status_code, B1Exception)
             raise exc_cls(f"SAP Error {sap_code}: {sap_msg}", details=body) from e
@@ -335,13 +339,11 @@ class AsyncRestAdapter(BaseRestAdapter):
                 status_code=response.status_code,
                 message=response.reason_phrase,
                 data=data_out,
-                next_link=data_out.get("odata.nextLink")
-                if isinstance(data_out, dict)
-                else None,
-                next_params=self._get_ep_params(data_out.get("odata.nextLink"))
-                if isinstance(data_out, dict) and data_out.get("odata.nextLink")
+                next_link=extract_next_link(data_out) if isinstance(data_out, dict) else None,
+                next_params=self._get_ep_params(extract_next_link(data_out))
+                if isinstance(data_out, dict) and extract_next_link(data_out)
                 else None,
-                metadata=data_out.get("odata.metadata")
+                metadata=(data_out.get("@odata.context") or data_out.get("odata.metadata"))
                 if isinstance(data_out, dict)
                 else None,
             )

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/base_adapter.py

@@ -16,7 +16,12 @@ from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 from urllib.parse import parse_qs, urlencode, urlparse
 
-from b1sl.b1sl.exceptions.exceptions import SAPConcurrencyError
+from b1sl.b1sl.exceptions.exceptions import (
+    B1SqlNotAllowedError,
+    B1SqlParamError,
+    B1SqlSyntaxError,
+    SAPConcurrencyError,
+)
 
 
 @dataclass
@@ -403,6 +408,44 @@ class BaseRestAdapter:
                 details=response_body,
             )
 
+    @staticmethod
+    def _raise_if_sql_error(
+        status_code: int,
+        sap_code: str,
+        sap_message: str,
+        response_body: dict | None,
+    ) -> None:
+        """Convert SAP 400 responses with SQL-specific codes into typed exceptions.
+
+        SAP error codes handled:
+        - ``"702"`` / ``"703"`` → ``B1SqlNotAllowedError`` (table or column blocked)
+        - ``"704"`` → ``B1SqlParamError`` (missing, extra, or mis-typed parameter)
+
+        Called from ``_do`` in both sync and async adapters, right before the
+        generic ``B1ValidationError`` fallback, so callers can catch the
+        granular subclass or the broader ``B1ValidationError``.
+
+        Note: SAP returns ``code`` as a JSON string (e.g. ``"702"``), not an int.
+        """
+        if status_code != 400:
+            return
+        if sap_code == B1SqlSyntaxError.SAP_ERROR_CODE:
+            raise B1SqlSyntaxError(
+                f"SAP SQL syntax error: {sap_message}",
+                details=response_body,
+            )
+        if sap_code in ("702", "703"):
+            raise B1SqlNotAllowedError(
+                f"SAP SQL allowlist violation [{sap_code}]: {sap_message}",
+                sap_code=sap_code,
+                details=response_body,
+            )
+        if sap_code == B1SqlParamError.SAP_ERROR_CODE:
+            raise B1SqlParamError(
+                f"SAP SQL parameter error: {sap_message}",
+                details=response_body,
+            )
+
     def _redact_data(self, data: dict | None) -> dict:
         """Mask sensitive information in data dictionaries before logging."""
         return {k: "***" if k == "Password" else v for k, v in (data or {}).items()}

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/batch/_recording_adapter.py

@@ -18,6 +18,7 @@ class PendingRequest:
     endpoint: str
     data: dict | None = None
     ep_params: dict | None = None
+    headers: dict | None = None
     model_type: Type[B1Model] | None = None
     changeset_id: str | None = None
     content_id: str = field(default_factory=lambda: str(uuid.uuid4()))
@@ -31,7 +32,8 @@ class _RecordingAdapter:
         self._batch = batch_client
         self._current_model: Type[B1Model] | None = None
 
-    def _record(self, method: str, endpoint: str, ep_params: dict | None = None, data: dict | None = None):
+    def _record(self, method: str, endpoint: str, ep_params: dict | None = None,
+                data: dict | None = None, headers: dict | None = None):
         """Captures the request and adds it to the client's queue."""
         if method == "GET" and self._batch.active_changeset_id:
             raise ValueError("OData Batch Error: GET operations are not allowed within a ChangeSet.")
@@ -41,27 +43,28 @@ class _RecordingAdapter:
             endpoint=endpoint,
             ep_params=ep_params,
             data=data,
+            headers=headers,
             model_type=self._current_model,
             changeset_id=self._batch.active_changeset_id
         )
         self._batch._pending.append(req)
-        
+
         # Return a simulated Result so Pydantic doesn't crash
         return Result(status_code=202, data={})
 
     # Asynchronous implementation for AsyncGenericResource
-    async def get(self, endpoint, ep_params=None, data=None):
-        return self._record("GET", endpoint, ep_params, data)
+    async def get(self, endpoint, ep_params=None, data=None, headers=None):
+        return self._record("GET", endpoint, ep_params, data, headers)
 
-    async def post(self, endpoint, ep_params=None, data=None):
-        return self._record("POST", endpoint, ep_params, data)
+    async def post(self, endpoint, ep_params=None, data=None, headers=None):
+        return self._record("POST", endpoint, ep_params, data, headers)
 
-    async def patch(self, endpoint, ep_params=None, data=None):
-        return self._record("PATCH", endpoint, ep_params, data)
+    async def patch(self, endpoint, ep_params=None, data=None, headers=None):
+        return self._record("PATCH", endpoint, ep_params, data, headers)
 
-    async def delete(self, endpoint, ep_params=None, data=None):
-        return self._record("DELETE", endpoint, ep_params, data)
+    async def delete(self, endpoint, ep_params=None, data=None, headers=None):
+        return self._record("DELETE", endpoint, ep_params, data, headers)
 
     # Synchronous implementation for GenericResource (compatibility)
-    def get_sync(self, endpoint, ep_params=None, data=None):
-        return self._record("GET", endpoint, ep_params, data)
+    def get_sync(self, endpoint, ep_params=None, data=None, headers=None):
+        return self._record("GET", endpoint, ep_params, data, headers)

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/batch/serializer.py

@@ -49,14 +49,25 @@ class BatchSerializer:
             lines.append(f"{req.method} /b1s/v2/{clean_endpoint} HTTP/1.1")
             
             # 5. Internal Headers
-            if req.data:
+            # Any caller-supplied per-part headers (e.g. Prefer:
+            # odata.maxpagesize, If-Match) — skip Content-Type, we set our own
+            # below whenever a body is present.
+            if req.headers:
+                for hk, hv in req.headers.items():
+                    if hk.lower() == "content-type":
+                        continue
+                    lines.append(f"{hk}: {hv}")
+            # A body is present whenever data is not None — note an empty dict
+            # ({}) is a valid, required body for some bounded functions (e.g.
+            # the SQLQueries /List POST), so we must not skip it on falsiness.
+            if req.data is not None:
                 lines.append("Content-Type: application/json")
             lines.append("") # End of internal headers
 
             # 6. Body
-            if req.data:
+            if req.data is not None:
                 lines.append(json.dumps(req.data))
-            
+
             lines.append("")  # Blank line after body (OData multipart spec)
 
         # Close the last changeset if it remained open

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/client.py

@@ -18,6 +18,8 @@ if TYPE_CHECKING:
     from b1sl.b1sl.models._generated.entities.inventory import Item
     from b1sl.b1sl.models.base import B1Model
     from b1sl.b1sl.resources.base import GenericResource
+    from b1sl.b1sl.resources.crossjoin import CrossJoinQueryBuilder, QueryServiceBuilder
+    from b1sl.b1sl.resources.sql_queries import SQLQueriesResource
     from b1sl.b1sl.resources.udo import UDOResource
 
 
@@ -348,6 +350,15 @@ class B1Client:
         from b1sl.b1sl.models._generated.entities.general import Document
         return self.get_resource(Document, "CorrectionPurchaseInvoiceReversal")
 
+    # --- SQL Queries ---
+
+    @property
+    def sql_queries(self) -> "SQLQueriesResource":
+        """Access the 'SQLQueries' endpoint (supports ETags, run() / run_stream())."""
+        from b1sl.b1sl.resources.sql_queries import SQLQueriesResource
+        resource = SQLQueriesResource(self._adapter)
+        return resource
+
     def udo(self, table_name: str) -> "UDOResource":
         """
         Access a User Defined Object (UDO) or User Table dynamically.
@@ -362,3 +373,48 @@ class B1Client:
         from b1sl.b1sl.resources.udo import UDOResource
 
         return UDOResource(adapter=self._adapter, table_name=table_name)
+
+    def crossjoin(self, *entities: str) -> "CrossJoinQueryBuilder":
+        """Build a ``$crossjoin`` query across entity sets (SAP HANA only, B1 9.2 patch 07+).
+
+        At least 2 entity names are required.  A bare crossjoin without
+        ``$expand`` or ``$apply`` will raise ``ValueError`` before the request.
+
+        Example::
+
+            rows = (
+                client.crossjoin("Orders", "BusinessPartners")
+                .expand({"Orders": ["DocEntry", "DocNum"], "BusinessPartners": ["CardCode"]})
+                .filter("Orders/CardCode eq BusinessPartners/CardCode")
+                .execute()
+            )
+        """
+        from b1sl.b1sl.resources.crossjoin import CrossJoinQueryBuilder
+
+        return CrossJoinQueryBuilder(self._adapter, *entities)
+
+    def query_service(self, query_path: str) -> "QueryServiceBuilder":
+        """Build a ``QueryService_PostQuery`` row-level filter (SAP HANA only, B1 9.2 PL11+).
+
+        Joins a document header with its navigation lines via POST.  Use this
+        when you need to filter by line-level fields (ItemCode, LineNum, etc.)
+        combined with header fields — which regular ``$filter`` cannot do.
+
+        Example::
+
+            rows = (
+                client.query_service("$crossjoin(Orders,Orders/DocumentLines)")
+                .expand({
+                    "Orders": ["DocEntry", "DocNum"],
+                    "Orders/DocumentLines": ["ItemCode", "LineNum"],
+                })
+                .filter(
+                    "Orders/DocEntry eq Orders/DocumentLines/DocEntry"
+                    " and Orders/DocumentLines/ItemCode eq 'WIDGET'"
+                )
+                .execute()
+            )
+        """
+        from b1sl.b1sl.resources.crossjoin import QueryServiceBuilder
+
+        return QueryServiceBuilder(self._adapter, query_path)

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/exceptions/__init__.py

@@ -4,6 +4,9 @@ from b1sl.b1sl.exceptions.exceptions import (
     B1Exception,
     B1NotFoundError,
     B1ResponseError,
+    B1SqlNotAllowedError,
+    B1SqlParamError,
+    B1SqlSyntaxError,
     B1ValidationError,
     SAPConcurrencyError,
 )
@@ -14,6 +17,9 @@ __all__ = [
     "B1ConnectionError",
     "B1NotFoundError",
     "B1ValidationError",
+    "B1SqlSyntaxError",
+    "B1SqlNotAllowedError",
+    "B1SqlParamError",
     "B1ResponseError",
     "SAPConcurrencyError",
 ]

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/exceptions/exceptions.py

@@ -88,6 +88,101 @@ class B1ValidationError(B1Exception):
     """
 
 
+class B1SqlNotAllowedError(B1ValidationError):
+    """Raised when SAP rejects a SQLQuery because a table or column is blocked.
+
+    SAP error codes:
+    - ``"702"`` — table not in the server allowlist (``b1s_sqltable.conf``).
+    - ``"703"`` — column excluded via ``ColumnExcludeList`` in the same config.
+
+    Neither condition can be fixed at runtime; the SQL text or the server
+    configuration must change.  The ``sap_code`` attribute lets callers
+    distinguish table-level from column-level blocks::
+
+        try:
+            result = client.sql_queries.run("sql04")
+        except B1SqlNotAllowedError as e:
+            if e.sap_code == "702":
+                print(f"Table blocked: {e}")
+            else:
+                print(f"Column blocked: {e}")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        sap_code: str = "702",
+        details: dict | None = None,
+    ) -> None:
+        super().__init__(message, details=details)
+        self.sap_code = sap_code
+
+
+class B1SqlSyntaxError(B1ValidationError):
+    """Raised when SAP rejects a SQL definition or execution due to invalid syntax.
+
+    SAP error code ``"701"`` — covers multiple sub-cases, all requiring a fix
+    to the SQL text itself (no runtime adjustment can resolve a 701 error):
+
+    - **Grammar error**: typos like ``ORDER BY x dsc`` instead of ``DESC``.
+    - **Unsupported function**: e.g. ``length()``, ``CASE WHEN``, ``COALESCE``.
+    - **``SELECT *`` in the top-level query**: only allowed inside subqueries.
+    - **Computed column without alias**: ``SUM(col)`` must be aliased as
+      ``SUM(col) AS total``.
+    - **Duplicate alias**: two columns sharing the same alias are rejected.
+    - **DML statement**: ``UPDATE``, ``INSERT``, ``DELETE``, ``ALTER``, etc. —
+      the ``SQLQueries`` endpoint accepts only ``SELECT`` queries.
+
+    The SAP error message includes the character position and a description::
+
+        try:
+            client.sql_queries.create(en.SQLQuery(sql_code="q1",
+                                                   sql_text="select * from ORDR"))
+        except B1SqlSyntaxError as e:
+            print(e)  # "Invalid SQL syntax: ..., Cannot support asterisk(*)..."
+    """
+
+    SAP_ERROR_CODE = "701"
+
+    def __init__(self, message: str, *, details: dict | None = None) -> None:
+        super().__init__(message, details=details)
+        self.sap_code = self.SAP_ERROR_CODE
+
+
+class B1SqlParamError(B1ValidationError):
+    """Raised when SAP rejects a ``/List`` invocation due to parameter problems.
+
+    SAP error code ``"704"`` — covers missing parameters, extra parameters, or
+    type mismatches.  Unlike ``B1SqlNotAllowedError``, this is fixable by the
+    caller: check that the kwargs passed to ``run()`` / ``run_stream()`` match
+    the ``ParamList`` declared in the stored ``SqlText``::
+
+        try:
+            rows = client.sql_queries.run("sql01", doc_total=100)
+        except B1SqlParamError:
+            # Wrong param name — SAP expects :docTotal, not :doc_total
+            rows = client.sql_queries.run("sql01", docTotal=100)
+
+    Note: SAP returns a generic ``"Parameter error."`` message without naming
+    the offending parameter.  Inspect the stored query's ``ParamList`` field
+    to cross-reference.
+    """
+
+    SAP_ERROR_CODE = "704"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        details: dict | None = None,
+        expected_params: list[str] | None = None,
+    ) -> None:
+        super().__init__(message, details=details)
+        self.sap_code = self.SAP_ERROR_CODE
+        self.expected_params: list[str] | None = expected_params
+
+
 class B1ResponseError(B1Exception):
     """Raised for unexpected non-2xx responses not covered by other subclasses."""
 

{b1sl_python-0.3.0 → b1sl_python-0.4.0}/src/b1sl/b1sl/pagination.py

@@ -1,6 +1,18 @@
 from urllib.parse import parse_qs, urlparse
 
 
+def extract_next_link(data: dict) -> str | None:
+    """Return the OData nextLink from a response body, tolerating v3 and v4 formats.
+
+    SAP Service Layer uses different key names depending on the OData version:
+    - OData v3 (``b1s/v1``): ``"odata.nextLink"``
+    - OData v4 (``b1s/v2``): ``"@odata.nextLink"``
+
+    Returns the first non-empty value found, or ``None``.
+    """
+    return data.get("@odata.nextLink") or data.get("odata.nextLink") or None
+
+
 def extract_skip(next_link: str) -> int | None:
     """
     Extracts the $skip value from an odata.nextLink string.