flex-api 1.0.0b35__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+flex_api/__init__.py,sha256=fVSASvVtpwRvEKNizR-n3fnAoGjpHBFCsckWce-zndg,8927
+flex_api-1.0.0b35.dist-info/licenses/LICENSE,sha256=EKxK-PX7qM2cv2bJ74p436Zew25apeQ7ayNPAlUVzCs,2823
+flex_api-1.0.0b35.dist-info/METADATA,sha256=BJPOK4qIN_r_DmsVlbw-jYOzrYUMzb_bfh6MB8buqd8,3498
+flex_api-1.0.0b35.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flex_api-1.0.0b35.dist-info/top_level.txt,sha256=65rmWjm-LH8azmbaFLhVicMryd9HolAF_K-XWtE-GbU,9
+flex_api-1.0.0b35.dist-info/RECORD,,

flex_api-1.0.0b35.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flex_api-1.0.0b35.dist-info/licenses/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.dist-info/top_level.txt

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