### ProductInfo Data Model Example

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

Contains details about a product offered, including its name, description, unique ID, and add-on priority. This model helps in managing product information within the system.

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

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

### Example Enriched Event Output by NSPS

Source: https://mogorno.github.io/NSPS-connector-docs/NSPS/data-flows

This JSON object illustrates an example of an enriched event generated by NSPS and sent to connector microservices. It includes the original event details, account information, SIM card details, access policy, product information, and counter details, providing comprehensive data for external system integration.

```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"
}
```

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

### AssignedAddon JSON Example

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

This JSON object details an add-on product assigned to an account. It includes activation dates, priority, product identification, and name. This structure is part of the broader AccountInfo object.

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

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

### Example PortaBilling ESPF Webhook Event

Source: https://mogorno.github.io/NSPS-connector-docs/NSPS/data-flows

This JSON object represents an example of a webhook event received by NSPS from PortaBilling ESPF. It contains basic information about the event type and associated variables, such as event and account identifiers. The structure of the 'variables' field 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"
    }
}
```

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

### AccessPolicyInfo Data Model Example

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

Defines the structure for access policy information applied to an account. It includes the policy ID, name, and a list of associated attributes with their group name and values.

```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"
        }
    ]
}
```

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

### VDCounterInfo JSON Example

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

This JSON object demonstrates the structure and typical values for a VDCounterInfo object. It includes fields such as service name, bundle name, plan ID, destination group ID, priority, service ID, remaining volume, discount information, unit, and allocated amount.

```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
}
```

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

### AccountInfo JSON Example

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

This JSON object represents the account information for a customer, including billing status, account details, assigned products, and service features. It's used to retrieve comprehensive data 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"
                }
            ]
        }
    ]
}
```

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

### SimInfo Data Model Example

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

Represents information about a SIM card, including its ID, IMSI, MSISDN, and status. This structure is used to store and retrieve SIM card details from PortaBilling.

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

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

### Example ESPF Event JSON

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

This JSON object represents a sample ESPF event, which is the core event payload sent to the NSPS system. It includes essential event details like type and variables.

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

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

### Get CS Profile with Default (Python)

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Retrieves the CS (Circuit Switched) profile, applying a default value if not explicitly provided. This ensures that a CS profile is always available for WTL requests. It relies on application settings for the default profile.

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

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

### Health Check Endpoint

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/requirements

Provides a GET endpoint to check the availability of the connector. It should return a 200 OK status.

```APIDOC
## GET /health

### Description
This endpoint is used to check the availability and health status of the connector.

### Method
GET

### Endpoint
/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

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

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

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

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

### ServiceFeature JSON Example

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

This JSON object describes a service feature assigned to an account, including its name, effective status, and associated attributes. It's utilized within the AccountInfo structure to represent specific service configurations.

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

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

### Health Check NSPS Connector Service

Source: https://mogorno.github.io/NSPS-connector-docs/testing

Sends a GET request to the service endpoint to verify its operational status. It expects a JSON response indicating 'Healthy' if the service is running correctly. This is a basic check to ensure the service is accessible.

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

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

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

### Define FastAPI Application

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Initializes the FastAPI application with a title, description, and version. This sets up the basic structure for the microservice.

```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",
)
```

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

### Implement Bearer Token Authentication

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Sets up Bearer authentication using HTTPBearer. The `verify_token` function checks the provided token against an environment variable and raises a 401 error if invalid, ensuring secure access.

```python
security = HTTPBearer()

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
```

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

### Authentication and Logging

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Details on how the API enforces Bearer token authentication and implements JSON logging with request context.

```APIDOC
## Authentication

### Method
Bearer Authentication

### Description
Authentication is enforced via a dependency (`verify_token`) that checks for a valid Bearer token in the `Authorization` header. The token is compared against an environment variable (`settings.API_TOKEN`).

### Failure Behavior
If the token is missing or invalid, a `401 Unauthorized` HTTP error is returned with a `WWW-Authenticate: Bearer` header.

## Request Context and JSON Logging

### Middleware
Middleware is used to set request context, including unique request IDs extracted from headers or generated if absent. All HTTP requests are logged in a structured JSON format upon completion, including status codes and timestamps.

### Log Format
JSON via structlog with automatic timestamp and traced IDs.

```

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

### POST /process-event

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/workflow

Accepts an HTTP request to process an event. It validates the payload, determines the provisioning action, extracts necessary data, and calls the WTL API.

```APIDOC
## POST /process-event

### Description
Accepts an HTTP request with a Bearer token to process an event. It performs validation, data extraction, and interacts with the WTL API.

### Method
POST

### Endpoint
/process-event

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event_type** (string) - Required - The type of the event.
- **data** (object) - Required - The main data payload.
- **pb_data** (object) - Optional - Additional payload data.
    - **account_info** (object) - Optional - Account information.
        - **id** (string) - Optional - The account ID.
    - **bill_status** (string) - Optional - The billing status.
    - **blocked** (boolean) - Optional - Whether the subscriber is blocked.
    - **cs_profile** (object) - Optional - CS profile details.
    - **eps_profile** (object) - Optional - EPS profile details.

### Request Example
```json
{
  "event_type": "user.created",
  "data": {},
  "pb_data": {
    "account_info": {
      "id": "12345"
    },
    "bill_status": "open",
    "blocked": false,
    "cs_profile": {},
    "eps_profile": {}
  }
}
```

### Response
#### Success Response (202 Accepted)
- **message** (string) - A confirmation message indicating the event has been accepted for processing.

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

#### Error Response
- **error** (object) - Details about the error.
    - **code** (string) - An error code.
    - **message** (string) - A human-readable error message.

#### Error Response Example
```json
{
  "error": {
    "code": "INVALID_PAYLOAD",
    "message": "The provided payload is invalid."
  }
}
```
```

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

### Define WTL Provisioning Actions (Python)

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Defines an enumeration for WTL provisioning actions. This helps in standardizing the actions that can be performed on the WTL system, ensuring consistency and clarity in the codebase. It serves as a set of predefined constants for different WTL operations.

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

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

### Construct Unified WTL Request (Python)

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Builds a `UnifiedSyncRequest` object, aggregating essential data for the WTL system. It includes IMSI, subscriber status, MSISDNs, profiles, and the action to be performed. Pydantic validation ensures the request structure is correct before sending.

```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,
)
```

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

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

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Establishes a mapping between incoming event types and the corresponding WTL provisioning actions. This dictionary allows the connector to translate generic event notifications into specific WTL operations. It supports extensibility for new event types and handles unknown types by logging and returning a 202 response.

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

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

### Create POST Endpoint for Event Processing

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Defines a POST endpoint '/process-event' that accepts validated 'Event' data. It uses Bearer token authentication and returns an HTTP 202 Accepted status upon successful processing.

```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)
```

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

### Call WTL API and Map Errors with httpx

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

This snippet demonstrates calling the WTL API using httpx, including configuring timeouts and headers. It also shows how to validate the WTL API response and raise a custom exception for service-level errors, ensuring clean separation of concerns for transport and business errors.

```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",
        )
```

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

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

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

A Pydantic model designed to map an event type to a WTL action. It utilizes the `EVENT_ACTION_MAP` to determine the appropriate action based on the provided event type. This model enforces data structure and provides a clear interface for action retrieval.

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

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

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

### Set Request Context and JSON Logging Middleware

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Implements middleware to set request context, including generating unique request IDs if not provided in headers. It also logs request completion in JSON format with status codes and timestamps.

```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]))

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
```

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

### POST /process-event

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Accepts an incoming event request, validates it, and initiates the processing workflow. This endpoint is protected by Bearer token authentication.

```APIDOC
## POST /process-event

### Description
This endpoint accepts an incoming event request, validates the payload against the `Event` schema, and delegates the processing to an event processor. It is protected by Bearer token authentication.

### Method
POST

### Endpoint
/process-event

### Parameters
#### 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) - Required - All event variables passed as-is from the 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": {
      "imsi": "123456789012345"
    }
  },
  "pb_data": {
    "customer_id": "C123"
  }
}
```

### Response
#### Success Response (202 Accepted)
- **message** (string) - Description indicating 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)
- Details about validation errors in the request body.

```

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

### AssignedAddon Details

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

Defines the structure and fields for an assigned add-on product within an account.

```APIDOC
## AssignedAddon Object

### Description
Represents an add-on product assigned to an account.

### Fields
- **addon_effective_from** (string) - ISO datetime string - The date and time when the add-on product is activated for an account.
- **addon_effective_to** (string) - ISO datetime string - The date and time when the add-on product assigned to an account 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 product.
- **i_product_group** (integer) - The unique ID of the product group to which the product belongs.
- **i_vd_plan** (integer) - The unique ID of the bundle assigned to the product.
- **name** (string) - The product name.

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

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

### Extract and Format Account ID (Python)

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Extracts the account ID from account information and formats it by removing any MSISDN suffix. This ensures a clean and consistent account identifier. 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
```

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

### AccountInfo

Source: https://mogorno.github.io/NSPS-connector-docs/implementation-specific/request-handling/request-body

Retrieves comprehensive information about a specific customer account.

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

### Description
Retrieves detailed information for a given account ID, including billing details, product information, assigned add-ons, and service features.

### Method
GET

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

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

### 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 currently blocked.
- **i_account** (integer) - The internal identifier for the account.
- **i_customer** (integer) - The identifier for the customer associated with the account.
- **i_product** (integer) - The identifier for the primary product associated with the account.
- **id** (string) - The primary ID of the account, often in MSISDN format.
- **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) - A list of add-on products assigned to the account.
  - See `AssignedAddon` for details.
- **service_features** (array) - A list of service features enabled for the account.
  - See `ServiceFeature` for details.

#### 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"
                }
            ]
        }
    ]
}
```
```

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

### Define ESPFEvent Pydantic Model

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Defines the 'ESPFEvent' Pydantic model used within the 'Event' model. It specifies '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",
    )
```

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

### NSPS Output: Enriched Events for Connector Microservices

Source: https://mogorno.github.io/NSPS-connector-docs/NSPS/data-flows

NSPS enriches incoming events with additional data before outputting them to connector microservices. This enriched data is formatted to facilitate integration with external systems.

```APIDOC
## NSPS Enriched Event Structure

### Description
This is the structure of the enriched event data that NSPS outputs to connector microservices. It contains comprehensive information derived from the input event and PortaBilling data.

### Method
N/A (This describes the data payload, not an API endpoint)

### Endpoint
N/A

### Parameters
(This section describes the fields within the enriched event payload)

#### Enriched Event Body
- **event_id** (string) - Unique identifier for the enriched event.
- **data** (object) - Original event data after minimal processing.
  - **event_type** (string) - Type of the event.
  - **variables** (object) - Variables associated with the event.
- **pb_data** (object) - Enriched data from PortaBilling.
  - **account_info** (object) - Information about the account.
    - **bill_status** (string) - Account billing status.
    - **billing_model** (string) - Account billing model.
    - **blocked** (boolean) - Indicates if the account is blocked.
    - **i_account** (integer) - Account identifier.
    - **i_customer** (integer) - Customer identifier.
    - **i_product** (integer) - Product identifier.
    - **id** (string) - Account ID (e.g., "79123456789@msisdn").
    - **phone1** (string) - Primary phone number.
    - **product_name** (string) - Name of the associated product.
    - **time_zone_name** (string) - Time zone of the account.
    - **assigned_addons** (array) - List of assigned add-ons.
      - **addon_effective_from** (string) - Add-on start date.
      - **addon_priority** (integer) - Add-on priority.
      - **description** (string) - Add-on description.
      - **i_product** (integer) - Add-on product identifier.
      - **i_vd_plan** (integer) - Add-on virtual data plan identifier.
      - **name** (string) - Add-on name.
    - **service_features** (array) - List of service features.
      - **name** (string) - Feature name.
      - **effective_flag_value** (string) - Feature effective flag value.
      - **attributes** (array) - Feature attributes.
        - **name** (string) - Attribute name.
        - **effective_value** (string) - Attribute effective value.
  - **sim_info** (object) - Information about the SIM card.
    - **i_sim_card** (integer) - SIM card identifier.
    - **imsi** (string) - IMSI number.
    - **msisdn** (string) - MSISDN number.
    - **status** (string) - SIM card status.
  - **access_policy_info** (object) - Information about the access policy.
    - **i_access_policy** (integer) - Access policy identifier.
    - **name** (string) - Access policy name.
    - **attributes** (array) - Access policy attributes.
      - **group_name** (string) - Attribute group name.
      - **name** (string) - Attribute name.
      - **value** (string) - Attribute value.
  - **product_info** (object) - Information about the product.
    - **name** (string) - Product name.
    - **description** (string) - Product description.
    - **addon_priority** (integer) - Product add-on priority.
    - **i_product** (integer) - Product identifier.
  - **full_vd_counter_info** (array) - Detailed virtual data counter information.
    - **service_name** (string) - Service name for the counter.
    - **vdp_name** (string) - Virtual data plan name.
    - **i_vd_plan** (integer) - Virtual data plan identifier.
    - **i_dest_group** (integer) - Destination group identifier.
    - **addon_priority** (integer) - Add-on priority for the counter.
    - **i_vd_dg** (integer) - Virtual data destination group identifier.
    - **remaining** (string) - Remaining amount.
    - **i_service** (integer) - Service identifier.
    - **dg_name** (string) - Destination group name.
    - **discount_info** (string) - Discount information.
    - **unit** (string) - Unit of measurement.
    - **allocated_amount** (integer) - Allocated amount.
- **handler_id** (string) - Identifier of the handler that processed the event.
- **created_at** (string) - Timestamp when the enriched event was created.
- **updated_at** (string) - Timestamp when the enriched event was last updated.
- **status** (string) - Current status of the enriched event.

### Request Example
(This is an output payload, not a request example)

### Response
(This describes the structure of the response from NSPS to its consumers, typically a webhook receiver)
#### Success Response (200 OK)
(Indicates successful delivery of the enriched event to the connector)

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

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

### Validate IMSI using Regex (Python)

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Validates an IMSI string against a regular expression defined in settings. If a regex is configured and the IMSI does not match, it returns False. This function helps ensure 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
```

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

### Return Success Response with JSONResponse

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

This code snippet illustrates how to return a successful JSON response with a 202 Accepted status code using FastAPI's JSONResponse. This signals to the client (NSPS) that the event has been successfully received and processed or queued, allowing the pipeline to proceed.

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

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

### Extract Block Status (Python)

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Extracts the boolean block status from the account information. This indicates whether an account is currently blocked. The method handles cases where account information might be absent, returning None.

```python
def get_block_status(self) -> Optional[bool]:
    return self.account_info and self.account_info.blocked
```

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

### Determine Subscriber Service Status (Python)

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Determines the subscriber's service status based on their block and billing status. If the subscriber is not blocked and has an open bill status, their service is granted. Otherwise, a default status (OPERATOR_DETERMINED_BARRING) is applied. This logic is critical for provisioning.

```python
subscriber_status = SubscriberStatus.OPERATOR_DETERMINED_BARRING.value
if (
    not processor.get_block_status()
    and processor.get_bill_status() == BillStatus.OPEN.value
):
    subscriber_status = SubscriberStatus.SERVICE_GRANTED.value
```

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

### Send Data Request to NSPS Connector Service

Source: https://mogorno.github.io/NSPS-connector-docs/testing

Sends a POST request with a JSON payload to the NSPS Connector service. This is used to test data processing, event handling, and integrations with external systems. It requires an authorization token and specifies the content type. The expected response is a JSON message confirming successful processing.

```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"
}
```

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

### NSPS Input: PortaBilling ESPF Webhook Events

Source: https://mogorno.github.io/NSPS-connector-docs/NSPS/data-flows

NSPS accepts webhook events from PortaBilling ESPF over secure HTTP. These events contain essential information about the event type and associated variables. Authentication is handled via HTTP Basic Auth.

```APIDOC
## POST /webhook

### Description
Receives webhook events from PortaBilling ESPF.

### Method
POST

### Endpoint
/webhook

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event_type** (string) - Required - Identifies the type of event (e.g., "Account/Unblocked", "SIM/Updated").
- **variables** (object) - Required - Contains identifiers and metadata for the event.
  - **i_env** (integer) - Unique environment identifier in PortaBilling.
  - **i_event** (integer) - Unique event identifier in PortaBilling.
  - **i_account** (integer) - Account identifier affected by the event.
  - **event_time** (string) - Optional - Timestamp when the event occurred (format: "YYYY-MM-DD HH:MM:SS" in UTC).
  *Note: The fields within the `variables` object may vary based on the `event_type`.*

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

### Response
#### Success Response (200 OK)
Indicates that the webhook event was successfully received and processed.

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

#### Error Responses
- **400 Bad Request**: Invalid event data.
- **401 Unauthorized**: Invalid authentication credentials.
- **500 Internal Server Error**: Server error during processing.
```

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

### Extract Billing Status (Python)

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Retrieves the billing status from the account information. This method safely accesses nested account data and returns the billing status, supporting `BillStatus` enum or None if unavailable. It's used to determine the account's payment state.

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

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

### Define Event Pydantic Model

Source: https://mogorno.github.io/NSPS-connector-docs/examples/wtl-hlr-hss-connector/explained

Defines the 'Event' Pydantic model for validating incoming request payloads. It includes fields for 'event_id', 'data' (nested ESPFEvent), and 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"
    )
```