exdrf-gen-openapi2rtk 0.1.17__py3-none-any.whl

exdrf_gen_openapi2rtk/__init__.py

@@ -0,0 +1,77 @@
+"""exdrf-gen plugin: RTK Query TypeScript from OpenAPI."""
+
+from __future__ import annotations
+
+import os
+
+import click
+from click import Context
+
+from exdrf_gen.cli_base import cli
+from exdrf_gen.plugin_support import install_plugin
+from exdrf_gen_openapi2rtk.creator import run_openapi2rtk
+
+install_plugin(
+    template_paths=[
+        os.path.join(os.path.dirname(__file__), "openapi2rtk_templates"),
+    ],
+)
+
+
+@cli.command(name="openapi2rtk")
+@click.argument(
+    "routes_out_dir",
+    type=click.Path(file_okay=False, dir_okay=True),
+    envvar="EXDRF_OPENAPI2RTK_ROUTES_DIR",
+)
+@click.option(
+    "--openapi-file",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="Path to a local openapi.json (or use --openapi-url).",
+)
+@click.option(
+    "--openapi-url",
+    default=None,
+    help="HTTP(S) URL to fetch OpenAPI JSON (requires --cache-file).",
+)
+@click.option(
+    "--cache-file",
+    type=click.Path(dir_okay=False),
+    default=None,
+    help="Cache path for --openapi-url downloads and ETag metadata.",
+)
+@click.option(
+    "--types-import",
+    default="@resi/models",
+    show_default=True,
+    help="Module path passed to emitted ``from '…'`` type imports.",
+)
+@click.option(
+    "--base-api-profile",
+    type=click.Choice(["minimal", "fr_one"]),
+    default="minimal",
+    show_default=True,
+    help=("``fr_one`` matches fr-one auth/baseUrl wiring; ``minimal`` is generic."),
+)
+@click.pass_context
+def openapi2rtk(
+    context: Context,
+    routes_out_dir: str,
+    openapi_file: str | None,
+    openapi_url: str | None,
+    cache_file: str | None,
+    types_import: str,
+    base_api_profile: str,
+) -> None:
+    """Generate RTK Query route modules from an OpenAPI document."""
+
+    run_openapi2rtk(
+        context,
+        routes_out_dir,
+        openapi_file,
+        openapi_url,
+        cache_file,
+        types_import,
+        base_api_profile,
+    )

exdrf_gen_openapi2rtk/__version__.py

@@ -0,0 +1,24 @@
+"""Package version from PEP 621 or installed metadata."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from exdrf.pep621_version import distribution_version, version_tuple_from_string
+
+_PYPROJECT = Path(__file__).resolve().parents[1] / "pyproject.toml"
+_DIST_NAME = "exdrf-gen-openapi2rtk"
+
+__version__ = version = distribution_version(_DIST_NAME, _PYPROJECT)
+__version_tuple__ = version_tuple = version_tuple_from_string(__version__)
+
+__commit_id__ = commit_id = None
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]

exdrf_gen_openapi2rtk/creator.py

@@ -0,0 +1,314 @@
+"""Emit RTK Query TypeScript from a parsed OpenAPI document."""
+
+from __future__ import annotations
+
+import logging
+import re
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Mapping
+
+import click
+from attrs import define, field
+
+from exdrf_gen.fs_support import Base, Dir, File
+from exdrf_gen_openapi2rtk.endpoint_keys import assert_unique_rtk_endpoint_keys
+from exdrf_gen_openapi2rtk.openapi_cache import (
+    fetch_openapi_url_cached,
+    load_openapi_from_file,
+)
+from exdrf_gen_openapi2rtk.spec_routes import (
+    GenRoute,
+    routes_by_primary_tag,
+    tag_file_stem,
+)
+
+if TYPE_CHECKING:
+    from jinja2 import Environment
+
+logger = logging.getLogger(__name__)
+
+_IN_STATE = {"tenant": "Tenant"}
+
+
+def _restrict_templates_to_package(env: "Environment", suffix: str) -> None:
+    """Limit Jinja search paths to this package's template directory."""
+
+    loader = getattr(env, "loader", None)
+    if loader is None:
+        return
+    paths = list(getattr(loader, "paths", []))
+    filtered = [p for p in paths if str(p).endswith(suffix)]
+    setattr(loader, "paths", filtered)
+
+
+def _category_camel(tag: str) -> str:
+    """Derive ``c_camel`` from a primary OpenAPI tag string."""
+
+    if not tag:
+        return tag
+    return tag[0].lower() + tag[1:]
+
+
+def _used_schema_names(routes: list[GenRoute]) -> list[str]:
+    """Collect named schema tokens imported from ``types_import``."""
+
+    names: set[str] = set()
+    for r in routes:
+        if r.body_m:
+            names.add(r.body_m.name)
+        if re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", r.response_ts):
+            names.add(r.response_ts)
+    return sorted(names)
+
+
+def _build_api_bundle(
+    category: str,
+    routes: list[GenRoute],
+    *,
+    types_import: str,
+    m_name: str,
+) -> dict[str, Any]:
+    """Assemble the Jinja context for one per-tag ``*.ts`` module."""
+
+    assert_unique_rtk_endpoint_keys(category, routes)
+
+    c_snake = tag_file_stem(category)
+    c_camel = _category_camel(category)
+    uses_list_query_contract = any(
+        r.body_schema_name == "ListQueryRequest" for r in routes
+    )
+    used_res_names = _used_schema_names(routes)
+
+    global_sourced = {
+        **{
+            arg: f"(api.getState() as LocalState).runtime.{arg}.id" for arg in _IN_STATE
+        },
+    }
+
+    def has_local_state(rs: list[GenRoute]) -> bool:
+        """True when any route body references ``_IN_STATE`` keys."""
+
+        for r in rs:
+            if r.body_m:
+                for fld in r.body_m.fields:
+                    if fld.name in _IN_STATE:
+                        return True
+        return False
+
+    def get_local_state(fld: Any) -> str:
+        """Map a body field to its global-state TypeScript type label."""
+
+        return _IN_STATE[fld.name]
+
+    def get_arg(arg: str) -> str:
+        """Build the JavaScript expression for one request argument."""
+
+        if arg in global_sourced:
+            return global_sourced[arg]
+        return "args." + arg
+
+    arg_pattern = re.compile(r"\{([^}]+)\}")
+
+    def get_route(route: GenRoute) -> str:
+        """Interpolate path and query template literals for RTK ``url``."""
+
+        result = arg_pattern.sub(
+            lambda m: "${" + get_arg(m.group(1)) + "}",
+            route.path,
+        )
+        if route.query_args:
+            result += "?" + "&".join(
+                q[0] + "=${" + get_arg(q[0]) + "}" for q in route.query_args
+            )
+        return result
+
+    def get_arg_type(route: GenRoute) -> str:
+        """Return the precomputed RTK args type for ``route``."""
+
+        return route.arg_type_ts
+
+    def get_response_type(route: GenRoute) -> str:
+        """Return the precomputed RTK response type for ``route``."""
+
+        return route.response_ts
+
+    def get_body_arg_names(route: GenRoute) -> list[str]:
+        """Return JSON body property names for ``route``."""
+
+        if route.body_m:
+            return [f.name for f in route.body_m.fields]
+        return [n for n, _ in route.body_args]
+
+    kind_str = ["mutation" if r.is_mutation else "query" for r in routes]
+
+    return {
+        "tag_snake": c_snake,
+        "category": category,
+        "routes": routes,
+        "c_snake": c_snake,
+        "c_camel": c_camel,
+        "r_count": len(routes),
+        "r_snake": [r.name_snake_case for r in routes],
+        "r_camel": [r.name_camel for r in routes],
+        "r_pascal": [r.name_pascal for r in routes],
+        "uses_list_query_contract": uses_list_query_contract,
+        "used_res_names": used_res_names,
+        "used_res": {n: None for n in used_res_names},
+        "kind_str": kind_str,
+        "global_sourced": global_sourced,
+        "get_arg": get_arg,
+        "get_route": get_route,
+        "get_arg_type": get_arg_type,
+        "get_response_type": get_response_type,
+        "get_local_state": get_local_state,
+        "has_local_state": has_local_state,
+        "get_body_arg_names": get_body_arg_names,
+        "in_state": _IN_STATE,
+        "types_import": types_import,
+        "m_name": m_name,
+    }
+
+
+@define
+class _RoutesPackageDir(Base):
+    """Emit ``index.ts`` plus one ``{tag_snake}.ts`` file per OpenAPI tag."""
+
+    name: str = field()
+    bundles: list[dict[str, Any]] = field(factory=list)
+    extra: dict[str, Any] = field(factory=dict)
+
+    def generate(self, out_path: str, **kwargs: Any) -> None:
+        """Create the routes directory and all per-tag RTK modules."""
+
+        mapping = {**self.extra, **kwargs}
+        c_path = self.create_directory(out_path, self.name, **mapping)
+        env = mapping["env"]
+        child_kw = {k: v for k, v in mapping.items() if k != "env"}
+        File("index.ts", "openapi2rtk/index.ts.j2").generate(
+            c_path,
+            env=env,
+            **child_kw,
+        )
+        for b in self.bundles:
+            File("{tag_snake}.ts", "openapi2rtk/api.ts.j2").generate(
+                c_path,
+                env=env,
+                **{**child_kw, **b},
+            )
+
+
+def generate_openapi2rtk(
+    spec: Mapping[str, Any],
+    routes_out_dir: str,
+    env: "Environment",
+    *,
+    types_import: str,
+    base_api_profile: str,
+    m_name: str,
+) -> None:
+    """Write RTK route modules and shared helpers next to ``routes_out_dir``."""
+
+    by_category = routes_by_primary_tag(spec)
+    if not by_category:
+        logger.warning(
+            "OpenAPI document produced no tagged operations; no TS files.",
+        )
+
+    bundles: list[dict[str, Any]] = []
+    for cat in sorted(by_category):
+        routes = by_category[cat]
+        if not routes:
+            continue
+        bundles.append(
+            _build_api_bundle(
+                cat,
+                routes,
+                types_import=types_import,
+                m_name=m_name,
+            )
+        )
+
+    c_keys = sorted(by_category.keys())
+    c_camel = [_category_camel(c) for c in c_keys]
+    c_snake = [tag_file_stem(c) for c in c_keys]
+    glb_vars: dict[str, Any] = {
+        "c_count": len(c_keys),
+        "c_keys": c_keys,
+        "c_snake": c_snake,
+        "c_camel": c_camel,
+        "categories": by_category,
+        "m_name": m_name,
+    }
+
+    routes_path = Path(routes_out_dir)
+    parent = str(routes_path.parent)
+    routes_folder_name = routes_path.name
+
+    base_tpl = (
+        "openapi2rtk/base-api.fr_one.ts.j2"
+        if base_api_profile == "fr_one"
+        else "openapi2rtk/base-api.minimal.ts.j2"
+    )
+
+    root = Dir(
+        name="",
+        comp=[
+            File(
+                "list-query-contract.ts",
+                "openapi2rtk/list-query-contract.ts.j2",
+            ),
+            File("base-api.ts", base_tpl),
+            File("cacheUtils.ts", "openapi2rtk/cacheUtils.ts.j2"),
+            _RoutesPackageDir(
+                name=routes_folder_name,
+                bundles=bundles,
+            ),
+        ],
+    )
+    root.generate(
+        parent,
+        env=env,
+        **glb_vars,
+    )
+
+
+def run_openapi2rtk(
+    context: click.Context,
+    routes_out_dir: str,
+    openapi_file: str | None,
+    openapi_url: str | None,
+    cache_file: str | None,
+    types_import: str,
+    base_api_profile: str,
+) -> None:
+    """CLI entry: load spec, then emit RTK TypeScript."""
+
+    env = context.obj["jinja_env"]
+    _restrict_templates_to_package(env, "openapi2rtk_templates")
+
+    if openapi_file:
+        spec = load_openapi_from_file(openapi_file)
+    elif openapi_url:
+        if not cache_file:
+            click.echo(
+                "--cache-file is required when using --openapi-url.",
+                err=True,
+            )
+            sys.exit(1)
+        spec = fetch_openapi_url_cached(openapi_url, Path(cache_file))
+    else:
+        click.echo(
+            "Provide --openapi-file or --openapi-url (with --cache-file).",
+            err=True,
+        )
+        sys.exit(1)
+
+    generate_openapi2rtk(
+        spec,
+        routes_out_dir,
+        env,
+        types_import=types_import,
+        base_api_profile=base_api_profile,
+        m_name="exdrf_gen_openapi2rtk.creator",
+    )

exdrf_gen_openapi2rtk/endpoint_keys.py

@@ -0,0 +1,29 @@
+"""RTK ``injectEndpoints`` key uniqueness for OpenAPI-derived routes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def assert_unique_rtk_endpoint_keys(category: str, routes: list[Any]) -> None:
+    """Fail fast when two routes would share the same RTK endpoint object key.
+
+    Args:
+        category: OpenAPI primary tag / grouping label for the emitted file.
+        routes: Route objects with ``name_camel`` (camelCase operation key).
+
+    Raises:
+        ValueError: When two routes share the same ``name_camel``.
+    """
+
+    seen: dict[str, str] = {}
+    for route in routes:
+        key = route.name_camel
+        if key in seen:
+            raise ValueError(
+                "Duplicate RTK endpoint key %r in category %r: paths %r vs %r. "
+                "Adjust ``operationId`` values or OpenAPI tags so keys are "
+                "unique within each emitted module."
+                % (key, category, seen[key], getattr(route, "path", "?"))
+            )
+        seen[key] = getattr(route, "path", "?")

exdrf_gen_openapi2rtk/openapi2rtk_templates/openapi2rtk/api.ts.j2

@@ -0,0 +1,112 @@
+// This file was automatically generated using exdrf-gen-openapi2rtk.
+// Source: {{ m_name }}
+// Don't change it manually.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { BaseQueryApi } from '@reduxjs/toolkit/query';
+import { apiBase } from '../base-api';
+import {
+    providesNestedList,
+    cacheByIdArgProperty,
+    invalidateByIdArgPropertyAndList,
+} from '../cacheUtils';
+{%- if uses_list_query_contract %}
+import type { ListQueryRequest } from '../list-query-contract';
+{%- endif %}
+{%- for res_name in used_res_names %}
+import { {{ res_name }} } from '{{ types_import }}';
+{%- endfor %}
+
+{%- if has_local_state(routes) -%}
+{% set name_seen = {} %}
+
+export interface LocalState {
+    runtime: {
+        {%- for i in range(r_count) -%}
+        {%- for field in routes[i].body_m.fields -%}
+        {%- if field.name in in_state and field.name not in name_seen -%}
+        {%- set _ = name_seen.update({field.name: true}) %}
+        {{ field.name }}: {{ get_local_state(field) }};
+        {% endif -%}
+        {%- endfor -%}
+        {%- endfor %}
+    }
+}
+{% endif %}
+
+apiBase.enhanceEndpoints({
+    addTagTypes: ['{{ category.capitalize() }}']
+});
+
+
+export const {{ c_camel }}Api = apiBase.injectEndpoints({
+    endpoints: (build) => ({
+        {%- for i in range(r_count) %}
+
+            /**
+            {% for line in routes[i].doc_lines %} * {{ line }}
+            {% endfor %} */
+            {{ r_camel[i] }}: build.{{ kind_str[i] }}<{{ get_response_type(routes[i]) }}, {{
+                get_arg_type(routes[i])
+            }}>({
+                queryFn: async (
+                    args,
+                    api: BaseQueryApi,
+                    extraOptions: any,  // eslint-disable-line
+                    usingBase
+                ) => {
+                    return usingBase({
+                        url: `{{ get_route(routes[i]) }}`,
+                        method: '{{ routes[i].method.name }}',
+                        {%- if routes[i].body_m %}
+                        body: {
+                        {%- for arg_name in get_body_arg_names(routes[i]) %}
+                            {{ arg_name }}: {{ get_arg(arg_name) }},
+                        {%- endfor %}
+                        },
+                        {%- elif routes[i].body_args %}
+                        body: {
+                        {%- for arg_name in get_body_arg_names(routes[i]) %}
+                            {{ arg_name }}: {{ get_arg(arg_name) }},
+                        {%- endfor %}
+                        },
+                        {%- endif %}
+                    });
+                },
+                {% if r_camel[i].startswith('create') -%}
+                invalidatesTags: [
+                    { type: '{{ category.capitalize() }}', id: 'LIST' },
+                    { type: '{{ category.capitalize() }}', id: 'Q-LIST' }
+                ] as any,
+                {%- elif r_camel[i].startswith('remove') -%}
+                invalidatesTags: [
+                    { type: '{{ category.capitalize() }}', id: 'LIST' },
+                    { type: '{{ category.capitalize() }}', id: 'Q-LIST' }
+                ] as any,
+                {%- elif r_camel[i].startswith('listQuick') -%}
+                providesTags: [{ type: '{{ category.capitalize() }}', id: 'Q-LIST' }] as any,
+                {%- elif routes[i].name.startswith('query_') -%}
+                providesTags: providesNestedList('{{ category.capitalize() }}') as any,
+                {%- elif r_camel[i].startswith('list') -%}
+                providesTags: providesNestedList('{{ category.capitalize() }}') as any,
+                {%- elif r_camel[i].startswith('read') -%}
+                providesTags: cacheByIdArgProperty('{{ category.capitalize() }}') as any,
+                {%- elif r_camel[i].startswith('get') -%}
+                providesTags: cacheByIdArgProperty('{{ category.capitalize() }}') as any,
+                {%- elif r_camel[i].startswith('update') -%}
+                invalidatesTags: invalidateByIdArgPropertyAndList('{{ category.capitalize() }}') as any,
+                {%- endif %}
+            }),
+        {%- endfor %}
+    }),
+    overrideExisting: false,
+});{{'\n'}}
+
+
+export const {
+    {%- for i in range(r_count) %}
+    use{{ r_pascal[i] }}{{ kind_str[i] | capitalize }},
+    {%- if kind_str[i]  == 'query' %}
+    useLazy{{ r_pascal[i] }}{{ kind_str[i] | capitalize }},
+    {%- endif -%}
+    {%- endfor %}
+} = {{ c_camel }}Api;

exdrf_gen_openapi2rtk/openapi2rtk_templates/openapi2rtk/base-api.fr_one.ts.j2

@@ -0,0 +1,61 @@
+// This file was automatically generated using exdrf-gen-openapi2rtk.
+// Source: {{ m_name }}
+// Don't change it manually.
+import { refreshHttpAccessTokenSingleFlight } from '@fr-one/shared-comms';
+import { getRtkAccessToken } from '@fr-one/shared-sec';
+import { getDefaultPublicEnv } from '@fr-one/core-config';
+import type {
+  BaseQueryFn,
+  FetchArgs,
+  FetchBaseQueryError,
+} from '@reduxjs/toolkit/query';
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
+
+const rawBaseQuery = fetchBaseQuery({
+  baseUrl: getDefaultPublicEnv().apiBaseUrl,
+  credentials: 'include',
+  prepareHeaders: (headers) => {
+    const token = getRtkAccessToken();
+    if (token) {
+      headers.set('Authorization', `Bearer ${token}`);
+    }
+    return headers;
+  },
+});
+
+/**
+ * Retries once after a cookie-backed refresh when RTK sees HTTP 401.
+ */
+const baseQueryWithReauth: BaseQueryFn<
+  string | FetchArgs,
+  unknown,
+  FetchBaseQueryError
+> = async (args, api, extraOptions) => {
+  const result = await rawBaseQuery(args, api, extraOptions);
+  if (
+    result.error &&
+    typeof result.error === 'object' &&
+    'status' in result.error &&
+    result.error.status === 401
+  ) {
+    const newTok = await refreshHttpAccessTokenSingleFlight();
+    if (newTok) {
+      return rawBaseQuery(args, api, extraOptions);
+    }
+  }
+  return result;
+};
+
+/**
+ * Shared RTK Query API instance used by generated route clients.
+ *
+ * It points to the runtime API base URL and keeps endpoint registration open
+ * for route-category files generated under `generated/routes`.
+ */
+export const apiBase = createApi({
+  reducerPath: 'generatedApi',
+  refetchOnFocus: true,
+  refetchOnReconnect: true,
+  baseQuery: baseQueryWithReauth,
+  endpoints: () => ({}),
+});

exdrf_gen_openapi2rtk/openapi2rtk_templates/openapi2rtk/base-api.minimal.ts.j2

@@ -0,0 +1,40 @@
+// This file was automatically generated using exdrf-gen-openapi2rtk.
+// Source: {{ m_name }}
+// Don't change it manually.
+//
+// Minimal RTK base for hosts that wire auth/baseUrl outside this package.
+import type {
+  BaseQueryFn,
+  FetchArgs,
+  FetchBaseQueryError,
+} from '@reduxjs/toolkit/query';
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
+
+declare const __OPENAPI2RTK_API_BASE_URL__: string | undefined;
+
+const baseUrl =
+  (typeof __OPENAPI2RTK_API_BASE_URL__ === 'string' &&
+    __OPENAPI2RTK_API_BASE_URL__) ||
+  '';
+
+const rawBaseQuery = fetchBaseQuery({
+  baseUrl,
+  credentials: 'include',
+});
+
+const baseQuery: BaseQueryFn<
+  string | FetchArgs,
+  unknown,
+  FetchBaseQueryError
+> = async (args, api, extraOptions) => rawBaseQuery(args, api, extraOptions);
+
+/**
+ * Shared RTK Query API instance used by generated route clients.
+ */
+export const apiBase = createApi({
+  reducerPath: 'generatedApi',
+  refetchOnFocus: true,
+  refetchOnReconnect: true,
+  baseQuery,
+  endpoints: () => ({}),
+});