servicetitan-pyapi

Name	servicetitan-pyapi JSON
Version	1.0.0 JSON
	download
home_page	https://github.com/n90-co/servicetitan-pyapi
Summary	A comprehensive Python client library for the ServiceTitan API
upload_time	2025-08-08 21:30:33
maintainer	None
docs_url	None
author	Brian Handrigan
requires_python	>=3.8
license	None
keywords	servicetitan api client hvac plumbing field-service crm
VCS
bugtrack_url
requirements	requests python-dateutil
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # ServiceTitan Python API Client

A comprehensive Python client library for the ServiceTitan API, providing easy access to all major endpoints with built-in authentication handling and data pagination.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-58%20passed-green.svg)](https://github.com/n90-co/servicetitan-pyapi/actions)

## � Analysis Notebooks

The `notebooks/` directory contains comprehensive Jupyter notebooks for business analysis:

- **[exploration.ipynb](notebooks/exploration.ipynb)** - Initial data exploration and API familiarization
- **[reporting.ipynb](notebooks/reporting.ipynb)** - Comprehensive business reporting and KPI dashboards
- **[marketing_analysis.ipynb](notebooks/marketing_analysis.ipynb)** - Marketing ROI and campaign performance analysis
- **[performance_monitoring.ipynb](notebooks/performance_monitoring.ipynb)** - Operational performance and efficiency monitoring
- **[customer_journey.ipynb](notebooks/customer_journey.ipynb)** - Customer lifecycle and experience analysis
- **[financial_forecasting.ipynb](notebooks/financial_forecasting.ipynb)** - Financial analysis and business forecasting
- **[data_quality.ipynb](notebooks/data_quality.ipynb)** - Data validation and API testing

See the [notebooks README](notebooks/README.md) for detailed usage instructions.

## 🏗️ Development

- **Complete API Coverage**: Support for customers, jobs, invoices, estimates, appointments, and more
- **Automatic Authentication**: OAuth2 handling with automatic token refresh
- **Smart Pagination**: Seamless handling of large datasets with continuation tokens
- **Type Safety**: Full type hints for better IDE support and fewer errors
- **Comprehensive Testing**: 58 test cases covering all functionality
- **Easy Configuration**: Simple JSON-based configuration
- **Error Handling**: Robust error handling with meaningful messages

## 📦 Installation

### From PyPI (When Published)
```bash
pip install servicetitan-pyapi
```

### From GitHub (Public Repository)
```bash
# Install latest version from main branch
pip install git+https://github.com/n90-co/servicetitan-pyapi.git

# Install specific version/tag
pip install git+https://github.com/n90-co/servicetitan-pyapi.git@v1.0.0

# Install with notebook dependencies for analysis
pip install "git+https://github.com/n90-co/servicetitan-pyapi.git[notebooks]"

# Install with development tools
pip install "git+https://github.com/n90-co/servicetitan-pyapi.git[dev]"
```

### Development Installation
```bash
# Clone repository and install in editable mode
git clone https://github.com/n90-co/servicetitan-pyapi.git
cd servicetitan-pyapi
pip install -e ".[dev,notebooks]"

# Run tests to verify installation
python -m pytest tests/ -v
```

### In Requirements.txt
```txt
# For production use
servicetitan-pyapi>=1.0.0

# Or directly from GitHub
git+https://github.com/n90-co/servicetitan-pyapi.git@v1.0.0
```

## Quick Start

```python
from servicetitan_pyapi import ServiceTitanAPI

# Initialize with config file
api = ServiceTitanAPI("config/servicetitan_config.json")

# Get customers
customers = api.customers.get_all()

# Get recent jobs
jobs = api.jobs.get_batch()

# Get invoices for revenue tracking
invoices = api.invoices.get_all()
```

## Configuration

Create a `servicetitan_config.json` file:

```json
{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "app_key": "your_app_key",
    "tenant_id": "your_tenant_id",
    "_comment": "Production credentials"
}
```

## Testing

The ServiceTitan Python API client includes a comprehensive test suite to ensure reliability and functionality.

### Prerequisites

Install testing dependencies:

```bash
# Basic testing (required)
pip install pytest>=7.0.0 pytest-mock requests-mock

# Optional: For advanced features
pip install pytest-cov pytest-xdist  # Coverage reporting and parallel execution
```

### Running Tests

#### Run All Tests
```bash
# Basic test run
python -m pytest tests/ -v

# Run with detailed output
python -m pytest tests/ -v --tb=long

# Run tests in parallel (requires pytest-xdist)
python -m pytest tests/ -n auto
```

#### Run Specific Test Categories
```bash
# Authentication tests
python -m pytest tests/test_auth.py -v

# Base client functionality
python -m pytest tests/test_base.py -v

# Customer API tests
python -m pytest tests/test_customers.py -v

# Jobs API tests  
python -m pytest tests/test_jobs.py -v

# Marketing Ads API tests
python -m pytest tests/test_marketing_ads.py -v

# Settings API tests
python -m pytest tests/test_settings_simple.py -v
```

#### Run Tests with Coverage
```bash
# Install coverage tool (if not already installed)
pip install pytest-cov

# Run with coverage report
python -m pytest tests/ --cov=servicetitan_pyapi --cov-report=html

# View coverage in terminal
python -m pytest tests/ --cov=servicetitan_pyapi --cov-report=term-missing
```

#### Run Specific Test Functions
```bash
# Test specific functionality
python -m pytest tests/test_auth.py::TestServiceTitanAuth::test_token_refresh_success -v

# Test integration scenarios
python -m pytest tests/test_customers.py::TestCustomersClientIntegration -v
```

#### Basic Commands (No Additional Dependencies Required)
```bash
# These commands work with just pytest, pytest-mock, requests-mock:
python -m pytest tests/ -v                    # Verbose output
python -m pytest tests/ --tb=short           # Short traceback
python -m pytest tests/ --maxfail=1          # Stop on first failure
python -m pytest tests/test_auth.py          # Run specific file
python -m pytest -k "test_auth"              # Run tests matching pattern
```

### Test Structure

The test suite includes:

- **Authentication Tests**: OAuth2 token management, expiry handling, configuration loading
- **Base Client Tests**: HTTP request handling, pagination logic, error handling
- **Service Client Tests**: All API endpoints including customers, jobs, marketing ads, settings
- **Integration Tests**: End-to-end workflows and real API scenarios
- **Mock Testing**: Comprehensive mocking of HTTP responses for reliable testing

### Test Coverage

Current test coverage includes:
- ✅ **58 test cases** covering all major functionality
- ✅ **Authentication & Configuration**: Token refresh, expiry, config file loading
- ✅ **API Client Methods**: All GET endpoints, pagination, batch processing
- ✅ **Error Handling**: HTTP errors, network failures, invalid responses
- ✅ **ServiceTitan Patterns**: Export endpoints, custom URL handling, continuation tokens
- ✅ **Integration Scenarios**: Multi-page data retrieval, complete API workflows

### Running Tests in CI/CD

For automated testing in CI/CD pipelines:

```bash
# Install all testing dependencies
pip install -e ".[dev]" pytest-cov pytest-xdist

# Run tests with XML output for CI (requires pytest-cov)
python -m pytest tests/ --junitxml=test-results.xml --cov=servicetitan_pyapi --cov-report=xml

# For GitHub Actions, GitLab CI, etc. (basic version)
python -m pytest tests/ --tb=short --maxfail=1

# Parallel execution in CI (requires pytest-xdist)
python -m pytest tests/ -n auto --tb=short
```

## Features

- ✅ Full authentication handling with automatic token refresh
- ✅ Support for all major ServiceTitan endpoints
- ✅ Automatic pagination for large datasets
- ✅ Incremental sync support with continuation tokens
- ✅ Built-in reference data resolution
- ✅ Type hints for better IDE support

## Available Clients

- **CRM**: Customers, Locations, Bookings, Leads
- **Operations**: Jobs, Estimates, Appointments
- **Communications**: Calls
- **Financial**: Invoices
- **Marketing**: Campaigns, Categories, Attribution
- **Settings**: Business Units, Employees, Technicians, Tags

## Examples

See the `examples/` directory for detailed usage examples:
- Basic usage and authentication
- Revenue analysis and reporting
- Marketing ROI calculation
- Performance tracking

## Development

### Running Tests
```bash
pytest tests/
```

### Code Formatting
```bash
black servicetitan_api/
flake8 servicetitan_api/
```

## License

MIT License - See LICENSE file for details

### `examples/basic_usage.py`
```python
#!/usr/bin/env python3
"""
Basic usage examples for the ServiceTitan Python API client.
"""

from servicetitan_pyapi import ServiceTitanAPI
from datetime import datetime, timedelta


def main():
    # Initialize API
    api = ServiceTitanAPI("config/servicetitan_config.json")
    
    # Get reference data for lookups
    print("Loading reference data...")
    lookups = api.settings.create_lookup_tables()
    
    # Get recent customers
    print("\nFetching recent customers...")
    customers = api.customers.get_test()
    print(f"Found {len(customers)} customers")
    
    # Get jobs from last 7 days
    print("\nFetching recent jobs...")
    jobs = api.jobs.get_batch()
    
    # Display jobs with business unit names
    for job in jobs.data[:5]:
        bu_id = job.get('businessUnitId')
        bu_name = lookups['business_units'].get(bu_id, 'Unknown')
        print(f"  Job {job['id']}: {bu_name}")
    
    # Track conversions
    print("\nAnalyzing conversions...")
    leads = api.leads.get_batch()
    estimates = api.estimates.get_batch()
    invoices = api.invoices.get_batch()
    
    print(f"  Leads: {len(leads)}")
    print(f"  Estimates: {len(estimates)}")
    print(f"  Invoices: {len(invoices)}")
    
    # Calculate revenue
    total_revenue = sum(i.get('total', 0) for i in invoices.data)
    print(f"  Total Revenue: ${total_revenue:,.2f}")


if __name__ == "__main__":
    main()
```

## How to Use This Structure

### 1. Create the directory structure:
```bash
mkdir -p servicetitan-pyapi/{servicetitan_pyapi/{clients,models,utils},config,examples,tests,notebooks}
```

### 2. Move your existing code:
- Move each client class to its own file in `servicetitan_pyapi/clients/`
- Move `ServiceTitanConfig` and `ServiceTitanAuth` to `servicetitan_pyapi/auth.py`
- Move `BaseClient` and `ExportResponse` to `servicetitan_pyapi/base.py`

### 3. Install the package locally:
```bash
cd servicetitan-pyapi
pip install -e .
```

### 4. Use in any project:
```python
from servicetitan_pyapi import ServiceTitanAPI

api = ServiceTitanAPI("path/to/config.json")
customers = api.customers.get_all()
```

### 5. Use in Jupyter notebooks:
```python
# In any notebook, after installing the package
from servicetitan_pyapi import ServiceTitanAPI
import pandas as pd

api = ServiceTitanAPI()
jobs_data = api.jobs.get_all().data
df = pd.DataFrame(jobs_data)
```

## Benefits of This Structure

1. **Reusable**: Install once, use in any project
2. **Maintainable**: Clear separation of concerns
3. **Testable**: Comprehensive test suite with 58 test cases covering all functionality
4. **Reliable**: Fully tested authentication, pagination, and error handling
5. **Documentable**: Clear structure for documentation
6. **Extensible**: Easy to add new endpoints
7. **Professional**: Follows Python packaging best practices

This structure makes your ServiceTitan API client a proper Python package that you can:
- Import in any project
- Share with team members
- Version control properly
- Extend with new features
- Test thoroughly (58 automated tests included)
- Document clearly
- Deploy with confidence

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Run tests: `python -m pytest tests/ -v`
5. Commit your changes: `git commit -m 'feat: add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Areas Where We Need Help

- 🌟 **New ServiceTitan API endpoints**
- 🐛 **Bug fixes and improvements**
- 📚 **Documentation and examples**
- 🧪 **Additional test coverage**
- ⚡ **Performance optimizations**

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🛡️ Security

For security concerns, please see our [Security Policy](SECURITY.md).

## 📞 Support

- 📚 **Documentation**: Check the README and examples
- 🐛 **Bug Reports**: [Create an issue](https://github.com/n90-co/servicetitan-pyapi/issues/new?template=bug_report.md)
- 💡 **Feature Requests**: [Request a feature](https://github.com/n90-co/servicetitan-pyapi/issues/new?template=feature_request.md)
- 🔌 **New API Endpoints**: [Request endpoint support](https://github.com/n90-co/servicetitan-pyapi/issues/new?template=api_endpoint.md)

## 🙏 Contributors

Thanks to all the amazing people who have contributed to this project! 

<!-- Contributors will be automatically added here via GitHub -->

## ⭐ Star History

If this project helps you, please consider giving it a star! ⭐

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/n90-co/servicetitan-pyapi",
    "name": "servicetitan-pyapi",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "servicetitan api client hvac plumbing field-service crm",
    "author": "Brian Handrigan",
    "author_email": "brian@n90.co",
    "download_url": "https://files.pythonhosted.org/packages/e9/90/91dcb94eed9f15816941179771a07dd0fe39a20858dcf77d1b94356d1744/servicetitan_pyapi-1.0.0.tar.gz",
    "platform": null,
    "description": "# ServiceTitan Python API Client\n\nA comprehensive Python client library for the ServiceTitan API, providing easy access to all major endpoints with built-in authentication handling and data pagination.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Tests](https://img.shields.io/badge/tests-58%20passed-green.svg)](https://github.com/n90-co/servicetitan-pyapi/actions)\n\n## \ufffd Analysis Notebooks\n\nThe `notebooks/` directory contains comprehensive Jupyter notebooks for business analysis:\n\n- **[exploration.ipynb](notebooks/exploration.ipynb)** - Initial data exploration and API familiarization\n- **[reporting.ipynb](notebooks/reporting.ipynb)** - Comprehensive business reporting and KPI dashboards\n- **[marketing_analysis.ipynb](notebooks/marketing_analysis.ipynb)** - Marketing ROI and campaign performance analysis\n- **[performance_monitoring.ipynb](notebooks/performance_monitoring.ipynb)** - Operational performance and efficiency monitoring\n- **[customer_journey.ipynb](notebooks/customer_journey.ipynb)** - Customer lifecycle and experience analysis\n- **[financial_forecasting.ipynb](notebooks/financial_forecasting.ipynb)** - Financial analysis and business forecasting\n- **[data_quality.ipynb](notebooks/data_quality.ipynb)** - Data validation and API testing\n\nSee the [notebooks README](notebooks/README.md) for detailed usage instructions.\n\n## \ud83c\udfd7\ufe0f Development\n\n- **Complete API Coverage**: Support for customers, jobs, invoices, estimates, appointments, and more\n- **Automatic Authentication**: OAuth2 handling with automatic token refresh\n- **Smart Pagination**: Seamless handling of large datasets with continuation tokens\n- **Type Safety**: Full type hints for better IDE support and fewer errors\n- **Comprehensive Testing**: 58 test cases covering all functionality\n- **Easy Configuration**: Simple JSON-based configuration\n- **Error Handling**: Robust error handling with meaningful messages\n\n## \ud83d\udce6 Installation\n\n### From PyPI (When Published)\n```bash\npip install servicetitan-pyapi\n```\n\n### From GitHub (Public Repository)\n```bash\n# Install latest version from main branch\npip install git+https://github.com/n90-co/servicetitan-pyapi.git\n\n# Install specific version/tag\npip install git+https://github.com/n90-co/servicetitan-pyapi.git@v1.0.0\n\n# Install with notebook dependencies for analysis\npip install \"git+https://github.com/n90-co/servicetitan-pyapi.git[notebooks]\"\n\n# Install with development tools\npip install \"git+https://github.com/n90-co/servicetitan-pyapi.git[dev]\"\n```\n\n### Development Installation\n```bash\n# Clone repository and install in editable mode\ngit clone https://github.com/n90-co/servicetitan-pyapi.git\ncd servicetitan-pyapi\npip install -e \".[dev,notebooks]\"\n\n# Run tests to verify installation\npython -m pytest tests/ -v\n```\n\n### In Requirements.txt\n```txt\n# For production use\nservicetitan-pyapi>=1.0.0\n\n# Or directly from GitHub\ngit+https://github.com/n90-co/servicetitan-pyapi.git@v1.0.0\n```\n\n## Quick Start\n\n```python\nfrom servicetitan_pyapi import ServiceTitanAPI\n\n# Initialize with config file\napi = ServiceTitanAPI(\"config/servicetitan_config.json\")\n\n# Get customers\ncustomers = api.customers.get_all()\n\n# Get recent jobs\njobs = api.jobs.get_batch()\n\n# Get invoices for revenue tracking\ninvoices = api.invoices.get_all()\n```\n\n## Configuration\n\nCreate a `servicetitan_config.json` file:\n\n```json\n{\n    \"client_id\": \"your_client_id\",\n    \"client_secret\": \"your_client_secret\",\n    \"app_key\": \"your_app_key\",\n    \"tenant_id\": \"your_tenant_id\",\n    \"_comment\": \"Production credentials\"\n}\n```\n\n## Testing\n\nThe ServiceTitan Python API client includes a comprehensive test suite to ensure reliability and functionality.\n\n### Prerequisites\n\nInstall testing dependencies:\n\n```bash\n# Basic testing (required)\npip install pytest>=7.0.0 pytest-mock requests-mock\n\n# Optional: For advanced features\npip install pytest-cov pytest-xdist  # Coverage reporting and parallel execution\n```\n\n### Running Tests\n\n#### Run All Tests\n```bash\n# Basic test run\npython -m pytest tests/ -v\n\n# Run with detailed output\npython -m pytest tests/ -v --tb=long\n\n# Run tests in parallel (requires pytest-xdist)\npython -m pytest tests/ -n auto\n```\n\n#### Run Specific Test Categories\n```bash\n# Authentication tests\npython -m pytest tests/test_auth.py -v\n\n# Base client functionality\npython -m pytest tests/test_base.py -v\n\n# Customer API tests\npython -m pytest tests/test_customers.py -v\n\n# Jobs API tests  \npython -m pytest tests/test_jobs.py -v\n\n# Marketing Ads API tests\npython -m pytest tests/test_marketing_ads.py -v\n\n# Settings API tests\npython -m pytest tests/test_settings_simple.py -v\n```\n\n#### Run Tests with Coverage\n```bash\n# Install coverage tool (if not already installed)\npip install pytest-cov\n\n# Run with coverage report\npython -m pytest tests/ --cov=servicetitan_pyapi --cov-report=html\n\n# View coverage in terminal\npython -m pytest tests/ --cov=servicetitan_pyapi --cov-report=term-missing\n```\n\n#### Run Specific Test Functions\n```bash\n# Test specific functionality\npython -m pytest tests/test_auth.py::TestServiceTitanAuth::test_token_refresh_success -v\n\n# Test integration scenarios\npython -m pytest tests/test_customers.py::TestCustomersClientIntegration -v\n```\n\n#### Basic Commands (No Additional Dependencies Required)\n```bash\n# These commands work with just pytest, pytest-mock, requests-mock:\npython -m pytest tests/ -v                    # Verbose output\npython -m pytest tests/ --tb=short           # Short traceback\npython -m pytest tests/ --maxfail=1          # Stop on first failure\npython -m pytest tests/test_auth.py          # Run specific file\npython -m pytest -k \"test_auth\"              # Run tests matching pattern\n```\n\n### Test Structure\n\nThe test suite includes:\n\n- **Authentication Tests**: OAuth2 token management, expiry handling, configuration loading\n- **Base Client Tests**: HTTP request handling, pagination logic, error handling\n- **Service Client Tests**: All API endpoints including customers, jobs, marketing ads, settings\n- **Integration Tests**: End-to-end workflows and real API scenarios\n- **Mock Testing**: Comprehensive mocking of HTTP responses for reliable testing\n\n### Test Coverage\n\nCurrent test coverage includes:\n- \u2705 **58 test cases** covering all major functionality\n- \u2705 **Authentication & Configuration**: Token refresh, expiry, config file loading\n- \u2705 **API Client Methods**: All GET endpoints, pagination, batch processing\n- \u2705 **Error Handling**: HTTP errors, network failures, invalid responses\n- \u2705 **ServiceTitan Patterns**: Export endpoints, custom URL handling, continuation tokens\n- \u2705 **Integration Scenarios**: Multi-page data retrieval, complete API workflows\n\n### Running Tests in CI/CD\n\nFor automated testing in CI/CD pipelines:\n\n```bash\n# Install all testing dependencies\npip install -e \".[dev]\" pytest-cov pytest-xdist\n\n# Run tests with XML output for CI (requires pytest-cov)\npython -m pytest tests/ --junitxml=test-results.xml --cov=servicetitan_pyapi --cov-report=xml\n\n# For GitHub Actions, GitLab CI, etc. (basic version)\npython -m pytest tests/ --tb=short --maxfail=1\n\n# Parallel execution in CI (requires pytest-xdist)\npython -m pytest tests/ -n auto --tb=short\n```\n\n## Features\n\n- \u2705 Full authentication handling with automatic token refresh\n- \u2705 Support for all major ServiceTitan endpoints\n- \u2705 Automatic pagination for large datasets\n- \u2705 Incremental sync support with continuation tokens\n- \u2705 Built-in reference data resolution\n- \u2705 Type hints for better IDE support\n\n## Available Clients\n\n- **CRM**: Customers, Locations, Bookings, Leads\n- **Operations**: Jobs, Estimates, Appointments\n- **Communications**: Calls\n- **Financial**: Invoices\n- **Marketing**: Campaigns, Categories, Attribution\n- **Settings**: Business Units, Employees, Technicians, Tags\n\n## Examples\n\nSee the `examples/` directory for detailed usage examples:\n- Basic usage and authentication\n- Revenue analysis and reporting\n- Marketing ROI calculation\n- Performance tracking\n\n## Development\n\n### Running Tests\n```bash\npytest tests/\n```\n\n### Code Formatting\n```bash\nblack servicetitan_api/\nflake8 servicetitan_api/\n```\n\n## License\n\nMIT License - See LICENSE file for details\n\n### `examples/basic_usage.py`\n```python\n#!/usr/bin/env python3\n\"\"\"\nBasic usage examples for the ServiceTitan Python API client.\n\"\"\"\n\nfrom servicetitan_pyapi import ServiceTitanAPI\nfrom datetime import datetime, timedelta\n\n\ndef main():\n    # Initialize API\n    api = ServiceTitanAPI(\"config/servicetitan_config.json\")\n    \n    # Get reference data for lookups\n    print(\"Loading reference data...\")\n    lookups = api.settings.create_lookup_tables()\n    \n    # Get recent customers\n    print(\"\\nFetching recent customers...\")\n    customers = api.customers.get_test()\n    print(f\"Found {len(customers)} customers\")\n    \n    # Get jobs from last 7 days\n    print(\"\\nFetching recent jobs...\")\n    jobs = api.jobs.get_batch()\n    \n    # Display jobs with business unit names\n    for job in jobs.data[:5]:\n        bu_id = job.get('businessUnitId')\n        bu_name = lookups['business_units'].get(bu_id, 'Unknown')\n        print(f\"  Job {job['id']}: {bu_name}\")\n    \n    # Track conversions\n    print(\"\\nAnalyzing conversions...\")\n    leads = api.leads.get_batch()\n    estimates = api.estimates.get_batch()\n    invoices = api.invoices.get_batch()\n    \n    print(f\"  Leads: {len(leads)}\")\n    print(f\"  Estimates: {len(estimates)}\")\n    print(f\"  Invoices: {len(invoices)}\")\n    \n    # Calculate revenue\n    total_revenue = sum(i.get('total', 0) for i in invoices.data)\n    print(f\"  Total Revenue: ${total_revenue:,.2f}\")\n\n\nif __name__ == \"__main__\":\n    main()\n```\n\n## How to Use This Structure\n\n### 1. Create the directory structure:\n```bash\nmkdir -p servicetitan-pyapi/{servicetitan_pyapi/{clients,models,utils},config,examples,tests,notebooks}\n```\n\n### 2. Move your existing code:\n- Move each client class to its own file in `servicetitan_pyapi/clients/`\n- Move `ServiceTitanConfig` and `ServiceTitanAuth` to `servicetitan_pyapi/auth.py`\n- Move `BaseClient` and `ExportResponse` to `servicetitan_pyapi/base.py`\n\n### 3. Install the package locally:\n```bash\ncd servicetitan-pyapi\npip install -e .\n```\n\n### 4. Use in any project:\n```python\nfrom servicetitan_pyapi import ServiceTitanAPI\n\napi = ServiceTitanAPI(\"path/to/config.json\")\ncustomers = api.customers.get_all()\n```\n\n### 5. Use in Jupyter notebooks:\n```python\n# In any notebook, after installing the package\nfrom servicetitan_pyapi import ServiceTitanAPI\nimport pandas as pd\n\napi = ServiceTitanAPI()\njobs_data = api.jobs.get_all().data\ndf = pd.DataFrame(jobs_data)\n```\n\n## Benefits of This Structure\n\n1. **Reusable**: Install once, use in any project\n2. **Maintainable**: Clear separation of concerns\n3. **Testable**: Comprehensive test suite with 58 test cases covering all functionality\n4. **Reliable**: Fully tested authentication, pagination, and error handling\n5. **Documentable**: Clear structure for documentation\n6. **Extensible**: Easy to add new endpoints\n7. **Professional**: Follows Python packaging best practices\n\nThis structure makes your ServiceTitan API client a proper Python package that you can:\n- Import in any project\n- Share with team members\n- Version control properly\n- Extend with new features\n- Test thoroughly (58 automated tests included)\n- Document clearly\n- Deploy with confidence\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Quick Start for Contributors\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Run tests: `python -m pytest tests/ -v`\n5. Commit your changes: `git commit -m 'feat: add amazing feature'`\n6. Push to the branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n### Areas Where We Need Help\n\n- \ud83c\udf1f **New ServiceTitan API endpoints**\n- \ud83d\udc1b **Bug fixes and improvements**\n- \ud83d\udcda **Documentation and examples**\n- \ud83e\uddea **Additional test coverage**\n- \u26a1 **Performance optimizations**\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udee1\ufe0f Security\n\nFor security concerns, please see our [Security Policy](SECURITY.md).\n\n## \ud83d\udcde Support\n\n- \ud83d\udcda **Documentation**: Check the README and examples\n- \ud83d\udc1b **Bug Reports**: [Create an issue](https://github.com/n90-co/servicetitan-pyapi/issues/new?template=bug_report.md)\n- \ud83d\udca1 **Feature Requests**: [Request a feature](https://github.com/n90-co/servicetitan-pyapi/issues/new?template=feature_request.md)\n- \ud83d\udd0c **New API Endpoints**: [Request endpoint support](https://github.com/n90-co/servicetitan-pyapi/issues/new?template=api_endpoint.md)\n\n## \ud83d\ude4f Contributors\n\nThanks to all the amazing people who have contributed to this project! \n\n<!-- Contributors will be automatically added here via GitHub -->\n\n## \u2b50 Star History\n\nIf this project helps you, please consider giving it a star! \u2b50\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A comprehensive Python client library for the ServiceTitan API",
    "version": "1.0.0",
    "project_urls": {
        "Bug Reports": "https://github.com/n90-co/servicetitan-pyapi/issues",
        "Documentation": "https://github.com/n90-co/servicetitan-pyapi#readme",
        "Homepage": "https://github.com/n90-co/servicetitan-pyapi",
        "Source": "https://github.com/n90-co/servicetitan-pyapi"
    },
    "split_keywords": [
        "servicetitan",
        "api",
        "client",
        "hvac",
        "plumbing",
        "field-service",
        "crm"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "a9aecd436376847f4c6349d50d75c0b45843f538b00accbf74df3fb31b3c906d",
                "md5": "3bcde1e870580d04dfe9d84c01faea73",
                "sha256": "79dfc49b82d662c933fee49c3d8f6b71c1abad2561b507e4c33cec9147716d8a"
            },
            "downloads": -1,
            "filename": "servicetitan_pyapi-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3bcde1e870580d04dfe9d84c01faea73",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 43644,
            "upload_time": "2025-08-08T21:30:32",
            "upload_time_iso_8601": "2025-08-08T21:30:32.380343Z",
            "url": "https://files.pythonhosted.org/packages/a9/ae/cd436376847f4c6349d50d75c0b45843f538b00accbf74df3fb31b3c906d/servicetitan_pyapi-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "e99091dcb94eed9f15816941179771a07dd0fe39a20858dcf77d1b94356d1744",
                "md5": "6f883060e7e3995d763dc7c5d5aa573e",
                "sha256": "b3a074d9c97f8d0bfcdf26aaf6c41f08d605a7126665fe07a9143bfb66f405fc"
            },
            "downloads": -1,
            "filename": "servicetitan_pyapi-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6f883060e7e3995d763dc7c5d5aa573e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 42182,
            "upload_time": "2025-08-08T21:30:33",
            "upload_time_iso_8601": "2025-08-08T21:30:33.534955Z",
            "url": "https://files.pythonhosted.org/packages/e9/90/91dcb94eed9f15816941179771a07dd0fe39a20858dcf77d1b94356d1744/servicetitan_pyapi-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-08 21:30:33",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "n90-co",
    "github_project": "servicetitan-pyapi",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "requests",
            "specs": [
                [
                    ">=",
                    "2.28.0"
                ]
            ]
        },
        {
            "name": "python-dateutil",
            "specs": [
                [
                    ">=",
                    "2.8.2"
                ]
            ]
        }
    ],
    "lcname": "servicetitan-pyapi"
}