utmkit 0.1.0__tar.gz

utmkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calasdan-sketch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

utmkit-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: utmkit
+Version: 0.1.0
+Summary: Batch UTM campaign links with consistent slugs, validation, QR codes and a static index page
+Author: calasdan-sketch
+License-Expression: MIT
+Keywords: utm,campaign,tracking,qr,marketing,csv,links
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: qr
+Requires-Dist: qrcode[pil]>=7; extra == "qr"
+Dynamic: license-file
+
+# utmkit
+
+**Campaign links, done consistently.** Batch-build UTM-tagged URLs from a CSV spec, with deterministic file slugs, validation that catches the mistakes that silently wreck analytics, optional QR codes, and a static index page you can host or print.
+
+## Install
+
+```bash
+pip install utmkit            # links, slugs, validation
+pip install 'utmkit[qr]'      # + QR code generation
+```
+
+## One link
+
+```bash
+utmkit gen https://calasautomations.com/onfile \
+  --source instagram --medium social --campaign launch26
+# https://calasautomations.com/onfile?utm_source=instagram&utm_medium=social&utm_campaign=launch26
+
+utmkit gen ... --qr launch26-ig.png    # QR for the same URL (needs [qr] extra)
+utmkit gen ... --qr launch26-ig.svg    # vector SVG for print: needs only the qrcode package, no Pillow
+```
+
+## Batch
+
+`spec.csv`:
+
+```csv
+url,source,medium,campaign,name
+https://calasautomations.com/onfile,instagram,social,launch26,Spring Ad
+https://calasautomations.com/quote,newsletter,email,launch26,Quote Nudge
+```
+
+```bash
+utmkit batch spec.csv --out-dir out/ --qr --html
+```
+
+Produces `out/links.csv` (slug, final URL, QR filename), one QR code per row when enabled (PNG, or vector SVG with `--qr-format svg`), and `out/index.html` — a table of every link with clickable URLs and QR images.
+
+## Validation
+
+`utmkit validate spec.csv` flags the classics without building anything:
+
+- **error** — missing `utm_source`, empty URL
+- **warn** (`batch` only) — `duplicate_url`: two rows build the exact same final URL, so their clicks can't be told apart in analytics; the warning names both rows
+- **warn** — uppercase values (analytics tools split `Instagram` from `instagram`), spaces in values, unusual `utm_medium` values, URLs without a scheme
+
+`--fix` on `gen` and `batch` cleans the five UTM values before validation: lowercase, trim, and inner spaces to `-` (`" Instagram Ads "` becomes `instagram-ads`). Each change is reported as an `info` finding naming the old and new value. Without `--fix`, nothing is changed.
+
+Warnings don't fail the build unless `--strict`. In `batch`, a row with an error is reported and skipped (no link built) and the run exits 1.
+
+## Audit an existing link
+
+```bash
+utmkit parse "https://x.com/?utm_source=IG&utm_medium=social"
+# url: https://x.com/
+# utm_source: IG
+# utm_medium: social
+# WARN  not_lowercase: utm_source='IG' should be lowercase (analytics tools split cases)
+# WARN  no_campaign: utm_campaign is missing
+```
+
+Splits a tagged URL someone else made into its base URL and UTM values, then runs the same checks as `validate` (plus `--rules` if given). `parse` also warns when `utm_campaign` is missing (`gen`/`batch` don't). Exit 1 on an error such as a missing `utm_source`; `--json` for automation.
+
+## Naming rules (allow-list)
+
+Lock the values your team may use, so nobody invents `Insta` next to `instagram`:
+
+```json
+{"source": ["instagram", "facebook"], "medium": ["social", "email", "cpc", "qr"], "campaign_pattern": "^[a-z0-9-]+$"}
+```
+
+```bash
+utmkit validate spec.csv --rules rules.json      # also on gen and batch
+```
+
+All three keys are optional. A `source` or `medium` outside its list, or a `campaign` that doesn't match the regex, is an **error** (`not_allowed`): the row is skipped in `batch` and the run exits 1. When you give a `medium` list, it replaces the built-in "unusual medium" warning. A missing or malformed rules file (bad JSON, a list that isn't a list of strings, an invalid regex, an unknown key) exits 2 with a message. Use `--fix` together with `--rules` to lowercase values before they are checked.
+
+utmkit builds links; it doesn't track clicks. Pair it with your analytics tool.
+
+## Design notes
+
+- **Deterministic slugs**: the `name` column (else the final tagged URL) becomes the filename slug; collisions get `-2`, `-3` suffixes — same input, same output names, every run.
+- **Existing params survive**: `?id=7&ref=nav` stays intact; stale values for the five standard keys (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) are replaced by the campaign (the campaign is the source of truth); other params such as `utm_id` are kept.
+- **QR is optional**: the core has zero dependencies; `qrcode` is only imported when you pass `--qr` and installs via the `[qr]` extra. PNG needs Pillow (the extra pulls it in); SVG output uses qrcode's own SVG writer and works without Pillow. Custom backends can be injected through the Python API.
+- **Static `index.html`**: host it, print it, or hand it to whoever is running the campaign — no JS, no build step.
+
+## Python API
+
+```python
+from utmkit import Campaign, build_url, slugify
+
+url = build_url(Campaign("https://ex.com", source="ig", medium="social", campaign="c1"))
+assert slugify("Spring Sale — 20% OFF!") == "spring-sale-20-off"
+```
+
+## License
+
+MIT-style: use it, ship it, no warranty.

utmkit-0.1.0/README.md

@@ -0,0 +1,98 @@
+# utmkit
+
+**Campaign links, done consistently.** Batch-build UTM-tagged URLs from a CSV spec, with deterministic file slugs, validation that catches the mistakes that silently wreck analytics, optional QR codes, and a static index page you can host or print.
+
+## Install
+
+```bash
+pip install utmkit            # links, slugs, validation
+pip install 'utmkit[qr]'      # + QR code generation
+```
+
+## One link
+
+```bash
+utmkit gen https://calasautomations.com/onfile \
+  --source instagram --medium social --campaign launch26
+# https://calasautomations.com/onfile?utm_source=instagram&utm_medium=social&utm_campaign=launch26
+
+utmkit gen ... --qr launch26-ig.png    # QR for the same URL (needs [qr] extra)
+utmkit gen ... --qr launch26-ig.svg    # vector SVG for print: needs only the qrcode package, no Pillow
+```
+
+## Batch
+
+`spec.csv`:
+
+```csv
+url,source,medium,campaign,name
+https://calasautomations.com/onfile,instagram,social,launch26,Spring Ad
+https://calasautomations.com/quote,newsletter,email,launch26,Quote Nudge
+```
+
+```bash
+utmkit batch spec.csv --out-dir out/ --qr --html
+```
+
+Produces `out/links.csv` (slug, final URL, QR filename), one QR code per row when enabled (PNG, or vector SVG with `--qr-format svg`), and `out/index.html` — a table of every link with clickable URLs and QR images.
+
+## Validation
+
+`utmkit validate spec.csv` flags the classics without building anything:
+
+- **error** — missing `utm_source`, empty URL
+- **warn** (`batch` only) — `duplicate_url`: two rows build the exact same final URL, so their clicks can't be told apart in analytics; the warning names both rows
+- **warn** — uppercase values (analytics tools split `Instagram` from `instagram`), spaces in values, unusual `utm_medium` values, URLs without a scheme
+
+`--fix` on `gen` and `batch` cleans the five UTM values before validation: lowercase, trim, and inner spaces to `-` (`" Instagram Ads "` becomes `instagram-ads`). Each change is reported as an `info` finding naming the old and new value. Without `--fix`, nothing is changed.
+
+Warnings don't fail the build unless `--strict`. In `batch`, a row with an error is reported and skipped (no link built) and the run exits 1.
+
+## Audit an existing link
+
+```bash
+utmkit parse "https://x.com/?utm_source=IG&utm_medium=social"
+# url: https://x.com/
+# utm_source: IG
+# utm_medium: social
+# WARN  not_lowercase: utm_source='IG' should be lowercase (analytics tools split cases)
+# WARN  no_campaign: utm_campaign is missing
+```
+
+Splits a tagged URL someone else made into its base URL and UTM values, then runs the same checks as `validate` (plus `--rules` if given). `parse` also warns when `utm_campaign` is missing (`gen`/`batch` don't). Exit 1 on an error such as a missing `utm_source`; `--json` for automation.
+
+## Naming rules (allow-list)
+
+Lock the values your team may use, so nobody invents `Insta` next to `instagram`:
+
+```json
+{"source": ["instagram", "facebook"], "medium": ["social", "email", "cpc", "qr"], "campaign_pattern": "^[a-z0-9-]+$"}
+```
+
+```bash
+utmkit validate spec.csv --rules rules.json      # also on gen and batch
+```
+
+All three keys are optional. A `source` or `medium` outside its list, or a `campaign` that doesn't match the regex, is an **error** (`not_allowed`): the row is skipped in `batch` and the run exits 1. When you give a `medium` list, it replaces the built-in "unusual medium" warning. A missing or malformed rules file (bad JSON, a list that isn't a list of strings, an invalid regex, an unknown key) exits 2 with a message. Use `--fix` together with `--rules` to lowercase values before they are checked.
+
+utmkit builds links; it doesn't track clicks. Pair it with your analytics tool.
+
+## Design notes
+
+- **Deterministic slugs**: the `name` column (else the final tagged URL) becomes the filename slug; collisions get `-2`, `-3` suffixes — same input, same output names, every run.
+- **Existing params survive**: `?id=7&ref=nav` stays intact; stale values for the five standard keys (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) are replaced by the campaign (the campaign is the source of truth); other params such as `utm_id` are kept.
+- **QR is optional**: the core has zero dependencies; `qrcode` is only imported when you pass `--qr` and installs via the `[qr]` extra. PNG needs Pillow (the extra pulls it in); SVG output uses qrcode's own SVG writer and works without Pillow. Custom backends can be injected through the Python API.
+- **Static `index.html`**: host it, print it, or hand it to whoever is running the campaign — no JS, no build step.
+
+## Python API
+
+```python
+from utmkit import Campaign, build_url, slugify
+
+url = build_url(Campaign("https://ex.com", source="ig", medium="social", campaign="c1"))
+assert slugify("Spring Sale — 20% OFF!") == "spring-sale-20-off"
+```
+
+## License
+
+MIT-style: use it, ship it, no warranty.

utmkit-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "utmkit"
+version = "0.1.0"
+description = "Batch UTM campaign links with consistent slugs, validation, QR codes and a static index page"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "calasdan-sketch" }]
+keywords = ["utm", "campaign", "tracking", "qr", "marketing", "csv", "links"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+[project.scripts]
+utmkit = "utmkit.cli:main"
+
+[project.optional-dependencies]
+qr = ["qrcode[pil]>=7"]  # qrcode 8 no longer pulls in an image backend by itself
+
+[tool.setuptools.packages.find]
+where = ["src"]

utmkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

utmkit-0.1.0/src/utmkit/__init__.py

@@ -0,0 +1,6 @@
+"""utmkit — batch UTM campaign links, slugs, validation and QR codes."""
+
+from .core import Campaign, Finding, build_url, slugify, validate_campaign
+
+__version__ = "0.1.0"
+__all__ = ["Campaign", "Finding", "build_url", "slugify", "validate_campaign", "__version__"]

utmkit-0.1.0/src/utmkit/batch.py

@@ -0,0 +1,121 @@
+"""Batch processing: campaign spec CSV -> tracked links, slugs, optional QR + HTML."""
+from __future__ import annotations
+
+import csv
+import html
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .core import Campaign, Finding, build_url, normalize, slugify, unique_slug, validate_campaign
+from .qr import Backend, QrUnavailable, get_backend
+
+COLUMNS = ("url", "source", "medium", "campaign", "term", "content", "name")
+
+
+def load_campaigns(path: str) -> List[tuple]:
+    """Read the spec CSV; returns [(row_number, Campaign)]."""
+    out = []
+    with open(path, newline="", encoding="utf-8-sig") as fh:
+        reader = csv.DictReader(fh)
+        if not reader.fieldnames or "url" not in {f.strip().lower() for f in reader.fieldnames}:
+            raise ValueError("spec CSV needs a 'url' column")
+        for i, row in enumerate(reader, start=2):
+            norm = {(k or "").strip().lower(): (v or "").strip() for k, v in row.items()}
+            out.append((i, Campaign(
+                url=norm.get("url", ""),
+                source=norm.get("source", ""),
+                medium=norm.get("medium", ""),
+                campaign=norm.get("campaign", ""),
+                term=norm.get("term", ""),
+                content=norm.get("content", ""),
+                name=norm.get("name", ""),
+            )))
+    return out
+
+
+@dataclass
+class BatchResult:
+    rows: List[dict] = field(default_factory=list)
+    findings: List[Finding] = field(default_factory=list)
+    qr_written: List[str] = field(default_factory=list)
+
+
+def run_batch(
+    campaigns: List[tuple],
+    out_dir: str,
+    qr: bool = False,
+    html_index: bool = False,
+    qr_backend: Optional[Backend] = None,
+    fix: bool = False,
+    rules: Optional[dict] = None,
+    qr_format: str = "png",
+) -> BatchResult:
+    result = BatchResult()
+    os.makedirs(out_dir, exist_ok=True)
+    backend = None
+    if qr:
+        try:
+            backend = get_backend(qr_backend)
+        except QrUnavailable as e:
+            result.findings.append(Finding("warn", "qr_unavailable", "", str(e)))
+    taken: List[str] = []
+    seen: dict = {}                       # final_url -> first row number
+    for row_no, campaign in campaigns:
+        where = f"row {row_no}"
+        if fix:
+            campaign, fixed = normalize(campaign, where=where)
+            result.findings.extend(fixed)
+        row_findings = validate_campaign(campaign, where=where, rules=rules)
+        result.findings.extend(row_findings)
+        if any(f.severity == "error" for f in row_findings):
+            continue                      # reported above; don't build a broken link (or crash on no url)
+        url = build_url(campaign)
+        if url in seen:                   # same tracked link twice: clicks can't be told apart
+            result.findings.append(Finding("warn", "duplicate_url", where,
+                                           f"same final URL as row {seen[url]}: {url}"))
+        else:
+            seen[url] = row_no
+        base = slugify(campaign.name or url)
+        slug = unique_slug(base, taken)
+        taken.append(slug)
+        entry = {"slug": slug, "url": campaign.url, "final_url": url, "qr": ""}
+        if backend is not None:
+            qr_path = os.path.join(out_dir, f"{slug}.{qr_format}")
+            try:
+                backend(url, qr_path)
+                entry["qr"] = os.path.basename(qr_path)
+                result.qr_written.append(qr_path)
+            except Exception as e:  # backend failure shouldn't kill the batch
+                result.findings.append(Finding("warn", "qr_failed", where, str(e)))
+        result.rows.append(entry)
+    if html_index:
+        write_html_index(result, os.path.join(out_dir, "index.html"))
+    return result
+
+
+def write_csv(result: BatchResult, path: str) -> None:
+    with open(path, "w", newline="", encoding="utf-8") as fh:
+        writer = csv.DictWriter(fh, fieldnames=["slug", "final_url", "qr"])
+        writer.writeheader()
+        for row in result.rows:
+            writer.writerow({k: row[k] for k in ("slug", "final_url", "qr")})
+
+
+def write_html_index(result: BatchResult, path: str) -> None:
+    lines = ["<!doctype html><meta charset='utf-8'><title>Campaign links</title>",
+             "<table border='1' cellpadding='6'><tr><th>slug</th><th>link</th><th>QR</th></tr>"]
+    for row in result.rows:
+        qr_cell = (f"<img src='{html.escape(row['qr'])}' width='120' alt='QR'>"
+                   if row["qr"] else "")
+        link = html.escape(row["final_url"])
+        if row["final_url"].lower().startswith(("http://", "https://")):  # no javascript: hrefs
+            link = f"<a href='{link}'>{link}</a>"
+        lines.append(
+            f"<tr><td>{html.escape(row['slug'])}</td>"
+            f"<td>{link}</td>"
+            f"<td>{qr_cell}</td></tr>"
+        )
+    lines.append("</table>")
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines))

utmkit-0.1.0/src/utmkit/cli.py

@@ -0,0 +1,130 @@
+"""utmkit CLI: build single links or batches from a spec CSV."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .batch import load_campaigns, run_batch, write_csv
+from .core import (Campaign, Finding, build_url, campaign_from_url, load_rules, normalize,
+                   validate_campaign)
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):  # Windows cp1252 consoles choke on non-Latin values
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(prog="utmkit", description="Batch UTM campaign links + QR codes.")
+    ap.add_argument("--version", action="version", version=f"utmkit {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    g = sub.add_parser("gen", help="build one tracked URL")
+    g.add_argument("url")
+    g.add_argument("--source", default="")
+    g.add_argument("--medium", default="")
+    g.add_argument("--campaign", default="")
+    g.add_argument("--term", default="")
+    g.add_argument("--content", default="")
+    g.add_argument("--qr", metavar="PATH", help="also write a QR code here (.svg = vector, else PNG)")
+    g.add_argument("--fix", action="store_true", help="lowercase, trim, spaces to '-' in UTM values")
+    g.add_argument("--rules", metavar="JSON", help="JSON allow-list: source/medium lists, campaign_pattern regex")
+
+    b = sub.add_parser("batch", help="build many tracked URLs from a CSV spec")
+    b.add_argument("spec", help="CSV with columns: url, source, medium, campaign[, term, content, name]")
+    b.add_argument("--out-dir", default="utmkit-out")
+    b.add_argument("--qr", action="store_true", help="write QR codes (needs utmkit[qr])")
+    b.add_argument("--qr-format", choices=["png", "svg"], default="png",
+                   help="svg is vector/print-ready and needs no Pillow")
+    b.add_argument("--html", action="store_true", help="also write index.html linking everything")
+    b.add_argument("--strict", action="store_true", help="validation warnings exit non-zero")
+    b.add_argument("--fix", action="store_true", help="lowercase, trim, spaces to '-' in UTM values")
+    b.add_argument("--rules", metavar="JSON", help="JSON allow-list: source/medium lists, campaign_pattern regex")
+
+    v = sub.add_parser("validate", help="check a spec CSV without building anything")
+    v.add_argument("spec")
+    v.add_argument("--strict", action="store_true")
+    v.add_argument("--rules", metavar="JSON", help="JSON allow-list: source/medium lists, campaign_pattern regex")
+
+    pa = sub.add_parser("parse", help="decode and check an existing tagged URL")
+    pa.add_argument("url")
+    pa.add_argument("--json", action="store_true")
+    pa.add_argument("--rules", metavar="JSON", help="JSON allow-list: source/medium lists, campaign_pattern regex")
+
+    args = ap.parse_args(argv)
+    try:
+        rules = load_rules(args.rules) if args.rules else None
+    except ValueError as e:
+        print(f"utmkit: {e}", file=sys.stderr)
+        return 2
+
+    if args.cmd == "parse":
+        campaign = campaign_from_url(args.url)
+        findings = validate_campaign(campaign, where="parse", rules=rules)
+        if campaign.url and not campaign.campaign:   # auditing someone else's link: say it's missing
+            findings.append(Finding("warn", "no_campaign", "parse", "utm_campaign is missing"))
+        if args.json:
+            print(json.dumps({"url": campaign.url, "utm": campaign.utm(),
+                              "findings": [vars(f) for f in findings]}, indent=2))
+        else:
+            print(f"url: {campaign.url}")
+            for key, value in campaign.utm().items():
+                print(f"{key}: {value}")
+            for f in findings:
+                print(f"{f.severity.upper():5} {f.code}: {f.detail}")
+        return 1 if any(f.severity == "error" for f in findings) else 0
+
+    if args.cmd == "gen":
+        campaign = Campaign(url=args.url, source=args.source, medium=args.medium,
+                            campaign=args.campaign, term=args.term, content=args.content)
+        fixed = []
+        if args.fix:
+            campaign, fixed = normalize(campaign, where="gen")
+        findings = fixed + validate_campaign(campaign, where="gen", rules=rules)
+        errors = [f for f in findings if f.severity == "error"]
+        for f in findings:
+            print(f"{f.severity.upper():5} {f.code}: {f.detail}", file=sys.stderr)
+        if errors:
+            return 1
+        url = build_url(campaign)
+        print(url)
+        if args.qr:
+            from .qr import QrUnavailable, get_backend
+            try:
+                get_backend()(url, args.qr)
+                print(f"QR written: {args.qr}", file=sys.stderr)
+            except QrUnavailable as e:
+                print(f"{e}", file=sys.stderr)
+                return 1
+        return 0
+
+    try:
+        campaigns = load_campaigns(args.spec)
+    except (FileNotFoundError, ValueError) as e:
+        print(f"utmkit: {e}", file=sys.stderr)
+        return 2
+
+    if args.cmd == "validate":
+        findings = [f for row, c in campaigns for f in validate_campaign(c, where=f"row {row}", rules=rules)]
+        for f in findings:
+            print(f"{f.severity.upper():5} {f.where}: {f.code}: {f.detail}")
+        print(f"{len(findings)} finding(s)")
+        return 1 if any(f.severity == "error" for f in findings) or (args.strict and findings) else 0
+
+    result = run_batch(campaigns, out_dir=args.out_dir, qr=args.qr, html_index=args.html,
+                       fix=args.fix, rules=rules, qr_format=args.qr_format)
+    out_csv = f"{args.out_dir}/links.csv"
+    write_csv(result, out_csv)
+    errors = [f for f in result.findings if f.severity == "error"]
+    warns = [f for f in result.findings if f.severity == "warn"]
+    for f in result.findings:
+        print(f"{f.severity.upper():5} {f.where}: {f.code}: {f.detail}", file=sys.stderr)
+    print(f"{len(result.rows)} link(s) -> {out_csv}"
+          + (f", {len(result.qr_written)} QR code(s)" if result.qr_written else ""))
+    if errors or (args.strict and warns):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

utmkit-0.1.0/src/utmkit/core.py

@@ -0,0 +1,183 @@
+"""UTM link building, deterministic slugs and campaign validation."""
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from dataclasses import dataclass, field, replace
+from typing import Dict, List, Optional, Tuple
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+UTM_KEYS = ("utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content")
+_SLUG_CLEAN = re.compile(r"[^a-z0-9]+")
+
+
+@dataclass
+class Campaign:
+    url: str
+    source: str = ""
+    medium: str = ""
+    campaign: str = ""
+    term: str = ""
+    content: str = ""
+    name: str = ""
+    extra: Dict[str, str] = field(default_factory=dict)
+
+    def utm(self) -> Dict[str, str]:
+        pairs = {
+            "utm_source": self.source,
+            "utm_medium": self.medium,
+            "utm_campaign": self.campaign,
+            "utm_term": self.term,
+            "utm_content": self.content,
+        }
+        return {k: v for k, v in pairs.items() if v}
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: str  # error | warn | info
+    code: str
+    where: str
+    detail: str
+
+
+_UTM_FIELDS = (("utm_source", "source"), ("utm_medium", "medium"), ("utm_campaign", "campaign"),
+               ("utm_term", "term"), ("utm_content", "content"))
+
+
+def normalize(c: Campaign, where: str = "") -> Tuple[Campaign, List[Finding]]:
+    """Lowercase, trim and turn inner whitespace into '-' in the five UTM values.
+
+    Returns a new Campaign plus one ``info`` finding per value that changed.
+    """
+    where = where or c.name or c.url
+    changes, findings = {}, []
+    for key, attr in _UTM_FIELDS:
+        old = getattr(c, attr)
+        new = re.sub(r"\s+", "-", old.strip().lower())
+        if new != old:
+            changes[attr] = new
+            findings.append(Finding("info", "fixed", where, f"{key}: {old!r} -> {new!r}"))
+    return replace(c, **changes), findings
+
+
+def build_url(campaign: Campaign) -> str:
+    """Merge UTM parameters into the URL, preserving existing query params.
+
+    Existing values for the five standard UTM keys are replaced by the campaign
+    (the campaign is the source of truth); every other param survives, including
+    non-standard ones such as GA4's utm_id.
+    """
+    if not campaign.url:
+        raise ValueError("campaign url is empty")
+    parts = urlsplit(campaign.url)
+    kept = [(k, v) for k, v in parse_qsl(parts.query, keep_blank_values=True)
+            if k.lower() not in UTM_KEYS]
+    merged = kept + list(campaign.utm().items()) + list(campaign.extra.items())
+    return urlunsplit((parts.scheme, parts.netloc, parts.path,
+                       urlencode(merged), parts.fragment))
+
+
+def slugify(text: str, fallback: str = "link") -> str:
+    """URL-safe, lowercase, deterministic slug."""
+    text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
+    slug = _SLUG_CLEAN.sub("-", text.lower()).strip("-")
+    return slug or fallback
+
+
+def unique_slug(base: str, taken: List[str]) -> str:
+    """first-wins with -2, -3 ... suffixes for collisions."""
+    if base not in taken:
+        return base
+    n = 2
+    while f"{base}-{n}" in taken:
+        n += 1
+    return f"{base}-{n}"
+
+
+def load_rules(path: str) -> dict:
+    """Read a rules JSON: optional "source"/"medium" allow-lists and a "campaign_pattern" regex.
+
+    Raises ValueError with a readable message for a missing file, bad JSON or wrong shapes.
+    """
+    try:
+        with open(path, encoding="utf-8-sig") as fh:
+            rules = json.load(fh)
+    except FileNotFoundError:
+        raise ValueError(f"rules file not found: {path}") from None
+    except json.JSONDecodeError as e:
+        raise ValueError(f"rules file {path} is not valid JSON: {e}") from None
+    if not isinstance(rules, dict):
+        raise ValueError("rules file must hold a JSON object")
+    unknown = set(rules) - {"source", "medium", "campaign_pattern"}
+    if unknown:
+        raise ValueError(f"unknown rules key(s): {', '.join(sorted(unknown))}")
+    for key in ("source", "medium"):
+        if key in rules and not (isinstance(rules[key], list)
+                                 and all(isinstance(v, str) for v in rules[key])):
+            raise ValueError(f"rules '{key}' must be a list of strings")
+    if "campaign_pattern" in rules:
+        if not isinstance(rules["campaign_pattern"], str):
+            raise ValueError("rules 'campaign_pattern' must be a string")
+        try:
+            re.compile(rules["campaign_pattern"])
+        except re.error as e:
+            raise ValueError(f"rules 'campaign_pattern' is not a valid regex: {e}") from None
+    return rules
+
+
+def validate_campaign(c: Campaign, where: str = "", rules: Optional[dict] = None) -> List[Finding]:
+    """Flag the mistakes that silently wreck campaign data.
+
+    ``rules`` (see load_rules) turn values outside the allow-lists into errors.
+    """
+    rules = rules or {}
+    out: List[Finding] = []
+    where = where or c.name or c.url
+    if not c.url:
+        out.append(Finding("error", "no_url", where, "row has no url"))
+        return out
+    if not c.source:
+        out.append(Finding("error", "no_source", where, "utm_source is required"))
+    for key, value in (("utm_source", c.source), ("utm_medium", c.medium),
+                       ("utm_campaign", c.campaign), ("utm_term", c.term),
+                       ("utm_content", c.content)):
+        if value and value != value.lower():
+            out.append(Finding("warn", "not_lowercase", where,
+                               f"{key}={value!r} should be lowercase (analytics tools split cases)"))
+        if " " in value:
+            out.append(Finding("warn", "has_spaces", where,
+                               f"{key}={value!r} has spaces; prefer dashes"))
+    for key, value in (("source", c.source), ("medium", c.medium)):
+        if value and key in rules and value not in rules[key]:
+            out.append(Finding("error", "not_allowed", where,
+                               f"utm_{key}={value!r} is not in the rules list {rules[key]}"))
+    pattern = rules.get("campaign_pattern")
+    if c.campaign and pattern and not re.search(pattern, c.campaign):
+        out.append(Finding("error", "not_allowed", where,
+                           f"utm_campaign={c.campaign!r} does not match {pattern!r}"))
+    if "medium" not in rules and c.medium and c.medium not in (
+            "email", "social", "cpc", "ppc", "affiliate",
+            "organic", "referral", "display", "qr", "print"):
+        out.append(Finding("warn", "unusual_medium", where,
+                           f"utm_medium={c.medium!r} is not a common value "
+                           "(email/social/cpc/...): fine if intentional"))
+    if c.url and not c.url.lower().startswith(("http://", "https://")):
+        out.append(Finding("warn", "no_scheme", where, f"url {c.url!r} has no http(s) scheme"))
+    return out
+
+
+def campaign_from_url(url: str) -> Campaign:
+    """Split a tagged URL back into a Campaign (the inverse of build_url).
+
+    The five standard UTM keys become fields; every other param stays on ``url``.
+    """
+    parts = urlsplit(url)
+    pairs = parse_qsl(parts.query, keep_blank_values=True)
+    utm = {k.lower(): v for k, v in pairs if k.lower() in UTM_KEYS}
+    rest = [(k, v) for k, v in pairs if k.lower() not in UTM_KEYS]
+    base = urlunsplit((parts.scheme, parts.netloc, parts.path, urlencode(rest), parts.fragment))
+    return Campaign(url=base, source=utm.get("utm_source", ""), medium=utm.get("utm_medium", ""),
+                    campaign=utm.get("utm_campaign", ""), term=utm.get("utm_term", ""),
+                    content=utm.get("utm_content", ""))

utmkit-0.1.0/src/utmkit/qr.py

@@ -0,0 +1,42 @@
+"""QR generation through an optional backend.
+
+The core kit never depends on ``qrcode``; QR is enabled when it's installed
+(``pip install utmkit[qr]``) or when a custom backend is injected.
+"""
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+
+class QrUnavailable(RuntimeError):
+    """No QR backend present."""
+
+
+Backend = Callable[[str, str], None]  # (data, output_path) -> None
+
+
+def default_backend() -> Optional[Backend]:
+    try:
+        import qrcode  # type: ignore
+    except ImportError:
+        return None
+
+    def render(data: str, out_path: str) -> None:
+        if out_path.lower().endswith(".svg"):    # vector, print-ready; needs no Pillow
+            from qrcode.image.svg import SvgPathImage  # type: ignore
+            img = qrcode.make(data, image_factory=SvgPathImage)
+        else:
+            img = qrcode.make(data)               # PNG via Pillow (the [qr] extra)
+        img.save(out_path)
+
+    return render
+
+
+def get_backend(injected: Optional[Backend] = None) -> Backend:
+    backend = injected or default_backend()
+    if backend is None:
+        raise QrUnavailable(
+            "QR support needs the 'qrcode' package: pip install 'utmkit[qr]' "
+            "(or omit --qr)"
+        )
+    return backend

utmkit-0.1.0/src/utmkit.egg-info/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: utmkit
+Version: 0.1.0
+Summary: Batch UTM campaign links with consistent slugs, validation, QR codes and a static index page
+Author: calasdan-sketch
+License-Expression: MIT
+Keywords: utm,campaign,tracking,qr,marketing,csv,links
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: qr
+Requires-Dist: qrcode[pil]>=7; extra == "qr"
+Dynamic: license-file
+
+# utmkit
+
+**Campaign links, done consistently.** Batch-build UTM-tagged URLs from a CSV spec, with deterministic file slugs, validation that catches the mistakes that silently wreck analytics, optional QR codes, and a static index page you can host or print.
+
+## Install
+
+```bash
+pip install utmkit            # links, slugs, validation
+pip install 'utmkit[qr]'      # + QR code generation
+```
+
+## One link
+
+```bash
+utmkit gen https://calasautomations.com/onfile \
+  --source instagram --medium social --campaign launch26
+# https://calasautomations.com/onfile?utm_source=instagram&utm_medium=social&utm_campaign=launch26
+
+utmkit gen ... --qr launch26-ig.png    # QR for the same URL (needs [qr] extra)
+utmkit gen ... --qr launch26-ig.svg    # vector SVG for print: needs only the qrcode package, no Pillow
+```
+
+## Batch
+
+`spec.csv`:
+
+```csv
+url,source,medium,campaign,name
+https://calasautomations.com/onfile,instagram,social,launch26,Spring Ad
+https://calasautomations.com/quote,newsletter,email,launch26,Quote Nudge
+```
+
+```bash
+utmkit batch spec.csv --out-dir out/ --qr --html
+```
+
+Produces `out/links.csv` (slug, final URL, QR filename), one QR code per row when enabled (PNG, or vector SVG with `--qr-format svg`), and `out/index.html` — a table of every link with clickable URLs and QR images.
+
+## Validation
+
+`utmkit validate spec.csv` flags the classics without building anything:
+
+- **error** — missing `utm_source`, empty URL
+- **warn** (`batch` only) — `duplicate_url`: two rows build the exact same final URL, so their clicks can't be told apart in analytics; the warning names both rows
+- **warn** — uppercase values (analytics tools split `Instagram` from `instagram`), spaces in values, unusual `utm_medium` values, URLs without a scheme
+
+`--fix` on `gen` and `batch` cleans the five UTM values before validation: lowercase, trim, and inner spaces to `-` (`" Instagram Ads "` becomes `instagram-ads`). Each change is reported as an `info` finding naming the old and new value. Without `--fix`, nothing is changed.
+
+Warnings don't fail the build unless `--strict`. In `batch`, a row with an error is reported and skipped (no link built) and the run exits 1.
+
+## Audit an existing link
+
+```bash
+utmkit parse "https://x.com/?utm_source=IG&utm_medium=social"
+# url: https://x.com/
+# utm_source: IG
+# utm_medium: social
+# WARN  not_lowercase: utm_source='IG' should be lowercase (analytics tools split cases)
+# WARN  no_campaign: utm_campaign is missing
+```
+
+Splits a tagged URL someone else made into its base URL and UTM values, then runs the same checks as `validate` (plus `--rules` if given). `parse` also warns when `utm_campaign` is missing (`gen`/`batch` don't). Exit 1 on an error such as a missing `utm_source`; `--json` for automation.
+
+## Naming rules (allow-list)
+
+Lock the values your team may use, so nobody invents `Insta` next to `instagram`:
+
+```json
+{"source": ["instagram", "facebook"], "medium": ["social", "email", "cpc", "qr"], "campaign_pattern": "^[a-z0-9-]+$"}
+```
+
+```bash
+utmkit validate spec.csv --rules rules.json      # also on gen and batch
+```
+
+All three keys are optional. A `source` or `medium` outside its list, or a `campaign` that doesn't match the regex, is an **error** (`not_allowed`): the row is skipped in `batch` and the run exits 1. When you give a `medium` list, it replaces the built-in "unusual medium" warning. A missing or malformed rules file (bad JSON, a list that isn't a list of strings, an invalid regex, an unknown key) exits 2 with a message. Use `--fix` together with `--rules` to lowercase values before they are checked.
+
+utmkit builds links; it doesn't track clicks. Pair it with your analytics tool.
+
+## Design notes
+
+- **Deterministic slugs**: the `name` column (else the final tagged URL) becomes the filename slug; collisions get `-2`, `-3` suffixes — same input, same output names, every run.
+- **Existing params survive**: `?id=7&ref=nav` stays intact; stale values for the five standard keys (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) are replaced by the campaign (the campaign is the source of truth); other params such as `utm_id` are kept.
+- **QR is optional**: the core has zero dependencies; `qrcode` is only imported when you pass `--qr` and installs via the `[qr]` extra. PNG needs Pillow (the extra pulls it in); SVG output uses qrcode's own SVG writer and works without Pillow. Custom backends can be injected through the Python API.
+- **Static `index.html`**: host it, print it, or hand it to whoever is running the campaign — no JS, no build step.
+
+## Python API
+
+```python
+from utmkit import Campaign, build_url, slugify
+
+url = build_url(Campaign("https://ex.com", source="ig", medium="social", campaign="c1"))
+assert slugify("Spring Sale — 20% OFF!") == "spring-sale-20-off"
+```
+
+## License
+
+MIT-style: use it, ship it, no warranty.

utmkit-0.1.0/src/utmkit.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/utmkit/__init__.py
+src/utmkit/batch.py
+src/utmkit/cli.py
+src/utmkit/core.py
+src/utmkit/qr.py
+src/utmkit.egg-info/PKG-INFO
+src/utmkit.egg-info/SOURCES.txt
+src/utmkit.egg-info/dependency_links.txt
+src/utmkit.egg-info/entry_points.txt
+src/utmkit.egg-info/requires.txt
+src/utmkit.egg-info/top_level.txt
+tests/test_batch.py
+tests/test_core.py

utmkit-0.1.0/src/utmkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

utmkit-0.1.0/src/utmkit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+utmkit = utmkit.cli:main

utmkit-0.1.0/src/utmkit.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[qr]
+qrcode[pil]>=7

utmkit-0.1.0/src/utmkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+utmkit

utmkit-0.1.0/tests/test_batch.py

@@ -0,0 +1,199 @@
+"""Batch, QR-backend and CLI tests."""
+import csv
+import os
+
+from utmkit.batch import load_campaigns, run_batch, write_csv
+from utmkit.cli import main
+
+
+def write_spec(tmp, rows):
+    p = tmp / "spec.csv"
+    with open(p, "w", newline="", encoding="utf-8") as fh:
+        w = csv.writer(fh)
+        w.writerow(["url", "source", "medium", "campaign", "name"])
+        for r in rows:
+            w.writerow(r)
+    return str(p)
+
+
+def test_load_and_batch(tmp_path):
+    spec = write_spec(tmp_path, [
+        ["https://ex.com/a", "instagram", "social", "launch", "Spring Ad"],
+        ["https://ex.com/b", "newsletter", "email", "launch", "Spring Ad"],
+    ])
+    campaigns = load_campaigns(spec)
+    assert len(campaigns) == 2 and campaigns[0][1].source == "instagram"
+    result = run_batch(campaigns, str(tmp_path / "out"))
+    assert len(result.rows) == 2
+    # identical names get unique slugs
+    slugs = [r["slug"] for r in result.rows]
+    assert slugs == ["spring-ad", "spring-ad-2"]
+    assert result.rows[0]["final_url"].startswith("https://ex.com/a?utm_source=instagram")
+
+
+def test_qr_with_fake_backend(tmp_path):
+    calls = []
+
+    def fake_backend(data, path):
+        calls.append((data, path))
+        with open(path, "wb") as fh:
+            fh.write(b"\x89PNG")
+
+    spec = write_spec(tmp_path, [["https://ex.com", "ig", "social", "c", "n"]])
+    result = run_batch(load_campaigns(spec), str(tmp_path / "out"), qr=True, qr_backend=fake_backend)
+    assert len(calls) == 1 and result.rows[0]["qr"] == "n.png"
+    assert os.path.exists(os.path.join(str(tmp_path / "out"), "n.png"))
+
+
+def test_qr_unavailable_warns_not_crashes(tmp_path):
+    spec = write_spec(tmp_path, [["https://ex.com", "ig", "social", "c", "n"]])
+    result = run_batch(load_campaigns(spec), str(tmp_path / "out"), qr=True, qr_backend=None)
+    assert any(f.code == "qr_unavailable" for f in result.findings) or result.qr_written
+
+
+def test_html_index(tmp_path):
+    spec = write_spec(tmp_path, [["https://ex.com", "ig", "social", "c", "Home"]])
+    run_batch(load_campaigns(spec), str(tmp_path / "out"), html_index=True)
+    html = (tmp_path / "out" / "index.html").read_text(encoding="utf-8")
+    assert "utm_source=ig" in html and "<table" in html
+
+
+def test_write_csv(tmp_path):
+    spec = write_spec(tmp_path, [["https://ex.com", "ig", "social", "c", "x"]])
+    result = run_batch(load_campaigns(spec), str(tmp_path / "out"))
+    out = tmp_path / "out" / "links.csv"
+    write_csv(result, str(out))
+    rows = list(csv.DictReader(open(out, encoding="utf-8")))
+    assert rows[0]["slug"] == "x" and rows[0]["final_url"].startswith("https://ex.com?")
+
+
+def test_cli_gen(capsys):
+    assert main(["gen", "https://ex.com", "--source", "ig", "--medium", "social",
+                 "--campaign", "launch"]) == 0
+    assert "utm_source=ig" in capsys.readouterr().out
+
+
+def test_cli_gen_requires_source(capsys):
+    assert main(["gen", "https://ex.com"]) == 1
+
+
+def test_cli_batch_and_validate(tmp_path, capsys):
+    spec = write_spec(tmp_path, [
+        ["https://ex.com/a", "ig", "social", "launch", "One"],
+        ["https://ex.com/b", "Newsletter", "email", "launch", "Two"],
+    ])
+    assert main(["batch", spec, "--out-dir", str(tmp_path / "o"), "--html"]) == 0
+    assert (tmp_path / "o" / "links.csv").exists() and (tmp_path / "o" / "index.html").exists()
+    capsys.readouterr()
+    assert main(["validate", spec]) == 0  # warnings only
+    assert main(["validate", spec, "--strict"]) == 1
+
+
+def test_cli_bad_spec(tmp_path):
+    bad = tmp_path / "bad.csv"
+    bad.write_text("nope,columns\n1,2\n", encoding="utf-8")  # lacks the url column
+    assert main(["batch", str(bad)]) == 2
+
+
+def test_batch_skips_error_rows_instead_of_crashing(tmp_path):
+    spec = write_spec(tmp_path, [
+        ["", "instagram", "social", "launch", "No URL"],
+        ["https://ex.com/a", "instagram", "social", "launch", "Good"],
+    ])
+    out = tmp_path / "out"
+    assert main(["batch", spec, "--out-dir", str(out)]) == 1
+    rows = list(csv.DictReader(open(out / "links.csv", encoding="utf-8")))
+    assert [r["slug"] for r in rows] == ["good"]
+
+
+def test_html_index_never_links_non_http_urls(tmp_path):
+    spec = write_spec(tmp_path, [["javascript:alert(1)", "x", "email", "c", "bad"]])
+    out = tmp_path / "out"
+    main(["batch", spec, "--out-dir", str(out), "--html"])
+    page = (out / "index.html").read_text(encoding="utf-8")
+    assert "href='javascript" not in page and "javascript:alert(1)" in page
+
+
+def test_fix_flag_on_gen_and_batch(tmp_path, capsys):
+    assert main(["gen", "https://ex.com", "--source", " Instagram Ads ", "--fix"]) == 0
+    out, err = capsys.readouterr()
+    assert "utm_source=instagram-ads" in out and "INFO" in err and "fixed" in err
+    assert main(["gen", "https://ex.com", "--source", " Instagram Ads "]) == 0
+    out, err = capsys.readouterr()
+    assert "Instagram+Ads" in out and "not_lowercase" in err     # unchanged without --fix
+    spec = write_spec(tmp_path, [["https://ex.com/a", "Instagram Ads", "Social", "launch", "One"]])
+    assert main(["batch", spec, "--out-dir", str(tmp_path / "o"), "--fix", "--strict"]) == 0
+    rows = list(csv.DictReader(open(tmp_path / "o" / "links.csv", encoding="utf-8")))
+    assert "utm_source=instagram-ads&utm_medium=social" in rows[0]["final_url"]
+
+
+def test_duplicate_final_url_warns(tmp_path, capsys):
+    row = ["https://ex.com/a", "ig", "social", "launch", "One"]
+    spec = write_spec(tmp_path, [row, ["https://ex.com/b", "ig", "social", "launch", "Two"], row])
+    result = run_batch(load_campaigns(spec), str(tmp_path / "o"))
+    dups = [f for f in result.findings if f.code == "duplicate_url"]
+    assert len(dups) == 1 and dups[0].severity == "warn"
+    assert "row 2" in dups[0].detail and dups[0].where == "row 4"
+    assert main(["batch", spec, "--out-dir", str(tmp_path / "o")]) == 0
+    assert main(["batch", spec, "--out-dir", str(tmp_path / "o"), "--strict"]) == 1
+
+
+RULES = {"source": ["instagram", "facebook"], "medium": ["social", "email", "cpc", "qr"],
+         "campaign_pattern": "^[a-z0-9-]+$"}
+
+
+def test_rules_file_allow_list(tmp_path, capsys):
+    import json
+    rules = tmp_path / "rules.json"
+    rules.write_text(json.dumps(RULES), encoding="utf-8")
+    spec = write_spec(tmp_path, [["https://ex.com/a", "instagram", "Social-Media", "launch", "One"]])
+    assert main(["validate", spec, "--rules", str(rules)]) == 1
+    assert "not_allowed" in capsys.readouterr().out
+    assert main(["batch", spec, "--out-dir", str(tmp_path / "o"), "--rules", str(rules)]) == 1
+    assert main(["gen", "https://ex.com", "--source", "instagram", "--medium", "social",
+                 "--campaign", "Spring Sale", "--rules", str(rules)]) == 1     # campaign pattern
+    assert main(["gen", "https://ex.com", "--source", "facebook", "--medium", "cpc",
+                 "--campaign", "spring-sale", "--rules", str(rules)]) == 0
+    rules.write_text("{not json", encoding="utf-8")
+    assert main(["validate", spec, "--rules", str(rules)]) == 2
+    rules.write_text('{"medium": "social"}', encoding="utf-8")                  # must be a list
+    assert main(["validate", spec, "--rules", str(rules)]) == 2
+    rules.write_text('{"campaign_pattern": "("}', encoding="utf-8")             # bad regex
+    assert main(["validate", spec, "--rules", str(rules)]) == 2
+    assert main(["validate", spec, "--rules", str(tmp_path / "missing.json")]) == 2
+
+
+def test_parse_existing_url(capsys):
+    import json
+    url = "https://x.com/?utm_source=IG&utm_medium=social"
+    assert main(["parse", url]) == 0
+    out = capsys.readouterr().out
+    assert "utm_source: IG" in out and "not_lowercase" in out and "no_campaign" in out
+    assert main(["parse", url, "--json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["url"] == "https://x.com/" and data["utm"]["utm_source"] == "IG"
+    codes = {(f["severity"], f["code"]) for f in data["findings"]}
+    assert ("warn", "not_lowercase") in codes and ("warn", "no_campaign") in codes
+    assert main(["parse", "https://x.com/?id=7"]) == 1                    # no utm_source: error
+
+
+def test_batch_qr_format_svg_names_files_svg(tmp_path):
+    paths = []
+
+    def fake_backend(data, path):
+        paths.append(path)
+        open(path, "w").close()
+
+    spec = write_spec(tmp_path, [["https://ex.com", "ig", "social", "c", "n"]])
+    result = run_batch(load_campaigns(spec), str(tmp_path / "out"), qr=True,
+                       qr_backend=fake_backend, qr_format="svg")
+    assert paths[0].endswith("n.svg") and result.rows[0]["qr"] == "n.svg"
+
+
+def test_real_svg_qr_needs_no_pillow(tmp_path, capsys):
+    import pytest
+    pytest.importorskip("qrcode")
+    out = tmp_path / "x.svg"
+    assert main(["gen", "https://ex.com", "--source", "ig", "--qr", str(out)]) == 0
+    head = out.read_text(encoding="utf-8").lstrip()[:5]
+    assert head in ("<?xml", "<svg ") or head.startswith("<svg")

utmkit-0.1.0/tests/test_core.py

@@ -0,0 +1,95 @@
+"""URL building, slug and validation tests."""
+import pytest
+
+from utmkit.core import Campaign, build_url, slugify, unique_slug, validate_campaign
+
+
+def test_build_url_appends_utm():
+    url = build_url(Campaign("https://ex.com/landing", source="instagram", medium="social",
+                             campaign="launch26"))
+    assert url == "https://ex.com/landing?utm_source=instagram&utm_medium=social&utm_campaign=launch26"
+
+
+def test_build_url_preserves_existing_query():
+    url = build_url(Campaign("https://ex.com/p?id=7&ref=nav", source="email", campaign="wk42"))
+    assert "id=7" in url and "ref=nav" in url and "utm_source=email" in url
+
+
+def test_build_url_overrides_existing_utm():
+    url = build_url(Campaign("https://ex.com/?utm_source=old", source="new"))
+    assert "utm_source=new" in url and "old" not in url
+
+
+def test_build_url_encodes_spaces_and_fragment_kept():
+    url = build_url(Campaign("https://ex.com/a#top", source="a b", campaign="c"))
+    assert "utm_source=a+b" in url or "utm_source=a%20b" in url
+    assert url.endswith("#top")
+
+
+def test_build_url_empty_rejected():
+    with pytest.raises(ValueError):
+        build_url(Campaign(""))
+
+
+def test_slugify():
+    assert slugify("Spring Sale — 20% OFF!") == "spring-sale-20-off"
+    assert slugify("Ünïcode Ünicorn") == "unicode-unicorn"
+    assert slugify("***") == "link"
+    assert slugify("") == "link"
+
+
+def test_unique_slug_suffixes():
+    taken = []
+    assert unique_slug("a", taken) == "a" or (taken.append("a") or True)
+    taken.clear()
+    first = unique_slug("a", taken)
+    taken.append(first)
+    second = unique_slug("a", taken)
+    taken.append(second)
+    third = unique_slug("a", taken)
+    assert (first, second, third) == ("a", "a-2", "a-3")
+
+
+def test_validate_required_source():
+    findings = validate_campaign(Campaign("https://x.com"))
+    assert any(f.code == "no_source" and f.severity == "error" for f in findings)
+
+
+def test_validate_case_and_spaces_warn():
+    findings = validate_campaign(Campaign("https://x.com", source="Instagram", medium="email",
+                                          campaign="Spring Sale"))
+    codes = [f.code for f in findings]
+    assert "not_lowercase" in codes and "has_spaces" in codes
+
+
+def test_validate_unusual_medium_and_scheme():
+    findings = validate_campaign(Campaign("ex.com", source="a", medium="teleport"))
+    codes = [f.code for f in findings]
+    assert "unusual_medium" in codes and "no_scheme" in codes
+
+
+def test_validate_known_mediums_quiet():
+    for medium in ("email", "social", "cpc", "qr", "print"):
+        assert validate_campaign(Campaign("https://x.com", source="a", medium=medium)) == []
+
+
+def test_non_standard_utm_params_survive():
+    url = build_url(Campaign("https://ex.com/?utm_id=42&utm_source=old", source="new"))
+    assert "utm_id=42" in url and "utm_source=new" in url and "old" not in url
+
+
+def test_normalize_fixes_case_space_and_reports_changes():
+    from utmkit.core import normalize
+    c, findings = normalize(Campaign("https://x.com", source=" Instagram Ads ", medium="social"), where="gen")
+    assert c.source == "instagram-ads" and c.medium == "social"
+    assert len(findings) == 1 and findings[0].severity == "info" and findings[0].code == "fixed"
+    assert "Instagram Ads" in findings[0].detail and "instagram-ads" in findings[0].detail
+    assert validate_campaign(c) == []
+
+
+def test_validate_with_rules():
+    rules = {"medium": ["social"], "source": ["ig"]}
+    f = validate_campaign(Campaign("https://x.com", source="fb", medium="teleport"), rules=rules)
+    codes = [(x.severity, x.code) for x in f]
+    assert codes.count(("error", "not_allowed")) == 2
+    assert ("warn", "unusual_medium") not in codes      # the allow-list replaces the generic list