@voxgig/sdkgen 1.5.1 → 2.0.0

package/project/.sdk/tm/py/{utility → pkg/utility}/prepare_headers.py

@@ -1,7 +1,7 @@
 # ProjectName SDK utility: prepare_headers
 
 from __future__ import annotations
-from utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 
 
 def prepare_headers_util(ctx):

package/project/.sdk/tm/py/{utility → pkg/utility}/prepare_method.py

@@ -1,6 +1,6 @@
 # ProjectName SDK utility: prepare_method
 
-from utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 
 METHOD_MAP = {
     "create": "POST",

package/project/.sdk/tm/py/{utility → pkg/utility}/prepare_params.py

@@ -1,7 +1,7 @@
 # ProjectName SDK utility: prepare_params
 
 from __future__ import annotations
-from utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 
 
 def prepare_params_util(ctx):

package/project/.sdk/tm/py/{utility → pkg/utility}/prepare_path.py

@@ -1,7 +1,7 @@
 # ProjectName SDK utility: prepare_path
 
 from __future__ import annotations
-from utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 
 
 def prepare_path_util(ctx):

package/project/.sdk/tm/py/{utility → pkg/utility}/prepare_query.py

@@ -1,7 +1,7 @@
 # ProjectName SDK utility: prepare_query
 
 from __future__ import annotations
-from utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 
 
 def _contains_param(params, s):

package/project/.sdk/tm/py/pkg/utility/register.py

@@ -0,0 +1,71 @@
+# ProjectName SDK utility registration
+
+from projectname_sdk.core.utility_type import ProjectNameUtility
+
+from projectname_sdk.utility.clean import clean_util
+from projectname_sdk.utility.done import done_util
+from projectname_sdk.utility.make_error import make_error_util
+from projectname_sdk.utility.feature_add import feature_add_util
+from projectname_sdk.utility.feature_hook import feature_hook_util
+from projectname_sdk.utility.feature_init import feature_init_util
+from projectname_sdk.utility.fetcher import fetcher_util
+from projectname_sdk.utility.make_fetch_def import make_fetch_def_util
+from projectname_sdk.utility.make_context import make_context_util
+from projectname_sdk.utility.make_options import make_options_util
+from projectname_sdk.utility.make_request import make_request_util
+from projectname_sdk.utility.make_response import make_response_util
+from projectname_sdk.utility.make_result import make_result_util
+from projectname_sdk.utility.make_point import make_point_util
+from projectname_sdk.utility.make_spec import make_spec_util
+from projectname_sdk.utility.make_url import make_url_util
+from projectname_sdk.utility.param import param_util
+from projectname_sdk.utility.prepare_auth import prepare_auth_util
+from projectname_sdk.utility.prepare_body import prepare_body_util
+from projectname_sdk.utility.prepare_headers import prepare_headers_util
+from projectname_sdk.utility.prepare_method import prepare_method_util
+from projectname_sdk.utility.prepare_params import prepare_params_util
+from projectname_sdk.utility.prepare_path import prepare_path_util
+from projectname_sdk.utility.prepare_query import prepare_query_util
+from projectname_sdk.utility.graphql import graphql_body_util, graphql_errors_util
+from projectname_sdk.utility.result_basic import result_basic_util
+from projectname_sdk.utility.result_body import result_body_util
+from projectname_sdk.utility.result_headers import result_headers_util
+from projectname_sdk.utility.transform_request import transform_request_util
+from projectname_sdk.utility.transform_response import transform_response_util
+
+
+def register_all(u):
+    u.clean = clean_util
+    u.done = done_util
+    u.make_error = make_error_util
+    u.feature_add = feature_add_util
+    u.feature_hook = feature_hook_util
+    u.feature_init = feature_init_util
+    u.fetcher = fetcher_util
+    u.make_fetch_def = make_fetch_def_util
+    u.make_context = make_context_util
+    u.make_options = make_options_util
+    u.make_request = make_request_util
+    u.make_response = make_response_util
+    u.make_result = make_result_util
+    u.make_point = make_point_util
+    u.make_spec = make_spec_util
+    u.make_url = make_url_util
+    u.param = param_util
+    u.prepare_auth = prepare_auth_util
+    u.prepare_body = prepare_body_util
+    u.prepare_headers = prepare_headers_util
+    u.prepare_method = prepare_method_util
+    u.prepare_params = prepare_params_util
+    u.prepare_path = prepare_path_util
+    u.prepare_query = prepare_query_util
+    u.graphql_body = graphql_body_util
+    u.graphql_errors = graphql_errors_util
+    u.result_basic = result_basic_util
+    u.result_body = result_body_util
+    u.result_headers = result_headers_util
+    u.transform_request = transform_request_util
+    u.transform_response = transform_response_util
+
+
+ProjectNameUtility._registrar = register_all

package/project/.sdk/tm/py/{utility → pkg/utility}/transform_request.py

@@ -1,8 +1,8 @@
 # ProjectName SDK utility: transform_request
 
 from __future__ import annotations
-from utility.voxgig_struct import voxgig_struct as vs
-from core.helpers import to_map
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core.helpers import to_map
 
 
 def transform_request_util(ctx):

package/project/.sdk/tm/py/{utility → pkg/utility}/transform_response.py

@@ -1,8 +1,8 @@
 # ProjectName SDK utility: transform_response
 
 from __future__ import annotations
-from utility.voxgig_struct import voxgig_struct as vs
-from core.helpers import to_map
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core.helpers import to_map
 
 
 def transform_response_util(ctx):

package/project/.sdk/tm/py/test/feature_harness.py

@@ -14,12 +14,12 @@ from __future__ import annotations
 
 from urllib.parse import quote
 
-from config import make_config
-from features import _make_feature
-from core.control import ProjectNameControl
-from core.error import ProjectNameError
-from core.result import ProjectNameResult
-from core.spec import ProjectNameSpec
+from projectname_sdk.config import make_config
+from projectname_sdk.features import _make_feature
+from projectname_sdk.core.control import ProjectNameControl
+from projectname_sdk.core.error import ProjectNameError
+from projectname_sdk.core.result import ProjectNameResult
+from projectname_sdk.core.spec import ProjectNameSpec
 
 
 # True when this SDK was generated with the named feature.

package/project/.sdk/tm/py/test/runner.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import os
 import json
 
-from utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 
 
 class ProjectNameTestRunner:

package/project/.sdk/tm/py/test/struct_runner.py

@@ -6,7 +6,7 @@ import json
 import re
 from typing import Any, Dict, List, Callable, TypedDict, Optional, Union
 
-from utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 
 
 NULLMARK = '__NULL__'  # Value is JSON null

package/project/.sdk/tm/py/test/test_pipeline.py

@@ -16,11 +16,11 @@
 import pytest
 
 from projectname_sdk import ProjectNameSDK
-from core.error import ProjectNameError
-from core.result import ProjectNameResult
-from core.response import ProjectNameResponse
-from core.spec import ProjectNameSpec
-from feature.base_feature import ProjectNameBaseFeature
+from projectname_sdk.core.error import ProjectNameError
+from projectname_sdk.core.result import ProjectNameResult
+from projectname_sdk.core.response import ProjectNameResponse
+from projectname_sdk.core.spec import ProjectNameSpec
+from projectname_sdk.feature.base_feature import ProjectNameBaseFeature
 
 
 def _client():

package/project/.sdk/tm/py/test/test_primary_utility.py

@@ -6,15 +6,15 @@ import re
 
 import pytest
 
-from utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 from projectname_sdk import ProjectNameSDK
-from core.spec import ProjectNameSpec
-from core.result import ProjectNameResult
-from core.response import ProjectNameResponse
-from core.operation import ProjectNameOperation
-from core.error import ProjectNameError
-from core import helpers
-from feature.base_feature import ProjectNameBaseFeature
+from projectname_sdk.core.spec import ProjectNameSpec
+from projectname_sdk.core.result import ProjectNameResult
+from projectname_sdk.core.response import ProjectNameResponse
+from projectname_sdk.core.operation import ProjectNameOperation
+from projectname_sdk.core.error import ProjectNameError
+from projectname_sdk.core import helpers
+from projectname_sdk.feature.base_feature import ProjectNameBaseFeature
 
 _TEST_DIR = os.path.dirname(os.path.abspath(__file__))
 

package/project/.sdk/tm/py/test/test_struct_utility.py

@@ -13,8 +13,8 @@ from test.struct_runner import (
     StructTestClient,
 )
 
-from utility.voxgig_struct import voxgig_struct as vs
-from utility.voxgig_struct.voxgig_struct import (
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.voxgig_struct.voxgig_struct import (
     T_noval, T_scalar, T_function, T_symbol, T_any, T_node, T_instance, T_null,
 )
 
@@ -308,7 +308,7 @@ class TestStructUtility(unittest.TestCase):
 
 
     def test_minor_joinurl(self):
-        from utility.voxgig_struct.voxgig_struct import join as struct_join
+        from projectname_sdk.utility.voxgig_struct.voxgig_struct import join as struct_join
         runsetflags(minorSpec["join"], {"null": False},
             lambda vin: struct_join(vin.get("val"), vin.get("sep"), vin.get("url")))
 

package/project/.sdk/tm/py-data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) $$const.year$$ Voxgig
+
+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.
+

package/project/.sdk/tm/py-data/Makefile

@@ -0,0 +1,57 @@
+.PHONY: test build clean publish dev notebook
+
+# Install the sibling ProjectName SDK from the same repo (../py) plus this
+# package, both editable, so a working copy tests against the SDK it was
+# generated alongside rather than whatever is on PyPI.
+dev:
+	python3 -m pip install -e ../py
+	python3 -m pip install -e .
+
+test:
+	python3 -m pytest test/
+
+# Execute the generated quickstart notebook end to end. A quickstart that
+# does not run is a broken product, so this is part of `make test` in CI.
+notebook:
+	python3 -m jupyter nbconvert --to notebook --execute \
+	  --stdout notebooks/quickstart.ipynb > /dev/null && echo "quickstart.ipynb OK"
+
+build:
+	@echo "No build step for Python"
+
+clean:
+	find . -name __pycache__ -exec rm -rf {} + 2>/dev/null; true
+	rm -rf dist .pytest_cache
+
+# --- Release: publish to PyPI ---------------------------------------------
+# Publish this package to PyPI, then tag py-data/vX.Y.Z. Run headless under the
+# boru key vault, which injects the PyPI + GitHub tokens as environment
+# variables (never written to disk or argv):
+#   boru vault exec --for=pypi=<alias> --for=github=<alias> -- make publish
+# boru `--dry-run` injects a filler token we detect to rehearse: builds the dist
+# but performs no upload, tag, or push. set -e + tag-last: a failed upload never
+# leaves a tag behind. Needs python `build` + `twine` (pip install build twine).
+VERSION := $(shell sed -nE 's/^version *= *"([^"]+)".*/\1/p' pyproject.toml | head -1)
+TAG := py-data/v$(VERSION)
+BORU_DRY_RUN_FILLER := BORU-DRY-RUN-FILLER-NOT-A-REAL-SECRET
+publish: test
+	@if git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null; then \
+	  echo "tag $(TAG) already exists — bump pyproject.toml version first"; exit 1; fi
+	@set -e; \
+	token="$${GITHUB_TOKEN:-$$GH_TOKEN}"; \
+	rm -rf dist; \
+	python3 -m build; \
+	if [ "$$token" = "$(BORU_DRY_RUN_FILLER)" ] || [ "$$TWINE_PASSWORD" = "$(BORU_DRY_RUN_FILLER)" ]; then \
+	  echo "[dry-run] boru filler token detected: built the dist; would upload to PyPI and tag $(TAG); nothing pushed."; \
+	  exit 0; \
+	fi; \
+	python3 -m twine upload dist/*; \
+	git tag -a "$(TAG)" -m "py-data v$(VERSION)"; \
+	url=$$(git remote get-url origin | sed -E 's#^git@github.com:#https://github.com/#'); \
+	if [ -n "$$token" ] && printf '%s' "$$url" | grep -q '^https://github.com/'; then \
+	  hdr="AUTHORIZATION: basic $$(printf 'x-access-token:%s' "$$token" | base64 | tr -d '\n')"; \
+	  git -c http.extraheader="$$hdr" push "$$url" "$(TAG)"; \
+	else \
+	  git push origin "$(TAG)"; \
+	fi; \
+	echo "Published to PyPI + tag $(TAG)."

package/project/.sdk/tm/py-data/pkg/auth.py

@@ -0,0 +1,131 @@
+# ProjectName Data — credential discovery.
+#
+# `data()` must work in a fresh Colab cell with no arguments. Analysts do not
+# want to construct a client; they want a DataFrame. So the token and base
+# URL are looked up through a short, predictable chain and the failure
+# message TEACHES rather than merely reports.
+#
+# Kept generic (the SDK's env-var prefix is passed in) because this file is
+# copied verbatim per SDK — only `ProjectName` is substituted at generation
+# time, so nothing here may hardcode a per-API name.
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+NOT_FOUND = object()
+
+
+def from_colab(key: str) -> Any:
+    """Read a Colab secret, or NOT_FOUND.
+
+    Guarded three ways because every one of them bites in practice:
+    the import fails outside Colab; `userdata` raises SecretNotFoundError for
+    a key that was never set; and it raises NotebookAccessError when the
+    secret exists but the notebook has not been granted access to it (the
+    toggle in Colab's key panel). None of those are errors HERE — they just
+    mean "try the next source".
+    """
+    try:
+        from google.colab import userdata  # type: ignore
+    except Exception:
+        return NOT_FOUND
+    try:
+        val = userdata.get(key)
+    except Exception:
+        return NOT_FOUND
+    return val if val else NOT_FOUND
+
+
+def from_env(key: str) -> Any:
+    val = os.environ.get(key)
+    return val if val else NOT_FOUND
+
+
+def resolve(
+    prefix: str,
+    token: str | None = None,
+    base_url: str | None = None,
+    *,
+    token_key: str | None = None,
+    base_key: str | None = None,
+) -> tuple:
+    """(token, base_url, source) from args, then Colab secrets, then env.
+
+    `prefix` is the SDK's upper-snake name, e.g. ACME -> ACME_APIKEY /
+    ACME_BASE. Returns the raw values; validation is the caller's job so it
+    can decide whether a missing base_url is fatal (multi-tenant APIs) or
+    fine (the model's default applies).
+    """
+    tkey = token_key or f"{prefix}_APIKEY"
+    bkey = base_key or f"{prefix}_BASE"
+
+    source = "argument"
+    tok: Any = token if token else NOT_FOUND
+
+    if tok is NOT_FOUND:
+        tok = from_colab(tkey)
+        source = "colab"
+    if tok is NOT_FOUND:
+        tok = from_env(tkey)
+        source = "env"
+
+    base: Any = base_url if base_url else NOT_FOUND
+    if base is NOT_FOUND:
+        base = from_colab(bkey)
+    if base is NOT_FOUND:
+        base = from_env(bkey)
+
+    return (
+        None if tok is NOT_FOUND else tok,
+        None if base is NOT_FOUND else base,
+        None if tok is NOT_FOUND else source,
+    )
+
+
+def missing_token_message(prefix: str, token_key: str | None = None) -> str:
+    """The error an analyst sees when no credential was found.
+
+    Shows the exact lines to run for THIS SDK in both environments. A generic
+    "credentials not found" costs the reader a trip to the README; this costs
+    them a copy-paste.
+    """
+    tkey = token_key or f"{prefix}_APIKEY"
+    return (
+        f"No API credential found for ProjectName.\n"
+        f"\n"
+        f"In Google Colab — open the key panel (left sidebar), add a secret\n"
+        f"named {tkey}, and enable notebook access for it. Or set it in code:\n"
+        f"\n"
+        f"    from google.colab import userdata\n"
+        f"    userdata.set('{tkey}', 'your-api-key')\n"
+        f"\n"
+        f"Elsewhere (Jupyter, a script, a terminal):\n"
+        f"\n"
+        f"    import os\n"
+        f"    os.environ['{tkey}'] = 'your-api-key'\n"
+        f"\n"
+        f"Or pass it directly:\n"
+        f"\n"
+        f"    data(token='your-api-key')\n"
+    )
+
+
+def missing_base_message(prefix: str, base_key: str | None = None) -> str:
+    """The error for a multi-tenant API with no base URL.
+
+    Only raised when the model's server URL carries an unresolved
+    placeholder, i.e. the API genuinely has no single host and every customer
+    has their own instance. Guessing one would produce confusing 404s.
+    """
+    bkey = base_key or f"{prefix}_BASE"
+    return (
+        f"ProjectName is multi-tenant: it has no single API host, so the base\n"
+        f"URL for YOUR instance is required.\n"
+        f"\n"
+        f"    data(base_url='https://your-instance.example.com')\n"
+        f"\n"
+        f"or set {bkey} as a Colab secret / environment variable.\n"
+    )

package/project/.sdk/tm/py-data/pkg/fetch.py

@@ -0,0 +1,178 @@
+# ProjectName Data — eager paging drain.
+#
+# Analysts want the whole table now. Lazy iterators are application
+# ergonomics: correct for a service processing a stream, wrong for someone
+# who typed `df = ad.things()` and wants to run a groupby on the next line.
+#
+# This module owns NO pagination knowledge. The sibling SDK's `paging`
+# feature already normalises every server dialect it understands — a
+# `Link: rel="next"` header, X-Page / X-Next-Page / X-Total-Count, or body
+# `next` / `cursor` / `nextCursor` / `hasMore` — onto `result.paging`, and
+# records the last one on the client. All we do is drive it to exhaustion by
+# feeding the cursor/page back in through the per-call `ctrl.paging` hook,
+# which exists for exactly this purpose.
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Callable
+
+
+# Safety backstop. A server that always reports "more" (or a cursor that
+# never advances) would otherwise loop forever inside a notebook cell with
+# no output. Hitting this is always reported, never silent.
+MAX_PAGES_DEFAULT = 1000
+
+
+def in_notebook() -> bool:
+    """True when running under IPython/Jupyter/Colab with a display."""
+    try:
+        from IPython import get_ipython  # type: ignore
+    except Exception:
+        return False
+    ip = get_ipython()
+    if ip is None:
+        return False
+    return hasattr(ip, "kernel")
+
+
+def _progress(count: int, pages: int, quiet: bool) -> None:
+    if quiet:
+        return
+    # Deliberately not tqdm: an extra hard dependency for a progress bar is a
+    # bad trade in an environment that reinstalls every dependency on every
+    # session start. A rewritten stderr line costs nothing and works in both
+    # notebooks and plain terminals.
+    sys.stderr.write(f"\r  fetched {count} rows ({pages} pages)…")
+    sys.stderr.flush()
+
+
+def _progress_done(count: int, pages: int, quiet: bool) -> None:
+    if quiet:
+        return
+    sys.stderr.write(f"\r  fetched {count} rows ({pages} pages)   \n")
+    sys.stderr.flush()
+
+
+def drain(
+    call: Callable[[dict], Any],
+    client: Any,
+    *,
+    limit: int | None = None,
+    max_pages: int = MAX_PAGES_DEFAULT,
+    quiet: bool = False,
+    progress_after: int = 1,
+) -> list:
+    """Call `call(ctrl)` until the server stops offering more.
+
+    call        — invoked with a ctrl dict; returns one page of records
+    client      — the SDK client, read for `_paging` (set by the paging feature)
+    limit       — stop once this many rows are collected (None = all)
+    max_pages   — backstop; a warning is emitted if it is reached
+    quiet       — suppress progress output
+    progress_after — only show progress once this many pages have been fetched,
+                  so the common single-page case prints nothing at all
+
+    Returns the accumulated records.
+
+    When the SDK's paging feature is INACTIVE there is no `_paging` state, so
+    this makes exactly one call and returns it — the correct degradation, not
+    an error. An SDK without paging configured genuinely has one page.
+    """
+    rows: list = []
+    ctrl: dict = {}
+    pages = 0
+    seen_cursors: set = set()
+    hit_max = False
+
+    while True:
+        page = call(ctrl)
+        pages += 1
+
+        if page is None:
+            batch = []
+        elif isinstance(page, (list, tuple)):
+            batch = list(page)
+        else:
+            batch = [page]
+
+        rows.extend(batch)
+
+        if pages >= progress_after + 1:
+            _progress(len(rows), pages, quiet)
+
+        if limit is not None and len(rows) >= limit:
+            rows = rows[:limit]
+            break
+
+        paging = _last_paging(client)
+        if not paging or not paging.get("hasMore"):
+            break
+
+        # An empty page that still claims more would spin forever.
+        if len(batch) == 0:
+            break
+
+        nxt = _next_ctrl(paging)
+        if nxt is None:
+            break
+
+        # A cursor that repeats means the server is not advancing. Stopping
+        # beats looping: the analyst gets the rows fetched so far, plus a
+        # warning, instead of a hung cell.
+        token = repr(sorted(nxt.get("paging", {}).items()))
+        if token in seen_cursors:
+            _warn("pagination stopped advancing (repeated cursor) — "
+                  f"returning the {len(rows)} rows fetched so far")
+            break
+        seen_cursors.add(token)
+
+        if pages >= max_pages:
+            hit_max = True
+            break
+
+        ctrl = nxt
+
+    if pages >= progress_after + 1:
+        _progress_done(len(rows), pages, quiet)
+
+    if hit_max:
+        _warn(f"stopped at max_pages={max_pages} with {len(rows)} rows; the "
+              "server still reported more. Pass max_pages= to raise the cap, "
+              "or limit= to take a defined slice.")
+
+    return rows
+
+
+def _last_paging(client: Any) -> dict | None:
+    """The paging state the SDK's paging feature recorded on the client."""
+    state = getattr(client, "_paging", None)
+    if not isinstance(state, dict):
+        return None
+    last = state.get("last")
+    return last if isinstance(last, dict) else None
+
+
+def _next_ctrl(paging: dict) -> dict | None:
+    """Build the ctrl for the next page from the recorded paging state.
+
+    Cursor wins over page number: when a server offers both, the cursor is
+    the one with consistency guarantees.
+    """
+    cursor = paging.get("cursor")
+    if cursor is not None:
+        return {"paging": {"cursor": cursor}}
+
+    next_page = paging.get("nextPage")
+    if next_page is not None:
+        return {"paging": {"page": next_page}}
+
+    # A `Link: rel="next"` URL with no cursor/page extracted is not something
+    # we can turn into a ctrl — the SDK builds its own request URLs. Rather
+    # than guess at query parsing, stop and keep what we have.
+    return None
+
+
+def _warn(msg: str) -> None:
+    import warnings
+    warnings.warn(f"ProjectName data: {msg}", stacklevel=3)