ft-hubspot-workflow-backup 0.1.4__py3-none-any.whl

ft_hubspot_workflow_backup/__init__.py

@@ -0,0 +1,14 @@
+from .client import HubSpotClient
+from .backup import backup_all_flows, get_timestamp, slugify, verify_backups
+from .restore import restore_flow
+
+__version__ = "0.1.4"
+
+__all__ = [
+    "HubSpotClient",
+    "backup_all_flows",
+    "restore_flow",
+    "verify_backups",
+    "get_timestamp",
+    "slugify",
+]

ft_hubspot_workflow_backup/backup.py

@@ -0,0 +1,315 @@
+import argparse
+import hashlib
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, Union
+
+import requests
+
+from .client import HubSpotClient
+
+
+def get_filter_sort_key(f: dict) -> tuple:
+    """Get a sort key for a filter based on property, type, and value."""
+    operation = f.get("operation", {})
+    op_value = operation.get("value", "") or str(operation.get("values", []))
+    return (
+        f.get("property", ""),
+        f.get("filterType", ""),
+        op_value,
+    )
+
+
+def get_filter_branch_sort_key(branch: dict) -> tuple:
+    """Get a sort key for a filter branch based on its first filter."""
+    filters = branch.get("filters", [])
+    if filters:
+        first_filter = filters[0]
+        operation = first_filter.get("operation", {})
+        op_value = operation.get("value", "") or str(operation.get("values", []))
+        return (
+            first_filter.get("property", ""),
+            first_filter.get("filterType", ""),
+            op_value,
+        )
+    return ("", "", "")
+
+
+def sort_filters(obj: dict | list) -> dict | list:
+    """Recursively sort filters and filter branches for consistent output."""
+    if isinstance(obj, dict):
+        for key, value in obj.items():
+            if key == "filters" and isinstance(value, list):
+                obj[key] = sorted(value, key=get_filter_sort_key)
+            elif key == "reEnrollmentTriggersFilterBranches" and isinstance(
+                value, list
+            ):
+                for branch in value:
+                    sort_filters(branch)
+                obj[key] = sorted(value, key=get_filter_branch_sort_key)
+            else:
+                sort_filters(value)
+    elif isinstance(obj, list):
+        for item in obj:
+            sort_filters(item)
+    return obj
+
+
+def normalize_flow(flow: dict) -> dict:
+    """Normalize flow data for consistent serialization."""
+    if "dataSources" in flow and isinstance(flow["dataSources"], list):
+        flow["dataSources"] = sorted(
+            flow["dataSources"],
+            key=lambda ds: (
+                ds.get("objectTypeId", ""),
+                ds.get("associationTypeId", 0),
+                ds.get("name", ""),
+            ),
+        )
+    sort_filters(flow)
+    return flow
+
+
+def slugify(name: str, max_length: int = 80) -> str:
+    """
+    Convert flow name to filesystem-safe slug.
+
+    Args:
+        name: Flow name to slugify.
+        max_length: Maximum slug length.
+
+    Returns:
+        Lowercase slug with only alphanumeric, dash, underscore.
+    """
+    if not name:
+        return "unnamed-flow"
+    slug = name.lower()
+    slug = re.sub(r"\s+", "-", slug)
+    slug = re.sub(r"[^a-z0-9_-]", "", slug)
+    if not slug:
+        slug = "unnamed-flow"
+    if len(slug) > max_length:
+        slug = slug[:max_length]
+    return slug
+
+
+def get_timestamp() -> str:
+    """
+    Get current UTC timestamp for backup naming.
+
+    Returns:
+        Timestamp string in YYYY_MM_DD_HHMMSS format.
+    """
+    return datetime.now(timezone.utc).strftime("%Y_%m_%d_%H%M%S")
+
+
+def backup_all_flows(
+    token: Optional[str] = None,
+    output_dir: Optional[Union[str, Path]] = None,
+    client: Optional[HubSpotClient] = None,
+    use_date_dir: bool = False,
+    use_date_prefix: bool = False,
+) -> Path:
+    """
+    Backup all HubSpot automation flows to JSON files.
+
+    Args:
+        token: HubSpot token. Falls back to HUBSPOT_AUTOMATION_TOKEN env var.
+        output_dir: Directory for snapshots. Defaults to ./snapshots/.
+        client: Pre-configured HubSpotClient instance.
+        use_date_dir: If True, create a timestamped subdirectory for this run.
+        use_date_prefix: If True, prefix each workflow filename with timestamp.
+
+    Returns:
+        Path to the created snapshot directory.
+    """
+    if client is None:
+        client = HubSpotClient(token=token)
+
+    timestamp = get_timestamp()
+
+    if output_dir is None:
+        output_dir = Path.cwd() / "snapshots"
+    else:
+        output_dir = Path(output_dir)
+
+    if use_date_dir:
+        run_dir = output_dir / timestamp
+    else:
+        run_dir = output_dir
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    flows = client.list_flows()
+
+    if not flows:
+        return run_dir
+
+    index_entries = []
+
+    for flow in flows:
+        flow_id = str(flow.get("id"))
+        name = flow.get("name") or f"flow-{flow_id}"
+        slug = slugify(name)
+
+        try:
+            details = client.get_flow(flow_id)
+        except requests.exceptions.HTTPError:
+            continue
+
+        details = normalize_flow(details)
+
+        if use_date_prefix:
+            filename = f"{timestamp}_{slug}.json"
+        else:
+            filename = f"{slug}.json"
+        filepath = run_dir / filename
+
+        with filepath.open("w", encoding="utf-8") as f:
+            json.dump(details, f, indent=2, sort_keys=True)
+
+        index_entries.append({
+            "id": flow_id,
+            "name": name,
+            "filename": filename,
+            "isEnabled": details.get("isEnabled"),
+            "flowType": details.get("flowType"),
+            "type": details.get("type"),
+        })
+
+    for entry in index_entries:
+        filepath = run_dir / entry["filename"]
+        content = filepath.read_bytes()
+        entry["hash"] = hashlib.sha256(content).hexdigest()
+
+    index_path = run_dir / "_index.json"
+    with index_path.open("w", encoding="utf-8") as f:
+        json.dump({
+            "timestamp": timestamp,
+            "flows": index_entries,
+        }, f, indent=2)
+
+    return run_dir
+
+
+def verify_backups(snapshot_dir: Optional[Union[str, Path]] = None) -> dict:
+    """
+    Verify all workflow backups against their stored SHA-256 hashes.
+
+    Args:
+        snapshot_dir: Directory containing snapshots. Defaults to ./snapshots/.
+
+    Returns:
+        Dict with 'verified', 'failed', and 'missing' lists of filenames.
+    """
+    if snapshot_dir is None:
+        snapshot_path = Path.cwd() / "snapshots"
+    else:
+        snapshot_path = Path(snapshot_dir)
+
+    index_path = snapshot_path / "_index.json"
+    if not index_path.exists():
+        raise FileNotFoundError(f"Index file not found: {index_path}")
+
+    with index_path.open("r", encoding="utf-8") as f:
+        index = json.load(f)
+
+    results: dict = {"verified": [], "failed": [], "missing": []}
+
+    for flow in index.get("flows", []):
+        filename = flow.get("filename")
+        expected_hash = flow.get("hash")
+
+        if not filename or not expected_hash:
+            continue
+
+        filepath = snapshot_path / filename
+        if not filepath.exists():
+            results["missing"].append(filename)
+            continue
+
+        actual_hash = hashlib.sha256(filepath.read_bytes()).hexdigest()
+        if actual_hash == expected_hash:
+            results["verified"].append(filename)
+        else:
+            results["failed"].append(filename)
+
+    return results
+
+
+def main() -> None:
+    """CLI entry point for workflows-backup command."""
+    parser = argparse.ArgumentParser(
+        description="Backup HubSpot automation workflows to JSON files."
+    )
+    parser.add_argument(
+        "-o", "--output-dir",
+        type=str,
+        default=None,
+        help="Output directory for snapshots (default: ./snapshots/)"
+    )
+    parser.add_argument(
+        "--use-date-dir",
+        action="store_true",
+        help="Create a timestamped subdirectory for this backup run"
+    )
+    parser.add_argument(
+        "--use-date-prefix",
+        action="store_true",
+        help="Prefix each workflow filename with a timestamp"
+    )
+    parser.add_argument(
+        "--verify",
+        action="store_true",
+        help="Verify backup integrity after completion"
+    )
+    args = parser.parse_args()
+
+    try:
+        client = HubSpotClient()
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print("Listing all HubSpot automation flows (v4)...\n")
+    flows = client.list_flows()
+
+    if not flows:
+        print("No flows returned.")
+        return
+
+    print(f"Total flows returned: {len(flows)}")
+    for flow in flows:
+        print(f"{flow.get('id')}: {flow.get('name')}")
+
+    print("\nBacking up flows...")
+    run_dir = backup_all_flows(
+        client=client,
+        output_dir=args.output_dir,
+        use_date_dir=args.use_date_dir,
+        use_date_prefix=args.use_date_prefix,
+    )
+
+    print(f"\nBackup complete.")
+    print(f"Files saved to: {run_dir}")
+
+    if args.verify:
+        print("\nVerifying backup integrity...")
+        results = verify_backups(run_dir)
+        print(f"  Verified: {len(results['verified'])}")
+        if results["failed"]:
+            print(f"  Failed: {len(results['failed'])}")
+            for f in results["failed"]:
+                print(f"    - {f}")
+            sys.exit(1)
+        if results["missing"]:
+            print(f"  Missing: {len(results['missing'])}")
+            for f in results["missing"]:
+                print(f"    - {f}")
+        print("All backups verified successfully.")
+
+
+if __name__ == "__main__":
+    main()

ft_hubspot_workflow_backup/client.py

@@ -0,0 +1,86 @@
+import os
+from typing import Optional
+
+import requests
+
+
+class HubSpotClient:
+    """Client for HubSpot Automation v4 API."""
+
+    BASE_URL = "https://api.hubapi.com"
+
+    def __init__(self, token: Optional[str] = None):
+        """
+        Initialize client.
+
+        Args:
+            token: HubSpot private app token. Falls back to HUBSPOT_AUTOMATION_TOKEN env var.
+        """
+        self.token = token or os.getenv("HUBSPOT_AUTOMATION_TOKEN")
+        if not self.token:
+            raise ValueError(
+                "HubSpot token required. Pass token= or set HUBSPOT_AUTOMATION_TOKEN env var."
+            )
+        self._headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    def list_flows(self) -> list:
+        """
+        List all automation flows with pagination.
+
+        Returns:
+            List of flow summary dicts.
+        """
+        url = f"{self.BASE_URL}/automation/v4/flows"
+        params = {"limit": 100}
+        flows: list = []
+
+        while True:
+            resp = requests.get(url, headers=self._headers, params=params, timeout=30)
+            resp.raise_for_status()
+
+            data = resp.json()
+            batch = data.get("results", [])
+            flows.extend(batch)
+
+            paging = data.get("paging") or {}
+            next_page = paging.get("next") if isinstance(paging, dict) else None
+            after = next_page.get("after") if isinstance(next_page, dict) else None
+            if not after:
+                break
+            params["after"] = after
+
+        return flows
+
+    def get_flow(self, flow_id: str) -> dict:
+        """
+        Get full details of a flow.
+
+        Args:
+            flow_id: HubSpot flow ID.
+
+        Returns:
+            Flow details dict.
+        """
+        url = f"{self.BASE_URL}/automation/v4/flows/{flow_id}"
+        resp = requests.get(url, headers=self._headers, timeout=30)
+        resp.raise_for_status()
+        return resp.json()
+
+    def update_flow(self, flow_id: str, body: dict) -> dict:
+        """
+        Update a flow configuration.
+
+        Args:
+            flow_id: HubSpot flow ID.
+            body: Flow configuration to apply.
+
+        Returns:
+            Updated flow dict.
+        """
+        url = f"{self.BASE_URL}/automation/v4/flows/{flow_id}"
+        resp = requests.put(url, headers=self._headers, json=body, timeout=30)
+        resp.raise_for_status()
+        return resp.json()

ft_hubspot_workflow_backup/restore.py

@@ -0,0 +1,327 @@
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Optional, Union
+
+from .client import HubSpotClient
+
+
+def build_datasource_mapping(backup_datasources: list, target_datasources: list) -> dict:
+    """
+    Build mapping between backup and target datasource IDs.
+
+    Args:
+        backup_datasources: Datasources from backup JSON.
+        target_datasources: Datasources from current flow.
+
+    Returns:
+        Dict mapping old fetched_object IDs to new IDs.
+    """
+    def ds_key(ds):
+        return (ds.get("objectTypeId"), ds.get("associationTypeId"), ds.get("type"))
+
+    def extract_id(name):
+        match = re.search(r'fetched_object_(\d+)', name)
+        return match.group(1) if match else None
+
+    target_by_key = {}
+    for ds in target_datasources:
+        key = ds_key(ds)
+        ds_id = extract_id(ds.get("name", ""))
+        if ds_id and key not in target_by_key:
+            target_by_key[key] = ds_id
+
+    mapping = {}
+    for ds in backup_datasources:
+        key = ds_key(ds)
+        backup_id = extract_id(ds.get("name", ""))
+        if backup_id and key in target_by_key:
+            target_id = target_by_key[key]
+            if backup_id != target_id:
+                mapping[backup_id] = target_id
+
+    return mapping
+
+
+def remap_fetched_objects(obj, mapping: dict):
+    """
+    Recursively remap fetched_object references in a data structure.
+
+    Args:
+        obj: Data structure (str, dict, list, or other).
+        mapping: Dict mapping old IDs to new IDs.
+
+    Returns:
+        Data structure with remapped references.
+    """
+    if not mapping:
+        return obj
+    if isinstance(obj, str):
+        result = obj
+        for old_id, new_id in mapping.items():
+            result = result.replace(f"fetched_object_{old_id}", f"fetched_object_{new_id}")
+        return result
+    elif isinstance(obj, dict):
+        return {k: remap_fetched_objects(v, mapping) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [remap_fetched_objects(item, mapping) for item in obj]
+    return obj
+
+
+def renumber_actions(backup_actions: list, backup_start_id: str, current_next_available: str) -> tuple:
+    """
+    Renumber action IDs to avoid conflicts with existing flow actions.
+
+    Args:
+        backup_actions: List of actions from backup.
+        backup_start_id: Start action ID from backup.
+        current_next_available: Next available action ID in target flow.
+
+    Returns:
+        Tuple of (renumbered_actions, new_start_id, new_next_available).
+    """
+    if not backup_actions:
+        return [], None, current_next_available
+
+    start_id = int(current_next_available)
+    old_to_new = {}
+
+    for i, action in enumerate(backup_actions):
+        old_id = action.get("actionId")
+        new_id = str(start_id + i)
+        old_to_new[old_id] = new_id
+
+    def remap_id(old_id):
+        return old_to_new.get(old_id, old_id)
+
+    def remap_action(action):
+        new_action = dict(action)
+        new_action["actionId"] = remap_id(action["actionId"])
+
+        if "connection" in new_action:
+            conn = dict(new_action["connection"])
+            if "nextActionId" in conn:
+                conn["nextActionId"] = remap_id(conn["nextActionId"])
+            new_action["connection"] = conn
+
+        if "staticBranches" in new_action and new_action["staticBranches"]:
+            new_branches = []
+            for branch in new_action["staticBranches"]:
+                new_branch = dict(branch)
+                if "nextActionId" in new_branch:
+                    new_branch["nextActionId"] = remap_id(new_branch["nextActionId"])
+                if "connection" in new_branch and new_branch["connection"]:
+                    conn = dict(new_branch["connection"])
+                    if "nextActionId" in conn:
+                        conn["nextActionId"] = remap_id(conn["nextActionId"])
+                    new_branch["connection"] = conn
+                new_branches.append(new_branch)
+            new_action["staticBranches"] = new_branches
+
+        if "defaultBranch" in new_action:
+            db = dict(new_action["defaultBranch"])
+            if "nextActionId" in db:
+                db["nextActionId"] = remap_id(db["nextActionId"])
+            new_action["defaultBranch"] = db
+
+        if "acceptActions" in new_action:
+            new_action["acceptActions"] = [remap_id(a) for a in new_action["acceptActions"]]
+        if "rejectActions" in new_action:
+            new_action["rejectActions"] = [remap_id(a) for a in new_action["rejectActions"]]
+
+        if "listBranches" in new_action and new_action["listBranches"]:
+            new_list_branches = []
+            for lb in new_action["listBranches"]:
+                new_lb = dict(lb)
+                if "connection" in new_lb and new_lb["connection"]:
+                    conn = dict(new_lb["connection"])
+                    if "nextActionId" in conn:
+                        conn["nextActionId"] = remap_id(conn["nextActionId"])
+                    new_lb["connection"] = conn
+                new_list_branches.append(new_lb)
+            new_action["listBranches"] = new_list_branches
+
+        return new_action
+
+    renumbered = [remap_action(a) for a in backup_actions]
+    new_start_id = remap_id(backup_start_id) if backup_start_id else None
+    new_next_available = str(start_id + len(backup_actions))
+
+    def remap_action_output_refs(obj):
+        if isinstance(obj, str):
+            def replace_ref(match):
+                prefix = match.group(1)
+                old_id = match.group(2)
+                new_id = old_to_new.get(old_id, old_id)
+                return f"{prefix}{new_id}"
+            return re.sub(r'(action_outputs?\.action_output_?)(\d+)', replace_ref, obj)
+        elif isinstance(obj, dict):
+            return {k: remap_action_output_refs(v) for k, v in obj.items()}
+        elif isinstance(obj, list):
+            return [remap_action_output_refs(item) for item in obj]
+        else:
+            return obj
+
+    renumbered = remap_action_output_refs(renumbered)
+
+    return renumbered, new_start_id, new_next_available
+
+
+def restore_flow(
+    backup: Union[str, Path, dict],
+    flow_id: Optional[str] = None,
+    name: Optional[str] = None,
+    token: Optional[str] = None,
+    client: Optional[HubSpotClient] = None,
+    dry_run: bool = False,
+) -> Optional[dict]:
+    """
+    Restore a HubSpot flow from a backup.
+
+    Args:
+        backup: Path to backup JSON file, or backup dict.
+        flow_id: Target flow ID. Defaults to ID in backup.
+        name: Override flow name. Defaults to name in backup.
+        token: HubSpot token. Falls back to HUBSPOT_AUTOMATION_TOKEN env var.
+        client: Pre-configured HubSpotClient instance.
+        dry_run: If True, return payload without making API call.
+
+    Returns:
+        Updated flow dict, or payload dict if dry_run=True.
+    """
+    if client is None:
+        client = HubSpotClient(token=token)
+
+    if isinstance(backup, (str, Path)):
+        backup_path = Path(backup)
+        if not backup_path.is_file():
+            raise FileNotFoundError(f"Backup file not found: {backup_path}")
+        with backup_path.open("r", encoding="utf-8") as f:
+            backup = json.load(f)
+
+    target_flow_id = flow_id or backup.get("id")
+    if not target_flow_id:
+        raise ValueError("flow_id not provided and not present in backup.")
+    target_flow_id = str(target_flow_id)
+
+    current = client.get_flow(target_flow_id)
+
+    current_revision = current.get("revisionId")
+    current_type = current.get("type")
+    current_name = current.get("name")
+    current_next_available = current.get("nextAvailableActionId", "1")
+
+    backup_actions = backup.get("actions", [])
+    backup_start_id = backup.get("startActionId")
+
+    renumbered_actions, new_start_id, new_next_available = renumber_actions(
+        backup_actions, backup_start_id, current_next_available
+    )
+
+    ds_mapping = build_datasource_mapping(
+        backup.get("dataSources", []),
+        current.get("dataSources", [])
+    )
+    if ds_mapping:
+        renumbered_actions = remap_fetched_objects(renumbered_actions, ds_mapping)
+
+    body = {
+        "type": current_type,
+        "revisionId": current_revision,
+        "objectTypeId": current.get("objectTypeId"),
+        "flowType": current.get("flowType"),
+        "actions": renumbered_actions,
+        "startActionId": new_start_id,
+        "nextAvailableActionId": new_next_available,
+    }
+
+    if name:
+        body["name"] = name
+    elif "name" in backup:
+        body["name"] = backup["name"]
+    else:
+        body["name"] = current_name
+
+    body["isEnabled"] = False
+
+    keys_to_copy = [
+        "description",
+        "customProperties",
+        "enrollmentCriteria",
+        "blockedDates",
+        "timeWindows",
+    ]
+    for key in keys_to_copy:
+        if key in backup:
+            body[key] = backup[key]
+
+    if dry_run:
+        return body
+
+    return client.update_flow(target_flow_id, body)
+
+
+def main() -> None:
+    """CLI entry point for workflows-restore command."""
+    parser = argparse.ArgumentParser(
+        description="Restore a HubSpot automation flow from a backup JSON file."
+    )
+    parser.add_argument("backup_path", help="Path to the backup JSON file")
+    parser.add_argument("--flow-id", dest="flow_id", help="Override target flowId")
+    parser.add_argument("--name", dest="name", help="Override flow name")
+    parser.add_argument("--dry", action="store_true", help="Show payload without sending")
+
+    args = parser.parse_args()
+
+    backup_file = Path(args.backup_path)
+    if not backup_file.is_file():
+        print(f"Backup file not found: {backup_file}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        client = HubSpotClient()
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    with backup_file.open("r", encoding="utf-8") as f:
+        backup = json.load(f)
+
+    flow_id = args.flow_id or backup.get("id")
+    if not flow_id:
+        print("flowId not provided and not present in backup JSON.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Using flowId: {flow_id}")
+    print(f"Backup file: {backup_file}")
+
+    current = client.get_flow(str(flow_id))
+    print("\nCurrent flow summary:")
+    print(f"  name: {current.get('name')}")
+    print(f"  revisionId: {current.get('revisionId')}")
+    print(f"  type: {current.get('type')}")
+
+    print("\nBackup summary:")
+    print(f"  name: {backup.get('name')}")
+    print(f"  actions: {len(backup.get('actions', []))}")
+
+    if args.dry:
+        result = restore_flow(backup, flow_id=args.flow_id, name=args.name, client=client, dry_run=True)
+        print("\n[DRY RUN] Would send PUT /automation/v4/flows/{flowId} with body:")
+        print(json.dumps(result, indent=2))
+        return
+
+    print("\nSending PUT to update flow...")
+    updated = restore_flow(backup, flow_id=args.flow_id, name=args.name, client=client)
+
+    print("\nUpdate complete. New flow summary:")
+    print(f"  id: {updated.get('id')}")
+    print(f"  name: {updated.get('name')}")
+    print(f"  revisionId: {updated.get('revisionId')}")
+    print(f"  isEnabled: {updated.get('isEnabled')}")
+
+
+if __name__ == "__main__":
+    main()

ft_hubspot_workflow_backup-0.1.4.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: ft-hubspot-workflow-backup
+Version: 0.1.4
+Summary: Backup and restore HubSpot Automation (v4) workflows
+Project-URL: Homepage, https://github.com/nflore/ft-hubspot-workflow-backup
+Project-URL: Repository, https://github.com/nflore/ft-hubspot-workflow-backup
+Project-URL: Issues, https://github.com/nflore/ft-hubspot-workflow-backup/issues
+Project-URL: Changelog, https://github.com/nflore/ft-hubspot-workflow-backup/releases
+Author: Nathan Flore
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25.0
+Description-Content-Type: text/markdown
+
+# HubSpot Workflow Backup & Restore
+
+[![PyPI](https://img.shields.io/pypi/v/ft-hubspot-workflow-backup)](https://pypi.org/project/ft-hubspot-workflow-backup/)
+
+Backup and restore HubSpot Automation (v4) workflows. There is NO confirmation once you request a restore, it will just overwrite the workflow.
+
+## Installation
+
+```bash
+# From PyPI
+pip install ft-hubspot-workflow-backup
+
+# Or with uv
+uv pip install ft-hubspot-workflow-backup
+
+# Or add to pyproject.toml
+# dependencies = ["ft-hubspot-workflow-backup>=0.1.0"]
+```
+
+## Requirements
+
+- Python 3.9+ (recommended with [`uv`](https://github.com/astral-sh/uv))
+- HubSpot private app token with `automation` read/write scope
+- Environment variable `HUBSPOT_AUTOMATION_TOKEN` set to your token
+
+## Usage
+
+### Backup all workflows
+
+```bash
+uv run workflows-backup
+```
+
+Creates `snapshots/` with:
+- One JSON file per workflow: `<slugified-name>.json`
+- An `_index.json` listing all backed up flows with SHA-256 hashes for verification
+
+Options:
+- `-o, --output-dir <path>`: Custom output directory (default: `./snapshots/`)
+- `--use-date-dir`: Create a timestamped subdirectory (e.g., `snapshots/2026_01_20_123456/`)
+- `--use-date-prefix`: Prefix filenames with timestamp (e.g., `2026_01_20_123456_workflow-name.json`)
+- `--verify`: Verify backup integrity immediately after completion
+
+Example with date organization:
+```bash
+uv run workflows-backup --use-date-dir --use-date-prefix
+```
+
+### Restore a workflow
+
+```bash
+uv run workflows-restore <backup-file> [--flow-id <id>] [--name "<name>"] [--dry]
+```
+
+Options:
+- `--flow-id`: Target flow ID (defaults to ID in backup)
+- `--name`: Override flow name
+- `--dry`: Preview payload without sending
+
+Example:
+```bash
+uv run workflows-restore snapshots/<workflow-name>.json --dry
+```
+
+### As a Python module
+
+```python
+from ft_hubspot_workflow_backup import backup_all_flows, restore_flow, verify_backups, HubSpotClient
+
+# Backup (uses HUBSPOT_AUTOMATION_TOKEN env var)
+snapshot_dir = backup_all_flows()
+
+# With date-based organization
+snapshot_dir = backup_all_flows(use_date_dir=True, use_date_prefix=True)
+
+# Or with explicit token and custom output
+client = HubSpotClient(token="your-token")
+snapshot_dir = backup_all_flows(client=client, output_dir="./my-snapshots")
+
+# Verify backups
+results = verify_backups("./my-snapshots")
+print(f"Verified: {len(results['verified'])}, Failed: {len(results['failed'])}")
+
+# Restore
+restore_flow("path/to/backup.json", flow_id="123456")
+```
+
+## Cryptographic Verification
+
+Each backup includes SHA-256 hashes in `_index.json` to cryptographically verify workflow integrity. This allows you to detect if a workflow file has been modified since backup.
+
+### Verify a single workflow
+
+```bash
+# Compare the stored hash with the actual file hash
+shasum -a 256 snapshots/<workflow-name>.json
+# Then compare with the hash in _index.json
+```
+
+### Verify all workflows (bash)
+
+```bash
+cd snapshots
+for file in *.json; do
+  [[ "$file" == "_index.json" ]] && continue
+  expected=$(jq -r ".flows[] | select(.filename == \"$file\") | .hash" _index.json)
+  actual=$(shasum -a 256 "$file" | cut -d' ' -f1)
+  if [[ "$expected" == "$actual" ]]; then
+    echo "✓ $file"
+  else
+    echo "✗ $file (hash mismatch)"
+  fi
+done
+```
+
+### Verify programmatically (Python)
+
+```python
+from ft_hubspot_workflow_backup import verify_backups
+
+results = verify_backups("snapshots")
+print(f"Verified: {len(results['verified'])}, Failed: {len(results['failed'])}")
+
+if results["failed"]:
+    print("Hash mismatches:", results["failed"])
+if results["missing"]:
+    print("Missing files:", results["missing"])
+```
+
+## Notes
+
+- Secrets (`secretNames`) are not backed up; only their names are referenced.
+- Flows reference HubSpot assets (pipelines, stages, templates) by ID. Restores assume those IDs are still valid.
+- Restored flows are always set to DISABLED. Enable manually after verifying.
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Nathan Flore / Flore Technologies, LLC.
+
+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.

ft_hubspot_workflow_backup-0.1.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+ft_hubspot_workflow_backup/__init__.py,sha256=G_Je8pEEMa7b2UWkWYhuM3Jp3zrDeH86-FbGs-UdzpE,306
+ft_hubspot_workflow_backup/backup.py,sha256=h17iDp-ehV28sb-g22cm0GC-wonQxwbFaS1nITcmAeE,9113
+ft_hubspot_workflow_backup/client.py,sha256=bXTd3wy6UW_d9h_WF_SF4QpemeBSvOXJBiJH9qKlS4o,2472
+ft_hubspot_workflow_backup/restore.py,sha256=MAFXe3L9tUPrZyNweWItIiPFWL4uhNtAPLteh4REq8A,11246
+ft_hubspot_workflow_backup-0.1.4.dist-info/METADATA,sha256=3Es2nEMZer5nqvhMu4Jeo25WLXwzOgjF2lOsBf-YkDw,5629
+ft_hubspot_workflow_backup-0.1.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ft_hubspot_workflow_backup-0.1.4.dist-info/entry_points.txt,sha256=vn3sTFGna_GR_ue_NvSIm1wHZEqnPkSNFIGNm-xvYRY,136
+ft_hubspot_workflow_backup-0.1.4.dist-info/licenses/LICENSE,sha256=rI0DW87f-vx36nZsWmDypJXzsisR5242gMfDCEtJxiU,1096
+ft_hubspot_workflow_backup-0.1.4.dist-info/RECORD,,

ft_hubspot_workflow_backup-0.1.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ft_hubspot_workflow_backup-0.1.4.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+workflows-backup = ft_hubspot_workflow_backup.backup:main
+workflows-restore = ft_hubspot_workflow_backup.restore:main

ft_hubspot_workflow_backup-0.1.4.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nathan Flore / Flore Technologies, LLC.
+
+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.