guzli-cli 0.2.0__py3-none-any.whl

guzli/commands/campaigns.py

@@ -0,0 +1,571 @@
+from __future__ import annotations
+
+import argparse
+import uuid
+from typing import Dict, Mapping
+
+from guzli.commands.campaign_launch import add_campaign_launch_parser
+from guzli.commands.common import parse_bool_flag as _parse_bool_flag
+from guzli.errors import ConfigError, ValidationError
+from guzli.runtime import RuntimeContext
+from guzli.validators import parse_json, parse_json_or_file, require_non_empty
+
+
+def handle_campaign_list(context: RuntimeContext, args: argparse.Namespace) -> None:
+    params: Dict[str, object] = {}
+    if args.status:
+        params["status"] = args.status
+    if args.search:
+        params["search"] = args.search
+    if args.limit:
+        params["limit"] = args.limit
+    payload = context.campaigns.list_campaigns(params)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_get(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    payload = context.campaigns.get_campaign(campaign_id)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_preview(context: RuntimeContext, args: argparse.Namespace) -> None:
+    body = parse_json_or_file(args.config_json, args.config_file, "campaign preview")
+    if not isinstance(body, Mapping):
+        raise ValidationError("campaign preview requires a JSON object")
+    context.renderer.print_json(context.campaigns.preview_campaign(dict(body)))
+
+
+def handle_campaign_create(context: RuntimeContext, args: argparse.Namespace) -> None:
+    body = parse_json_or_file(args.config_json, args.config_file, "campaign config")
+    if not isinstance(body, Mapping):
+        raise ValidationError("campaign config must be a JSON object")
+    body = dict(body)
+    if args.name:
+        body["name"] = args.name
+    if "name" not in body or not str(body.get("name", "")).strip():
+        raise ValidationError('name is required (pass --name or include "name" in the config)')
+    if not str(body.get("organization_id", "")).strip():
+        if not context.organization_id:
+            raise ConfigError(
+                "organization_id is required for campaign create. "
+                "Set it via `guzli auth login --organization-id …` or include it in the config."
+            )
+        body["organization_id"] = context.organization_id
+    if not str(body.get("agent_id", "")).strip() and context.agent_id:
+        body["agent_id"] = context.agent_id
+    payload = context.campaigns.create_campaign(body)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_update(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    body = parse_json_or_file(args.config_json, args.config_file, "campaign update")
+    if not isinstance(body, Mapping):
+        raise ValidationError("campaign update must be a JSON object (matches CampaignUpdate)")
+    payload = context.campaigns.update_campaign(campaign_id, dict(body))
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_readiness(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    payload = context.campaigns.get_readiness(campaign_id)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_activate(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    payload = context.campaigns.activate_campaign(campaign_id)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_pause(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    payload = context.campaigns.pause_campaign(campaign_id)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_archive(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    context.renderer.print_json(context.campaigns.archive_campaign(campaign_id))
+
+
+def handle_campaign_run(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    body: Dict[str, object] = {}
+    metadata = parse_json(args.metadata, "metadata")
+    if metadata is not None:
+        if not isinstance(metadata, Mapping):
+            raise ValidationError("metadata must be a JSON object")
+        body["metadata"] = dict(metadata)
+    audience = parse_json(args.audience_override, "audience_override")
+    if audience is not None:
+        if not isinstance(audience, Mapping):
+            raise ValidationError("audience_override must be a JSON object")
+        body["audience_override"] = dict(audience)
+    payload = context.campaigns.trigger_manual_run(campaign_id, body)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_audience_import(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    body = parse_json_or_file(args.config_json, args.config_file, "audience import")
+    if body is None:
+        raise ValidationError("audience import requires --config-json or --config-file")
+    # Accept either a bare list of items or a full import request object.
+    if isinstance(body, list):
+        request: Dict[str, object] = {"items": list(body)}
+    elif isinstance(body, Mapping):
+        request = dict(body)
+    else:
+        raise ValidationError(
+            'audience import body must be a JSON array of items, or an object with an "items" array'
+        )
+    items = request.get("items")
+    if not isinstance(items, list) or not items:
+        raise ValidationError('audience import requires a non-empty "items" array')
+    if args.operation_id:
+        request["operation_id"] = args.operation_id
+    if not str(request.get("operation_id", "") or "").strip():
+        request["operation_id"] = f"cli-import-{uuid.uuid4().hex[:16]}"
+    if args.no_update_existing:
+        request["update_existing"] = False
+    elif "update_existing" not in request:
+        request["update_existing"] = True
+    payload = context.campaigns.import_audience_members(campaign_id, request)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_audience_list(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    params: Dict[str, object] = {}
+    if args.lifecycle_status:
+        params["lifecycle_status"] = args.lifecycle_status
+    if args.phone:
+        params["target_phone_e164"] = args.phone
+    if args.cursor:
+        params["cursor"] = args.cursor
+    if args.limit:
+        params["limit"] = args.limit
+    payload = context.campaigns.list_audience_members(campaign_id, params)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_audience_queue_eligible(
+    context: RuntimeContext, args: argparse.Namespace
+) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    body: Dict[str, object] = {"operation_id": args.operation_id or str(uuid.uuid4())}
+    if args.limit:
+        body["limit"] = args.limit
+    if args.include_line_type_lookup:
+        body["include_line_type_lookup"] = True
+    payload = context.campaigns.queue_eligible_audience_members(campaign_id, body)
+    context.renderer.print_json(payload)
+
+
+def handle_compliance_get(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    payload = context.campaigns.get_compliance(campaign_id)
+    context.renderer.print_json(payload)
+
+
+_COMPLIANCE_DEFAULTS: Dict[str, object] = {
+    "policy_region": "US",
+    "compliance_mode": "enforced",
+    "call_purpose": "support",
+    "recipient_type": "consumer",
+}
+
+
+def _apply_compliance_flags(body: Dict[str, object], args: argparse.Namespace) -> Dict[str, object]:
+    if getattr(args, "compliance_mode", None):
+        body["compliance_mode"] = args.compliance_mode
+    if getattr(args, "ai_notice", None) is not None:
+        body["automated_voice_notice_required"] = args.ai_notice
+    if getattr(args, "opt_out", None) is not None:
+        body["spoken_opt_out_enabled"] = args.opt_out
+    if getattr(args, "recording_notice", None) is not None:
+        body["recording_notice_required"] = args.recording_notice
+    return body
+
+
+def handle_compliance_set(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    base = parse_json_or_file(args.config_json, args.config_file, "compliance settings")
+    if base is None:
+        body: Dict[str, object] = dict(_COMPLIANCE_DEFAULTS)
+    elif isinstance(base, Mapping):
+        body = dict(base)
+    else:
+        raise ValidationError(
+            "compliance settings must be a JSON object (CampaignComplianceSettings)"
+        )
+    _apply_compliance_flags(body, args)
+    payload = context.campaigns.save_compliance(campaign_id, body)
+    context.renderer.print_json(payload)
+
+
+def handle_compliance_approve(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    payload = context.campaigns.approve_compliance(campaign_id)
+    context.renderer.print_json(payload)
+
+
+def handle_compliance_disable(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    payload = context.campaigns.disable_compliance(campaign_id)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_runs_list(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    params: Dict[str, object] = {}
+    if args.status:
+        params["status"] = args.status
+    if args.cursor:
+        params["cursor"] = args.cursor
+    if args.limit:
+        params["limit"] = args.limit
+    payload = context.campaigns.list_runs(campaign_id, params)
+    context.renderer.print_json(payload)
+
+
+def handle_campaign_run_get(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    run_id = require_non_empty(args.run_id, "run_id")
+    context.renderer.print_json(context.campaigns.get_run(campaign_id, run_id))
+
+
+def handle_campaign_run_cancel(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    run_id = require_non_empty(args.run_id, "run_id")
+    context.renderer.print_json(context.campaigns.cancel_run(campaign_id, run_id))
+
+
+def handle_campaign_results_list(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    params: Dict[str, object] = {}
+    for name in ("status", "campaign_run_id", "schema_name", "limit"):
+        value = getattr(args, name, None)
+        if value is not None:
+            params[name] = value
+    context.renderer.print_json(context.campaigns.list_results(campaign_id, params))
+
+
+def handle_campaign_result_get(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    result_id = require_non_empty(args.result_id, "result_id")
+    context.renderer.print_json(context.campaigns.get_result(campaign_id, result_id))
+
+
+def _compliance_check_body(args: argparse.Namespace, label: str) -> Dict[str, object]:
+    body = parse_json_or_file(args.config_json, args.config_file, label)
+    if body is None:
+        return {}
+    if not isinstance(body, Mapping):
+        raise ValidationError(f"{label} must be a JSON object")
+    return dict(body)
+
+
+def handle_compliance_preview(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    body = _compliance_check_body(args, "compliance preview")
+    context.renderer.print_json(context.campaigns.preview_compliance(campaign_id, body))
+
+
+def handle_compliance_preflight(context: RuntimeContext, args: argparse.Namespace) -> None:
+    campaign_id = require_non_empty(args.campaign_id, "campaign_id")
+    body = _compliance_check_body(args, "compliance preflight")
+    context.renderer.print_json(context.campaigns.preflight_compliance(campaign_id, body))
+
+
+def _add_campaign_list(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("list", help="List campaigns")
+    parser.add_argument(
+        "--status", help="Filter by status (DRAFT, ACTIVE, PAUSED, ARCHIVED, COMPLETED)"
+    )
+    parser.add_argument("--search", help="Substring search on campaign name")
+    parser.add_argument("--limit", type=int)
+    parser.set_defaults(handler=handle_campaign_list)
+
+
+def _add_campaign_get(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("get", help="Fetch a campaign definition")
+    parser.add_argument("campaign_id")
+    parser.set_defaults(handler=handle_campaign_get)
+
+
+def _add_campaign_preview(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("preview", help="Validate and preview a campaign definition")
+    parser.add_argument("--config-json", dest="config_json", help="Inline JSON body")
+    parser.add_argument("--config-file", dest="config_file", help="Path to JSON body")
+    parser.set_defaults(handler=handle_campaign_preview)
+
+
+def _add_campaign_create(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "create",
+        help="Create a campaign from JSON (matches CampaignCreate schema)",
+    )
+    parser.add_argument("--name", help="Convenience override for the campaign name")
+    parser.add_argument("--config-json", dest="config_json", help="Inline JSON body")
+    parser.add_argument("--config-file", dest="config_file", help="Path to JSON file with body")
+    parser.set_defaults(handler=handle_campaign_create)
+
+
+def _add_campaign_update(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("update", help="Patch a campaign (partial CampaignUpdate body)")
+    parser.add_argument("campaign_id")
+    parser.add_argument("--config-json", dest="config_json", help="Inline JSON partial body")
+    parser.add_argument(
+        "--config-file", dest="config_file", help="Path to JSON file with partial body"
+    )
+    parser.set_defaults(handler=handle_campaign_update)
+
+
+def _add_campaign_readiness(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("readiness", help="Check whether a campaign is ready to activate")
+    parser.add_argument("campaign_id")
+    parser.set_defaults(handler=handle_campaign_readiness)
+
+
+def _add_campaign_activate(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("activate", help="Transition a campaign to ACTIVE")
+    parser.add_argument("campaign_id")
+    parser.set_defaults(handler=handle_campaign_activate)
+
+
+def _add_campaign_pause(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("pause", help="Pause a running campaign")
+    parser.add_argument("campaign_id")
+    parser.set_defaults(handler=handle_campaign_pause)
+
+
+def _add_campaign_archive(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("archive", help="Archive a campaign")
+    parser.add_argument("campaign_id")
+    parser.set_defaults(handler=handle_campaign_archive)
+
+
+def _add_campaign_run(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("run", help="Trigger a manual outbound run for a campaign")
+    parser.add_argument("campaign_id")
+    parser.add_argument("--metadata", help="Inline JSON object passed as run metadata")
+    parser.add_argument(
+        "--audience-override",
+        dest="audience_override",
+        help="Inline JSON CampaignAudienceDefinition to override the campaign audience for this run",
+    )
+    parser.set_defaults(handler=handle_campaign_run)
+
+
+def _add_campaign_audience_import(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "import",
+        help="Import audience members (supports per-target campaign_metadata)",
+    )
+    parser.add_argument("campaign_id")
+    parser.add_argument(
+        "--config-json",
+        dest="config_json",
+        help="Inline JSON: an array of import items, or {operation_id, update_existing, items[]}",
+    )
+    parser.add_argument(
+        "--config-file",
+        dest="config_file",
+        help="Path to a JSON file with the same shape as --config-json",
+    )
+    parser.add_argument(
+        "--operation-id",
+        dest="operation_id",
+        help="Idempotency batch id (re-using one reprocesses that batch); generated if omitted",
+    )
+    parser.add_argument(
+        "--no-update-existing",
+        dest="no_update_existing",
+        action="store_true",
+        help="Preserve existing members instead of updating pending ones (default: update)",
+    )
+    parser.set_defaults(handler=handle_campaign_audience_import)
+
+
+def _add_campaign_audience_list(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("list", help="List a campaign's audience members")
+    parser.add_argument("campaign_id")
+    parser.add_argument("--lifecycle-status", dest="lifecycle_status")
+    parser.add_argument("--phone", help="Filter by target phone (E.164)")
+    parser.add_argument("--cursor")
+    parser.add_argument("--limit", type=int)
+    parser.set_defaults(handler=handle_campaign_audience_list)
+
+
+def _add_campaign_audience_queue_eligible(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "queue-eligible",
+        help="Queue eligible imported members for dialing — this is what actually dials members WITH their campaign_metadata (campaign must be active)",
+    )
+    parser.add_argument("campaign_id")
+    parser.add_argument(
+        "--limit", type=int, help="Max members to queue this call (1-200, default 50)"
+    )
+    parser.add_argument(
+        "--operation-id", dest="operation_id", help="Idempotency id (generated if omitted)"
+    )
+    parser.add_argument(
+        "--include-line-type-lookup",
+        dest="include_line_type_lookup",
+        action="store_true",
+        help="Run a line-type lookup on each number before queueing",
+    )
+    parser.set_defaults(handler=handle_campaign_audience_queue_eligible)
+
+
+def _add_compliance_get(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("get", help="Fetch campaign compliance settings")
+    parser.add_argument("campaign_id")
+    parser.set_defaults(handler=handle_compliance_get)
+
+
+def _add_compliance_set(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "set",
+        help="Save compliance settings. Without --config-* a sensible default body is used; shorthand flags override.",
+    )
+    parser.add_argument("campaign_id")
+    parser.add_argument("--config-json", dest="config_json", help="Inline JSON body")
+    parser.add_argument("--config-file", dest="config_file", help="Path to JSON file with body")
+    parser.add_argument(
+        "--compliance-mode",
+        dest="compliance_mode",
+        choices=["enforced", "advisory"],
+        help="Set compliance_mode",
+    )
+    parser.add_argument(
+        "--ai-notice",
+        dest="ai_notice",
+        type=_parse_bool_flag,
+        metavar="on|off",
+        help="Toggle automated_voice_notice_required",
+    )
+    parser.add_argument(
+        "--opt-out",
+        dest="opt_out",
+        type=_parse_bool_flag,
+        metavar="on|off",
+        help="Toggle spoken_opt_out_enabled",
+    )
+    parser.add_argument(
+        "--recording-notice",
+        dest="recording_notice",
+        type=_parse_bool_flag,
+        metavar="on|off",
+        help="Toggle recording_notice_required",
+    )
+    parser.set_defaults(handler=handle_compliance_set)
+
+
+def _add_compliance_approve(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("approve", help="Approve compliance settings (required before dialing)")
+    parser.add_argument("campaign_id")
+    parser.set_defaults(handler=handle_compliance_approve)
+
+
+def _add_compliance_disable(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("disable", help="Disable compliance enforcement for a campaign")
+    parser.add_argument("campaign_id")
+    parser.set_defaults(handler=handle_compliance_disable)
+
+
+def _add_compliance_preview(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("preview", help="Preview compliance decisions without dialing")
+    parser.add_argument("campaign_id")
+    parser.add_argument("--config-json", dest="config_json", help="Inline preview request")
+    parser.add_argument("--config-file", dest="config_file", help="Path to preview request")
+    parser.set_defaults(handler=handle_compliance_preview)
+
+
+def _add_compliance_preflight(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("preflight", help="Run the campaign compliance preflight")
+    parser.add_argument("campaign_id")
+    parser.add_argument("--config-json", dest="config_json", help="Inline preflight request")
+    parser.add_argument("--config-file", dest="config_file", help="Path to preflight request")
+    parser.set_defaults(handler=handle_compliance_preflight)
+
+
+def _add_campaign_runs_list(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("runs", help="List runs for a campaign")
+    parser.add_argument("campaign_id")
+    parser.add_argument("--status")
+    parser.add_argument("--cursor")
+    parser.add_argument("--limit", type=int)
+    parser.set_defaults(handler=handle_campaign_runs_list)
+
+
+def _add_campaign_run_get(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("run-get", help="Fetch a campaign run")
+    parser.add_argument("campaign_id")
+    parser.add_argument("run_id")
+    parser.set_defaults(handler=handle_campaign_run_get)
+
+
+def _add_campaign_run_cancel(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("run-cancel", help="Cancel a campaign run")
+    parser.add_argument("campaign_id")
+    parser.add_argument("run_id")
+    parser.set_defaults(handler=handle_campaign_run_cancel)
+
+
+def _add_campaign_results(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("results", help="Structured post-call extraction results")
+    results_sub = parser.add_subparsers(dest="results_command", required=True)
+    list_parser = results_sub.add_parser("list", help="List campaign results")
+    list_parser.add_argument("campaign_id")
+    list_parser.add_argument("--status")
+    list_parser.add_argument("--campaign-run-id", dest="campaign_run_id")
+    list_parser.add_argument("--schema-name", dest="schema_name")
+    list_parser.add_argument("--limit", type=int)
+    list_parser.set_defaults(handler=handle_campaign_results_list)
+    get_parser = results_sub.add_parser("get", help="Fetch one campaign result")
+    get_parser.add_argument("campaign_id")
+    get_parser.add_argument("result_id")
+    get_parser.set_defaults(handler=handle_campaign_result_get)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    campaigns = subparsers.add_parser("campaigns", help="Voice campaign operations")
+    camp_sub = campaigns.add_subparsers(dest="campaigns_command", required=True)
+    _add_campaign_list(camp_sub)
+    _add_campaign_get(camp_sub)
+    _add_campaign_preview(camp_sub)
+    _add_campaign_create(camp_sub)
+    _add_campaign_update(camp_sub)
+    _add_campaign_readiness(camp_sub)
+    _add_campaign_activate(camp_sub)
+    _add_campaign_pause(camp_sub)
+    _add_campaign_archive(camp_sub)
+    _add_campaign_run(camp_sub)
+    _add_campaign_runs_list(camp_sub)
+    _add_campaign_run_get(camp_sub)
+    _add_campaign_run_cancel(camp_sub)
+    _add_campaign_results(camp_sub)
+    add_campaign_launch_parser(camp_sub)
+
+    add_campaign_launch_parser(subparsers, command_name="call")
+
+    compliance = camp_sub.add_parser("compliance", help="Campaign compliance settings")
+    comp_sub = compliance.add_subparsers(dest="compliance_command", required=True)
+    _add_compliance_get(comp_sub)
+    _add_compliance_set(comp_sub)
+    _add_compliance_approve(comp_sub)
+    _add_compliance_disable(comp_sub)
+    _add_compliance_preview(comp_sub)
+    _add_compliance_preflight(comp_sub)
+
+    audience = camp_sub.add_parser(
+        "audience", help="Campaign audience members (import with per-target metadata)"
+    )
+    aud_sub = audience.add_subparsers(dest="audience_command", required=True)
+    _add_campaign_audience_import(aud_sub)
+    _add_campaign_audience_list(aud_sub)
+    _add_campaign_audience_queue_eligible(aud_sub)

guzli/commands/common.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from guzli.errors import ValidationError
+from guzli.runtime import RuntimeContext
+from guzli.validators import parse_bool
+
+
+def add_json_flag(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+
+
+def parse_bool_flag(value: str) -> bool:
+    parsed = parse_bool(value, "boolean flag")
+    if parsed is None:
+        raise ValidationError("Boolean flag is required")
+    return parsed
+
+
+def require_org_id(context: RuntimeContext, args: argparse.Namespace) -> str:
+    organization_id = getattr(args, "organization_id_arg", None) or context.organization_id
+    if not organization_id:
+        raise ValidationError(
+            "organization-id required: pass --org / --organization-id, set "
+            "GUZLI_ORGANIZATION_ID, or store it in your profile (guzli auth use ...)."
+        )
+    return organization_id
+
+
+def add_org_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--org",
+        "--organization-id",
+        dest="organization_id_arg",
+        help="Organization UUID (falls back to GUZLI_ORGANIZATION_ID / active profile)",
+    )
+
+
+def print_error(message: str) -> None:
+    print(message, file=sys.stderr)