sapsf-shared 0.1.0__tar.gz

sapsf_shared-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev,flask]"
+      - name: Test
+        run: pytest -q

sapsf_shared-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run tests
+        run: |
+          pip install -e ".[dev,flask]"
+          pytest -q
+      - name: Build distributions
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sapsf_shared-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+.coverage
+.env

sapsf_shared-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sahir Vhora
+
+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.

sapsf_shared-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: sapsf-shared
+Version: 0.1.0
+Summary: Shared Python SDK for SAP SuccessFactors tools - OData client, auth, config, and Flask base
+Project-URL: Homepage, https://github.com/SahirVhora/sapsf-shared
+Project-URL: Repository, https://github.com/SahirVhora/sapsf-shared
+Project-URL: Issues, https://github.com/SahirVhora/sapsf-shared/issues
+Project-URL: SF Compass Suite, https://sahirvhora.github.io/sf-compass/
+Author: Sahir Vhora
+License: MIT
+License-File: LICENSE
+Keywords: odata,sap,sdk,successfactors
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# sapsf-shared
+
+**Shared Python SDK for SAP SuccessFactors tools.**
+
+A single, well-tested library that extracts the common patterns repeated across every SAP SF tool in your workspace: OData HTTP client, authentication, config loading, logging, utilities, and Flask boilerplate.
+
+## Why this exists
+
+Every SAP SF tool in your workspace reimplements:
+- OData v2 HTTP client with retries and pagination
+- Basic Auth / OAuth2 / Certificate auth handling
+- Keyring vs file-based credential storage
+- Config loader (YAML/JSON with env var substitution)
+- Coloured logging setup
+- Flask CSRF, error handlers, health endpoint
+
+`sapsf-shared` consolidates all of this into one package. When you fix a bug in the auth layer, it's fixed everywhere.
+
+## Installation
+
+```bash
+cd sapsf/_shared
+pip install -e ".[dev,flask]"
+```
+
+## Quick Start
+
+### 1. Connect to SAP SuccessFactors
+
+```python
+from sapsf_shared import AuthConfig, SFClient
+
+config = AuthConfig(
+    base_url="https://api4.successfactors.com/odata/v2",
+    username="admin@companyId",
+    password="secret",
+    company_id="companyId",
+    auth_type="basic",
+)
+
+with SFClient(config) as client:
+    # Fetch all departments
+    depts = client.get("FODepartment")
+    print(f"Found {len(depts)} departments")
+
+    # Fetch with filter and pagination
+    positions = client.get(
+        "Position",
+        filter_expr="cust_Country eq 'GBR'",
+        select=["code", "externalName", "cust_JobFunction"],
+        expand=["cust_JobFunction"],
+    )
+```
+
+### 2. OAuth 2.0
+
+```python
+config = AuthConfig(
+    base_url="https://api4.successfactors.com/odata/v2",
+    auth_type="oauth2",
+    client_id="my_client_id",
+    client_secret="my_secret",
+    company_id="companyId",
+)
+with SFClient(config) as client:
+    ok, msg = client.test_connection()
+    print(ok, msg)
+```
+
+### 3. Secure credential storage
+
+```python
+from sapsf_shared.auth import CredentialStore
+
+store = CredentialStore(service="my_tool")
+store.set("prd:password", "secret123")
+pwd = store.get("prd:password")
+```
+
+Automatically uses OS keyring when available; falls back to a chmod-600 JSON file on headless systems.
+
+### 4. Config from YAML
+
+```python
+from sapsf_shared.config import load_config
+
+cfg = load_config("config.yaml")
+# Supports ${ENV_VAR} substitution inside the YAML file
+```
+
+### 5. Flask base app
+
+```python
+from sapsf_shared.flask_base import create_app
+
+app = create_app(__name__, log_dir="logs", enable_csrf=True)
+
+@app.route("/")
+def index():
+    return {"status": "ok"}
+
+if __name__ == "__main__":
+    app.run(port=5050)
+```
+
+Comes with built-in:
+- `/api/health` endpoint
+- CSRF token generation + validation
+- JSON error handlers (400, 403, 404, 500)
+- CORS preflight support
+- Rotating file logging
+
+## API Reference
+
+### `SFClient`
+
+| Method | Description |
+|--------|-------------|
+| `get(entity_set, **kwargs)` | Fetch all records with auto-pagination |
+| `get_entity_by_code(entity_set, external_code, **kwargs)` | Filter by externalCode |
+| `post(entity_set, payload)` | Create a record |
+| `patch(entity_set, payload)` | Update a record |
+| `delete(entity_set, key)` | Delete a record |
+| `test_connection()` | Quick connectivity probe |
+| `entity_exists(entity_set, external_code)` | Check existence |
+
+### `AuthConfig`
+
+Dataclass that normalises auth settings across all your tools. Fields: `base_url`, `company_id`, `auth_type`, `username`, `password`, `client_id`, `client_secret`, `token_url`, `cert_path`, `key_path`, `timeout_sec`.
+
+### `SFEnvConfig`
+
+Loads configuration from environment variables with the standard `SF_*` prefix:
+
+```bash
+export SF_BASE_URL=https://api4.successfactors.com/odata/v2
+export SF_USERNAME=admin
+export SF_PASSWORD=secret
+export SF_COMPANY_ID=companyId
+```
+
+```python
+cfg = SFEnvConfig.from_env()
+```
+
+### `CredentialStore`
+
+Keyring-backed secret storage with automatic fallback to a local `.secrets.json` file (chmod 600). Use `store.clear_alias(alias)` to delete all secrets for a tenant.
+
+### Utilities
+
+| Function | Description |
+|----------|-------------|
+| `parse_sf_date(raw)` | Parse `/Date(millis)/` and ISO formats |
+| `is_active_today(record)` | Check effective dating + status |
+| `flatten_record(record)` | Flatten nested OData for CSV export |
+| `build_odata_filter(dict)` | Build `$filter` strings from dicts |
+
+## Development
+
+```bash
+pip install -e ".[dev,flask]"
+pytest -v                  # 13 tests
+mypy src/sapsf_shared      # Type checking
+ruff check src tests       # Linting
+ruff format src tests      # Formatting
+```
+
+## Roadmap
+
+- [ ] Vectorised batch operations (`upsert_many`, `delete_many`)
+- [ ] Connection pooling tuning
+- [ ] Async support (httpx-based client)
+- [ ] SAP SF API v4 support
+
+## License
+
+MIT
+
+## Adoption status
+
+| Tool | Status |
+|---|---|
+| sf-config-compare | Adopted - `parse_sf_date` via `sapsf_shared.utils` |
+| sf-position-integrity-checker | Next - client/pagination migration pending tenant testing |
+| sf-object-sync | Planned |
+
+Depend on it from any tool:
+
+```
+sapsf-shared @ git+https://github.com/SahirVhora/sapsf-shared
+```

sapsf_shared-0.1.0/README.md

@@ -0,0 +1,192 @@
+# sapsf-shared
+
+**Shared Python SDK for SAP SuccessFactors tools.**
+
+A single, well-tested library that extracts the common patterns repeated across every SAP SF tool in your workspace: OData HTTP client, authentication, config loading, logging, utilities, and Flask boilerplate.
+
+## Why this exists
+
+Every SAP SF tool in your workspace reimplements:
+- OData v2 HTTP client with retries and pagination
+- Basic Auth / OAuth2 / Certificate auth handling
+- Keyring vs file-based credential storage
+- Config loader (YAML/JSON with env var substitution)
+- Coloured logging setup
+- Flask CSRF, error handlers, health endpoint
+
+`sapsf-shared` consolidates all of this into one package. When you fix a bug in the auth layer, it's fixed everywhere.
+
+## Installation
+
+```bash
+cd sapsf/_shared
+pip install -e ".[dev,flask]"
+```
+
+## Quick Start
+
+### 1. Connect to SAP SuccessFactors
+
+```python
+from sapsf_shared import AuthConfig, SFClient
+
+config = AuthConfig(
+    base_url="https://api4.successfactors.com/odata/v2",
+    username="admin@companyId",
+    password="secret",
+    company_id="companyId",
+    auth_type="basic",
+)
+
+with SFClient(config) as client:
+    # Fetch all departments
+    depts = client.get("FODepartment")
+    print(f"Found {len(depts)} departments")
+
+    # Fetch with filter and pagination
+    positions = client.get(
+        "Position",
+        filter_expr="cust_Country eq 'GBR'",
+        select=["code", "externalName", "cust_JobFunction"],
+        expand=["cust_JobFunction"],
+    )
+```
+
+### 2. OAuth 2.0
+
+```python
+config = AuthConfig(
+    base_url="https://api4.successfactors.com/odata/v2",
+    auth_type="oauth2",
+    client_id="my_client_id",
+    client_secret="my_secret",
+    company_id="companyId",
+)
+with SFClient(config) as client:
+    ok, msg = client.test_connection()
+    print(ok, msg)
+```
+
+### 3. Secure credential storage
+
+```python
+from sapsf_shared.auth import CredentialStore
+
+store = CredentialStore(service="my_tool")
+store.set("prd:password", "secret123")
+pwd = store.get("prd:password")
+```
+
+Automatically uses OS keyring when available; falls back to a chmod-600 JSON file on headless systems.
+
+### 4. Config from YAML
+
+```python
+from sapsf_shared.config import load_config
+
+cfg = load_config("config.yaml")
+# Supports ${ENV_VAR} substitution inside the YAML file
+```
+
+### 5. Flask base app
+
+```python
+from sapsf_shared.flask_base import create_app
+
+app = create_app(__name__, log_dir="logs", enable_csrf=True)
+
+@app.route("/")
+def index():
+    return {"status": "ok"}
+
+if __name__ == "__main__":
+    app.run(port=5050)
+```
+
+Comes with built-in:
+- `/api/health` endpoint
+- CSRF token generation + validation
+- JSON error handlers (400, 403, 404, 500)
+- CORS preflight support
+- Rotating file logging
+
+## API Reference
+
+### `SFClient`
+
+| Method | Description |
+|--------|-------------|
+| `get(entity_set, **kwargs)` | Fetch all records with auto-pagination |
+| `get_entity_by_code(entity_set, external_code, **kwargs)` | Filter by externalCode |
+| `post(entity_set, payload)` | Create a record |
+| `patch(entity_set, payload)` | Update a record |
+| `delete(entity_set, key)` | Delete a record |
+| `test_connection()` | Quick connectivity probe |
+| `entity_exists(entity_set, external_code)` | Check existence |
+
+### `AuthConfig`
+
+Dataclass that normalises auth settings across all your tools. Fields: `base_url`, `company_id`, `auth_type`, `username`, `password`, `client_id`, `client_secret`, `token_url`, `cert_path`, `key_path`, `timeout_sec`.
+
+### `SFEnvConfig`
+
+Loads configuration from environment variables with the standard `SF_*` prefix:
+
+```bash
+export SF_BASE_URL=https://api4.successfactors.com/odata/v2
+export SF_USERNAME=admin
+export SF_PASSWORD=secret
+export SF_COMPANY_ID=companyId
+```
+
+```python
+cfg = SFEnvConfig.from_env()
+```
+
+### `CredentialStore`
+
+Keyring-backed secret storage with automatic fallback to a local `.secrets.json` file (chmod 600). Use `store.clear_alias(alias)` to delete all secrets for a tenant.
+
+### Utilities
+
+| Function | Description |
+|----------|-------------|
+| `parse_sf_date(raw)` | Parse `/Date(millis)/` and ISO formats |
+| `is_active_today(record)` | Check effective dating + status |
+| `flatten_record(record)` | Flatten nested OData for CSV export |
+| `build_odata_filter(dict)` | Build `$filter` strings from dicts |
+
+## Development
+
+```bash
+pip install -e ".[dev,flask]"
+pytest -v                  # 13 tests
+mypy src/sapsf_shared      # Type checking
+ruff check src tests       # Linting
+ruff format src tests      # Formatting
+```
+
+## Roadmap
+
+- [ ] Vectorised batch operations (`upsert_many`, `delete_many`)
+- [ ] Connection pooling tuning
+- [ ] Async support (httpx-based client)
+- [ ] SAP SF API v4 support
+
+## License
+
+MIT
+
+## Adoption status
+
+| Tool | Status |
+|---|---|
+| sf-config-compare | Adopted - `parse_sf_date` via `sapsf_shared.utils` |
+| sf-position-integrity-checker | Next - client/pagination migration pending tenant testing |
+| sf-object-sync | Planned |
+
+Depend on it from any tool:
+
+```
+sapsf-shared @ git+https://github.com/SahirVhora/sapsf-shared
+```

sapsf_shared-0.1.0/docs/findings-schema.md

@@ -0,0 +1,92 @@
+# SF Compass Suite - Findings Schema (v1)
+
+A common JSON format for analysis findings, so every scanner in the suite
+(sf-config-debt-radar, sf-position-integrity-checker, sf-config-compare, ...)
+can emit results that any other tool (the sf-compass dashboard, AI agents via
+MCP, future trend tooling) can consume without tool-specific parsing.
+
+Schema identifier: `sf-compass-findings/v1`
+
+## Top-level document
+
+```json
+{
+  "schema": "sf-compass-findings/v1",
+  "tool": "sf-position-integrity-checker",
+  "tool_version": "1.4.0",
+  "generated_at": "2026-06-11T14:32:00",
+  "tenant": "https://***masked***.successfactors.eu",
+  "scope": {
+    "country": "CAN",
+    "as_of_date": "2026-06-11"
+  },
+  "summary": {
+    "total_records": 1240,
+    "findings": 37,
+    "by_severity": { "high": 4, "medium": 21, "low": 12 }
+  },
+  "findings": []
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `schema` | yes | Always `sf-compass-findings/v1` |
+| `tool` | yes | Repo name of the emitting tool |
+| `tool_version` | yes | Version string of the emitting tool |
+| `generated_at` | yes | ISO 8601 local timestamp |
+| `tenant` | no | Masked tenant URL only - never the raw subdomain |
+| `scope` | no | Tool-specific run parameters (country, module, object types) |
+| `summary` | yes | Counts; `by_severity` keys are lowercase severities |
+| `findings` | yes | Array of finding objects, may be empty |
+
+## Finding object
+
+```json
+{
+  "id": "POS-014",
+  "severity": "high",
+  "category": "Org Assignment",
+  "object_type": "Position",
+  "object_id": "POS_10023",
+  "field": "costCenter",
+  "message": "Cost centre is inactive as of the as-of date",
+  "details": {}
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `id` | yes | Stable rule/check identifier within the tool |
+| `severity` | yes | One of `critical`, `high`, `medium`, `low`, `info` (lowercase) |
+| `category` | yes | Tool-defined grouping label |
+| `object_type` | yes | e.g. `Position`, `Picklist`, `ObjectDefinition`, `BusinessRule` |
+| `object_id` | yes | External code / ID of the affected record |
+| `field` | no | Affected field name, if applicable |
+| `message` | yes | Plain-English description of the finding |
+| `details` | no | Free-form object for tool-specific extras |
+
+## Rules
+
+- Severities are normalised to lowercase. Map tool-native scales onto
+  critical/high/medium/low/info before emitting.
+- Never include employee personal data in `message` or `details`. IDs and
+  codes only.
+- Always mask tenant URLs (`***masked***` subdomain convention, see
+  `sapsf_shared.utils`).
+- Emitters write the file alongside their other reports as
+  `<tool>_findings_<datestamp>.json`.
+
+## Current emitters
+
+- `sf-position-integrity-checker` - `write_findings_json` in `reporters.py`
+  (also exposed via its MCP server tool `sf_validate_positions`)
+- `sf-config-debt-radar` - `build_findings_v1` in `cli.py`, written as
+  `config_debt_findings.json` on every scan
+
+## Consumers
+
+- `sf-compass` - [Tenant Findings Viewer](https://sahirvhora.github.io/sf-compass/findings.html)
+  loads any number of v1 files into one combined, filterable view
+
+Planned emitter: sf-config-compare.

sapsf_shared-0.1.0/favicon.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="SF Tools">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#141820"/>
+      <stop offset="100%" stop-color="#0a0d14"/>
+    </linearGradient>
+    <linearGradient id="gold" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#f0c850"/>
+      <stop offset="50%" stop-color="#c8a84e"/>
+      <stop offset="100%" stop-color="#8b6914"/>
+    </linearGradient>
+  </defs>
+  <!-- Background -->
+  <rect x="1" y="1" width="62" height="62" rx="12" fill="url(#bg)" stroke="#1c212b" stroke-width="1.5"/>
+  <!-- SF text -->
+  <text x="32" y="43" font-family="'Segoe UI',system-ui,-apple-system,sans-serif" font-size="28" font-weight="700" fill="url(#gold)" text-anchor="middle" letter-spacing="-1">SF</text>
+  <!-- Subtle accent dot -->
+  <circle cx="48" cy="15" r="3.5" fill="#c8a84e" opacity="0.7"/>
+</svg>

sapsf_shared-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sapsf-shared"
+version = "0.1.0"
+description = "Shared Python SDK for SAP SuccessFactors tools - OData client, auth, config, and Flask base"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [{name = "Sahir Vhora"}]
+keywords = ["sap", "successfactors", "odata", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "requests>=2.31",
+    "pyyaml>=6.0",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SahirVhora/sapsf-shared"
+Repository = "https://github.com/SahirVhora/sapsf-shared"
+Issues = "https://github.com/SahirVhora/sapsf-shared/issues"
+"SF Compass Suite" = "https://sahirvhora.github.io/sf-compass/"
+
+[project.optional-dependencies]
+flask = ["flask>=2.3"]
+dev = [
+    "pytest>=8.0",
+    "pytest-xdist>=3.0",
+    "responses>=0.25",
+    "mypy>=1.0",
+    "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sapsf_shared"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+show_error_codes = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B", "C4", "SIM"]
+ignore = ["E501", "SIM115"]