feat: expand Python SDK coverage and clean up repo scaffolding

.github/workflows/ci.yml

@@ -3,8 +3,26 @@ name: CI
 on:
   push:
     branches: [ main ]
+    paths:
+      - "nexla_sdk/**"
+      - "scripts/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "requirements.txt"
+      - "pytest.ini"
+      - "README.md"
+      - ".github/workflows/ci.yml"
   pull_request:
     branches: [ main ]
+    paths:
+      - "nexla_sdk/**"
+      - "scripts/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "requirements.txt"
+      - "pytest.ini"
+      - "README.md"
+      - ".github/workflows/ci.yml"
 
 jobs:
   build-test:
@@ -30,9 +48,12 @@ jobs:
           pip install ruff
           ruff check nexla_sdk
 
+      - name: Check Generated Operation Map Sync
+        run: |
+          python scripts/parity/check_operation_map_sync.py
+
       - name: Run unit tests
         env:
           PYTHONWARNINGS: default
         run: |
           pytest -m unit --maxfail=1 -q
-

.github/workflows/docs.yml

@@ -4,8 +4,20 @@ on:
   push:
     branches: [ main ]
     tags: [ 'v*' ]
+    paths:
+      - "docs-site/**"
+      - "docs/**"
+      - "nexla_sdk/**"
+      - "README.md"
+      - ".github/workflows/docs.yml"
   pull_request:
     branches: [ main ]
+    paths:
+      - "docs-site/**"
+      - "docs/**"
+      - "nexla_sdk/**"
+      - "README.md"
+      - ".github/workflows/docs.yml"
 
 permissions:
   contents: read

.gitignore

@@ -37,6 +37,7 @@ pip-log.txt
 pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+coverage/
 htmlcov/
 .tox/
 .nox/
@@ -167,30 +168,20 @@ logs/
 *.sqlite
 *.sqlite3
 
-# Node.js
-.node/
-node_modules/
-**/node_modules/
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-.npm
-.yarn-integrity
-
-# Documentation site
+# Documentation site (Docusaurus / Node-based)
 docs_venv/
 docs-site/docs_venv/
 docs-site/.docusaurus/
 docs-site/build/
 docs-site/.cache/
+docs-site/node_modules/
 
 # OpenAPI
 openapi/
 
 # Project-specific files
 CLAUDE.md
 digest.txt
-plugin-redoc-0.yaml
 
 # Sample directory
 create_flow_sample/
@@ -202,3 +193,6 @@ create_flow_sample/
 .claude/
 .direnv/
 .envrc
+
+# Parity artifacts generated from local backend/spec analysis
+artifacts/parity/*.json

.pre-commit-config.yaml

@@ -6,12 +6,6 @@ repos:
         args: ["--fix"]
       - id: ruff-format
 
-  - repo: https://github.com/psf/black
-    rev: 24.8.0
-    hooks:
-      - id: black
-        language_version: python3
-
   - repo: https://github.com/pycqa/isort
     rev: 5.13.2
     hooks:

README.md

@@ -576,6 +576,25 @@ doc_audit = client.doc_containers.get_audit_log(doc_container_id=1001)
 schema_audit = client.data_schemas.get_audit_log(schema_id=5001)
 ```
 
+### Raw Operation-Level Access
+
+```python
+# List available OpenAPI operation ids
+ops = client.raw.list_operations()
+
+# Call by operation id with typed path/query/body slots
+project_flows = client.raw.call(
+    "get_project_flows",
+    path_params={"project_id": 123},
+)
+
+# Direct raw HTTP helpers are also available
+limits = client.raw.get("/limits")
+
+# Backend-only or non-spec route access
+approved = client.raw.request("POST", "/self_signup_requests/42/approve")
+```
+
 ## Coverage Matrix
 
 Mapping of major OpenAPI areas to SDK resources. All requests set `Accept: application/vnd.nexla.api.v1+json` and default base URL `https://dataops.nexla.io/nexla-api`.
@@ -605,7 +624,8 @@ Mapping of major OpenAPI areas to SDK resources. All requests set `Accept: appli
 - GenAI Configurations/Org Settings: `client.genai` — configs CRUD; org settings CRUD; active_config
 - Doc Containers: `client.doc_containers` — audit_log; (access control via BaseResource helpers)
 - Data Schemas: `client.data_schemas` — audit_log; (access control via BaseResource helpers)
-- Webhooks: not included as a dedicated helper yet (use direct HTTP with API key per spec)
+- Webhooks: `client.create_webhook_client(api_key=...)` for API-key authenticated webhook sends
+- Full OpenAPI operation-level access: `client.raw.call(operation_id, ...)`
 
 ## Error Handling
 
@@ -682,6 +702,24 @@ export NEXLA_API_URL="https://your-nexla-instance.com/nexla-api"
 pytest tests/integration/
 ```
 
+### Parity Tooling
+
+The parity scripts compare the SDK surface against the OpenAPI spec
+(`plugin-redoc-0.yaml`, sourced from upstream and not committed) and the admin
+API's `routes.rb`. Set `NEXLA_ADMIN_API_PATH` to the local checkout of the
+admin-api repo before running `build_matrices.py`, or pass `--admin-routes`
+explicitly.
+
+```bash
+# Generate operation map for client.raw
+python scripts/parity/generate_operation_map.py
+
+# Build OpenAPI/admin-routes/SDK parity matrices
+export NEXLA_ADMIN_API_PATH="/path/to/admin-api"
+python scripts/parity/build_matrices.py \
+  --admin-routes "$NEXLA_ADMIN_API_PATH/config/routes.rb"
+```
+
 ### Setting Up Environment
 
 ```bash