feat(clickup): add flyteplugins-clickup (#1516)

Part of the webhook plugin stack. Requires #1512
(`flyteplugins-webhooks-core`), which is this PR's base — the diff here
is just this package.

Receive ClickUp webhooks in Flyte.

## What it implements

The `Provider` contract from core: which environment variable holds the
secret, how to verify a delivery, how to parse one into a
`WebhookEvent`, plus typed constants for every event ClickUp sends.

**Verification:** HMAC-SHA256 over the raw body (`X-Clickup-Signature`).

The list id sits at the top level on list-scoped events and on the
nested task for task-scoped ones; the parser reads both, or a `scopes`
allowlist cannot attribute task events at all.

## Conformance

Runs the shared `assert_provider_conforms`, which replays this plugin's
`SAMPLE_DELIVERY` — a real ClickUp payload — through `verify` and
`parse` rather than trusting them to agree with each other. It also
asserts the verifier returns False rather than raising on a hostile
header, that event constants render as wire values rather than enum
names, and that the sample parses to something the constants actually
spell.

5 tests. `make fmt`, `make mypy`, `make ty`, ruff, and codespell pass.

## What it does not do

Call the ClickUp API. Use `httpx` — ClickUp ships no Python SDK and its
API is a handful of REST calls directly from your tasks — the recipes
are in the examples PR at the end of this stack. This plugin owns only
the part that is Flyte's: authenticating an inbound delivery and turning
it into a run.

---------

Signed-off-by: Niels Bantilan <niels.bantilan@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cosmicBboy

examples/external_saas_integrations/README.md

@@ -0,0 +1,65 @@
+# External SaaS integrations
+
+Recipes for driving GitHub, Slack, Linear, ClickUp, and Jira from Flyte.
+
+There is deliberately **no Flyte client plugin** for these products. Each vendor
+already ships (or the community maintains) a Python client that is tested
+against the live API by people who get deprecation notices first, and a task is
+just a function — so calling `PyGithub` or `slack_sdk` from a task needs nothing
+in between. A wrapper here would only add a surface to keep in sync with someone
+else's release calendar.
+
+What *is* Flyte's job, and what these examples use from it:
+
+- **`flyte.extras.webhooks`** — ships with flyte: one app that authenticates an inbound
+  delivery with the product's own scheme, normalizes it into a single event
+  model, and launches a run once per event key with `idempotent_run`.
+- **`flyteplugins-webhooks-<product>`** — one small package per product,
+  contributing just its verification and parsing.
+- **`flyte.new_condition`** — park a run on a human decision, with a typed
+  payload coming back. `flyteplugins.github.review_pr` wraps this into a PR
+  review gate, which is the one place a plugin beats calling the vendor SDK:
+  the condition is Flyte's, not GitHub's.
+
+## The examples
+
+| File | What it shows | Client |
+| --- | --- | --- |
+| `webhook_receiver.py` | One app receiving from all five products, launching a task per event | `flyteplugins-webhooks-*` |
+| `github_pr_review_gate.py` | Human-gated merge, on `flyteplugins.github.review_pr` | plugin + `PyGithub` |
+| `github_triage_pr.py` | Label, comment, and report a check run | `PyGithub` |
+| `slack_notify.py` | Post, thread, react, answer a mention | `slack_sdk` |
+| `linear_triage_issue.py` | Query a backlog and comment, over GraphQL | `gql` |
+| `clickup_manage_ticket.py` | Open and close tickets, with a status pre-check | `httpx` |
+| `jira_manage_ticket.py` | Open, transition, and search issues | `jira` |
+
+Linear and ClickUp ship no official Python SDK. Linear's API is a single GraphQL
+endpoint, so `gql` is the maintained client; ClickUp's is a handful of REST
+calls, so `httpx` directly beats a thin third-party wrapper.
+
+## Putting it together
+
+The receiver and the tasks are separate on purpose: the app authenticates and
+dispatches, the tasks do the work and can be run, tested, and retried on their
+own.
+
+```bash
+# 1. deploy the tasks the receiver will launch
+flyte deploy examples/external_saas_integrations/github_triage_pr.py env
+flyte deploy examples/external_saas_integrations/slack_notify.py env
+
+# 2. run one directly, to confirm credentials work before any webhook is involved
+flyte run examples/external_saas_integrations/github_triage_pr.py triage_pr \
+    --repo <owner>/<repo> --number <pr>
+
+# 3. deploy the receiver and point each provider at the URL its dashboard shows
+python examples/external_saas_integrations/webhook_receiver.py
+```
+
+Task names are qualified by their environment when deployed — `triage_pr` in
+`github_triage_pr.py` becomes `github-triage.triage_pr`, which is what the
+receiver looks up. That qualifier is also what keeps the two `triage_issue`
+tasks here (Linear's and Jira's) from colliding.
+
+`plugins/webhooks/README.md` has the full end-to-end testing guide, including
+how to wire up each provider and what to check at every step.

examples/external_saas_integrations/clickup_manage_ticket.py

@@ -0,0 +1,90 @@
+"""Read and write ClickUp from tasks, with `httpx` against its REST v2 API.
+
+ClickUp ships no official Python SDK and the community ones are thin and
+sporadically maintained, so this calls the REST API directly with `httpx`
+rather than adding a dependency that wraps four endpoints.
+
+Requirements:
+    pip install flyte httpx
+
+Setup:
+    flyte create secret CLICKUP_TOKEN --value pk_...
+
+Usage:
+    flyte run examples/external_saas_integrations/clickup_manage_ticket.py \\
+        open_ticket --list_id <list-id> --name "From Flyte"
+"""
+
+import os
+
+import flyte
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("httpx")
+
+env = flyte.TaskEnvironment(
+    name="clickup-tickets",
+    image=image,
+    secrets=[flyte.Secret("CLICKUP_TOKEN", as_env_var="CLICKUP_TOKEN")],
+)
+
+API = "https://api.clickup.com/api/v2"
+
+
+def _client():
+    import httpx
+
+    return httpx.AsyncClient(base_url=API, headers={"Authorization": os.environ["CLICKUP_TOKEN"]}, timeout=30)
+
+
+@env.task
+async def open_ticket(list_id: str, name: str, description: str = "") -> str:
+    """Create a task and return its URL."""
+    async with _client() as client:
+        response = await client.post(f"/list/{list_id}/task", json={"name": name, "description": description})
+        response.raise_for_status()
+        return response.json()["url"]
+
+
+@env.task
+async def triage_task(task_id: str) -> str:
+    """Comment on a newly created task.
+
+    This is what `webhook_receiver.py` launches for every `taskCreated`.
+    """
+    async with _client() as client:
+        task = await client.get(f"/task/{task_id}")
+        task.raise_for_status()
+        status = (task.json().get("status") or {}).get("status")
+        posted = await client.post(
+            f"/task/{task_id}/comment", json={"comment_text": f"Flyte triaged this ticket (status: {status})."}
+        )
+        posted.raise_for_status()
+    return f"triaged {task_id}"
+
+
+@env.task
+async def close_ticket(task_id: str, done_status: str = "done") -> str:
+    """Move a ticket to a Done-like status, validating it first.
+
+    ClickUp rejects transitions to statuses the ticket's list does not define,
+    with an opaque 400 — so check the list's statuses before trying.
+    """
+    async with _client() as client:
+        task = await client.get(f"/task/{task_id}")
+        task.raise_for_status()
+        list_id = (task.json().get("list") or {}).get("id")
+
+        listing = await client.get(f"/list/{list_id}")
+        listing.raise_for_status()
+        valid = [s["status"] for s in listing.json().get("statuses", [])]
+        if done_status not in valid:
+            raise ValueError(f"status {done_status!r} is not defined on list {list_id}; valid: {valid}")
+
+        updated = await client.put(f"/task/{task_id}", json={"status": done_status})
+        updated.raise_for_status()
+    return f"{task_id} -> {done_status}"
+
+
+if __name__ == "__main__":
+    flyte.init_from_config()
+    print(flyte.run(open_ticket, list_id="LIST_ID", name="Flyte test ticket").url)

examples/external_saas_integrations/github_pr_review_gate.py

@@ -0,0 +1,78 @@
+"""Human-gated PR merging: a condition carrying a JSON payload.
+
+A task collects review metadata from a pull request, embeds it as JSON in a
+markdown condition prompt, parks the run until a human answers in the Flyte UI,
+and parses the response into a typed decision. Approved PRs get merged.
+
+The gate itself is `flyteplugins.github.review_pr` — it lives in the plugin
+because `flyte.new_condition` is the part only Flyte can do. Merging is
+`PyGithub`, called directly here.
+
+Requirements:
+    pip install "flyteplugins-github[review]"
+
+Setup:
+    flyte create secret GITHUB_TOKEN --value <token-with-repo-scope>
+
+Usage:
+    flyte run examples/external_saas_integrations/github_pr_review_gate.py \\
+        gated_merge --repo octocat/hello-world --number 1
+"""
+
+import asyncio
+import os
+
+from flyteplugins.github import ReviewDecision, review_pr
+
+import flyte
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("flyteplugins-github[review]")
+
+env = flyte.TaskEnvironment(
+    name="github-review-gate",
+    image=image,
+    secrets=[flyte.Secret("GITHUB_TOKEN", as_env_var="GITHUB_TOKEN")],
+)
+
+
+def _comment(repo: str, number: int, body: str) -> None:
+    from github import Auth, Github
+
+    with Github(auth=Auth.Token(os.environ["GITHUB_TOKEN"])) as gh:
+        gh.get_repo(repo).get_issue(number).create_comment(body)
+
+
+def _merge(repo: str, number: int) -> str:
+    from github import Auth, Github
+
+    with Github(auth=Auth.Token(os.environ["GITHUB_TOKEN"])) as gh:
+        result = gh.get_repo(repo).get_pull(number).merge(merge_method="squash")
+    return f"merged {result.sha}"
+
+
+@env.task
+async def gated_merge(repo: str, number: int) -> str:
+    """Wait for a human review, then merge if approved.
+
+    The run parks at `review_pr` until someone answers the condition in the
+    Flyte UI. Pass `timeout=` to bound that wait.
+    """
+    decision: ReviewDecision = await review_pr(repo, number)
+
+    if not decision.is_approved:
+        # Post the reviewer's reasoning back to the PR before bailing out, so
+        # the decision is visible where the author is looking.
+        blockers = "\n".join(f"- `{c.path}`: {c.body}" for c in decision.blocking_comments)
+        await asyncio.to_thread(
+            _comment, repo, number, f"Review gate blocked this merge: {decision.summary}\n{blockers}"
+        )
+        return f"blocked: {decision.summary}"
+
+    # PyGithub is synchronous; keep it off the event loop.
+    return await asyncio.to_thread(_merge, repo, number)
+
+
+if __name__ == "__main__":
+    flyte.init_from_config()
+    run = flyte.with_runcontext().run(gated_merge, repo="octocat/hello-world", number=1)
+    print(run.url)

examples/external_saas_integrations/github_triage_pr.py

@@ -0,0 +1,71 @@
+"""Read and write GitHub from tasks, with PyGithub.
+
+The task the webhook receiver launches when a PR opens. There is no Flyte
+plugin between you and GitHub here — PyGithub is the maintained client, and a
+task is just a function that calls it.
+
+Requirements:
+    pip install flyte PyGithub
+
+Setup:
+    flyte create secret GITHUB_TOKEN --value <token-with-repo-scope>
+
+Usage:
+    flyte run examples/external_saas_integrations/github_triage_pr.py \\
+        triage_pr --repo octocat/hello-world --number 1
+"""
+
+import os
+
+import flyte
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("PyGithub")
+
+env = flyte.TaskEnvironment(
+    name="github-triage",
+    image=image,
+    secrets=[flyte.Secret("GITHUB_TOKEN", as_env_var="GITHUB_TOKEN")],
+)
+
+
+def _client():
+    from github import Auth, Github
+
+    return Github(auth=Auth.Token(os.environ["GITHUB_TOKEN"]))
+
+
+@env.task
+def summarize_pr(repo: str, number: int) -> str:
+    """Read a pull request and summarize what it changes."""
+    with _client() as gh:
+        pr = gh.get_repo(repo).get_pull(number)
+        lines = [f"- {f.filename} (+{f.additions}/-{f.deletions})" for f in pr.get_files()[:20]]
+        return f"{pr.title} ({pr.head.ref} -> {pr.base.ref})\n" + "\n".join(lines)
+
+
+@env.task
+def triage_pr(repo: str, number: int) -> str:
+    """Label a new PR, comment on it, and report a check run.
+
+    This is what `webhook_receiver.py` launches for every newly opened PR.
+    """
+    with _client() as gh:
+        repository = gh.get_repo(repo)
+        pr = repository.get_pull(number)
+        pr.add_to_labels("flyte-triage")
+        pr.create_issue_comment(
+            f"Flyte triage: this PR touches {pr.changed_files} files (+{pr.additions}/-{pr.deletions})."
+        )
+        repository.create_check_run(
+            name="flyte-triage",
+            head_sha=pr.head.sha,
+            status="completed",
+            conclusion="success",
+            output={"title": "flyte-triage", "summary": "Flyte triaged this pull request."},
+        )
+    return f"triaged {repo}#{number}"
+
+
+if __name__ == "__main__":
+    flyte.init_from_config()
+    print(flyte.run(triage_pr, repo="octocat/hello-world", number=1).url)

examples/external_saas_integrations/jira_manage_ticket.py

@@ -0,0 +1,91 @@
+"""Read and write Jira from tasks, with the official `jira` package.
+
+Requirements:
+    pip install flyte jira
+
+Setup:
+    flyte create secret JIRA_BASE_URL  --value https://<site>.atlassian.net
+    flyte create secret JIRA_EMAIL     --value you@example.com
+    flyte create secret JIRA_API_TOKEN --value <api-token>
+
+Usage:
+    flyte run examples/external_saas_integrations/jira_manage_ticket.py \\
+        open_ticket --project_key PROJ --summary "From Flyte"
+"""
+
+import os
+
+import flyte
+
+image = flyte.Image.from_debian_base(python_version=(3, 12)).with_pip_packages("jira")
+
+env = flyte.TaskEnvironment(
+    name="jira-tickets",
+    image=image,
+    secrets=[
+        flyte.Secret("JIRA_BASE_URL", as_env_var="JIRA_BASE_URL"),
+        flyte.Secret("JIRA_EMAIL", as_env_var="JIRA_EMAIL"),
+        flyte.Secret("JIRA_API_TOKEN", as_env_var="JIRA_API_TOKEN"),
+    ],
+)
+
+
+def _client():
+    from jira import JIRA
+
+    return JIRA(
+        server=os.environ["JIRA_BASE_URL"],
+        basic_auth=(os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"]),
+    )
+
+
+@env.task
+def open_ticket(project_key: str, summary: str, description: str = "") -> str:
+    """Create an issue and return its key."""
+    issue = _client().create_issue(
+        project=project_key, summary=summary, description=description, issuetype={"name": "Task"}
+    )
+    return issue.key
+
+
+@env.task
+def triage_issue(issue_key: str) -> str:
+    """Comment on a newly created issue.
+
+    This is what `webhook_receiver.py` launches for every `jira:issue_created`.
+    """
+    jira = _client()
+    issue = jira.issue(issue_key)
+    jira.add_comment(issue, f"Flyte triaged this issue (status: {issue.fields.status.name}).")
+    return f"triaged {issue_key}"
+
+
+@env.task
+def summarize_open_bugs(project_key: str, limit: int = 20) -> str:
+    """Summarize open bugs via JQL."""
+    issues = _client().search_issues(
+        f'project = "{project_key}" AND issuetype = Bug AND statusCategory != Done', maxResults=limit
+    )
+    return "\n".join(f"- {i.key}: {i.fields.summary}" for i in issues) or "no open bugs"
+
+
+@env.task
+def start_work(issue_key: str, transition: str = "In Progress") -> str:
+    """Transition an issue by name, listing the valid ones when it does not apply.
+
+    Jira rejects transitions the issue's workflow does not offer, so resolve the
+    name against what is actually available rather than guessing an id.
+    """
+    jira = _client()
+    issue = jira.issue(issue_key)
+    available = {t["name"].lower(): t["id"] for t in jira.transitions(issue)}
+    target = available.get(transition.lower())
+    if target is None:
+        raise ValueError(f"{issue_key} cannot transition to {transition!r}; available: {sorted(available)}")
+    jira.transition_issue(issue, target)
+    return f"{issue_key} -> {transition}"
+
+
+if __name__ == "__main__":
+    flyte.init_from_config()
+    print(flyte.run(open_ticket, project_key="PROJ", summary="Flyte test issue").url)