flex-api 1.0.0b35__tar.gz

flex_api-1.0.0b35/LICENSE

@@ -0,0 +1,58 @@
+Flex API Client SDK — Proprietary License
+
+Copyright (c) 2026 Flex Services, LLC. All rights reserved.
+
+1. Definitions.
+   "Software" means this package (the Flex API client SDK), in source and
+   compiled form, together with its documentation.
+   "Flex Service" means the Flex on the Job application and its API
+   (https://flexonthejob.com).
+   "You" means the individual or entity exercising the rights granted below.
+
+2. Grant of license.
+   Subject to Your compliance with this License, Flex Services, LLC grants You
+   a personal, non-exclusive, non-transferable, non-sublicensable, revocable
+   license to install and use the Software, in unmodified form, solely to
+   develop and operate Your own applications that access the Flex Service
+   through its API using credentials issued to You.
+
+3. Restrictions.
+   Except as expressly permitted in Section 2, You may not:
+   (a) copy, reproduce or distribute the Software, in whole or in part, or
+       publish or re-publish it to any package registry or other repository;
+   (b) modify, adapt, translate or create derivative works of the Software;
+   (c) sell, rent, lease, lend, sublicense or otherwise transfer the Software
+       or Your rights under this License;
+   (d) reverse engineer, decompile or disassemble the Software, or attempt to
+       derive its source code, except to the extent this restriction is
+       prohibited by applicable law;
+   (e) remove, alter or obscure any copyright, trademark or other proprietary
+       notice; or
+   (f) use the Software to build, train or improve a product or service that
+       competes with the Software or the Flex Service.
+
+4. Ownership.
+   The Software is licensed, not sold. Flex Services, LLC and its licensors
+   retain all right, title and interest in and to the Software, including all
+   intellectual property rights. No rights are granted except as expressly set
+   out in this License.
+
+5. Termination.
+   This License terminates automatically if You breach any of its terms, and
+   may be revoked by Flex Services, LLC at any time. On termination You must
+   stop using and destroy all copies of the Software. Sections 3, 4, 6 and 7
+   survive termination.
+
+6. No warranty.
+   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 NON-INFRINGEMENT.
+
+7. Limitation of liability.
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL FLEX SERVICES, LLC
+   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.
+
+For other uses, or to request additional rights, contact
+legal@flexonthejob.com.

flex_api-1.0.0b35/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: flex-api
+Version: 1.0.0b35
+Summary: Client for the Flex on the Job tenant API (/api/v1): inventory, jobs, invoices, purchasing.
+License: Proprietary. See LICENSE file.
+Project-URL: Homepage, https://flexonthejob.com/developers
+Project-URL: API reference, https://app.flexonthejob.com/docs
+Keywords: flex,inventory,field-service,openapi,api-client
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flex-api (Python)
+
+Client for the [Flex on the Job](https://flexonthejob.com) tenant API. Standard library only, Python 3.9+.
+
+```python
+from flex_api import FlexClient, FlexApiError, SANDBOX_URL
+
+flex = FlexClient(api_key="flx_live_...")          # Settings -> Integrations -> API Keys
+# flex = FlexClient("flx_live_YLJG6oxA6hOiJTT7ziyAOFs8nJAJfbRE", base_url=SANDBOX_URL)  # public read-only demo
+
+for item in flex.paginate("/api/v1/items", search="filter"):
+    print(item["name"], item["onHand"])
+
+# Writes get an Idempotency-Key automatically (kept across retries).
+flex.post("/api/v1/items/stock/batch", {"operations": [
+    {"action": "Adjust", "itemId": 12, "locationId": 3, "delta": -2, "reason": "Cycle count"},
+    {"action": "Move", "itemId": 12, "fromLocationId": 3, "toLocationId": 4, "quantity": 1},
+]})
+
+try:
+    flex.post("/api/v1/purchase-orders", {"receivingLocationId": 1, "lines": [{"itemId": 999, "quantityOrdered": 1}]})
+except FlexApiError as e:
+    print(e.status, e.detail, e.errors)   # 422 ... {'lines[0].itemId': [...]}
+```
+
+What the client does for you:
+
+- `Authorization: Bearer` on every request.
+- An `Idempotency-Key` on every POST/PUT/PATCH/DELETE (pass `idempotency_key=` to choose your own), reused if the
+  request is retried, so a retry is never applied twice.
+- Retries 429 and 503 (default 3 times), waiting `Retry-After` (seconds or an HTTP date), and a 409 "still being
+  processed" while an earlier attempt with the same key is running.
+- `flex.last_response_headers` holds the last response's headers: send its `etag` back as `if_match=` on
+  `put()` / `patch()` to refuse an update if the record changed in between (412).
+- `paginate(path, **query)` follows `nextCursor` across pages.
+- Errors raise `FlexApiError` with the RFC 7807 problem: `status`, `detail`, and `errors` per field.
+
+Paths, parameters and bodies are exactly those of the OpenAPI document at
+<https://app.flexonthejob.com/openapi/v1.json> (browsable at `/docs`). Tests: `python -m unittest discover -s tests`.
+
+Examples in `examples/`: `cycle_count.py`, `invoice_completed_jobs.py` (`--finalize` also marks the drafts sent), `receive_delivery.py` and `reorder_low_stock.py`. They talk to the sandbox unless you set `FLEX_BASE_URL=https://app.flexonthejob.com`. The last three preview
+their change and write only after `--apply`, `--yes` or an interactive yes. The Flex MCP server (`/mcp`) offers the same tasks as prompts (`cycle_count`, `invoice_completed_jobs`, `receive_delivery`, `reorder_below_minimum`).
+
+## License
+
+Proprietary — Copyright (c) 2026 Flex Services, LLC. All rights reserved. Licensed for use in your
+applications to access the Flex on the Job API; you may not copy, modify, redistribute, or reverse-engineer
+it. See the [LICENSE](./LICENSE) file for the full terms.

flex_api-1.0.0b35/README.md

@@ -0,0 +1,48 @@
+# flex-api (Python)
+
+Client for the [Flex on the Job](https://flexonthejob.com) tenant API. Standard library only, Python 3.9+.
+
+```python
+from flex_api import FlexClient, FlexApiError, SANDBOX_URL
+
+flex = FlexClient(api_key="flx_live_...")          # Settings -> Integrations -> API Keys
+# flex = FlexClient("flx_live_YLJG6oxA6hOiJTT7ziyAOFs8nJAJfbRE", base_url=SANDBOX_URL)  # public read-only demo
+
+for item in flex.paginate("/api/v1/items", search="filter"):
+    print(item["name"], item["onHand"])
+
+# Writes get an Idempotency-Key automatically (kept across retries).
+flex.post("/api/v1/items/stock/batch", {"operations": [
+    {"action": "Adjust", "itemId": 12, "locationId": 3, "delta": -2, "reason": "Cycle count"},
+    {"action": "Move", "itemId": 12, "fromLocationId": 3, "toLocationId": 4, "quantity": 1},
+]})
+
+try:
+    flex.post("/api/v1/purchase-orders", {"receivingLocationId": 1, "lines": [{"itemId": 999, "quantityOrdered": 1}]})
+except FlexApiError as e:
+    print(e.status, e.detail, e.errors)   # 422 ... {'lines[0].itemId': [...]}
+```
+
+What the client does for you:
+
+- `Authorization: Bearer` on every request.
+- An `Idempotency-Key` on every POST/PUT/PATCH/DELETE (pass `idempotency_key=` to choose your own), reused if the
+  request is retried, so a retry is never applied twice.
+- Retries 429 and 503 (default 3 times), waiting `Retry-After` (seconds or an HTTP date), and a 409 "still being
+  processed" while an earlier attempt with the same key is running.
+- `flex.last_response_headers` holds the last response's headers: send its `etag` back as `if_match=` on
+  `put()` / `patch()` to refuse an update if the record changed in between (412).
+- `paginate(path, **query)` follows `nextCursor` across pages.
+- Errors raise `FlexApiError` with the RFC 7807 problem: `status`, `detail`, and `errors` per field.
+
+Paths, parameters and bodies are exactly those of the OpenAPI document at
+<https://app.flexonthejob.com/openapi/v1.json> (browsable at `/docs`). Tests: `python -m unittest discover -s tests`.
+
+Examples in `examples/`: `cycle_count.py`, `invoice_completed_jobs.py` (`--finalize` also marks the drafts sent), `receive_delivery.py` and `reorder_low_stock.py`. They talk to the sandbox unless you set `FLEX_BASE_URL=https://app.flexonthejob.com`. The last three preview
+their change and write only after `--apply`, `--yes` or an interactive yes. The Flex MCP server (`/mcp`) offers the same tasks as prompts (`cycle_count`, `invoice_completed_jobs`, `receive_delivery`, `reorder_below_minimum`).
+
+## License
+
+Proprietary — Copyright (c) 2026 Flex Services, LLC. All rights reserved. Licensed for use in your
+applications to access the Flex on the Job API; you may not copy, modify, redistribute, or reverse-engineer
+it. See the [LICENSE](./LICENSE) file for the full terms.

flex_api-1.0.0b35/flex_api/__init__.py

@@ -0,0 +1,198 @@
+"""Flex on the Job API client (https://flexonthejob.com/developers).
+
+Standard library only (Python 3.9+). Wraps /api/v1 with what every caller needs:
+
+* ``Authorization: Bearer flx_live_...`` on every request;
+* an ``Idempotency-Key`` on every POST/PUT/PATCH/DELETE (the API requires one), reused across retries so a
+  retried write is applied once;
+* retry on 429 / 503 honouring ``Retry-After`` (seconds or an HTTP date), and on the 409 "still being processed"
+  answer while an earlier attempt with the same ``Idempotency-Key`` is in flight;
+* :attr:`FlexClient.last_response_headers` (e.g. the ``ETag`` to send back as ``if_match=``);
+* :meth:`FlexClient.paginate` over ``{ items, nextCursor }`` list endpoints;
+* :class:`FlexApiError` carrying the RFC 7807 problem (``status``, ``detail``, field ``errors``).
+
+Paths, parameters and bodies are exactly those in the OpenAPI document
+(https://app.flexonthejob.com/openapi/v1.json, browsable at /docs)::
+
+    from flex_api import FlexClient
+    flex = FlexClient(api_key="flx_live_...")
+    for item in flex.paginate("/api/v1/items", search="filter"):
+        print(item["name"], item["onHand"])
+    flex.post("/api/v1/items/stock/batch", {"operations": [
+        {"action": "Adjust", "itemId": 12, "locationId": 3, "delta": -2, "reason": "Cycle count"},
+    ]})
+"""
+from __future__ import annotations
+
+import email.utils
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Iterator, Optional
+
+__all__ = ["FlexClient", "FlexApiError", "PRODUCTION_URL", "SANDBOX_URL"]
+__version__ = "1.0.0b35"
+
+PRODUCTION_URL = "https://app.flexonthejob.com"
+SANDBOX_URL = "https://sandbox.flexonthejob.com"
+_WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+# The API's 409 detail while a request with the same Idempotency-Key is still running (safe to retry with that key).
+_IN_PROGRESS_MARKER = "still being processed"
+
+
+class FlexApiError(Exception):
+    """An error response from the API. ``problem`` is the parsed problem+json body (may be empty)."""
+
+    def __init__(self, status: int, problem: Optional[Dict[str, Any]] = None):
+        self.status = status
+        self.problem = problem or {}
+        self.detail = self.problem.get("detail") or self.problem.get("title")
+        self.errors: Dict[str, Any] = self.problem.get("errors") or {}
+        super().__init__(self.detail or f"Flex API error {status}")
+
+
+# (method, url, headers, body bytes, timeout) -> (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):
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 - https API URL
+            return response.status, {k.lower(): v for k, v in response.headers.items()}, response.read()
+    except urllib.error.HTTPError as error:
+        return error.code, {k.lower(): v for k, v in error.headers.items()}, error.read()
+
+
+class FlexClient:
+    """Client for one organization's API key.
+
+    :param api_key: key from Settings -> Integrations -> API Keys (``flx_live_...``).
+    :param base_url: defaults to production; use :data:`SANDBOX_URL` with the public demo keys.
+    :param max_retries: retries after 429/503 (default 3; 0 disables).
+    :param timeout: seconds per request (default 30).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = PRODUCTION_URL,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+        max_retry_after: float = 60.0,
+        transport: Optional[Transport] = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required (Settings -> Integrations -> API Keys).")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self.max_retry_after = max_retry_after
+        self._transport = transport or _urllib_transport
+        #: Lower-cased headers of the last response (``etag``, ``x-ratelimit-remaining``, ...).
+        self.last_response_headers: Dict[str, str] = {}
+
+    # ---- verbs -------------------------------------------------------------------------------
+
+    def get(self, path: str, **query: Any) -> Any:
+        return self.request("GET", path, query=query)
+
+    def post(self, path: str, body: Any = None, idempotency_key: Optional[str] = None, **query: Any) -> Any:
+        return self.request("POST", path, query=query, body=body, idempotency_key=idempotency_key)
+
+    def put(self, path: str, body: Any = None, idempotency_key: Optional[str] = None, if_match: Optional[str] = None) -> Any:
+        headers = {"If-Match": if_match} if if_match else None
+        return self.request("PUT", path, body=body, idempotency_key=idempotency_key, headers=headers)
+
+    def patch(self, path: str, body: Any = None, idempotency_key: Optional[str] = None, if_match: Optional[str] = None) -> Any:
+        headers = {"If-Match": if_match} if if_match else None
+        return self.request("PATCH", path, body=body, idempotency_key=idempotency_key, headers=headers)
+
+    def delete(self, path: str, idempotency_key: Optional[str] = None, **query: Any) -> Any:
+        return self.request("DELETE", path, query=query, idempotency_key=idempotency_key)
+
+    def paginate(self, path: str, **query: Any) -> Iterator[Dict[str, Any]]:
+        """Yields every item of a list endpoint, following ``nextCursor``."""
+        after = None
+        while True:
+            page = self.get(path, **dict(query, after=after) if after else query)
+            for item in page.get("items") or []:
+                yield item
+            after = page.get("nextCursor")
+            if not after:
+                return
+
+    # ---- core --------------------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Sends one request; returns the parsed JSON body (None for an empty body) or raises FlexApiError."""
+        method = method.upper()
+        url = self.base_url + (path if path.startswith("/") else "/" + path)
+        params = {k: _query_value(v) for k, v in (query or {}).items() if v is not None}
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+
+        sent = {"Authorization": f"Bearer {self.api_key}", "Accept": "application/json", "User-Agent": f"flex-api-python/{__version__}"}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            sent["Content-Type"] = "application/json"
+        if method in _WRITE_METHODS:
+            sent["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        sent.update(headers or {})
+
+        attempt = 0
+        while True:
+            status, response_headers, raw = self._transport(method, url, sent, data, self.timeout)
+            in_progress = status == 409 and "Idempotency-Key" in sent and _IN_PROGRESS_MARKER.encode() in (raw or b"")
+            if (status in (429, 503) or in_progress) and attempt < self.max_retries:
+                time.sleep(self._retry_delay(response_headers.get("retry-after"), attempt))
+                attempt += 1
+                continue
+            self.last_response_headers = dict(response_headers)
+            payload = _parse(raw)
+            if status >= 400:
+                raise FlexApiError(status, payload if isinstance(payload, dict) else None)
+            return payload
+
+    def _retry_delay(self, retry_after: Optional[str], attempt: int, now: Optional[float] = None) -> float:
+        seconds = 2.0 ** attempt
+        value = (retry_after or "").strip()
+        if value:
+            try:
+                seconds = float(value)
+            except ValueError:
+                try:  # HTTP-date form, e.g. "Thu, 24 Sep 2026 12:00:05 GMT"
+                    seconds = email.utils.parsedate_to_datetime(value).timestamp() - (time.time() if now is None else now)
+                except (TypeError, ValueError, IndexError):
+                    pass
+        return max(0.0, min(seconds, self.max_retry_after))
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if hasattr(value, "isoformat"):
+        return value.isoformat()
+    return str(value)
+
+
+def _parse(raw: bytes) -> Any:
+    if not raw:
+        return None
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except ValueError:
+        return raw.decode("utf-8", errors="replace")

flex_api-1.0.0b35/flex_api.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: flex-api
+Version: 1.0.0b35
+Summary: Client for the Flex on the Job tenant API (/api/v1): inventory, jobs, invoices, purchasing.
+License: Proprietary. See LICENSE file.
+Project-URL: Homepage, https://flexonthejob.com/developers
+Project-URL: API reference, https://app.flexonthejob.com/docs
+Keywords: flex,inventory,field-service,openapi,api-client
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flex-api (Python)
+
+Client for the [Flex on the Job](https://flexonthejob.com) tenant API. Standard library only, Python 3.9+.
+
+```python
+from flex_api import FlexClient, FlexApiError, SANDBOX_URL
+
+flex = FlexClient(api_key="flx_live_...")          # Settings -> Integrations -> API Keys
+# flex = FlexClient("flx_live_YLJG6oxA6hOiJTT7ziyAOFs8nJAJfbRE", base_url=SANDBOX_URL)  # public read-only demo
+
+for item in flex.paginate("/api/v1/items", search="filter"):
+    print(item["name"], item["onHand"])
+
+# Writes get an Idempotency-Key automatically (kept across retries).
+flex.post("/api/v1/items/stock/batch", {"operations": [
+    {"action": "Adjust", "itemId": 12, "locationId": 3, "delta": -2, "reason": "Cycle count"},
+    {"action": "Move", "itemId": 12, "fromLocationId": 3, "toLocationId": 4, "quantity": 1},
+]})
+
+try:
+    flex.post("/api/v1/purchase-orders", {"receivingLocationId": 1, "lines": [{"itemId": 999, "quantityOrdered": 1}]})
+except FlexApiError as e:
+    print(e.status, e.detail, e.errors)   # 422 ... {'lines[0].itemId': [...]}
+```
+
+What the client does for you:
+
+- `Authorization: Bearer` on every request.
+- An `Idempotency-Key` on every POST/PUT/PATCH/DELETE (pass `idempotency_key=` to choose your own), reused if the
+  request is retried, so a retry is never applied twice.
+- Retries 429 and 503 (default 3 times), waiting `Retry-After` (seconds or an HTTP date), and a 409 "still being
+  processed" while an earlier attempt with the same key is running.
+- `flex.last_response_headers` holds the last response's headers: send its `etag` back as `if_match=` on
+  `put()` / `patch()` to refuse an update if the record changed in between (412).
+- `paginate(path, **query)` follows `nextCursor` across pages.
+- Errors raise `FlexApiError` with the RFC 7807 problem: `status`, `detail`, and `errors` per field.
+
+Paths, parameters and bodies are exactly those of the OpenAPI document at
+<https://app.flexonthejob.com/openapi/v1.json> (browsable at `/docs`). Tests: `python -m unittest discover -s tests`.
+
+Examples in `examples/`: `cycle_count.py`, `invoice_completed_jobs.py` (`--finalize` also marks the drafts sent), `receive_delivery.py` and `reorder_low_stock.py`. They talk to the sandbox unless you set `FLEX_BASE_URL=https://app.flexonthejob.com`. The last three preview
+their change and write only after `--apply`, `--yes` or an interactive yes. The Flex MCP server (`/mcp`) offers the same tasks as prompts (`cycle_count`, `invoice_completed_jobs`, `receive_delivery`, `reorder_below_minimum`).
+
+## License
+
+Proprietary — Copyright (c) 2026 Flex Services, LLC. All rights reserved. Licensed for use in your
+applications to access the Flex on the Job API; you may not copy, modify, redistribute, or reverse-engineer
+it. See the [LICENSE](./LICENSE) file for the full terms.

flex_api-1.0.0b35/flex_api.egg-info/SOURCES.txt

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

flex_api-1.0.0b35/flex_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flex_api-1.0.0b35/flex_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+flex_api

flex_api-1.0.0b35/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flex-api"
+version = "1.0.0b35"
+description = "Client for the Flex on the Job tenant API (/api/v1): inventory, jobs, invoices, purchasing."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary. See LICENSE file." }
+dependencies = []
+keywords = ["flex", "inventory", "field-service", "openapi", "api-client"]
+classifiers = [
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://flexonthejob.com/developers"
+"API reference" = "https://app.flexonthejob.com/docs"
+
+[tool.setuptools]
+packages = ["flex_api"]
+license-files = ["LICENSE"]

flex_api-1.0.0b35/setup.cfg

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

flex_api-1.0.0b35/tests/test_client.py

@@ -0,0 +1,105 @@
+"""Offline tests for flex_api (python -m unittest discover -s tests). No network: a fake transport."""
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from flex_api import FlexApiError, FlexClient  # noqa: E402
+
+
+class FakeTransport:
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.calls = []
+
+    def __call__(self, method, url, headers, body, timeout):
+        self.calls.append({"method": method, "url": url, "headers": dict(headers), "body": body})
+        status, payload, extra = self.responses.pop(0)
+        return status, {"content-type": "application/json", **extra}, json.dumps(payload).encode() if payload is not None else b""
+
+
+class ClientTests(unittest.TestCase):
+    def test_paginate_follows_next_cursor(self):
+        fake = FakeTransport([(200, {"items": [{"id": 1}], "nextCursor": "c1"}, {}), (200, {"items": [{"id": 2}], "nextCursor": None}, {})])
+        flex = FlexClient("flx_live_test", base_url="https://example.test/", transport=fake)
+        self.assertEqual([1, 2], [i["id"] for i in flex.paginate("/api/v1/items", search="x", includeDeleted=False)])
+        self.assertIn("search=x", fake.calls[0]["url"])
+        self.assertIn("includeDeleted=false", fake.calls[0]["url"])
+        self.assertIn("after=c1", fake.calls[1]["url"])
+        self.assertTrue(all(c["headers"]["Authorization"] == "Bearer flx_live_test" for c in fake.calls))
+        self.assertTrue(all("Idempotency-Key" not in c["headers"] for c in fake.calls))
+
+    def test_writes_get_one_idempotency_key_kept_across_429_retry(self):
+        fake = FakeTransport([(429, None, {"retry-after": "0"}), (200, {"message": "ok"}, {})])
+        flex = FlexClient("flx_live_test", transport=fake)
+        self.assertEqual({"message": "ok"}, flex.post("/api/v1/items/stock/batch", {"operations": []}))
+        keys = [c["headers"]["Idempotency-Key"] for c in fake.calls]
+        self.assertEqual(2, len(keys))
+        self.assertEqual(keys[0], keys[1])
+        self.assertEqual(b'{"operations": []}', fake.calls[0]["body"])
+
+    def test_delete_also_gets_an_idempotency_key(self):
+        # Every /api/v1 DELETE is [Idempotent] and refuses a request without the header (400).
+        fake = FakeTransport([(200, {"message": "ok"}, {})])
+        flex = FlexClient("flx_live_test", transport=fake)
+        flex.delete("/api/v1/categories/7")
+        self.assertTrue(fake.calls[0]["headers"].get("Idempotency-Key"))
+
+    def test_problem_json_becomes_flex_api_error(self):
+        fake = FakeTransport([(422, {"title": "One or more validation errors occurred.", "status": 422, "errors": {"lines[0].itemId": ["No active item"]}}, {})])
+        flex = FlexClient("flx_live_test", transport=fake)
+        with self.assertRaises(FlexApiError) as caught:
+            flex.post("/api/v1/purchase-orders", {"receivingLocationId": 1})
+        self.assertEqual(422, caught.exception.status)
+        self.assertIn("lines[0].itemId", caught.exception.errors)
+
+    def test_in_flight_409_is_retried_with_the_same_key_but_other_409s_are_not(self):
+        busy = {"status": 409, "detail": "A request with this Idempotency-Key is still being processed. Wait for it to finish, then retry with the same key to get its result."}
+        fake = FakeTransport([(409, busy, {"retry-after": "0"}), (200, {"message": "ok"}, {}), (409, {"status": 409, "detail": "Version conflict"}, {})])
+        flex = FlexClient("flx_live_test", transport=fake)
+        self.assertEqual({"message": "ok"}, flex.post("/api/v1/items/stock/batch", {"operations": []}))
+        self.assertEqual(fake.calls[0]["headers"]["Idempotency-Key"], fake.calls[1]["headers"]["Idempotency-Key"])
+        with self.assertRaises(FlexApiError) as caught:
+            flex.post("/api/v1/customers", {"name": "x"})
+        self.assertEqual(409, caught.exception.status)
+        self.assertEqual(3, len(fake.calls))
+
+    def test_retry_after_seconds_http_date_and_garbage(self):
+        flex = FlexClient("flx_live_test", transport=FakeTransport([]))
+        now = 1790251200.0  # 2026-09-24T12:00:00Z
+        self.assertEqual(2.0, flex._retry_delay("2", 0, now))
+        self.assertEqual(5.0, flex._retry_delay("Thu, 24 Sep 2026 12:00:05 GMT", 0, now))
+        self.assertEqual(0.0, flex._retry_delay("Thu, 24 Sep 2026 11:59:00 GMT", 0, now))
+        self.assertEqual(4.0, flex._retry_delay("soon", 2, now))
+        self.assertEqual(60.0, flex._retry_delay("600", 0, now))
+
+    def test_etag_round_trip_with_if_match_on_put_and_patch(self):
+        fake = FakeTransport([(200, {"id": 7}, {"etag": 'W/"abc"'}), (200, {"id": 7}, {}), (200, {"id": 7}, {})])
+        flex = FlexClient("flx_live_test", transport=fake)
+        flex.get("/api/v1/customers/7")
+        etag = flex.last_response_headers["etag"]
+        flex.put("/api/v1/customers/7", {"name": "x"}, if_match=etag)
+        flex.patch("/api/v1/items/7", {"name": "x"}, if_match=etag)
+        self.assertEqual('W/"abc"', fake.calls[1]["headers"]["If-Match"])
+        self.assertEqual('W/"abc"', fake.calls[2]["headers"]["If-Match"])
+
+    def test_version_matches_pyproject_and_user_agent(self):
+        from flex_api import __version__
+        with open(os.path.join(os.path.dirname(__file__), "..", "pyproject.toml"), encoding="utf-8") as f:
+            self.assertIn(f'version = "{__version__}"', f.read())
+        fake = FakeTransport([(200, {}, {})])
+        FlexClient("k", transport=fake).get("/api/v1/items")
+        self.assertEqual(f"flex-api-python/{__version__}", fake.calls[0]["headers"]["User-Agent"])
+
+    def test_retries_stop_after_max_retries(self):
+        fake = FakeTransport([(429, None, {"retry-after": "0"})] * 2)
+        flex = FlexClient("flx_live_test", max_retries=1, transport=fake)
+        with self.assertRaises(FlexApiError) as caught:
+            flex.get("/api/v1/items")
+        self.assertEqual(429, caught.exception.status)
+        self.assertEqual(2, len(fake.calls))
+
+
+if __name__ == "__main__":
+    unittest.main()