openapi-client-codegen 0.3.3.dev87__tar.gz → 0.3.3.dev91__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/AGENTS.md +6 -4
  2. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/PKG-INFO +1 -1
  3. openapi_client_codegen-0.3.3.dev91/README.md +3 -0
  4. openapi_client_codegen-0.3.3.dev91/design/AGENTS.md +8 -0
  5. openapi_client_codegen-0.3.3.dev91/design/typescript-fetch-generator-plan.md +61 -0
  6. openapi_client_codegen-0.3.3.dev91/design/typescript-fetch-generator.md +121 -0
  7. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/pyproject.toml +1 -1
  8. openapi_client_codegen-0.3.3.dev91/src/openapi_client_codegen/_data/configs/typescript-fetch.json +13 -0
  9. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/cli.py +1 -0
  10. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/client.py +13 -0
  11. openapi_client_codegen-0.3.3.dev91/src/openapi_client_codegen/npm.py +23 -0
  12. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/orchestrator.py +1 -0
  13. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/tests/test_cli.py +1 -0
  14. openapi_client_codegen-0.3.3.dev91/tests/test_npm.py +51 -0
  15. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/tests/test_orchestrate.py +90 -1
  16. openapi_client_codegen-0.3.3.dev87/README.md +0 -3
  17. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/.gitattributes +0 -0
  18. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/.github/workflows/cleanup-pr-releases.yml +0 -0
  19. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/.github/workflows/integrate.yml +0 -0
  20. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/.github/workflows/merge-gate.yml +0 -0
  21. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/.github/workflows/release.yml +0 -0
  22. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/.gitignore +0 -0
  23. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/.python-version +0 -0
  24. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/CLAUDE.md +0 -0
  25. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/LICENSE +0 -0
  26. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/NOTICE +0 -0
  27. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/publish.yml +0 -0
  28. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/ruff.base.toml +0 -0
  29. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/ruff.toml +0 -0
  30. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/scripts/preflight.py +0 -0
  31. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/__init__.py +0 -0
  32. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/configs/csharp.json +0 -0
  33. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/configs/python.json +0 -0
  34. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/openapi-generator-ignore +0 -0
  35. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/templates-patches/csharp/0001-csharp-remove-errant-comma.patch +0 -0
  36. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/templates-patches/csharp/0002-csharp-models-required-only-constructors.patch +0 -0
  37. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/templates-patches/csharp/0003-csharp-httpclient-use-defaultT.patch +0 -0
  38. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/templates-patches/csharp/0004-csharp-support-hybrid-multipart-payloads.patch +0 -0
  39. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/templates-patches/csharp/0006-csharp-streaming-download-response.patch +0 -0
  40. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/templates-patches/csharp/0007-csharp-model-default-initializers.patch +0 -0
  41. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/_data/templates-patches/csharp/0008-csharp-redirect-documentation-file.patch +0 -0
  42. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/downgrade.py +0 -0
  43. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/py.typed +0 -0
  44. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/resources.py +0 -0
  45. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/templates.py +0 -0
  46. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/src/openapi_client_codegen/unity.py +0 -0
  47. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/tests/test_config.py +0 -0
  48. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/tests/test_downgrade.py +0 -0
  49. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/tests/test_unity.py +0 -0
  50. {openapi_client_codegen-0.3.3.dev87 → openapi_client_codegen-0.3.3.dev91}/uv.lock +0 -0
@@ -2,19 +2,20 @@
2
2
 
3
3
  ## What this is
4
4
 
5
- `openapi-client-codegen` wraps [OpenAPI Generator](https://openapi-generator.tech/) to turn an OpenAPI schema into typed client packages — a Python (`httpx`) client and a Unity-consumable C# (`httpclient`) client. It owns every step that is generic across consumers: the project orchestration loop, downgrading 3.1→3.0, the committed-spec unchanged skip, authoring and patching the C# templates, running the generator, and writing the Unity package metadata. The caller owns what is inherently project-specific: **producing the OpenAPI spec** (a command string in the consumer's config, run by the library's `SpecProducer`), the project→client mapping, the naming root, the npm scope, license, repository URL, and the generated output root.
5
+ `openapi-client-codegen` wraps [OpenAPI Generator](https://openapi-generator.tech/) to turn an OpenAPI schema into typed client packages — a Python (`httpx`) client, a Unity-consumable C# (`httpclient`) client, and a browser TypeScript (`typescript-fetch`) client (native `fetch`, zero runtime deps). It owns every step that is generic across consumers: the project orchestration loop, downgrading 3.1→3.0, the committed-spec unchanged skip, authoring and patching the C# templates, running the generator, and writing the Unity/npm package metadata. The caller owns what is inherently project-specific: **producing the OpenAPI spec** (a command string in the consumer's config, run by the library's `SpecProducer`), the project→client mapping, the naming root, the package scopes, license, repository URL, and the generated output root.
6
6
 
7
7
  The package is `openapi_client_codegen` (src-layout under `src/openapi_client_codegen/`). Python dependencies: `bashrun`, `packaging` (`requires` specifier parsing), `pydantic` (config schema), `strictyaml` (config loading), `typer` (thin CLI) — all from PyPI; git-source pins only in scratch branches testing unreleased changes. At **runtime** it also needs **Java (JDK 11+)** and **`uvx`** on PATH — the generator itself runs as `uvx --from 'openapi-generator-cli[jdk4py]==<pin>' ...`.
8
8
 
9
9
  ## Public API
10
10
 
11
- The package init is empty (RUF067 strict mode); import each symbol from its defining module: `client` (`generate_client`), `cli` (`app`), `downgrade` (`downgrade_openapi_3_1_to_3_0`, `JsonDict`), `orchestrator` (`ProjectsConfig`, `ClientNaming`, `SpecProducer`, `load_config`), `templates` (`regenerate_templates`), `unity` (`write_unity_package_metadata`).
11
+ The package init is empty (RUF067 strict mode); import each symbol from its defining module: `client` (`generate_client`), `cli` (`app`), `downgrade` (`downgrade_openapi_3_1_to_3_0`, `JsonDict`), `npm` (`write_npm_package_metadata`), `orchestrator` (`ProjectsConfig`, `ClientNaming`, `SpecProducer`, `load_config`), `templates` (`regenerate_templates`), `unity` (`write_unity_package_metadata`).
12
12
 
13
- - `ProjectsConfig` is the pydantic schema of a consumer's config (`extra="forbid"`) and the single source of identity — the CLI validates `--config` into it and nothing overrides it per invocation. Required: `projects` (project path → generator list), `root_name`, `generated_root`, `spec_command`, `requires` (a PEP 440 specifier; `load_config` self-checks the installed version and refuses outside range; "no constraint" is explicit `requires: ">=0.0"`; the `0.0.0.dev0` dev sentinel bypasses the check, not the field's presence). Optional: `spec_env`, `npm_scope`, `license_spdx`, `repository_url`.
13
+ - `ProjectsConfig` is the pydantic schema of a consumer's config (`extra="forbid"`) and the single source of identity — the CLI validates `--config` into it and nothing overrides it per invocation. Required: `projects` (project path → generator list), `root_name`, `generated_root`, `spec_command`, `requires` (a PEP 440 specifier; `load_config` self-checks the installed version and refuses outside range; "no constraint" is explicit `requires: ">=0.0"`; the `0.0.0.dev0` dev sentinel bypasses the check, not the field's presence). Optional: `spec_env`, `npm_scope` (UPM, csharp-only), `typescript_npm_scope` (bare npm org, no `@`), `license_spdx`, `repository_url`.
14
14
  - The CLI (`app`, single command, no subcommand; consumer `[project.scripts]` aliases point at it, e.g. placeframe's `generate-clients`) orchestrates per mapping entry: produce the spec via the config-built `SpecProducer` → downgrade 3.1→3.0 → write `<project>/openapi.json` unless byte-identical to the committed spec (`--no-cache` forces through) → `generate_client` per listed generator into `<generated_root>/<generator>/<base>`. `--check` is the CI staleness gate: unconditional regen, non-zero exit if any spec or generated client differs from the committed tree; the checked paths are fully derived from config, no per-consumer path args. Flags are invocation-scoped only (`--project`/`--client` filters, `--no-cache`, `--check`, `--root`). Commands run shell-less (shlex-split, operators rejected) — env gating is the structured `spec_env`, never a `VAR=…` prefix.
15
15
  - `SpecProducer(command, env=None)` — callable class wrapping any command that prints the spec to stdout, run with the project directory as cwd and an optional per-call env overlay; programmatic consumers construct it directly.
16
16
  - `ClientNaming` — the derived per-project package identity: `base` (last path segment + `-client`), `dashed` (`{root_name}-{base}`), `underscored`, `camel`. Constructed inline by the CLI per project; a consumer needing different names calls the per-client API directly with its own `ClientNaming`.
17
- - `generate_client(spec, generator, output_dir, names, ...)` — run the generator for one `(spec, generator)` and sync into `output_dir`; `templates_dir` is required for `csharp`, where `npm_scope` composes the UPM identity `{scope}.{base-minus-dashes}` (unset falls back to the legacy `org.nuget.{camel-lower}`).
17
+ - `generate_client(spec, generator, output_dir, names, ...)` — run the generator for one `(spec, generator)` and sync into `output_dir`; `templates_dir` is required for `csharp`, where `npm_scope` composes the UPM identity `{scope}.{base-minus-dashes}` (unset falls back to the legacy `org.nuget.{camel-lower}`). For `typescript-fetch`, `typescript_npm_scope` composes the npm package name `@{scope}/{base}` in the generated `package.json` (unset falls back to unscoped `{dashed}`); the identity is baked at generation time, so renaming later churns the committed tree through the staleness gate. `generate_client` then rewrites the generated `package.json` metadata from config via `write_npm_package_metadata` — `repository` from `repository_url`, `author` from the npm scope, `license` from `license_spdx` — replacing the generator's `GIT_USER_ID/GIT_REPO_ID` placeholders (the publish-time manifest patch rewrites only the version, so the committed tree must carry the real metadata).
18
+ - `write_npm_package_metadata(package_json_path, ...)` — conditionally rewrite `repository`/`author`/`license` in an existing generated `package.json`; a no-op leaving the file byte-identical when no metadata fields are set. Called by `generate_client` for typescript-fetch.
18
19
  - `write_unity_package_metadata(...)` — write `package.json` / `.asmdef` / `csc.rsp` / `Directory.Build.props`; called by `generate_client` for csharp.
19
20
 
20
21
  The generator version pin and the shipped configs/patches/ignore-file live in `src/openapi_client_codegen/_data/` (paths in `_data.py`).
@@ -47,4 +48,5 @@ github-actions-toolkit's `AGENTS.md` owns the consumer workflow contract — thi
47
48
 
48
49
  ## See also
49
50
 
51
+ - [`design/`](./design/) — pre-implementation ADRs; the in-flux tier, not present truth about this repo.
50
52
  - [`bashrun`](https://github.com/outernet-foundation/bashrun) — the subprocess wrapper this package shells out through.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: openapi-client-codegen
3
- Version: 0.3.3.dev87
3
+ Version: 0.3.3.dev91
4
4
  Summary: OpenAPI client-generation wrapper: Litestar spec dump, 3.1->3.0 downgrade, patched openapi-generator templates, Unity package metadata
5
5
  License-File: LICENSE
6
6
  License-File: NOTICE
@@ -0,0 +1,3 @@
1
+ # openapi-client-codegen
2
+
3
+ Typed API clients (Python `httpx`, Unity-consumable C# `httpclient`, browser TypeScript `fetch`) generated from an OpenAPI schema via OpenAPI Generator. Agent-facing documentation lives in [`AGENTS.md`](./AGENTS.md).
@@ -0,0 +1,8 @@
1
+ # design/
2
+
3
+ Pre-implementation ADRs and their execution plans — the in-flux tier, not present truth
4
+ about this repo. Nothing here is authoritative about shipped code; when a design is built,
5
+ its hardened parts fold into the co-located `AGENTS.md` and the note stops being
6
+ load-bearing. Records here may go stale without that being a defect. Each ADR rules its
7
+ decisions up front; once ruled, the open-questions section is deleted and the ruling is
8
+ recorded as a decision.
@@ -0,0 +1,61 @@
1
+ # Execution plan: typescript-fetch generator
2
+
3
+ Input: [typescript-fetch-generator.md](./typescript-fetch-generator.md) — fully ruled
4
+ (D1–D7). Scope: D3 — this repo only. The change is additive (new optional config field, new
5
+ param, new shipped config) → patch-auto under the existing `major_minor: "0.3"`; bump
6
+ manually only if the public API somehow breaks.
7
+
8
+ Ordered steps for the emitter session:
9
+
10
+ 1. **Verify generator options** against the pin, not against doc prose:
11
+
12
+ ```
13
+ uvx --from 'openapi-generator-cli[jdk4py]==7.22.0' openapi-generator-cli config-help -g typescript-fetch
14
+ ```
15
+
16
+ Confirm the option names this plan assumes: `npmName`, `npmVersion`,
17
+ `hideGenerationTimestamp`, and that the tests/docs `globalProperties` behave as in
18
+ python.json. A real emission needs Java; unit tests never do (mocked `uvx`).
19
+
20
+ 2. **Shipped config** — `_data/configs/typescript-fetch.json`, mirroring python.json:
21
+ `generatorName`, globalProperties off for tests/docs, `hideGenerationTimestamp: true`,
22
+ static `npmVersion: "0.1.0"` (versioning happens at publish time via the toolkit's
23
+ manifest patch). No static `npmName` — it is per-consumer (D7).
24
+
25
+ 3. **Config schema** — `orchestrator.py` `ProjectsConfig`: new optional
26
+ `typescript_npm_scope: str | None` alongside `npm_scope` (which stays UPM/csharp-only).
27
+ Value is the bare scope (`placeframe`, no `@`).
28
+
29
+ 4. **CLI pass-through** — `cli.py`'s `generate_client` call site gains
30
+ `typescript_npm_scope=settings.typescript_npm_scope`.
31
+
32
+ 5. **Naming branch** — `client.py` (the `csharp`/`else` fork around line 39): add a
33
+ `typescript-fetch` branch setting `additionalProperties["npmName"]` to
34
+ `@{typescript_npm_scope}/{names.base}` when the scope is set, else `names.dashed` (D7
35
+ fallback). No `templates_dir` requirement, no post-generation step (skip python's
36
+ `uv pip install` and csharp's metadata write).
37
+
38
+ 6. **Emit once for real** against a scratch spec — a hand-written minimal OpenAPI 3.0 doc
39
+ under `/tmp/opencode` (D3 forbids touching placeframe). Inspect the emitted tree.
40
+
41
+ 7. **Ignore file** — `_data/openapi-generator-ignore`: add global-basename entries for the
42
+ generator's repo/CI baggage found in step 6 (`.travis.yml`/`.gitlab-ci.yml`/`.gitignore`
43
+ are already covered; typescript-fetch may add its own). Curate against the actual tree
44
+ only — no guessed filenames.
45
+
46
+ 8. **Tests** — `tests/test_orchestrate.py`: extend `Recorder.fake_generate_client`'s
47
+ signature with the new kwarg; add a typescript-fetch orchestration test (generator key,
48
+ output dir `generated/typescript-fetch/api-client`); add a client-level composition
49
+ test that mocks `bash` in `client`, reads the temp config the built command references,
50
+ and asserts the composed `npmName` for scope-set and scope-unset cases.
51
+
52
+ 9. **Docs (spec-first)** — root `AGENTS.md` "What this is" gains the third target
53
+ (typescript-fetch, zero runtime deps, browser consumer); the `generate_client` entry
54
+ documents the new param and the `npmName` composition; the `ProjectsConfig` optional
55
+ list gains `typescript_npm_scope`; README's one-liner likewise. Prose commit separate
56
+ from code, per repo convention.
57
+
58
+ Adoption (placeframe-side, later — sequenced in the ADR, not executed on this branch):
59
+ release 0.3.x, port PRs merge, npm org created, `requires` bump, `typescript-fetch` under
60
+ `workloads/api` with `typescript_npm_scope: placeframe`, regenerate, `publish.yml` entry
61
+ for `@placeframe/api-client`.
@@ -0,0 +1,121 @@
1
+ # ADR: typescript-fetch as the third generated client target
2
+
3
+ Status: **Ruled** — D1–D7 decided (Tyler; D6–D7 in the follow-up session, same day).
4
+ Execution plan: [typescript-fetch-generator-plan.md](./typescript-fetch-generator-plan.md);
5
+ the next session executes it.
6
+
7
+ ## Context
8
+
9
+ Placeframe's dashboard is being reworked from Howard's dev_hh prototype into a hosted SPA —
10
+ Vite + React + TypeScript + three.js, v1 unauthenticated, talking **directly** to the
11
+ placeframe API with no backend of its own. The dev_hh disposition record (report.md on the
12
+ frozen `dev_hh-refactor` branch, placeframe repo) lists a "TS api-client target in
13
+ openapi-client-codegen, published or tarball-referenced for npm consumption" as the item
14
+ that **gates all frontend migration** — every dashboard route that flips from Howard's
15
+ subprocess backend to a direct API call needs this client first.
16
+
17
+ This tool today emits two targets: a Python (`httpx`) client and a Unity-consumable C#
18
+ (`httpclient`) client. This ADR adds the third. The consumer is browser-only; Howard's
19
+ frontend currently has zero HTTP library dependencies.
20
+
21
+ ## Decisions
22
+
23
+ - **D1 — Generator: `typescript-fetch`** (in the pinned openapi-generator-cli 7.22.0).
24
+ Why: the consumer is a browser SPA; native `fetch` means the generated client has **zero
25
+ runtime dependencies**. The axios-based `typescript` generator is labeled *experimental*
26
+ in 7.22.0's own `list` output; `typescript-axios`, `typescript-node`, `typescript-rxjs`,
27
+ and the rest are deprecated or non-browser. Consequence: consumers need an environment
28
+ with `fetch` (every modern browser, Node ≥ 18, Deno) — acceptable for this consumer.
29
+ - **D2 — Authorship: Tyler** (via agent sessions). This supersedes the dev_hh port plan's
30
+ next-batch note assigning the TS emitter to Howard as his first delegated code work /
31
+ curriculum arc; that arc moves elsewhere. Recorded here so the supersession is visible
32
+ where the work lands.
33
+ - **D3 — Scope: tool only.** This branch changes openapi-client-codegen and nothing else.
34
+ All placeframe-side adoption work (see "Adoption sequencing") is a separate later effort.
35
+ - **D4 — Consumer-side coverage intent: `workloads/api` only.** The dashboard talks only to
36
+ the api; the localizer and lease-server stay python-only. (Recorded for the adoption
37
+ effort; nothing in the tool enforces or needs this.)
38
+ - **D5 — Branch name `typescript-generator`** (this branch).
39
+ - **D6 — Distribution: publish to public npm**, from placeframe's `publish.yml` via the
40
+ existing NpmRegistry machinery (dev dist-tag channel included). Both the npm org
41
+ `placeframe` and the unscoped name `placeframe-api-client` were unclaimed on npmjs.com
42
+ as of 2026-11-18; creating the org is a foundation-side prerequisite, before the first
43
+ publish.
44
+ - **D7 — npm identity: scoped and tool-composed.** The emitted name is
45
+ `@placeframe/api-client`. The tool composes `npmName` as `@{typescript_npm_scope}/{base}`
46
+ from a new optional `ProjectsConfig` field, falling back to unscoped `{dashed}` when
47
+ unset — not a verbatim free-text name, and not the UPM reverse-domain identities (those
48
+ serve Unity, not browsers).
49
+
50
+ ## Mechanism sketch (input for the plan)
51
+
52
+ The existing orchestration loop is generator-agnostic — spec production, the 3.1→3.0
53
+ downgrade, the single-Default-tag forcing, the unchanged-spec skip, and the `--check`
54
+ staleness gate all derive from config and need no change. The emitter session touches:
55
+
56
+ - **`_data/configs/typescript-fetch.json`** — new, mirroring python.json/csharp.json:
57
+ `generatorName`, globalProperties off for tests/docs, `hideGenerationTimestamp`, a static
58
+ `npmVersion: "0.1.0"` (established pattern — real versioning happens at publish time, see
59
+ "Version stamping" below), and `npmName` — composed per consumer by the naming branch
60
+ (D7), never static in this file. Verify
61
+ exact option names/defaults with `config-help -g typescript-fetch` at the pinned version;
62
+ do not trust this doc's option names over config-help.
63
+ - **`client.generate_client` naming branch** — the current non-csharp `else` writes
64
+ Python's `projectName`/`packageName`; typescript-fetch keys its package identity off
65
+ npm-style options (`npmName`/`npmVersion` — verify). No `templates_dir` requirement (no
66
+ template patches initially; patch only if stock output proves deficient, under the same
67
+ path-generic patch convention as csharp). No post-generation step (python gets
68
+ pip-installed into the venv; csharp gets Unity metadata written; the TS tree is just
69
+ committed by the consumer).
70
+ - **Output location** — the CLI writes `generated_root / <generator-as-keyed> / <base>`,
71
+ so placeframe will see `packages/generated/typescript-fetch/api-client/`.
72
+ - **`_data/openapi-generator-ignore` additions** for the generator's repo baggage
73
+ (precedent: python's CI baggage got global-basename entries). Curate against the actual
74
+ emitted tree in the emitter session; do not guess the file list here.
75
+ - **Tests** — extend the mocked-generator unit tests (tests/test_orchestrate.py's recorder
76
+ pattern) for the naming branch and config load; no Java or Node needed in unit tests,
77
+ per the existing pattern of mocking the `uvx` invocation.
78
+ - **Doc updates (spec-first, in the emitter session)** — root `AGENTS.md` "What this is"
79
+ and the `generate_client` public-API entry gain the third target; README's one-liner
80
+ likewise.
81
+ - **Release** — additive change → patch-auto under the existing `major_minor: "0.3"` line.
82
+ If the emitter session discovers it must break the public API, bump `major_minor`
83
+ manually per repo convention instead.
84
+
85
+ ## Technical facts the plan should not re-derive
86
+
87
+ - Pin is openapi-generator-cli **7.22.0** (`resources.py`); `typescript` and
88
+ `typescript-fetch` both exist in it (verified via `list`).
89
+ - Spec-level workarounds upstream of any generator already cover TS: the 3.1→3.0 downgrade,
90
+ and the placeframe-side discipline of `list[list[float]]` over tuples (openapi-generator
91
+ rejects `prefixItems` and exits 0 — this bit Howard once; it applies to TS equally).
92
+ - `format: int64` maps to `number` in TS; JS numbers are float64, so the multi-GiB
93
+ magnitudes that broke the C# Int32 parse are not a TS hazard. The dev_hh port plan's rule
94
+ "bigint-int64 must land on dev before any TS client generation" is spec-consistency
95
+ sequencing, not a TS type problem.
96
+ - **Version stamping precedent**: generated trees carry a static package version; at
97
+ publish time github-actions-toolkit's registry support rewrites the version (and
98
+ intra-org dependency pins) via an ephemeral manifest patch, and treats EPUBLISHCONFLICT
99
+ as an idempotent skip. Its NpmRegistry publishes with `npm publish --access public
100
+ --provenance` and a dev dist-tag channel. Placeframe already publishes the C# api-client
101
+ to both nuget and npm this way (`publish.yml`: `PlaceframeApiClient` /
102
+ `org.outernet.placeframe.apiclient`). A published TS client would ride this machinery.
103
+ - **npm identity is baked at generation time**: typescript-fetch writes `npmName` into the
104
+ generated `package.json`, and the publish tooling patches only the version — so even an
105
+ unpublished TS tree needs a package name, and renaming it later churns the committed tree
106
+ through the staleness gate. This is why the identity ruling (D7) could not be deferred.
107
+ - v1 auth posture: the dashboard is unauthenticated (placeframe `auth_mode = "disabled"`),
108
+ so the emitted client carries **no auth plumbing** — a conscious default, not an
109
+ oversight; typescript-fetch middleware can add auth when the deferred user-facing auth
110
+ work lands.
111
+
112
+ ## Adoption sequencing (placeframe-side, later; not this branch)
113
+
114
+ 1. This tool releases 0.3.x to PyPI.
115
+ 2. The five dev_hh port PRs merge — at minimum the bigint-int64 one — so placeframe's spec
116
+ is final (as of 2026-11-18 none of the five PRs were open yet).
117
+ 3. The foundation creates the `placeframe` npm org (D6).
118
+ 4. Placeframe bumps `openapi-client-codegen.yaml` `requires` to `>=0.3`, adds
119
+ `typescript-fetch` under `workloads/api` with `typescript_npm_scope: placeframe`,
120
+ regenerates (canonical `Run generate-clients`
121
+ commit), and adds a `publish.yml` entry publishing `@placeframe/api-client` (D6/D7).
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "openapi-client-codegen"
3
- version = "0.3.3.dev87"
3
+ version = "0.3.3.dev91"
4
4
  description = "OpenAPI client-generation wrapper: Litestar spec dump, 3.1->3.0 downgrade, patched openapi-generator templates, Unity package metadata"
5
5
  requires-python = ">=3.13"
6
6
  dependencies = [
@@ -0,0 +1,13 @@
1
+ {
2
+ "generatorName": "typescript-fetch",
3
+ "globalProperties": {
4
+ "apiTests": false,
5
+ "modelTests": false,
6
+ "modelDocs": false,
7
+ "apiDocs": false
8
+ },
9
+ "additionalProperties": {
10
+ "npmVersion": "0.1.0",
11
+ "disallowAdditionalPropertiesIfNotPresent": false
12
+ }
13
+ }
@@ -81,6 +81,7 @@ def generate_projects_command(
81
81
  names,
82
82
  templates_dir=templates_directory,
83
83
  npm_scope=settings.npm_scope,
84
+ typescript_npm_scope=settings.typescript_npm_scope,
84
85
  license_spdx=settings.license_spdx,
85
86
  repository_url=settings.repository_url,
86
87
  )
@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING
10
10
 
11
11
  from bashrun.bash import bash
12
12
 
13
+ from .npm import write_npm_package_metadata
13
14
  from .resources import CONFIGS_DIR, IGNORE_FILE, OPENAPI_GENERATOR_CLI_VERSION
14
15
  from .unity import write_unity_package_metadata
15
16
 
@@ -27,6 +28,7 @@ def generate_client(
27
28
  templates_dir: Path | None = None,
28
29
  extra_references: list[str] | None = None,
29
30
  npm_scope: str | None = None,
31
+ typescript_npm_scope: str | None = None,
30
32
  license_spdx: str | None = None,
31
33
  repository_url: str | None = None,
32
34
  ) -> None:
@@ -38,6 +40,10 @@ def generate_client(
38
40
 
39
41
  if generator == "csharp":
40
42
  client_config["additionalProperties"]["packageName"] = names.camel
43
+ elif generator == "typescript-fetch":
44
+ client_config["additionalProperties"]["npmName"] = (
45
+ names.dashed if typescript_npm_scope is None else f"@{typescript_npm_scope}/{names.base}"
46
+ )
41
47
  else:
42
48
  client_config["additionalProperties"]["projectName"] = names.dashed
43
49
  client_config["additionalProperties"]["packageName"] = names.underscored
@@ -89,6 +95,13 @@ def generate_client(
89
95
  license_spdx=license_spdx,
90
96
  repository_url=repository_url,
91
97
  )
98
+ elif generator == "typescript-fetch":
99
+ write_npm_package_metadata(
100
+ temporary_directory / "package.json",
101
+ author=typescript_npm_scope,
102
+ license_spdx=license_spdx,
103
+ repository_url=repository_url,
104
+ )
92
105
 
93
106
  print(f"Syncing to {output_dir}...")
94
107
 
@@ -0,0 +1,23 @@
1
+ import json
2
+ from pathlib import Path
3
+
4
+
5
+ def write_npm_package_metadata(
6
+ package_json_path: Path,
7
+ author: str | None = None,
8
+ license_spdx: str | None = None,
9
+ repository_url: str | None = None,
10
+ ) -> None:
11
+ if author is None and license_spdx is None and repository_url is None:
12
+ return
13
+
14
+ package = json.loads(package_json_path.read_text(encoding="utf-8"))
15
+
16
+ if repository_url is not None:
17
+ package["repository"] = {"type": "git", "url": repository_url}
18
+ if author is not None:
19
+ package["author"] = author
20
+ if license_spdx is not None:
21
+ package["license"] = license_spdx
22
+
23
+ package_json_path.write_text(json.dumps(package, indent=2) + "\n", encoding="utf-8")
@@ -21,6 +21,7 @@ class ProjectsConfig(BaseModel):
21
21
  spec_command: str
22
22
  spec_env: dict[str, str] | None = None
23
23
  npm_scope: str | None = None
24
+ typescript_npm_scope: str | None = None
24
25
  license_spdx: str | None = None
25
26
  repository_url: str | None = None
26
27
  requires: str
@@ -45,6 +45,7 @@ class Recorder:
45
45
  templates_dir: Path | None = None,
46
46
  extra_references: list[str] | None = None,
47
47
  npm_scope: str | None = None,
48
+ typescript_npm_scope: str | None = None,
48
49
  license_spdx: str | None = None,
49
50
  repository_url: str | None = None,
50
51
  ) -> None:
@@ -0,0 +1,51 @@
1
+ import json
2
+ from pathlib import Path
3
+
4
+ from openapi_client_codegen.npm import write_npm_package_metadata
5
+
6
+
7
+ def write_package(
8
+ tmp_path: Path,
9
+ author: str | None = None,
10
+ license_spdx: str | None = None,
11
+ repository_url: str | None = None,
12
+ ) -> tuple[Path, str]:
13
+ original = (
14
+ json.dumps(
15
+ {
16
+ "name": "@placeframe/api-client",
17
+ "version": "0.1.0",
18
+ "author": "OpenAPI-Generator",
19
+ "repository": {"type": "git", "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"},
20
+ },
21
+ indent=2,
22
+ )
23
+ + "\n"
24
+ )
25
+ package_json_path = tmp_path / "package.json"
26
+ package_json_path.write_text(original, encoding="utf-8")
27
+ write_npm_package_metadata(
28
+ package_json_path, author=author, license_spdx=license_spdx, repository_url=repository_url
29
+ )
30
+ return package_json_path, original
31
+
32
+
33
+ def test_rewrites_repository_author_and_license(tmp_path: Path) -> None:
34
+ package_json_path, _ = write_package(
35
+ tmp_path,
36
+ author="placeframe",
37
+ license_spdx="Apache-2.0",
38
+ repository_url="https://github.com/outernet-foundation/placeframe.git",
39
+ )
40
+ package = json.loads(package_json_path.read_text(encoding="utf-8"))
41
+
42
+ assert package["name"] == "@placeframe/api-client"
43
+ assert package["repository"] == {"type": "git", "url": "https://github.com/outernet-foundation/placeframe.git"}
44
+ assert package["author"] == "placeframe"
45
+ assert package["license"] == "Apache-2.0"
46
+
47
+
48
+ def test_no_metadata_leaves_generated_manifest_untouched(tmp_path: Path) -> None:
49
+ package_json_path, original = write_package(tmp_path)
50
+
51
+ assert package_json_path.read_text(encoding="utf-8") == original
@@ -7,8 +7,9 @@ import pytest
7
7
  import yaml
8
8
  from typer.testing import CliRunner
9
9
 
10
- from openapi_client_codegen import cli, orchestrator
10
+ from openapi_client_codegen import cli, client, orchestrator
11
11
  from openapi_client_codegen.cli import app
12
+ from openapi_client_codegen.client import generate_client
12
13
  from openapi_client_codegen.downgrade import JsonDict, downgrade_openapi_3_1_to_3_0
13
14
  from openapi_client_codegen.orchestrator import ClientNaming, SpecProducer
14
15
 
@@ -16,16 +17,37 @@ runner = CliRunner()
16
17
 
17
18
  RAW_SCHEMA: JsonDict = {"openapi": "3.1.0", "info": {"title": "demo", "version": "0.0.0"}, "paths": {}}
18
19
 
20
+ STOCK_PACKAGE_JSON = (
21
+ json.dumps(
22
+ {
23
+ "name": "placeholder",
24
+ "version": "0.1.0",
25
+ "author": "OpenAPI-Generator",
26
+ "repository": {"type": "git", "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"},
27
+ },
28
+ indent=2,
29
+ )
30
+ + "\n"
31
+ )
32
+
19
33
 
20
34
  class Recorder:
21
35
  def __init__(self) -> None:
22
36
  self.generated: list[tuple[str, Path, ClientNaming]] = []
23
37
  self.commands: list[tuple[str, Path | None, dict[str, str] | None]] = []
38
+ self.scopes: list[str | None] = []
39
+ self.bash_commands: list[str] = []
24
40
 
25
41
  def fake_bash_output(self, command: str, *, cwd: Path | None = None, env: dict[str, str] | None = None) -> str:
26
42
  self.commands.append((command, cwd, env))
27
43
  return json.dumps(RAW_SCHEMA)
28
44
 
45
+ def fake_bash(self, command: str, *, cwd: Path | None = None, env: dict[str, str] | None = None) -> None:
46
+ self.bash_commands.append(command)
47
+ if "-g typescript-fetch" in command:
48
+ output_directory = Path(command.split(" -o ")[1].split(" ")[0])
49
+ (output_directory / "package.json").write_text(STOCK_PACKAGE_JSON, encoding="utf-8")
50
+
29
51
  def fake_regenerate_templates(self, target_dir: Path, extra_patches_dir: Path | None = None) -> None:
30
52
  pass
31
53
 
@@ -38,10 +60,12 @@ class Recorder:
38
60
  templates_dir: Path | None = None,
39
61
  extra_references: list[str] | None = None,
40
62
  npm_scope: str | None = None,
63
+ typescript_npm_scope: str | None = None,
41
64
  license_spdx: str | None = None,
42
65
  repository_url: str | None = None,
43
66
  ) -> None:
44
67
  self.generated.append((generator, output_dir, names))
68
+ self.scopes.append(typescript_npm_scope)
45
69
 
46
70
 
47
71
  @pytest.fixture
@@ -186,3 +210,68 @@ def test_spec_producer_overlays_env(recorder: Recorder) -> None:
186
210
  assert recorder.commands == [
187
211
  ("uv run --project . python -m src.dump_openapi", Path("docker/api"), {"CODEGEN": "1"})
188
212
  ]
213
+
214
+
215
+ def test_typescript_fetch_client_and_scope_pass_through(tmp_path: Path, recorder: Recorder) -> None:
216
+ make_project(tmp_path, "docker/api")
217
+
218
+ settings: dict[str, object] = {
219
+ "projects": {"docker/api": ["typescript-fetch"]},
220
+ "root_name": "placeframe",
221
+ "generated_root": str(tmp_path / "generated"),
222
+ "spec_command": "dump-openapi",
223
+ "typescript_npm_scope": "placeframe",
224
+ "requires": ">=0.1",
225
+ }
226
+ config = tmp_path / "clients.yaml"
227
+ config.write_text(yaml.safe_dump(settings, default_flow_style=False, sort_keys=False), encoding="utf-8")
228
+ result = runner.invoke(app, ["--config", str(config), "--root", str(tmp_path)])
229
+ assert result.exit_code == 0
230
+
231
+ assert [(generator, output_dir.name) for generator, output_dir, _ in recorder.generated] == [
232
+ ("typescript-fetch", "api-client")
233
+ ]
234
+ assert recorder.generated[0][1] == tmp_path / "generated" / "typescript-fetch" / "api-client"
235
+ assert recorder.scopes == ["placeframe"]
236
+
237
+
238
+ def test_typescript_fetch_composes_npm_name(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
239
+ recorder = Recorder()
240
+ monkeypatch.setattr(client, "bash", recorder.fake_bash)
241
+
242
+ names = ClientNaming(
243
+ base="api-client",
244
+ dashed="placeframe-api-client",
245
+ underscored="placeframe_api_client",
246
+ camel="PlaceframeApiClient",
247
+ )
248
+
249
+ generate_client(
250
+ json.dumps(RAW_SCHEMA),
251
+ "typescript-fetch",
252
+ tmp_path / "scoped",
253
+ names,
254
+ typescript_npm_scope="placeframe",
255
+ license_spdx="Apache-2.0",
256
+ repository_url="https://github.com/outernet-foundation/placeframe.git",
257
+ )
258
+ generate_client(json.dumps(RAW_SCHEMA), "typescript-fetch", tmp_path / "unscoped", names)
259
+
260
+ composed: list[str] = []
261
+ for command in recorder.bash_commands:
262
+ config_path = Path(command.split(" -c ")[1].split(" ")[0])
263
+ generator_config = json.loads(config_path.read_text(encoding="utf-8"))
264
+ composed.append(generator_config["additionalProperties"]["npmName"])
265
+
266
+ assert composed == ["@placeframe/api-client", "placeframe-api-client"]
267
+
268
+ scoped_package = json.loads((tmp_path / "scoped" / "package.json").read_text(encoding="utf-8"))
269
+ assert scoped_package["repository"] == {
270
+ "type": "git",
271
+ "url": "https://github.com/outernet-foundation/placeframe.git",
272
+ }
273
+ assert scoped_package["author"] == "placeframe"
274
+ assert scoped_package["license"] == "Apache-2.0"
275
+
276
+ unscoped_package = json.loads((tmp_path / "unscoped" / "package.json").read_text(encoding="utf-8"))
277
+ assert unscoped_package["repository"]["url"] == "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
@@ -1,3 +0,0 @@
1
- # openapi-client-codegen
2
-
3
- Typed API clients (Python `httpx` + Unity-consumable C# `httpclient`) generated from an OpenAPI schema via OpenAPI Generator. Agent-facing documentation lives in [`AGENTS.md`](./AGENTS.md).