Metadata-Version: 2.4
Name: hfortix-forticare
Version: 0.5.160
Summary: FortiCare Asset Management API Client
Author: FortiX Development Team
License: MIT
Project-URL: Homepage, https://github.com/hermanwjacobsen/hfortix-dev
Project-URL: Documentation, https://hfortix.readthedocs.io
Project-URL: Repository, https://github.com/hermanwjacobsen/hfortix-dev
Keywords: fortinet,forticare,api,client,asset-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: hfortix-core>=0.5.160
Requires-Dist: httpx>=0.24.0

# hfortix-forticare

Python SDK for Fortinet FortiCare Asset Management V3 API.

## Overview

`hfortix-forticare` provides a fully typed Python interface to the FortiCare Asset Management API, enabling programmatic access to:

- **Product Management**: Register, list, update, and decommission products
- **License Management**: Register, list, and download licenses  
- **Contract Management**: View contract information
- **Folder Management**: Organize assets into folders
- **Service Management**: Register subscription services

## Features

✨ **Fully Typed** - Complete type hints with TypedDict for request/response structures
📝 **Auto-completion** - IDE auto-completion for all parameters and return values
🔒 **OAuth 2.0** - Built-in OAuth Bearer token authentication
🚀 **Modern HTTP** - HTTP/2 support via httpx
🎯 **Explicit Parameters** - All API parameters exposed as function arguments
📚 **Rich Documentation** - Comprehensive docstrings from Swagger specs

## Installation

```bash
pip install hfortix-forticare
```

## Quick Start

### 1. Obtain OAuth Token

First, create an API user through the IAM portal and obtain an OAuth token:

```python
# Get token from FortiAuthenticator OAuth endpoint
# https://customerapiauth.fortinet.com/api/v1/oauth/token
```

### 2. Initialize Client

```python
from hfortix_forticare import FortiCare

fcc = FortiCare(oauth_token="your_oauth_token_here")
```

### 3. Use the API

```python
# List products with entitlements
products = fcc.api.products.list.post(
    serial_number="FGT*",
    status="Registered"
)

# Get product details
details = fcc.api.products.details.post(
    serial_number="FGT90D1234567890"
)

# Register a product
result = fcc.api.products.register.post(
    registration_units=[
        {
            "serialNumber": "FGT90D1234567890",
            "description": "My FortiGate",
            # ... other fields
        }
    ]
)

# List contracts
contracts = fcc.api.contracts.list.post()

# List licenses  
licenses = fcc.api.licenses.list.post()

# Manage folders
folders = fcc.api.folders.list.post()

# Always clean up when done
fcc.logout()
```

## API Structure

The SDK mirrors the FortiCare Asset Management V3 API structure:

```
fcc.api.
  ├── products.
  │   ├── list          - List products with entitlements
  │   ├── register      - Register products and contracts
  │   ├── details       - Get product details
  │   ├── description   - Update product description
  │   ├── location      - Update product location
  │   ├── folder        - Update product folder
  │   ├── decommission  - Decommission products
  │   └── transfer      - Transfer products between accounts
  ├── licenses.
  │   ├── list          - List licenses
  │   ├── register      - Register a license
  │   └── download      - Download VM license file
  ├── contracts.
  │   └── list          - List contracts
  ├── folders.
  │   ├── list          - List asset folders
  │   ├── create        - Create new folder
  │   └── delete        - Delete folder
  └── services.
      └── register      - Register subscription service
```

## Type Safety

All endpoints use TypedDict for request and response structures:

```python
# IDE will show all available parameters
products = fcc.api.products.list.post(
    serial_number="FGT*",     # str
    expire_before="2024...",   # str (ISO 8601)
    status="Registered",       # str
    product_model="...",       # str  
    account_id=12345          # float
)

# Response is also typed
assert products['status'] == 0  # int
assert isinstance(products['message'], str)
assert isinstance(products['assets'], list)
```

## Rate Limits

FortiCare Asset Management API enforces the following limits:

- **100 calls per minute**
- **1000 calls per hour**
- **10 errors per hour**
- **Batch operations**: Max 10 units, max 5 errors per batch

## Error Handling

```python
try:
    result = fcc.api.products.list.post(serial_number="FGT*")
    
    if result['status'] == 0:
        print("Success!")
    else:
        print(f"API Error: {result['message']}")
        
except httpx.HTTPStatusError as e:
    print(f"HTTP Error: {e.response.status_code}")
except httpx.TimeoutException:
    print("Request timed out")
except httpx.RequestError as e:
    print(f"Network error: {e}")
```

## Context Manager

Use as a context manager for automatic cleanup:

```python
with FortiCare(oauth_token="...") as fcc:
    products = fcc.api.products.list.post(...)
    # ... use the client ...
# Automatically logged out
```

## Configuration

```python
fcc = FortiCare(
    oauth_token="your_token",
    base_url="https://support.fortinet.com",  # Default
    verify=True,                               # SSL verification
    max_retries=3,                            # Retry attempts
    connect_timeout=10.0,                     # Connection timeout (seconds)
    read_timeout=300.0                        # Read timeout (seconds)
)
```

## Examples

See [EXAMPLES.py](./EXAMPLES.py) for more comprehensive examples.

## Development

### Regenerating the SDK

If Fortinet updates the API, regenerate the SDK:

```bash
cd packages/forticare/dev/generator
python generate.py --clean
```

This will:
1. Parse updated Swagger JSON files
2. Generate all endpoint classes with type hints
3. Create .pyi stub files for IDE support
4. Generate category and main __init__.py files

### Project Structure

```
packages/forticare/
├── src/
│   └── hfortix_forticare/
│       ├── __init__.py           # Main FortiCare client
│       └── api/
│           └── v3/
│               ├── __init__.py   # V3API class
│               ├── products/     # Product endpoints
│               ├── licenses/     # License endpoints
│               ├── contracts/    # Contract endpoints
│               ├── folders/      # Folder endpoints
│               └── services/     # Service endpoints
├── dev/
│   └── generator/
│       ├── generate.py           # Code generator
│       ├── parsers/              # Swagger parsers
│       ├── generators/           # Code generators
│       ├── templates/            # Code templates
│       └── swagger/              # Swagger JSON files
└── README.md
```

## Requirements

- Python 3.10+
- httpx
- hfortix-core

## License

Copyright © 2024 Fortinet, Inc.

## Links

- [FortiCare API Documentation](http://docs.fortinet.com/document/forticloud/latest/asset-management-api/)
- [OAuth Token Guide](http://docs.fortinet.com/document/fortiauthenticator/6.1.2/rest-api-solution-guide/498666/oauth-server-token-oauth-token)
- [IAM Portal](https://support.fortinet.com/)
