utmkit 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+utmkit/__init__.py,sha256=8i3nSd_T9j0SCeonpSwFO03iwXNdodB05CMlT_Sm2Qw,274
+utmkit/batch.py,sha256=nOFoSBY_24oX4wkXBEPiryOYO_0RQULthpW-Om8Pgqo,5088
+utmkit/cli.py,sha256=_mopA9h_XwaX1ZyUu8cWMMbTom80UyLgubpjr4HTJyo,6388
+utmkit/core.py,sha256=dlYbOfcouSS-z_Cd3IKeZUSX7HP-Nn3pR94K78KkJXQ,7650
+utmkit/qr.py,sha256=Oa-VbHnFjSZ3_vk0A6sWEoElRkzjulavtV1gqsVkQDA,1304
+utmkit-0.1.0.dist-info/licenses/LICENSE,sha256=MlKnYMK2NBctIb-rpLY0EIwVni85V8-igwwParSUi6I,1093
+utmkit-0.1.0.dist-info/METADATA,sha256=yoBxnzsmDvyoj7nuUitBf14DKJP7ldu7SHFEpdhfwx8,5534
+utmkit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+utmkit-0.1.0.dist-info/entry_points.txt,sha256=EKVtx_za00bFaLS7BQHNwrrtHQwW5_sM2kuzFPdyaTo,43
+utmkit-0.1.0.dist-info/top_level.txt,sha256=Z5zxVrsM6ak01SNUQ99N3F-yHXDS_2bdw7zy3D708-A,7
+utmkit-0.1.0.dist-info/RECORD,,

utmkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

utmkit-0.1.0.dist-info/entry_points.txt

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

utmkit-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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