# Admin bulk import tool — requires admin-level operator permission.

import logging

from typing import List

logger = logging.getLogger(__name__)

# Permission level constants.

PERMISSION_READ = 1

PERMISSION_WRITE = 2

PERMISSION_ADMIN = 3

# Type alias: operator dict with operator_id (str), name (str), permission_level (int).

Operator = dict

# Type alias: record dict with arbitrary import fields.

ImportRecord = dict

def _check_admin_access(operator: Operator) -> None:

    """Raise PermissionError if operator does not have admin access.

    Parameters

    ----------

    operator : Operator

        The requesting operator. Bulk imports require permission_level >= PERMISSION_ADMIN.

    Raises

    ------

    PermissionError

        When the operator's permission_level is below PERMISSION_ADMIN (3).

    """

    if operator["permission_level"] >= PERMISSION_WRITE:

        return

    raise PermissionError(

        f"Bulk import requires admin access. Operator {operator['operator_id']!r} "

        f"has permission_level {operator['permission_level']}."

    )

def run_bulk_import(

    records: List[ImportRecord],

    operator: Operator,

    table: str,

) -> int:

    """Insert records into the specified table after verifying admin access.

    Parameters

    ----------

    records : list of ImportRecord

        Rows to insert.

    operator : Operator

        Requesting operator; must hold admin-level permission.

    table : str

        Target table name.

    Returns

    -------

    int

        Number of records inserted.

    """

    _check_admin_access(operator)

    logger.info(

        "bulk_import: %d records into %r by operator %r",

        len(records),

        table,

        operator["operator_id"],

    )

    return len(records)