qrid 1.0.0__tar.gz

qrid-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/

qrid-1.0.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: qrid
+Version: 1.0.0
+Summary: Decode and encode MergeID electronic invoice QR codes
+Project-URL: Homepage, https://github.com/Quality-XP-Development-SESSA/qrid-python
+Project-URL: Repository, https://github.com/Quality-XP-Development-SESSA/qrid-python
+Author-email: Valentin Secades Mendez <vsecades@qxdev.com>
+License: MIT
+Keywords: codec,decoder,invoice,mergeid,qr,qrcode
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: segno>=1.6; extra == 'dev'
+Provides-Extra: encode
+Requires-Dist: segno>=1.6; extra == 'encode'
+Description-Content-Type: text/markdown
+
+# qrid — Python
+
+Decode and encode **MergeID electronic invoice QR codes**.
+
+Python port of [`qrid/codec`](https://packagist.org/packages/qrid/codec) (PHP). All three implementations (PHP, Node.js, Python) share the same payload format and function signatures, so QR codes generated by any one of them scan correctly in the others.
+
+## Installation
+
+```bash
+# Decode only (no extra dependencies)
+pip install qrid
+
+# Decode + encode SVG
+pip install 'qrid[encode]'
+```
+
+## Usage
+
+### Decode
+
+```python
+from qrid import decode_qr_id
+
+# `encoded` is the raw string value scanned from a MergeID QR code
+payload = decode_qr_id(encoded)
+
+print(payload["v"])       # Payload schema version (int, currently 1)
+print(payload["code"])    # Installation / activity code  (e.g. "ACT-001")
+print(payload["id"])      # Tax or company ID              (e.g. "3101679980")
+print(payload["company"]) # Company legal name
+print(payload["email"])   # Billing e-mail address
+print(payload["address"]) # Physical address
+```
+
+`decode_qr_id` strips surrounding whitespace before decoding, so strings
+copied with accidental padding are handled transparently.
+
+**Exceptions raised:**
+
+| Exception | Cause |
+| --- | --- |
+| `ValueError` | Input is not valid base64 |
+| `json.JSONDecodeError` | Decoded bytes are not valid JSON |
+
+```python
+import json
+from qrid import decode_qr_id
+
+try:
+    payload = decode_qr_id(raw)
+except ValueError:
+    # QR data was not base64
+    ...
+except json.JSONDecodeError:
+    # QR data decoded but was not the expected JSON structure
+    ...
+```
+
+### Encode (requires `qrid[encode]`)
+
+```python
+from qrid import encode_qr_id
+
+svg = encode_qr_id(
+    code="ACT-001",
+    id="3101679980",
+    company="Acme Corp S.A.",
+    email="billing@acme.example",
+    address="123 Main St, San José, Costa Rica",
+)
+
+# Write to a file
+with open("invoice_qr.svg", "w") as f:
+    f.write(svg)
+
+# Or serve directly
+# Content-Type: image/svg+xml
+```
+
+**Exceptions raised:**
+
+| Exception | Cause |
+| --- | --- |
+| `ImportError` | `segno` is not installed (`pip install 'qrid[encode]'`) |
+
+## Payload format
+
+The QR code data is a UTF-8 JSON object encoded as standard base64 (no line-breaks):
+
+```json
+{
+  "v": 1,
+  "code": "ACT-001",
+  "id": "3101679980",
+  "company": "Acme Corp S.A.",
+  "email": "billing@acme.example",
+  "address": "123 Main St, San José, Costa Rica"
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `v` | `int` | Payload schema version. Currently always `1`. |
+| `code` | `str` | Installation or activity code that links the QR to an internal record. |
+| `id` | `str` | Tax / company registration ID. |
+| `company` | `str` | Legal company name (UTF-8, including accented characters). |
+| `email` | `str` | Primary billing or contact e-mail address. |
+| `address` | `str` | Physical address of the company. |
+
+## Requirements
+
+| Dependency | Version | Required for |
+| --- | --- | --- |
+| Python | `>= 3.9` | Always |
+| `segno` | `>= 1.6` | `encode_qr_id()` only |
+
+## Running tests
+
+```bash
+pip install 'qrid[dev]'
+pytest
+```
+
+## License
+
+MIT

qrid-1.0.0/README.md

@@ -0,0 +1,126 @@
+# qrid — Python
+
+Decode and encode **MergeID electronic invoice QR codes**.
+
+Python port of [`qrid/codec`](https://packagist.org/packages/qrid/codec) (PHP). All three implementations (PHP, Node.js, Python) share the same payload format and function signatures, so QR codes generated by any one of them scan correctly in the others.
+
+## Installation
+
+```bash
+# Decode only (no extra dependencies)
+pip install qrid
+
+# Decode + encode SVG
+pip install 'qrid[encode]'
+```
+
+## Usage
+
+### Decode
+
+```python
+from qrid import decode_qr_id
+
+# `encoded` is the raw string value scanned from a MergeID QR code
+payload = decode_qr_id(encoded)
+
+print(payload["v"])       # Payload schema version (int, currently 1)
+print(payload["code"])    # Installation / activity code  (e.g. "ACT-001")
+print(payload["id"])      # Tax or company ID              (e.g. "3101679980")
+print(payload["company"]) # Company legal name
+print(payload["email"])   # Billing e-mail address
+print(payload["address"]) # Physical address
+```
+
+`decode_qr_id` strips surrounding whitespace before decoding, so strings
+copied with accidental padding are handled transparently.
+
+**Exceptions raised:**
+
+| Exception | Cause |
+| --- | --- |
+| `ValueError` | Input is not valid base64 |
+| `json.JSONDecodeError` | Decoded bytes are not valid JSON |
+
+```python
+import json
+from qrid import decode_qr_id
+
+try:
+    payload = decode_qr_id(raw)
+except ValueError:
+    # QR data was not base64
+    ...
+except json.JSONDecodeError:
+    # QR data decoded but was not the expected JSON structure
+    ...
+```
+
+### Encode (requires `qrid[encode]`)
+
+```python
+from qrid import encode_qr_id
+
+svg = encode_qr_id(
+    code="ACT-001",
+    id="3101679980",
+    company="Acme Corp S.A.",
+    email="billing@acme.example",
+    address="123 Main St, San José, Costa Rica",
+)
+
+# Write to a file
+with open("invoice_qr.svg", "w") as f:
+    f.write(svg)
+
+# Or serve directly
+# Content-Type: image/svg+xml
+```
+
+**Exceptions raised:**
+
+| Exception | Cause |
+| --- | --- |
+| `ImportError` | `segno` is not installed (`pip install 'qrid[encode]'`) |
+
+## Payload format
+
+The QR code data is a UTF-8 JSON object encoded as standard base64 (no line-breaks):
+
+```json
+{
+  "v": 1,
+  "code": "ACT-001",
+  "id": "3101679980",
+  "company": "Acme Corp S.A.",
+  "email": "billing@acme.example",
+  "address": "123 Main St, San José, Costa Rica"
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `v` | `int` | Payload schema version. Currently always `1`. |
+| `code` | `str` | Installation or activity code that links the QR to an internal record. |
+| `id` | `str` | Tax / company registration ID. |
+| `company` | `str` | Legal company name (UTF-8, including accented characters). |
+| `email` | `str` | Primary billing or contact e-mail address. |
+| `address` | `str` | Physical address of the company. |
+
+## Requirements
+
+| Dependency | Version | Required for |
+| --- | --- | --- |
+| Python | `>= 3.9` | Always |
+| `segno` | `>= 1.6` | `encode_qr_id()` only |
+
+## Running tests
+
+```bash
+pip install 'qrid[dev]'
+pytest
+```
+
+## License
+
+MIT

qrid-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qrid"
+version = "1.0.0"
+description = "Decode and encode MergeID electronic invoice QR codes"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "Valentin Secades Mendez", email = "vsecades@qxdev.com" },
+]
+keywords = ["qrcode", "qr", "invoice", "mergeid", "codec", "decoder"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+encode = ["segno>=1.6"]
+dev    = ["pytest>=7.0", "segno>=1.6"]
+
+[project.urls]
+Homepage   = "https://github.com/Quality-XP-Development-SESSA/qrid-python"
+Repository = "https://github.com/Quality-XP-Development-SESSA/qrid-python"

qrid-1.0.0/qrid/__init__.py

@@ -0,0 +1,3 @@
+from .codec import decode_qr_id, encode_qr_id, QRIdPayload
+
+__all__ = ["decode_qr_id", "encode_qr_id", "QRIdPayload"]

qrid-1.0.0/qrid/codec.py

@@ -0,0 +1,90 @@
+import base64
+import binascii
+import io
+import json
+from typing import TypedDict
+
+
+class QRIdPayload(TypedDict):
+    v: int
+    code: str
+    id: str
+    company: str
+    email: str
+    address: str
+
+
+def decode_qr_id(encoded: str) -> QRIdPayload:
+    """Decode a base64-encoded QR ID string into its structured payload.
+
+    Mirrors QRId\\Codec::decodeQRId() in qrid/codec (PHP).
+
+    Args:
+        encoded: The base64 string read from a MergeID QR code.
+
+    Returns:
+        A TypedDict with keys: v, code, id, company, email, address.
+
+    Raises:
+        ValueError: When the base64 input is malformed.
+        json.JSONDecodeError: When the decoded content is not valid JSON.
+    """
+    trimmed = encoded.strip()
+    try:
+        json_bytes = base64.b64decode(trimmed, validate=True)
+    except binascii.Error:
+        raise ValueError(
+            "Invalid base64 input: could not decode the provided string."
+        )
+    return json.loads(json_bytes.decode("utf-8"))
+
+
+def encode_qr_id(
+    code: str,
+    id: str,
+    company: str,
+    email: str,
+    address: str,
+) -> str:
+    """Encode invoice identity fields and return an SVG QR code string.
+
+    Mirrors QRId\\Codec::encodeQRId() in qrid/codec (PHP).
+    Requires the encode extra: pip install 'qrid[encode]'
+
+    Args:
+        code:    Installation or activity code.
+        id:      Tax / company registration ID.
+        company: Company legal name (UTF-8).
+        email:   Primary billing or contact e-mail address.
+        address: Physical address of the company.
+
+    Returns:
+        An SVG markup string containing the generated QR code.
+
+    Raises:
+        ImportError: When the segno package is not installed.
+    """
+    try:
+        import segno
+    except ImportError:
+        raise ImportError(
+            "segno is required for encode_qr_id(). "
+            "Install with: pip install 'qrid[encode]'"
+        )
+
+    payload: QRIdPayload = {
+        "v": 1,
+        "code": code,
+        "id": id,
+        "company": company,
+        "email": email,
+        "address": address,
+    }
+    encoded = base64.b64encode(
+        json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    ).decode()
+
+    qr = segno.make_qr(encoded)
+    buf = io.BytesIO()
+    qr.save(buf, kind="svg", nl=False)
+    return buf.getvalue().decode("utf-8")

qrid-1.0.0/tests/test_codec.py

@@ -0,0 +1,92 @@
+import base64
+import json
+
+import pytest
+
+from qrid import QRIdPayload, decode_qr_id, encode_qr_id
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def encode(payload: dict) -> str:
+    return base64.b64encode(
+        json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    ).decode()
+
+
+def sample_payload(**overrides) -> QRIdPayload:
+    p: QRIdPayload = {
+        "v": 1,
+        "code": "ACT-001",
+        "id": "3101679980",
+        "company": "Acme Corp S.A.",
+        "email": "billing@acme.example",
+        "address": "123 Main St, San José, Costa Rica",
+    }
+    p.update(overrides)  # type: ignore[typeddict-item]
+    return p
+
+
+# ── decode_qr_id ──────────────────────────────────────────────────────────────
+
+class TestDecodeQRId:
+    def test_returns_all_fields(self):
+        result = decode_qr_id(encode(sample_payload()))
+
+        assert result["v"] == 1
+        assert result["code"] == "ACT-001"
+        assert result["id"] == "3101679980"
+        assert result["company"] == "Acme Corp S.A."
+        assert result["email"] == "billing@acme.example"
+        assert result["address"] == "123 Main St, San José, Costa Rica"
+
+    def test_handles_utf8(self):
+        result = decode_qr_id(
+            encode(sample_payload(
+                company="Société Générale",
+                address="Paseo Colón, San José, Costa Rica",
+            ))
+        )
+
+        assert result["company"] == "Société Générale"
+        assert result["address"] == "Paseo Colón, San José, Costa Rica"
+
+    def test_trims_surrounding_whitespace(self):
+        result = decode_qr_id("  " + encode(sample_payload()) + "  ")
+        assert result["code"] == "ACT-001"
+
+    def test_raises_value_error_on_invalid_base64(self):
+        with pytest.raises(ValueError, match="Invalid base64 input"):
+            decode_qr_id("not-valid-base64!!!")
+
+    def test_raises_on_non_json_payload(self):
+        with pytest.raises(json.JSONDecodeError):
+            decode_qr_id(base64.b64encode(b"not json").decode())
+
+
+# ── encode_qr_id ──────────────────────────────────────────────────────────────
+
+class TestEncodeQRId:
+    def test_returns_svg_string(self):
+        svg = encode_qr_id(
+            code="ACT-001",
+            id="3101679980",
+            company="Acme Corp S.A.",
+            email="billing@acme.example",
+            address="123 Main St",
+        )
+
+        assert isinstance(svg, str)
+        assert "<svg" in svg.lower()
+
+    def test_round_trip(self):
+        p = sample_payload()
+        encoded = base64.b64encode(
+            json.dumps(p, ensure_ascii=False).encode("utf-8")
+        ).decode()
+
+        decoded = decode_qr_id(encoded)
+
+        assert decoded["code"] == p["code"]
+        assert decoded["id"] == p["id"]
+        assert decoded["company"] == p["company"]