klaviyo-cli 0.1.0__py3-none-any.whl

klaviyo_cli/__init__.py

@@ -0,0 +1,3 @@
+"""klaviyo-cli: unofficial Klaviyo CLI."""
+
+__version__ = "0.1.0"

klaviyo_cli/_util.py

@@ -0,0 +1,186 @@
+"""Shared helpers for command modules: timezone parsing, date ranges, output."""
+
+import json as json_module
+import re
+from datetime import datetime
+
+import click
+from zoneinfo import ZoneInfo
+
+from .transport import KLAVIYO_BASE
+
+TZ_MAP = {
+    "EST": "America/New_York",
+    "EDT": "America/New_York",
+    "CST": "America/Chicago",
+    "CDT": "America/Chicago",
+    "MST": "America/Denver",
+    "MDT": "America/Denver",
+    "PST": "America/Los_Angeles",
+    "PDT": "America/Los_Angeles",
+}
+
+
+def _parse_send_time(date_str: str, time_str: str) -> str:
+    """Parse MM-DD-YYYY + 'HH:MM AM/PM TZ' into an ISO 8601 string with timezone."""
+    # Normalize date from MM-DD-YYYY → YYYY-MM-DD
+    parts = date_str.strip().split("-")
+    if len(parts) == 3 and len(parts[2]) == 4:
+        # MM-DD-YYYY
+        month, day, year = parts
+        iso_date = f"{year}-{month}-{day}"
+    else:
+        # Assume already YYYY-MM-DD
+        iso_date = date_str.strip()
+
+    time_parts = time_str.strip().split()
+    tz_name = "America/New_York"  # default
+
+    if len(time_parts) == 3:
+        # "3:00 PM EST"
+        t, ampm, tz_abbr = time_parts
+        t_str = f"{t} {ampm}"
+        fmt = "%I:%M %p"
+        tz_name = TZ_MAP.get(tz_abbr.upper(), tz_abbr)
+    elif len(time_parts) == 2:
+        if time_parts[1].upper() in ("AM", "PM"):
+            # "3:00 PM"
+            t_str = time_str.strip()
+            fmt = "%I:%M %p"
+        else:
+            # "15:00 CST"
+            t_str = time_parts[0]
+            fmt = "%H:%M"
+            tz_name = TZ_MAP.get(time_parts[1].upper(), time_parts[1])
+    else:
+        # "15:00"
+        t_str = time_parts[0]
+        fmt = "%H:%M"
+
+    dt = datetime.strptime(f"{iso_date} {t_str}", f"%Y-%m-%d {fmt}")
+    dt = dt.replace(tzinfo=ZoneInfo(tz_name))
+    return dt.isoformat()
+
+
+def _resolve_date_range(days: int, since: str | None, until: str | None):
+    """Resolve a (start, end, label) tuple from --days / --since / --until.
+
+    If either --since or --until is provided, the explicit bounds win. Otherwise
+    falls back to (now - days) .. now. Dates are parsed as YYYY-MM-DD in UTC; the
+    end date is inclusive (23:59:59).
+    """
+    from datetime import datetime, timedelta, timezone
+
+    end = datetime.now(timezone.utc)
+    start = end - timedelta(days=days)
+    label = f"last {days} days"
+
+    if since or until:
+        if since:
+            try:
+                start = datetime.strptime(since, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+            except ValueError:
+                raise click.ClickException(f"Invalid --since date {since!r} — expected YYYY-MM-DD")
+        if until:
+            try:
+                parsed = datetime.strptime(until, "%Y-%m-%d")
+                end = parsed.replace(hour=23, minute=59, second=59, tzinfo=timezone.utc)
+            except ValueError:
+                raise click.ClickException(f"Invalid --until date {until!r} — expected YYYY-MM-DD")
+        label = f"{start.strftime('%Y-%m-%d')} to {end.strftime('%Y-%m-%d')}"
+
+    return start, end, label
+
+
+def output(data, use_json: bool = False):
+    """Print data — raw JSON if use_json, otherwise assume caller formatted it."""
+    if use_json:
+        print(json_module.dumps(data, indent=2, default=str))
+    else:
+        if isinstance(data, str):
+            print(data)
+        else:
+            # Fallback for unformatted data — callers should format before calling
+            print(json_module.dumps(data, indent=2, default=str))
+
+
+# ---------------------------------------------------------------------------
+# Segment definition helpers
+# ---------------------------------------------------------------------------
+#
+# Klaviyo segment conditions reference metrics by opaque ID (e.g. "profile-metric"
+# conditions carry a metric_id like "XJcga2" rather than a name like "Opened
+# Email"). Reading or building any metric-based segment requires the ID->name
+# map, so these helpers back both list-metrics and the segment commands.
+
+_WINDOW_UNIT = {"day": "d", "week": "w", "month": "mo", "hour": "h", "year": "y"}
+_OP_SYMBOL = {"greater-than": ">", "greater-than-or-equal": ">=",
+              "less-than": "<", "less-than-or-equal": "<=", "equals": "="}
+
+
+def _resolve_metrics(call) -> dict:
+    """Return {metric_id: {"name": str, "integration": str}} for all metrics."""
+    out: dict = {}
+    path = "/api/metrics/"
+    while path:
+        data = call("GET", path)
+        for m in data.get("data", []):
+            attrs = m.get("attributes", {})
+            out[m["id"]] = {
+                "name": attrs.get("name", "?"),
+                "integration": (attrs.get("integration") or {}).get("name", ""),
+            }
+        next_link = data.get("links", {}).get("next")
+        path = next_link.replace(KLAVIYO_BASE, "") if next_link else None
+    return out
+
+
+def _format_condition(cond: dict, metric_map: dict) -> str:
+    """Render a single segment condition to a human-readable string."""
+    t = cond.get("type")
+    if t == "profile-marketing-consent":
+        ch = (cond.get("consent") or {}).get("channel", "?")
+        return f"can receive {ch} marketing"
+    if t == "profile-property":
+        prop = cond.get("property", "?")
+        m = re.match(r"properties\['(.+)'\]", prop)
+        prop = m.group(1) if m else prop
+        f = cond.get("filter") or {}
+        ft = f.get("type")
+        if ft == "existence":
+            return f"{prop} is {f.get('operator', '?')}"
+        if ft == "boolean":
+            return f"{prop} = {f.get('value')}"
+        val = f.get("value")
+        return f"{prop} {f.get('operator', '?')}{'' if val is None else ' ' + str(val)}"
+    if t == "profile-metric":
+        mid = cond.get("metric_id")
+        name = metric_map.get(mid, {}).get("name", mid)
+        mf = cond.get("measurement_filter") or {}
+        op = _OP_SYMBOL.get(mf.get("operator"), mf.get("operator", "?"))
+        val = mf.get("value")
+        tf = cond.get("timeframe_filter") or {}
+        window = ""
+        if tf.get("operator") == "in-the-last":
+            unit = _WINDOW_UNIT.get(tf.get("unit"), tf.get("unit", ""))
+            window = f" in last {tf.get('quantity')}{unit}"
+        return f"{name} {op}{val}{window}"
+    return t or "?"
+
+
+def _render_definition(definition: dict, metric_map: dict, oneline: bool = False):
+    """Render condition_groups. Groups are AND'd; conditions within OR'd.
+
+    Returns a list of per-group strings, or a single AND-joined string when
+    oneline=True.
+    """
+    groups = (definition or {}).get("condition_groups", [])
+    rendered = [" OR ".join(_format_condition(c, metric_map) for c in g.get("conditions", []))
+                for g in groups]
+    if oneline:
+        return " AND ".join(f"({g})" if " OR " in g else g for g in rendered)
+    return rendered
+
+
+def _norm_name(s: str) -> str:
+    return re.sub(r"\s+", " ", (s or "").strip().lower())

klaviyo_cli/cli.py

@@ -0,0 +1,48 @@
+"""CLI group: `klaviyo` command. Commands live in klaviyo_cli/commands/."""
+
+from importlib.metadata import entry_points
+
+import click
+
+from .config import resolve_transport
+
+
+def build_context(profile: str | None) -> dict:
+    """Build ctx.obj auth pieces. Transport resolves lazily on first call."""
+    transport = None
+
+    def call(method, path, body=None, revision=None):
+        nonlocal transport
+        if transport is None:
+            transport = resolve_transport(profile)
+        return transport.call(method, path, body=body, revision=revision)
+
+    return {"call": call, "label": profile or "default"}
+
+
+@click.group()
+@click.option("--json", "use_json", is_flag=True, help="Output raw JSON")
+@click.option("-p", "--profile", envvar="KLAVIYO_PROFILE", default=None,
+              help="Named account profile from ~/.config/klaviyo-cli/config.toml")
+@click.version_option(package_name="klaviyo-cli")
+@click.pass_context
+def main(ctx, use_json, profile):
+    """Unofficial Klaviyo CLI: campaigns, segments, flows, metrics, scheduling.
+
+    Auth: set KLAVIYO_API_KEY, or use --profile with a config file.
+    Not affiliated with or endorsed by Klaviyo, Inc.
+    """
+    ctx.obj = {"json": use_json, **build_context(profile)}
+
+
+def entry():
+    """Console-script entry. Host packages (klaviyo_cli.hosts entry points)
+    may supply a replacement group (e.g. an agency wrapper with per-client auth)."""
+    for ep in entry_points(group="klaviyo_cli.hosts"):
+        group = ep.load()()
+        if group is not None:
+            return group()
+    return main()
+
+
+from . import commands  # noqa: E402,F401  (registers subcommands on `main`)

klaviyo_cli/commands/__init__.py

@@ -0,0 +1,7 @@
+"""Import command modules so they register on the main group."""
+from . import campaigns  # noqa: F401
+from . import segments  # noqa: F401
+from . import flows  # noqa: F401
+from . import metrics  # noqa: F401
+from . import sms  # noqa: F401
+from . import raw  # noqa: F401