feat: add schema patcher

Allow us to patch the openapi schema during development or due to a slow
release of mfd. Once the changes are part of the released spec, we can
remove the override.

Author: dimi-cb

.github/workflows/publish.yaml

@@ -70,6 +70,16 @@ jobs:
           echo "Latest MFD tag: $MFD_TAG"
           gh api /repos/cloudbeds/mfd/tarball/$MFD_TAG | tar --strip-components=1 --wildcards -zxf - '*/public_accessa/api'
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Patch OpenAPI Spec
+        run: |
+          pip install pyyaml
+          python scripts/patch_openapi_spec.py
+
       - name: Get next version
         run: |
           if [ -n "${{ inputs.version }}" ]; then

CLAUDE.md

@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Auto-generated Python SDK for the Cloudbeds PMS v1.3 API, produced by OpenAPI Generator 7.11.0. Nearly all code under `cloudbeds_pms_v1_3/` is generated — do not manually edit generated files.
+
+## Commands
+
+- **Install dependencies**: `uv sync` (dev) or `uv sync --locked --no-dev` (prod)
+- **Run all tests**: `pytest`
+- **Run a single test**: `pytest cloudbeds_pms_v1_3/test/test_<name>.py`
+- **Build**: `uv build`
+
+## Code Generation
+
+The SDK is regenerated from an OpenAPI spec using the config in `openapitools.json`:
+- Generator: `python` (OpenAPI Generator CLI 7.11.0)
+- Input spec: sourced from Cloudbeds MFD repository (fetched during CI)
+- Custom Mustache templates in `templates/` (`model_enum.mustache`, `model_generic.mustache`)
+- Key setting: `enumUnknownDefaultCase: true` — enums include an unknown default case
+
+To regenerate: the CI workflow in `.github/workflows/publish.yaml` handles spec fetching, generation, version bumping, and publishing to PyPI.
+
+## Architecture
+
+```
+cloudbeds_pms_v1_3/
+├── api/              # 21 API endpoint classes (one per resource domain)
+├── models/           # ~318 Pydantic v2 models (from OpenAPI schemas)
+├── test/             # Unittest stubs (one per model, auto-generated)
+├── docs/             # Markdown docs (one per model/endpoint)
+├── api_client.py     # Core HTTP client (request building, serialization)
+├── configuration.py  # Auth config: API key (x-api-key header) and OAuth2
+├── exceptions.py     # Exception hierarchy
+└── rest.py           # REST layer using urllib3
+```
+
+API classes use `@validate_call` from Pydantic and return typed model instances. Auth is configured via `Configuration` with either API key or OAuth2 bearer token.
+
+## Version
+
+Current version: `1.9.0` (tracked in `VERSION` file and `openapitools.json`). Version bumps happen automatically during the publish workflow.

pyproject.toml

@@ -50,7 +50,8 @@ testing = [
 [dependency-groups]
 dev = [
     "pytest",
-    "coverage"
+    "coverage",
+    "pyyaml",
 ]
 
 [tool.setuptools.packages.find]

scripts/patch_openapi_spec.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Patch the OpenAPI spec with temporary overrides before code generation.
+
+Reads spec_overrides.yaml and applies each override to the OpenAPI spec
+defined in openapitools.json. This allows releasing SDK versions with type
+fixes while waiting for the upstream spec to be updated.
+
+Usage:
+    python scripts/patch_openapi_spec.py
+
+The script is a no-op (exits 0) if spec_overrides.yaml doesn't exist or
+has no overrides defined.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+OVERRIDES_FILE = ROOT / "spec_overrides.yaml"
+OPENAPITOOLS_FILE = ROOT / "openapitools.json"
+
+
+def load_overrides():
+    if not OVERRIDES_FILE.exists():
+        return []
+    with open(OVERRIDES_FILE) as f:
+        data = yaml.safe_load(f)
+    if not data or not data.get("overrides"):
+        return []
+    return data["overrides"]
+
+
+def get_spec_path():
+    with open(OPENAPITOOLS_FILE) as f:
+        config = json.load(f)
+    return ROOT / config["inputSpec"]
+
+
+def set_nested(doc, dotted_path, value):
+    """Set a value in a nested dict using a dot-separated path, creating intermediate keys as needed."""
+    keys = dotted_path.split(".")
+    current = doc
+    for key in keys[:-1]:
+        if key not in current:
+            current[key] = {}
+        current = current[key]
+    current[keys[-1]] = value
+
+
+def apply_overrides(spec, overrides):
+    applied = 0
+    for override in overrides:
+        path = override["path"]
+        schema = override["schema"]
+        set_nested(spec, path, schema)
+        print(f"  Patched: {path}")
+        applied += 1
+    return applied
+
+
+def main():
+    overrides = load_overrides()
+    if not overrides:
+        print("No spec overrides found, skipping patch step.")
+        return
+
+    spec_path = get_spec_path()
+    if not spec_path.exists():
+        print(f"Error: spec file not found at {spec_path}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(spec_path) as f:
+        spec = yaml.safe_load(f)
+
+    print(f"Applying {len(overrides)} override(s) to {spec_path.name}:")
+    applied = apply_overrides(spec, overrides)
+
+    with open(spec_path, "w") as f:
+        yaml.dump(spec, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
+
+    print(f"Done. {applied} override(s) applied.")
+
+
+if __name__ == "__main__":
+    main()

spec_overrides.yaml

@@ -0,0 +1,28 @@
+# Temporary OpenAPI spec overrides.
+# Each entry patches a specific path in the spec before code generation.
+# Remove entries once the upstream spec includes the fix.
+#
+# Usage:
+#   python scripts/patch_openapi_spec.py
+#
+# Path format: dot-separated keys into the spec YAML.
+# The "schema" value replaces whatever exists at that path.
+#
+# Examples:
+#
+# Override a property type (e.g. datetime -> datetime|string):
+#   - path: "components.schemas.GetReservationsResponseDataInner.properties.dateCreated"
+#     schema:
+#       anyOf:
+#         - type: string
+#           format: date-time
+#         - type: string
+#       description: "Creation datetime (format: Y-m-d H:i:s)"
+#
+# Add a new property to an existing schema:
+#   - path: "components.schemas.SomeModel.properties.newField"
+#     schema:
+#       type: string
+#       description: "A field not yet in the upstream spec"
+
+overrides: [ ]