fiscguy 0.1.2__py3-none-any.whl

fiscguy/__init__.py

@@ -0,0 +1,35 @@
+"""
+ZIMRA Fiscal Device Library
+
+Public API for fiscal device operations. Import functions directly:
+
+    from fiscguy import open_day, close_day, submit_receipt, get_status, get_taxes, get_configuration
+
+Each function handles initialization and error handling transparently.
+"""
+
+default_app_config = "fiscguy.apps.FiscguyConfig"
+
+def __getattr__(name):
+    """Lazy-load API functions on first access."""
+    if name in (
+        "open_day", 
+        "close_day", 
+        "get_status", 
+        "submit_receipt", 
+        "get_configuration", 
+        "get_taxes"
+    ):
+        from fiscguy import api
+        return getattr(api, name)
+    raise AttributeError(f"module 'fiscguy' has no attribute '{name}'")
+
+
+__all__ = [
+    "open_day",
+    "close_day",
+    "get_status",
+    "submit_receipt",
+    "get_configuration",
+    "get_taxes",
+]

fiscguy/admin.py

@@ -0,0 +1,19 @@
+from django.contrib import admin
+
+from fiscguy.models import (
+    Certs,
+    Configuration,
+    Device,
+    FiscalCounter,
+    FiscalDay,
+    Receipt,
+    Taxes,
+)
+
+admin.site.register(Certs)
+admin.site.register(Configuration)
+admin.site.register(Taxes)
+admin.site.register(Device)
+admin.site.register(FiscalDay)
+admin.site.register(Receipt)
+admin.site.register(FiscalCounter)

fiscguy/api.py

@@ -0,0 +1,235 @@
+"""
+ZIMRA Fiscal Device Public API.
+
+Provides high-level functions for fiscal operations:
+- open_day: Open a new fiscal day
+- close_day: Close the open fiscal day
+- get_status: Get device and fiscal status
+- submit_receipt: Create and submit a receipt to ZIMRA
+- get_configuration: Fetch device configuration
+- get_taxes: Fetch available tax types
+
+This module encapsulates business logic previously in views,
+providing a clean library interface for both API and programmatic use.
+"""
+
+from typing import Dict, Any
+from loguru import logger
+
+from fiscguy.models import Device, FiscalDay, Taxes
+from fiscguy.services.closing_day_service import ClosingDayService
+from fiscguy.services.receipt_service import ReceiptService
+from fiscguy.zimra_base import ZIMRAClient
+from fiscguy.zimra_receipt_handler import ZIMRAReceiptHandler
+
+
+# Module-level instances
+_device = None
+_client = None
+_receipt_handler = None
+
+
+def _get_device() -> Device:
+    """Get or cache the first device. Raises if none exists."""
+    global _device
+    if _device is None:
+        _device = Device.objects.first()
+        if not _device:
+            raise RuntimeError("No Device found. Please run init_device management command.")
+    return _device
+
+
+def _get_client() -> ZIMRAClient:
+    """Get or cache the ZIMRA client. Lazy initialization."""
+    global _client
+    if _client is None:
+        device = _get_device()
+        logger.info(f"Initializing ZIMRA client for device {device}")
+        _client = ZIMRAClient(device)
+    return _client
+
+
+def _get_receipt_handler() -> ZIMRAReceiptHandler:
+    """Get or cache the receipt handler. Lazy initialization."""
+    global _receipt_handler
+    if _receipt_handler is None:
+        _receipt_handler = ZIMRAReceiptHandler()
+    return _receipt_handler
+
+
+def get_status() -> Dict[str, Any]:
+    """
+    Get the current device and fiscal day status.
+
+    Returns:
+        dict: Status response from ZIMRA FDMS.
+
+    Raises:
+        RuntimeError: If device not found or FDMS request fails.
+    """
+    logger.info("Fetching device status")
+    client = _get_client()
+    return client.get_status()
+
+
+def open_day() -> Dict[str, Any]:
+    """
+    Open a new fiscal day.
+
+    Creates a FiscalDay record and calls ZIMRA to open the day.
+    Returns early if a day is already open.
+
+    Returns:
+        dict: Response from ZIMRA FDMS or local message if already open.
+
+    Raises:
+        RuntimeError: If device not found or FDMS request fails.
+    """
+    logger.info("Opening fiscal day")
+    client = _get_client()
+    return client.open_day()
+
+
+def close_day() -> Dict[str, Any]:
+    """
+    Close the open fiscal day.
+
+    Collects fiscal counters, builds closing string, signs it, and submits
+    to ZIMRA. Updates the fiscal day status and returns the status payload.
+
+    Returns:
+        dict: Final device/fiscal status from ZIMRA FDMS.
+
+    Raises:
+        RuntimeError: If no open fiscal day or device not found.
+        Exception: If FDMS request fails.
+    """
+    logger.info("Closing fiscal day")
+    device = _get_device()
+    receipt_handler = _get_receipt_handler()
+    client = _get_client()
+
+    # Get open fiscal day
+    fiscal_day = FiscalDay.objects.filter(is_open=True).first()
+    if not fiscal_day:
+        return {"error": "No open fiscal day to close"}
+
+    # Collect counters and build closing payload
+    fiscal_counters = fiscal_day.counters.all()
+    tax_map = {t.tax_id: t.name for t in Taxes.objects.all()}
+
+    logger.info(f"Fiscal counters for day {fiscal_day.day_no}: {list(fiscal_counters)}")
+
+    service = ClosingDayService(
+        device=device,
+        fiscal_day=fiscal_day,
+        fiscal_counters=fiscal_counters,
+        tax_map=tax_map,
+        receipt_handler=receipt_handler,
+    )
+
+    closing_string, payload = service.close_day()
+
+    logger.info(f"Closing fiscal day string: {closing_string}")
+    logger.info(f"Closing payload: {payload}")
+
+    # Submit to ZIMRA and fetch final status
+    client.close_day(payload)
+    status_payload = client.get_status()
+
+    return status_payload
+
+
+def submit_receipt(receipt_data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Create and submit a receipt to ZIMRA.
+
+    Parses the receipt payload, creates Receipt and ReceiptLine records,
+    generates receipt data (signature/hash), and submits to ZIMRA.
+
+    Args:
+        receipt_data (dict): Receipt payload with structure:
+            {
+                "receipt_type": str,
+                "currency": str,
+                "total_amount": float,
+                "lines": [
+                    {
+                        "product": str,
+                        "quantity": float,
+                        "unit_price": float,
+                        "line_total": float,
+                        "tax_amount": float, # optional, can be calculated from tax percent if tax_name provided
+                        "tax_name": str,  
+                    },
+                    ...
+                ],
+                ...
+            }
+
+    Returns:
+        dict: Serialized receipt with all fields including ID and lines.
+
+    Raises:
+        ValidationError: If receipt_data is invalid (missing required fields, invalid tax).
+        Exception: If FDMS submission fails.
+    """
+    logger.info(f"Submitting receipt: {receipt_data}")
+    receipt_handler = _get_receipt_handler()
+
+    service = ReceiptService(receipt_handler=receipt_handler)
+    receipt, submission_res = service.create_and_submit_receipt(receipt_data)
+
+    logger.info(f"Receipt submitted to ZIMRA: {submission_res}")
+    return receipt
+
+
+def get_configuration() -> Dict[str, Any]:
+    """
+    Get the stored device configuration.
+
+    Returns:
+        dict: Configuration fields (tax_payer_name, tin_number, vat_number, etc.)
+              or empty dict if no configuration exists.
+    """
+    from fiscguy.models import Configuration
+    from fiscguy.serializers import ConfigurationSerializer
+
+    logger.info("Fetching device configuration")
+    config = Configuration.objects.first()
+    if not config:
+        logger.warning("No configuration found")
+        return {}
+    return ConfigurationSerializer(config).data
+
+
+def get_taxes() -> list:
+    """
+    Get all available tax types.
+
+    Returns:
+        list: Array of tax objects with fields:
+            {
+                "id": int,
+                "code": str,
+                "name": str,
+                "tax_id": int,
+                "percent": float
+            }
+    """
+    from fiscguy.serializers import TaxSerializer
+
+    logger.info("Fetching taxes")
+    taxes = Taxes.objects.all()
+    return TaxSerializer(taxes, many=True).data
+
+
+# module-level shortcuts
+__all__ = [
+    "open_day",
+    "close_day",
+    "get_status",
+    "submit_receipt",
+    "get_configuration",
+    "get_taxes",
+]

fiscguy/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class FiscguyConfig(AppConfig):
+    name = "fiscguy"

fiscguy/management/commands/init_device.py

@@ -0,0 +1,354 @@
+import json
+import shutil
+import tempfile
+import threading
+from pathlib import Path
+
+import requests
+from django.core.management.base import BaseCommand
+from django.db import transaction
+from loguru import logger
+
+from fiscguy.models import Certs, Configuration, Device, Taxes
+from fiscguy.zimra_crypto import ZIMRACrypto
+from fiscguy.services.configuration_service import create_or_update_config
+
+"""
+Management command to register a ZIMRA fiscal device and fetch its
+configuration from the ZIMRA FDMS API.
+
+Primary responsibilities:
+- Interactively collect device registration details from the user.
+- Generate CSR and register the device to obtain a signed certificate.
+- Fetch device configuration using the signed certificate and persist
+    the taxpayer configuration and applicable taxes into local models.
+
+This command intentionally writes/updates a single `Configuration` row
+and replaces the `Taxes` table contents with the `applicableTaxes`
+returned from ZIMRA. Database writes are wrapped in a transaction to
+avoid partial updates.
+
+Note: network calls to ZIMRA use client certificates stored in the
+`Certs` model. Temporary files are created for the requests library
+and removed afterwards.
+"""
+
+
+crypto = ZIMRACrypto()
+
+
+class Command(BaseCommand):
+    """Django management command for device registration.
+
+    Usage (interactive): run `python manage.py init_device` and follow
+    the prompts. The command will:
+    - create/update a `Device` record
+    - generate a CSR and register the device to obtain a signed cert
+    - fetch and persist configuration and taxes from ZIMRA's FDMS
+
+    The class keeps operations small and logs failures rather than
+    raising unhandled exceptions so it can be used in ad-hoc admin
+    workflows.
+    """
+
+    help = "Interactive registration of a new ZIMRA device"
+
+    def handle(self, *args, **options):
+        print("\n" + "*" * 75)
+        print("*" + " " * 73 + "*")
+        print("*  ****  **  ****   ****   ****    **  **  **   **  ")
+        print("*  **    **  **     **     **      **  **  **   **  ")
+        print("*  ****  **  ****   **     ** **   **  **   *****   ")
+        print("*  **    **    **   **     **  **  **  **     **    ")
+        print("*  **    **  ****   ****   ****     ****      **    ")
+        print("*" + " " * 73 + "*")
+        print("*" * 75)
+        print("\nDeveloped by Casper Moyo")
+        print("Version 1.0.0\n")
+        print(
+            "Welcome to device registration please input the following provided information as proveded by ZIMRA\n"
+        )
+
+        environment = input(
+            "Enter yes for production environment and no for test enviroment: "
+        ).strip()
+        org = input("Enter your organisation name: ").strip()
+        device_id = input("Enter your device ID: ").strip()
+        activation_key = input("Enter activation Key: ").strip()
+        model_version = input("Enter device model version eg v1: ").strip()
+        model_name = input("Enter device model name eg Server: ").strip()
+        device_sn = input("Enter device serial number: ").strip()
+
+        if not environment.lower() in ["yes", "no"]:
+            self.stdout.write(
+                self.style.ERROR("Please input environment between yes or no")
+            )
+            return
+
+        if (
+            not device_id
+            or not model_version
+            or not model_name
+            or not environment
+            or not device_sn
+            or not org
+            or not activation_key
+        ):
+            self.stdout.write(self.style.ERROR("All fields are required."))
+            return
+
+        device = Device.objects.first()
+        env = True if environment.lower() == "yes" else False
+
+        if not device:
+            device = Device.objects.create(
+                org_name=org,
+                activation_key=activation_key,
+                device_id=device_id,
+                device_model_name=model_name,
+                device_serial_number=device_sn,
+                device_model_version=model_version,
+                production=env,
+            )
+            print(
+                f"Device {device.device_id} created for {'production' if env else 'test'} environment."
+            )
+
+        else:
+            if device.production != env:
+                print("\n" + "!" * 75)
+                print("!" + " " * 73 + "!")
+                print("!  WARNING: ENVIRONMENT SWITCH DETECTED" + " " * 33 + "!")
+                print("!" + " " * 73 + "!")
+                print("!" + " " * 73 + "!")
+                print("!  Switching from", "PRODUCTION" if device.production else "TEST", "to", "PRODUCTION" if env else "TEST" + " " * (73 - 54) + "!")
+                print("!" + " " * 73 + "!")
+                print("!  ALL TEST DATA WILL BE PERMANENTLY DELETED:" + " " * 28 + "!")
+                print("!    - Fiscal Days" + " " * 57 + "!")
+                print("!    - Fiscal Counters" + " " * 52 + "!")
+                print("!    - Receipts & Receipt Lines" + " " * 40 + "!")
+                print("!    - Device Configuration" + " " * 47 + "!")
+                print("!    - Certificates" + " " * 55 + "!")
+                print("!    - Device Record" + " " * 54 + "!")
+                print("!" + " " * 73 + "!")
+                print("!" * 75)
+                
+                confirm = input(
+                    "\nType 'YES' to confirm data deletion and switch environment, or press Enter to cancel: "
+                ).strip()
+                
+                if confirm.upper() != "YES":
+                    print("Environment switch cancelled. No data was deleted.")
+                    return
+                
+                print("\nDeleting all test data...")
+                self.delete_all_test_data()
+                print("✓ All test data has been deleted.\n")
+                
+                device.org_name = org
+                device.activation_key = activation_key
+                device.device_id = device_id
+                device.device_model_name = model_name
+                device.device_serial_number = device_sn
+                device.device_model_version = model_version
+                device.production = env
+                device.save()
+                print(
+                    f"Device {device.device_id} updated to {'production' if env else 'test'} environment."
+                )
+            else:
+                device.org_name = org
+                device.activation_key = activation_key
+                device.device_id = device_id
+                device.save()
+                print(f"Device {device.device_id} updated for current environment.")
+
+        cert_key, csr = crypto.generate_key_and_csr(device_sn, device_id, env)
+
+        # register the device and get signed certificate from ZIMRA
+        self.register_device(
+            device_id, activation_key, model_name, model_version, env, csr, device_sn
+        )
+
+        # get zimra configurations for the provided device
+        zimra_config = self.get_config(
+            device_id, model_name, model_version, device.production
+        )
+        print(zimra_config)
+
+    def delete_all_test_data(self) -> None:
+        """
+        Delete all test data when switching environments.
+        
+        Deletes in order of dependencies:
+        - Fiscal Days
+        - Fiscal Counters
+        - Receipts & Receipt Lines
+        - Configuration
+        - Certificates
+        - Device
+        - Taxes
+        
+        """
+        try:
+            from fiscguy.models import (
+                FiscalDay,
+                FiscalCounter,
+                Receipt,
+                ReceiptLine,
+                Configuration,
+            )
+            
+            with transaction.atomic():
+                # Delete in order of dependencies (child tables first)
+                logger.info("Deleting receipt lines...")
+                count = ReceiptLine.objects.all().delete()[0]
+                self.stdout.write(self.style.SUCCESS(f"  Deleted {count} receipt lines"))
+                
+                logger.info("Deleting receipts...")
+                count = Receipt.objects.all().delete()[0]
+                self.stdout.write(self.style.SUCCESS(f"  Deleted {count} receipts"))
+                
+                logger.info("Deleting fiscal counters...")
+                count = FiscalCounter.objects.all().delete()[0]
+                self.stdout.write(self.style.SUCCESS(f"  Deleted {count} fiscal counters"))
+                
+                logger.info("Deleting fiscal days...")
+                count = FiscalDay.objects.all().delete()[0]
+                self.stdout.write(self.style.SUCCESS(f"  Deleted {count} fiscal days"))
+                
+                logger.info("Deleting configuration...")
+                count = Configuration.objects.all().delete()[0]
+                self.stdout.write(self.style.SUCCESS(f"  Deleted {count} configuration records"))
+                
+                logger.info("Deleting certificates...")
+                count = Certs.objects.all().delete()[0]
+                self.stdout.write(self.style.SUCCESS(f"  Deleted {count} certificates"))
+                
+                logger.info("Deleting taxes...")
+                count = Taxes.objects.all().delete()[0]
+                self.stdout.write(self.style.SUCCESS(f"  Deleted {count} tax records"))
+                
+                logger.info("Deleting device...")
+                count = Device.objects.all().delete()[0]
+                self.stdout.write(self.style.SUCCESS(f"  Deleted {count} devices"))
+                
+                logger.info("All test data successfully deleted")
+        except Exception as e:
+            logger.exception(f"Error deleting test data: {e}")
+            self.stdout.write(self.style.ERROR(f"ERROR: Failed to delete test data: {e}"))
+            raise
+
+    def get_config(
+        self, device_id: str, model_name: str, model_version: str, env: bool
+    ) -> dict:
+        """Fetch device configuration from ZIMRA and persist locally.
+
+        Args:
+            device_id (str): Device identifier supplied by ZIMRA.
+            model_name (str): Device model name header required by FDMS.
+            model_version (str): Device model version header.
+            env (bool): True for production FDMS endpoint, False for test.
+
+        Returns:
+            dict | None: Parsed JSON response from FDMS on success, or
+            None when the HTTP request fails.
+
+        Side effects:
+            - Creates/updates a single `Configuration` row.
+            - Replaces all rows in `Taxes` with the `applicableTaxes`
+              returned by the FDMS response.
+        """
+
+        logger.info(f"Fetching device: {device_id} configurations")
+
+        url = (
+            f"https://fdmsapi.zimra.co.zw/Device/v1/{device_id}"
+            if env
+            else f"https://fdmsapitest.zimra.co.zw/Device/v1/{device_id}"
+        )
+
+        headers = {
+            "Content-Type": "application/json",
+            "deviceModelName": model_name,
+            "deviceModelVersion": model_version,
+        }
+
+        temp_dir = Path(tempfile.mkdtemp(prefix="zimra_fdms_"))
+        cert_path = temp_dir / "client_cert.pem"
+        key_path = temp_dir / "client_key.pem"
+
+        from fiscguy.models import Certs
+
+        cert = Certs.objects.first()
+        cert_path.write_text(cert.certificate)
+        key_path.write_text(cert.certificate_key)
+
+        try:
+            response = requests.get(
+                f"{url}/getConfig",
+                headers=headers,
+                cert=(str(cert_path), str(key_path)),
+                timeout=30,
+            )
+            response.raise_for_status()
+            res = response.json()
+
+            create_or_update_config(res)
+            logger.info(f"Configuration for device {device_id} updated successfully.")
+            return res
+        except requests.RequestException as e:
+            logger.error(f"Error fetching config: {e}")
+            return None
+        finally:
+            cert_path.unlink(missing_ok=True)
+            key_path.unlink(missing_ok=True)
+            temp_dir.rmdir()
+
+    def register_device(
+        self, device_id, activation_key, model_name, model_version, env, csr, device_sn
+    ):
+        logger.info(f"Registering device: {device_id}")
+        url = (
+            f"https://fdmsapi.zimra.co.zw/Public/v1/{device_id}"
+            if env
+            else f"https://fdmsapitest.zimra.co.zw/Public/v1/{device_id}"
+        )
+        print(csr)
+        csr = csr.replace("\n", "")
+        print(csr)
+
+        payload = {
+            "activationKey": activation_key,
+            "deviceSerial": device_sn,
+            "certificateRequest": csr,
+        }
+
+        headers = {
+            "Content-Type": "application/json",
+            "deviceModelName": model_name,
+            "deviceModelVersion": model_version,
+        }
+
+        try:
+            response = requests.post(
+                f"{url}/RegisterDevice", json=payload, headers=headers
+            )
+            response.raise_for_status()
+
+            logger.info(response.json())
+
+            signed_certificate = response.json().get("certificate")
+
+            if signed_certificate:
+                from fiscguy.models import Certs
+
+                cert = Certs.objects.first()
+                cert.certificate = signed_certificate
+                cert.save()
+
+                logger.info(f"Device {device_id} registered successfully.")
+                return signed_certificate
+        except Exception as e:
+            logger.error(f"Device registration failed: {e}")
+            return