{"id":46354757,"url":"https://github.com/dougborg/stocktrim-openapi-client","last_synced_at":"2026-03-05T00:03:09.078Z","repository":{"id":306335886,"uuid":"1021835524","full_name":"dougborg/stocktrim-openapi-client","owner":"dougborg","description":"Production-ready Python client for the StockTrim Inventory Management API with transport-layer resilience","archived":false,"fork":false,"pushed_at":"2026-01-16T22:00:11.000Z","size":1591,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T06:16:28.474Z","etag":null,"topics":["client","mcp","openapi","stocktrim"],"latest_commit_sha":null,"homepage":"https://dougborg.github.io/stocktrim-openapi-client/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dougborg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/api-feedback.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-18T03:04:59.000Z","updated_at":"2026-01-16T21:57:42.000Z","dependencies_parsed_at":"2025-07-25T04:31:16.897Z","dependency_job_id":"f0cb1292-bc9e-4c49-94d7-3606d57d23b7","html_url":"https://github.com/dougborg/stocktrim-openapi-client","commit_stats":null,"previous_names":["dougborg/stocktrim-openapi-client"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/dougborg/stocktrim-openapi-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fstocktrim-openapi-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fstocktrim-openapi-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fstocktrim-openapi-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fstocktrim-openapi-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dougborg","download_url":"https://codeload.github.com/dougborg/stocktrim-openapi-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fstocktrim-openapi-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30101678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T23:59:36.199Z","status":"ssl_error","status_checked_at":"2026-03-04T23:56:48.556Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","mcp","openapi","stocktrim"],"created_at":"2026-03-05T00:03:04.287Z","updated_at":"2026-03-05T00:03:09.036Z","avatar_url":"https://github.com/dougborg.png","language":"Python","readme":"# StockTrim OpenAPI Client\n\nA production-ready Python client library and MCP server for the\n[StockTrim Inventory Management API](https://www.stocktrim.com/).\n\n[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![CI](https://github.com/dougborg/stocktrim-openapi-client/actions/workflows/ci.yml/badge.svg)](https://github.com/dougborg/stocktrim-openapi-client/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/dougborg/stocktrim-openapi-client/branch/main/graph/badge.svg)](https://codecov.io/gh/dougborg/stocktrim-openapi-client)\n[![Security](https://github.com/dougborg/stocktrim-openapi-client/actions/workflows/security.yml/badge.svg)](https://github.com/dougborg/stocktrim-openapi-client/actions/workflows/security.yml)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n\nClient:\n[![PyPI - Version](https://img.shields.io/pypi/v/stocktrim-openapi-client)](https://pypi.org/project/stocktrim-openapi-client/)\n\nMCP:\n[![PyPI - MCP Server](https://img.shields.io/pypi/v/stocktrim-mcp-server)](https://pypi.org/project/stocktrim-mcp-server/)\n\n## Features\n\n### Client Library\n\n- **🎯 Domain Helpers**: Ergonomic wrapper methods for common operations (15+ convenience\n  functions)\n- **🔄 Transport-Layer Resilience**: Automatic retries with exponential backoff built\n  into HTTP transport\n- **⚡ Modern Python**: Fully async/await with comprehensive type hints (ty strict)\n- **🔐 Custom Authentication**: Automatic handling of StockTrim `api-auth-id` and\n  `api-auth-signature` headers\n- **🛡️ Typed Exceptions**: Structured error handling (AuthenticationError,\n  ValidationError, ServerError, etc.)\n- **📦 OpenAPI Generated**: Always up-to-date with the latest StockTrim API\n\n### MCP Server\n\n- **🤖 AI Integration**: Natural language interface for Claude and other AI assistants\n- **⚡ FastMCP**: High-performance Model Context Protocol implementation\n- **🔧 Production Ready**: 30 tools, 5 workflow prompts, and resource endpoints\n- **🎯 Type-Safe**: Full Pydantic validation for all operations\n- **🏗️ Service Architecture**: Clean service layer with dependency injection\n- **🛡️ Safety Patterns**: User confirmation for destructive operations\n- **📝 Well-Documented**: Comprehensive usage examples and troubleshooting\n\n## Installation\n\n### Client Library\n\n```bash\n# With UV (recommended)\nuv add stocktrim-openapi-client\n\n# With pip\npip install stocktrim-openapi-client\n\n# With Poetry\npoetry add stocktrim-openapi-client\n```\n\n### MCP Server\n\n```bash\n# With UV\nuv add stocktrim-mcp-server\n\n# With pip\npip install stocktrim-mcp-server\n```\n\n## Quick Start\n\n### Using Domain Helpers (Recommended)\n\n```python\nfrom stocktrim_public_api_client import StockTrimClient\n\nasync with StockTrimClient(\n    api_auth_id=\"your_tenant_id\",\n    api_auth_signature=\"your_tenant_name\"\n) as client:\n    # Product operations\n    product = await client.products.find_by_code(\"WIDGET-001\")\n    widgets = await client.products.search(\"WIDGET\")\n    exists = await client.products.exists(\"WIDGET-001\")\n\n    # Customer operations\n    customer = await client.customers.get(\"CUST-001\")\n    customer = await client.customers.find_or_create(\n        \"CUST-002\",\n        name=\"New Customer\",\n        email=\"customer@example.com\"\n    )\n\n    # Inventory operations\n    await client.inventory.set_for_product(\n        product_id=\"123\",\n        stock_on_hand=50.0,\n        stock_on_order=100.0,\n        location_code=\"WAREHOUSE-A\"\n    )\n```\n\n### Using Generated API Methods\n\n```python\nfrom stocktrim_public_api_client import StockTrimClient\nfrom stocktrim_public_api_client.generated.api.products import get_api_products\nfrom stocktrim_public_api_client.utils import unwrap\n\nasync with StockTrimClient(\n    api_auth_id=\"your_tenant_id\",\n    api_auth_signature=\"your_tenant_name\"\n) as client:\n    # Direct API call with automatic retries and auth\n    response = await get_api_products.asyncio_detailed(client=client)\n\n    # Unwrap response or raise typed exception\n    products = unwrap(response)  # Raises AuthenticationError, ServerError, etc.\n```\n\n### MCP Server\n\n```bash\n# Set environment variables\nexport STOCKTRIM_API_AUTH_ID=your_tenant_id\nexport STOCKTRIM_API_AUTH_SIGNATURE=your_tenant_name\n\n# Run server\nuvx stocktrim-mcp-server\n```\n\nFor Claude Desktop integration, see [MCP Server README](stocktrim_mcp_server/README.md).\n\n## Domain Helpers\n\nThe client provides convenient helper classes that wrap the generated API:\n\n### Products\n\n- `find_by_code(code)` - Get product by exact code\n- `search(code_prefix)` - Find products starting with prefix\n- `exists(code)` - Check if product exists\n- `get_all()` - List all products\n- `create(...)` - Create new product\n- `delete(product_id)` - Delete product\n\n### Customers\n\n- `get(code)` - Get customer by code\n- `get_all()` - List all customers\n- `exists(code)` - Check if customer exists\n- `find_or_create(code, **defaults)` - Get or create customer (idempotent)\n- `update(customer)` - Update customer\n\n### Suppliers\n\n- `find_by_code(code)` - Get supplier by code (handles API inconsistencies)\n- `create_one(supplier)` - Create single supplier\n- `exists(code)` - Check if supplier exists\n- `get_all()` - List all suppliers\n- `create([suppliers])` - Batch create suppliers\n- `delete(code)` - Delete supplier\n\n### Sales Orders\n\n- `get_for_product(product_id)` - Get orders for specific product\n- `delete_for_product(product_id)` - Delete all orders for product\n- `get_all()` - List all orders\n- `create(...)` - Create order\n- `delete(...)` - Delete orders\n\n### Purchase Orders\n\n- `find_by_reference(reference_number)` - Get order by reference\n- `exists(reference_number)` - Check if order exists\n- `get_all()` - List all orders\n- `create(...)` - Create order\n- `delete(...)` - Delete orders\n\n### Inventory\n\n- `set_for_product(product_id, stock_on_hand, stock_on_order, ...)` - Set inventory\n  levels\n- `set(request)` - Batch set inventory\n\n### Locations\n\n- `get_all()` - List all locations\n- `create(...)` - Create location\n\nSee [docs/user-guide/helper-methods.md](docs/user-guide/helper-methods.md) for complete\ndocumentation.\n\n## Error Handling\n\nThe client provides typed exceptions for structured error handling:\n\n```python\nfrom stocktrim_public_api_client.utils import (\n    unwrap,\n    AuthenticationError,\n    ValidationError,\n    NotFoundError,\n    ServerError\n)\n\ntry:\n    product = unwrap(response)\nexcept AuthenticationError:\n    print(\"Invalid credentials\")\nexcept ValidationError as e:\n    print(f\"Validation failed: {e.validation_errors}\")\nexcept NotFoundError:\n    print(\"Product not found\")\nexcept ServerError as e:\n    print(f\"Server error: {e.status_code}\")\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Required\nSTOCKTRIM_API_AUTH_ID=your_tenant_id\nSTOCKTRIM_API_AUTH_SIGNATURE=your_tenant_name\n\n# Optional\nSTOCKTRIM_BASE_URL=https://api.stocktrim.com  # Default\n```\n\n### Programmatic Configuration\n\n```python\nasync with StockTrimClient(\n    api_auth_id=\"your_tenant_id\",\n    api_auth_signature=\"your_tenant_name\",\n    base_url=\"https://api.stocktrim.com\",\n    timeout=30.0,\n    max_retries=5\n) as client:\n    # Use client\n    pass\n```\n\n## Architecture\n\n### Transport-Layer Resilience\n\nResilience features are implemented at the HTTP transport level:\n\n- **Automatic retries** on 5xx errors for idempotent methods (GET, HEAD, OPTIONS, TRACE)\n- **Exponential backoff** with jitter to prevent thundering herd\n- **Error logging** with detailed response parsing\n- **Custom authentication** injection without modifying generated code\n\nThis approach ensures:\n\n- ✅ All generated API methods automatically get resilience features\n- ✅ No code changes needed when regenerating from OpenAPI spec\n- ✅ Type safety preserved throughout\n- ✅ Optimal performance (resilience at lowest level)\n\n### Domain Helpers\n\nHelper classes provide:\n\n- **Clear intent** with intuitive method names\n- **API inconsistency handling** (e.g., single vs list returns)\n- **Common patterns** for frequent workflows\n- **Reduced boilerplate** for simple operations\n- **Full type safety** with comprehensive hints\n\n### MCP Server Architecture\n\nThe MCP server is built with a clean, maintainable architecture:\n\n- **Service Layer**: Business logic separated from tool interfaces with dependency\n  injection\n- **Parameter Flattening**: MCP-compatible tool signatures while maintaining type safety\n  (ADR 002)\n- **User Confirmation Pattern**: Destructive operations require explicit confirmation\n  via MCP elicitation (ADR 001)\n- **Structured Logging**: Observability throughout with detailed operation tracking\n- **Template System**: Consistent, formatted responses for forecast operations\n- **Resource Discovery**: Read-only endpoints for context gathering without mutations\n\nSee [Architecture Decision Records](docs/architecture/decisions/) for detailed design\nrationale.\n\n## MCP Server Tools\n\nThe MCP server provides **30 tools** organized into foundation tools and workflow tools:\n\n### Foundation Tools (21 functions)\n\nDirect CRUD operations across all domains:\n\n- **Products**: get, search, create, delete\n- **Customers**: get_customer, list_customers\n- **Suppliers**: get, list, create, delete\n- **Inventory**: set\n- **Sales Orders**: create, get, list, delete\n- **Purchase Orders**: get, list, create, delete\n- **Locations**: list, create\n\n### Workflow Tools (9 functions)\n\nHigh-level business operations combining multiple API calls:\n\n- **Forecast Management**: update_and_monitor, get_for_products, update_settings, manage_group\n- **Urgent Orders**: review_requirements, generate_purchase_orders\n- **Product Management**: configure_lifecycle, configure_product\n- **Supplier Management**: create_supplier_with_products\n\n### MCP Prompts (5 workflow prompts)\n\nGuided workflows for complex operations:\n\n- **purchasing_workflow**: Comprehensive purchase order generation workflow\n- **forecast_accuracy_review**: Analyze and improve forecast accuracy\n- **supplier_performance_review**: Comprehensive supplier analysis\n- **stockout_prevention**: Proactive inventory management and reordering\n- **product_lifecycle_review**: Product performance and lifecycle analysis\n\n### MCP Resources\n\nRead-only discovery endpoints for context:\n\n- **Foundation**: Products, customers, suppliers, locations, inventory\n- **Reports**: inventory-status, urgent-orders, supplier-directory\n\nExample conversation with Claude:\n\n```\nYou: What products do we have starting with \"WID\"?\nClaude: [uses search_products(\"WID\")]\nFound 3 products:\n- WIDGET-001: Standard Widget ($10.00)\n- WIDGET-002: Premium Widget ($15.00)\n- WIDGET-SPECIAL: Custom Widget ($25.00)\n\nYou: Run the purchasing workflow to review urgent orders\nClaude: [uses purchasing_workflow prompt]\nLet me guide you through reviewing urgent orders and generating purchase orders...\n```\n\nSee [stocktrim_mcp_server/README.md](stocktrim_mcp_server/README.md) for detailed usage.\n\n## Code Quality \u0026 Testing\n\nThis project maintains high code quality standards with comprehensive tooling:\n\n### Testing Infrastructure\n\n- **30+ test files** covering client library and MCP server\n- **Test categories**: unit, integration, docs markers for selective execution\n- **pytest** with async support, coverage reporting, and mocking\n- **Separate test suites** for client (~6 files) and MCP server (~23 files)\n- **Code coverage tracking** with pytest-cov (terminal, HTML, and XML reports)\n\n### Linting \u0026 Type Checking\n\n- **Ruff**: Fast Python linter and formatter with comprehensive rule sets\n- **ty**: Astral's strict type checker ensuring full type safety\n- **yamllint**: YAML validation for configuration files\n- **mdformat**: Markdown formatting with GFM and tables support\n\n### Security Scanning\n\n- **Trivy**: Vulnerability scanner (runs weekly and on PRs)\n- **Semgrep**: Static analysis for security patterns (runs weekly and on PRs)\n- **Dependency review**: Automated checks on pull requests\n- Results uploaded to GitHub Security tab for tracking\n\n### CI/CD Pipeline\n\n- **Matrix testing**: Python 3.11, 3.12, 3.13 across all tests\n- **Automated releases**: Semantic versioning with python-semantic-release\n- **Documentation**: Auto-deployed to GitHub Pages on releases\n- **Pre-commit hooks**: Full lint and test suite runs before commits\n- **Codecov integration**: Coverage tracking and reporting\n\n### Quality Commands\n\n```bash\n# Run full quality check suite\nuv run poe check\n\n# Individual checks\nuv run poe format        # Format code with Ruff\nuv run poe lint          # Lint with Ruff\nuv run poe lint-ty       # Type check with ty\nuv run poe test-coverage # Tests with coverage report\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/dougborg/stocktrim-openapi-client.git\ncd stocktrim-openapi-client\n\n# Install UV (if needed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# Install dependencies\nuv sync --all-extras\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\n### Common Tasks\n\n```bash\n# Run tests\nuv run poe test\n\n# Run linting\nuv run poe lint\n\n# Format code\nuv run poe format\n\n# Type check\nuv run ty check\n\n# Regenerate client from OpenAPI spec\nuv run poe regenerate-client\n\n# Build documentation\nuv run poe docs-build\n\n# Run all checks (format + lint + test)\nuv run poe check\n```\n\n### Testing\n\n```bash\n# All tests\nuv run poe test\n\n# With coverage\nuv run poe test-coverage\n\n# Unit tests only\nuv run poe test-unit\n\n# Integration tests only\nuv run poe test-integration\n```\n\n## Project Structure\n\n```\nstocktrim-openapi-client/\n├── stocktrim_public_api_client/   # Client library\n│   ├── stocktrim_client.py        # Main client with transport layer\n│   ├── helpers/                   # Domain helper classes\n│   │   ├── products.py\n│   │   ├── customers.py\n│   │   ├── suppliers.py\n│   │   ├── sales_orders.py\n│   │   ├── purchase_orders.py\n│   │   ├── inventory.py\n│   │   └── locations.py\n│   ├── utils.py                   # Response unwrapping \u0026 exceptions\n│   └── generated/                 # OpenAPI-generated code\n│       ├── api/                   # API endpoint methods\n│       ├── models/                # Data models\n│       └── client.py              # Base client\n├── stocktrim_mcp_server/          # MCP server package\n│   └── src/stocktrim_mcp_server/\n│       ├── server.py              # FastMCP server\n│       └── tools/                 # MCP tool implementations\n├── tests/                         # Test suite\n├── scripts/                       # Development scripts\n└── docs/                          # Documentation\n```\n\n## Documentation\n\n- **Full Documentation**:\n  [https://dougborg.github.io/stocktrim-openapi-client/](https://dougborg.github.io/stocktrim-openapi-client/)\n- **Client Guide**: [docs/user-guide/client-guide.md](docs/user-guide/client-guide.md)\n- **Helper Methods**:\n  [docs/user-guide/helper-methods.md](docs/user-guide/helper-methods.md)\n- **Testing Guide**: [docs/user-guide/testing.md](docs/user-guide/testing.md)\n- **MCP Server**: [stocktrim_mcp_server/README.md](stocktrim_mcp_server/README.md)\n\n## Contributing\n\nContributions are welcome! Please see:\n\n- [Development Setup](#development) above\n- [Code of Conduct](docs/contributing/code-of-conduct.md)\n- [API Feedback](docs/contributing/api-feedback.md) - Constructive feedback for\n  StockTrim developers\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- Built with [httpx](https://www.python-httpx.org/) for modern async HTTP\n- Generated with\n  [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)\n- MCP server built with [FastMCP](https://github.com/jlowin/fastmcp)\n- Architecture patterns inspired by\n  [katana-openapi-client](https://github.com/dougborg/katana-openapi-client)\n\n## Support\n\n- **Issues**:\n  [GitHub Issues](https://github.com/dougborg/stocktrim-openapi-client/issues)\n- **Source**: [GitHub Repository](https://github.com/dougborg/stocktrim-openapi-client)\n- **StockTrim**: [www.stocktrim.com](https://www.stocktrim.com/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdougborg%2Fstocktrim-openapi-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdougborg%2Fstocktrim-openapi-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdougborg%2Fstocktrim-openapi-client/lists"}