===============
LIBRARY RULES
===============
From library maintainers:
- Include all documentation and examples relevant to implementing NSPS connectors.
- Include OpenAPI.json to provide API schema and event/request examples.
- Focus on requirements, configuration, error handling, logging, request/response formats, and workflow sections.

### Run Local MkDocs Development Server

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/README.md

Starts a local web server to preview the documentation. Changes made to the documentation files will be reflected automatically. The server typically runs on http://127.0.0.1:8000/.

```bash
mkdocs serve
# then open http://127.0.0.1:8000/
```

--------------------------------

### Install Project Dependencies with Pip

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/README.md

Installs all required Python packages listed in the 'requirements.txt' file using pip. This ensures all necessary libraries are available for the project.

```bash
pip install -r requirements.txt
```

--------------------------------

### Verify MkDocs Installation

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/README.md

Checks the installed version of MkDocs to confirm successful installation. MkDocs is the static site generator used for this project.

```bash
mkdocs --version
```

--------------------------------

### Clone Repository using Git

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/README.md

Clones the NSPS connector documentation repository from GitHub and navigates into the project directory. This is the initial step to obtain the project files.

```bash
git clone https://github.com/Mogorno/NSPS-connector-docs.git
cd NSPS-connector-docs
```

--------------------------------

### FastAPI Application Setup

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Initializes the FastAPI application with a title, description, and version. This forms the base for the microservice's API.

```python
app = FastAPI(
    title="HLR/HSS Connector Microservice",
    description="Processes PortaBilling ESPF events (post-NSPS) and syncs with HLR/HSS Core system",
    version="1.0.0",
)
```

--------------------------------

### Build Static MkDocs Site

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/README.md

Generates the static HTML, CSS, and JavaScript files for the documentation website. These files are typically output to a 'site' directory and can be deployed to any web server.

```bash
mkdocs build
```

--------------------------------

### Example PortaBilling ESPF Webhook Event (JSON)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/NSPS/data-flows.md

This snippet shows an example of a webhook event received by NSPS from PortaBilling ESPF. It contains minimal information, primarily the event type and variables related to the event. The 'variables' object's content can differ based on the 'event_type'.

```json
{
    "event_type": "SIM/Updated",
    "variables": {
        "i_env": 3,
        "i_event": 999999,
        "i_account": 277147,
        "event_time": "2025-05-01 12:00:00"
    }
}
```

--------------------------------

### HTTP Bearer Authentication Setup

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Sets up HTTP Bearer authentication using FastAPI's security utilities. This involves defining the security scheme.

```python
security = HTTPBearer()
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/README.md

Creates a new Python virtual environment named '.venv' and activates it. This isolates project dependencies. Activation commands differ for Linux/macOS and Windows.

```bash
# create venv
python -m venv .venv

# activate venv
# On Linux/macOS:
source .venv/bin/activate
# On Windows (PowerShell):
.venv\Scripts\Activate
```

--------------------------------

### VDCounterInfo JSON Example

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

This JSON object represents an example of the VDCounterInfo structure. It outlines the fields and their typical values for a specific service, such as 'Internet Access KB'.

```json
{
    "service_name":"Internet Access KB",
    "vdp_name":"DEV WTL Free 10MB (1 day)",
    "i_vd_plan":204,
    "i_dest_group":2650,
    "addon_priority":10,
    "i_vd_dg":283,
    "remaining":"10",
    "i_service":106,
    "dg_name":"RG100",
    "discount_info":"0..10 - 100%",
    "unit":"megabyte",
    "allocated_amount":10
}
```

--------------------------------

### Copy Markdown Files with Python Script

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/README.md

Executes a Python script named 'copy_md.py'. This script is used to make Markdown files available at the same URL as their corresponding HTML files, likely for search or linking purposes.

```python
python copy_md.py
```

--------------------------------

### Process Event

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/testing.md

Submit event data to the NSPS Connector for processing.

```APIDOC
## POST /event

### Description
Sends event data to the NSPS Connector for processing. It requires proper authentication and a JSON payload with the event details.

### Method
POST

### Endpoint
`/event`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event_id** (string) - Required - A unique identifier for the event.
- **data** (object) - Required - Contains event type and variables.
  - **event_type** (string) - Required - The type of the event (e.g., "SIM/Updated").
  - **variables** (object) - Required - Key-value pairs of event-specific variables.
- **pb_data** (object) - Required - Payload data containing account, SIM, and access policy information.
  - **account_info** (object) - Account-specific details.
  - **sim_info** (object) - SIM card details.
  - **access_policy_info** (object) - Access policy details.
- **handler_id** (string) - Required - Identifier for the handler processing the event.
- **created_at** (string) - Required - Timestamp when the event was created.
- **updated_at** (string) - Required - Timestamp when the event was last updated.
- **status** (string) - Required - The current status of the event processing.

### Request Example
```json
{
    "event_id": "3e84c79f-ab6f-4546-8e27-0b6ab866f1fb",
    "data": {
        "event_type": "SIM/Updated",
        "variables": {
            "i_env": 1,
            "i_event": 999999,
            "i_account": 1,
            "curr_status": "used",
            "prev_status": "active"
        }
    },
    "pb_data": {
        "account_info": {
            "bill_status": "open",
            "billing_model": "credit_account",
            "blocked": false,
            "firstname": "Serhii",
            "i_account": 1,
            "i_customer": 6392,
            "i_product": 3774,
            "id": "79123456789@msisdn",
            "lastname": "Dolhopolov",
            "phone1": "",
            "product_name": "Pay as you go",
            "time_zone_name": "Europe/Prague",
            "assigned_addons": [
                {
                    "addon_effective_from": "2025-05-16T12:59:46",
                    "addon_priority": 10,
                    "description": "",
                    "i_product": 3775,
                    "i_vd_plan": 1591,
                    "name": "Youtube UHD"
                }
            ],
            "service_features": [
                {
                    "name": "netaccess_policy",
                    "effective_flag_value": "Y",
                    "attributes": [
                        {
                            "name": "access_policy",
                            "effective_value": "179"
                        }
                    ]
                }
            ]
        },
        "sim_info": {
            "i_sim_card": 3793,
            "imsi": "001010000020349",
            "msisdn": "79123456789",
            "status": "active"
        },
        "access_policy_info": {
            "i_access_policy": 179,
            "name": "Integration test",
            "attributes": [
                {
                    "group_name": "lte.wtl",
                    "name": "cs_profile",
                    "value": "cs-pp-20250319"
                },
                {
                    "group_name": "lte.wtl",
                    "name": "eps_profile",
                    "value": "eps-pp-20250319"
                }
            ]
        }
    },
    "handler_id": "hlr-hss-nsps",
    "created_at": "2025-03-12T16:47:30.443939+00:00",
    "updated_at": "2025-03-12T16:47:36.585885+00:00",
    "status": "received"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirms successful event processing.

#### Response Example
```json
{ "message": "Event processed successfully" }
```
```

--------------------------------

### ESPF Event Data Example (JSON)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

An example of the ESPF event payload generated by EventSender. This event contains basic information like event type, account ID, environment, and event timestamps.

```json
{
    "event_type":"SIM/Updated",
    "variables":{
      "i_env":3,
      "i_event":999999,
      "i_account":277147,
      "event_time":"2025-05-01 12:00:00"
    }
}
```

--------------------------------

### ProductInfo Structure and Example

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

Outlines the structure for Product Information, related to PortaBillingData. Key fields include product name, description, product ID, virtual data plan ID, and add-on priority. The addon_priority field uses a numerical scale to denote priority levels, with 0 representing the main product.

```json
{
    "name":"DEV WTL Pay as you go",
    "description":"",
    "addon_priority":0,
    "i_product":658
}
```

--------------------------------

### Example Enriched Event for Connector Microservices (JSON)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/NSPS/data-flows.md

This snippet illustrates an enriched event generated by NSPS and sent to downstream connector microservices. It includes comprehensive data, such as account information, SIM details, access policies, and product information, used for provisioning and external system integration. The 'pb_data' object contains detailed information from PortaBilling.

```json
{
    "event_id":"3e84c79f-ab6f-4546-8e27-0b6ab866f1fb",
    "data":{
        "event_type":"SIM/Updated",
        "variables":{
            "i_env":1,
            "i_event":999999,
            "i_account":1,
            "curr_status":"used",
            "prev_status":"active"
        }
    },
    "pb_data":{
        "account_info":{
            "bill_status":"open",
            "billing_model":"credit_account",
            "blocked":false,
            "i_account":1,
            "i_customer":6392,
            "i_product":3774,
            "id":"79123456789@msisdn",
            "phone1":"",
            "product_name":"wtl Pay as you go",
            "time_zone_name":"Europe/Prague",
            "assigned_addons":[
                {
                    "addon_effective_from":"2025-05-16T12:59:46",
                    "addon_priority":10,
                    "description":"",
                    "i_product":3775,
                    "i_vd_plan":1591,
                    "name":"wtl Youtube UHD"
                }
            ],
            "service_features":[
                {
                    "name":"netaccess_policy",
                    "effective_flag_value":"Y",
                    "attributes":[
                        {
                            "name":"access_policy",
                            "effective_value":"179"
                        }
                    ]
                }
            ]
        },
        "sim_info":{
            "i_sim_card":3793,
            "imsi":"001010000020349",
            "msisdn":"79123456789",
            "status":"active"
        },
        "access_policy_info":{
            "i_access_policy":179,
            "name":"WTL integration test",
            "attributes":[
                {
                    "group_name":"lte.wtl",
                    "name":"cs_profile",
                    "value":"cs-pp-20250319"
                },
                {
                    "group_name":"lte.wtl",
                    "name":"eps_profile",
                    "value":"eps-pp-20250319"
                }
            ]
        },
        "product_info":{
            "name":"DEV WTL Pay as you go",
            "description":"",
            "addon_priority":0,
            "i_product":658
        },
        "full_vd_counter_info":[
            {
                "service_name":"Internet Access KB",
                "vdp_name":"DEV WTL Free 10MB (1 day)",
                "i_vd_plan":204,
                "i_dest_group":2650,
                "addon_priority":10,
                "i_vd_dg":283,
                "remaining":"10",
                "i_service":106,
                "dg_name":"RG100",
                "discount_info":"0..10 - 100%",
                "unit":"megabyte",
                "allocated_amount":10
            }
        ]
    },
    "handler_id":"wtl-hlr-hss-nsps",
    "created_at":"2025-03-12T16:47:30.443939+00:00",
    "updated_at":"2025-03-12T16:47:36.585885+00:00",
    "status":"received"
}
```

--------------------------------

### Health Check

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/testing.md

Check the status of the NSPS Connector service to ensure it is running.

```APIDOC
## GET /

### Description
Checks if the NSPS Connector service is operational.

### Method
GET

### Endpoint
`/`

### Parameters
None

### Request Example
```bash
curl https://[TAG---]SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service, expected to be "Healthy".

#### Response Example
```json
{
    "status": "Healthy"
}
```
```

--------------------------------

### AssignedAddon JSON Example

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

This JSON object details an assigned add-on product for an account. It includes activation dates, priority, product identifiers, and the add-on's name. This structure is part of the broader account information.

```json
{
    "addon_effective_from": "2025-05-16T12:59:46",
    "addon_priority": 10,
    "description": "",
    "i_product": 3775,
    "i_vd_plan": 1591,
    "name": "wtl Youtube UHD"
}
```

--------------------------------

### Health Check NSPS Connector Service

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/testing.md

Performs a health check on the NSPS Connector service by sending a GET request to its endpoint. It verifies if the service is running and responsive. The expected response is a JSON object indicating a 'Healthy' status.

```bash
$ curl https://[TAG---]SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
```

```json
{
    "status": "Healthy"
}
```

--------------------------------

### Health Endpoint

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/requirements.md

Provides a GET endpoint to check the availability and operational status of the NSPS Connector.

```APIDOC
## GET /health

### Description
This endpoint is used to check the availability of the NSPS connector. It should return a successful status code if the connector is operational.

### Method
GET

### Endpoint
/health

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the connector (e.g., "OK").

#### Response Example
```json
{
  "status": "OK"
}
```
```

--------------------------------

### AccountInfo JSON Example

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

This JSON object represents the account information, including billing status, billing model, account identifiers, product details, timezone, assigned add-ons, and service features. It is used to retrieve comprehensive details about a customer's account.

```json
{
    "bill_status": "open",
    "billing_model": "credit_account",
    "blocked": false,
    "i_account": 1,
    "i_customer": 6392,
    "i_product": 3774,
    "id": "79123456789@msisdn",
    "phone1": "",
    "product_name": "wtl Pay as you go",
    "time_zone_name": "Europe/Prague",
    "assigned_addons": [
        {
            "addon_effective_from": "2025-05-16T12:59:46",
            "addon_priority": 10,
            "description": "",
            "i_product": 3775,
            "i_vd_plan": 1591,
            "name": "wtl Youtube UHD"
        }
    ],
    "service_features": [
        {
            "name": "netaccess_policy",
            "effective_flag_value": "Y",
            "attributes": [
                {
                    "name": "access_policy",
                    "effective_value": "179"
                }
            ]
        }
    ]
}
```

--------------------------------

### Extract CS Profile (Python)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Retrieves the CS (Circuit Switched) profile information. It uses a helper method to get the profile, falling back to a default value defined in settings if the profile is not explicitly found. This is necessary for configuring subscriber services.

```python
def get_cs_profile(self) -> str:
    return self._get_profile("cs_profile", settings.WTL_DEFAULT_CS_PROFILE)
```

--------------------------------

### Send Data Request to NSPS Connector Service

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/testing.md

Sends a POST request with a JSON payload to the NSPS Connector service to process an event. Requires authentication via a Bearer token and specifies the content type as JSON. The payload includes detailed event and account information. The expected response is a success message.

```bash
curl -X POST https://[TAG---]SERVICE_NAME-PROJECT_NUMBER.REGION.run.app \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "3e84c79f-ab6f-4546-8e27-0b6ab866f1fb",
    "data": {
      "event_type": "SIM/Updated",
      "variables": {
        "i_env": 1,
        "i_event": 999999,
        "i_account": 1,
        "curr_status": "used",
        "prev_status": "active"
      }
    },
    "pb_data": {
      "account_info": {
        "bill_status": "open",
        "billing_model": "credit_account",
        "blocked": false,
        "firstname": "Serhii",
        "i_account": 1,
        "i_customer": 6392,
        "i_product": 3774,
        "id": "79123456789@msisdn",
        "lastname": "Dolhopolov",
        "phone1": "",
        "product_name": "Pay as you go",
        "time_zone_name": "Europe/Prague",
        "assigned_addons": [
          {
            "addon_effective_from": "2025-05-16T12:59:46",
            "addon_priority": 10,
            "description": "",
            "i_product": 3775,
            "i_vd_plan": 1591,
            "name": "Youtube UHD"
          }
        ],
        "service_features": [
          {
            "name": "netaccess_policy",
            "effective_flag_value": "Y",
            "attributes": [
              {
                "name": "access_policy",
                "effective_value": "179"
              }
            ]
          }
        ]
      },
      "sim_info": {
        "i_sim_card": 3793,
        "imsi": "001010000020349",
        "msisdn": "79123456789",
        "status": "active"
      },
      "access_policy_info": {
        "i_access_policy": 179,
        "name": "Integration test",
        "attributes": [
          {
            "group_name": "lte.wtl",
            "name": "cs_profile",
            "value": "cs-pp-20250319"
          },
          {
            "group_name": "lte.wtl",
            "name": "eps_profile",
            "value": "eps-pp-20250319"
          }
        ]
      }
    },
    "handler_id": "hlr-hss-nsps",
    "created_at": "2025-03-12T16:47:30.443939+00:00",
    "updated_at": "2025-03-12T16:47:36.585885+00:00",
    "status": "received"
  }'
```

```json
{
  "message": "Event processed successfully"
}
```

--------------------------------

### SimInfo Structure and Example

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

Defines the structure for SIM card information, including its relation to PortaBillingData. It details fields such as account ID, SIM card ID, ICCID, IMSI, MSISDN, and status. The status field has specific enumerated values indicating the SIM card's lifecycle state.

```json
{
    "i_sim_card": 3793,
    "imsi": "001010000020349",
    "msisdn": "79123456789",
    "status": "active"
}
```

--------------------------------

### AccessPolicyInfo Structure and Example

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

Details the structure for Access Policy information, linked to PortaBillingData. It includes the access policy ID, name, and a list of attributes. Each attribute has a group name, attribute name, and its value, which can be a comma-separated list if multiple values are present.

```json
{
    "i_access_policy":179,
    "name":"WTL integration test",
    "attributes":[
        {
            "group_name":"lte.wtl",
            "name":"cs_profile",
            "value":"cs-pp-20250319"
        },
        {
            "group_name":"lte.wtl",
            "name":"eps_profile",
            "value":"eps-pp-20250319"
        }
    ]
}
```

--------------------------------

### ServiceFeature JSON Example

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

This JSON object represents a service feature assigned to an account, including its name, effective flag value, and a list of attributes. This structure is used within the AccountInfo to specify active service configurations.

```json
{
    "name": "netaccess_policy",
    "effective_flag_value": "Y",
    "attributes": [
        {
            "name": "access_policy",
            "effective_value": "179"
        }
    ]
}
```

--------------------------------

### POST /process-event

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/workflow.md

Processes incoming events to determine provisioning actions and interact with the WTL API. It handles authentication, validation, data extraction, and external API calls.

```APIDOC
## POST /process-event

### Description
Processes incoming events to determine provisioning actions and interact with the WTL API. It handles authentication, validation, data extraction, and external API calls.

### Method
POST

### Endpoint
/process-event

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event_type** (string) - Required - The type of event to process.
- **data** (object) - Required - The main data payload for the event.
- **pb_data** (object) - Optional - Additional payload data for provisioning.
  - **account_info** (object) - Optional - Account information.
    - **id** (string) - Optional - MSISDN when bill_status is 'open'.
  - **blocked** (boolean) - Optional - Indicates if the subscriber is blocked.
  - **cs_profile** (string) - Optional - Customer Service profile.
  - **eps_profile** (string) - Optional - Enhanced Profile Service profile.

### Request Example
```json
{
  "event_type": "SUBSCRIPTION_ACTIVATION",
  "data": {
    "subscriberId": "1234567890"
  },
  "pb_data": {
    "account_info": {
      "id": "1234567890",
      "bill_status": "open"
    },
    "blocked": false,
    "cs_profile": "DEFAULT_CS",
    "eps_profile": "DEFAULT_EPS"
  }
}
```

### Response
#### Success Response (202 Accepted)
- **status** (string) - "accepted"
- **message** (string) - "Event processed successfully."

#### Response Example
```json
{
  "status": "accepted",
  "message": "Event processed successfully."
}
```

#### Error Response
- **status** (string) - "error"
- **message** (string) - A description of the error.
- **code** (integer) - An error code.

#### Error Response Example
```json
{
  "status": "error",
  "message": "Invalid payload format.",
  "code": 400
}
```
```

--------------------------------

### Build Unified WTL Sync Request (Python)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Constructs a `UnifiedSyncRequest` object, aggregating essential subscriber data including IMSI, subscriber status, MSISDN list, CS and EPS profiles, and the provisioning action. Utilizes Pydantic for robust data validation before sending the request to the WTL API.

```python
request_data = UnifiedSyncRequest(
    imsi=imsi,
    subscriber_status=subscriber_status,
    msisdn=msisdn_list,
    cs_profile=processor.get_cs_profile(),
    eps_profile=processor.get_eps_profile(),
    action=action,
)
```

--------------------------------

### Create Event to WTL Action Mapper (Python)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Implements a Pydantic model for mapping event types to WTL actions. It takes an event type as input and provides a property to retrieve the corresponding WTL action using the predefined `EVENT_ACTION_MAP`. This facilitates dynamic action determination based on incoming events.

```python
class EventWTLActionMapper(BaseModel):
    event_type: str

    @property
    def action(self) -> str:
        return EVENT_ACTION_MAP.get(self.event_type)
```

--------------------------------

### Define /process-event POST Endpoint

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Defines the main POST endpoint '/process-event' that accepts event data. It includes authentication dependency and specifies the response model and status code.

```python
@app.post(
    "/process-event",
    dependencies=[Depends(verify_token)],
    response_model=EventResponse,
    status_code=status.HTTP_202_ACCEPTED,
)
async def process_event(event_data: Event):
    return event_processor.process_event(event_data)
```

--------------------------------

### Map Event Types to WTL Actions (Python)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Establishes a mapping between `EventType` instances and `WTLProvAction` instances. This dictionary is crucial for translating external event types into internal WTL provisioning actions. It supports a clear and extensible way to define event handling.

```python
EVENT_ACTION_MAP = {
    EventType.SIM_UPDATED: WTLProvAction.UPDATE,
}
```

--------------------------------

### Request Context Middleware

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

A middleware that sets the request context before processing the request and logs the completion of the HTTP request in JSON format, including status codes.

```python
async def request_context_middleware(request: Request, call_next):
    set_request_context(request)
    response = await call_next(request)
    logger.info(
        "HTTP request completed",
        extra={"status_code": response.status_code},
    )
    return response
```

--------------------------------

### Process Event API

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

This endpoint accepts event requests, validates them, and initiates the processing workflow. It's protected by Bearer token authentication.

```APIDOC
## POST /process-event

### Description
Accepts an event request, validates the payload against the Event schema, and initiates the processing workflow. This endpoint is protected by Bearer token authentication.

### Method
POST

### Endpoint
/process-event

### Parameters
#### Query Parameters
None

#### Request Body
- **event_id** (string) - Required - Unique identifier of the event.
- **data** (object) - Required - Event data containing type and variables.
  - **event_type** (string) - Required - The type of the event.
  - **variables** (object) - Optional - All event variables passed as-is from original event.
- **pb_data** (object) - Optional - Simplified PortaBilling data with only essential fields.

### Request Example
```json
{
  "event_id": "a3623086-24c2-47fb-a17f-929d9e542ed2",
  "data": {
    "event_type": "SIM/Updated",
    "variables": {
      "msisdn": "1234567890",
      "imsi": "9876543210"
    }
  },
  "pb_data": {
    "account_id": "12345"
  }
}
```

### Response
#### Success Response (202 Accepted)
- **message** (string) - Indicates that the event has been accepted for processing.

#### Response Example
```json
{
  "message": "Event accepted for processing"
}
```

#### Error Response (401 Unauthorized)
- **detail** (string) - "Invalid access token"
- **headers** - {"WWW-Authenticate": "Bearer"}

#### Error Response (422 Unprocessable Entity)
- **detail** (array) - Validation error details.
```

--------------------------------

### Pydantic Event Model Definition

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Defines the Pydantic model `Event` for incoming requests, specifying required fields like `event_id`, `data` (nested `ESPFEvent`), and an optional `pb_data`.

```python
class Event(BaseModel):
    event_id: str = Field(
        description="Unique identifier of the event",
        examples=["a3623086-24c2-47fb-a17f-929d9e542ed2"]
    )
    data: ESPFEvent = Field(
        description="Event data containing type and variables"
    )
    pb_data: Optional[PBData] = Field(
        None,
        description="Simplified PortaBilling data with only essential fields"
    )
```

--------------------------------

### VDCounterInfo

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

The VDCounterInfo type describes the VD counter information retrieved from PortaBilling. It includes details about discounts, destination groups, bundle plans, and service usage.

```APIDOC
## VDCounterInfo Structure

### Description
This section details the fields available within the `VDCounterInfo` object, which represents virtual destination counter information from PortaBilling.

### Fields

#### `discount_info`
- **Type**: `str`
- **Description**: Short representation of the discount details (e.g., '0..60 - 100%').

#### `dg_name`
- **Type**: `str`
- **Description**: The name of the destination group the bundle item is applied to.

#### `i_vd_plan`
- **Type**: `int`
- **Description**: The unique ID of the bundle.

#### `i_dest_group`
- **Type**: `int`
- **Description**: The unique ID of the destination group the discount is applied to.

#### `allocated_amount`
- **Type**: `float`
- **Description**: The total amount of service volume allocated to the customer/account in the current usage period.

#### `unit`
- **Type**: `str`
- **Description**: The name of the service unit or currency used.

#### `addon_priority`
- **Type**: `int`
- **Description**: The priority level of the bundle item. Possible values range from -1 (no priority) to 255 (not part of a product).

#### `vdp_name`
- **Type**: `str`
- **Description**: The name of the bundle.

#### `i_vd_dg`
- **Type**: `int`
- **Description**: The unique ID of the bundle item.

#### `i_service`
- **Type**: `int`
- **Description**: The unique ID of the service.

#### `service_name`
- **Type**: `str`
- **Description**: The name of the service the discount is applied to.

#### `remaining`
- **Type**: `float/str`
- **Description**: The service volume that remains to be used to reach the current threshold. Can be a numeric value or a string like 'N/A'.

### Example Response

```json
{
    "service_name":"Internet Access KB",
    "vdp_name":"DEV WTL Free 10MB (1 day)",
    "i_vd_plan":204,
    "i_dest_group":2650,
    "addon_priority":10,
    "i_vd_dg":283,
    "remaining":"10",
    "i_service":106,
    "dg_name":"RG100",
    "discount_info":"0..10 - 100%",
    "unit":"megabyte",
    "allocated_amount":10
}
```
```

--------------------------------

### Define WTL Provisioning Actions (Python)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Defines an enumeration for WTL provisioning actions, serving as a standardized set of operations for the WTL system. This enum is used to map incoming event types to specific WTL actions.

```python
class WTLProvAction(str, Enum):
    INSERT = "insert"
    UPDATE = "update"
    DELETE = "delete"
    SET = "set"
    UNSET = "unset"
    MODIFY = "modify"
```

--------------------------------

### Account Info API

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

Retrieve detailed information about a specific account. This endpoint provides access to billing status, account type, blocking status, contact details, and associated product information.

```APIDOC
## GET /api/accounts/{accountId}/info

### Description
Retrieves comprehensive account information, including billing details, status, product assignments, and owner contact information.

### Method
GET

### Endpoint
`/api/accounts/{accountId}/info`

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The unique identifier for the account.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **bill_status** (string) - The billing status of the account.
- **billing_model** (string) - The account type.
- **blocked** (bool) - Indicates if the account's calls and self-care access are blocked.
- **email** (string) - The email address associated with the account.
- **firstname** (string) - The account owner's first name.
- **i_account** (int) - Internal ID of the account.
- **i_customer** (int) - The ID of the customer record to which the account belongs.
- **i_master_account** (int) - The ID of the parent account.
- **i_product** (int) - The ID for the account's product.
- **i_vd_plan** (int) - The unique ID of the bundle assigned to the account individually.
- **id** (string) - Charging ID (MSISDN, ICCID or IMSI) of the account on the network.
- **lastname** (string) - The account owner's last name.
- **phone1** (string) - The main phone number.
- **product_name** (string) - The name of the account's product.
- **status** (string) - The current status of the account.
- **time_zone_name** (string) - The name of the account's time zone.
- **zip** (string) - The postal (zip) code.
- **assigned_addons** (List[AssignedAddon]) - List of account's add-on products.
- **service_features** (List[AssignedAddon]) - List of service features.

#### Response Example
```json
{
  "bill_status": "active",
  "billing_model": "credit_account",
  "blocked": false,
  "email": "john.doe@example.com",
  "firstname": "John",
  "i_account": 12345,
  "i_customer": 67890,
  "i_master_account": null,
  "i_product": 111,
  "i_vd_plan": 222,
  "id": "+1234567890",
  "lastname": "Doe",
  "phone1": "+1234567890",
  "product_name": "Basic Plan",
  "status": "active",
  "time_zone_name": "America/New_York",
  "zip": "10001",
  "assigned_addons": [
    {
      "id": "addon1",
      "name": "Extra Data"
    }
  ],
  "service_features": [
    {
      "id": "feature1",
      "name": "Voicemail"
    }
  ]
}
```
```

--------------------------------

### Return successful response in Python

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

This code snippet shows how to return a JSON response with a 202 Accepted status code using FastAPI's JSONResponse. This indicates successful reception and processing (or queuing) of an event by the NSPS connector.

```python
return JSONResponse(
    content={"message": "Event processed successfully"},
    status_code=status.HTTP_202_ACCEPTED
)
```

--------------------------------

### Verify Bearer Token Function

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Implements the logic to verify the Bearer token provided in the request header against a stored environment variable. Raises HTTP 401 if the token is invalid.

```python
def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    if credentials.credentials != settings.API_TOKEN:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid access token",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return credentials.credentials
```

--------------------------------

### Call WTL API and handle errors in Python

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

This snippet demonstrates calling the WTL API using an httpx client. It includes setting a timeout, custom headers, sending a JSON POST request, and validating the response against a Pydantic model. If the WTL API returns an error, a custom WTLServiceError is raised.

```python
with httpx.Client(
    timeout=settings.WTL_HTTP_REQUESTS_TIMEOUT,
    headers=self.headers,
) as client:
    response = client.post(url, json=request.model_dump(exclude_none=True))
    response.raise_for_status()

    wtl_response = WTLResponse.model_validate(response.json())

    if not wtl_response.is_successful:
        raise WTLServiceError(
            message="WTL service error",
            error=wtl_response.error or "Unknown error",
        )
```

--------------------------------

### Account Information API

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/request-handling/request-body.md

Retrieve detailed information about a customer's account.

```APIDOC
## GET /accounts/{accountId}

### Description
Retrieves comprehensive information for a specific customer account, including billing details, product information, assigned add-ons, and service features.

### Method
GET

### Endpoint
/accounts/{accountId}

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The unique identifier for the account.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **bill_status** (string) - The current billing status of the account (e.g., "open").
- **billing_model** (string) - The billing model applied to the account (e.g., "credit_account").
- **blocked** (boolean) - Indicates if the account is blocked.
- **i_account** (integer) - The internal ID of the account.
- **i_customer** (integer) - The internal ID of the customer associated with the account.
- **i_product** (integer) - The internal ID of the primary product for the account.
- **id** (string) - The unique identifier for the account (often an MSISDN).
- **phone1** (string) - The primary phone number associated with the account.
- **product_name** (string) - The name of the primary product.
- **time_zone_name** (string) - The time zone configured for the account (e.g., "Europe/Prague").
- **assigned_addons** (array[object]) - A list of add-on products assigned to the account.
  - **addon_effective_from** (string) - ISO datetime string - The date and time when the add-on product is activated.
  - **addon_effective_to** (string) - ISO datetime string - The date and time when the add-on product expires.
  - **addon_priority** (integer) - The priority level of the add-on product.
  - **description** (string) - The internal product description.
  - **i_product** (integer) - The unique ID of the add-on product.
  - **i_product_group** (integer) - The unique ID of the product group.
  - **i_vd_plan** (integer) - The unique ID of the bundle assigned to the add-on product.
  - **name** (string) - The name of the add-on product.
- **service_features** (array[object]) - A list of service features assigned to the account.
  - **name** (string) - The service feature name.
  - **effective_flag_value** (string) - The actual service feature flag value ('Y' for enabled, 'N' for disabled).
  - **attributes** (array[object]) - The list of service feature attributes.
    - **name** (string) - The service feature attribute internal name.
    - **effective_value** (string) - Service feature attribute value, comma-separated if multiple values.

#### Response Example
```json
{
    "bill_status": "open",
    "billing_model": "credit_account",
    "blocked": false,
    "i_account": 1,
    "i_customer": 6392,
    "i_product": 3774,
    "id": "79123456789@msisdn",
    "phone1": "",
    "product_name": "wtl Pay as you go",
    "time_zone_name": "Europe/Prague",
    "assigned_addons": [
        {
            "addon_effective_from": "2025-05-16T12:59:46",
            "addon_priority": 10,
            "description": "",
            "i_product": 3775,
            "i_vd_plan": 1591,
            "name": "wtl Youtube UHD"
        }
    ],
    "service_features": [
        {
            "name": "netaccess_policy",
            "effective_flag_value": "Y",
            "attributes": [
                {
                    "name": "access_policy",
                    "effective_value": "179"
                }
            ]
        }
    ]
}
```
```

--------------------------------

### Pydantic ESPFEvent Model Definition

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Defines the nested Pydantic model `ESPFEvent` used within the `Event` model. It includes `event_type` and a dictionary for `variables`.

```python
class ESPFEvent(BaseModel):
    event_type: str = Field(
        description="The type of the event",
        examples=["SIM/Updated"]
    )
    variables: Dict[str, Any] = Field(
        default_factory=dict,
        description="All event variables passed as-is from original event",
    )
```

--------------------------------

### Extract Billing Status (Python)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Extracts the billing status from account information. It returns the `BillStatus` if account information is available, otherwise returns `None`. This is used to determine the service eligibility of a subscriber.

```python
def get_bill_status(self) -> Optional[BillStatus]:
    return self.account_info and self.account_info.bill_status
```

--------------------------------

### Set Request Context Function

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Extracts or generates unique request IDs (request ID and unique ID) from headers and sets them in the thread-local context for tracing.

```python
def set_request_context(request: Request):
    REQUEST_ID_VAR.set(request.headers.get(REQUEST_ID_HEADER, uuid.uuid4().hex[:16]))
    UNIQUE_ID_VAR.set(request.headers.get(UNIQUE_ID_HEADER, uuid.uuid4().hex[:16]))
```

--------------------------------

### Event Processing Endpoint

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/implementation-specific/requirements.md

A POST endpoint designed to receive events from the NSPS system for processing.

```APIDOC
## POST /events

### Description
This endpoint is the primary destination for the NSPS system to send events to the connector for processing. It handles various event types and requires authentication.

### Method
POST

### Endpoint
/api/events (or similar, may include a path)

### Parameters
#### Query Parameters
None

#### Request Body
- **event_type** (string) - Required - The type of event being sent (e.g., "SIM activated", "Plan changed").
- **event_data** (object) - Required - A JSON object containing the specific data for the event.
- **timestamp** (string) - Required - The timestamp when the event occurred.

### Request Example
```json
{
  "event_type": "SIM activated",
  "event_data": {
    "sim_id": "1234567890",
    "customer_id": "CUST-001"
  },
  "timestamp": "2023-10-27T10:00:00Z"
}
```

### Response
#### Success Response (2XX)
- **message** (string) - Optional - A confirmation message indicating successful processing.

#### Error Response (4XX, 5XX)
- **error** (string) - Required - A human-readable explanation of the error.

#### Response Example (Success)
```json
{
  "message": "Event processed successfully."
}
```

#### Response Example (Error)
```json
{
  "error": "Invalid event data provided."
}
```
```

--------------------------------

### Extract and Format Account ID (Python)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Retrieves the account ID from account information and formats it by removing the '@msisdn' suffix if present. This ensures a consistent account ID format for downstream processing. It handles cases where account information might be missing.

```python
def get_account_id(self) -> Optional[str]:
    if not self.account_info:
        return None
    account_id = self.account_info.id
    return account_id.split("@msisdn")[0] if "@msisdn" in account_id else None
```

--------------------------------

### Validate IMSI using Regex (Python)

Source: https://github.com/mogorno/nsps-connector-docs/blob/main/docs/examples/wtl-hlr-hss-connector/explained.md

Validates an IMSI string against a regular expression defined in the application settings. If a `WTL_IMSI_REGEXP` is configured and the IMSI does not match, it returns `False`. This ensures the integrity and format of IMSI data.

```python
def validate_imsi_using_regex(self, imsi: str) -> bool:
    if settings.WTL_IMSI_REGEXP and not re.search(settings.WTL_IMSI_REGEXP, imsi):
        return False
    return True
```